给Cursor和Claude Code装上长期记忆：agent-memory通过MCP接入的完整教程-平芜编程栈

给Cursor和Claude Code装上长期记忆：agent-memory通过MCP接入的完整教程

【免费下载链接】agent-memoryMemory 是一款面向 AI 智能体的长期记忆模块，为运行在 openJiuwen 框架上的智能体提供记忆提取、存储、检索与迁移能力。项目地址: https://gitcode.com/openJiuwen/agent-memory

agent-memory 是一款开源的智能体长期记忆系统，本教程将手把手教你通过 MCP（Model Context Protocol）把它接入 Cursor 和 Claude Code，让 AI 编程助手跨会话记住你的偏好、项目约定与历史决策，告别"失忆"烦恼。

为什么需要给编程助手加长期记忆？

用 Cursor 或 Claude Code 写代码时，你肯定经历过这些场景：

上周明确说过"项目用 Python 3.11 + ruff"，换个会话它又开始给你上 Java 风格；
修过的 Bug、确认过的技术选型，每次新会话都要重新解释一遍；
项目里散落一堆MEMORY.md、笔记文件，AI 只能靠猜去翻。

agent-memory 就是为此设计的：它不是简单的"往文件里追加文本"，而是一套融合记忆提取、分层存储、混合检索与自演进的记忆底座——对话进来后，系统会自动抽取事实、精炼抽象、建立关联，并在你提问时通过关键词 + 向量的混合召回把最相关的记忆喂给模型。

接入后你能获得什么？

agent-memory 的 MCP 接入面（源码位于 jiuwen_memory_entry/mcp_server/）会把记忆能力注册为36 个memory_*工具，与 HTTP/CLI 共享同一套契约，覆盖常用场景：

类别	代表工具	用途
数据面	`memory_add`/`memory_search`/`memory_list`/`memory_get`	写入、召回、查看记忆
任务面	`memory_evolve`/`memory_submit_ingest`	触发记忆自演进、摄入新内容
管理面	`memory_admin_get`/ Space 系列工具	配置、多空间隔离与共享

对模型来说，这意味着它可以在对话中自主决定何时写入、何时召回记忆，而不需要你手动操作。

一键安装：获取并启动 MCP 服务

整个过程只需三步，全程不超过 5 分钟。

第 1 步：克隆仓库并安装 MCP 依赖

git clone https://gitcode.com/openJiuwen/agent-memory cd agent-memory pip install ".[mcp]"

⚠️ 注意：MCP 依赖要求mcpSDK 版本 < 2（2.x 已对 FastMCP 改名），按上面方式安装即可自动锁定正确版本。

第 2 步：启动 MCP 服务

仓库提供了启动脚本 scripts/run-mcp.sh，本地开发推荐先用 dev 认证模式（固定测试身份、免配置凭据）：

JIUWEN_MEMORY_MCP_AUTH_MODE=dev scripts/run-mcp.sh

第 3 步：用 Inspector 可视化验证（可选但推荐）

JIUWEN_MEMORY_MCP_AUTH_MODE=dev npx @modelcontextprotocol/inspector \ python jiuwen_memory_entry/mcp_server/__main__.py

打开 Inspector 网页，在 Tools 页应能看到全部 36 个memory_*工具，说明服务正常。

给 Claude Code 接入：3 行配置搞定

Claude Code 支持 stdio 方式的 MCP 服务器，在项目目录或用户级配置中登记即可。以 Claude Desktop 风格的claude_desktop_config.json为例：

{ "mcpServers": { "agent-memory": { "command": "python", "args": ["<仓库路径>/jiuwen_memory_entry/mcp_server/__main__.py"], "env": { "PYTHONPATH": "<仓库路径>;<仓库路径>/jiuwen_memory_entry/core", "JIUWEN_MEMORY_MCP_AUTH_MODE": "dev" } } } }

把<仓库路径>替换为你本地克隆的目录，保存后重启 Claude Code，输入/mcp即可确认agent-memory服务器已连接。此后你在对话里随口一句"以后这个项目里测试都用 pytest"，模型就会调用memory_add把它存下来。

在 Cursor 中配置 MCP 记忆工具

Cursor 的 MCP 配置位于~/.cursor/mcp.json（或设置 → MCP），写法几乎一致：

{ "mcpServers": { "agent-memory": { "command": "python", "args": ["<仓库路径>/jiuwen_memory_entry/mcp_server/__main__.py"], "env": { "PYTHONPATH": "<仓库路径>;<仓库路径>/jiuwen_memory_entry/core", "JIUWEN_MEMORY_MCP_AUTH_MODE": "dev" } } } }

配置完成后，在 Cursor 的 Agent 对话中，工具列表里会出现memory_add、memory_search等工具，模型可自主调用。

5 分钟验证：写入并召回一条记忆

接入后建议立刻做一次闭环验证，确认"写入 → 召回"链路通畅：

写入：让助手调用memory_add，内容填我喜欢喝咖啡，scope 填{"org":"local","user":"developer"}，记下返回的id；
召回：调用memory_search，query 填"喝什么"，context 的 scope 与写入时一致——返回的items中应包含刚写入的那条，附带相关性得分；
进阶：拿id继续memory_get查看详情、memory_evolve触发演进（返回job_id，可用memory_job_status查询进度）。

三步走通，你的编程助手就真正"长记性"了。

常见问题与注意事项

重启后记忆清空？默认 OFFLINE 模式使用纯内存栈，进程退出数据即清空。生产使用请启动时传入真实后端配置，例如scripts/run-mcp.sh examples/config.yml（可参考 examples/config.yml 及 docs/zh/安装指导/部署方式概览.md）。
dev 模式能上生产吗？不能。dev 模式仅固定local/developer测试身份且只允许回环绑定，适合本地功能测试；生产环境请使用required认证模式并接入正式认证器（fail-closed 设计，未装配认证器时业务调用一律拒绝）。
调用报 "cannot be called from a running event loop"？这是旧版事件循环冲突问题，当前版本已通过工作线程隔离修复，升级到最新代码即可。
工具参数对不上？MCP 面与 HTTP/CLI 共享同一套参数契约（jiuwen_memory_entry/core/api_contract.py），如有出入请以最新 docs/features/F03-mcp-surface.md 为准。