code-memory#

code-memory is a local MCP server for code intelligence. It indexes a project into a local SQLite database, extracts AST symbols where supported, embeds code/docs with sentence-transformers, and exposes MCP tools for code search, docs search, Git history, index stats, and dead-code candidates.

Upstream: https://github.com/kapillamba4/code-memory Reviewed version: v1.0.32 / commit 563788a2a7d015699f20251d404aeb293346f40c.

When To Use#

Use this skill anytime coding a GitHub project or any local Git repository, especially when:

• Starting work in an unfamiliar or large codebase.
• Looking for definitions, references, file structure, or concept-related code.
• Understanding architecture, README/doc conventions, or docstrings.
• Debugging regressions where Git history, file history, blame, or commit details matter.
• Looking for candidate dead code before a cleanup.

Do not use it as the only evidence for risky edits. It is retrieval assistance, not a replacement for rg, direct file reads, tests, typechecks, or human review.

Install#

Prerequisites:

• Python >=3.13.
• uv/ uvx recommended. Install uv with the official Astral installer or package manager.
• First run downloads the default embedding model, currently jinaai/jina-code-embeddings-0.5b, to the HuggingFace cache. Expect roughly 600 MB download and about 1 GB+ RAM when loaded.
• On GPU machines, it may auto-use CUDA or MPS. Use CPU mode when GPU memory is tight.

Recommended MCP command:

bash

uvx code-memory

Pip install:

bash

python3.13 -m pip install code-memory
code-memory

From source:

bash

git clone https://github.com/kapillamba4/code-memory.git
cd code-memory
uv sync
uv run mcp run code_memory/server.py

Standalone binaries are published on GitHub Releases. Treat binaries as a supply-chain trust decision: prefer package/source installs unless there is a specific reason to use a binary.

MCP Configuration#

Use stdio for normal per-project MCP hosting:

json

{
  "mcpServers": {
    "code-memory": {
      "command": "uvx",
      "args": ["code-memory"]
    }
  }
}

For a shared server, run:

bash

uvx code-memory --transport sse --host 127.0.0.1 --port 8765

Then configure the MCP host to use:

json

{
  "mcpServers": {
    "code-memory": {
      "url": "http://127.0.0.1:8765/sse"
    }
  }
}

Do not bind SSE to 0.0.0.0 or a public interface without an authenticated reverse proxy. The SSE endpoint is unauthenticated.

Use Workflow#

Before searching a project:

1. Check status if available: check_index_status(directory="/path/to/repo").
2. Index first: index_codebase(directory="/path/to/repo").
3. Re-index after meaningful file changes or if results look stale.
4. Use direct reads/tests after retrieval before making edits.

Core tools:

• index_codebase(directory, cpu=false): builds/refreshes the local index. Use cpu=true if CUDA/MPS memory is constrained.
• check_index_status(directory): quick readiness check.
• get_index_stats(directory): index size, coverage, model, and database health.
• search_code(query, search_type, directory): semantic/structural code lookup. search_type is topic_discovery, definition, references, or file_structure.
• search_docs(query, directory, top_k=10): README/docs/docstring search.
• search_history(query, directory, search_type, target_file, line_start, line_end): Git history, file history, blame, and commit details.
• find_dead_code(directory, min_confidence=0.5, kinds=null, include_tests=false, top_k=50): candidate unused functions/classes/methods. Verify manually before deleting anything.

Useful examples:

text

index_codebase(directory="/home/jim/project")
search_code(query="authentication middleware", search_type="topic_discovery", directory="/home/jim/project")
search_code(query="UserService", search_type="definition", directory="/home/jim/project")
search_code(query="send_email", search_type="references", directory="/home/jim/project")
search_docs(query="deployment architecture", directory="/home/jim/project", top_k=5)
search_history(query="timeout", search_type="commits", directory="/home/jim/project")
search_history(query="", search_type="file_history", target_file="src/auth.py", directory="/home/jim/project")
find_dead_code(directory="/home/jim/project", min_confidence=0.75)

Files And State#

• Creates code_memory.db in the indexed project root.
• SQLite WAL mode may also create code_memory.db-wal and code_memory.db-shm.
• The index stores file paths, source excerpts/symbol text, doc chunks, embeddings, and Git-derived search data.
• .gitignore is respected, including nested .gitignore files. Built-in skipped dirs include .git, .venv, venv, node_modules, caches, dist, build, target, bin, and obj.
• If a repo contains secrets that are not ignored, they can be indexed. Add sensitive files to .gitignore or exclude/remove the database after accidental indexing.
• Add code_memory.db* to .gitignore unless there is a deliberate reason to version the index. Usually there is not.

Python And Dependencies#

Current upstream requires Python >=3.13 and declares these runtime dependencies:

• mcp[cli]
• sentence-transformers
• sqlite-vec
• tree-sitter
• language grammars: tree-sitter-python, tree-sitter-javascript, tree-sitter-typescript, tree-sitter-java, tree-sitter-kotlin, tree-sitter-go, tree-sitter-rust, tree-sitter-c, tree-sitter-cpp, tree-sitter-ruby
• gitpython
• pathspec
• markdown-it-py
• einops
• xxhash

Development dependencies include pytest, pytest-asyncio, pytest-cov, ruff, and mypy.

Supported AST parsing: Python, JavaScript/TypeScript, Java, Go, Rust, C/C++, Ruby, Kotlin.

Fallback whole-file indexing: C#, Swift, Scala, Lua, shell, YAML/TOML/JSON, HTML/CSS, SQL, Markdown, text, and similar source-like files.

Environment variables:

• CODE_MEMORY_LOG_LEVEL: DEBUG, INFO, WARNING, or ERROR.
• EMBEDDING_MODEL: HuggingFace model id. Changing it invalidates/rebuilds indexes.
• CODE_MEMORY_DEVICE: auto, cuda, mps, or cpu.
• CODE_MEMORY_BATCH_SIZE: embedding batch size, default 64.
• CODE_MEMORY_MAX_WORKERS: parser thread pool size, default 4.
• CODE_MEMORY_RERANK: true/ 1/ yes enables cross-encoder reranking.
• RERANK_MODEL: HuggingFace model id for reranking.

Security Review#

Observed positives:

• No obvious telemetry, analytics, HTTP client, or external API reporting path in reviewed source.
• Code/docs/Git search runs locally after package/model installation.
• Paths are resolved and directory existence is validated for indexing.
• SQLite queries appear parameterized where user-provided values matter.
• .gitignore and common dependency/build/cache folders are skipped during indexing.

Important risks and controls:

• sentence-transformers loads the embedding model with trust_remote_code=True. The default HuggingFace model therefore becomes executable code. For sensitive environments, pre-vet/pin the model or use a trusted local/bundled model via EMBEDDING_MODEL.
• First install/run fetches packages and model artifacts from package/model registries. For high-trust work, pin versions/hashes or pre-cache artifacts from a vetted machine.
• SSE transport is unauthenticated. Keep --host 127.0.0.1; never expose it directly to a LAN or internet interface.
• The MCP server can index any directory path the host allows it to access. Do not run it with broader filesystem access than needed.
• code_memory.db* contains searchable code snippets and embeddings. Treat it as sensitive project data; do not commit, sync, or share casually.
• Secrets accidentally committed or merely present in non-ignored files can be indexed. Check .gitignore before indexing private repos.
• find_dead_code is heuristic. Reflection, decorators, framework registration, dynamic dispatch, exports, and tests can make live code appear unused.
• Standalone binaries should be verified before use. Prefer source/PyPI installs if provenance matters.

Troubleshooting#

• Empty code/docs results: run index_codebase(directory) first, then search again.
• Git history errors: make sure directory is inside a Git repository.
• CUDA out-of-memory: call index_codebase(..., cpu=true) or set CODE_MEMORY_DEVICE=cpu.
• Slow first run: the model download and warmup are normal. Subsequent runs reuse the HuggingFace cache.
• Stale results after edits: re-run index_codebase; indexing is incremental.
• Model changed: re-index. Existing index metadata is invalidated when embedding model/dimension changes.