{
  "markdown": "# code-memory\n\n<!-- mcp-name: io.github.kapillamba4/code-memory -->\n\n<img src=\"assets/logo.png\" alt=\"code-memory logo\" width=\"100%\">\n\n[![Zero Telemetry](https://img.shields.io/badge/Zero-Telemetry-brightgreen)](#privacy--security)\n[![No API Key](https://img.shields.io/badge/No-API_Key-blue)](#why-code-memory)\n[![Offline First](https://img.shields.io/badge/Offline-First-orange)](#air-gapped--offline-support)\n\nA deterministic, high-precision **code intelligence layer** exposed as a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server.\n\n- **Zero telemetry** — your code never leaves your machine\n- **No API key required** — runs entirely locally with sentence-transformers\n- **1 min setup** — just `uvx code-memory` and you're ready\n- **Token saving by 50%** — precise code retrieval instead of dumping entire files\n\n**Please help star code-memory if you like this project!**\n\n## Why code-memory?\n\nFinding 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.\n\nInstead 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](https://github.com/redmonkez12/claude-context), but designed from the ground up for large-scale local search.\n\n## Supported Languages\n\n**Full AST Support** (structural parsing with symbol extraction): Python, JavaScript/TypeScript, Java, Go, Rust, C/C++, Ruby, Kotlin\n\n**Fallback Support** (whole-file indexing): C#, Swift, Scala, Lua, Shell, Config (yaml/toml/json), Web (html/css), SQL, Markdown\n\n> Files matching `.gitignore` patterns are automatically skipped.\n\n## Architecture: Progressive Disclosure\n\nInstead of a single monolithic search, `code-memory` routes queries through **three purpose-built tools**:\n\n| Question Type | Tool | Data Source |\n|---|---|---|\n| **\"Where / What / How?\"** — find definitions, references, structure, semantic search | `search_code` | BM25 + Dense Vector (SQLite vec) |\n| **\"Architecture / Patterns\"** — understand architecture, explain workflows | `search_docs` | Semantic / Fuzzy |\n| **\"Who / Why?\"** — debug regressions, understand intent | `search_history` | Git + BM25 + Dense Vector (SQLite vec) |\n| **\"Setup / Prepare\"** — index parsing & embedding generation | `index_codebase` | AST Parser + `sentence-transformers` |\n\nThis forces the LLM to pick the *right retrieval strategy* before any data is fetched.\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\n# Install with pip\npip install code-memory\n\n# Or with uvx (for MCP hosts)\nuvx code-memory\n```\n\n### From Source\n\n```bash\n# Clone the repo\ngit clone https://github.com/kapillamba4/code-memory.git\ncd code-memory\n\n# Install dependencies\nuv sync\n\n# Run the MCP server (stdio transport)\nuv run mcp run code_memory/server.py\n```\n\n### Pre-built Binaries (Standalone)\n\nDownload standalone executables from [GitHub Releases](https://github.com/kapillamba4/code-memory/releases) — no Python installation required.\n\n| Platform | Architecture | File |\n|----------|-------------|------|\n| Linux | x86_64 | `code-memory-linux-x86_64` |\n| macOS | x86_64 (Intel) | `code-memory-macos-x86_64` |\n| macOS | ARM64 (Apple Silicon) | `code-memory-macos-arm64` |\n| Windows | x86_64 | `code-memory-windows-x86_64.exe` |\n\n```bash\n# Linux/macOS: Download and make executable\nchmod +x code-memory-*\n./code-memory-*\n\n# Windows: Run directly\ncode-memory-windows-x86_64.exe\n```\n\n**Note:** The first run will download the embedding model (~600MB) to `~/.cache/huggingface/`. Subsequent runs use the cached model.\n\n## Quickstart\n\n### Prerequisites\n\n- Python ≥ 3.13\n- [`uv`](https://docs.astral.sh/uv/) package manager (recommended) or pip\n\nInstall uv if you don't have it:\n\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\n### Install & Run\n\n```bash\n# Install from PyPI\npip install code-memory\n\n# Or run directly with uvx\nuvx code-memory\n```\n\n### Development\n\n```bash\n# Run with the MCP Inspector for interactive debugging\nuv run mcp dev code_memory/server.py\n\n# Run tests\nuv run pytest tests/ -v\n\n# Lint and format\nuv run ruff check .\nuv run ruff format .\n\n# Build package\nuv build\n\n# Build standalone binary (requires pyinstaller)\npip install pyinstaller\npyinstaller --clean code-memory.spec\n# Binary output: dist/code-memory\n```\n\n## Configure Your MCP Host\n\nYou can use either `uvx` (requires Python) or the standalone binary (no dependencies).\n\n### Using uvx (Python required)\n\n### Gemini CLI / Gemini Code Assist\n\nAdd to your MCP settings (e.g. `~/.gemini/settings.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"code-memory\": {\n      \"command\": \"uvx\",\n      \"args\": [\"code-memory\"]\n    }\n  }\n}\n```\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"code-memory\": {\n      \"command\": \"uvx\",\n      \"args\": [\"code-memory\"]\n    }\n  }\n}\n```\n\n### Claude Code (CLI)\n\nAdd to `.mcp.json` in your project root or `~/.mcp.json` for global access:\n\n```json\n{\n  \"mcpServers\": {\n    \"code-memory\": {\n      \"command\": \"uvx\",\n      \"args\": [\"code-memory\"]\n    }\n  }\n}\n```\n\n### VS Code (Copilot / Continue)\n\nAdd to `.vscode/mcp.json` in your workspace:\n\n```json\n{\n  \"servers\": {\n    \"code-memory\": {\n      \"command\": \"uvx\",\n      \"args\": [\"code-memory\"]\n    }\n  }\n}\n```\n\n### Using Standalone Binary (No Python required)\n\nReplace the path with the location of your downloaded binary:\n\n```json\n{\n  \"mcpServers\": {\n    \"code-memory\": {\n      \"command\": \"/path/to/code-memory-linux-x86_64\"\n    }\n  }\n}\n```\n\nFor Windows:\n```json\n{\n  \"mcpServers\": {\n    \"code-memory\": {\n      \"command\": \"C:\\\\path\\\\to\\\\code-memory-windows-x86_64.exe\"\n    }\n  }\n}\n```\n\n## Shared SSE Server (Reduce Memory Usage)\n\nBy 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.\n\n### Start the shared server\n\n```bash\n# Using uvx (recommended)\nuvx code-memory --transport sse\n\n# Custom port and host\nuvx code-memory --transport sse --port 8765 --host 127.0.0.1\n\n# Using standalone binary\n./code-memory-linux-x86_64 --transport sse\n```\n\nThe server listens on `http://127.0.0.1:8765/sse` by default.\n\n### Configure MCP hosts to use the shared server\n\nInstead of launching a new process, point your MCP host at the running SSE endpoint.\n\n#### Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"code-memory\": {\n      \"url\": \"http://127.0.0.1:8765/sse\"\n    }\n  }\n}\n```\n\n#### VS Code (Copilot / Continue)\n\n```json\n{\n  \"servers\": {\n    \"code-memory\": {\n      \"url\": \"http://127.0.0.1:8765/sse\"\n    }\n  }\n}\n```\n\n#### Claude Code (CLI) — `.mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"code-memory\": {\n      \"url\": \"http://127.0.0.1:8765/sse\"\n    }\n  }\n}\n```\n\n> **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.\n\n> **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.\n\n## Configuration\n\n### CLI Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--transport` | Transport protocol: `stdio` or `sse` | `stdio` |\n| `--port` | Port for SSE transport (only when `--transport sse` is used) | `8765` |\n| `--host` | Host/bind address for SSE transport (only when `--transport sse` is used) | `127.0.0.1` |\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `CODE_MEMORY_LOG_LEVEL` | Logging verbosity (DEBUG, INFO, WARNING, ERROR) | INFO |\n| `EMBEDDING_MODEL` | HuggingFace model ID for embeddings | `jinaai/jina-code-embeddings-0.5b` |\n\nExample:\n```bash\nCODE_MEMORY_LOG_LEVEL=DEBUG uvx code-memory\n```\n\n### Custom Embedding Model\n\nYou can use a different embedding model by setting the `EMBEDDING_MODEL` environment variable:\n\n```bash\nEMBEDDING_MODEL=\"BAAI/bge-small-en-v1.5\" uvx code-memory\n```\n\nFor MCP hosts, add the environment variable to your configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"code-memory\": {\n      \"command\": \"uvx\",\n      \"args\": [\"code-memory\"],\n      \"env\": {\n        \"EMBEDDING_MODEL\": \"BAAI/bge-small-en-v1.5\"\n      }\n    }\n  }\n}\n```\n\n> **Note:** Changing the embedding model will invalidate existing indexes. You'll need to re-run `index_codebase` after switching models.\n\n## Tools\n\n### `index_codebase`\n\nIndexes 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.\n\n```\nindex_codebase(directory=\".\")\n```\n\n### `search_code`\n\nPerform 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.\n\n```\nsearch_code(query=\"parse python files\", search_type=\"definition\")\nsearch_code(query=\"how do we establish the database connection\", search_type=\"references\")\nsearch_code(query=\"src/auth/\", search_type=\"file_structure\")\n```\n\n### `search_docs`\n\nUnderstand the codebase conceptually — how things work, architectural patterns, SOPs. Searches markdown documentation, READMEs, and docstrings extracted from code.\n\n```\nsearch_docs(query=\"how does the authentication flow work?\")\nsearch_docs(query=\"installation instructions\", top_k=5)\n```\n\n### `search_history`\n\nDebug regressions and understand developer intent through Git history.\n\n```\nsearch_history(query=\"fix login timeout\", search_type=\"commits\")\nsearch_history(query=\"src/auth/login.py\", search_type=\"file_history\", target_file=\"src/auth/login.py\")\nsearch_history(query=\"server.py\", search_type=\"blame\", target_file=\"server.py\", line_start=1, line_end=20)\n```\n\n## Project Structure\n\n```\ncode-memory/\n├── code_memory/           # Package source\n│   ├── server.py          # MCP server entry point (FastMCP)\n│   ├── db.py              # SQLite database layer with sqlite-vec\n│   ├── parser.py          # Tree-sitter-based code parser\n│   ├── doc_parser.py      # Markdown documentation parser\n│   ├── queries.py         # Hybrid retrieval query layer\n│   ├── git_search.py      # Git history search module\n│   ├── errors.py          # Custom exception hierarchy\n│   ├── validation.py      # Input validation functions\n│   ├── logging_config.py  # Structured logging configuration\n│   └── api_types.py       # MCP response TypedDicts\n├── tests/                 # Test suite\n├── pyproject.toml         # Project metadata & dependencies\n└── prompts/               # Milestone prompt engineering files\n```\n\n## Troubleshooting\n\n### \"Git repository not found\" error\n\nMake sure you're running `search_history` from within a git repository. The tool searches upward from the current directory to find `.git`.\n\n### Empty search results\n\nRun `index_codebase(directory=\".\")` first to index your code and documentation. The index is stored locally in `code_memory.db`.\n\n### Slow indexing\n\nIndexing 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.\n\n### Embedding model errors\n\nEnsure you have enough disk space and memory. The `jina-code-embeddings-0.5b` model requires ~1GB RAM when loaded.\n\n## Privacy & Security\n\n**Your code never leaves your machine.** Unlike cloud-based code intelligence tools, code-memory runs entirely locally:\n\n- **Zero telemetry** — no usage data, analytics, or tracking\n- **Zero external API calls** — all processing happens in-process\n- **Zero cloud dependencies** — works without internet (after initial setup)\n- **Your data stays local** — indexes stored in local SQLite database\n\nThis makes code-memory ideal for:\n- Proprietary and confidential codebases\n- Security-conscious organizations\n- Air-gapped development environments\n- Privacy-focused developers\n\nSee [COMPARISON.md](COMPARISON.md) for a detailed comparison with cloud-based alternatives.\n\n## Air-gapped & Offline Support\n\ncode-memory works in completely isolated environments:\n\n### Method 1: Pre-built Binary + Cached Model\n\n1. On a connected machine, run code-memory once to cache the embedding model:\n   ```bash\n   uvx code-memory\n   # Model downloads to ~/.cache/huggingface/\n   ```\n\n2. Transfer to air-gapped machine:\n   - Standalone binary from [GitHub Releases](https://github.com/kapillamba4/code-memory/releases)\n   - Model cache directory (`~/.cache/huggingface/hub/models--*`)\n\n3. Run on air-gapped machine — no network required.\n\n### Method 2: Offline pip Install\n\n1. Download the wheel from PyPI on a connected machine\n2. Transfer and install: `pip install code-memory-*.whl`\n3. Pre-cache the model as above\n4. Run offline\n\n## Roadmap\n\n- [x] **Milestone 1** — Project scaffolding & MCP protocol wiring\n- [x] **Milestone 2** — Implement `search_code` with AST parsing + SQLite + `sqlite-vec`\n- [x] **Milestone 3** — Implement `search_history` with Git integration\n- [x] **Milestone 4** — Implement `search_docs` with semantic search\n- [x] **Milestone 5** — Production hardening & packaging\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history.\n\n## License\n\nMIT\n",
  "bytes": 13930,
  "sha": "bff130c17390eb6c4b921fe493654e4fcd0bcdccc25ff175307705b5e93c79b3",
  "repo_slug": "kapillamba4/code-memory",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_kapillamba4_code_memory_ab06dc0e/readme"
}