Codebase Memory MCP 介绍和使用指南

本系统将整个代码仓库转化为一个持久化的知识图谱（Knowledge Graph），供Claude Code、Codex CLI、Cursor等工具使用，以提供持久的代码记忆能力；该系统有效节约了大量TOKEN，且仅需在初次建立索引后，后续查询即可直接访问图数据库，从而几乎无需重新读取源码。

---

什么是 Codebase Memory MCP

Codebase Memory MCP（Model Context Protocol）是一个用于记录、检索、管理项目知识的 MCP Server。

它解决了 AI 编程助手最大的一个问题：

AI 每次都是第一次认识你的项目。

例如：

• 为什么这个接口这样设计？
• 为什么不用 Redis，而选择 PostgreSQL？
• 为什么这个目录不能修改？
• 某个 Bug 曾经修复过？
• 某个模块负责人是谁？

这些知识通常：

• 存在 Git Commit
• 存在 Issue
• 存在脑子里
• 存在微信群
• 存在飞书

AI 并不知道。

Codebase Memory MCP 就是把这些信息沉淀下来，让 AI 可以持续学习整个项目。

---

它解决什么问题

传统 AI：

用户：
帮我修改 UserService

AI：
好的。
（完全不知道这个项目历史）

使用 Memory 后：

用户：
帮我修改 UserService

AI：

查询 Memory...

发现：

- UserService 曾经重构过
- 登录逻辑不能修改
- Token 使用 JWT
- 权限系统依赖 Casbin
- 负责人是张三

然后开始修改

AI 不再是"第一次看项目"。

---

工作原理

          用户
            │
            │
            ▼
     Claude Code / Cursor
            │
            │ MCP
            ▼
    Codebase Memory Server
            │
            ├──────────────┐
            ▼              ▼
      Memory Store      Embedding
            │              │
            └──────────────┘
                   │
                   ▼
              Vector Search

Memory Server 提供：

• 保存知识
• 查询知识
• 删除知识
• 更新知识
• 根据语义搜索

AI 每次工作前都会查询相关 Memory。

---

可以记录哪些内容

几乎所有项目知识。

例如：

1、架构设计

Auth 使用 JWT。

Refresh Token 保存 Redis。

Access Token 30 分钟。

所有权限使用 Casbin。

---

2、开发规范

Controller 不允许写业务。

Service 不能直接访问数据库。

Repository 层负责 SQL。

---

3、编码规范

所有错误统一返回 Result。

日志统一使用 slog。

禁止 panic。

---

4、历史原因

订单模块不能拆分。

原因：

历史数据库太大。

已有几十个系统依赖。

---

5、Bug 记录

2025-08

修复：

Redis Key 冲突。

原因：

订单ID重复。

以后 AI 可以直接搜索：

Redis Bug

即可找到。

---

6、项目经验

例如：

MySQL 大表不要 Join。

ClickHouse 查询超过 30 天必须走聚合表。

OSS 上传必须异步。

---

安装

一般通过 npm 安装。

npm install -g codebase-memory-mcp

或者：

npx codebase-memory-mcp

也可以源码运行：

git clone xxx

npm install

npm run build

npm start

---

Claude Code 配置

例如：

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": [
        "codebase-memory-mcp"
      ]
    }
  }
}

启动 Claude Code：

claude

即可自动连接。

---

Cursor 配置

Cursor：

Settings

↓

MCP

↓

Add Server

填写：

Command

npx codebase-memory-mcp

即可。

---

常见工具

通常提供以下 MCP Tool：

add_memory

添加知识。

例如：

今天：

登录模块改成 JWT。

原因：

Session 性能不足。

AI：

Memory Saved

---

search_memory

查询知识。

例如：

JWT

返回：

JWT 登录方案

更新时间：

2025-06-01

相关文件：

auth/

---

update_memory

更新知识。

例如：

JWT 有效期

30分钟

↓

2小时

---

delete_memory

删除无效知识。

例如：

删除：

旧支付方案

---

list_memories

列出所有知识。

例如：

Architecture

Coding Style

Deployment

Database

Bug History

---

推荐使用方式

第一阶段

先记录：

项目架构

例如：

前端：

Vue3

后端：

Go

数据库：

PostgreSQL

缓存：

Redis

对象存储：

MinIO

---

第二阶段

记录：

开发规范

例如：

禁止：

Controller 写 SQL

禁止：

跨模块调用 Repository

---

第三阶段

每天记录：

今天修复了什么

今天踩了什么坑

今天新增什么规范

这样 AI 会越来越了解项目。

---

最佳实践

每完成一个功能

记录：

为什么这样设计？

例如：

订单取消：

采用异步消息。

原因：

避免事务过长。

---

每修复一个 Bug

记录：

Bug

原因

解决方案

避免再次发生

例如：

Redis Key 冲突。

统一增加业务前缀：

order:

---

每次重构

记录：

为什么重构？

哪些接口不能动？

兼容哪些系统？

---

团队协作

多人开发：

A

新增 Memory

↓

B

立即可以搜索

↓

AI

也立即知道

整个团队共享同一套知识库。

---

与 RAG 的区别

对比	Codebase Memory	RAG
保存项目经验	✅	❌
保存历史决策	✅	❌
长期知识	✅	一般
向量检索	✅	✅
AI 自动调用	✅	需要集成
面向代码库	✅	不一定

Memory 更关注：

项目知识。

而 RAG 更多关注：

文档检索。

---

使用场景

适用于：

• 企业项目
• SaaS 产品
• 微服务
• AI Agent
• 开源项目
• 长期维护项目
• 大型团队协作

尤其适合：

• Claude Code
• Cursor
• Continue
• Cline
• Windsurf
• OpenAI Codex
• 支持 MCP 的各种 AI IDE

---

优势

• 长期记忆项目知识
• AI 理解历史设计
• 减少重复解释
• 保存团队经验
• 快速定位历史 Bug
• 提高 AI 修改代码准确率
• 支持语义搜索
• 可多人共享知识库
• 与 MCP 协议无缝集成
• 持续积累项目上下文

---

总结

Codebase Memory MCP 可以理解为：

项目知识库 + AI 长期记忆 + MCP Server。

它不仅记录代码，更记录：

• 为什么这样设计
• 为什么这样实现
• 历史 Bug
• 团队规范
• 开发经验
• 架构演进

随着知识不断积累，AI 会越来越熟悉项目，能够提供更准确、更符合团队规范的代码建议，真正成为长期协作的开发伙伴。