open-memex 0.4.0-alpha.11 → 0.4.0-alpha.12

package/README.md

@@ -475,7 +475,9 @@ open-memex distill-agents [--scope project|personal] [--type t1,t2] [--limit N]
 # propose an AGENTS.md snippet distilled from project memories
 # (decisions, constraints, lessons, gotchas, howtos). Prints markdown;
 # -o writes it to a file. You review and merge by hand — open-memex
-# never rewrites your AGENTS.md on its own.
+# never rewrites your AGENTS.md on its own. The snippet ends with a
+# "memory hygiene" section (§3.5 checkpoint guidance) so agents reading
+# AGENTS.md learn to propose distilled captures at checkpoints.
 
 open-memex propose <id...> --to project [--local-approve]
 # propose one or several personal memories at once (one branch, one PR);

package/README.zh-CN.md

@@ -448,7 +448,8 @@ open-memex import <bundle.tar.gz> [--dry-run]
 open-memex distill-agents [--scope project|personal] [--type t1,t2] [--limit N] [-o <file>]
 # 把项目记忆（decision/constraint/lesson/gotcha/howto）提炼成
 # AGENTS.md 片段。默认打印到 stdout；-o 写文件。人工审阅后手工合并——
-# open-memex 永不自动改写你的 AGENTS.md。
+# open-memex 永不自动改写你的 AGENTS.md。片段末尾带一段"记忆卫生"
+# （§3.5 检查点指引），让读 AGENTS.md 的 agent 学会在检查点提议蒸馏捕获。
 
 open-memex propose <id...> --to project [--local-approve]
 # 一次 propose 一条或多条（一个分支、一个 PR），每条独立新 id。

package/dist/distill-agents.js

@@ -51,5 +51,12 @@ export function distillAgentsMarkdown(opts) {
         }
         lines.push(``);
     }
+    // D43 — §3.5 memory-hygiene footer (double insurance for opencode users,
+    // who never see the MCP handshake / init instructions): teach the agent
+    // reading this AGENTS.md to propose distilled captures at checkpoints.
+    lines.push(`### Memory hygiene (open-memex)`);
+    lines.push(``);
+    lines.push(`- At checkpoints (session start, end of a work chunk, after the user commits),`, `  distill the session: propose 1–3 short memories capturing the useful`, `  conclusion — what was learned or decided, how an issue was resolved, what`, `  to avoid, where the authoritative doc lives — not the raw transcript.`, `  Save nothing without user approval.`, `- If the knowledge already lives in project docs, save a \`reference\` memory`, `  pointing at the doc instead of copying it.`);
+    lines.push(``);
     return lines.join("\n");
 }

package/docs/V2-DESIGN.md

@@ -860,6 +860,13 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   saved via `memory_add` with the new optional `source` param set to
   `"inference"` (default `"tool"`). *Rationale: closes the 0.4.0 TODO from D41 —
   the design's capture loop now reaches the agent. Implemented 2026-09-29.*
+- **D43** — `distill-agents` output gains a "Memory hygiene (open-memex)"
+  footer carrying the §3.5 checkpoint guidance (propose 1–3 distilled captures
+  at checkpoints; save nothing without approval; prefer `reference` over
+  copying). *Rationale: double insurance for opencode users, who never see the
+  MCP handshake instructions or the `init`-written instruction files — but
+  opencode reads AGENTS.md natively, so the distilled snippet teaches the
+  checkpoint habit wherever it lands. Approved 2026-09-29.*
 - **D41** — The type taxonomy is reconciled to 11 types with one-line definitions
   (§3.1): `fact` `preference` `decision` `constraint` `todo` `knowledge` `howto`
   `gotcha` `lesson` `observation` `reference`. Merged away: `warning`→`gotcha`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-memex",
-  "version": "0.4.0-alpha.11",
+  "version": "0.4.0-alpha.12",
   "description": "Local-first memory layer and protocol for AI coding agents. Markdown source of truth, SQLite FTS5 index, zero cloud.",
   "type": "module",
   "license": "Apache-2.0",

package/src/distill-agents.ts

@@ -66,5 +66,20 @@ export function distillAgentsMarkdown(opts: DistillAgentsOptions): string {
     }
     lines.push(``);
   }
+  // D43 — §3.5 memory-hygiene footer (double insurance for opencode users,
+  // who never see the MCP handshake / init instructions): teach the agent
+  // reading this AGENTS.md to propose distilled captures at checkpoints.
+  lines.push(`### Memory hygiene (open-memex)`);
+  lines.push(``);
+  lines.push(
+    `- At checkpoints (session start, end of a work chunk, after the user commits),`,
+    `  distill the session: propose 1–3 short memories capturing the useful`,
+    `  conclusion — what was learned or decided, how an issue was resolved, what`,
+    `  to avoid, where the authoritative doc lives — not the raw transcript.`,
+    `  Save nothing without user approval.`,
+    `- If the knowledge already lives in project docs, save a \`reference\` memory`,
+    `  pointing at the doc instead of copying it.`,
+  );
+  lines.push(``);
   return lines.join("\n");
 }