Mycelium

Codebase memory for AI coding agents

The problem

AI coding agents read 30–40 files before touching anything. They have no memory of your codebase between sessions. Every task starts from zero.

What Mycelium does

One command scans your project, builds a semantic dependency graph, and starts an MCP HTTP server. Your agent calls /preflight?task=add stripe checkout and gets back the 4–6 files it actually needs — ranked by relevance, with dependency context included.

Mycelium also tracks work sessions. Declare what you're building, let your agent run, then call mycelium task done. Mycelium computes exactly what changed, which files were touched, and generates an AI summary of the session.

Install

npm install -g @kopikocappu/mycelium

mycelium key sk-ant-...        # Anthropic key (AI file descriptions)
mycelium key --openai sk-...   # OpenAI key (semantic search, recommended)

Quick start

cd your-project
mycelium init                  # scan, describe, start server
# → graph viewer at http://localhost:47821/ui

mycelium task "add stripe checkout"
# use your agent normally
mycelium task done             # records what changed

CLI

| Command | Description | |---------|-------------| | mycelium init [path] | Scan, describe all files, start server | | mycelium serve [path] | Start server without rescanning | | mycelium scan [path] | Rescan structure, skip AI descriptions | | mycelium task "description" | Start a work session | | mycelium task done | End session and compute diff | | mycelium task status | Show active task and elapsed time | | mycelium task abandon | Drop session without recording | | mycelium search <query> | Search files by natural language | | mycelium status | Graph stats and server state | | mycelium history | Show completed sessions | | mycelium key | Show or set API keys | | mycelium embed | Generate/refresh semantic embeddings | | mycelium debug | Diagnose missing import edges |

mycelium init flags

mycelium init --port 4000      # custom port (default: 47821)
mycelium init --force          # clear and rebuild from scratch
mycelium init --no-serve       # scan only, don't start server
mycelium init --no-watch       # don't watch for file changes

Session workflow

mycelium task "refactor auth module"
# → snapshot taken of all source files

# run your agent, make changes

mycelium task done
# ✓ Task complete  28m
# 2 files touched  +89 -34
#   ~ src/auth/session.ts    120→174 lines  +54
#   ~ src/middleware/jwt.ts   45→10 lines   -35

MCP endpoints

The server runs at http://localhost:47821 by default. .mcp.json is written automatically by mycelium init so Claude Code discovers it without any manual config.

GET /preflight?task=<description>

The core endpoint. Returns the most relevant files for a task, ranked by semantic similarity.

GET /preflight?task=add stripe checkout flow

{
  "task": "add stripe checkout flow",
  "mode": "semantic",
  "files": [
    { "nodeId": "src/payments/index.ts", "score": 0.91, "reason": "semantic" },
    { "nodeId": "src/api/checkout.ts",   "score": 0.87, "reason": "semantic" }
  ],
  "tokensSaved": 7200,
  "contextSummary": "## Mycelium Pre-flight: ..."
}

Agents should call this before touching any file. The contextSummary field is a pre-formatted markdown block ready to paste directly into context.

Other endpoints

| Endpoint | Description | |----------|-------------| | GET /graph | Full dependency graph (nodes + edges) | | GET /dependencies?file= | What a file imports and who imports it | | GET /search?q= | Semantic or keyword search across descriptions | | GET /node/<id> | Single node with dependency details | | GET /xref?file=&fn= | Import + call graph cross-reference | | GET /history | All sessions with per-file change breakdowns | | GET /task | Current session status | | POST /task/start | Start a session programmatically | | POST /task/complete | End session and compute diff | | GET /entry-points | Files at the top of the dependency tree | | GET /status | Server health and graph stats | | GET /config | Read ignore patterns | | POST /config | Add, remove, or reset ignore patterns | | GET /ui | Graph viewer | | GET /debug | Alias resolution diagnostics |

Graph viewer

Open at http://localhost:47821/ui while the server is running.

• Nodes — each dot is a file. Color = directory. Size = lines × connections.
• Edges — solid lines are imports, dashed lines are function calls.
• Flow dots — select a node and animated dots show dependency direction. Lime flows toward you (imports). Pink flows away (imported by).

Navigation

| Action | Result | |--------|--------| | Click node | Select, center, show connections | | Double-click node | Ripple animation through neighbors | |

How descriptions work

mycelium init sends each file to Claude Haiku for a one-sentence description, tags, and export summary. Descriptions are cached by file hash — unchanged files are never re-described. Re-running init is fast.

Descriptions power semantic search and preflight scoring. You can edit any description inline in the graph viewer if the generated one is weak.

Language support

Built-in parser covers TypeScript and JavaScript with full tsconfig.json path alias resolution.

If codebase-memory-mcp is installed, Mycelium uses it automatically for structural indexing across 150+ languages — Python, Go, Rust, Java, C++, and more — plus full call graph tracing between functions.

Troubleshooting

No import edges in the graph Run mycelium debug. Most common cause: import aliases (@/, ~/) not resolving to graph node IDs. Check that tsconfig.json is readable and paths are set correctly.

Descriptions are stale after a refactor Run mycelium scan --clear to rebuild everything from scratch.

Server not found from agent Run mycelium status in another terminal to confirm the server is up. Check that .mcp.json points to the right port (default 47821).

mycelium not found in terminal

npm config get prefix
# add the output path to your PATH

Roadmap

• [ ] Git integration — branch overlay, diff since last commit
• [ ] Session replay — animate history on the graph
• [ ] Auto-refresh — live graph updates without page reload
• [ ] Preflight accuracy metrics — track prediction vs actual edits
• [ ] LOC/connectivity heatmap
• [ ] Export PNG
• [ ] Mycelium Cloud — team sessions, shared history, web dashboard

Configuration files

| Path | Contents | |------|----------| | .mycelium/graph.json | Dependency graph | | .mycelium/sessions.json | Session history | | .mycelium/config.json | Ignore patterns | | .mycelium/embeddings.json | Semantic vectors | | ~/.mycelium/config.json | Global API keys (shared across projects) |