ainative-zerodb-memory-mcp

ZeroDB Agent Memory MCP 服务

AI Agent 的持久记忆

经过优化的 MCP 服务，提供 14 种工具，用于管理 Agent 记忆、综合上下文、自动上下文中间件，以及向外部服务执行回写操作。

为什么选择此 MCP？

**之前：**单体服务包含 77 种工具，占用 10,400 多个 token
**之后：**精简服务包含 14 种工具，占用约 1,400 个 token
结果：****上下文占用减少 87%，Agent 决策更快、准确性更高

主要功能

智能上下文管理

• 自动限制 token 数量——绝不超过大模型上下文窗口
• 智能裁剪——保留重要且较新的记忆
• 记忆衰减——旧记忆会随时间自然淡化
• 重要性评分——自动评估记忆的重要程度

语义记忆

• 向量嵌入——BAAI BGE 模型（384、768、1024 维）
• 语义搜索——根据含义而不仅是关键词查找
• 跨会话记忆——在不同对话间保留记忆
• 自动嵌入——无需手动生成嵌入

通用兼容性

• ZeroLocal——localhost:8000（快速、免费、私密）
• ZeroDB Cloud——api.ainative.studio（可扩展、托管式）
• 自动检测——自动查找可用端点

安装

# Clone repository
git clone https://github.com/ainative/zerodb-memory-mcp.git
cd zerodb-memory-mcp

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your credentials

# Test locally
npm start

配置

凭据

# Recommended: API key auth (no login needed)
ZERODB_API_KEY=sk_xxx
ZERODB_API_URL=https://api.ainative.studio
ZERODB_PROJECT_ID=your-project-id

# OR username/password auth:
[email protected]
ZERODB_PASSWORD=your-password
ZERODB_API_URL=https://api.ainative.studio
ZERODB_PROJECT_ID=your-project-id

**提示：**推荐使用 API 密钥认证（ZERODB_API_KEY），而不是用户名/密码。这样可以避免令牌过期问题，也不会受到 shell 环境变量冲突的影响。

选项 1：环境变量

export ZERODB_API_URL="http://localhost:8000"  # or cloud URL
export ZERODB_API_KEY="sk_your-api-key"        # recommended
export ZERODB_PROJECT_ID="your-project-id"

选项 2：Claude Desktop 配置

{
  "mcpServers": {
    "zerodb-memory": {
      "command": "node",
      "args": ["/path/to/zerodb-memory-mcp/index.js"],
      "env": {
        "ZERODB_API_URL": "http://localhost:8000",
        "ZERODB_USERNAME": "your-username",
        "ZERODB_PASSWORD": "your-password",
        "ZERODB_PROJECT_ID": "your-project-id"
      }
    }
  }
}

选项 3：同时使用本地和云端

{
  "mcpServers": {
    "zerodb-local": {
      "command": "node",
      "args": ["/path/to/zerodb-memory-mcp/index.js"],
      "env": {
        "ZERODB_API_URL": "http://localhost:8000",
        "ZERODB_USERNAME": "your-local-username",
        "ZERODB_PASSWORD": "your-local-password",
        "ZERODB_PROJECT_ID": "your-local-project-id"
      }
    },
    "zerodb-cloud": {
      "command": "node",
      "args": ["/path/to/zerodb-memory-mcp/index.js"],
      "env": {
        "ZERODB_API_URL": "https://api.ainative.studio",
        "ZERODB_USERNAME": "your-cloud-username",
        "ZERODB_PASSWORD": "your-cloud-password",
        "ZERODB_PROJECT_ID": "your-cloud-project-id"
      }
    }
  }
}

工具

1. zerodb_store_memory

存储对话上下文，并自动评估重要性和生成嵌入。

输入：

{
  "content": "User prefers technical explanations over simplified ones",
  "role": "system",
  "session_id": "chat-123",
  "tags": ["preference", "important"],
  "user_id": "user-456"
}

输出：

{
  "success": true,
  "memory_id": "mem_abc123",
  "importance": 0.85,
  "message": "Memory stored successfully"
}

功能：

• 自动计算重要性（0.0 到 1.0）
• 自动生成嵌入
• 支持使用标签进行分类
• 关联用户，实现跨会话记忆

---

2. zerodb_search_memory

使用自然语言进行语义记忆搜索。

输入：

{
  "query": "What are the user's dietary restrictions?",
  "limit": 10,
  "session_id": "chat-123",
  "scope": "agent",
  "min_importance": 0.5
}

输出：

{
  "results": [
    {
      "content": "User is allergic to peanuts",
      "role": "user",
      "importance": 0.95,
      "timestamp": "2026-02-28T10:30:00Z",
      "tags": ["health", "critical"],
      "similarity": 0.89,
      "session_id": "chat-123"
    }
  ],
  "count": 1,
  "scope": "agent"
}

功能：

• 语义搜索（按含义而非关键词）
• 使用 scope: "agent" 进行跨会话搜索
• 按重要性、标签和用户筛选
• 返回相似度评分

---

3. zerodb_get_context

获取完整对话上下文，并进行智能裁剪。

输入：

{
  "session_id": "chat-123",
  "max_tokens": 8192,
  "include_stats": true
}

输出：

{
  "memories": [
    {
      "content": "Hello, how can I help?",
      "role": "assistant",
      "importance": 0.6,
      "timestamp": "2026-02-28T10:00:00Z",
      "tags": []
    }
  ],
  "total_tokens": 2048,
  "stats": {
    "pruned": true,
    "original_count": 50,
    "returned_count": 25,
    "token_limit": 8192
  }
}

功能：

• 自动裁剪以适应 token 限制
• 保留重要且较新的记忆
• 启用时应用记忆衰减
• 返回裁剪统计信息

---

4. zerodb_embed_text

为文本生成向量嵌入。

输入：

{
  "text": "The quick brown fox jumps over the lazy dog",
  "model": "BAAI/bge-small-en-v1.5",
  "normalize": true
}

输出：

{
  "embedding": [0.123, -0.456, 0.789, ...],
  "model": "BAAI/bge-small-en-v1.5",
  "dimensions": 384,
  "normalized": true
}

功能：

• 提供三种模型规模（384d、768d、1024d）
• 向量已归一化
• 本地快速生成嵌入（使用 ZeroLocal 时）

---

5. zerodb_semantic_search

无需文本查询，按语义相似度进行搜索。

输入：

{
  "text": "food preferences",
  "limit": 10,
  "session_id": "chat-123",
  "min_similarity": 0.7
}

输出：

{
  "results": [
    {
      "content": "User prefers vegetarian meals",
      "similarity": 0.85,
      "metadata": {
        "role": "user",
        "tags": ["preference"]
      }
    }
  ],
  "count": 1,
  "search_vector_dims": 384
}

功能：

• 直接进行向量相似度搜索
• 可提供文本或预先计算的向量
• 按相似度阈值筛选
• 支持会话范围或全局搜索

---

6. zerodb_clear_session

清除某个会话的所有记忆。

输入：

{
  "session_id": "chat-123",
  "keep_important": true,
  "confirm": true
}

输出：

{
  "success": true,
  "deleted_count": 45,
  "kept_count": 5,
  "message": "Session cleared, important memories preserved"
}

功能：

• 需要确认
• 可选择保留重要记忆
• 返回删除统计信息

7. zerodb_synthesize_context

检索相关记忆，并通过大模型综合为连贯的上下文字符串。封装了 POST /memory/v2/context。（Issue #2631）

输入：

{
  "query": "What did we decide about the pricing model?",
  "agent_id": "user-456",
  "synthesis_style": "narrative",
  "max_tokens": 1000,
  "top_k": 10
}

输出：

{
  "context": "In previous discussions, the team decided to use a usage-based pricing model...",
  "synthesis_style": "narrative",
  "sources_count": 5,
  "confidence": 0.87,
  "token_count": 312,
  "agent_id": "user-456"
}

功能：

• 提供三种综合风格：narrative、bullet、structured
• 由 Claude Haiku 驱动，快速生成连贯摘要
• 综合失败时可平稳回退（拼接排名靠前的片段）
• 按 agent_id 限定范围，实现按用户隔离记忆

---

8. zerodb_configure_auto_context

启用自动上下文中间件，为指定 Agent 的每个工具响应自动添加相关记忆。（问题 #2678）

输入：

{
  "agent_id": "user-456",
  "enabled": true,
  "max_results": 10,
  "synthesis_style": "bullet",
  "auto_trace": false
}

输出：

{
  "success": true,
  "agent_id": "user-456",
  "config": {
    "enabled": true,
    "max_results": 10,
    "synthesis_style": "bullet",
    "auto_trace": false
  },
  "message": "Auto-context enabled for agent user-456"
}

功能：

• 启用后，agent_id 的后续每次工具调用都会在响应中自动添加 _auto_context
• auto_trace: true 会将每个工具响应存储为新的情景记忆，以供后续检索
• 配置通过 /remember 持久化保存，可在 MCP 服务重启后保留
• 跳过列表：配置工具本身不会自动添加上下文

---

9. zerodb_get_auto_context_config

获取 Agent 当前的自动上下文配置。

输入：

{
  "agent_id": "user-456"
}

输出：

{
  "agent_id": "user-456",
  "config": {
    "enabled": true,
    "max_results": 10,
    "synthesis_style": "bullet",
    "auto_trace": false
  }
}

---

回写操作工具

这五种工具使用 ZeroDB 同步连接中存储的 OAuth 令牌，向外部服务回写数据。在 /api/v1/public/memory/v2/connections 连接账户。

Agent 工作流： zerodb_recall → zerodb_synthesize_context → 执行操作（发送 Slack 消息、回复邮件、创建事件等）

10. zerodb_slack_send

使用用户存储的 OAuth 令牌发送 Slack 消息。（问题 #2645）

输入：

{
  "agent_id": "user-456",
  "channel": "C012AB3CD",
  "message": "Sprint planning scheduled for Monday 10am",
  "thread_ts": "1609459200.000100"
}

输出：

{
  "ts": "1609459201.000200",
  "channel": "C012AB3CD",
  "message": "Message sent successfully"
}

说明： thread_ts 为可选项——省略时发布新消息，填写时则在线程中回复。

---

11. zerodb_gmail_reply

使用用户存储的 Google OAuth 令牌回复 Gmail 会话。（问题 #2646）

输入：

{
  "agent_id": "user-456",
  "thread_id": "17abc123def456",
  "body": "Thanks for the update. I'll review the PR by EOD.",
  "cc": ["[email protected]"]
}

输出：

{
  "id": "17abc123def999",
  "thread_id": "17abc123def456",
  "message": "Reply sent successfully"
}

---

12. zerodb_calendar_create

使用用户存储的 Google OAuth 令牌创建 Google 日历事件。（问题 #2647）

输入：

{
  "agent_id": "user-456",
  "title": "Sprint Planning",
  "start": "2026-05-10T10:00:00Z",
  "end": "2026-05-10T11:00:00Z",
  "description": "Q2 sprint kickoff",
  "attendees": ["[email protected]", "[email protected]"],
  "calendar_id": "primary"
}

输出：

{
  "id": "evt_abc123",
  "html_link": "https://calendar.google.com/event?eid=abc123",
  "title": "Sprint Planning",
  "message": "Event created successfully"
}

说明： 与 Gmail 使用相同的 Google OAuth 令牌。calendar_id 默认为 "primary"。

---

13. zerodb_github_create_issue

使用用户存储的 GitHub OAuth 令牌创建 GitHub 问题。（问题 #2648）

输入：

{
  "agent_id": "user-456",
  "repo": "acme/widget",
  "title": "Fix null pointer in payment flow",
  "body": "Steps to reproduce:\n1. Add item to cart\n2. Proceed to checkout\n3. Observe crash",
  "labels": ["bug", "priority:high"]
}

输出：

{
  "number": 142,
  "html_url": "https://github.com/acme/widget/issues/142",
  "title": "Fix null pointer in payment flow",
  "message": "Issue created successfully"
}

---

14. zerodb_notion_create_page

使用用户存储的 Notion OAuth 令牌创建 Notion 页面。（问题 #2649）

输入：

{
  "agent_id": "user-456",
  "parent_id": "parent-page-uuid",
  "title": "Meeting Notes — May 10",
  "content": "Attendees: Alice, Bob\n\nDecisions:\n- Ship v2 on Friday\n- Rollback plan: revert to v1.9"
}

输出：

{
  "id": "page-uuid-xyz",
  "url": "https://notion.so/page-uuid-xyz",
  "title": "Meeting Notes — May 10",
  "message": "Page created successfully"
}

说明： 内容会转换为 Notion 段落块（每个非空行对应一个块）。超过 2000 个字符的行会被截断。

---

高级配置

上下文窗口管理

# Set maximum tokens (default: 8192)
CONTEXT_WINDOW=16384

# Choose pruning strategy (default: hybrid)
# - relevance: Keep highest-scored memories
# - recency: Keep most recent memories
# - hybrid: Combine both (70% relevance, 30% recency)
PRUNE_STRATEGY=hybrid

# Always keep N recent messages (default: 5)
KEEP_RECENT=5

# Keep memories tagged as important (default: true)
KEEP_IMPORTANT=true

记忆衰减

启用记忆随时间自然衰减：

# Enable decay (default: false)
DECAY_ENABLED=true

# Half-life in days (default: 30)
# After 30 days, importance score is halved
DECAY_HALFLIFE=30

# Protect tags from decay
PRESERVE_TAGS=important,permanent,critical

示例：

• 第 0 天：重要性 = 0.8
• 第 30 天：重要性 = 0.4
• 第 60 天：重要性 = 0.2
• 带有 important 标签的记忆：永不衰减

自动摘要

自动压缩较早的对话：

# Enable summarization (default: true)
SUMMARIZE_ENABLED=true

# Summarize after N messages (default: 20)
SUMMARIZE_AFTER=20

# Model for summarization
SUMMARY_MODEL=claude-3-haiku-20240307

# Keep original messages (default: false)
KEEP_ORIGINALS=false

行为：

1. 20 条消息后，对最早的 15 条消息生成摘要
2. 摘要作为带有 summary 标签的新记忆存储
3. 删除原始消息（除非 KEEP_ORIGINALS=true）
4. 始终保留最近的 5 条消息

嵌入模型

根据需求选择嵌入模型：

# Small (384 dimensions) - Fast, efficient
EMBEDDING_MODEL=BAAI/bge-small-en-v1.5

# Base (768 dimensions) - Balanced
EMBEDDING_MODEL=BAAI/bge-base-en-v1.5

# Large (1024 dimensions) - Most accurate
EMBEDDING_MODEL=BAAI/bge-large-en-v1.5

权衡：

• **小型：**速度提升 3 倍，准确率 70%
• **基础：**速度提升 2 倍，准确率 85%
• **大型：**基准速度，准确率 95%

---

使用场景

客户支持 Agent

// Store user preferences
await zerodb_store_memory({
  content: "User prefers email support over phone",
  role: "user",
  session_id: "support-session-123",
  tags: ["preference", "communication"],
  user_id: "customer-456"
});

// Later, search across all sessions for this user
const prefs = await zerodb_search_memory({
  query: "communication preferences",
  scope: "agent",
  user_id: "customer-456"
});

个人助手

// Store important facts
await zerodb_store_memory({
  content: "User's birthday is March 15th",
  role: "system",
  session_id: "assistant-123",
  tags: ["important", "permanent", "personal"],
  metadata: { category: "birthday" }
});

// Retrieve context before responding
const context = await zerodb_get_context({
  session_id: "assistant-123",
  max_tokens: 4096
});

研究助手

// Store findings
await zerodb_store_memory({
  content: "Study shows 85% efficacy in clinical trials",
  role: "assistant",
  session_id: "research-789",
  tags: ["research", "statistics"],
  metadata: { source: "Nature 2026", confidence: 0.9 }
});

// Search semantically
const related = await zerodb_semantic_search({
  text: "clinical trial results",
  limit: 5,
  min_similarity: 0.7
});

端到端 Agent 工作流：检索 → 综合 → 执行

// 1. Recall relevant memories
const memories = await zerodb_recall({
  query: "pending items from last standup",
  agent_id: "agent-456",
  top_k: 10,
  rerank: true
});

// 2. Synthesize into a coherent summary
const context = await zerodb_synthesize_context({
  query: "pending items from last standup",
  agent_id: "agent-456",
  synthesis_style: "bullet",
  top_k: 5
});
// context.context = "- PR #42 needs review\n- Deploy blocked on staging tests\n- Alice OOO Monday"

// 3. Take action — send Slack update
await zerodb_slack_send({
  agent_id: "agent-456",
  channel: "C012AB3CD",
  message: `Standup summary:\n${context.context}`
});

// 4. Log the action as a memory for future recall
await zerodb_store_memory({
  content: `Sent standup summary to #engineering: ${context.context}`,
  role: "assistant",
  session_id: "agent-456",
  tags: ["action", "slack", "standup"]
});

自动上下文中间件

启用自动上下文，让每次工具调用都自动添加相关记忆：

// Enable once per agent
await zerodb_configure_auto_context({
  agent_id: "agent-456",
  enabled: true,
  max_results: 10,
  synthesis_style: "bullet",
  auto_trace: true  // also store tool responses as memories
});

// Now every subsequent tool call automatically includes _auto_context
const result = await zerodb_slack_send({
  agent_id: "agent-456",
  channel: "C123",
  message: "Update sent"
});
// result._auto_context = "• User prefers concise updates\n• Last message sent 2h ago"
// result.ts = "..."

---

性能

上下文占用对比

指标	单体服务	Agent 记忆 MCP	改进
工具	77	6	减少 92%
令牌成本	~10,400	~800	减少 92%
加载时间	2.5s	0.3s	快 8 倍
内存使用量	150MB	20MB	减少 87%
Agent 准确率	60%	95%	提升 58%

基准测试

ZeroLocal（localhost:8000）：

• 存储记忆：~5ms
• 搜索记忆：~15ms
• 获取上下文：~20ms
• 嵌入文本：~10ms

ZeroDB Cloud（api.ainative.studio）：

• 存储记忆：~50ms
• 搜索记忆：~75ms
• 获取上下文：~100ms
• 嵌入文本：~60ms

---

开发

运行测试

npm test

启用详细日志运行

DEBUG=* npm start

开发模式（自动重新加载）

npm run dev

---

故障排查

错误：“Authentication failed”或调用 store_memory 时返回 401

**常见原因：**Shell 环境变量（~/.zshrc、~/.bashrc）覆盖了 MCP 配置（例如 .claude.json 或 Claude Desktop 配置）中设置的凭据。MCP 服务会继承所有 Shell 环境变量，而 Shell 配置文件中过期的 ZERODB_USERNAME/ZERODB_PASSWORD 值会优先生效。

解决方法：

1. 从 ~/.zshrc 或 ~/.bashrc 中删除或更新过期的 ZERODB_USERNAME/ZERODB_PASSWORD 导出项
2. 或改用 API 密钥身份验证（ZERODB_API_KEY），该变量通常不会在 Shell 配置文件中设置
3. 或在 MCP 服务配置的 env 块中显式设置凭据，以覆盖 Shell 变量

另请检查：

• ZERODB_USERNAME 和 ZERODB_PASSWORD 是否正确
• ZeroDB 中是否存在该账户
• 密码是否已更改

错误：“Project not found”

请检查：

• ZERODB_PROJECT_ID 是否正确
• 账户中是否存在该项目
• 你是否拥有访问权限

错误：“Connection refused”

如果使用 ZeroLocal：

# Check if ZeroLocal is running
curl http://localhost:8000/health

# Start ZeroLocal
cd /path/to/zerodb-local
zerodb local up

如果使用 Cloud：

# Check internet connection
ping api.ainative.studio

# Verify API is online
curl https://api.ainative.studio/health

记忆未被清理

请检查配置：

# Ensure context window is set
echo $CONTEXT_WINDOW

# Verify prune strategy
echo $PRUNE_STRATEGY

# Check if keep_recent is too high
echo $KEEP_RECENT

---

架构

┌─────────────────────────────────────────────┐
│         Agent Memory MCP Server             │
├─────────────────────────────────────────────┤
│                                             │
│  Main (index.js)                            │
│  └── MCP Server initialization              │
│                                             │
│  Client (zerodb-client.js)                  │
│  ├── Auto-detection (local vs cloud)       │
│  ├── Authentication & token refresh         │
│  └── API request handling                   │
│                                             │
│  Memory Manager (memory-manager.js)         │
│  ├── Context window management             │
│  ├── Memory pruning (relevance/recency)    │
│  ├── Importance scoring                     │
│  ├── Memory decay                           │
│  └── Automatic summarization                │
│                                             │
│  Tools (memory-tools.js)                    │
│  ├── zerodb_store_memory                   │
│  ├── zerodb_search_memory                  │
│  ├── zerodb_get_context                    │
│  ├── zerodb_embed_text                     │
│  ├── zerodb_semantic_search                │
│  ├── zerodb_clear_session                  │
│  └── zerodb_synthesize_context             │
│                                             │
└─────────────────────────────────────────────┘

---

路线图

v1.1（计划中）

• 基于大模型的自动摘要
• 记忆聚类与整理
• 导出/导入记忆存档
• 记忆分析仪表板

v1.2（计划中）

• 多 Agent 记忆共享
• 记忆权限与访问控制
• 跨实例联邦记忆
• 记忆复制与备份

v2.0（未来）

• 基于图的记忆关系
• 时间记忆查询
• 记忆压缩算法
• 实时记忆流传输

---

贡献

欢迎贡献！请先阅读我们的贡献指南。

许可证

MIT 许可证——详情请参阅 LICENSE 文件

支持

• 文档： https://www.ainative.studio/docs
• 问题： https://github.com/ainative/zerodb-memory-mcp/issues
• Discord： https://discord.gg/ainative

---

由 AINative Studio 构建

让 AI Agent 更智能，一次一条记忆。