具备认知记忆架构的 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.

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

接入总览 · vs Mem0

为什么不是 Mem0？

接入	MemoryAgent	Mem0	单 App 内置记忆
独立对话	✅ Web 控制台	部分托管 UI	仅该 App
IDE / Agent	✅ 任意 MCP 宿主	SDK	通常无
自研软件	✅ HTTP API	✅ API	❌
存储	本地 Markdown	向量云为主	黑盒

一句话：一套本地 Markdown 记忆，Cursor 能用、你自己的 App 也能用，不想接 API 还能直接打开网页聊。

三种用法

详见 docs/integrations.md。

独立对话 — 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+ 测试用例

贡献

欢迎贡献！请遵循以下步骤：

Fork 本仓库
创建特性分支 (git checkout -b feature/your-feature)
提交更改 (git commit -m 'Add your feature')
推送到分支 (git push origin feature/your-feature)
创建 Pull Request

许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

致谢

Claude Code — Agent Loop / 记忆类型灵感
TencentDB Agent Memory — 分层记忆与证据链思路
Headroom — 可逆上下文压缩思路
FastAPI · Next.js · tree-sitter · networkx

⭐ 如果这个项目对你有帮助，请给个 Star！⭐

Platforms	api, web
Operating systems	—
AI compatibility	claude
License	MIT
Pricing	open-source
Language	Python