MCP server with local vector search for your codebase. Smart indexing, semantic search, Git history — all offline.
CODE_MEMORY_LOG_LEVEL, EMBEDDING_MODEL
ตรวจสอบล่าสุด
2026-10-28
ดาว
49
เครื่องมือ
—
อัปไทม์
—
Zero telemetry — your code never leaves your machine
No API key required — runs entirely locally with sentence-transformers
1 min setup — just uvx code-memory and you're ready
Token saving by 50% — precise code retrieval instead of dumping entire files
Please help star code-memory if you like this project!
Why code-memory?
Finding the right context from a large codebase is expensive, inaccurate, and limited by context windows. Dumping files into prompts wastes tokens, and LLMs lose track of the actual task as context fills up.
Instead of manually hunting with grep/find or dumping raw file text, code-memory runs semantic searches against a locally indexed codebase. Inspired by claude-context, but designed from the ground up for large-scale local search.
Supported Languages
Full AST Support (structural parsing with symbol extraction): Python, JavaScript/TypeScript, Java, Go, Rust, C/C++, Ruby, Kotlin
Fallback Support (whole-file indexing): C#, Swift, Scala, Lua, Shell, Config (yaml/toml/json), Web (html/css), SQL, Markdown
Files matching .gitignore patterns are automatically skipped.
Architecture: Progressive Disclosure
Instead of a single monolithic search, code-memory routes queries through three purpose-built tools:
"Setup / Prepare" — index parsing & embedding generation
index_codebase
AST Parser + sentence-transformers
This forces the LLM to pick the right retrieval strategy before any data is fetched.
Installation
From PyPI (Recommended)
# Install with pip
pip install code-memory
# Or with uvx (for MCP hosts)
uvx code-memory
From Source
# Clone the repo
git clone https://github.com/kapillamba4/code-memory.git
cd code-memory
# Install dependencies
uv sync
# Run the MCP server (stdio transport)
uv run mcp run code_memory/server.py
Pre-built Binaries (Standalone)
Download standalone executables from GitHub Releases — no Python installation required.
Platform
Architecture
File
Linux
x86_64
code-memory-linux-x86_64
macOS
x86_64 (Intel)
code-memory-macos-x86_64
macOS
ARM64 (Apple Silicon)
code-memory-macos-arm64
Windows
x86_64
code-memory-windows-x86_64.exe
# Linux/macOS: Download and make executable
chmod +x code-memory-*
./code-memory-*
# Windows: Run directly
code-memory-windows-x86_64.exe
Note: The first run will download the embedding model (~600MB) to ~/.cache/huggingface/. Subsequent runs use the cached model.
# Install from PyPI
pip install code-memory
# Or run directly with uvx
uvx code-memory
Development
# Run with the MCP Inspector for interactive debugging
uv run mcp dev code_memory/server.py
# Run tests
uv run pytest tests/ -v
# Lint and format
uv run ruff check .
uv run ruff format .
# Build package
uv build
# Build standalone binary (requires pyinstaller)
pip install pyinstaller
pyinstaller --clean code-memory.spec
# Binary output: dist/code-memory
Configure Your MCP Host
You can use either uvx (requires Python) or the standalone binary (no dependencies).
Using uvx (Python required)
Gemini CLI / Gemini Code Assist
Add to your MCP settings (e.g. ~/.gemini/settings.json):
By default, each MCP host project launches its own code-memory process, which loads the embedding model (~1–2 GB) once per project. To avoid this, you can run a single shared instance over SSE (Server-Sent Events) and point all your MCP hosts at it.
Start the shared server
# Using uvx (recommended)
uvx code-memory --transport sse
# Custom port and host
uvx code-memory --transport sse --port 8765 --host 127.0.0.1
# Using standalone binary
./code-memory-linux-x86_64 --transport sse
The server listens on http://127.0.0.1:8765/sse by default.
Configure MCP hosts to use the shared server
Instead of launching a new process, point your MCP host at the running SSE endpoint.
Tip: Configure uvx code-memory --transport sse to start via a single-instance service manager (e.g. systemd user service, launchd agent, or another one-time login/startup mechanism) so the shared server starts automatically.
Security: The SSE endpoint is unauthenticated. Keep the default --host 127.0.0.1 so only local processes can connect; do not bind to 0.0.0.0 or a public interface unless you've put authentication in front of it.
Configuration
CLI Options
Option
Description
Default
--transport
Transport protocol: stdio or sse
stdio
--port
Port for SSE transport (only when --transport sse is used)
8765
--host
Host/bind address for SSE transport (only when --transport sse is used)
127.0.0.1
Environment Variables
Variable
Description
Default
CODE_MEMORY_LOG_LEVEL
Logging verbosity (DEBUG, INFO, WARNING, ERROR)
INFO
EMBEDDING_MODEL
HuggingFace model ID for embeddings
jinaai/jina-code-embeddings-0.5b
Example:
CODE_MEMORY_LOG_LEVEL=DEBUG uvx code-memory
Custom Embedding Model
You can use a different embedding model by setting the EMBEDDING_MODEL environment variable:
Note: Changing the embedding model will invalidate existing indexes. You'll need to re-run index_codebase after switching models.
Tools
index_codebase
Indexes or re-indexes source files and documentation in the given directory. Run this before using search_code or search_docs to ensure the database is up to date. Uses tree-sitter for language-agnostic structural extraction and generates dense vector embeddings using sentence-transformers (runs locally, in-process) for semantic search.
index_codebase(directory=".")
search_code
Perform semantic search and find structural code definitions, locate where functions/classes are defined, or map out dependency references (call graphs). Uses hybrid retrieval (BM25 + vector embeddings) to find exact matches and semantic similarities.
search_code(query="parse python files", search_type="definition")
search_code(query="how do we establish the database connection", search_type="references")
search_code(query="src/auth/", search_type="file_structure")
search_docs
Understand the codebase conceptually — how things work, architectural patterns, SOPs. Searches markdown documentation, READMEs, and docstrings extracted from code.
search_docs(query="how does the authentication flow work?")
search_docs(query="installation instructions", top_k=5)
search_history
Debug regressions and understand developer intent through Git history.
Make sure you're running search_history from within a git repository. The tool searches upward from the current directory to find .git.
Empty search results
Run index_codebase(directory=".") first to index your code and documentation. The index is stored locally in code_memory.db.
Slow indexing
Indexing generates embeddings using a local sentence-transformers model. The first run downloads the model (~600MB for jina-code-embeddings-0.5b). Subsequent runs are faster.
Embedding model errors
Ensure you have enough disk space and memory. The jina-code-embeddings-0.5b model requires ~1GB RAM when loaded.
Privacy & Security
Your code never leaves your machine. Unlike cloud-based code intelligence tools, code-memory runs entirely locally:
Zero telemetry — no usage data, analytics, or tracking
Zero external API calls — all processing happens in-process
Zero cloud dependencies — works without internet (after initial setup)
Your data stays local — indexes stored in local SQLite database
This makes code-memory ideal for:
Proprietary and confidential codebases
Security-conscious organizations
Air-gapped development environments
Privacy-focused developers
See COMPARISON.md for a detailed comparison with cloud-based alternatives.
Air-gapped & Offline Support
code-memory works in completely isolated environments:
Method 1: Pre-built Binary + Cached Model
On a connected machine, run code-memory once to cache the embedding model:
uvx code-memory
# Model downloads to ~/.cache/huggingface/
