Mycelium JavaScript SDK

TypeScript SDK for adding memory to autonomous web agents. The package is named @mycelium-dev/mycelium.

Mycelium primes a web-agent run with domain-specific observations, records what happened afterwards, and stores reusable hints in a local SQLite graph.

Install

npm install @mycelium-dev/mycelium

Adapter Convenience

import { run, stagehandAdapter } from "@mycelium-dev/mycelium"

const result = await run({
  url: "linkedin.com",
  goal: "open a public post and summarize it",
  adapter: stagehandAdapter({
    stagehandOptions: {
      env: "BROWSERBASE",
    },
  }),
})

console.log(result.data)
console.log("hints loaded:", result.primed.hintsLoaded)
console.log("hints saved:", result.recorded.hintsExtracted)

On later runs, Mycelium can load hints such as:

Search engine fallback worked. Try search results before deep site navigation.

Agent Adapters

Mycelium is a memory layer, not a replacement for every browser agent. Public adapters stay at the autonomous web-agent layer:

| Adapter | What it wraps | Install when needed | | --- | --- | --- | | tinyfishAdapter() | TinyFish | Built in | | stagehandAdapter() | Stagehand agent(...).execute(...) | npm install @browserbasehq/stagehand | | browserUseAdapter() | Browser Use Cloud client.run(...) | npm install browser-use-sdk |

Stagehand v1 is intentionally agent-execute-only. If you need lower-level act / extract workflows or raw browser-runtime control, use Mycelium's prime() / record() APIs around your own code instead of an adapter.

Examples:

• examples/stagehand-sdk.ts
• examples/browser-use-sdk.ts
• examples/basic-sdk.ts
• examples/advanced-sdk.ts

Two-Phase Integration

Use this when your app already has an agent loop.

import { buildGoal, prime, record } from "@mycelium-dev/mycelium"

const domain = "amazon.com"
const goal = "find the price of Kindle Paperwhite"

const primed = await prime(domain, goal)
const enrichedGoal = buildGoal(goal, primed)

const agentResult = await yourWebAgent.run({
  url: domain,
  goal: enrichedGoal,
})

await record({
  domain,
  goal,
  success: agentResult.success,
  steps: agentResult.steps,
  errors: agentResult.errors,
  raw: agentResult.raw,
  durationMs: agentResult.durationMs,
}, {
  hintsUsedIds: primed.hintsUsedIds,
})

Local Tools

npx myc inspect <domain>       # colored knowledge store view
npx myc stats [--all]          # success-rate trend
npx myc clear <domain>         # wipe one domain store
npx myc run x.com "summarize a public post" --stealth
npx myc run x.com "summarize a public post" --show-hints
npx myc-explorer               # local dashboard at http://127.0.0.1:3333

The myc binary is a developer/admin wrapper around the SDK. Application integrations should call the exported SDK functions directly.

Dashboard

npx myc-explorer
npx myc-explorer -- --port 3334 --store .mycelium/store.db

The dashboard is local-only by default and reads the same SQLite graph store as the SDK and CLI.

Environment

Loaded by load-env.ts from js/.env and the repo-root .env for local tools.

TINYFISH_API_KEY=          # required only when using tinyfishAdapter()
BROWSERBASE_API_KEY=      # required by Stagehand when env is BROWSERBASE
BROWSERBASE_PROJECT_ID=   # used by Stagehand examples/cookbook
BROWSER_USE_API_KEY=      # required only when using browserUseAdapter()
OPENAI_API_KEY=           # optional; LLM hint extraction and OpenAI embeddings
MYCELIUM_EMBED_PROVIDER=local  # optional; use openai or stub
MYCELIUM_LLM_EXTRACT=1    # optional; opt in to LLM hint extraction
MYCELIUM_STORE_PATH=./.mycelium

Local Development

From the repo root:

npm run install:js
npm run typecheck
npm test
npm run build

From inside js/ directly:

npm run typecheck
npm test
npm run build

Local Artifacts

.mycelium/      # SQLite graph store, relative to cwd or MYCELIUM_STORE_PATH
.bench/         # benchmark results and benchmark stores
*.db-shm
*.db-wal

Do not commit local SQLite files by default. Export or copy MYCELIUM_STORE_PATH intentionally if you want team-shared knowledge.

Project Layout

js/
├── index.ts              SDK public exports
├── adapters/
│   ├── types.ts          adapter contract
│   ├── tinyfish.ts       TinyFish autonomous agent adapter
│   ├── stagehand.ts      Stagehand autonomous agent adapter
│   └── browser-use.ts    Browser Use Cloud autonomous agent adapter
├── core/
│   ├── runner.ts         run() - prime -> adapter -> record
│   ├── prime.ts          prime(), buildGoal()
│   └── recorder.ts       record() - rule hints + optional LLM extraction
├── analyzer/
│   └── classifier.ts     deterministic web-automation symptoms -> hints
├── store/graph/          SQLite graph, traversal, embeddings, queries
├── tools/                optional myc inspection/debugging wrappers
├── explorer/             local graph/prompt/benchmark explorer
├── bench/                benchmark runner and task definitions
├── test/                 Node test runner tests
└── examples/             SDK and adapter examples

Publishing

npm run typecheck
npm test
npm run build
npm pack --dry-run
npm publish --access public