codebase-memory — pi-coding-agent extension

A minimal port of codebase-memory-mcp as a pi-coding-agent extension.

Instead of a Go binary + tree-sitter + SQLite the extension runs entirely inside the Node.js process that already hosts pi:

| MCP component | Extension equivalent | |---|---| | Go binary + CGO | Node.js built-ins — zero native deps | | tree-sitter AST | Per-language regex, line-by-line with quick-filter | | Content-hash incremental index | MD5 per file, async stat batch, same skip-if-unchanged logic | | SQLite WAL database | .pi-codebase.bin next to your project (v8 serialized) | | 11 MCP tools via stdio | 5 pi tools + 1 slash-command |

Installation

# Install directly from GitHub:
pi install git:github.com/R-Dson/pi-codebase

# Or via npm:
pi install npm:pi-codebase-memory

Resources

• GitHub: R-Dson/pi-codebase
• npm: pi-codebase-memory

Tools

codebase_index

Full scan — walks the project, extracts symbols, writes .pi-codebase.bin.

codebase_index()
codebase_index({ root_path: "/my/app" })

Supported languages: TypeScript · JavaScript · Python · Go · Rust · Java · C# · PHP · C · C++ · Ruby · Swift · Kotlin · Shell · Perl · Dart · Lua · Scala · R

Ignored directories: node_modules, .git, dist, build, .next, __pycache__, target, .cache, vendor, .venv, venv, coverage, .nyc_output, out

codebase_update (incremental)

Re-parses only files whose MD5 content hash has changed since the last index run. Unchanged files are reused verbatim — identical to the MCP's incremental reindex strategy. Falls back to a full scan when no prior index exists.

codebase_update()                        # check everything since last run
codebase_update({ root_path: "/my/app" })

Output tells you how many files were +added, -removed, or ~changed.

codebase_search

Query the in-memory index — much faster than grep for structural questions. Equivalent to search_graph in the MCP.

codebase_search({ query: "Handler" })                     # name regex
codebase_search({ kind: "class" })                        # by kind
codebase_search({ query: "process", file_pattern: "api" })
codebase_search({ kind: "function", limit: 100 })

Supported kinds: function · method · class · interface · type · variable · struct · enum · trait · module · route · http_call · macro · protocol · extension · object

codebase_refs

Find every usage of a symbol across the project. Equivalent to trace_call_path(direction="inbound") in the MCP.

Search back-end priority:

1. ripgrep (rg) — if installed; fastest, cross-platform including native Windows
2. grep — Unix (Linux / macOS / WSL)
3. Pure Node.js — always available; slower on large trees but works everywhere

codebase_refs({ symbol: "processOrder" })
codebase_refs({ symbol: "UserService", file_pattern: "*.ts" })
codebase_refs({ symbol: "main", limit: 200 })

codebase_schema

High-level overview: file counts per language, symbol counts per kind, index age, root directory listing. Equivalent to get_graph_schema.

codebase_schema()

The output also reports the platform and which search back-ends are active (find, grep, rg), so you know exactly what the extension is using.

Command

/codebase   →  index status (root, file/symbol count, age, platform info)

What gets extracted

| Language | Kinds | |---|---| | TypeScript / TSX | function, arrow function, class, interface, type, enum, method, route, http_call | | JavaScript / JSX | function, arrow function, class, method, route, http_call | | Python | function, method, class, route | | Go | function, method, struct, interface, type | | Rust | function, struct, enum, trait, type, module | | Java | class, interface, enum, method, route | | C# | class, interface, enum, struct, function, route | | PHP | function, class, interface, route | | C | function, struct, enum, type, macro | | C++ | class, struct, enum, function, method, type, macro | | Ruby | class, module, method | | Swift | class, struct, protocol, enum, function, method, type, extension | | Kotlin | class, interface, function, method, type, enum, object | | Shell | function | | Perl | function, module, class | | Dart | class, function, method, enum, type, mixin | | Lua | function, module | | Scala | class, object, trait, function, method, type, enum | | R | function |

Signatures are captured up to 200 characters — enough to show full generic bounds in Rust (pub fn foo<T: Serialize + Clone>() and long Java return types.

Platform support

| Environment | Discovery | Symbol extraction | Reference search | |---|---|---|---| | Linux / macOS | find (fast) | Node.js regex | rg → grep | | WSL | find (fast) | Node.js regex | rg → grep | | Native Windows | Node.js walk | Node.js regex | rg → JS scan |

Install ripgrep (winget install ripgrep / brew install ripgrep / apt install ripgrep) to get the fastest reference search on all platforms.

Persistence & incremental workflow

# Day 1 — initial index
codebase_index()          →  writes .pi-codebase.bin

# Day 2, session start    →  index reloaded automatically from .pi-codebase.bin

# After editing a few files
codebase_update()         →  only changed files are re-parsed (hash diff)

# After a big refactor
codebase_index()          →  full re-scan (safe to run at any time)

Add .pi-codebase.bin to .gitignore if you prefer not to commit it:

echo ".pi-codebase.bin" >> .gitignore

Workflow examples

# Structural overview of an unfamiliar repo
You: "What does this codebase look like?"
  → codebase_index() then codebase_schema()

# Find all HTTP handlers
You: "Where are the route handlers?"
  → codebase_search({ query: "Handler|Route|Controller", kind: "function" })

# Call-site tracing
You: "What calls processPayment?"
  → codebase_refs({ symbol: "processPayment" })

# Dead-code hint
You: "Find all exported functions in the billing package"
  → codebase_search({ query: "^[A-Z]", kind: "function", file_pattern: "billing" })

# After editing
You: "I just moved some files around, update the index"
  → codebase_update()

Comparison with codebase-memory-mcp

| Feature | MCP | This extension | |---|---|---| | Requires Go + CGO | ✅ | ❌ — zero external deps | | tree-sitter AST accuracy | ✅ | ⚠️ regex (resilient to syntax errors) | | Content-hash incremental index | ✅ | ✅ MD5, async stat batch, same strategy | | Call-graph edges (multi-hop) | ✅ | ❌ (use codebase_refs for single-hop) | | Cross-service HTTP linking | ✅ | ❌ | | Cypher-like query language | ✅ | ❌ | | Dead-code detection | ✅ | ❌ | | Works inside pi without MCP | ❌ | ✅ | | Modular, no build step | ❌ | ✅ | | Persistent index | ✅ | ✅ | | Reference search | ✅ | ✅ (rg / grep / JS) | | Symbol search | ✅ | ✅ | | Schema / overview | ✅ | ✅ | | Windows support | ❌ (WSL only) | ✅ (native + WSL) | | Resilient to broken syntax | ⚠️ | ✅ regex keeps working |

File structure

codebase-memory/
├── index.ts       # Entry point — state, events, registration (~140 lines)
├── types.ts       # Interfaces, constants, language specs with quickFilter (~420 lines)
├── indexing.ts    # File discovery, symbol extraction, full/incremental index (~340 lines)
├── search.ts      # ripgrep / grep / JS reference search (~90 lines)
└── tools.ts       # Helpers + 5 tool registrations with renderers (~480 lines)

Performance

The indexer is optimized for speed:

• Concurrent I/O — semaphore-based worker pool keeps N files in flight simultaneously
• Async stat batch — incrementalIndex stats all files in parallel, not sequentially
• Per-language quick-filter — a single cheap regex skips ~85% of lines before running expensive pattern matches
• Native crypto — MD5 via Node's C++ crypto module (hardware-accelerated)
• v8 serialization — binary index persistence is 5–10× faster than JSON
• Auto-tuned thread pool — UV_THREADPOOL_SIZE set to max(cpus × 2, 32) at startup

Real-world result on the Linux kernel (64,770 files, 7M+ symbols): ~24 seconds on a modern machine.

License

MIT