Code Memory

代码存储器

  

确定性、高精度 代码智能层 暴露为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 通过路由查询 三种专用工具:

这迫使LLM选择 *正确的检索策略* 在获取任何数据之前。

安装

来自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

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

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

# 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代码辅助

添加到MCP设置中（例如。 ~/.gemini/settings.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）：

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

克劳德代码（CLI）

添加 .mcp.json 在您的项目根目录中或 ~/.mcp.json 全球访问：

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

VS代码（复制/继续）

添加 .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-2GB）。为了避免这种情况，你可以运行 单一共享实例 通过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端点。

克劳德桌面版

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

VS代码（复制/继续）

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

克劳德代码（CLI）-- .mcp.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选项

环境变量

例子：

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 以确保数据库是最新的。使用树形图进行语言无关的结构提取，并使用 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. 在连接的机器上，运行代码内存一次以缓存嵌入模型：

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

1. 转移到气隙机器：

- 独立二进制文件来自 - 模型缓存目录(~/.cache/huggingface/hub/models--*)

1. 在气隙机器上运行——不需要网络。

方法2：离线pip安装

1. 在连接的机器上从PyPI下载车轮
2. 转移并安装： pip install code-memory-*.whl
3. 如上所述预缓存模型
4. 脱机运行

路线图

• \[x\] 里程碑1 --项目脚手架和MCP协议布线
• \[x\] 里程碑2 --实施 search_code 使用AST解析+SQLite+ sqlite-vec
• \[x\] 里程碑3 --实施 search_history 与Git集成
• \[x\] 里程碑4 --实施 search_docs 语义搜索
• \[x\] 里程碑5 --生产硬化和包装

贡献

看 贡献.md 用于开发设置和指南。

更新日志

看 更改日志.md 版本历史。

许可证

麻省理工学院