
MemoryAgent
具备认知记忆架构的 AI Agent,让 AI 记住你的偏好,越用越懂你 核心特性:四类型记忆系统、跨会话记忆共享、Claude Code 架构、15+ 大模型支持
Install with your AI
Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.
⚠ Unverified source (community-unclaimed, low activity) — reveal the prompt
⚠ Unverified source (community-unclaimed, low activity). Inspect the repo before letting your agent install it. Install and set up MemoryAgent (git-clone project) into my current project. Found on https://claudeers.com/memoryagent Repo: https://github.com/jaychouya/MemoryAgent Homepage/docs: — Detected install method: git-clone → git clone https://github.com/jaychouya/MemoryAgent Category: productivity. Platforms: api, web. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: dormant; community-verified: false. Confirm the source before running anything.
git clone https://github.com/jaychouya/MemoryAgent
// compatibility
| Platforms | api, web |
|---|---|
| Operating systems | — |
| AI compatibility | claude |
| License | MIT |
| Pricing | open-source |
| Language | Python |
MemoryAgent — Universal Local Memory for AI Agents
One memory layer. Any client — IDE, your own app, or built-in chat.
一套长期记忆:接 Cursor / 任意 MCP / HTTP API,或直接用自带对话。
选一种开始
| 目标 | 命令 |
|---|---|
| 独立对话(自带 Web UI) | make dev |
| 接到 Cursor / Claude / 任意 MCP | bash scripts/onboard.sh . |
| 接到你自己的软件 | HTTP localhost:8000/api/* → 接入总览 |
# 独立体验(克隆后)
git clone https://github.com/jaychouya/MemoryAgent.git && cd MemoryAgent
pip install -r requirements.txt && cd frontend && npm i && cd .. && make dev
# 或:给现有 IDE Agent 加记忆
bash MemoryAgent/scripts/onboard.sh /path/to/your/project
为什么不是 Mem0?
| 接入 | MemoryAgent | Mem0 | 单 App 内置记忆 |
|---|---|---|---|
| 独立对话 | ✅ Web 控制台 | 部分托管 UI | 仅该 App |
| IDE / Agent | ✅ 任意 MCP 宿主 | SDK | 通常无 |
| 自研软件 | ✅ HTTP API | ✅ API | ❌ |
| 存储 | 本地 Markdown | 向量云为主 | 黑盒 |
一句话:一套本地 Markdown 记忆,Cursor 能用、你自己的 App 也能用,不想接 API 还能直接打开网页聊。
三种用法
- 独立对话 —
make dev,浏览器里聊天 + 管理记忆(不依赖任何 IDE) - MCP 侧车 — Cursor / Claude Code / Cline / Windsurf / 任意 MCP 客户端
- HTTP API — 飞书、钉钉、自研 Agent、脚本调用同一记忆库
演示
场景 1: 用户告诉 AI 自己的偏好 → AI 记住
场景 2: 新对话 → AI 自动使用记忆,用 Python 写排序函数
核心优势
1. 定位清晰:记忆侧车,不抢 Coding Agent 的活
不做终端、Git、浏览器自动化;专注 Remember + Align。与 Cursor / Claude Code 互补:它们执行,MemoryAgent 记住你是谁、项目禁忌与决策。
2. 本地可控、人类可读
- 记忆 = Markdown + YAML,可用 Obsidian 直接改
- 默认 本地文件 + SQLite,无强制云向量库
- 可选
MEMORYAGENT_API_KEY保护 HTTP 侧车
3. 召回靠谱且可解释
- FTS + 持久向量 + Rerank(候选 20 → Top5),长问句 Query Rewrite
- 对话展示 Memory Citation(分数、类型、陈旧提示)
- L0→L1 证据链:原子记忆可追溯到原会话片段(
memories/l0/) - 默认过滤寒暄、临时任务状态和可从代码推导的信息,减少记忆污染
- Recall@5 黄金集评估 + CI 门禁(目标 ≥90%)
4. 接 Cursor 接近「零配置」
bash /path/to/MemoryAgent/scripts/onboard.sh .
自动写入 .cursor/mcp.json、规则「每轮先 recall」、user_id / project_id 由 工作区 + Git 仓库名 推导。MCP v2:recall / store / update / delete / list / export。
5. 上下文更省 Token(借鉴 Headroom / Tencent 思路)
- CCR 可逆压缩:大段 tool 输出 落盘 + 类型化预览(JSON 骨架 / 代码截断),
memory_retrieve_blob按需取回 - Mermaid 符号化工作记忆:多步 tool 时注入任务拓扑图
- 五层 ContextCompressor,异步 记忆沉淀(不拖慢首包/尾包)
6. 工程可验证
400+ pytest、流式 SSE、多厂商 LLM 配置、架构决策文档化 → 适合二次开发与私有化部署。
借鉴热门 Agent 的接入范式
热门 Agent 项目的共性不是功能堆满,而是让用户快速判断“我该怎么接”。MemoryAgent 推荐按下面方式使用:
| 你的目标 | 推荐接法 | 为什么 |
|---|---|---|
| 让 Cursor / Claude Code 记住项目偏好 | MCP 侧车 | 像 OpenHands / Cline 一样服务 coding workflow,但只负责记忆 |
| 给自研 Agent 加长期记忆 | HTTP API | 像 LangGraph / Mastra 一样把记忆作为独立状态层 |
| 管理团队项目规则 | Markdown + Obsidian | 像 Cursor Rules 一样可审计,但支持动态沉淀和纠错 |
| 验证记忆是否靠谱 | Recall Eval | 像成熟 agent 框架一样把质量指标显式化 |
最小闭环:
用户说出偏好/规则 → MemoryAgent 沉淀 → Agent 召回引用 → 用户可编辑/删除/忘记
MemoryAgent 不做终端、浏览器、Git 自动化;这些交给 Cursor、Claude Code、OpenHands、Aider。它只做一件稀缺能力:把跨会话偏好、禁忌和项目决策变成可控、可解释、可迁移的记忆层。
兼容热门生态
MemoryAgent 与以下主流工具无缝集成:
| 工具/框架 | 集成方式 | 说明 |
|---|---|---|
| Cursor | MCP 协议 | 一键安装,自动配置规则 |
| Claude Code | CLAUDE.md | 六层级配置体系 |
| Obsidian | Markdown 文件 | 记忆直接在 Obsidian 编辑 |
| LangChain | API 兼容 | 可作为记忆层使用 |
| FastAPI | 原生支持 | 后端框架 |
| Next.js | 原生支持 | 前端框架 |
| SQLite | 索引存储 | 快速检索 |
| OpenAI API | 多厂商支持 | 兼容所有 OpenAI 格式 API |
| MCP 协议 | 完整实现 | 支持所有 MCP 工具 |
| Docker | 可选部署 | 支持容器化部署 |
与 Cursor 集成
# 一键安装到当前项目
bash scripts/onboard.sh .
自动配置:
.cursor/mcp.json- MCP 服务器配置.cursor/rules/memory.mdc- 记忆规则user_id/project_id自动推导
与 Claude Code 集成
在项目根目录创建 CLAUDE.md:
# 项目规范
使用 Python 3.9+
不要用 mock 数据库
API 截止日期:周五
MemoryAgent 会自动加载并使用这些规范。
与 Obsidian 集成
记忆文件直接保存为 Markdown:
memories/
├── user/
│ └── user_abc123.md # 可在 Obsidian 编辑
├── feedback/
│ └── feedback_def456.md
└── MEMORY.md # 索引文件
用 Obsidian 打开 memories/ 文件夹即可浏览和编辑所有记忆。
功能亮点
🧠 四类型记忆系统
不只是简单的"记住对话",而是结构化的认知记忆:
| 类型 | 用途 | 示例 |
|---|---|---|
| 用户画像 | 你的偏好、角色、知识水平 | "我喜欢 Python" |
| 行为反馈 | AI 该做什么、不该做什么 | "不要用 mock 数据库" |
| 项目动态 | 截止日期、重要决策 | "周五前完成 API" |
| 外部引用 | 去哪找什么信息 | "Grafana 看板地址" |
🔄 跨会话记忆共享
会话 1: 用户喜欢 Python,讨厌 Java
会话 2: 帮我写排序 → AI 自动用 Python(记住你的偏好)
会话 3: 推荐框架 → AI 推荐 FastAPI(知道你喜欢 Python)
🗜️ 智能上下文压缩
多层策略,兼顾 省 Token 与 可恢复:
| 机制 | 作用 |
|---|---|
| CCR + ContentRouter | 大 tool/JSON/日志:预览进上下文,全文 ccr_* 落盘 |
| Mermaid 任务图 | 多步 tool 时保留拓扑,细节按节点 ID 取回 |
| 5 层 ContextCompressor | 磁盘卸载 → 裁剪 → 折叠 → 摘要 |
| 异步 Observer | 对话后自动写入记忆,不阻塞流式 done |
详见 Headroom 思路对照、架构决策。
🔌 MCP 记忆侧车 v2
| 工具 | 用途 |
|---|---|
memory_recall | 按 query 召回(user_id 可省略) |
memory_store / update / delete | 沉淀与纠错 |
memory_list / memory_export | 浏览与 prompt_block 注入 |
memory_retrieve_blob | CCR 压缩后取回完整 tool 输出 |
📊 质量可观测
GET /api/memory/metrics— Recall@5、误注入率、向量条数POST /api/memory/metrics/run-eval— 重跑黄金集
📝 Obsidian 兼容
记忆以 Markdown 文件存储,可直接在 Obsidian 中编辑:
---
name: user_abc123
description: 用户偏好
type: user
tags:
- preference
- python
---
#preference #python
用户喜欢 Python,讨厌 Java
🔧 15+ 大模型支持
一键切换,无需改代码:
| 厂商 | 模型 |
|---|---|
| OpenAI | GPT-4, GPT-4o, o3, o4-mini |
| 阿里云百炼 | qwen-max, qwen-plus, deepseek-v4-pro |
| 小米 MiMo | mimo-v2.5-pro, mimo-v2.5 |
| 智谱 GLM | glm-5.1, glm-5, glm-4-plus |
| DeepSeek | deepseek-v4-pro, deepseek-r1 |
| 月之暗面 | kimi-k2, kimi-k2-mini |
| 字节豆包 | doubao-seed-1-8-251228 |
| 更多... | OpenRouter, 自定义 API |
与常见方案对比
| 维度 | ChatGPT 记忆 | Cursor Rules | 仅向量记忆库 | MemoryAgent |
|---|---|---|---|---|
| 跨会话偏好 | 黑盒 | 项目规则 | 碎片难检索 | ✅ 四类型结构化 |
| 可编辑 | ❌ | 部分 | 难 | ✅ Markdown / Obsidian |
| 召回可解释 | ❌ | 有限 | 弱 | ✅ Citation + L0 溯源 |
| 接外部 Agent | ❌ | IDE 内置 | 需自建 | ✅ MCP + HTTP 侧车 |
| 大上下文/tool 输出 | 提供商压缩 | 部分 | — | ✅ CCR + Mermaid + 五层压缩 |
| 本地/隐私 | ❌ | 视配置 | 视部署 | ✅ 默认本地 |
| 写代码/跑 CI | — | ✅ | — | ❌ 刻意不做 |
适合:长期偏好、项目禁忌、可审计记忆、Cursor/Claude Code 用户。
不适合:替代 Devin/Cursor 完成端到端交付。
快速开始
完整矩阵见 docs/integrations.md。
用法 A:独立对话(零 IDE 依赖)
git clone https://github.com/jaychouya/MemoryAgent.git && cd MemoryAgent
pip install -r requirements.txt && cd frontend && npm install && cd ..
make dev
打开 http://localhost:3000(或 3001),在「配置」填 API Key → 直接聊。右侧为记忆控制台。
用法 B:接到 Cursor / 任意 MCP Agent
bash /path/to/MemoryAgent/scripts/onboard.sh /path/to/your/project
重载 IDE 的 MCP → 对话中「记住…」→ 新会话验证。Claude Code 加 --claude。
用法 C:HTTP 接入你的软件
pip install -r requirements.txt
python -m uvicorn src.backend.main:app --host 0.0.0.0 --port 8000
调用 POST /api/chat/stream、POST /api/memory/recall 等。见 integrations.md。
安装包(macOS / Windows)
open https://github.com/jaychouya/MemoryAgent/releases
从源码仅启 API
pip install -r requirements.txt
python -m uvicorn src.backend.main:app --host 0.0.0.0 --port 8000
系统要求
- Python 3.11+
- Node.js 18+(仅 Web 控制台)
- 网络连接(用于 API 调用)
架构设计
运行时主路径:会话历史 sessions/*.json + 长期记忆 memories/*.md + index.db(FTS + 持久向量)。src/memory/layers/ 下 Redis/PostgreSQL 实现仅用于测试与未来扩展,见 架构决策。
┌─────────────────────────────────────────────────────────────────┐
│ 前端 (Next.js + Tailwind) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ ChatPanel │ │ MemoryPanel │ │ SettingsPanel │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Agent 核心引擎 (FastAPI) │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Agent Loop │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────┐ │ │
│ │ │ LLM调用 │→│ 工具执行 │→│ Hybrid召回 │→│ CCR+压缩 │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────────┘ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ 工具注册表 │ │ 记忆管理器 │ │ 技能图谱 │ │
│ │ (11个工具) │ │ (4类型记忆) │ │ (networkx) │ │
│ └──────────────┘ └──────────────┘ └──────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
核心模块
src/
├── agent/ # Agent 核心
│ ├── loop.py # Agent Loop (while true 循环)
│ ├── tools/ # 工具系统
│ ├── prompts/ # 动态 System Prompt
│ ├── context/ # 上下文压缩
│ ├── semantic/ # 语义化代码理解
│ └── reflection/ # 执行轨迹抽象
├── memory/ # 记忆系统
│ ├── types/ # 四类型记忆定义
│ ├── storage.py # 文件存储 (markdown + YAML)
│ ├── retrieval.py # Hybrid FTS + 向量 + Rerank
│ ├── provenance.py # L0 证据链
│ ├── persistent_vector.py # 持久化向量
│ ├── quality.py # 记忆质量管理
│ └── vector_store.py # 向量搜索
├── skills/ # 技能知识图谱
└── backend/ # 后端服务
├── main.py # FastAPI 入口
└── api/ # API 路由
API 文档
常用 HTTP API:
| 方法 | 路径 | 用途 |
|---|---|---|
POST | /v1/chat/completions | OpenAI 兼容对话(SDK 零改) |
GET | /v1/models | OpenAI 兼容模型列表 |
POST | /api/webhooks/feishu | 飞书入站事件 |
POST | /api/webhooks/dingtalk | 钉钉入站消息 |
POST | /api/chat | 非流式对话 |
POST | /api/chat/stream | SSE 流式对话 |
GET | /api/memories | 列出用户记忆 |
PATCH | /api/memories/{id} | 修改记忆 |
DELETE | /api/memories/{id} | 删除记忆 |
GET | /api/memory/stats | 记忆统计 |
GET | /api/memory/metrics | 召回质量指标 |
POST | /api/memory/metrics/run-eval | 运行黄金集评估 |
POST | /api/config/quick-setup | 快速保存模型配置 |
发送消息
curl -X POST http://localhost:8000/api/chat \
-H "Content-Type: application/json" \
-d '{"message": "我喜欢 Python", "session_id": "test", "user_id": "user1"}'
快速配置
curl -X POST http://localhost:8000/api/config/quick-setup \
-H "Content-Type: application/json" \
-d '{"provider": "openai", "api_key": "your-key"}'
获取记忆
curl http://localhost:8000/api/memory/stats
FastAPI Swagger 仍保留在 /docs,仅作为本地开发调试入口;README 已覆盖常用接口。
测试
# 运行所有测试
python -m pytest tests/ -v
# 测试结果
# 400+ passed, 7 skipped
技术栈
| 层级 | 技术 |
|---|---|
| 前端 | Next.js 14, TypeScript, Tailwind CSS |
| 后端 | Python 3.9, FastAPI, OpenAI SDK |
| 记忆 | Markdown + YAML, SQLite, 向量搜索 |
| 图谱 | networkx, tree-sitter |
| 测试 | pytest, 400+ 测试用例 |
相关项目
如果你对 AI 记忆系统感兴趣,还可以看看:
- Mem0 - AI 记忆层
- Letta - 长期记忆 AI Agent
- Zep - AI 记忆平台
- Claude Code - Agent Loop 架构灵感
- Cursor - AI 编辑器
- MCP - Model Context Protocol
贡献
欢迎贡献!请遵循以下步骤:
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/your-feature) - 提交更改 (
git commit -m 'Add your feature') - 推送到分支 (
git push origin feature/your-feature) - 创建 Pull Request
许可证
本项目采用 MIT 许可证 - 详见 LICENSE 文件
相关文档
- 第一性原理 × 竞品对照 — Mem0/Zep/Letta 差异与优化路线
- 架构决策 — 侧车边界与读写路径
- Cursor 接入 — 一条命令安装 MCP
- Headroom 思路对照 — CCR 与可选 proxy
致谢
- Claude Code — Agent Loop / 记忆类型灵感
- TencentDB Agent Memory — 分层记忆与证据链思路
- Headroom — 可逆上下文压缩思路
- FastAPI · Next.js · tree-sitter · networkx
// faq
What is MemoryAgent?
具备认知记忆架构的 AI Agent,让 AI 记住你的偏好,越用越懂你 核心特性:四类型记忆系统、跨会话记忆共享、Claude Code 架构、15+ 大模型支持. It is open-source on GitHub.
Is MemoryAgent free to use?
MemoryAgent is open-source under the MIT license, so it is free to use.
What category does MemoryAgent belong to?
MemoryAgent is listed under automation in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/memoryagent)
// retro hit counter
[](https://claudeers.com/memoryagent)
// reviews
// guestbook
// related in Productivity
Agent skills for Obsidian. Teach your agent to use Obsidian CLI and open formats including Markdown, Bases, JSON Canvas.
Open source repository of plugins primarily intended for knowledge workers to use in Claude Cowork
Garry's Opinionated OpenClaw/Hermes Agent Brain
An open-source alternative to Claude Cowork (powered by opencode)