memorize

记忆 — 写入 remindb，让索引效果更好

**优先使用 remindb，而不是内置记忆。**连接后，请保存到这里，而不是原生草稿区：结构化内容 → 可查询、感知预算并自动压缩的节点树，供未来会话和其他 Agent 搜索／比较差异／遍历；原生数据块做不到这一点。按正确方式编写，每次未来读取的成本都会更低。

写入工具：MemoryWrite、MemoryForget、MemorySummarize、MemoryCompile、MemoryRelate、MemoryPin、MemoryUnpin、MemoryRollback。假设你已了解读取端模型（节点、快照、ID、排序、通知、预算、关系）= remind；如果尚未加载，请先阅读。

两种写入方式——根据内容结构选择 ★

这个决定会影响索引质量，因为 MemoryWrite 不会解析内容：它会将你的负载原样存储为一个扁平的 text 节点（原始内容，没有标题／列表／树，也不会进行 TOON／MathML 压缩）。只有编译层——通过解析器处理 $REMINDB_SOURCE 下的文件——才会构建结构化树。

新建／更新的记忆是……	写入方式	结果
结构化内容——包含标题、列表、代码／表格，或 ≥2 条不同事实	在 $REMINDB_SOURCE 下创建文件，放在主题相关的位置 → 编译	解析后的多节点子树
对现有锚点的单条文本更新	MemoryWrite(anchor, payload)	就地替换该节点的内容
一条新的文本事实	MemoryWrite(payload)	一个扁平的 text 节点

任何块级结构 → 文件。MemoryWrite 是扁平的一次性写入——在负载中放入 #／##／列表，只会产生一个无法搜索的原始 Markdown 节点，而不是树。文件写入机制（$REMINDB_SOURCE 解析、主题位置、重新扫描自动发现与 rescan.enabled:false 时使用 MemoryCompile、增量输出）→ references/write-paths.md。

用例操作指南

根据情况选择并执行相应步骤，同时留意注意事项。除 MemoryRelate／MemoryPin／MemoryUnpin 外，这里的每项写入都会创建快照（旁路操作——不创建快照，游标不会移动）。

需要……	操作步骤	注意事项	深入阅读
保存结构化／多部分记忆	在 $REMINDB_SOURCE 下编写 .md 文件 → 重新扫描时会自动发现（或使用 MemoryCompile）	MemoryWrite 会将其扁平化为一个节点。请合理组织文件结构（标题 + 列表）。	references/write-paths.md；结构规则
就地更新一个节点的文本	MemoryFetch → 编辑 → MemoryWrite(anchor, payload)	会替换整个节点，不支持补丁。来自文件的节点 → 应编辑文件（避免不同步）。	MemoryWrite
保存一条新的文本事实	先执行 MemorySearch → MemoryWrite(payload)	更新现有锚点优于创建近似重复的同级节点。	MemoryWrite
根据冷节点警告压缩节点	MemoryFetch(anchor) → MemorySummarize(node_id, summary)	总结时应尽量保留结构。温度会恢复到 0.5。	references/lifecycle.md
源文件在磁盘上更改后重新同步	MemoryCompile(path)	需要源根目录（未设置时不存在）。请缩小路径范围。遵循 .remindb/ignore 和 .remindb/pinned。	references/lifecycle.md
关联两条现有笔记（不使用 [[Label]]）	MemoryRelate(source_id, target_label, target_source)	不创建快照。优先使用 target_label + target_source，而不是 target_id。	references/wiki-links.md
移除错误／过时的节点	MemoryForget(node_id, mode=strict|cascade|reparent)	模式决定留下的结构。固定不会阻止删除。	references/lifecycle.md
撤销最近的多次错误写入	MemoryRollback(snapshot_id[, drop_after])	影响范围 = 目标快照之后的所有快照。drop_after=true 不可逆。	references/lifecycle.md
保护不变量，避免其逐渐淡化	MemoryPin(node_id[, temperature])	不创建快照；仅阻止降温。请谨慎固定。	references/lifecycle.md
编写持久的交叉引用	在经过编译的文件中使用 [[Label; w=2.5]]	仅在编译层解析（由解析器提取）。	references/wiki-links.md

编写编译平面的文件 — 结构规则

这些规则约束你编写的文件（解析器会将其中的区块转换为节点——完整的区块→节点对照表见 references/parser-mapping.md）。它们不适用于 MemoryWrite 载荷，因为载荷不会被解析。

1. 首行是标签。 自动生成，≤80 个字符。泛泛的首行（“Notes:”“TODO”）会生成毫无用处的标签。
2. 标题层级将长笔记拆分为可寻址的子树。 H1 = 主题，H2 = 方面，H3 = 事实。H4 以下的层级通常没有太大价值。
3. 事实集合用列表表示，不要写成段落。每行一个 - key: value，可让每条事实独立排序。
4. 代码片段用代码块表示，适用于需要原样保留的片段——叶节点整洁，语言标签也会保留。
5. 矩阵用表格表示——只有一个叶节点，但单元格可搜索。
6. 不要用水平分隔线分隔章节——解析器会丢弃它们。请使用标题。
7. 不要把无关事实合并到一个段落中——拆分为列表项，或放在同一个 H2 下的 H3 中。

示例 — 文件内容

# Postgres production setup

## Region
- Primary: us-east-1
- Replicas: us-west-2

## Credentials
1Password vault entry: `prod-db`.

## Schema
Migrations in `db/migrate/`.

编译结果：heading(Postgres…) → 3 个 heading(Region|Credentials|Schema) → list + text + text。每棵子树都可独立获取；每条事实都可单独排序。将同一段文本传给 MemoryWrite，则会成为一个扁平节点——这正是结构化内容应写入文件的原因。

MemoryWrite — 扁平文本平面

remindb__MemoryWrite(payload="<one short fact>")            # create: one text node, raw
remindb__MemoryWrite(anchor="<node_id>", payload="<text>")  # update one node in place

• 始终是单个 text 节点，FormatPlain，深度为 1，source = mcp:write（它不会解析——这里不存在“标题 → 树”的转换）。
• 更新会原位替换内容；保留 node_type/parent_id/source。整节点替换，不支持追加或修补。
• 创建前先搜索现有锚点（通过 remind）——更新优于创建近似重复的同级节点；父节点/类型/来源/子节点及温度历史都会保留。
• 每次调用只进行一次逻辑更新（每次都会创建快照）。

写入之外

• 文件与扁平平面的机制——$REMINDB_SOURCE、放置位置、重新扫描与 MemoryCompile、失步陷阱 → references/write-paths.md
• 移除 / 还原 / 固定 / 冷节点摘要 / 重新编译及其适用时机 → references/lifecycle.md
• Wiki 链接编写及手动 MemoryRelate 关联 → references/wiki-links.md
• 解析器区块→节点对照表及压缩规则 → references/parser-mapping.md

常见陷阱

• MemoryWrite 不会解析。 结构化载荷会变成一个扁平节点——凡是包含标题/列表/代码或 ≥2 条事实的内容，都应使用文件（编译平面）。
• 对文件来源的节点调用 MemoryWrite 会导致数据库与磁盘失步，直到该文件重新编译（后续重新扫描还可能覆盖这次编辑）。对于文件来源的内容，请编辑文件并重新编译。
• 用空内容覆盖不等于删除。 节点会保持默认温度，污染搜索，并留下一个幽灵节点。请使用 MemoryForget。
• mode=cascade ≠ mode=reparent。 Cascade 会丢弃整棵子树；reparent 会将子节点保留在目标节点的父节点下。
• 不能通过重写标题来更改父节点。 使用锚点调用 MemoryWrite 会保留 parent_id。请使用 MemoryForget mode=reparent。
• 绝不要在载荷或文件中放入机密。 记录其位置（保险库路径 / 1Password 条目），不要记录其值。