convez.ai
AgenteAutomaçãoAvançado
jaychouya

MemoryAgent — Sistema de Memória para AI Agents

jaychouya/MemoryAgent

Memória de longo prazo para Cursor/Claude Code que aprende suas preferências

Ver no GitHub
BomPluginScore · de 0 a 100

Agent de IA com arquitetura de memória cognitiva que aprende e retém suas preferências e contexto do projeto. Implementa um sistema de 4 tipos de memória com recuperação via RAG, compatível com Cursor, Claude Code e +15 modelos de linguagem, mantendo dados localmente.

Instalação

$npx convez-ai jaychouya/MemoryAgent

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
61
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 5 meses
Versão
v1.0.1
Issues abertas
0
Contribuidores
1

Casos de uso

  • Manter contexto de projeto em Cursor/Claude Code
  • Reter preferências de codificação e guidelines entre sessões
  • Recuperar decisões arquiteturais e regras do projeto via IA
  • Documentar dinamicamente padrões e proibições de projeto

Veredito

Solução bem arquitetada para memória persistente de AI Agents, com suporte MCP native para Cursor e Claude Code. Código robusto (400+ testes), mas requer Python/FastAPI para instalação e demanda curva de aprendizado pelo sistema de 4 tipos de memória.

README

A tradução para o português deste README ainda está na fila.

MemoryAgent — AI Agent 长期记忆系统 | Local Memory for Cursor & Claude Code

🧠 AI Agent 记忆系统 — 让 Cursor / Claude Code / ChatGPT 越用越懂你 | 本地优先 | Obsidian 兼容 | RAG 记忆检索

Python FastAPI Next.js License Tests MCP

每次新会话都要重讲偏好?MemoryAgent 为 AI Coding Agent 提供长期记忆,支持 RAG 检索、向量搜索、记忆老化警告——数据留在本地,隐私可控。

核心优势 • 功能亮点 • 快速开始 • Cursor 集成 • Claude Code 集成 • 架构设计


演示

场景 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/install-sidecar.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 与以下主流工具无缝集成:

工具/框架集成方式说明
CursorMCP 协议一键安装,自动配置规则
Claude CodeCLAUDE.md六层级配置体系
ObsidianMarkdown 文件记忆直接在 Obsidian 编辑
LangChainAPI 兼容可作为记忆层使用
FastAPI原生支持后端框架
Next.js原生支持前端框架
SQLite索引存储快速检索
OpenAI API多厂商支持兼容所有 OpenAI 格式 API
MCP 协议完整实现支持所有 MCP 工具
Docker可选部署支持容器化部署

与 Cursor 集成

# 一键安装到当前项目
bash scripts/install-sidecar.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_blobCCR 压缩后取回完整 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+ 大模型支持

一键切换,无需改代码:

厂商模型
OpenAIGPT-4, GPT-4o, o3, o4-mini
阿里云百炼qwen-max, qwen-plus, deepseek-v4-pro
小米 MiMomimo-v2.5-pro, mimo-v2.5
智谱 GLMglm-5.1, glm-5, glm-4-plus
DeepSeekdeepseek-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 完成端到端交付。


快速开始

方式一:一键安装(推荐)

macOS:

# 下载 DMG 安装包
open https://github.com/jaychouya/MemoryAgent/releases

Windows:

# 下载 ZIP 安装包
Start-Process "https://github.com/jaychouya/MemoryAgent/releases"

方式二:从源码运行

# 克隆仓库
git clone https://github.com/jaychouya/MemoryAgent.git
cd MemoryAgent

# 安装后端依赖
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# 安装前端依赖
cd frontend && npm install && cd ..

# 启动
python src/main.py

如需体验 Web UI,本地启动成功后打开 http://localhost:3000,在「配置」里填写模型 API Key。只接入 Cursor / Claude Code 时可跳过 Web UI,直接使用下面的侧车安装方式。

方式三:Cursor / Claude Code 侧车(一条命令)

在你的业务项目目录执行(将路径换成本仓库位置):

bash /path/to/MemoryAgent/scripts/install-sidecar.sh .

自动写入 .cursor/mcp.json、规则「每轮先 memory_recall 再回答」、记忆目录 .memoryagent/memories/。user_id / project_id 由工作区与 Git 仓库名 自动推导。详见 Cursor 接入。

系统要求

  • Python 3.11+
  • Node.js 18+
  • 网络连接(用于 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/api/chat非流式对话
POST/api/chat/streamSSE 流式对话
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

贡献

欢迎贡献!请遵循以下步骤:

  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 文件


相关文档

致谢


⭐ 如果这个项目对你有帮助,请给个 Star!⭐

Star History Chart

Ver o original no GitHub

Bom para

Relacionados