code-memory — Claude Code MCP server: what it does, how to install
Runs local semantic searches across your codebase and Git history without third-party API keys. It delivers exact code slices to avoid wasting tokens on entire files.
claude mcp add --env CODE_MEMORY_LOG_LEVEL=<CODE_MEMORY_LOG_LEVEL> --env EMBEDDING_MODEL=<EMBEDDING_MODEL> --transport stdio code-memory -- uvx code-memoryWhat code-memory does
The server constructs a local code index using SQLite vec and sentence-transformers. It parses structure and symbols via AST for languages such as Python, TypeScript, Java, Go, and Rust. Secondary formats, including SQL, Markdown, and configuration files, use whole-file indexing. Files listed in .gitignore are omitted automatically.
Queries route through dedicated tools: search_code pairs BM25 keyword matching with dense vectors, search_docs handles architectural questions, search_history inspects Git commit changes, and index_codebase generates embeddings. All processing stays offline with zero telemetry.
Running via uvx requires Python 3.13 or newer, though standalone executables are distributed on GitHub Releases. First startup pulls a ~600MB embedding model into the Hugging Face cache, requiring an active internet connection once. Loading separate processes across multiple folders consumes 1–2 GB RAM each, so running a shared SSE instance prevents duplicate model instances.
What it helps with
- retrieve code symbols and definitions with hybrid BM25 and vector search
- investigate regression causes through Git commit history
- cut LLM token usage by retrieving specific code segments instead of full files
- index codebases locally without exposing private code to external services
Example prompts for the agent
- Find where UserSession is defined using search_code.
- Inspect commit history with search_history to explain why auth logic changed.
- Run index_codebase to rebuild embeddings for the project.
How to install code-memory
Platform CLI
claude mcp add --env CODE_MEMORY_LOG_LEVEL=<CODE_MEMORY_LOG_LEVEL> --env EMBEDDING_MODEL=<EMBEDDING_MODEL> --transport stdio code-memory -- uvx code-memoryReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from code-memory <command>
Platform CLI
codex mcp add code-memory --env CODE_MEMORY_LOG_LEVEL=<CODE_MEMORY_LOG_LEVEL> --env EMBEDDING_MODEL=<EMBEDDING_MODEL> -- uvx code-memoryReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from code-memory <command>
Config file
{
"mcpServers": {
"code-memory": {
"command": "uvx",
"args": [
"code-memory"
],
"env": {
"CODE_MEMORY_LOG_LEVEL": "<CODE_MEMORY_LOG_LEVEL>",
"EMBEDDING_MODEL": "<EMBEDDING_MODEL>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from code-memory <command>
Config file
{
"servers": {
"code-memory": {
"type": "stdio",
"command": "uvx",
"args": [
"code-memory"
],
"env": {
"CODE_MEMORY_LOG_LEVEL": "<CODE_MEMORY_LOG_LEVEL>",
"EMBEDDING_MODEL": "<EMBEDDING_MODEL>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from code-memory <command>
Platform CLI
gemini mcp add -e CODE_MEMORY_LOG_LEVEL=<CODE_MEMORY_LOG_LEVEL> -e EMBEDDING_MODEL=<EMBEDDING_MODEL> code-memory uvx code-memoryReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from code-memory <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about code-memory
How do I install code-memory in Claude Code?
Run claude mcp add code-memory -- uvx code-memory in your terminal. To supply environment variables, run `claude mcp add --env CODE_MEMORY_LOG_LEVEL=<CODE_MEMORY_LOG_LEVEL> --env EMBEDDING_MODEL=<EMBEDDING_MODEL> --transport stdio code-memory -- uvx code-memory`.
Does code-memory need an external API key?
No API key is needed because embeddings run locally via sentence-transformers. The server operates offline and does not send telemetry or source files outside your device.
How do I reduce RAM usage across multiple workspaces?
Start a shared daemon with uvx code-memory --transport sse, which defaults to http://127.0.0.1:8765/sse. Point your MCP client configurations directly to that endpoint URL instead of launching isolated processes.
