CodeMap MCP

Local context engine for AI coding agents. CodeMap indexes repositories into a structured knowledge graph (stored in Turso / libSQL) and serves minimal, task-relevant context over MCP—without modifying source code.

Status

Agent-written summaries (MCP), Pyright/Python, go/packages, rust-analyzer Rust indexing, golden context tests, multi-workspace daemon, refresh_index, and hybrid semantic search_code.

pnpm install
pnpm build
pnpm codemap init .
pnpm codemap index .
pnpm codemap status
pnpm codemap context "add password reset"
pnpm codemap search "WorkspaceService"
pnpm codemap watch   # incremental re-index on save
pnpm codemap doctor --repair
codemap daemon start .          # multi-workspace; socket at ~/.codemap/daemon.sock
codemap workspace add ../other  # register another repo while daemon runs

See docs/MCP_SETUP.md for Cursor/Claude integration. With the daemon running, MCP tools auto-attach to keep the index warm. Architecture and roadmap: docs/.

Agent-written summaries

CodeMap does not summarize code. After reading a symbol, the agent can persist notes for later tasks:

set_symbol_summary({ name: "auth.resetPassword", summary: "Validates token, updates hash." })
get_symbol({ name: "auth.resetPassword" })  // includes summary + stale flag
get_task_context({ task: "password reset", include_summaries: true })

Details: MCP tools, task context, schema.

Database (Turso)

Default: local libSQL file at .codemap/index.db (file: URL).

Remote Turso:

export TURSO_DATABASE_URL="libsql://your-db.turso.io"
export TURSO_AUTH_TOKEN="..."
codemap index .

Embedded replica (local + sync):

export CODEMAP_DB_URL="file:.codemap/index.db"
export CODEMAP_DB_SYNC_URL="$TURSO_DATABASE_URL"
export CODEMAP_DB_SYNC_TOKEN="$TURSO_AUTH_TOKEN"

Quick links

Document	Contents
Architecture	System design, components, data flow
Database	SQLite schema, indexes, migrations
MCP Tools	Tool definitions and contracts
Language Adapters	Normalized schema, adapter protocol
Incremental Indexing	Watchers, dirty queues, partial re-index
Dependency Graph	Graph model, queries, persistence
Task Context	get_task_context retrieval algorithm
API	Internal programmatic API
CLI	Operator and CI commands
Roadmap	Phased delivery plan

Principles

• Local-first — index and store on disk; no cloud required
• Repository is source of truth — observe only; never edit project files
• Token-efficient — agents query the graph instead of re-reading trees
• Incremental — re-analyze changed files, not full repos
• Language-agnostic surface — native tooling per language, one normalized schema

Vision

CodeMap is not a coding agent. It is infrastructure that Claude Code, Codex CLI, OpenCode, Cursor, and other MCP clients use to understand large codebases cheaply and quickly.