# 独立体验（克隆后）
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

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

详见 docs/integrations.md。

1. 独立对话 — make dev，浏览器里聊天 + 管理记忆（不依赖任何 IDE）
2. MCP 侧车 — Cursor / Claude Code / Cline / Windsurf / 任意 MCP 客户端
3. HTTP API — 飞书、钉钉、自研 Agent、脚本调用同一记忆库

场景 1: 用户告诉 AI 自己的偏好 → AI 记住

场景 2: 新对话 → AI 自动使用记忆，用 Python 写排序函数

不做终端、Git、浏览器自动化；专注 Remember + Align。与 Cursor / Claude Code 互补：它们执行，MemoryAgent 记住你是谁、项目禁忌与决策。

• 记忆 = Markdown + YAML，可用 Obsidian 直接改
• 默认 本地文件 + SQLite，无强制云向量库
• 可选 MEMORYAGENT_API_KEY 保护 HTTP 侧车

• FTS + 持久向量 + Rerank（候选 20 → Top5），长问句 Query Rewrite
• 对话展示 Memory Citation（分数、类型、陈旧提示）
• L0→L1 证据链：原子记忆可追溯到原会话片段（memories/l0/）
• 默认过滤寒暄、临时任务状态和可从代码推导的信息，减少记忆污染
• Recall@5 黄金集评估 + CI 门禁（目标 ≥90%）

bash /path/to/MemoryAgent/scripts/onboard.sh .

自动写入 .cursor/mcp.json、规则「每轮先 recall」、user_id / project_id 由 工作区 + Git 仓库名 推导。MCP v2：recall / store / update / delete / list / export。

• CCR 可逆压缩：大段 tool 输出 落盘 + 类型化预览（JSON 骨架 / 代码截断），memory_retrieve_blob 按需取回
• Mermaid 符号化工作记忆：多步 tool 时注入任务拓扑图
• 五层 ContextCompressor，异步 记忆沉淀（不拖慢首包/尾包）

400+ pytest、流式 SSE、多厂商 LLM 配置、架构决策文档化 → 适合二次开发与私有化部署。

热门 Agent 项目的共性不是功能堆满，而是让用户快速判断“我该怎么接”。MemoryAgent 推荐按下面方式使用：

最小闭环：

用户说出偏好/规则 → MemoryAgent 沉淀 → Agent 召回引用 → 用户可编辑/删除/忘记

MemoryAgent 不做终端、浏览器、Git 自动化；这些交给 Cursor、Claude Code、OpenHands、Aider。它只做一件稀缺能力：把跨会话偏好、禁忌和项目决策变成可控、可解释、可迁移的记忆层。

MemoryAgent 与以下主流工具无缝集成：

# 一键安装到当前项目
bash scripts/onboard.sh .

自动配置：

• .cursor/mcp.json - MCP 服务器配置
• .cursor/rules/memory.mdc - 记忆规则
• user_id / project_id 自动推导

在项目根目录创建 CLAUDE.md：

# 项目规范

使用 Python 3.9+
不要用 mock 数据库
API 截止日期：周五

MemoryAgent 会自动加载并使用这些规范。

记忆文件直接保存为 Markdown：

memories/
├── user/
│   └── user_abc123.md      # 可在 Obsidian 编辑
├── feedback/
│   └── feedback_def456.md
└── MEMORY.md               # 索引文件

用 Obsidian 打开 memories/ 文件夹即可浏览和编辑所有记忆。

不只是简单的"记住对话"，而是结构化的认知记忆：

会话 1: 用户喜欢 Python，讨厌 Java
会话 2: 帮我写排序 → AI 自动用 Python（记住你的偏好）
会话 3: 推荐框架 → AI 推荐 FastAPI（知道你喜欢 Python）

多层策略，兼顾 省 Token 与 可恢复：

详见 Headroom 思路对照、架构决策。

• GET /api/memory/metrics — Recall@5、误注入率、向量条数
• POST /api/memory/metrics/run-eval — 重跑黄金集

记忆以 Markdown 文件存储，可直接在 Obsidian 中编辑：

---
name: user_abc123
description: 用户偏好
type: user
tags:
  - preference
  - python
---
#preference #python

用户喜欢 Python，讨厌 Java

一键切换，无需改代码：

适合：长期偏好、项目禁忌、可审计记忆、Cursor/Claude Code 用户。
不适合：替代 Devin/Cursor 完成端到端交付。

完整矩阵见 docs/integrations.md。

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 → 直接聊。右侧为记忆控制台。

bash /path/to/MemoryAgent/scripts/onboard.sh /path/to/your/project

重载 IDE 的 MCP → 对话中「记住…」→ 新会话验证。Claude Code 加 --claude。

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。

open https://github.com/jaychouya/MemoryAgent/releases

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 路由

常用 HTTP API：

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

如果你对 AI 记忆系统感兴趣，还可以看看：

• Mem0 - AI 记忆层
• Letta - 长期记忆 AI Agent
• Zep - AI 记忆平台
• Claude Code - Agent Loop 架构灵感
• Cursor - AI 编辑器
• MCP - Model Context Protocol

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

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/your-feature)
3. 提交更改 (git commit -m 'Add your feature')
4. 推送到分支 (git push origin feature/your-feature)
5. 创建 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