Claude Memory + RAG Server

给Claude提供代码理解和语义记忆层

这是一个位于Claude和你的开发环境之间的MCP服务器，它维护着对你的代码库、偏好和上下文的持久理解。可以将其视为给Claude提供了长期记忆，并能够语义搜索你的代码。

系统

┌─────────────────────────────────────────────────────────┐
│  Claude Code                                             │
│  "查找认证逻辑"                                         │
│  "记住我更喜欢Python"                                   │
└────────────────┬────────────────────────────────────────┘
                 │ MCP协议
┌────────────────▼────────────────────────────────────────┐
│  记忆RAG服务器                                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │   记忆       │  │     代码     │  │   Git历史   │  │
│  │ (偏好,工作流)│  │   (索引函数) │  │  (提交与变更)│  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
│         语义向量搜索 (7ms)                               │
└─────────────────────────────────────────────────────────┘
                 │
┌────────────────▼────────────────────────────────────────┐
│  你的开发环境                                            │
│  • 代码文件 (Python, JS, TS, Java, Go, Rust, PHP)      │
│  • 文档 (Markdown)                                      │
│  • Git仓库                                              │
└─────────────────────────────────────────────────────────┘

工作原理

1. 索引： 服务器解析你的代码（使用Rust以提高速度），提取语义单元（函数、类），并将其存储在嵌入向量数据库中。

2. 记忆存储： 当你与Claude一起工作时，服务器会自动存储偏好、项目上下文和决策。这些被分类并嵌入以供语义检索。

3. 语义搜索： 当Claude需要信息时，它会用自然语言查询服务器。服务器根据意义而不是关键词返回相关代码、记忆或Git历史。

4. 上下文维护： 跨会话，Claude保留对你的代码库结构、偏好和项目特定知识的理解。

这使什么成为可能

• 代码理解： 询问“认证逻辑在哪里？”而不是通过函数名进行搜索
• 持久偏好： Claude记得你更喜欢Python，使用async/await等
• 项目记忆： Claude知道这个项目使用FastAPI，PostgreSQL，并遵循特定模式
• Git意识： 按语义搜索提交历史，跟踪代码如何演变
• 混合搜索： 结合语义理解与关键词精度

状态： v4.0 RC1 • ✅ 2723个测试 (BUG-023已修复) • 67%覆盖率 • 7-13ms搜索延迟

版本： 4.0 (生产就绪企业功能)

功能

🔍 语义代码搜索 (新功能！)

按意义而不是关键词搜索你的代码库。用自然语言提问，基于语义而非文本匹配找到相关代码。

示例搜索：

📌 查找认证逻辑：
你: "查找认证逻辑"
→ auth/handlers.py:45-67 - login() 异步函数
→ auth/middleware.py:23-45 - authenticate_request()
→ auth/token.py:12-34 - verify_jwt_token()

📌 查找错误处理：
你: "我们在哪里处理数据库错误？"
→ db/connection.py:89-105 - handle_db_exception()
→ models/base.py:34-56 - retry_on_connection_error() 装饰器
→ api/error_handlers.py:12-28 - database_error_handler()

📌 查找API端点：
你: "显示所有与用户相关的API路由"
→ api/routes/users.py:23-45 - GET /api/users 端点
→ api/routes/users.py:67-89 - POST /api/users/create 端点
→ api/routes/users.py:102-124 - PUT /api/users/{id} 端点

📌 查找初始化代码：
你: "应用程序是如何启动的？"
→ main.py:12-34 - initialize_app() 函数
→ config/startup.py:45-78 - load_configuration()
→ db/init.py:23-45 - setup_database_connection()

为什么有效：

• 语义理解： 根据代码的功能而不是变量名称找到代码
• 混合模式： 结合语义搜索与关键词匹配以提高精度
• 上下文感知： 理解函数、类和模块之间的关系
• 快速： 即使在大型代码库上，搜索延迟也仅为7-13ms

支持的语言：

• 编程： Python, JavaScript, TypeScript, Java, Go, Rust, Ruby, Swift, Kotlin, PHP, C, C++, C#, SQL (14种语言)
• 配置： JSON, YAML, TOML (3种格式)
• 总计： 支持17种文件格式

性能：

• 7-13ms搜索延迟 (混合搜索：10-18ms)
• 10-20文件/秒索引 (使用并行嵌入，速度快4-8倍)
• 再索引时98%缓存命中率 (速度快5-10倍)
• 实时文件监控与自动再索引

🧠 自动记忆

Claude自动记住：

• 偏好： “我更喜欢Python”，“我总是使用async/await”
• 工作流： “我通常在提交前运行测试”
• 项目事实： “此API使用FastAPI”，“数据库是PostgreSQL”
• 事件： “11月15日修复了认证bug”，“部署到生产”

📚 文档搜索

• 摄取Markdown文档 (README, docs/ 文件夹)
• 在所有文档中进行语义搜索
• 项目特定上下文
• 智能分块保留结构

快速开始

先决条件

• 必需：
  • Python 3.8+ (推荐使用Python 3.13+以获得最佳性能)
  • Docker (用于Qdrant向量数据库 - 语义代码搜索所需)
• 可选： Rust (用于更快的代码解析，如果不可用则回退到Python)
• 硬盘空间约1GB (建议10GB用于大型代码库)

安装 (一行命令！)

# 克隆并设置
git clone https://github.com/yourusername/claude-memory-server.git
cd claude-memory-server
python setup.py

# 就这样！安装向导会处理一切。

交互式向导将：

• ✅ 检查系统
• ✅ 安装依赖项
• ✅ 配置存储 (Qdrant向量数据库用于语义搜索)
• ✅ 通过Docker启动Qdrant (代码搜索所需)
• ✅ 设置解析器 (如果Rust不可用则回退到Python)
• ✅ 验证一切是否正常工作

结果： 2-5分钟内完成安装！

注意： 语义代码搜索需要在Docker上运行Qdrant。使用claude-rag validate-setup检查您的设置。

添加到Claude代码

# 第一步：获取绝对Python路径 (重要！对于pyenv用户)
PYTHON_PATH=$(which python)
echo "Python路径: $PYTHON_PATH"  # 验证路径

# 第二步：获取项目目录 (确保您在claude-memory-server目录中！)
PROJECT_DIR=$(pwd)
echo "项目目录: $PROJECT_DIR"  # 验证路径

# 第三步：使用绝对路径添加MCP服务器
claude mcp add --transport stdio --scope user \
  claude-memory-rag -- \
  $PYTHON_PATH "$PROJECT_DIR/src/mcp_server.py"

这些变量的意义：

• $PYTHON_PATH：Python解释器的完整路径 (例如，/usr/local/bin/python3)
• $PROJECT_DIR：此项目的完整路径 (例如，/Users/you/claude-memory-server)
• 这些是Bash shell变量，在您运行上述命令时会被实际路径自动替换

重要配置说明：

• 对于pyenv用户： 使用绝对Python路径 ($PYTHON_PATH) 可确保MCP服务器即使在切换不同项目目录和不同的pyenv环境时也能使用正确的Python环境和已安装的依赖项。
• 使用绝对脚本路径： 配置使用mcp_server.py的完整路径而不是-m src.mcp_server，以确保从任何目录都能正常工作。cwd参数在所有Claude Code版本中不一定可靠。

验证安装

# 快速健康检查
python -m src.cli health

# 综合验证 (检查Python、依赖项、Qdrant、解析器)
python -m src.cli validate-install

# 如果验证失败，请按照提供的操作错误消息进行操作

可选：升级以获得更好的性能

# 添加Rust解析器 (索引速度提高10-20倍)
python setup.py --build-rust

# 升级到Qdrant (更适合大型数据集)
python setup.py --upgrade-to-qdrant

<details> <summary><b>高级：手动安装</b></summary>

如果您希望手动控制：

# 1. 安装依赖项
pip install -r requirements.txt

# 2. (可选) 构建Rust模块
cd rust_core && maturin develop && cd ..

# 3. (可选) 启动Qdrant
docker-compose up -d

# 4. 配置 (编辑.env或设置环境变量)
export CLAUDE_RAG_STORAGE_BACKEND=qdrant

</details>

使用

代码搜索

索引代码库：

# 通过CLI
python -m src.cli index ./src --project-name 我的项目

# 通过Claude (MCP)
你: 请索引src目录
Claude: ✅ 从4个文件中索引了175个语义单元，耗时2.99秒

搜索代码：

# 通过Claude (MCP)
你: 查找与数据库连接相关的代码
Claude: [显示相关函数及其文件路径和行号]

监视更改：

python -m src.cli watch ./src
# 文件更改时自动重新索引

记忆与文档

存储偏好：

你: 我更喜欢TypeScript用于所有新项目
Claude: ✅ 存储偏好记忆 (全局范围)

摄取文档：

你: 请分析这个目录并摄取所有文档
Claude: ✅ 文档摄取完成
        处理文件数：15
        创建的总块数：87

查询文档：

你: 在这个项目中身份验证是如何工作的？
Claude: 根据文档：
        [显示文档中的相关部分]

交互式浏览记忆：

# 启动交互式记忆浏览器 (TUI)
python -m src.cli browse

# 特性：
# - 跨所有记忆的全文搜索
# - 按类别、上下文级别或项目过滤
# - 查看详细记忆元数据 (来源、信任评分、使用统计)
# - 使用键盘快捷键导航
# - 实时搜索

项目归档

归档不活跃项目：

# 查看项目状态
python -m src.cli archival status
# 显示活动、暂停、归档项目及其不活跃指标

# 归档项目以节省存储空间
python -m src.cli archival archive old-project
# ✅ 压缩并归档 (存储减少77%)

# 需要时重新激活
python -m src.cli archival reactivate old-project
# ✅ 在约10秒内恢复

导出备份或迁移：

# 导出归档项目到便携文件
python -m src.cli archival export my-project
# 创建：my-project_archive_20251118_103000.tar.gz (28.3 MB)
# 包括：压缩索引、清单、README

# 在另一台机器上导入
python -m src.cli archival import my-project_archive_20251118_103000.tar.gz
# ✅ 导入项目'my-project' (28.3 MB)

# 列出可用的导出
python -m src.cli archival list-exportable
# 显示所有准备导出的归档项目

存储优化：

• 压缩： 归档项目存储减少60-80%
• 便携： 导出到.tar.gz用于备份或共享
• 自动： 根据不活跃情况配置自动归档
• 快速： 恢复归档项目需5-30秒

示例节省：

之前：623.7 MB (5000个文件，活动项目)
之后： 142.8 MB (压缩归档)
节省： 77%存储减少

可用的MCP工具

Claude可以访问以下工具：

代码搜索工具 (新功能！)

• search_code - 跨索引文件进行语义代码搜索
• index_codebase - 对目录进行索引以进行代码搜索

记忆工具

• store_memory - 存储记忆 (通常是自动的)
• retrieve_memories - 搜索记忆和/或文档
• delete_memory - 通过ID删除特定记忆

文档工具

• ingest_docs - 摄取Markdown文档
• search_all - 显式搜索而不进行路由

实用工具

• get_status - 查看记忆和索引统计
• show_context - 调试工具以查看当前上下文

架构

┌─────────────────────────────────────┐
│          Claude通过MCP              │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│      MCP服务器 (mcp_server.py)      │
│  ┌───────────────────────────────┐  │
│  │   search_code                 │  │
│  │   index_codebase              │  │
│  │   store_memory                │  │
│  │   retrieve_memories           │  │
│  └───────────────────────────────┘  │
└───────┬──────────────────┬──────────┘
        │                  │
        ▼                  ▼
┌──────────────┐    ┌──────────────┐
│  增量索引器  │    │   Qdrant     │
│              │───▶│  向量数据库  │
│ Rust解析器  │    │ (localhost   │
│ 1-6ms/文件  │    │  :6333)      │
│              │    │ 7-13ms搜索  │
└──────────────┘    └──────────────┘

技术栈

核心

• Python 3.8+ - 主应用 (推荐使用3.13+)
• Rust 1.91 - 快速代码解析 (tree-sitter，可选)
• Qdrant - 向量数据库 (可选，SQLite备用)
• PyO3 - Python-Rust桥接 (可选)

AI/ML

• sentence-transformers - 嵌入生成
• all-MiniLM-L6-v2 - 嵌入模型 (384维)

存储

• Qdrant - 主要向量存储
• SQLite - 备用 + 嵌入缓存

性能

指标	性能
代码搜索	7-13ms延迟
索引	2.45文件/秒
解析	1-6ms/文件 (Rust)
嵌入	每文本约30ms
嵌入 (缓存)	<1ms
测试	2723个通过 ✅
代码覆盖率	67% (核心80-85%)

项目结构

claude-memory-server/
├── src/
│   ├── core/              # 主服务器逻辑
│   │   ├── server.py      # 带有所有工具的MemoryRAGServer
│   │   ├── models.py      # Pydantic数据模型
│   │   └── exceptions.py  # 自定义异常
│   ├── store/             # 向量存储
│   │   ├── qdrant_store.py    # Qdrant (主要)
│   │   └── sqlite_store.py    # SQLite (备用)
│   ├── embeddings/        # 嵌入生成及缓存
│   ├── memory/            # 代码索引
│   │   ├── incremental_indexer.py  # 主索引器
│   │   └── file_watcher.py         # 自动再索引
│   ├── cli/               # CLI命令 (索引、监视)
│   ├── mcp_server.py      # MCP入口点
│   └── config.py          # 配置
├── rust_core/             # Rust解析模块
│   └── src/parsing.rs     # Tree-sitter解析
├── tests/                 # 2723个测试
├── docker-compose.yml     # Q