Skip to main content
Glama

human-memory · 类人脑记忆

给 AI 装一套像人脑的记忆:重要的记牢,日常的会淡,被提起才想起,可以手动抢救。

零第三方依赖、纯本地、单文件 SQLite。

第一次用?看 TUTORIAL.md(5 分钟上手 + 场景化用法 + 常见问题)。

现在的 AI 记忆要么全量塞上下文(很快撑爆),要么粗暴摘要(压缩后没有主次)。这个项目试着按人脑的方式处理:不同的记忆有不同的权重和寿命,遗忘不是删除,是沉下去。


它和现有方案的区别

mem0

MemoryOS

本项目

记忆分主次

部分(有层级、无权重)

✅

✅ 11 种类型 + 七因子权重

会遗忘

❌ ADD-only,只增不减

部分(只升温)

✅ 按类型分半衰期

遗忘后可唤醒

—

—

✅ 休眠记忆被线索命中自动唤醒

手动抢救

❌

❌

✅ 钉住 / 手动唤醒

情绪建模

—

—

✅ 效价 × 唤醒度两维

时间维度

—

—

✅ 余波期 / 心结 / 连续低迷

Related MCP server: Memorium

核心机制

  1. 记忆分主次:写入时按七因子打分(自我参照、情绪冲击、社会关系、身份目标、状态持续、新奇、细节),偏好类 0.81 分,日常待办 0.35 分。

  2. 分类型衰减:心结近乎不衰减(36500 天)、身份十年、偏好一年、事件十天。情绪冲击强的翻倍。

  3. 休眠不删除:active / dormant 状态,沉下去但内容还在,被线索命中会自动唤醒。

  4. 情绪两维:效价(-11)× 唤醒度(01),记忆强度看 |效价| × 唤醒度——暴怒和狂喜都记得牢,“有点烦”和“还行”都不留痕。

  5. 时间维度:高冲击事件有余波期(3~11 天);赌气、冷战记为“心结”,靠时间 + 多次表达 + 状态转正多路证据才消退,一句话不够。

快速开始

需要 Python 3.10+,不需要装任何包。

git clone https://github.com/zyj52742-cloud/human-memory.git
cd human-memory

# 记一句话
python memcli.py add "我讨厌香菜,闻到就想吐"

# 换一天再问
python memcli.py recall "我讨厌什么"

# 看情绪轨迹
python memcli.py mood

跑测试:

python selftest.py       # 75 项断言
python mcp_test.py       # MCP 协议 9 项
python bench.py          # 1 万条记忆性能

三种用法

1. 命令行(最简单)

python memcli.py add "用户原话"
python memcli.py recall "当前话题"
python memcli.py mood
python memcli.py list
python memcli.py explain 3      # 看第 3 条为什么是这个分

2. 作为 AI skill(推荐,零配置)

把仓库里的 skills/memory/ 复制到你的 AI 技能目录(例如 ~/.dsh/skills/memory/),AI 读到 SKILL.md 后会自己决定何时记忆、何时召回。

数据独立存在 ~/.human-memory/memory.db,skill 升级不会丢记忆。

3. 作为 MCP 服务(给 Claude Desktop / Cursor 等)

{
  "mcpServers": {
    "human-memory": {
      "command": "python",
      "args": ["<绝对路径>/mcp_server.py"]
    }
  }
}

提供 14 个工具:remember / recall / list / pin / sleep / wake / stats / alias / explain / mood / update / delete / resolve / export。

评分体系

重要度(写入时算一次)

0.25 基础
+0.28 自我参照(关于"我")
+0.30 情绪冲击(|效价| × 唤醒度)
+0.12 社会关系(家人、伴侣)
+0.10 身份目标
+0.10 状态持续(疲惫、低落)
+0.08 新奇意外
+0.05 细节丰富

召回(每轮实时)

0.45×相关性 + 0.25×重要度 + 0.12×时近性 + 0.10×权重 + 0.08×情绪冲击
休眠 ×0.35;钉住 +0.25;相关性 < 0.10 且没钉住 → 丢弃

实测

  • 1 万条记忆:召回 10–45 ms,写入 12 ms/条,库约 20 MB

  • 四轮对话注入约 39 tokens,全量注入需 144,省 73%

  • 自动化测试 75 项 + MCP 协议 9 项

已知限制(诚实说明)

  1. 抽取是规则版:靠约 95 个情绪词 + 规则,识别不了“说不上来哪里不对”这类隐性表达。

  2. 本地小模型不可用(实测):在 RTX 4060 8 GB 显存 + 16 GB 内存的机器上,qwen2.5 的 1.5B 能跑但会照抄示例,3B/7B 输出退化成一串重复数字。大显存机器可能不同。

  3. 可接外部 API:extractor.py 支持任何 OpenAI 兼容接口,配三个环境变量即可;失败自动回退规则版,不会丢记忆。

  4. 权重是先验值:七因子权重有心理学依据的排序,但具体数字没拿大规模真实对话调过。tune.py 可以做自动调参。

  5. 中文按 2-gram 切词:单字情绪词(累/怕/烦)已特殊处理,但跨词表达仍可能漏召回。

  6. 不做复杂的记忆冲突仲裁:只做“同对象 + 态度反转 → 旧的标记为被取代”,不做时效推理。

文件

├── scoring.py          评判标准:情绪词典、七因子、类型、衰减、心结
├── memory_core.py      引擎:存储、状态机、召回、情绪分析、迁移、导入导出
├── extractor.py        抽取层:规则版 / 模型版(可切换、失败自动回退)
├── memcli.py           命令行入口
├── mcp_server.py       MCP 服务(14 工具)
├── chat_play.py        交互式体验
├── skills/memory/      可直接安装的 AI skill
├── selftest.py         75 项断言
├── mcp_test.py         MCP 协议验收
├── bench.py            1 万条性能测试
├── tune.py             召回参数自动调优
├── ARCHITECTURE.md     架构说明
└── data/               记忆库(已 gitignore)

许可

MIT

Available Tools

14 tools
memory_aliasB

添加同义词映射,让召回不漏(如 香菜 ↔ 芫荽)。

NameRequiredDescriptionDefault
aliasYes同义词
canonicalYes标准词

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden for what is a write/mutation tool. It says nothing about persistence scope, whether an existing mapping is overwritten, what happens on duplicate canonical/alias pairs, or required permissions — only the intended benefit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence: verb first, purpose second, example last. Nothing is redundant, though the example could be dropped without loss of meaning for an agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an annotation-free mutation tool with no output schema, the definition should describe at minimum whether the mapping persists across memory_recall and whether conflicts overwrite. Both are missing, leaving the agent unable to predict side effects of the call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%: canonical (标准词) and alias (同义词) are already documented in the schema. The description's 香菜 ↔ 芫荽 example reinforces the direction of the mapping but adds no constraints (length, normalization, direction rule) beyond the schema — baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb (添加/add) plus resource (同义词映射/synonym mapping) and illustrates it with a cilantro↔coriander example, so the effect is unambiguous. No sibling in the list handles aliases, so no differentiation is strictly needed, but the description never explicitly says that.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The clause 让召回不漏 ('so recall doesn't miss') hints at the motivating use case (improving memory_recall coverage), which is genuine implied guidance. It does not state when to prefer this over memory_remember/memory_update, nor any exclusion such as when an alias already exists.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_deleteA

删除一条记忆。默认软删除(仍可查到),hard=true 才彻底删除。

NameRequiredDescriptionDefault
idYes记忆 id
hardNo是否彻底删除,默认 false

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does disclose the single most important behavioral trait: the default is a soft delete whose record remains queryable, and only hard=true destroys it. It stops short of saying whether soft-deleted memories surface in memory_list/memory_recall or whether the operation is reversible.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, zero filler, and the default behavior is front-loaded before the opt-in destructive flag. Nothing could be removed without losing meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A two-parameter tool with full schema coverage and no output schema needs little more than a clear statement of destructive semantics, which this provides. The remaining gap is what a soft-deleted memory means operationally for the read-side sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented in the schema. The description reinforces the `hard` semantics and its default, but adds no format, range, or id-resolution detail beyond what the schema states, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('删除一条记忆') and immediately scopes it into two modes (soft vs. hard). It does not name or contrast any sibling such as memory_update or memory_resolve, so an agent must infer the boundary itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the decision rule for the two modes ('默认软删除' vs. 'hard=true 才彻底删除'), which is genuinely useful guidance. However, it gives no when-not-to-use condition, no prerequisites (e.g. whether the id must be active), and no pointer to an alternative sibling tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_explainA

查看某条记忆为什么是这个重要度(六个因子的明细)。

NameRequiredDescriptionDefault
idYes记忆 id

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full behavioral burden. '查看' (view) implies a read-only, side-effect-free operation and the description usefully discloses the shape of the result (six-factor breakdown), but it says nothing about permissions, what happens if the id is unknown, or whether the computation is expensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with the core purpose stated first and the parenthetical output hint second; no filler. It is short enough that the only slight cost is that the parenthetical is the sole clue about what is returned.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read-only introspection tool with no output schema, the description covers both input intent (which memory) and output shape (six-factor importance breakdown), which is the key missing piece. Error behavior for an invalid id is the only notable gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single 'id' parameter is already documented as '记忆 id' in the schema. The description adds no format, range, or sourcing details beyond that, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: '查看某条记忆为什么是这个重要度' (view why a given memory has this importance level), and adds that the result is a six-factor breakdown. This clearly distinguishes the tool from siblings such as memory_stats (aggregate) and memory_recall (content retrieval), though it does not name those siblings directly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The intent (explain an importance score) implies when to use the tool, but there is no explicit guidance on when to prefer it over memory_stats or memory_recall, and no prerequisites or exclusions are stated. Usage is inferable rather than spelled out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_exportC

把记忆导出成 JSON 备份文件。

NameRequiredDescriptionDefault
pathYes导出文件路径
profileNo只导出某个角色,可省略

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It says a file is written but not whether an existing file at 'path' is overwritten, what permissions are needed, whether the export is atomic, or how long it takes on large stores—critical side-effect details for a write-to-disk tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler. It is efficient, though the terseness is part of why other dimensions fall short.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations, no output schema, and no explanation of return value, overwrite semantics, or scope of the exported data, the definition does not give an agent enough to call this safely and predictably.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both 'path' and 'profile' are already documented in the schema. The description adds no extra meaning (e.g., whether 'profile' scoping changes the output structure or is recorded in the file), so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource+output format: exporting memories into a JSON backup file. An agent can distinguish it from memory_recall/memory_list (read queries) by the 'backup file' outcome, but the description never names a sibling or explicitly contrasts itself with them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The word '备份' implies a backup scenario, but there is no explicit when-to-use, when-not-to-use, or alternative routing (e.g., use memory_recall for querying, memory_export only for durable copies). Usage must be inferred from the name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_listC

列出记忆条目(含休眠中的),用于查看记忆库全貌。

NameRequiredDescriptionDefault
limitNo最多列几条,默认 30
statusNo筛选状态,可省略表示全部
profileNo角色/用户分区,默认 default

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden, and it only discloses that dormant entries are included. It says nothing about read-only semantics, ordering, whether a default limit truncates results, or what the response looks like. For a no-annotation tool this leaves significant behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence with the resource and scope front-loaded and no filler. It is efficient, though its brevity is part of why other dimensions are thin.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With three optional parameters, no annotations, and no output schema, the description should say more about what comes back and how truncation/ordering behaves. As written, an agent knows it lists entries including dormant ones but little else needed to call it confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so limit, status, and profile are already fully documented in the schema, which sets the baseline at 3. The description's mention of "含休眠中的" loosely relates to the status filter but adds no syntax, defaults, or interaction detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a concrete verb and resource ("列出记忆条目") and adds scope (includes dormant entries), so the basic action is clear. However, it never distinguishes itself from close siblings such as memory_recall, memory_stats, or memory_export, all of which could plausibly also 'view' memory. An agent must infer from the name alone which one to pick.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"用于查看记忆库全貌" implies a browsing/overview use case, which is a reasonable hint about when to use it. But there is no explicit when-not guidance and no named alternative (e.g., use memory_recall for targeted lookup, memory_stats for counts), leaving the choice to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_moodB

查看近期情绪轨迹:连续低迷天数、趋势、未化解的心结、仍在余波中的事件。

NameRequiredDescriptionDefault
daysNo回看多少天,默认 14
profileNo角色/用户分区,默认 default

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It implies a read-only view operation and names the reported dimensions, but does not disclose permissions, data scope, rate limits, privacy behavior, or whether it triggers any side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single front-loaded sentence that immediately states the tool's purpose, followed by a compact list of reported aspects. There is no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description explains the kinds of outputs an agent will get, which is useful because there is no output schema. However, with no annotations and only implied usage guidance, it does not fully cover behavioral context such as safety, permissions, or when this tool should be preferred over related memory tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (days and profile) are already documented with defaults. The description does not add syntax, constraints, or meaning beyond the schema, making the baseline score of 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: "查看近期情绪轨迹" (view recent emotional trajectory), and lists the concrete aspects it reports. It is clearly distinct from general memory recall/list tools, though it does not explicitly name or contrast with sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives no guidance on when to use this tool versus alternatives such as memory_recall, memory_list, or memory_stats. Usage is only implicitly suggested by the name and description, with no exclusions or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_pinA

钉住/取消钉住一条记忆。钉住的记忆永不沉底,每次召回都会考虑它(手动抢救)。

NameRequiredDescriptionDefault
idYes记忆 id
pinnedNotrue 钉住,false 取消,默认 true

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It does disclose the key behavioral consequence — pinned memories never sink and are always considered during recall — and the word 取消 makes clear that pinning is reversible. It still omits side effects such as what happens if the id does not exist, whether the operation is idempotent, or what the call returns.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with zero filler: the action comes first and the behavioral rationale follows. Every clause adds information, and the parenthetical is a compact usage hint.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter mutation with no output schema and no annotations, the description covers the effect but leaves gaps around failure modes and return behavior. Nothing incorrect is present, but more edge-condition coverage would be needed to call it complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the schema already explains both `id` and `pinned`, including the default of true. The description adds no parameter-level detail beyond that, which is the expected baseline of 3 when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb pair (pin/unpin) and the resource (a memory), so the agent immediately knows the operation. It does not explicitly distinguish itself from nearby siblings such as memory_update or memory_alias, which keeps it below a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The parenthetical '手动抢救' (manual rescue) implies the situation in which this is appropriate — a memory that would otherwise sink. However, there is no explicit when-not condition, no mention of alternatives such as memory_update, and no statement about prerequisites (for example, the id must belong to an existing memory).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_recallA

按当前话题召回相关记忆(只返回少量高度相关的,不返回全部历史)。

NameRequiredDescriptionDefault
queryYes当前用户说的话或话题
top_kNo最多返回几条,默认 5
profileNo角色/用户分区,默认 default

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It does disclose a genuine behavioral trait — result set is deliberately truncated to a few highly relevant items rather than full history — but says nothing about ranking method, permissions, or response shape for a read tool with a 3-param surface.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One compact sentence that front-loads the action and parenthesizes the scope constraint. No filler, no restatement of the name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 3 simple parameters, full schema coverage, and no output schema, the description supplies the one thing the schema cannot: that results are a small relevant subset, not history. Missing details like relevance ranking or whether results are deduplicated are minor at this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so each parameter is already documented (query, top_k default 5, profile default 'default'). The description only adds the framing that query is the current topic, which is marginal value beyond the schema — baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('召回相关记忆') plus a scoping constraint ('只返回少量高度相关的,不返回全部历史') that implicitly distinguishes it from sibling list-style tools such as memory_list. It stops short of naming an alternative sibling explicitly, so it lands at 4 rather than 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase '按当前话题' implies the trigger condition (there is an active topic/query), but the description never states when to prefer this over memory_list, memory_wake, or memory_explain. Usage is inferable rather than instructed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_rememberA

把一条值得长期记住的信息写入记忆库(分主次存储,重复内容会强化而非重复)。

NameRequiredDescriptionDefault
kindNo记忆类型,可省略,自动判断
entityNo涉及的人或物,可省略
contentYes要记住的内容,一句自然语言
profileNo角色/用户分区,默认 default
importanceNo重要度 0~1,可省略,自动估算
trigger_termsNo唤醒线索词,被提到时更容易想起,可省略

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry behavioral burden; it does add real value by disclosing that storage is split into primary/secondary tiers and that duplicate content reinforces rather than duplicates. However, it omits permissions, whether writes are reversible, and what the agent gets back after storing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence that states the purpose first and the non-obvious dedup/reinforcement behavior second. No filler or redundant restatement of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a six-parameter write tool with full schema coverage and no output schema, the description covers the essential semantics including the surprising merge-on-duplicate behavior. Only the lack of any statement about side effects on near-duplicate or conflicting memories keeps it from a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all six parameters including the kind enum and importance range. The description adds only the duplicate-reinforcement behavior tied to content, which does not meaningfully extend per-parameter meaning, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (写入记忆库 / write into memory store) and scopes it to information worth remembering long-term, which distinguishes it from read-oriented siblings like memory_recall and memory_list. It does not explicitly differentiate from the closer sibling memory_update, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies when to use it ('值得长期记住的信息'), giving a usable criterion, but never names alternatives such as memory_update for existing entries or memory_pin for emphasis. The duplicate-handling note hints at usage but no explicit when-not guidance is present.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_resolveA

人工强制标记某个心结已化解。慎用:正常情况应由时间、表达、状态多路证据自然消退。

NameRequiredDescriptionDefault
idYes记忆 id

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It does disclose the key behavioral trait — this is a manual override that bypasses the natural resolution path — which is genuinely useful. However it omits reversibility, whether the mark is permanent, permission/auth needs, and any confirmation of what state change occurs; for a mutation tool these gaps keep it at adequate rather than strong.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences, zero filler, with the action stated first and the caution immediately following. Nothing is buried or redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter mutation tool with no annotations and no output schema, the description covers purpose and the caution/routing signal, which is the essential part. It still leaves the agent guessing about the effect of the call (irreversibility, what the memory looks like afterward, error cases for invalid ids), so it is adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is one parameter (id) with 100% schema description coverage ('记忆 id'), so the schema already handles the semantics. The description implies the id names the memory being resolved but adds no format, validation, or failure-mode guidance beyond that; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb-plus-resource: it force-marks a given memory ('心结', via id) as resolved. The '人工强制' qualifier implicitly contrasts with the natural-decay path used elsewhere, though no sibling tool is named explicitly. An agent can tell what it does, but must infer which sibling normally handles resolution.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says '慎用' (use with caution) and states the normal case — resolution should emerge naturally from time/expression/state evidence — which functions as a clear when-not-to-use condition. It stops short of naming the alternative tool or defining what 'evidence-based' resolution looks like operationally.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_sleepA

手动让一条记忆进入休眠(不删除,只是平时不被唤起)。

NameRequiredDescriptionDefault
idYes记忆 id

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It usefully discloses that the memory is not deleted and that it simply will not be recalled under normal conditions. It does not state whether the sleep is reversible, how to reverse it, or whether any permissions or side effects apply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single compact sentence with zero waste. The core behavior and the non-deletion constraint are front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter mutation tool, the description covers the essential behavior and clarifies that data is not destroyed. It is slightly incomplete because it omits reversibility details and explicit routing to memory_wake, but the core semantics are sufficient given the simple schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single required parameter 'id' is fully documented in the schema (100% coverage), so the schema already does the heavy lifting. The description adds no additional semantics about the identifier beyond what the schema provides, making the baseline score of 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: manually putting a memory into sleep. It also distinguishes the action from deletion ('不删除'), which helps separate it from memory_delete. However, it does not explicitly name memory_wake as the counterpart, so sibling differentiation is strong but not complete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: use this when you want a memory to stop being recalled normally without deleting it. There is no explicit when-to-use guidance, no mention of when to prefer memory_delete or memory_wake, and no stated prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_statsA

查看记忆库统计:总数、活跃、休眠、钉住。

NameRequiredDescriptionDefault
profileNo角色/用户分区,默认 default

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. 'View statistics' implies a read-only, non-destructive operation and the enumerated metrics give a rough sense of the return payload, but the description says nothing about cost, permissions, or how dormant/pinned are counted. Adequate but thin for an unannotated tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence that front-loads the action and then lists the reported fields. No filler, no repetition of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, single-optional-parameter read tool with no output schema, the description conveys enough to invoke it correctly and even previews the returned counters. Only the profile-scoping semantics remain unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single optional 'profile' parameter is already documented there with its default. The description adds no additional meaning about what profile scoping does to the statistics, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (查看/view) and resource (记忆库统计/memory-library statistics) and enumerates the metrics returned (total, active, dormant, pinned). This clearly separates it from siblings like memory_list or memory_recall, though it never names those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer this is a metrics/overview call rather than a content-retrieval call. There is no explicit statement of when to reach for it versus memory_list or memory_recall, and no exclusions or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_updateB

修改一条记忆的内容,会自动重新评分。

NameRequiredDescriptionDefault
idYes记忆 id
kindNo新类型,可省略
contentYes新内容

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does disclose one important side effect: the memory is automatically re-scored after the edit, so ranking changes. It omits what happens to fields not supplied (e.g. kind retained or reset), whether the edit is reversible, and permission requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence that front-loads the action and appends the side effect; no filler. It is efficient but too terse to be exemplary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple three-parameter mutation with no output schema and no annotations, the description is minimally adequate. It does not explain the re-scoring consequence in terms an agent can act on, nor does it cover the optional field's effect.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so id, kind, and content are already documented in the schema. The description adds no detail on the optional kind parameter or on how content replacement interacts with re-scoring, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (修改) and resource (一条记忆的内容), so the operation is unambiguous. It does not contrast itself with siblings such as memory_remember or memory_delete, though the name makes the mutation role discoverable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to update versus delete-and-recreate via memory_remember, nor any prerequisite such as needing a valid id from memory_list or memory_recall. Usage is only implied by the verb.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_wakeC

手动把一条休眠记忆救回来(对应“想起来”)。

NameRequiredDescriptionDefault
idYes记忆 id

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not say what state change occurs (dormant to active), whether the operation is reversible (the counterpart memory_sleep exists), what happens if the id refers to a memory that is not dormant, or whether it requires confirmation, which are all material for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence with no padding, and the key action is front-loaded. It is efficient, albeit partly because it omits the information it should contain.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a state-mutating tool with no annotations and no output schema, the description is too thin: it says neither what the call returns, nor how failure when the memory is not dormant is signalled, nor how it relates to memory_sleep and memory_recall.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is one parameter and its schema coverage is 100%, so the schema fully documents `id`. The description adds no further meaning beyond that, which is the expected baseline when the schema does the work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a concrete verb and resource: manually reviving a dormant memory ('想起来' / recall). It is more than a restatement of the name, but it does not distinguish this operation from the sibling memory_recall tool, which presumably covers the ordinary recall path, so the boundary between the two is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The word '手动' (manually) implies a contrast with an automatic mechanism, but the description never states when an agent should call memory_wake rather than memory_recall or memory_pin, nor does it give preconditions such as the memory having to be dormant first.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 14 tool updatesv0.4.0
    • First observedmemory_alias
    • First observedmemory_delete
    • First observedmemory_explain
    • First observedmemory_export
    • First observedmemory_list
    • First observedmemory_mood
    • First observedmemory_pin
    • First observedmemory_recall
    • First observedmemory_remember
    • First observedmemory_resolve
    • First observedmemory_sleep
    • First observedmemory_stats
    • First observedmemory_update
    • First observedmemory_wake

TDQS

B3.4/5.0

Scored across 14 tools

Disambiguation4/5

Most tools have clearly distinct purposes: recall vs. list vs. stats, remember vs. update, and delete vs. sleep are well separated by their descriptions. The slight overlap between memory_wake and memory_pin (both framed as manual rescue) and between memory_delete soft delete and memory_sleep is manageable but not perfectly crisp.

Naming Consistency5/5

Every tool uses the same memory_ prefix followed by a concise snake_case action or concept name. The pattern is predictable across all 14 tools, with no mixed casing or inconsistent verb style.

Tool Count5/5

Fourteen tools is well within the ideal 3–15 range for a memory-management server. Each tool covers a specific lifecycle or diagnostic operation, and none appears redundant or trivial.

Completeness4/5

The surface covers creation, recall, listing, update, soft/hard delete, dormancy, pinning, aliasing, diagnostics, mood tracking, and export. The main minor gap is the absence of a corresponding memory_import tool to restore exported backups, but otherwise the lifecycle is well covered.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants to have persistent long-term memory by automatically storing and retrieving important information via MCP tools.
    MIT
  • A
    license
    Not graded
    quality
    A
    maintenance
    Provides AI assistants with a persistent knowledge graph and experience memory, featuring context-aware routing, progressive disclosure, decay-based forgetting, and automatic promotion of important knowledge. It offers 22 MCP tools for storing, recalling, connecting, and querying knowledge, experiences, preferences, and ideas.
    13
    MIT