Claude Code Agentic Semantic Memory System MCP

🚀 Claude Code 代理语义记忆系统 (MCP)

Claude Code 代理语义记忆系统（MCP）是一个先进的模型上下文协议（MCP）服务器，它为 Claude Code 提供了持久的语义记忆能力，能够实现跨会话的长期信息存储和检索。该系统使 Claude 能够在对话之间记住上下文、用户偏好和重要信息。

🚀 快速开始

前提条件

• Node.js 18 及以上版本
• 具备 pgvector 扩展的 PostgreSQL 数据库（推荐使用 Neon）
• 已安装 Claude Code CLI

安装步骤

1. 将此 MCP 服务器克隆或复制到你的项目中：

cp -r /path/to/agentic-memory /your/project/.claude/mcp-servers/

2. 安装依赖项：

cd /your/project/.claude/mcp-servers/agentic-memory
npm install

3. 配置环境变量：

cp .env.example .env
# 使用你的数据库 URL 编辑 .env 文件

4. 运行数据库迁移：

npm run db:migrate

5. 添加到 Claude Code：

claude mcp add agentic-memory ./run-server.sh

6. 验证连接：

claude mcp list
# 应显示：agentic-memory - ✓ 已连接

✨ 主要特性

• 🧠 持久记忆：信息能够在 Claude Code 会话之间持久保存。
• 🔍 语义搜索：基于语义而非仅关键词来检索记忆。
• 📁 项目命名空间：将记忆组织到不同的上下文/项目中。
• 🌐 本地嵌入：无需外部 API 依赖，可离线工作。
• 🔗 记忆关系：创建具有关联记忆的知识图谱。
• 🚀 基于意图的激活：自然语言触发自动工具调用。
• 📊 完整的 CRUD 操作：创建、读取、更新和删除记忆。
• 🔐 隐私优先：所有数据存储在你自己的 PostgreSQL 数据库中。

🏗️ 架构

核心组件

agentic-memory/
├── src/
│   ├── index.ts           # MCP 服务器入口点
│   ├── db/
│   │   ├── client.ts      # 数据库连接（Neon PostgreSQL）
│   │   └── schema.ts      # Drizzle ORM 模式（记忆、关系）
│   └── tools/
│       ├── createMemory.ts    # 存储新记忆
│       ├── searchMemory.ts    # 语义搜索
│       ├── listMemories.ts    # 列出并过滤记忆
│       ├── deleteMemory.ts    # 删除记忆
│       ├── updateMemory.ts    # 修改现有记忆
│       ├── manageProjects.ts  # 项目命名空间管理
│       └── simpleEmbedding.ts # 本地嵌入生成
├── run-server.sh          # 服务器启动脚本
└── .env                   # 环境配置

工作原理

1. Claude Code 通过标准输入输出向 MCP 服务器发送请求。
2. MCP 服务器 处理工具请求（创建、搜索、删除记忆）。
3. 嵌入 使用数学算法在本地生成。
4. PostgreSQL（Neon）使用 pgvector 存储记忆以进行语义搜索。
5. Drizzle ORM 管理数据库操作和迁移。

💻 使用示例

基础用法

以下是使用 MCP 服务器的基本步骤示例：

# 克隆或复制 MCP 服务器
cp -r /path/to/agentic-memory /your/project/.claude/mcp-servers/

# 安装依赖
cd /your/project/.claude/mcp-servers/agentic-memory
npm install

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填入你的数据库 URL

# 运行数据库迁移
npm run db:migrate

# 添加到 Claude Code
claude mcp add agentic-memory ./run-server.sh

# 验证连接
claude mcp list

高级用法

在实际使用中，你可以利用 MCP 提供的各种工具进行记忆操作：

# 创建新记忆
claude mcp run create_memory "记住用户更喜欢 TypeScript"

# 搜索相关记忆
claude mcp run search_memory "我们对用户的偏好了解多少？"

# 列出所有记忆
claude mcp run list_memories "显示当前项目中的所有记忆"

# 删除特定记忆
claude mcp run delete_memory "删除 ID 为 xyz 的记忆"

# 更新现有记忆
claude mcp run update_memory "更新位置信息"

# 切换项目
claude mcp run switch_project "切换到项目 'work'"

# 列出所有项目
claude mcp run list_projects "存在哪些项目？"

# 删除整个项目
claude mcp run delete_project "删除 'test' 项目"

📚 详细文档

可用的 MCP 工具

使用 CLAUDE.md 编排

CLAUDE.md 文件可作为准编排器，提供以下功能：

• 上下文指令：关于记忆使用的高级规则。
• 专家代理：Claude Code 可以调用的记忆代理。
• 不可变性原则：记忆应仅可追加。
• 质量准则：仅存储高价值、可复用的信息。

示例 CLAUDE.md 模式：

# 项目上下文: [你的项目名称]

本项目使用先进的语义记忆系统，随着时间的推移不断学习和改进。

## 关键能力
- **语义记忆**：长期记忆存储和检索
- **专家代理**：专门用于记忆操作的代理

## 核心原则
- **不可变记忆**：一旦创建，记忆不应被更改
- **仅高价值信息**：仅存储可复用、非显而易见的信息
- **无敏感信息**：绝不存储 API 密钥、密码或个人身份信息

🔧 技术细节

环境变量配置

创建 .env 文件：

# PostgreSQL 连接（必需）
DATABASE_URL=postgresql://user:pass@host/db?sslmode=require

# 可选：嵌入配置
EMBEDDING_MODEL=simple  # 或 'llama' 用于高级配置
EMBEDDING_DIMENSIONS=1536

# 可选：默认项目
DEFAULT_PROJECT=default

数据库模式

该系统使用两个主要表：

• memories：存储内容、嵌入、元数据和时间戳。
• memory_relations：链接相关记忆（父子关系）。

嵌入系统

简单嵌入（默认）

• 优点：无外部依赖，可离线工作，速度快。
• 缺点：语义准确性较低。
• 使用场景：开发、受限网络、测试。

Llama CPP 嵌入（高级）

• 优点：语义准确性更高。
• 缺点：需要下载模型，占用更多资源。
• 使用场景：网络连接良好的生产环境。

代理架构

当前代理

✅ 记忆 CRUD 代理：执行创建、读取、更新、删除操作。 ✅ 项目管理代理：进行命名空间组织。 ✅ 搜索代理：进行语义相似性搜索。

推荐的额外代理

1. 记忆关系代理

   • 创建父子关系。
   • 构建知识图谱。
   • 跟踪记忆演变。

2. 记忆分析代理

   • 提供使用统计信息。
   • 分析记忆模式。
   • 提供优化建议。

3. 导出/导入代理

   • 备份记忆。
   • 在项目之间转移。
   • 提供迁移工具。

4. 去重代理

   • 检测相似记忆。
   • 合并重复项。
   • 保持一致性。

🚨 常见问题及解决方案

问题：MCP 列表中显示“连接失败”

解决方案：检查 .env 文件是否存在，以及 DATABASE_URL 是否正确。

问题：嵌入维度不匹配

解决方案：确保 EMBEDDING_DIMENSIONS 与你的数据库向量大小匹配。

问题：记忆在会话之间无法持久保存

解决方案：验证数据库连接，并确保已运行迁移。

📝 开发

直接运行 TypeScript

npm run dev

为生产环境构建

npm run build

运行测试

npm test

🔄 复制指南

要在另一个代码库中复制此设置，请按以下步骤操作：

1. 复制 MCP 服务器目录
2. 设置具有 pgvector 的 PostgreSQL 数据库
3. 配置环境变量
4. 运行迁移
5. 添加到 Claude Code 配置中
6. 创建包含记忆指令的 CLAUDE.md 文件
7. 使用简单的记忆操作进行测试

📊 生产环境考虑事项

• 数据库扩展：对于高负载使用情况，考虑使用连接池。
• 嵌入缓存：为频繁访问的记忆实现缓存。
• 备份策略：定期进行数据库备份至关重要。
• 安全性：切勿在记忆中存储敏感信息。
• 监控：跟踪记忆使用情况和搜索性能。

🤝 贡献

欢迎贡献代码！请随时提交拉取请求。

贡献领域

• 改进嵌入算法
• 添加新的记忆管理工具
• 增强搜索功能
• 创建可视化工具
• 优化数据库查询
• 增加对更多嵌入模型的支持

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🙏 致谢

• Anthropic 提供 Claude 和 MCP 协议
• Neon 提供无服务器 PostgreSQL
• Drizzle ORM 用于数据库管理
• Claude Code 社区提供反馈和建议

📧 联系信息

Tristan McInnis

• GitHub: @tristan-mcinnis
• 项目: claude-code-agentic-semantic-memory-system-mcp

为 Claude Code 构建 - 实现跨 AI 编码会话的持久语义记忆。

⭐ 如果你觉得这个项目有用，请在 GitHub 上给它点个星！