code-memory

code-memory

以 Model Context Protocol (MCP) 服务形式提供的确定性、高精度代码智能层。

• 零遥测——你的代码绝不会离开本机
• 无需 API 密钥——完全在本地运行，使用 sentence-transformers
• 1 分钟完成设置——只需运行 uvx code-memory，即可开始使用
• 节省 50% Token——精准检索代码，而非倾倒整个文件

如果你喜欢这个项目，请帮忙给 code-memory 点个 Star！

为什么选择 code-memory？

从大型代码库中找到合适的上下文既耗费资源、不准确，又受上下文窗口限制。将文件倾倒到提示词中会浪费 Token，而且随着上下文不断填满，大模型会逐渐偏离实际任务。

与其手动使用 grep/find 搜索或倾倒原始文件文本，不如使用 code-memory 对本地索引的代码库进行语义搜索。它受到 claude-context 的启发，但从一开始就是为大规模本地搜索而设计的。

支持的语言

完整 AST 支持（结构化解析并提取符号）：Python、JavaScript/TypeScript、Java、Go、Rust、C/C++、Ruby、Kotlin

回退支持（整文件索引）：C#、Swift、Scala、Lua、Shell、Config（yaml/toml/json）、Web（html/css）、SQL、Markdown

匹配 .gitignore 规则的文件会自动跳过。

架构：渐进式披露

code-memory 不采用单一的庞大搜索，而是将查询路由到三个专用工具：

问题类型	工具	数据源
“在哪里／是什么／怎么做？”——查找定义、引用、结构并进行语义搜索	search_code	BM25 + Dense Vector（SQLite vec）
“架构／模式”——理解架构、解释工作流	search_docs	语义／模糊搜索
“是谁／为什么？”——调试回归问题、理解意图	search_history	Git + BM25 + Dense Vector（SQLite vec）
“设置／准备”——解析索引并生成嵌入	index_codebase	AST 解析器 + sentence-transformers

这样可以确保大模型在获取任何数据之前，先选择正确的检索策略。

安装

从 PyPI 安装（推荐）

# Install with pip
pip install code-memory

# Or with uvx (for MCP hosts)
uvx code-memory

从源代码安装

# 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

预构建二进制文件（独立运行）

从 GitHub Releases 下载独立可执行文件——无需安装 Python。

平台	架构	文件
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

**注意：**首次运行时会将嵌入模型（约 600MB）下载到 ~/.cache/huggingface/。之后的运行会使用缓存的模型。

快速入门

前置条件

• Python ≥ 3.13
• uv 包管理器（推荐）或 pip

如果尚未安装 uv，请先安装：

curl -LsSf https://astral.sh/uv/install.sh | sh

安装并运行

# Install from PyPI
pip install code-memory

# Or run directly with uvx
uvx code-memory

开发

# 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

配置 MCP 宿主

你可以使用 uvx（需要 Python）或独立二进制文件（无需依赖）。

使用 uvx（需要 Python）

Gemini CLI / Gemini Code Assist

将以下内容添加到 MCP 设置中（例如 ~/.gemini/settings.json）：

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

Claude Desktop

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

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

Claude Code（CLI）

将以下内容添加到项目根目录下的 .mcp.json，或添加到 ~/.mcp.json 以便全局使用：

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

VS Code (Copilot / Continue)

在工作区的 .vscode/mcp.json 中添加：

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

使用独立二进制文件（无需 Python）

将路径替换为下载的二进制文件所在位置：

{
  "mcpServers": {
    "code-memory": {
      "command": "/path/to/code-memory-linux-x86_64"
    }
  }
}

对于 Windows：

{
  "mcpServers": {
    "code-memory": {
      "command": "C:\\path\\to\\code-memory-windows-x86_64.exe"
    }
  }
}

共享 SSE 服务（降低内存使用量）

默认情况下，每个 MCP 宿主项目都会启动自己的 code-memory 进程，并为每个项目加载一次嵌入模型（约 1–2 GB）。为避免这种情况，你可以通过 SSE（服务器发送事件）运行单个共享实例，并让所有 MCP 宿主连接到该实例。

启动共享服务

# 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

服务默认监听 http://127.0.0.1:8765/sse。

配置 MCP 宿主以使用共享服务

不要启动新进程，而是将 MCP 宿主指向正在运行的 SSE 端点。

Claude Desktop

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

VS Code (Copilot / Continue)

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

Claude Code（CLI）— .mcp.json

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

提示： 配置 uvx code-memory --transport sse，通过单实例服务管理器（例如 systemd 用户服务、launchd Agent 或其他一次性登录／启动机制）启动，这样共享服务就会自动启动。

安全性： SSE 端点未经过身份验证。请保留默认的 --host 127.0.0.1，以便只有本地进程可以连接；除非已在前面配置身份验证，否则不要绑定到 0.0.0.0 或公共网络接口。

配置

CLI 选项

选项	说明	默认值
--transport	传输协议：stdio 或 sse	stdio
--port	SSE 传输使用的端口（仅在使用 --transport sse 时）	8765
--host	SSE 传输使用的主机／绑定地址（仅在使用 --transport sse 时）	127.0.0.1

环境变量

变量	说明	默认值
CODE_MEMORY_LOG_LEVEL	日志详细程度（DEBUG、INFO、WARNING、ERROR）	INFO
EMBEDDING_MODEL	用于生成嵌入的 HuggingFace 模型 ID	jinaai/jina-code-embeddings-0.5b

示例：

CODE_MEMORY_LOG_LEVEL=DEBUG uvx code-memory

自定义嵌入模型

你可以通过设置 EMBEDDING_MODEL 环境变量使用其他嵌入模型：

EMBEDDING_MODEL="BAAI/bge-small-en-v1.5" uvx code-memory

对于 MCP 宿主，请将环境变量添加到配置中：

{
  "mcpServers": {
    "code-memory": {
      "command": "uvx",
      "args": ["code-memory"],
      "env": {
        "EMBEDDING_MODEL": "BAAI/bge-small-en-v1.5"
      }
    }
  }
}

注意： 更改嵌入模型会使现有索引失效。切换模型后，你需要重新运行 index_codebase。

工具

index_codebase

对指定目录中的源文件和文档编制索引或重新编制索引。在使用 search_code 或 search_docs 之前运行此工具，以确保数据库保持最新。使用 tree-sitter 进行与语言无关的结构提取，并使用 sentence-transformers 生成稠密向量嵌入（在本地进程中运行），以支持语义搜索。

index_codebase(directory=".")

search_code

执行语义搜索、查找结构化代码定义、定位函数／类的定义位置，或梳理依赖引用（调用图）。使用混合检索（BM25 + 向量嵌入）查找精确匹配和语义相似内容。

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

从概念层面理解代码库，例如了解其工作方式、架构模式和标准操作流程（SOP）。搜索 Markdown 文档、README 和从代码中提取的文档字符串。

search_docs(query="how does the authentication flow work?")
search_docs(query="installation instructions", top_k=5)

search_history

通过 Git 历史调试回归问题并了解开发者意图。

search_history(query="fix login timeout", search_type="commits")
search_history(query="src/auth/login.py", search_type="file_history", target_file="src/auth/login.py")
search_history(query="server.py", search_type="blame", target_file="server.py", line_start=1, line_end=20)

项目结构

code-memory/
├── code_memory/           # Package source
│   ├── server.py          # MCP server entry point (FastMCP)
│   ├── db.py              # SQLite database layer with sqlite-vec
│   ├── parser.py          # Tree-sitter-based code parser
│   ├── doc_parser.py      # Markdown documentation parser
│   ├── queries.py         # Hybrid retrieval query layer
│   ├── git_search.py      # Git history search module
│   ├── errors.py          # Custom exception hierarchy
│   ├── validation.py      # Input validation functions
│   ├── logging_config.py  # Structured logging configuration
│   └── api_types.py       # MCP response TypedDicts
├── tests/                 # Test suite
├── pyproject.toml         # Project metadata & dependencies
└── prompts/               # Milestone prompt engineering files

故障排除

“Git repository not found”错误

请确保在 Git 仓库中运行 search_history。该工具会从当前目录开始向上查找 .git。

搜索结果为空

先运行 index_codebase(directory=".")，为代码和文档编制索引。索引保存在本地的 code_memory.db 中。

索引速度缓慢

索引过程会使用本地的 sentence-transformers 模型生成嵌入。首次运行时会下载模型（jina-code-embeddings-0.5b 约 600MB）。后续运行会更快。

嵌入模型错误

请确保磁盘空间和内存充足。加载 jina-code-embeddings-0.5b 模型需要约 1GB RAM。

隐私与安全

你的代码永远不会离开你的设备。 与基于云的代码智能工具不同，code-memory 完全在本地运行：

• 零遥测 — 不收集使用数据、分析信息或跟踪数据
• 零外部 API 调用 — 所有处理都在进程内完成
• 零云依赖 — 初始设置后无需联网即可使用
• 数据留在本地 — 索引存储在本地 SQLite 数据库中

因此，code-memory 非常适合用于：

• 专有和机密代码库
• 注重安全的组织
• 隔离网络的开发环境
• 注重隐私的开发者

请参阅 COMPARISON.md，了解与基于云的替代方案的详细对比。

隔离网络与离线支持

code-memory 可在完全隔离的环境中运行：

方法 1：预构建二进制文件 + 缓存模型

1. 在联网设备上运行一次 code-memory，以缓存嵌入模型：

   uvx code-memory
   # Model downloads to ~/.cache/huggingface/
   

2. 将以下内容传输到隔离网络设备：

   • 从 GitHub Releases 获取的独立二进制文件
   • 模型缓存目录（~/.cache/huggingface/hub/models--*）

3. 在隔离网络设备上运行 — 无需联网。

方法 2：离线 pip 安装

1. 在联网设备上从 PyPI 下载 wheel 文件
2. 传输并安装：pip install code-memory-*.whl
3. 按上述方法预缓存模型
4. 离线运行

路线图

• 里程碑 1 — 项目脚手架与 MCP 协议接入
• 里程碑 2 — 使用 AST 解析 + SQLite + sqlite-vec 实现 search_code
• 里程碑 3 — 集成 Git 实现 search_history
• 里程碑 4 — 使用语义搜索实现 search_docs
• 里程碑 5 — 生产环境加固与打包

贡献

请参阅 CONTRIBUTING.md，了解开发环境设置和指南。

更新日志

请参阅 CHANGELOG.md，了解版本历史。

许可证

MIT