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 上給它點個星！