codebase-memory-mcp
by sameer2191
README.md
# RepoLens MCP
[](https://github.com/sameer2191/repolens-mcp/actions/workflows/ci.yml)
[](https://github.com/sameer2191/repolens-mcp/actions/workflows/codeql.yml)
[](https://scorecard.dev/viewer/?uri=github.com/sameer2191/repolens-mcp)
[](LICENSE)
[](package.json)
Local-first repository intelligence for AI coding agents. Index a repo into SQLite, expose architecture-aware MCP tools, and inspect code relationships in a browser dashboard.
RepoLens MCP is an original TypeScript implementation built around fast local verification, readable internals, and reviewable engineering evidence. It focuses on the workflows engineers actually need during AI-assisted development: finding code, tracing symbols, checking impact, and preserving architecture decisions.
## Core Capabilities
- **MCP-native workflow**: 38 tools grouped around indexing, code search, graph search, tracing, impact analysis, project inventory, fleet views, report generation, and ADR memory.
- **Code graph extraction**: captures symbols, routes, imports, package manifests, lockfiles, infrastructure files, protocol surfaces, event channels, typed relationships, conservative data flow, runtime traces, and HTTP route-call links.
- **Local verification loop**: repeatable full/incremental benchmarks, package-boundary checks, release gates, graph packages, dashboard/report artifacts, and security-summary commands keep validation inspectable.
- **Agent-ready setup**: `doctor` inspects the local Codex MCP configuration, `install-codex` can add a managed MCP block with dry-run and force safeguards, `uninstall-codex` removes only managed RepoLens config, `agent-hook` provides executable non-blocking broad-search reminders, and `agent-setup`/`install-agents` generate reviewable guidance plus opt-in hook/reminder files for Codex, Claude, Gemini, Zed, OpenCode, Antigravity, Aider, KiloCode, VS Code, OpenClaw, and Kiro, including a managed local Claude PreToolUse hook config.
- **Local-first SQLite memory**: all indexed data stays in `.repolens/memory.db`.
- **Project catalog and cross-repo graphing**: `list-projects`, `project-status`, `fleet-summary`, `fleet-graph`, and `delete-project` track indexed repositories, aggregate languages/routes/HTTP calls/dependencies, and produce a catalog-wide graph with shared dependencies, route overlaps, inferred consumer/provider service links, and shareable HTML/JSON artifacts through `fleet-graph --out`.
- **Incremental refreshes**: skip unchanged files, prune removed files, preserve the existing graph when a repo has not changed, optionally refresh on MCP startup with `REPOLENS_AUTO_INDEX`, and keep long-running MCP sessions fresh with git-aware `REPOLENS_AUTO_SYNC`.
- **Persistent local config**: `config set auto-index incremental` and `config set auto-sync true` store defaults for MCP startup indexing, live-session syncing, root, database path, max file size, max file count, labels, graph-package bootstrap, and diagnostics output without requiring shell env vars.
- **Watch mode**: keep an indexed graph fresh during active coding with polling-based incremental refreshes, optionally skipping unchanged git polls with `--git-aware`.
- **Operational diagnostics**: opt into JSONL lifecycle events for index, benchmark, watch, MCP startup auto-index, and auto-sync runs with `--diagnostics`, `REPOLENS_DIAGNOSTICS`, or persistent `diagnostics-path`.
- **Portable graph and report artifacts**: export self-contained interactive HTML graph explorers, architecture reports, and compressed `.rlgz` graph packages from the CLI; first index can bootstrap a missing database from `.repolens/graph.rlgz`.
- **Operational dashboard**: browse an interactive graph explorer with filtering, hover/click node inspection, legend, pause, and fit controls, plus structural filters, references, semantic/vector search, schema counts, relationship patterns, label property hints, fleet service links, dead-code candidates, review signals, and report links without a frontend build.
- **Graph communities**: detects functional modules from weighted relationships, not just folder names.
- **Code-aware search ranking**: uses SQLite FTS5 BM25 ranking with indexed camelCase and snake_case term expansion, so `create order` can find `createOrder` without scanning files.
- **Reference lookup**: finds exact indexed identifier references and labels definition lines for language-server-style navigation without requiring an external LSP process.
- **Type relationship graph**: adds `INHERITS`, `IMPLEMENTS`, and `USES_TYPE` edges from class/interface/protocol declarations and typed signatures for safer impact analysis.
- **Configuration links**: extracts config keys from repo-local config files and links config keys, dependency declarations, and referenced config files back to code with `CONFIGURES` edges.
- **Receiver-aware call graph**: resolves TypeScript/JavaScript calls such as `repo.save()` to the method on the inferred constructed class, avoiding ambiguous same-name method edges.
- **Local semantic and vector search**: adds dependency-free `SIMILAR_TO` and `SEMANTICALLY_RELATED` edges, concept search, and persisted local vector embeddings over names, paths, signatures, metadata, and symbol bodies.
- **Context packs for agents**: one query can return semantic matches, vector matches, graph matches, BM25 code hits, snippets, and nearby edges for focused development context.
- **Redacted secret scan**: review high-confidence token shapes, sensitive assignments, and environment references from indexed source/config lines without returning raw secret values.
- **Resolved import graph**: creates `IMPORTS_FILE` edges for relative imports, file-like includes/requires, dotted or backslash namespaces, workspace package names, source-root imports, and `tsconfig`/`jsconfig` path aliases.
- **Route-call edges**: stores literal HTTP requests as `http_call` nodes, connects callers with `CALLS_HTTP_ENDPOINT`, and links matching in-repo routes with `HTTP_CALLS`.
- **Runtime trace ingestion**: imports observed HTTP, event, or symbol traces as `OBSERVED_*` graph edges with counts and timestamps.
- **Channel/event edges**: detects EventEmitter, Socket.IO-style, DOM custom event, Python decorator/call, and Swift `NotificationCenter` channels with `EMITS` and `LISTENS_ON` edges.
- **Protocol surfaces**: extracts GraphQL operations/types, gRPC services/RPC routes from protobuf, OpenAPI routes, and common tRPC procedures/calls.
- **Manifest and lockfile dependency graph**: extracts declared package/dependency nodes from npm, Composer, Python, Go, Cargo, Maven, Gradle, Dart, Elixir, Ruby, and `requirements.txt` manifests, plus pinned `lockfile` and `locked_dependency` nodes from common package-manager locks.
- **Infrastructure graph nodes**: indexes Dockerfile stages/images, Kubernetes resources, container images, and Kustomize overlays with `DECLARES`, `CONFIGURES`, and `IMPORTS` edges.
- **Architecture recommendations**: turns structural hotspots, git-history churn, import-resolved dependency cycles, dead-code candidates, and review signals into concrete next steps.
- **Wide practical coverage**: TypeScript, JavaScript, Python, Go, Java, Rust, Swift, C/C++, C#, Kotlin, PHP, Ruby, Elixir, Dart, Terraform/HCL, QML, Apex, SQL, YAML, Markdown, JSON, and shell-oriented project files.
- **Project-specific language overrides**: map framework or template extensions in `.repolens.json`, such as treating `.astro` or `.view` files as TypeScript for indexing.
- **Validation evidence**: tests, CI, CodeQL, OpenSSF Scorecard, CycloneDX SBOM generation, GitHub build-provenance attestations, docs, local dashboard smoke checks, and a documented local big-repo validation run.
- **Architecture decisions built in**: persist ADR-style decisions next to the code graph.
- **No frontend build required**: the dashboard is served by the CLI.
## Security And Quality
- **Protected mainline**: `main` requires PR review, CODEOWNERS review, fresh branch checks, resolved conversations, linear history, `verify`, and CodeQL `Analyze`; force pushes and branch deletion are blocked.
- **GitHub security coverage**: CodeQL, OpenSSF Scorecard, Dependabot security updates, secret scanning with push protection, private vulnerability reporting, pinned workflow actions, least-privilege workflow tokens, and a release gate that blocks publishing when actionable CodeQL, Dependabot, or secret-scanning alerts are open or alert APIs are unavailable.
- **Property-based fuzzing**: `fast-check` fuzzes import resolver traversal boundaries, safe alias/source-root/workspace-package resolution, and MCP JSON-RPC tool-call validation in `tests/security-fixes.test.ts` and `tests/mcp-server.test.ts`.
- **Release integrity**: npm provenance, GitHub build-provenance attestations, CycloneDX SBOM generation, lockfile dependency graphing, clean builds, dry-run package validation, and a package contents gate that blocks local graph artifacts and stale compiled output from being published.
- **Agent-readable docs**: `llms.txt` and `docs/agent-guide.md` give coding agents a concise operating guide, data-boundary rules, and validation commands.
## Quick Start
```bash
npm install
npm run build
node --experimental-sqlite dist/src/cli.js index .
node --experimental-sqlite dist/src/cli.js architecture
node --experimental-sqlite dist/src/cli.js serve
```
Then open `http://127.0.0.1:9749`.
The dashboard includes an interactive graph explorer, code search, reference lookup, semantic/vector search, graph search, graph schema tables with relationship patterns and label property hints, fleet service links, hotspot and boundary summaries, git-history signals, dead-code candidates, and one-click Markdown/HTML architecture reports.
From a local clone, the installer runs the same build and Codex checks:
```bash
./install.sh --install-codex --dry-run
./install.sh --install-codex
./install.sh --install-agents --dry-run
./install.sh --install-agents --with-hooks --dry-run
./install.sh --uninstall-agents --dry-run
```
Windows PowerShell uses the same installer flow:
```powershell
.\install.ps1 -InstallCodex -DryRun
.\install.ps1 -InstallCodex
.\install.ps1 -InstallAgents -DryRun
.\install.ps1 -InstallAgents -WithHooks -DryRun
.\install.ps1 -UninstallAgents -DryRun
```
Project-specific language suffixes can be mapped in `.repolens.json` without changing RepoLens source:
```json
{
"languages": {
".astro": "typescript",
".view": "typescript",
"*.blade.php": "php"
}
}
```
## CLI
```bash
repolens-mcp index [repo] [--db path] [--max-file-bytes n] [--max-files n] [--incremental] [--label name] [--write-package [graph.rlgz]] [--diagnostics [path|true|off]]
repolens-mcp index [repo] [--bootstrap-package .repolens/graph.rlgz] [--no-bootstrap]
repolens-mcp version [--check] [--registry url]
repolens-mcp update-check [--registry url]
repolens-mcp benchmark [repo] [--db path] [--max-file-bytes n] [--max-files n] [--no-secret-scan] [--diagnostics [path|true|off]]
repolens-mcp list-projects [--limit n]
repolens-mcp project-status [root-or-db-or-label]
repolens-mcp delete-project <root-or-db-or-label> [--delete-db]
repolens-mcp fleet-summary [--limit n]
repolens-mcp fleet-graph [--limit n] [--max-nodes n] [--max-edges n] [--out fleet.html|fleet.json]
repolens-mcp config list|get|set|reset|path [key] [value]
repolens-mcp architecture [--db path]
repolens-mcp search <query> [--db path]
repolens-mcp scan-secrets [--db path] [--limit n] [--min-confidence low|medium|high] [--include-tests]
repolens-mcp symbols <query> [--kind function]
repolens-mcp snippet <symbol-or-path:line> [--context n]
repolens-mcp references <symbol> [--db path] [--limit n]
repolens-mcp trace <symbol> [--direction inbound|outbound|both] [--mode all|calls|data_flow|cross_service] [--parameter name]
repolens-mcp impact <path-or-symbol...>
repolens-mcp schema [--db path]
repolens-mcp communities [--db path] [--limit n] [--min-size n]
repolens-mcp watch [repo] [--db path] [--interval-ms n] [--git-aware] [--diagnostics [path|true|off]]
repolens-mcp search-graph [query] [--kind function] [--relationship CALLS] [--min-degree n]
repolens-mcp semantic "live session repository" [--limit n]
repolens-mcp vector "live session repository" [--limit n]
repolens-mcp context-pack "create order" [--limit n] [--context n]
repolens-mcp query-graph "MATCH (a)-[:CALLS]->(b) RETURN a.name,b.name LIMIT 5"
repolens-mcp dead-code [--db path]
repolens-mcp cycles [--db path] [--limit n]
repolens-mcp ingest-traces traces.json [--db path]
repolens-mcp changes [repo] [--db path]
repolens-mcp report [--db path] [--format markdown|html] [--graph-limit n] [--out report.html]
repolens-mcp export-graph --out graph.html [--db path]
repolens-mcp pack-graph --out graph.rlgz [--db path] [--label name]
repolens-mcp unpack-graph graph.rlgz [--db path] [--overwrite]
repolens-mcp doctor [--config ~/.codex/config.toml] [--name repolens]
repolens-mcp install-codex [--db .repolens/memory.db] [--dry-run] [--force]
repolens-mcp uninstall-codex [--dry-run]
repolens-mcp agent-setup [--target .] [--agents all|codex,claude,gemini,zed,opencode,antigravity,aider,kilocode,vscode,openclaw,kiro] [--db .repolens/memory.db] [--with-hooks]
repolens-mcp install-agents [--target .] [--agents all|codex,claude,gemini,zed,opencode,antigravity,aider,kilocode,vscode,openclaw,kiro] [--dry-run] [--with-hooks]
repolens-mcp uninstall-agents [--target .] [--agents all|codex,claude,gemini,zed,opencode,antigravity,aider,kilocode,vscode,openclaw,kiro] [--dry-run] [--with-hooks]
repolens-mcp agent-hook|hook-augment [--db .repolens/memory.db] [--name repolens] [--json|--claude] [--with-query]
repolens-mcp decision --title "Use SQLite" --body "Keep memory local."
repolens-mcp decision-update 1 --status accepted --tags sqlite,privacy
repolens-mcp decision-delete 1
repolens-mcp serve [--db path] [--port 9749]
repolens-mcp mcp
```
## MCP Tools
| Tool | Purpose |
| --- | --- |
| `index_repository` | Build or refresh the local SQLite memory, optionally bootstrapping from a `.rlgz` graph package when the database is missing. |
| `version_status` | Report installed package and Node versions, plus optional npm latest-version/update guidance. |
| `benchmark_repository` | Run full and no-op incremental indexing, graph totals, throughput, and optional redacted secret-scan summary for repeatable performance evidence. |
| `export_graph_package` | Create a compressed, checksummed `.rlgz` package from an indexed graph database. |
| `import_graph_package` | Import a compressed `.rlgz` package into a local graph database. |
| `manage_config` | Read or update persistent RepoLens defaults for startup auto-indexing and graph paths. |
| `list_projects` | List repositories indexed through RepoLens on this machine. |
| `index_status` | Return the latest indexed status for a root, database path, label, or project folder name. |
| `delete_project` | Remove a project from the local catalog, with optional safe `.repolens` DB cleanup. |
| `fleet_summary` | Aggregate indexed projects by language, package, dependency, route, HTTP call, route overlap, and inferred service link. |
| `cross_repo_graph` | Return a catalog-wide graph of indexed repositories, shared dependencies, overlapping routes, and inferred cross-repo HTTP caller/provider edges. |
| `agent_setup` | Render or write project-local RepoLens MCP setup guidance for supported coding agents. |
| `search_code` | Search indexed source lines with BM25 ranking and code-aware token expansion. |
| `scan_secrets` | Scan indexed source/config lines for redacted secret, token, credential, and sensitive environment patterns. |
| `search_symbols` | Search functions, classes, routes, resources, headings, and package nodes. |
| `get_code_snippet` | Return source lines around a symbol, qualified name, file path, or `path:line` target. |
| `find_references` | Find indexed definition and reference lines for a symbol or identifier. |
| `get_architecture` | Return language mix, hotspots, git-history churn, entrypoints, packages, and risk markers. |
| `trace_symbol` / `trace_path` | Trace inbound, outbound, or bidirectional paths around a symbol; modes include calls, data flow, cross-service HTTP/event edges, and unfiltered graph traversal. |
| `impact_analysis` | Find adjacent symbols for changed files or symbols. |
| `get_graph_schema` | Return node labels, edge types, relationship patterns, label properties, language coverage, and totals. |
| `find_communities` | Detect weighted graph communities with representative symbols, cohesion, and boundary counts. |
| `search_graph` | Search structurally by query, kind, regex, relationship, file scope, or degree. |
| `semantic_search` | Search symbols by local semantic token overlap across names, paths, signatures, and bodies. |
| `vector_search` | Search symbols with deterministic local vector embeddings over names, paths, signatures, metadata, and bodies. |
| `context_pack` | Return semantic matches, vector matches, graph matches, code hits, snippets, and nearby edges for one query. |
| `query_graph` | Run a read-only Cypher-like query over symbols and one-hop edges. |
| `find_dead_code` | Find non-exported functions and methods with no inbound call edges. |
| `find_dependency_cycles` | Find import-resolved dependency cycles between architecture clusters. |
| `ingest_traces` | Add observed runtime HTTP, event, or symbol edges as `OBSERVED_*` relationships. |
| `detect_changes` | Map uncommitted git changes to indexed graph impact with per-file blast radius, relationship counts, and risk reasons. |
| `architecture_report` | Generate a markdown or HTML architecture report with graph, hotspot, history, risk, and recommendation sections. |
| `remember_decision` | Persist an ADR-style architecture decision. |
| `list_decisions` | Retrieve saved decisions. |
| `update_decision` | Update an existing architecture decision without rewriting unspecified fields. |
| `delete_decision` | Delete an architecture decision by id. |
| `graph_snapshot` | Export compact graph data for dashboards or reviews. |
## Supported Extraction
The extractor is intentionally compact and extensible:
- TypeScript and JavaScript: classes, interfaces, types, functions, const functions, imports, resolved local import edges, Express-style routes, and Next.js App Router `app/api/**/route.ts` handlers.
- Receiver-aware TypeScript/JavaScript call edges: method symbols are attached to parent classes, and constructor-assigned receivers such as `const repo = new MemoryOrderRepository()` resolve `repo.save()` to the matching class method instead of every method named `save`.
- Conservative data-flow edges: maps meaningful call arguments to target parameters when the callee can be resolved without ambiguous duplicate names, and prunes stale `DATA_FLOWS` edges during incremental refreshes.
- Trace modes: `trace_path` can focus on call paths, value propagation through `DATA_FLOWS`, cross-service HTTP/event paths, or all nearby edges.
- HTTP call linking: literal `fetch`, Axios, and Node `http` calls become `http_call` nodes with `CALLS_HTTP_ENDPOINT`; matching route nodes also receive `HTTP_CALLS`.
- GraphQL, gRPC, and OpenAPI: `.graphql`, `.gql`, `.proto`, OpenAPI JSON, and OpenAPI YAML files produce protocol nodes; protobuf `rpc` methods become route nodes using `/Service/Method` paths, and OpenAPI `{id}` path params normalize to `:id`.
- tRPC: common procedure declarations and client calls become `trpc_procedure` and `trpc_call` nodes.
- Channel/event linking: EventEmitter/Socket.IO-style `emit`, `on`, `once`, `addListener`, `subscribe`, DOM `CustomEvent`, Python `@*.on`, and Swift `NotificationCenter` patterns become `channel` nodes with `EMITS` and `LISTENS_ON` edges.
- Swift: classes, structs, enums, protocols, actors, functions, and imports.
- Python: classes, functions, imports, route decorators.
- Go, Java, Rust: common functions, methods, types, classes, traits, structs, imports, and route decorators where applicable.
- C/C++, C#, Kotlin, PHP, Dart, Ruby, Elixir, QML, and Apex: practical symbol extraction for classes/interfaces/records/modules/functions/methods, imports/includes/uses/requires, plus C#/PHP/Kotlin/Apex route annotations and route helpers.
- SQL: created tables, views, indexes, functions, procedures.
- Terraform/HCL: `resource`, `data`, `module`, `variable`, `output`, and `provider` blocks, including module `source` import edges.
- YAML: multi-document Kubernetes resources from `kind` and `metadata.name`, container image links, and Kustomize `resources`, `bases`, and `components`.
- Dockerfile: build stages, base images, and `COPY --from` stage dependencies.
- Markdown: headings as knowledge nodes.
- Manifest files: `package.json`, `composer.json`, `pyproject.toml`, `requirements.txt`, `go.mod`, `Cargo.toml`, `pom.xml`, `build.gradle`, `pubspec.yaml`, `mix.exs`, and `*.gemspec` package/dependency nodes.
- Lockfiles: `package-lock.json`, `npm-shrinkwrap.json`, `pnpm-lock.yaml`, `yarn.lock`, `composer.lock`, `Cargo.lock`, `poetry.lock`, `go.sum`, and `Gemfile.lock` become `lockfile` and `locked_dependency` nodes connected by `LOCKS` edges.
### Repository Ignore Rules
Add `.repolensignore` at the repository root to exclude generated code, local scratch folders, vendored samples, or sensitive paths from indexing. Rules are path-relative globs with `!` negation, similar to `.gitignore`; RepoLens still applies its built-in skips for dependency folders, build outputs, binaries, and `.repolens` artifacts.
### Local Graph Artifact Cleanup
`.repolens/` is gitignored and can grow when you run benchmarks, imports, dashboard exports, or large-repo validation locally. Review old artifacts with:
```bash
find .repolens -maxdepth 1 -type f -size +50M -print
```
Use `repolens-mcp delete-project <root-or-db-or-label> --delete-db` for catalog-tracked databases, or manually remove reviewed scratch artifacts you no longer need. Do not publish `.repolens/` databases or graph packages without reviewing them for derived source metadata.
## Query Graph Subset
`query-graph` and `query_graph` are read-only. Supported patterns:
```cypher
MATCH (f:Function) WHERE f.name = 'main' RETURN f.name,f.filePath LIMIT 10
MATCH (a)-[r:CALLS]->(b) WHERE b.name CONTAINS 'order' RETURN a.name,b.name,r.type LIMIT 10
MATCH (a)<-[:CALLS]-(b) RETURN a.name,b.name LIMIT 10
MATCH (s) WHERE s.kind IN ['function', 'method'] RETURN s.name,s.kind LIMIT 10
MATCH (s) WHERE s.kind = 'route' OR s.kind = 'http_call' RETURN s.name,s.kind LIMIT 10
MATCH (a)-[r]->(b) WHERE r.weight >= 0.7 RETURN a.name,b.name,r.weight LIMIT 10
MATCH (f:Function) RETURN count(f) AS functions
MATCH (f:Function) RETURN DISTINCT f.name ORDER BY f.name SKIP 10 LIMIT 10
```
Supported `WHERE` operators are `=`, `<>`, `CONTAINS`, `STARTS WITH`, `ENDS WITH`, `IN`, `>`, `>=`, `<`, and `<=`, joined with `AND` or `OR`; `AND` binds tighter than `OR`.
Supported result clauses include `RETURN DISTINCT`, `count(...)`, `ORDER BY`, `SKIP`, and `LIMIT`.
## Validation
```bash
npm run verify
npm run test:skip-gate
npm run package:check
npm run installer:audit
npm run audit:prod
GITHUB_REPOSITORY=sameer2191/repolens-mcp GH_TOKEN="$(gh auth token)" npm run security:github
GITHUB_REPOSITORY=sameer2191/repolens-mcp GH_TOKEN="$(gh auth token)" npm run release:security-gate
node --experimental-sqlite dist/src/cli.js index /path/to/big/repo --db /tmp/memory.db
node --experimental-sqlite dist/src/cli.js benchmark /path/to/big/repo --db /tmp/benchmark.db
node --experimental-sqlite dist/src/cli.js list-projects
node --experimental-sqlite dist/src/cli.js project-status /path/to/big/repo
node --experimental-sqlite dist/src/cli.js fleet-summary
node --experimental-sqlite dist/src/cli.js fleet-graph --limit 20 --max-nodes 500 --max-edges 1000 --out /tmp/repolens-fleet.html
node --experimental-sqlite dist/src/cli.js index /path/to/big/repo --db /tmp/memory.db --incremental
node --experimental-sqlite dist/src/cli.js architecture --db /tmp/memory.db
node --experimental-sqlite dist/src/cli.js schema --db /tmp/memory.db
node --experimental-sqlite dist/src/cli.js communities --db /tmp/memory.db --limit 12
node --experimental-sqlite dist/src/cli.js snippet createOrder --db /tmp/memory.db
node --experimental-sqlite dist/src/cli.js references createOrder --db /tmp/memory.db
node --experimental-sqlite dist/src/cli.js semantic "order checkout flow" --db /tmp/memory.db
node --experimental-sqlite dist/src/cli.js vector "order checkout flow" --db /tmp/memory.db
node --experimental-sqlite dist/src/cli.js context-pack "order checkout flow" --db /tmp/memory.db
node --experimental-sqlite dist/src/cli.js cycles --db /tmp/memory.db
node --experimental-sqlite dist/src/cli.js query-graph "MATCH (f:Function) RETURN f.name,f.filePath LIMIT 5" --db /tmp/memory.db
node --experimental-sqlite dist/src/cli.js ingest-traces traces.json --db /tmp/memory.db
node --experimental-sqlite dist/src/cli.js report --db /tmp/memory.db --format html --out report.html
node --experimental-sqlite dist/src/cli.js export-graph --db /tmp/memory.db --out graph.html --limit 1000
node --experimental-sqlite dist/src/cli.js pack-graph --db /tmp/memory.db --out graph.rlgz --label validation
node --experimental-sqlite dist/src/cli.js unpack-graph graph.rlgz --db /tmp/imported-memory.db
node --experimental-sqlite dist/src/cli.js watch /path/to/big/repo --db /tmp/memory.db --interval-ms 2500 --git-aware
node --experimental-sqlite dist/src/cli.js config set auto-index incremental
node --experimental-sqlite dist/src/cli.js config set root /path/to/big/repo
node --experimental-sqlite dist/src/cli.js serve --db /tmp/memory.db --port 9749
node --experimental-sqlite dist/src/cli.js agent-setup --target /tmp/project --agents all
```
Security-summary commands need a token that can read GitHub security-alert endpoints; see `SECURITY.md` for local token requirements.
The repo includes `docs/research-notes.md` with source-research notes and design decisions, plus `docs/BENCHMARK.md` with sanitized validation evidence for the npm package.
## Team-Shared Graph Bootstrap
Create a reusable graph package:
```bash
repolens-mcp index . --db .repolens/memory.db --write-package
```
`--write-package` without a value writes `.repolens/graph.rlgz` after a successful index. Pass a path such as `--write-package artifacts/service.rlgz` to write somewhere else, or use `REPOLENS_WRITE_PACKAGE=.repolens/graph.rlgz` for session-wide automation. `.rlgz` packages are marked as binary by `.gitattributes`; review them before force-adding ignored `.repolens` artifacts to a repository.
On another machine or a fresh clone, the first index will import `.repolens/graph.rlgz` when the target database is missing, then run an incremental refresh for local changes:
```bash
repolens-mcp index . --db .repolens/memory.db
```
Use `--bootstrap-package path/to/graph.rlgz` for a custom artifact, `REPOLENS_BOOTSTRAP_PACKAGE=path/to/graph.rlgz` for MCP/session-wide configuration, or `--no-bootstrap` / `REPOLENS_BOOTSTRAP_PACKAGE=0` to force a fresh database.
## MCP Client Config
Codex users can inspect or install the MCP entry directly:
```bash
repolens-mcp doctor
repolens-mcp install-codex --db .repolens/memory.db --dry-run
repolens-mcp install-codex --db .repolens/memory.db
repolens-mcp uninstall-codex --dry-run
```
`install-codex` refuses to replace an existing unmanaged `mcp_servers.repolens` entry unless `--force` is passed. `uninstall-codex` removes only the RepoLens managed block and leaves unmanaged MCP entries untouched.
Optional startup indexing for MCP sessions:
```toml
[mcp_servers.repolens.env]
REPOLENS_DB = ".repolens/memory.db"
REPOLENS_AUTO_INDEX = "1" # incremental startup refresh
REPOLENS_AUTO_SYNC = "1" # keep a long-running MCP session fresh after git changes
REPOLENS_AUTO_SYNC_INTERVAL_MS = "2500"
REPOLENS_ROOT = "." # optional, defaults to process cwd
REPOLENS_MAX_FILE_BYTES = "750000" # optional
REPOLENS_MAX_FILES = "5000" # optional, fail closed on unexpected huge repos
REPOLENS_DIAGNOSTICS = "true" # optional, writes .repolens/diagnostics.jsonl
```
Set `REPOLENS_AUTO_INDEX=full` to force a full rebuild on startup. Leave it unset for the default manual-index behavior.
`REPOLENS_AUTO_SYNC=1` starts a background git-aware watcher after startup; unchanged HEAD/status polls are skipped, while committed or dirty worktree changes trigger incremental refreshes.
You can also persist those defaults without shell env vars:
```bash
node --experimental-sqlite dist/src/cli.js config set auto-index incremental
node --experimental-sqlite dist/src/cli.js config set auto-sync true
node --experimental-sqlite dist/src/cli.js config set auto-sync-interval-ms 2500
node --experimental-sqlite dist/src/cli.js config set root /path/to/repo
node --experimental-sqlite dist/src/cli.js config set db-path /path/to/repo/.repolens/memory.db
node --experimental-sqlite dist/src/cli.js config set max-files 5000
node --experimental-sqlite dist/src/cli.js config set diagnostics-path .repolens/diagnostics.jsonl
```
Project teams can generate agent guidance and config snippets for the broader agent set:
```bash
repolens-mcp agent-setup --target . --agents all
repolens-mcp install-agents --target . --agents codex,claude,gemini --dry-run
repolens-mcp install-agents --target . --agents codex,claude,gemini --with-hooks --dry-run
repolens-mcp install-agents --target . --agents codex,claude,gemini
repolens-mcp uninstall-agents --target . --agents codex,claude,gemini --with-hooks --dry-run
```
`install-agents` writes managed markdown blocks into project-local instruction files and a `docs/repolens-agent-setup.md` guide. For VS Code it also writes a project-local `.vscode/mcp.json` `servers.repolens` entry while preserving unrelated servers. Add `--with-hooks` to generate opt-in, non-blocking hook/reminder files plus `docs/repolens-agent-hooks.md`; for Claude Code it also merges a managed `.claude/settings.local.json` PreToolUse hook entry while preserving unrelated hooks and settings. These files tell agents when to call RepoLens before broad searches or risky edits and include an executable `hook-augment --claude` command for agents that pass hook payload JSON through stdin. `agent-hook`/`hook-augment` recognizes PreToolUse-style Grep, Glob, and broad shell search payloads, emits either text, JSON, or Claude-compatible `hookSpecificOutput.additionalContext`, exits successfully, and does not intercept Read/Edit/Write tools. The hook does not query or mutate the local graph by default; add `--with-query` only when you want it to open the RepoLens database and append symbol metadata matches. `uninstall-agents --with-hooks` removes those managed reminder files and the managed Claude hook entry alongside managed RepoLens markdown blocks and managed VS Code config entries while preserving hand-written content. The MCP `agent_setup` tool is dry-run by default; write mode is limited to the server working directory, and executable hook writes require `REPOLENS_ALLOW_MCP_HOOK_WRITES=1`, so interactive CLI installers are the recommended hook setup path. The guide includes MCP config snippets for Codex, Claude, Gemini, Zed, OpenCode, Antigravity, Aider, KiloCode, VS Code, OpenClaw, and Kiro.
```json
{
"mcpServers": {
"repolens-mcp": {
"command": "npx",
"args": ["-y", "@sameermir/repolens-mcp", "mcp"],
"env": {
"REPOLENS_DB": ".repolens/memory.db"
}
}
}
}
```
## Architecture
```mermaid
flowchart LR
Repo["Repository files"] --> Walker["Ignore-aware walker"]
Walker --> Extractor["Language extractors"]
Extractor --> Store["SQLite memory"]
Store --> MCP["MCP tools"]
Store --> CLI["CLI"]
Store --> Dashboard["Local dashboard"]
MCP --> Agent["AI coding agent"]
```
## Roadmap
- Optional parser-backed adapters for deeper language-specific call/use precision where regex extractors are not enough.
- Host-aware service-link inference from config, environment variables, and trace data.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues