JinDaGe - a-mem-mcp MCP Details

article

README

🚀 A-MEM：编码智能体的自进化记忆系统

A-MEM 是一款专为编码智能体设计的自进化记忆系统。与简单的向量存储不同，A-MEM 能够自动将知识组织成具有动态关系的卡片盒笔记法（Zettelkasten）风格的图谱。记忆不仅会被存储，还会随着时间不断进化和相互关联。目前，该系统已在 Claude Code 上进行了测试，并计划支持其他与 MCP 兼容的智能体。

🚀 快速开始

📦 安装

pip install a-mem

➕ 添加到 Claude Code

claude mcp add a-mem -s user -- a-mem-mcp \
  -e LLM_BACKEND=openai \
  -e LLM_MODEL=gpt-4o-mini \
  -e OPENAI_API_KEY=sk-...

就是这么简单！会话启动钩子会自动安装，以提醒 Claude 使用记忆功能。

⚠️ 重要提示 记忆数据会按项目存储在 ./chroma_db 中。若要实现跨项目的全局记忆，请参考记忆范围。

🗑️ 卸载

a-mem-uninstall-hook   # 先移除钩子
pip uninstall a-mem

🔧 工作原理

t=0              t=1                t=2

                 ◉───◉             ◉───◉
 ◉               │                 ╱ │ ╲
                 ◉                ◉──┼──◉
                                     │
                                     ◉

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━▶
            自进化记忆

添加记忆 → A-MEM 通过大语言模型（LLM）提取关键词、上下文和标签。
查找相邻记忆 → 搜索语义相似的现有记忆。
进化 → 决定是否建立链接、加强连接或更新相关记忆。
存储 → 将完整的元数据和关系持久化到 ChromaDB 中。

最终结果是一个随着时间推移变得更加智能的知识图谱，而不仅仅是规模变大。

✨ 主要特性

自进化记忆

记忆并非静态的。当你添加新的知识时，A-MEM 会自动查找相关记忆，加强连接、更新上下文并进化标签。

语义 + 结构搜索

将向量相似度与图遍历相结合。先按语义查找记忆，再探索它们之间的关联。

预览与深入挖掘

首先进行广度优先搜索，通过轻量级元数据（ID、上下文、关键词、标签）捕获相关记忆。然后使用 read_memory_note 进行深度优先搜索，获取特定记忆的完整内容。这样可以在最小化令牌使用的同时最大化召回率。

🛠️ MCP 工具

A-MEM 为你的编码智能体提供了 8 个工具： | 工具 | 描述 | |------|-------------| | add_memory_note | 存储新知识（异步操作，立即返回） | | search_memories | 对所有记忆进行语义搜索 | | search_memories_agentic | 搜索并跟踪图连接 | | search_memories_by_time | 在时间范围内进行搜索 | | read_memory_note | 获取完整详细信息（支持批量读取） | | update_memory_note | 修改现有记忆 | | delete_memory_note | 删除一条记忆 | | check_task_status | 检查异步任务的完成情况 |

💻 使用示例

# 智能体会自动调用这些工具，以下是具体操作：

# 存储一条记忆（立即返回任务 ID）
add_memory_note(content="Auth uses JWT in httpOnly cookies, validated by AuthMiddleware")

# 稍后进行搜索
search_memories(query="authentication flow", k=5)

# 进行带连接的深度搜索
search_memories_agentic(query="security", k=5)

⚙️ 高级配置

JSON 配置

若需要更多控制，可以编辑 ~/.claude/settings.json（全局）或 .claude/settings.local.json（项目）：

{
  "mcpServers": {
    "a-mem": {
      "command": "a-mem-mcp",
      "env": {
        "LLM_BACKEND": "openai",
        "LLM_MODEL": "gpt-4o-mini",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

环境变量

| 变量 | 描述 | 默认值 | |----------|-------------|---------| | LLM_BACKEND | openai、ollama、sglang、openrouter | openai | | LLM_MODEL | 模型名称 | gpt-4o-mini | | OPENAI_API_KEY | OpenAI API 密钥 | — | | EMBEDDING_MODEL | 句子转换器模型 | all-MiniLM-L6-v2 | | CHROMA_DB_PATH | 存储目录 | ./chroma_db | | EVO_THRESHOLD | 进化触发阈值 | 100 |

记忆范围

特定项目（默认）：每个项目在 ./chroma_db 中拥有独立的记忆。
全局：通过设置 CHROMA_DB_PATH=~/.local/share/a-mem/chroma_db 实现跨项目共享。

替代后端

Ollama（本地、免费）

claude mcp add a-mem -s user -- a-mem-mcp \
  -e LLM_BACKEND=ollama \
  -e LLM_MODEL=llama2

OpenRouter（100 + 模型）

claude mcp add a-mem -s user -- a-mem-mcp \
  -e LLM_BACKEND=openrouter \
  -e LLM_MODEL=anthropic/claude-3.5-sonnet \
  -e OPENROUTER_API_KEY=sk-or-...

钩子管理（Claude Code）

会话启动钩子会提醒 Claude 使用记忆工具。它会随 Claude Code 自动安装，但你也可以手动管理：

a-mem-install-hook     # 安装/重新安装钩子
a-mem-uninstall-hook   # 完全移除钩子

🐍 Python API

你可以在 Python 中直接使用 A-MEM（适用于任何智能体或应用程序）：

from agentic_memory.memory_system import AgenticMemorySystem

memory = AgenticMemorySystem(
    llm_backend="openai",
    llm_model="gpt-4o-mini"
)

# 添加（自动生成关键词、标签、上下文）
memory_id = memory.add_note("FastAPI app uses dependency injection for DB sessions")

# 搜索
results = memory.search("database patterns", k=5)

# 读取完整详细信息
note = memory.read(memory_id)
print(note.keywords, note.tags, note.links)

📚 详细文档

A-MEM 实现了以下论文中的概念：

A-MEM: Agentic Memory for LLM Agents Xu 等人，2025 arXiv:2502.12110

a-mem-mcp