ai-memory-durable-pages

ai-memory 持久页面

仅在有意修改持久知识库时使用此技能。常规会话记录会自动保存；永久笔记则需要用户明确提出请求。

此工具集中的工具

• memory_write_page 用于编写持久知识库页面，保存永久项目知识。
• memory_delete_page 用于按确切路径删除持久知识库页面。
• memory_restore_page 用于列出页面的检查点（不带 rev），或将较早版本写回（带 rev），也可恢复已删除的页面。在多用户服务上，此操作仅限管理员使用，且无法访问 scope: "profile" 页面。

编写持久记忆

仅当用户明确要求永久记住某事、保存笔记、添加注释或记录项目知识时，才编写页面。不要将持久页面用于记录临时进度、常规状态更新或下次会话的上下文。

在正文第一行将页面标题写成 # H1，并省略单独的标题参数。ai-memory 会从该 H1 提取标题。内容应简洁、客观，并提供足够的上下文，让后续 Agent 无需重读整个会话即可应用。

可选的顶层元数据：kind（64 个字符）、entities（最多 10 个名称，每个 64 个字符；会进行规范化和去重）、abstract（1,024 个字符），以及 relations（一个将 causes、fixes 或 contradicts 映射到页面目标数组的对象；目标总数最多 32 个，每个目标 1,024 个字符）。关系目标可使用 path、project:path 或 workspace/project:path；省略扩展名的页面路径会解析为 .md，且范围组件必须已去除首尾空格。长度限制在修剪、规范化或去重之前按原始值计算。无法编辑任意 frontmatter 和作者字段。 每次写入都会替换整个页面及其元数据；未提供的字段将被清除。若需要保留现有内容，请先读取当前页面。此操作不支持局部更新或比较后写入的前置条件。

当用户明确要求将笔记设为临时内容时，请将 expires_at 设为 RFC3339 时间点或单独的 YYYY-MM-DD（表示该日期 UTC 时间当天结束时）。超过 TTL 后，常规搜索、最近记录和简报读取将隐藏该页面；后续的遗忘清理会将其删除。TTL 优先于 pinned，除非用户有意要求这种行为，否则不要同时设置两者。

自行编写会话页面

当用户要求整理你所参与的会话时，请使用自己的模型编写页面，而不是使用服务端模型：先读取会话的原始观察记录（检索技能中介绍了读取方法），然后使用 memory_write_page 编写每个页面，并传入相同的 session_id，以此将该会话记录为证据，并完成其排队中的整合任务。请遵循服务端的多页面布局，最多编写五个页面：

• sessions/<session_id>.md：会话叙述，tier: "episodic"，kind: "fact"。
• concepts/<slug>.md：常青概念页面，tier: "semantic"，kind: "fact"。
• decisions/<short>.md：记录已作出选择的 ADR 风格页面，tier: "semantic"，kind: "decision"。
• gotchas/<slug>.md：记录故障模式和意外情况，tier: "semantic"，kind: "gotcha"。
• _rules/<slug>.md：以独立指令形式编写的持久项目约定，tier: "semantic"，kind: "rule"。

只拆分记录会话中确立的内容；简短会话只需一个会话页面。记录实际说过和做过的事，绝不要把用户的问题写成已确认的决定。

项目规则应优先写入指令文件

如果用户要求创建持久项目规则，例如始终执行 X 或绝不执行 Y，而仓库说明存在规范的 Agent 指令文件，则应更新该文件。只有当用户明确要求也将规则存入知识库，或不存在适用的规范指令文件时，才使用持久页面。

删除持久记忆

只能按确切路径删除。如果用户提供的是含糊的标题或主题，请先通过只读查询确定页面路径。除非用户明确指定，否则应保留同级项目。

项目范围

根据 MCP 客户端的身份支持情况选择范围：

• 支持会话的 MCP 客户端：每次请求都会转发真实的生命周期钩子会话 ID，应使用自动的当前项目路由。对于当前仓库，省略 workspace、project 和 cwd；只有当用户指定了其他项目时才传递显式范围。
• 静态 MCP 客户端（包括支持生命周期钩子、但没有桥接该钩子会话 ID 与 MCP 请求的客户端）必须在每次项目范围调用中同时传递 workspace 和 project，包括关于本项目、此处或我们工作的请求。如果最近的 .ai-memory.toml 声明了这两个名称，请读取其中的确切名称。如果没有标记覆盖，则根据规范化后的 upstream，再根据 origin 推导项目；使用不带主机名的完整仓库路径（github.com/acme/api → acme-api）。只有在不存在有效远程地址时才使用文件夹基本名称。绝不要依赖服务端最近一次激活的项目。

此规则仅适用于项目范围调用。跨项目检索时，global=true 必须省略 workspace、project 和 scopes。对于以 scope: "global" 写入的长期偏好，省略 workspace 和 project。

架构决策应采用 ADR 结构并固定

当用户要求记录架构决策（选定的方案、拒绝的替代方案、长期取舍）时，应将其写成位于 decisions/<short-slug>.md 下的持久页面，设置 pinned: true，并在正文中采用以下结构：

# <Decision title>

**Status:** accepted   

## Context
What situation forced a decision; the constraints that mattered.

## Decision
What was decided, stated as a fact.

## Consequences
What becomes easier, what becomes harder, what was given up.
Rejected alternatives and WHY, so future sessions don't re-propose them.

固定页面不受保留期限衰减和整理的影响，自动改进流程也会拒绝重写它们——除非有人取消固定，否则记录保持不可变。若要取代某项决策，请新建一个页面，并将旧页面的状态行设为 superseded by [[decisions/<new>]]；绝不要修改旧决策的实质内容。注意：ai-memory 不会触碰项目仓库中的文件——由项目仓库管理的 docs/adr/ 目录（无论是手动管理还是由其他工具管理）完全不属于 ai-memory；这些 wiki ADR 是对其的补充，用于跨会话检索。

长期用户／团队偏好应写入跨项目配置文件

如果某项事实是应适用于每个项目的长期偏好——技术选择（“始终使用 pnpm workspaces”）、代码风格（“优先组合而非继承”）、个人约定（“未经询问绝不使用 --force”）——请调用 memory_write_page 并设置 scope: "profile"，而不是写入当前项目。该页面会加入 profile/ 下的跨项目配置文件（传入类似 tools/pnpm.md 的路径；它会存储为 profile/tools/pnpm.md），每个项目的会话启动信息都会将其列为默认项，默认记忆读取也会将其作为 global_scope_hits 呈现。正文应以 # Title 和一行祈使句开头；传入 applies_to（例如 ["rust"]）可将其限定为采用该技术栈的项目；如果已有机制强制执行某项偏好，可传入 enforced_by（例如 "pre-push hook"），这样它就不会出现在会话启动摘要中。这两个字段仅对 profile 条目有效，重写时若省略它们，就会将其清除。使用 memory_delete_page 并设置 scope: "profile" 可删除条目。scope: "global" 仍会直接写入共享的 _global 范围。两种范围都不能与 workspace/project 参数一起使用。只有真正适用于多个项目的偏好才应使用它；项目特定规则应保留在项目中（或按上文所述，放在其指令文件中）。规则文件始终优先于配置文件：对于仓库中未说明的内容，配置文件才是默认设置。