代码存储器
确定性、高精度 代码智能层 暴露为a 模型上下文协议(MCP) 服务器。
- 零遥测 --你的代码永远不会离开你的机器
- 不需要API密钥 --使用句子转换器完全在本地运行
- 1分钟设置 --只是
uvx code-memory你准备好了 - 代币节省50% --精确的代码检索,而不是转储整个文件
如果你喜欢这个项目,请帮助星码记忆!
为什么是代码内存?
从大型代码库中查找正确的上下文是 昂贵的, 不准确的,以及 受上下文窗口限制将文件转储到提示中会浪费令牌,LLM会随着上下文的填充而失去对实际任务的跟踪。
而不是手动狩猎 grep/find 或转储原始文件文本, code-memory 对本地索引代码库运行语义搜索。灵感源自 克劳德语境,但从头开始设计用于大规模本地搜索。
支持的语言
完全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+密集向量(SQLite向量) |
| “架构/模式” --了解架构,解释工作流程 | search_docs |
语义/模糊 |
| “谁/为什么?” --调试回归,理解意图 | search_history |
Git+BM25+密集向量(SQLite向量) |
| “设置/准备” --索引解析与嵌入生成 | index_codebase |
AST解析器+ sentence-transformers |
这迫使LLM选择 正确的检索策略 在获取任何数据之前。
安装
来自PyPI(推荐)```bash
Install with pip
pip install code-memory
Or with uvx (for MCP hosts)
uvx code-memory
### 源自```bash
# 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 发布 --无需安装Python。
| 平台 | 架构 | 文件 |
|---|---|---|
| Linux | x86_64 | code-memory-linux-x86_64 |
| macOS | x86_64(英特尔) | code-memory-macos-x86_64 |
| macOS | ARM64(苹果硅) | 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:```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
### 安装并运行```bash
# Install from PyPI
pip install code-memory
# Or run directly with uvx
uvx code-memory
发展```bash
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代码辅助
添加到MCP设置中(例如。 `~/.gemini/settings.json`):```json
{
"mcpServers": {
"code-memory": {
"command": "uvx",
"args": ["code-memory"]
}
}
}
克劳德桌面版
添加 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)或 %APPDATA%\Claude\claude_desktop_config.json (Windows):```json
{
"mcpServers": {
"code-memory": {
"command": "uvx",
"args": ["code-memory"]
}
}
}
### 克劳德代码(CLI)
添加 `.mcp.json` 在您的项目根目录中或 `~/.mcp.json` 全球访问:```json
{
"mcpServers": {
"code-memory": {
"command": "uvx",
"args": ["code-memory"]
}
}
}
VS代码(复制/继续)
添加 .vscode/mcp.json 在您的工作空间中:```json
{
"servers": {
"code-memory": {
"command": "uvx",
"args": ["code-memory"]
}
}
}
### 使用独立二进制(不需要Python)
将路径替换为下载的二进制文件的位置:```json
{
"mcpServers": {
"code-memory": {
"command": "/path/to/code-memory-linux-x86_64"
}
}
}
对于Windows:```json
{
"mcpServers": {
"code-memory": {
"command": "C:\path\to\code-memory-windows-x86_64.exe"
}
}
}
## 共享SSE服务器(减少内存使用)
默认情况下,每个MCP主机项目都会启动自己的 `code-memory` 进程,每个项目加载一次嵌入模型(~1-2GB)。为了避免这种情况,你可以运行 **单一共享实例** 通过SSE(服务器发送事件)并将所有MCP主机指向它。
### 启动共享服务器```bash
# 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端点。
克劳德桌面版```json
{
"mcpServers": {
"code-memory": {
"url": "http://127.0.0.1:8765/sse"
}
}
}
#### VS代码(复制/继续)```json
{
"servers": {
"code-memory": {
"url": "http://127.0.0.1:8765/sse"
}
}
}
克劳德代码(CLI)-- `.mcp.json````json
{
"mcpServers": {
"code-memory": {
"url": "http://127.0.0.1:8765/sse"
}
}
}
> **提示:** 配置 `uvx code-memory --transport sse` 通过单实例服务管理器(例如systemd用户服务、launchd代理或其他一次性登录/启动机制)启动,以便共享服务器自动启动。
> **安全:** 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` |记录详细信息(调试、信息、警告、错误)|信息|
| `EMBEDDING_MODEL` |用于嵌入的HuggingFace模型ID| `jinaai/jina-code-embeddings-0.5b` |
例子:```bash
CODE_MEMORY_LOG_LEVEL=DEBUG uvx code-memory
自定义嵌入模型
您可以通过设置以下参数来使用不同的嵌入模型 EMBEDDING_MODEL 环境变量:```bash
EMBEDDING_MODEL="BAAI/bge-small-en-v1.5" uvx code-memory
对于MCP主机,将环境变量添加到配置中:```json
{
"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 以确保数据库是最新的。使用树形图进行语言无关的结构提取,并使用 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和docstring。```
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存储库”错误
确保你在跑步 `search_history` 从git存储库中。该工具从当前目录向上搜索以查找 `.git`.
### 空搜索结果
跑 `index_codebase(directory=".")` 首先对代码和文档进行索引。索引存储在本地 `code_memory.db`.
### 索引速度慢
索引使用局部句子变换器模型生成嵌入。第一次运行下载模型(约600MB) `jina-code-embeddings-0.5b`).后续的跑步速度更快。
### 嵌入模型错误
确保您有足够的磁盘空间和内存。这 `jina-code-embeddings-0.5b` 加载时,该型号需要~1GB RAM。
## 隐私和安全
**你的代码永远不会离开你的机器。** 与基于云的代码智能工具不同,代码内存完全在本地运行:
- **零遥测** --没有使用数据、分析或跟踪
- **外部API调用为零** --所有处理都在进程中进行
- **零云依赖** --在没有互联网的情况下工作(初始设置后)
- **您的数据保留在本地** --存储在本地SQLite数据库中的索引
这使得代码内存非常适合:
- 专有和机密代码库
- 具有安全意识的组织
- 气隙开发环境
- 注重隐私的开发人员
看 比较.md 以获取与基于云的替代方案的详细比较。
## 气隙和离线支持
代码内存在完全隔离的环境中工作:
### 方法1:预构建二进制+缓存模型
1. 在连接的机器上,运行代码内存一次以缓存嵌入模型:```bash
uvx code-memory
# Model downloads to ~/.cache/huggingface/
- 转移到气隙机器:
- 独立二进制文件来自 GitHub 发布
- 模型缓存目录(
~/.cache/huggingface/hub/models--*)
- 在气隙机器上运行——不需要网络。
方法2:离线pip安装
- 在连接的机器上从PyPI下载车轮
- 转移并安装:
pip install code-memory-*.whl - 如上所述预缓存模型
- 脱机运行
路线图
- [x] 里程碑1 --项目脚手架和MCP协议布线
- [x] 里程碑2 --实施
search_code使用AST解析+SQLite+sqlite-vec - [x] 里程碑3 --实施
search_history与Git集成 - [x] 里程碑4 --实施
search_docs语义搜索 - [x] 里程碑5 --生产硬化和包装
贡献
看 贡献.md 用于开发设置和指南。
更新日志
看 更改日志.md 版本历史。
许可证
麻省理工学院
