@agfpd/iapeer-memory 0.2.8 → 0.2.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer-memory",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "iapeer-memory — peer memory for the iapeer ecosystem: vault, memoryd (index/search/MCP-http), layer-5 context fragments, role doctrines. The package IS the system; the claude/codex plugins are thin session sockets (docs/10-distribution.md, ADR-009).",
   "license": "MIT",
   "type": "module",
@@ -27,7 +27,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@agfpd/iapeer-memory-core": "0.2.8"
+    "@agfpd/iapeer-memory-core": "0.2.9"
   },
   "devDependencies": {
     "@types/bun": "^1.2.0",

package/src/cli.ts

@@ -25,6 +25,7 @@ import { cmdInstallBinary } from "./commands/install-binary.js";
 import { cmdMemoryd } from "./commands/memoryd.js";
 import { cmdMigrate } from "./commands/migrate.js";
 import { cmdDreamCollect } from "./commands/dream-collect.js";
+import { cmdArchiveStale } from "./commands/archive-stale.js";
 import { cmdProvisionPeer, cmdUnprovisionPeer } from "./commands/provision-peer.js";
 import { cmdRender } from "./commands/render.js";
 import { cmdStatus } from "./commands/status.js";
@@ -68,6 +69,11 @@ Commands:
                             batched tasks, from the LIVE registry (read-only).
                             --gate: no output, exit 0 iff there is work (the
                             notifier check that decides if DreamWeaver wakes)
+  archive-stale [--commit]  deliberate backlog archiver (lean §2.2a): move
+                            pre-existing stale notes to the archive. Dry-run by
+                            default (lists what would move); --commit executes.
+                            03_Projects is excluded; memoryd archives ongoing
+                            staleness incrementally on its own.
   render index|fragment|doctrine|guide
                             render one artifact explicitly (memoryd does this
                             continuously; render is the manual/scripted path)
@@ -134,6 +140,8 @@ export async function main(argv: string[]): Promise<number> {
       return cmdInstallBinary(rest, egress);
     case "dream-collect":
       return cmdDreamCollect(rest, egress);
+    case "archive-stale":
+      return cmdArchiveStale(rest);
     case "provision-peer":
       return cmdProvisionPeer(rest, egress);
     case "unprovision-peer":

package/src/commands/archive-stale.ts

@@ -0,0 +1,87 @@
+/**
+ * `iapeer-memory archive-stale [--commit]` — the DELIBERATE backlog archiver
+ * (lean §2.2a, decision boris 15.06).
+ *
+ * memoryd archives notes incrementally as they BECOME stale (an edit fires the
+ * change pass). Pre-existing stale notes are NOT swept on startup (that would
+ * be a mass move as a side-effect of a daemon boot — banned by §1: bulk
+ * actions are deliberate and verifiable). This verb is that deliberate path:
+ *
+ *   archive-stale            DRY-RUN — list what would move + a count
+ *   archive-stale --commit   actually move them
+ *
+ * `03_Projects` is excluded (a completed phase is a project record, not
+ * displaced knowledge — `isArchivableZone`). memoryd reindexes the moves on
+ * its next pass (or on restart); the verb itself only moves files.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import {
+  configFromEnv,
+  snapshotVault,
+  shouldArchive,
+  archiveTargetRel,
+} from "@agfpd/iapeer-memory-core";
+
+export function cmdArchiveStale(argv: string[]): number {
+  const commit = argv.includes("--commit");
+  const config = configFromEnv();
+  const vault = config.vaultPath;
+  const taxonomy = config.taxonomy;
+
+  // Candidates: notes in the monitored content folders carrying a final
+  // status, EXCLUDING 03_Projects (filtered by shouldArchive → isArchivableZone).
+  const snap = snapshotVault(vault, taxonomy);
+  const reserved = new Set<string>(); // archive targets claimed within this run
+  const moves: Array<{ from: string; to: string }> = [];
+  for (const rel of snap.keys()) {
+    let content: string;
+    try {
+      content = fs.readFileSync(path.join(vault, rel), "utf-8");
+    } catch {
+      continue;
+    }
+    if (!shouldArchive(rel, content, taxonomy)) continue;
+    const to = archiveTargetRel(
+      path.basename(rel),
+      taxonomy,
+      (r) => reserved.has(r) || fs.existsSync(path.join(vault, r)),
+    );
+    reserved.add(to);
+    moves.push({ from: rel, to });
+  }
+
+  if (moves.length === 0) {
+    console.log("archive-stale: no stale notes outside the archive — nothing to do.");
+    return 0;
+  }
+
+  if (!commit) {
+    console.log(
+      `archive-stale (DRY-RUN): ${moves.length} stale note(s) WOULD move to ${taxonomy.folders.archive}/:`,
+    );
+    for (const m of moves) console.log(`  ${m.from}  →  ${m.to}`);
+    console.log(
+      `\nPass --commit to move them. (03_Projects is excluded — completed phases stay project-local.)`,
+    );
+    return 0;
+  }
+
+  let moved = 0;
+  for (const m of moves) {
+    const toAbs = path.join(vault, m.to);
+    try {
+      fs.mkdirSync(path.dirname(toAbs), { recursive: true });
+      fs.renameSync(path.join(vault, m.from), toAbs);
+      moved += 1;
+      console.log(`  moved: ${m.from}  →  ${m.to}`);
+    } catch (err) {
+      console.error(`  FAILED: ${m.from} (${String(err)})`);
+    }
+  }
+  console.log(
+    `archive-stale: moved ${moved}/${moves.length}. memoryd reindexes on its next pass (or restart).`,
+  );
+  return 0;
+}

package/src/commands/hook.ts

@@ -39,6 +39,13 @@ import {
   getTaxonomy,
   isLocaleId,
   resolveAgentName,
+  resolveZone,
+  splitFrontmatter,
+  parseNoteTags,
+  parseDictionaryTags,
+  tagGateProblems,
+  tagsDictionarySourceRel,
+  type TaxonomyPreset,
 } from "@agfpd/iapeer-memory-core";
 import { memoryPaths, type MemoryPaths } from "../paths.js";
 import { DEFAULT_HEARTBEAT_STALE_MS } from "./verify.js";
@@ -113,15 +120,6 @@ export type PostWriteResult = {
   output: string | null;
 };
 
-export function reminderText(inboxFolder: string): string {
-  return (
-    "[iapeer-memory] New note in your agent memory. Check the guide's " +
-    "canon-vs-memory filter: does any part of it belong to the team's shared " +
-    `knowledge? If yes — also drop a draft into ${inboxFolder}/ and mention ` +
-    "this note inline as [[Title]] in the draft body; the Index will link them."
-  );
-}
-
 export function runPostWrite(
   eventJson: string,
   env: Record<string, string | undefined> = process.env,
@@ -182,26 +180,194 @@ export function runPostWrite(
     stamp: true,
   });
 
-  // Reminder: ONLY on a claude Write (new note) in the author's OWN memory
-  // folder — an Edit-loop must not spam the context (reference semantics).
-  // The codex branch NEVER emits: hookSpecificOutput.additionalContext is a
-  // claude protocol — codex support is unverified (upstream issue #19385
-  // ASKS for it, which reads as «not there»; fact-checked stance, not a gap).
-  const ownMemoryDir =
-    path.join(vault, taxonomy.folders.agentMemory, agent) + path.sep;
-  const output =
-    tool === "Write" && files[0]!.startsWith(ownMemoryDir)
-      ? JSON.stringify({
-          hookSpecificOutput: {
-            hookEventName: "PostToolUse",
-            additionalContext: reminderText(taxonomy.folders.inbox),
-          },
-        })
-      : null;
-
+  // TAG GATE (lean §3): validate the canon note's tags against the dictionary
+  // and teach the author to fix any problem (unknown tag / no tag). The guard
+  // stays SILENT on a clean write (§2.3) — output is non-null ONLY on a
+  // problem. RUNTIME-AGNOSTIC: codex supports PostToolUse `additionalContext`
+  // too (official codex hooks docs — the earlier «claude-only» was wrong), so
+  // the SAME schema reaches both runtimes. `files` already covers claude
+  // Write/Edit and codex apply_patch (multi-file).
+  const problems = collectTagProblems(files, vault, taxonomy);
+  const output = problems.length
+    ? JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "PostToolUse",
+          additionalContext: tagTeaching(problems),
+        },
+      })
+    : null;
   return { stamped: true, output };
 }
 
+/**
+ * Tag-gate problems across the just-written CANON files (lean §3). Reads the
+ * dictionary from the vault; FAIL-OPEN — an unreadable/empty dictionary (e.g.
+ * an evicted iCloud placeholder) yields no problems rather than rejecting
+ * every tag. Operative/inbox zones are not gated (canon only).
+ */
+export function collectTagProblems(
+  files: string[],
+  vault: string,
+  taxonomy: TaxonomyPreset,
+): string[] {
+  const dictRel = tagsDictionarySourceRel(taxonomy);
+  let allow: Set<string> | null = null;
+  try {
+    const dict = fs.readFileSync(path.join(vault, dictRel), "utf-8");
+    if (dict.trim()) allow = new Set(parseDictionaryTags(dict));
+  } catch {
+    // fail-open
+  }
+  if (!allow) return [];
+  const out: string[] = [];
+  for (const f of files) {
+    if (resolveZone(f, vault, taxonomy) !== "permanent") continue;
+    let fm: string;
+    try {
+      fm = splitFrontmatter(fs.readFileSync(f, "utf-8"))[0];
+    } catch {
+      continue;
+    }
+    const problems = tagGateProblems(parseNoteTags(fm), allow, {
+      requireAtLeastOne: true,
+      dictionaryRel: dictRel,
+    });
+    for (const p of problems) out.push(`${path.basename(f)}: ${p}`);
+  }
+  return out;
+}
+
+export function tagTeaching(problems: string[]): string {
+  return (
+    "[iapeer-memory] tag check — fix so this canon note indexes cleanly:\n" +
+    problems.map((p) => `- ${p}`).join("\n")
+  );
+}
+
+// ── dedup hint (lean §3a) ──────────────────────────────────────────────────────
+
+/** Short fail-open budget for the dedup RPC — a slow/down memoryd must never
+ *  hang a write-hook (same posture as the embedding circuit-breaker). */
+export const DEDUP_TIMEOUT_MS = 1500;
+
+type DedupResponse = {
+  enabled: boolean;
+  matches: Array<{ path: string; title: string; similarity: number }>;
+};
+
+/** POST the note body to memoryd's loopback /dedup RPC through the egress hub
+ *  (loopback allowance — П6 topology). Fail-open: any error (timeout,
+ *  connection refused, bad JSON) → null → the caller stays silent. */
+async function dedupFetch(
+  egress: Egress,
+  env: Record<string, string | undefined>,
+  content: string,
+): Promise<DedupResponse | null> {
+  const port = env.IAPEER_MEMORY_MCP_PORT || "8766";
+  const thr = env.IAPEER_MEMORY_DEDUP_THRESHOLD;
+  const body: { content: string; threshold?: number } = { content };
+  if (thr && !Number.isNaN(Number(thr))) body.threshold = Number(thr);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), DEDUP_TIMEOUT_MS);
+  try {
+    const res = await egress.fetch(`http://127.0.0.1:${port}/dedup`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    if (!res.ok) return null;
+    return (await res.json()) as DedupResponse;
+  } catch {
+    return null; // fail-open
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Dedup hint lines for a just-written CANON note (lean §3a). Re-parses the
+ * event independently of `runPostWrite` (keeps that sync contract intact).
+ * Claude-only (Write/Edit → additionalContext); canon-zone only; queries
+ * memoryd by the note BODY. Embeddings-off → memoryd returns enabled:false →
+ * no hint (silent).
+ */
+export async function collectDedupHints(
+  eventJson: string,
+  egress: Egress,
+  env: Record<string, string | undefined> = process.env,
+): Promise<string[]> {
+  let event: {
+    tool_name?: string;
+    cwd?: string;
+    tool_input?: { file_path?: string };
+    tool_response?: unknown;
+  };
+  try {
+    event = JSON.parse(eventJson) as typeof event;
+  } catch {
+    return [];
+  }
+  const tool = event.tool_name ?? "";
+  if (!POST_WRITE_TOOLS.has(tool)) return [];
+  const vault = env.IAPEER_MEMORY_VAULT_PATH ?? "";
+  if (!vault) return [];
+  const localeRaw = env.IAPEER_MEMORY_LOCALE || "en";
+  if (!isLocaleId(localeRaw)) return [];
+  const taxonomy = getTaxonomy(localeRaw);
+  // Candidate files: claude Write/Edit carry one file_path; codex apply_patch
+  // carries a patch over possibly many (RUNTIME-AGNOSTIC — codex receives the
+  // additionalContext hint via the same channel).
+  const candidates =
+    tool === "apply_patch" ? applyPatchPaths(event) : [event.tool_input?.file_path ?? ""];
+  const vaultPrefix = vault.endsWith(path.sep) ? vault : vault + path.sep;
+  const files = candidates.filter(
+    (p) => p.endsWith(".md") && p.startsWith(vaultPrefix) && fs.existsSync(p),
+  );
+  const hints: string[] = [];
+  for (const file of files) {
+    if (resolveZone(file, vault, taxonomy) !== "permanent") continue; // canon only (§3a)
+    let body: string;
+    try {
+      body = splitFrontmatter(fs.readFileSync(file, "utf-8"))[1];
+    } catch {
+      continue;
+    }
+    if (!body.trim()) continue;
+    const result = await dedupFetch(egress, env, body);
+    if (!result?.enabled || !result.matches?.length) continue;
+    for (const m of result.matches) {
+      if (path.basename(m.path) === path.basename(file)) continue; // self-guard (belt + braces)
+      hints.push(`[[${m.title}]] (${Math.round(m.similarity * 100)}%)`);
+    }
+  }
+  return hints;
+}
+
+/** Combine the sync tag-teaching output with async dedup hints into one
+ *  additionalContext blob (or null when both are empty). */
+export function mergeHookOutput(tagOutput: string | null, dedupHints: string[]): string | null {
+  let ctx = "";
+  if (tagOutput) {
+    try {
+      ctx = (JSON.parse(tagOutput).hookSpecificOutput?.additionalContext as string) ?? "";
+    } catch {
+      ctx = "";
+    }
+  }
+  if (dedupHints.length) {
+    const dedupText =
+      "[iapeer-memory] possible duplicate(s) of this canon note — verify, then extend " +
+      "the existing note or keep only new material:\n" +
+      dedupHints.map((h) => `- ${h}`).join("\n");
+    ctx = ctx ? `${ctx}\n\n${dedupText}` : dedupText;
+  }
+  if (!ctx) return null;
+  return JSON.stringify({
+    hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: ctx },
+  });
+}
+
 // ── session-start ────────────────────────────────────────────────────────────
 
 export type SessionStartResult = {
@@ -298,8 +464,11 @@ export async function cmdHook(argv: string[], egress: Egress): Promise<number> {
   try {
     switch (event) {
       case "post-write": {
-        const result = runPostWrite(await Bun.stdin.text());
-        if (result.output) console.log(result.output);
+        const text = await Bun.stdin.text();
+        const result = runPostWrite(text); // sync: stamp + tag gate
+        const dedupHints = await collectDedupHints(text, egress); // async, fail-open §3a
+        const output = mergeHookOutput(result.output, dedupHints);
+        if (output) console.log(output);
         return 0;
       }
       case "session-start": {

package/src/commands/render.ts

@@ -125,7 +125,10 @@ function renderFragment(argv: string[]): number {
       logs: paths.logsDir,
     },
     authorIndexPath: indexFile,
-    tagsDictionaryPath: agent === indexAgent ? paths.tagsMirrorPath : undefined,
+    // lean §3: the compact projection goes to EVERY peer (memoryd renders the
+    // projection file; a missing file is skipped gracefully by buildLayers).
+    tagsProjectionPath: paths.tagsProjectionPath,
+    tagsTitle: config.taxonomy.systemFiles.tagsDictionary,
   };
   const written = renderPeerFragment({ peerCwd, env });
   console.log(`render fragment: ${written}`);

package/src/paths.ts

@@ -32,6 +32,8 @@ export type MemoryPaths = {
   heartbeatPath: string;
   hashStatePath: string;
   tagsMirrorPath: string;
+  /** Compact tags-dictionary projection, injected to all peers (lean §3). */
+  tagsProjectionPath: string;
   /** Roles manifest (written by init, read by verify/render): role → peerCwd/template. */
   rolesManifestPath: string;
   /** Rendered author indexes (`<agent>-vault-index.md` + `-full` variant). */
@@ -92,6 +94,7 @@ export function memoryPaths(
     heartbeatPath: path.join(stateDir, "memoryd.heartbeat"),
     hashStatePath: path.join(stateDir, "memoryd.hashes.json"),
     tagsMirrorPath: path.join(cacheDir, "tags-dictionary.md"),
+    tagsProjectionPath: path.join(cacheDir, "tags-projection.md"),
     rolesManifestPath: path.join(stateDir, "roles.json"),
     indexesDir: path.join(stateDir, "indexes"),
     pidPath: path.join(stateDir, "memoryd.pid"),

package/src/provision.ts

@@ -176,6 +176,15 @@ export function defaultConfigContent(opts: ConfigContentOptions): string {
     "# Curator personalities exempt from needs_review stamping (ADR-006).",
     "# IAPEER_MEMORY_CURATOR_SET=index,scriber,dreamweaver",
     "",
+    "# Lean §3: per-tag boundary budget in the injected dictionary projection",
+    "# (×whole fleet — keep tight). Boundary text over this many chars is clipped.",
+    "# IAPEER_MEMORY_TAGS_BOUNDARY_MAXLEN=160",
+    "",
+    "# Lean §3a: dedup hint on canon writes — raw cosine similarity threshold",
+    "# above which an existing canon note is surfaced as a possible duplicate.",
+    "# Needs embeddings (semantic); with embeddings off the hint is silent.",
+    "# IAPEER_MEMORY_DEDUP_THRESHOLD=0.82",
+    "",
     "# Weekly dream-tick (deterministic pre-filter → DreamWeaver). Schedule is",
     "# 5-field cron; the window is days BY TIME (not since-last-tick).",
     "# IAPEER_MEMORY_DREAM_CRON=0 4 * * 1",