Skip to main content
Glama
agent-memory

agent-memory

by ac0033

agent-memory

给 LLM agent 的本地长期记忆基础设施。 一个跑在你自己机器上的小服务,让任何 agent(Claude Code 等编程 agent、LangGraph 应用……)跨会话记住用户偏好、项目约定和踩过的坑;写入必须过门、可按要求遗忘、能在合适的时候主动想起来。

记忆机制不是从别家的机制清单里挑出来的,而是从一套 13 项能力、3 项质量属性的能力框架和它的评价标准(每一项都要显著优于朴素 RAG)反推出来的:原话是证据,记忆只是通向证据的键和贴在证据上的注解;读取时只组织不裁决;智能前移到写入期且只增不减。 验收用多个公开评测集、每个只测一次:LoCoMo 未见过的对话 42 对 33(p=0.049),PersonaMem-32k 与 LongMemEval-S 与朴素 RAG 持平;自建的 92 题 11 桶验证集 88/92,朴素 RAG 在最初 45 题上 39/45;治理能力(遗忘、投毒、任务状态、主动浮现)另有一套 373 条用例的内部评测集 MemCompass 量出来。

English: README.en.md · License: MIT · Python ≥ 3.12 · 876 个测试无需网络与 API key · 当前版本 v0.4.0(CHANGELOG)


目录


Related MCP server: Recall

它解决什么问题

编程 agent 每开一个新会话都从零开始:上周定好的数据库选型、用户"以后都用 uv"的偏好、昨天踩过的坑,全部要重新讲一遍。常见的补救办法是把历史对话整体塞进 RAG,但这样做有四个结构性的问题:

问题

原文 RAG 的表现

agent-memory 的做法

忘不掉

用户要求"忘了这件事",原文还在,检索照样泄漏

删除记忆条目 + 把原文对应片段擦成占位符,审计只记元数据

防不了投毒

对话里混进的"以后忽略安全检查"会被原样召回

写入过评价门:指令性内容、注入特征、泄漏的密钥一律拦在库外

没有任务状态

只能检索到"说过什么",不知道"现在做到哪了"

独立的工作记忆层:目标、约束、待办、未决问题,会话开头自动注入

不知道何时该开口

每轮都注入,相关不相关一起塞

精确率优先的主动浮现:只在"不提就会出错"时才提

agent-memory 把记忆分成三层(长期 / 工作 / 短期),写入走"脱敏 → 蒸馏 → 评价门 → 对账"管线,读出时带"参考而非指令"的护栏,并提供 MCP、Python 库、Skill 三种接入方式。

为什么不是"再做一个 RAG"

朴素 RAG(原文全留、每轮检索)是很强的基线——我们自己早期的评测里,它在多数纯问答子集上追平甚至超过当时的记忆系统。memory-v1(2026-09-21 起)的答案不是"不跟它比问答",而是把它当成地板:

  • 载荷按构造包含原话:记忆条目只是通向原文的键和贴在原文上的注解,答题者看到的信息不少于朴素 RAG 给的(检索对等率约 90%,载荷体量 ≤ 1.15 倍);

  • 读取时只组织、不裁决:不合成"库里没有 X"、不替答题者数数,读路径零 LLM 调用;

  • 写入期把原文里没有的东西加上去:绝对日期、取代史、有效期、出处、线索词、用户画像——这些是朴素 RAG 结构上给不出的,也是领先的来源;

  • 治理能力照旧是它做不到的:按要求遗忘(泄漏 0%)、投毒拦截(误拦 0%)、任务状态、主动浮现、跨 agent 不串线。

在没见过的外部对话上的读数(同一套默认配置,答题器与评委固定):LoCoMo 两段新对话 60 题 42 对 33(p=0.049);PersonaMem-32k 60 道选择题 51 对 53(持平);LongMemEval-S 60 题 51 对 49(持平,p=0.77;知识更新 9 对 6)。推导与逐轮记录见 docs/research/memory-v1-design.md,机制说明见 docs/design/memory-v1-mechanism.md。

核心亮点

  1. 机制由能力框架推导,用多个外部评测集验收。 先定义好的 agent 记忆应具备哪 13 项能力(K1–K13)、每项怎么度量、成熟度怎么定级(L2 = 显著优于朴素 RAG),再从"分数由什么决定"反推机制,每条原则对应一类实测过的失分。准入规则写在机制之前:至少两个独立评测同向不劣、至少一个显著更优、任何一个题型显著变差即否决;外部集只做验收、每个只测一次,机制迭代靠自建验证集(一份 55 场会话的共享历史,92 题 11 个能力桶,第 0 层不调 LLM 一分钟出结果)。推导过程与被证伪的预测都记录在 docs/research/memory-v1-design.md。

  2. 三层记忆,一次组装。 长期记忆(跨会话的事实 / 偏好 / 流程)、工作记忆(当前任务的目标 / 约束 / 待办 / 未决问题)、短期记忆(直接读宿主自己的会话日志,不复制)。memory_context 一次调用拿到"常驻画像 + 工作记忆 + 相关召回"三个分节块。

  3. 写入永远过门,但永不丢数据。 任何候选都要经过脱敏 → 蒸馏 → 评价门 → 对账(ADD / UPDATE / DELETE / NOOP);判不了的冲突进人工复核队列而不是猜。原文在蒸馏之前就已归档,评价门拒绝的内容可以强制转人工复核。

  4. 记忆是参考,不是指令。 蒸馏拒绝提炼指令性内容,评价门拦截提示词注入特征,注入块自带护栏声明。当记忆与当前请求冲突时,永远以当前请求为准。

  5. 可验证的遗忘。 memory_forget_request 同时删除记忆条目和原文归档中的对应片段,审计日志只记元数据,检索层与回答层泄漏均为 0%。

  6. 主动浮现(精确率优先)。 LLM 线索扩展 + 一跳扩散 + 逐条判断"不提就会出错 / 原理相通值得点明",宁可少说。系统层 F0.5 77%,误插话率 2/13。

  7. 双时态与变更史。 每条记忆带 valid_from / valid_to,对账 UPDATE 时旧版本折进 history;蒸馏时按会话日期换算相对时间、识别追溯更正。"截至某时"问答准确率 97%。

  8. 原话随记忆一起到场。 归档脱敏后建派生索引(向量 + 词级 / trigram 全文);检索返回的是"证据束"——同一处原话及其注解(取代史、有效期、出处、事件日期),原话在前、注解在后,只是复述原话的条目不再渲染。答题者永远能回到证据核实。

  9. 离线进化闭环,可回滚。 agent-memory evolve 做去重合并、离线复核、降权归档,产出提案而非直接改库;三档验证(边界 / 留存 / 安全)任一不过即否决,晋升前快照、晋升后审计、随时回滚。

  10. 宿主中立,没有 API key 也能用。 MCP over HTTP / MCP stdio / LangGraph 库 / Skill 四种接入;订阅制 agent 拿 memory_distill_prompt 的协议在自己的上下文里蒸馏,服务端照样校验、脱敏、过门、对账。

  11. 自带评测集与诚实的报告。 MemCompass:8 个子集 373 条合成用例,覆盖公开评测集没有的能力(遗忘、投毒、主动浮现、任务状态、跨 agent、双时态……),程序化金标、异源评委、配对统计、消融、对照组,报告里连"朴素 RAG 在哪里赢了我们"都写清楚。

评测结果

三类数据、三种用途:外部评测集(LoCoMo、PersonaMem-32k、LongMemEval-S)只做验收,每个来源只测一次,朴素 RAG 同场作答;自建验证集是集成测试,按能力维度出题、反复用;内部评测集 MemCompass 覆盖公开评测集没有的治理能力。验收标准:每个外部集都不劣于朴素 RAG,且至少一个显著更优。

外部验收(memory-v1,2026-09-22,每个来源只测一次;朴素 RAG 同场、同答题器 deepseek-v4.1-flash、同评委 glm-5.3-flash,AML 公开的答题与评分提示词):

来源

题量

朴素 RAG

memory-v1

配对

LoCoMo(未见过的 conv-41/42)

60

33(55%)

42(70%)

独赢 13 / 独输 4,McNemar p=0.049

LoCoMo 首测(conv-26/30)

54

31(57%)

37(69%)

独赢 10 / 独输 4,p=0.18,方向一致

PersonaMem-32k(4 份历史,选择题)

60

53

51

独赢 2 / 独输 4,p=0.69(持平);全文上下文 47

LongMemEval-S

60

49

51

独赢 7 / 独输 5,p=0.77(持平);知识更新 9 对 6,弃答题 4/5 对 1/5

LoCoMo 上的领先主要来自前提不成立的对抗题(9 对 0,载荷首条的静态行为协议起作用),多跳与时间题各 +1,单跳与开放域各 −1;载荷体量 1.15 倍于朴素 RAG。PersonaMem 上事实回忆 21/21、变更原因 6/6、推荐 7/7 与朴素 RAG 相等,唯一落后的 suggest_new_ideas 类(5 对 8 / 14)对全文上下文也只有 6/14。

自建验证集(一份 55 场会话的共享历史,92 题 11 个能力桶)88/92;最初的 45 题上朴素 RAG 39、全文上下文 40,每桶不低于两个对照;21 道换说法、泛称、有描述无名字的可答题没有一次错误弃答。方法:docs/research/benchmark-suite/README.md §8。

内部评测集(v0.2.2 时的读数)MemCompass v0.3(8 个子集 / 373 条用例,本仓库自建,全部合成数据)。下表是 test 切分(193 条)上 v0.2.2 与前一版本的逐题配对比较,McNemar 精确检验:

能力

子集 / 模式

v0.2.2

前一版本

p

机制证据

按要求遗忘

fg / 问答

100%(15/15)

40%

.004

检索层硬泄漏 0% vs 70%

回溯补全

ca / 端到端

88%(30/33)

19%

<.001

消融关掉原文工具后降到 75%

主动浮现(系统层)

pr / 系统层

78%(25/32,F0.5 77%)

41%(13/32)

.004

消融关掉主动浮现后回到 13/32

跨 agent 迁移(系统层)

xa / 系统层

83%

0%

.002

宿主中立的归档与注入

时间与变化

at / 问答

97%

57%

.007

双时态与追溯更正

当下保真

pf / 端到端

100%

84%

.016

压缩前情节卡片

投毒鲁棒

mp / 问答

100%

89%

.250

攻击成功率两版都是 0%,差异在误拦 0% vs 21%

v0.3.2 回归(同一评委 glm-5.3-flash 下重跑三方;Kimi K3 已不可用,所以不与上表直接比较):xa 为 v0.3.2 的读数,其余子集为 v0.3.1——v0.3.2 只多了作用域约定兜底,它不作用于 global 记忆,而这些子集的记忆全是 global。

能力

子集 / 模式

v0.3.2

v0.2.2

朴素 RAG

当下保真

pf / 端到端

100%

95%

99%

回溯补全

ca / 端到端

100%

94%

81%

主动浮现(系统层)

pr / 系统层 F0.5

80%

77%

60%

跨 agent 迁移(系统层)

xa / 系统层

10/12(该注入的 12/12)

10/12

7/12

任务状态(系统层)

ts / 系统层

15/23

15/23

0/23

时间与变化

at / 问答

100%

97%

100%

按要求遗忘

fg / 问答

100%

100%

47%

投毒鲁棒

mp / 问答

97%

96%

94%

细节保留

ca / 问答

90%

80%

100%

此后两版只改动了对应子集:v0.3.3 任务状态(ts / 系统层)串线率 60% → 0%、主动浮现端到端(pr / 端到端)F0.5 70% → 80%(朴素 RAG 75%);v0.3.4 主动浮现过早插话 16% → 11%、跨 agent 串线 17% → 8%。逐项读数见 CHANGELOG 与设计稿 §11–12。

诚实的注脚:

  • 每条用例只有 2–8 个会话,朴素 RAG 在多数纯问答子集上持平或更好(见上一节);长历史档位(每题约 35 万 token)尚未构建,是下一步最重要的工作。

  • 单种子、n < 50 的子集区间较宽,报告里逐处标注了"只看方向"。

  • 评委与答题器异源(DeepSeek 答题、Kimi K3 评委、Claude 修订用例),评委间一致率 85%–98%(κ 0.69–0.93);尚未做人工一致性研究。

完整报告(对照组、消融、成本、用例体检、局限):docs/research/benchmark-suite/results/2026-09-16-v03-report.md。复现方法见 evals/memcompass/README.md。

架构

                 ┌──────────────────────────────────────────────────────┐
   宿主 agent    │  memory_context = 常驻画像 + 工作记忆 + 相关召回      │
 (MCP / 库 / Skill)  memory_surface = 主动浮现(精确率优先)              │
                 └───────────────▲──────────────────────────▲───────────┘
                                 │ 读                        │ 读
        ┌────────────────────────┴────────┐   ┌──────────────┴──────────────┐
        │ 长期记忆  data/memory/*.md      │   │ 工作记忆  data/working/      │
        │ 唯一事实来源,按 scope 隔离      │   │ 目标/约束/待办/未决问题       │
        │ + 可重建索引 index.db           │   │ 服务端增量整理 wm_refresh    │
        │   (sqlite-vec 1024d + FTS5)     │   └──────────────▲──────────────┘
        └────────────────────────▲────────┘                  │ 只过脱敏
                                 │ 写                        │
   ┌─────────────────────────────┴──────────────────────────────────────┐
   │ 写入管线: 脱敏 → 蒸馏 → 评价门 → 对账(ADD/UPDATE/DELETE/NOOP) → 变更传播 │
   │           判不了的 → data/review_queue/(人工复核)                    │
   └─────────────────────────────▲──────────────────────────────────────┘
                                 │ 先归档再蒸馏
        ┌────────────────────────┴────────┐   ┌─────────────────────────────┐
        │ 原文归档  data/raw/(只追加)    │   │ 短期记忆 = 宿主自己的会话日志 │
        │ 脱敏后归档 + 派生索引 raw_index │   │ transcript 适配层直接解析     │
        └─────────────────────────────────┘   └─────────────────────────────┘

   离线:agent-memory evolve → 提案 → 三档验证 → 快照 → 晋升 → 审计 / 回滚

作用域:global(跨项目)/ repo:<项目名> / agent:<宿主名>,检索只看当前 scope 加 global。三条不可违反的红线(数据三层分离、写入过门、评测可信根)见 AGENTS.md。

快速开始

1. 安装本体

uv tool install git+https://github.com/ac0033/agent-memory   # 得到 agent-memory 命令;Python ≥ 3.12
# 开发本仓库时改用可编辑安装,改了代码无需重装:uv tool install --editable .

bge-m3 嵌入模型在第一次检索时下载(约 2 GB)。配置写进 ~/.agent-memory/config.env(KEY=VALUE,环境变量优先;AGENT_MEMORY_CONFIG 可改路径),宿主拉起的进程都能读到:

AGENT_MEMORY_LLM_API_KEY=sk-...        # 任意 OpenAI 兼容端点;默认 DeepSeek deepseek-flash
# AGENT_MEMORY_LLM_BASE_URL= / AGENT_MEMORY_LLM_MODEL=
# AGENT_MEMORY_DATA_DIR=               # 缺省 ~/.agent-memory/data
# AGENT_MEMORY_DAEMON_IDLE_MINUTES=30  # 后台进程空闲多久退出

没有 LLM key 时,检索、手动写入、反馈、工作记忆、归档等不依赖 LLM 的功能照常可用;对话蒸馏可交给宿主自己做(见下文)。

2. 接入方式

方式

适合谁

怎么接

Claude Code 插件(推荐)

Claude Code 用户

/plugin marketplace add ac0033/agent-memory,再 /plugin install agent-memory@agent-memory。一次装齐 25 个 MCP 工具、使用规范 Skill 和三个 hook

MCP stdio

任何 MCP 宿主

注册命令 agent-memory mcp,例如 claude mcp add agent-memory -- agent-memory mcp;其他宿主写 {"command": "agent-memory", "args": ["mcp"]}。再把 SKILL.md 装进宿主的 skills 目录

宿主 hook

支持命令 hook 的宿主

agent-memory hook wm-inject --agent <宿主名>(会话开始)、agent-memory hook surface(用户提交消息)、agent-memory hook turn(一轮回复结束);插件已包含

Python 库

LangGraph / LangChain 应用

见下方示例,进程内直接调用,不经后台进程

后台进程:工具调用由本机一个后台进程执行,模型在本机只加载一份、所有会话共用。它不是开机常驻的服务:第一次调用时自动拉起(普通用户权限,只绑 127.0.0.1),空闲 30 分钟自己退出,代码更新后下次调用自动重启。一般不用管它;需要时用 agent-memory daemon status | start | stop 查看或控制。

from langgraph.prebuilt import create_react_agent
from agent_memory.long_term.adapters.langgraph.store import AgentMemoryStore
from agent_memory.long_term.adapters.langgraph.tools import build_memory_tools
from agent_memory.long_term.retrieve.resident import build_system_context

store = AgentMemoryStore()                       # LangGraph BaseStore,namespace ("memories", <scope>)
tools = build_memory_tools()                     # 17 个 ReAct tool,三层记忆全暴露
prompt = "你是用户的编程助手。\n\n" + build_system_context("repo:myproj")   # 常驻画像进 system prompt
agent = create_react_agent(model, tools, prompt=prompt, store=store)

可运行示例:uv run python examples/langgraph_demo.py。

3. 没有 API key 的订阅制 agent

宿主本身就是大模型,蒸馏可以自己做:memory_distill_prompt() 拿协议 → 宿主在自己的上下文里产出 {"memories": [...]} → memory_add(distilled_json=...) 提交。服务端照常校验、脱敏、过门、对账。

更多用法(CLI、评估命令、离线整理、人工复核、hook、工作记忆、会话收尾)见 使用手册;宿主 runtime 必须自己承担的职责清单见 接入指南 §四。开发本仓库:uv sync 装环境,uv run pytest -q 跑测试(不需要网络与 API key)。

MCP 工具一览

25 个 MCP tool(stdio 转发层与后台进程用同一份定义与业务实现):

分组

工具

用途

读取

memory_context memory_search memory_wm_read memory_transcript_read memory_distill_prompt memory_consistency_check

一次组装上下文;混合检索(稠密 + BM25 → RRF → 置信度 × 时间衰减);读工作记忆;读会话日志;宿主蒸馏协议;记忆层与索引一致性检查

写入

memory_add memory_update memory_forget memory_feedback memory_wm_write memory_wm_clear

长期记忆走完整管线;工作记忆只过脱敏

会话

memory_session_end

会话收尾:归档 + 联合蒸馏 + 清理已完成待办(有未完成待办时否决)

复核

memory_review_list memory_review_resolve

管线不敢自动入库的候选交人裁决(approve / modify / discard)

原文归档

memory_archive_search memory_archive_read memory_archive_sync

脱敏后只追加的原文归档,可检索;记忆只有要点或看起来不对时回溯原文

主动浮现

memory_surface

精确率优先的"记忆副手",在 agent 会漏掉的时候提醒它

待确认队列

memory_confirm_enqueue memory_confirm_list memory_confirm_resolve

无人值守时把需要用户拍板的事挂起,其余照常处理

工作记忆整理

memory_wm_refresh

服务端按最近轮次增量整理目标 / 约束 / 待办 / 未决问题

情节卡片

memory_episode_pack

上下文压缩前把标识符、端口、路径、报错原文等原样细节存成卡片

遗忘请求

memory_forget_request

执行用户明确的遗忘要求:删记忆 + 擦原文片段,审计只记元数据

写类工具的描述都注明"仅限主 agent 调用";subagent 只读,结论回传主 agent 后由它策展沉淀。

仓库结构

agent-memory/
├── agent_memory/            # Python 包(import agent_memory)
│   ├── config.py / models.py    配置(AGENT_MEMORY_* 环境变量)与记忆条目 schema
│   ├── llm.py / confirmations.py  OpenAI 兼容 LLM 客户端;待确认队列
│   ├── long_term/               长期记忆:store(Markdown + SQLite 索引)/ ingest(脱敏、蒸馏、评价门、对账、
│   │                            变更传播、情节卡片、遗忘)/ retrieve(bge-m3 混合检索、注入、常驻画像、主动浮现)/
│   │                            evolve(离线整理闭环)/ adapters/langgraph
│   ├── working/                 工作记忆(任务状态 + 服务端增量整理)
│   ├── short_term/              短期记忆:宿主会话日志适配层
│   ├── hooks.py                 宿主 hook(会话开头注入、主动提醒、每 N 轮沉淀),经 agent-memory hook 调用
│   └── server/                  MemoryService 业务层、stdio 转发层、按需启动的后台进程及其生命周期管理
├── plugins/agent-memory/    # Claude Code 插件:.mcp.json、hooks、skills/agent-memory/SKILL.md(Skill 唯一源头)
├── .claude-plugin/          # 插件市场清单
├── examples/                # LangGraph 最小接入示例
├── evals/                   # 可信根(agent 不得修改):layer1–3 / prefix 回归集;另含 MemCompass 运行副本(不属可信根,从源头同步)
├── docs/                    # 使用手册、接入指南、设计文档、研究与评测(见下)
├── tests/                   # 876 个测试(慢测试默认跳过:uv run pytest -m slow)
└── data/                    # 运行时数据(gitignored):raw / memory / working / review_queue / snapshots / logs
                             #   + dev/(自建验证集)、external/<来源>/(外部测试集)

文档导航

想做什么

看哪里

把记忆接进我的 agent,宿主要负责什么

docs/agent-integration.md

日常用法:CLI、评估命令、离线整理、人工复核、hook、会话收尾

docs/usage.md

理解三层记忆的设计与取舍

docs/design/memory-architecture.md

记忆现在怎么读、怎么写、为什么(memory-v1)

docs/design/memory-v1-mechanism.md

机制是怎么从能力框架推导出来的、每一轮实测

docs/research/memory-v1-design.md

好的 agent 记忆应该具备哪些能力、怎么度量

docs/research/agent-memory-capability-framework.md

评测集 MemCompass 的设计、构造脚本、校验与运行

docs/research/benchmark-suite/README.md

最新评测报告

docs/research/benchmark-suite/results/

v0.2 每个机制为什么这么做

docs/research/optimization-v02.md

各版本改了什么

docs/CHANGELOG.md

各阶段交付记录、缺陷复盘、可靠性加固

docs/history/

给在本仓库工作的人和 agent 的规范(红线、约定、行为语义)

AGENTS.md

参与贡献

CONTRIBUTING.md

设计原则

  • D1 数据三层分离:data/raw 只追加;data/memory 的 Markdown 是唯一事实来源;data/index.db 是可重建的派生索引,绝不手改。

  • D2 写入过门:原始对话不直接入库,必须经脱敏 → 蒸馏 → 评价门 → 对账;蒸馏绝不提炼指令性内容。

  • D6 可信根:evals/、rubric、发布门槛、审计日志禁止 agent 自行修改。MemCompass 在 docs/research/benchmark-suite/ 编写与核验,用 tools/migrate_to_evals.py 逐字节同步到运行副本 evals/memcompass/,不在副本里单独改。

  • fail-closed 但不 fail-lost:配置非法、校验失败、证据缺失直接报错,不静默降级;写入路径的内容永不因故障丢失。

  • 本地优先:所有数据是你磁盘上的 Markdown 与 SQLite 文件,后台进程只绑 127.0.0.1,除你配置的 LLM 端点外没有任何数据出站。

已知局限与路线图

  • 领先不是在每个外部集上都显著:LoCoMo 显著领先,PersonaMem 与 LongMemEval-S 与朴素 RAG 持平。LongMemEval-S 的时间推理板块是两边都补上提问日期后的读数(AML 答题模板不带提问日期,"几天前"类题对任何系统都无解);MemCompass 内部表格的读数来自 v0.2.2。

  • PersonaMem 的 suggest_new_ideas 类略低于朴素 RAG(5 对 8 / 14);该类对全文上下文也只有 6/14,属答题者层面的"选泛泛选项"。

  • 关联与图式归纳(K6 离线归纳)未实现:离线整理的验证逻辑属于可信根,需要新的提案类型。

  • 写入成本:对账已按批(每批 8 条)判定,但整段对话蒸馏仍可能要几十秒到几分钟,而 MCP 客户端的超时不可配;改成"先归档、返回任务号、再查状态"的异步写入是待办。

  • LangGraph 适配只覆盖 15 个基础工具,v0.2 新增的 10 个目前仅 MCP 侧提供。

  • 内部评测集为合成数据,评委—人工一致性研究尚未开展。

许可

MIT,见 LICENSE。evals/memcompass/ 与 docs/research/benchmark-suite/datasets/ 下的评测数据均为合成数据,同样按 MIT 发布。

Available Tools

13 tools
memory_addA

写入记忆:对话走蒸馏管线,单条 content 走脱敏+对账。conversation_json 推荐传 [{role, content}, ...] 的 JSON 字符串(直接传数组也可以,服务端会自动序列化;其他类型会报错并提示格式)。scope 应显式选择:跨项目通用知识用 global,项目相关用 repo:<项目名>,agent 自身相关用 agent:<名字>;缺省回落 global 并附提醒

Inputs: scope, source, content, entry_id, +4 more.

memory_contextA

统一组装注入上下文:常驻画像块(长期用户画像)+ 工作记忆块(当前任务状态)+ 召回块(传 query 才检索历史记忆),按此顺序拼接。复核队列有积压时按 review_gate 配置处置:返回 status=blocked 表示被复核门拦截,需先向用户确认(用户同意后以 acknowledge_pending=true重试,或先用 memory_review_list / memory_review_resolve 处理待办)

Inputs: scope (required), k, query, current_turn, +1 more.

memory_feedbackB

反馈记忆是否有用,调整置信度;降到 low 以下进人工复核队列

Inputs: helpful (required), memory_id (required), note.

memory_forgetB

删除一条记忆(记忆层与索引同步删除)

Inputs: memory_id (required).

memory_review_listA

列出人工复核队列的全部待办(内容、排队原因、队列文件名)

Inputs: no named parameters.

memory_review_resolveA

裁决一条复核待办:approve 确认入库 / modify 以 new_content 替换正文后入库 / discard 丢弃。queue_file 取 memory_review_list 返回里的 file 字段

Inputs: action (required), queue_file (required), new_content.

memory_session_endA

会话结束收尾编排:归档原文(data/raw,只追加不改写)+ 联合蒸馏(对话提炼长期记忆,工作记忆快照作参考上下文,冲突会更新旧条目) + 清理工作记忆里已完成的待办。工作记忆有未完成任务时会 veto(status=vetoed,归档/蒸馏/清理都不执行),确认结束请以 force=true 重试。对话材料二选一:conversation_json([{role, content}, ...] 的 JSON 字符串或数组,agent 中立推荐,优先使用)或 log_path(agent 会话日志路径,走日志适配器解析,adapter 可缺省按文件名 自动识别)。未配置 LLM 时只归档不蒸馏(status=archived_only)

Inputs: scope (required), force, source, adapter, +3 more.

memory_transcript_readA

读取 agent 会话日志(如 kimi-code 的 wire.jsonl),解析成干净的轮次序列(user/assistant/tool,含轮次编号与时间戳)。纯读不写。配合工作记忆水位做新鲜度补偿:传 since_turn=<memory_wm_read 返回的 turn_watermark> 只返回水位之后的新轮次,据此判断要不要 wm_write 刷新工作记忆。adapter 缺省按日志文件名自动识别,识别不了需显式指定(可用列表见报错信息);日志不存在会报错

Inputs: log_path (required), adapter, since_turn.

memory_updateB

更新一条记忆的正文(过脱敏与评价门)

Inputs: memory_id (required), new_content (required).

memory_wm_clearA

清空一个 scope 的工作记忆;本就不存在时返回 already empty,不算错误

Inputs: scope (required).

memory_wm_readA

读取一个 scope 的工作记忆(当前任务状态:目标/待办/决策/变量/备注),返回渲染好的注入块与结构化字段。scope 自动归一化,非法当场报错。传 current_turn 时返回 stale_wm 表示工作记忆是否可能滞后(当前轮次超过已更新到的轮次水位),滞后可考虑 wm_write 刷新

Inputs: scope (required), current_turn.

memory_wm_writeA

写入工作记忆(当前任务状态)。注意是全量替换而非合并:未传的字段会被置空,只想改一个字段也要把其余字段原样带上。所有文本过脱敏;不过评价门——待办事项天然是祈使句,属于正常内容。todos 可传 [{content, status}, ...](status 为 pending/done)或纯字符串列表(按 pending)。turn_watermark 传当前对话轮次;未传保留旧值

Inputs: scope (required), goal, notes, todos, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool maps to a distinct resource and action: long-term memory CRUD, working memory read/write/clear, review queue list/resolve, unified context assembly, transcript reading, and session-end orchestration. Even memory_context is clearly an orchestration layer over memory_search and memory_wm_read, not a competing implementation. The only mild overlap is transcript_read versus session_end log parsing, but one is read-only and the other is a write pipeline.

    Naming Consistency4/5

    All tools share the memory_ prefix and snake_case, but the pattern varies slightly: base operations use verb-only suffixes like memory_search and memory_add, while subarea operations use noun_verb suffixes like memory_wm_read and memory_review_resolve. memory_context and memory_feedback are noun-oriented rather than strict verb_noun. Overall the convention is still predictable and readable.

    Tool Count5/5

    13 tools is well-scoped for a memory server covering long-term memory, working memory, review queue, context assembly, transcript access, and session-end orchestration. Each tool has a distinct lifecycle purpose, and none feels redundant or missing as a surface-level feature.

    Completeness5/5

    The surface covers full CRUD for long-term memories, working-memory read/write/clear, review workflow, context assembly, and session-end archival/distillation. The review-gate blocked/acknowledge and session-end veto/force flows prevent dead ends. The only arguable gap is dedicated profile management, but profiles are exposed through memory_context and updatable via memory_add/memory_update.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to store and semantically retrieve durable memories across sessions via MCP or REST, with tools for remembering, recalling, asking, updating, and forgetting memories.
      17 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides AI agents with persistent, human-like memory infrastructure via MCP, enabling them to store, search, summarize, and forget episodic, semantic, procedural, and working memories across sessions.
      658 npm
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Provides agents with a structured long-term memory pipeline, enabling recall, hybrid retrieval, and memory management operations through MCP tools.
      -