AI Agent Memory MCP Server

AI Memory MCP Server

与 Agent 无关的持久化记忆，以 MCP 服务形式提供——本地优先：记忆随项目保存在 .aamm/ 中，可由 Claude Code / Qoder / Cursor 共享。

中文 | 日本語

与 Agent 无关的持久化记忆层，以 MCP 服务形式提供。任何 MCP 客户端——Claude Code、Qoder、Cursor——都可以复用它。记忆保存在各项目的 .aamm/ 目录中，并随项目迁移；在同一项目中工作的不同 Agent 共享一个记忆库，并通过 source_agent 标记区分写入者。

架构

• SQLite — 结构化事实来源（CRUD + FTS5 关键词搜索）
• Chroma（嵌入式） — 向量检索，持久化到 .aamm/chroma/
• 嵌入 — 支持任何兼容 OpenAI 的服务（Volcengine / SiliconFlow / OpenAI / 其他服务）；默认使用 Volcengine 的 doubao-embedding-vision
• Markdown 镜像 — 每条记忆也会写入 .aamm/memories/<category>/<id>.md，便于阅读和编辑

三个层通过 id 关联。

记忆类别

category	用途
user	用户偏好（技术背景 / 开发习惯 / 回答风格）
project	项目知识（架构 / 技术栈 / 布局 / 设计决策）
process	工作过程（已解决的问题 / Bug / 调试 / 经验教训）
agent	Agent 协作（已完成的工作 / 交接说明）

安装

从 PyPI 安装：

pip install ai-agent-memory-mcp

从源码安装：

cd ai_agent_memory_mcp
pip install .          # or: pip install -e .   (editable, for development)

需要 Python 3.11+。

配置嵌入服务（任意兼容 OpenAI 的服务）

嵌入层是一个通用的兼容 OpenAI 的客户端——Volcengine / SiliconFlow / OpenAI / 任何兼容服务均可使用。首次运行时，会在 .aamm/config.yml 中生成默认配置；可按需编辑。

字段（.aamm/config.yml 的 embedding 部分）

字段	含义
provider	标签（仅供说明）
model	嵌入模型名称
base_url	兼容 OpenAI 的端点
api_key_env	保存密钥的环境变量名
dim	向量维度（必须与模型匹配）

将密钥放入项目根目录下的 .env，然后编辑 config.yml 的 embedding 部分。

示例

Volcengine doubao-embedding-vision（默认；Agent/Coding Plan 密钥必须使用 Plan 端点 /api/plan/v3——标准端点 /api/v3 会返回 401）

embedding:
  provider: volcengine
  model: doubao-embedding-vision
  base_url: https://ark.cn-beijing.volces.com/api/plan/v3
  api_key_env: VOLCENGINE_API_KEY
  dim: 2048

.env：VOLCENGINE_API_KEY=...

SiliconFlow bge-large-zh（针对中文文本优化）

embedding:
  provider: siliconflow
  model: BAAI/bge-large-zh-v1.5
  base_url: https://api.siliconflow.cn/v1
  api_key_env: SILICONFLOW_API_KEY
  dim: 1024

.env：SILICONFLOW_API_KEY=...

OpenAI

embedding:
  provider: openai
  model: text-embedding-3-small
  base_url: https://api.openai.com/v1
  api_key_env: OPENAI_API_KEY
  dim: 1536

.env：OPENAI_API_KEY=...

其他任何兼容 OpenAI 的服务：只需填写 base_url / model / api_key_env / dim。

切换嵌入模型后，旧向量的维度可能不匹配；请清除 .aamm/chroma/ 并重新执行 remember，或运行 python tests/rebuild_vectors.py。

检索

recall 使用三路融合检索以最大限度提高命中率：

• 向量（权重 0.6）：Chroma 余弦相似度；嵌入基于 title + tags + content 计算，因此标题和标签的信号也会纳入向量
• 关键词（权重 0.25）：SQLite FTS5 trigram
• 标题/标签匹配（权重 0.15）：查询出现在标题中时加 +0.15，出现在标签中时加 +0.075

候选数量会扩展到 top_k*3，再融合筛选至 top_k。如果查询包含 FTS5 特殊字符（.、*、"、- 等），关键词分支会改用 LIKE 子串匹配，而不会报错。

工作日志

除了可搜索的记忆外，aamm 还会维护一份便于人类阅读的工作日志。完成用户请求后，Agent 会调用 journal_entry()，记录用户提出了什么要求、它做了什么，以及是否有未解决的问题。工作日志供人们查看时间线；recall 不会搜索工作日志。只有在需要回溯“过去一次交互中发生了什么”时，才将 search_journal() 作为备用方案。

工作日志写入 .aamm/logs/：

• journal.db — 单个 SQLite 存储（搜索来源，涵盖所有日期）
• YYYY-MM-DD.md — 每天一个 Markdown 文件，采用仅追加的时间线格式

.aamm/logs/
├── journal.db        # search source (all dates)
├── 2026-07-14.md     # per-day timeline
└── 2026-07-15.md

MCP 工具

记忆（8 个）：

• remember(title, content, category, tags?, scope?) — 存储（三方同步，自动生成嵌入）
• recall(query, category?, top_k=5) — 融合检索（向量 + 关键词 + 标题匹配）
• get_memory(id) — 获取一条记忆
• search_memories(category?, tag?, agent?) — 结构化筛选
• update_memory(id, ...) — 更新（重新生成嵌入 + 刷新 md）
• forget(id) — 删除（三方同步）
• list_memories(category?) — 列出记忆
• who_am_i() — 当前 Agent + 项目上下文

工作日志（3 个）：

• journal_entry(question, answer_summary, key_points?, open_question?, session_id?) — 记录一条时间线条目
• search_journal(query, date_from?, date_to?, agent?, limit=10) — 备用的工作日志搜索
• setup_profile(user_name) — 设置用户名（显示在工作日志中）

管理 CLI

python -m ai_agent_memory_mcp.cli init                  # initialize .aamm in the current project
python -m ai_agent_memory_mcp.cli status                # store overview (categories / vectors / md / journal)
python -m ai_agent_memory_mcp.cli export [--dir DIR]    # export all memories to Markdown
python -m ai_agent_memory_mcp.cli sync                  # rebuild SQLite + Chroma from Markdown
python -m ai_agent_memory_mcp.cli check                 # consistency check (db / md / chroma)
python -m ai_agent_memory_mcp.cli journal [--limit N]   # show recent journal entries

接入 Claude Code（用户范围；共享代码，各项目数据独立）

从 PyPI 安装（无需 PYTHONPATH）：

claude mcp add aamm -s user -- python -m ai_agent_memory_mcp --agent claude-code --project-from-cwd

从源代码克隆目录安装，添加 -e PYTHONPATH=<clone dir>\ai_agent_memory_mcp：

claude mcp add aamm -s user -e PYTHONPATH=<clone dir>\ai_agent_memory_mcp -- python -m ai_agent_memory_mcp --agent claude-code --project-from-cwd

Qoder / Cursor 的配置相同，只需更改 --agent。

数据布局

.aamm/
├── memory.db                    # SQLite: structured memories + FTS5
├── chroma/                      # Chroma vector store
├── memories/<category>/<id>.md  # Markdown mirror (editable)
├── logs/
│   ├── journal.db               # work journal (search source)
│   └── YYYY-MM-DD.md            # per-day journal timeline
├── config.yml                   # embedding config
└── profile.json                 # user name

许可证

MIT