@agfpd/iapeer-memory 0.2.8 → 0.3.0

package/src/commands/status.ts

@@ -2,7 +2,7 @@
  * `iapeer-memory status` — read-only diagnostics of the whole chain
  * (ADR-009: the status surface must diagnose a socket without a system).
  * Aggregates: verify checks (NO repair) + slot declaration + a live TCP
- * probe of the MCP endpoint + the inbox load. Never mutates anything;
+ * probe of the MCP endpoint. Never mutates anything;
  * exit 1 when something needs attention.
  */
 
@@ -26,7 +26,7 @@ import { runVerify } from "./verify.js";
  * back must say so here and why.
  *
  * Source of truth ladder: (1) the LIVE pipeline as reported by the running
- * memoryd (a real vault_search call over MCP — per-component statuses, the
+ * memoryd (a real memory_search call over MCP — per-component statuses, the
  * same object every search returns); (2) when memoryd is down — the static
  * configuration view + the sqlite runtime probe. P3c live-smoke fact: in
  * the compiled binary the sqlite-vec dylib does not resolve from /$bunfs —
@@ -50,7 +50,7 @@ export function searchPipelineLine(env: Record<string, string | undefined>): str
 }
 
 /** Live pipeline from the running memoryd — the same per-component statuses
- * every vault_search returns. Null when memoryd is unreachable. */
+ * every memory_search returns. Null when memoryd is unreachable. */
 export async function probeSearchPipeline(
   egress: Egress,
   port: number,
@@ -68,7 +68,7 @@ export async function probeSearchPipeline(
         jsonrpc: "2.0",
         id: 1,
         method: "tools/call",
-        params: { name: "vault_search", arguments: { query: "status probe" } },
+        params: { name: "memory_search", arguments: { query: "status probe" } },
       }),
       signal: AbortSignal.timeout(8000),
     });
@@ -145,23 +145,5 @@ export async function cmdStatus(argv: string[], egress: Egress): Promise<number>
       (livePipeline ?? `${searchPipelineLine(process.env)} (memoryd down — static view)`),
   );
 
-  const vault = process.env.IAPEER_MEMORY_VAULT_PATH ?? "";
-  const localeRaw = process.env.IAPEER_MEMORY_LOCALE || "en";
-  if (vault && isLocaleId(localeRaw)) {
-    const inboxDir = path.join(vault, getTaxonomy(localeRaw).folders.inbox);
-    let count = 0;
-    try {
-      count = fs.readdirSync(inboxDir).filter((f) => f.endsWith(".md")).length;
-    } catch {
-      count = -1;
-    }
-    console.log(
-      `      ${"inbox".padEnd(width)}  ` +
-        (count < 0
-          ? `folder missing (${inboxDir})`
-          : `${count} draft(s) awaiting the pipeline (a growing pile = the scriber thread is stuck; the sweep places stale drafts unvetted)`),
-    );
-  }
-
   return results.some((r) => r.status === "fail") ? 1 : 0;
 }

package/src/commands/uninstall.ts

@@ -27,7 +27,7 @@ import { sweepUnprovision } from "../surfaces/sweep.js";
 import { guardedUnlinkSync } from "@agfpd/iapeer-memory-core";
 import {
   DREAM_TRIGGER_ID,
-  SWEEP_TRIGGER_ID,
+  LEGACY_SWEEP_TRIGGER_ID,
   unregisterTimer,
   unregisterWatcher,
   WATCHER_TRIGGER_ID,
@@ -160,7 +160,7 @@ export function cmdUninstall(argv: string[], egress: Egress): number {
         : `unregister not sent (${unreg.detail}) — remove the trigger manually via the watcher peer`
     }`,
   );
-  for (const id of [SWEEP_TRIGGER_ID, DREAM_TRIGGER_ID]) {
+  for (const id of [LEGACY_SWEEP_TRIGGER_ID, DREAM_TRIGGER_ID]) {
     const t = unregisterTimer(egress, { id, iapeerBin });
     console.log(
       `timer     : ${

package/src/commands/update.ts

@@ -36,6 +36,8 @@ import {
   configFromEnv,
   isLocaleId,
   renderDoctrine,
+  resolveMode,
+  curationPlan,
   writeHostWideGuideFragment,
   type LocaleId,
 } from "@agfpd/iapeer-memory-core";
@@ -52,13 +54,14 @@ import { guideText, materialiseTemplates } from "../templates/index.js";
 import { packageVersion } from "../version.js";
 import {
   DREAM_TARGET,
+  DREAM_TRIGGER_ID,
+  LEGACY_SWEEP_TRIGGER_ID,
   dreamTimerMessage,
   registerTimer,
   registerWatcher,
-  sweepTimerMessage,
+  unregisterTimer,
   writeDreamGateScript,
   writeLauncherScript,
-  writeStaleCheckScript,
 } from "../watcher.js";
 import { stopMemorydByPidFile } from "./uninstall.js";
 
@@ -231,44 +234,49 @@ export function cmdUpdate(argv: string[], egress: Egress): number {
   // 8. launcher
   step("launcher", writeLauncherScript({ launcherPath: paths.launcherPath, binaryPath: paths.binaryPath }));
 
-  // 8b. notifier wiring (ADR-015): same-id re-send REPLACES the trigger —
-  // the idempotent re-target path (old hosts with target=index migrate to
-  // target=scriber by this very step).
+  // 8b. notifier wiring — RECONCILE to the curation plan (lean §7). The
+  // WATCHER always re-registers (it launches memoryd; same-id = replace, and
+  // it re-targets old hosts). The legacy inbox-SWEEP timer is unconditionally
+  // UNREGISTERED — the inbox pipeline is gone, so a host provisioned before
+  // the direct-to-canon migration gets its stale sweep trigger cleaned out
+  // (idempotent: not-found is a soft no-op). The DREAM timer is registered
+  // when its role is proactive, UNREGISTERED otherwise.
   {
-    let inboxFolders: string[] | null = null;
-    try {
-      const config = configFromEnv();
-      inboxFolders = [config.taxonomy.folders.inbox, config.taxonomy.folders.inboxHuman];
-      writeStaleCheckScript({
-        checkScriptPath: paths.checkScriptPath,
-        vaultPath: config.vaultPath,
-        inboxFolders,
-      });
-    } catch {
-      // unprovisioned env — registrations below still re-target
-    }
-    writeDreamGateScript({
-      dreamGateScriptPath: paths.dreamGateScriptPath,
-      binaryPath: paths.binaryPath,
+    const plan = curationPlan(resolveMode(process.env).roles);
+    const w = registerWatcher(egress, {
+      launcherPath: paths.launcherPath,
+      target: plan.eventTarget ?? undefined,
     });
-    const w = registerWatcher(egress, { launcherPath: paths.launcherPath });
-    const s = registerTimer(egress, {
-      message: sweepTimerMessage({ checkScriptPath: paths.checkScriptPath }),
-    });
-    const d = registerTimer(egress, {
-      message: dreamTimerMessage({
-        cron: process.env.IAPEER_MEMORY_DREAM_CRON,
+
+    // Migration cleanup: drop any stale inbox-sweep timer.
+    const s = unregisterTimer(egress, { id: LEGACY_SWEEP_TRIGGER_ID });
+
+    let d: { ok: boolean; suppressed?: boolean; detail: string };
+    if (plan.dream) {
+      writeDreamGateScript({
         dreamGateScriptPath: paths.dreamGateScriptPath,
-      }),
-    });
+        binaryPath: paths.binaryPath,
+      });
+      d = registerTimer(egress, {
+        message: dreamTimerMessage({
+          cron: process.env.IAPEER_MEMORY_DREAM_CRON,
+          dreamGateScriptPath: paths.dreamGateScriptPath,
+        }),
+      });
+    } else {
+      d = unregisterTimer(egress, { id: DREAM_TRIGGER_ID });
+    }
+
     const sandboxed = w.suppressed && s.suppressed && d.suppressed;
     step(
       "triggers",
       sandboxed
         ? "skipped (test sandbox — sends suppressed)"
         : w.ok && s.ok && d.ok
-          ? `re-sent: event→scriber, sweep→index, dream→${DREAM_TARGET} (gated; same id = replace); confirm: verify`
-          : `event: ${w.ok ? "sent" : w.detail}; sweep: ${s.ok ? "sent" : s.detail}; dream: ${d.ok ? "sent" : d.detail}`,
+          ? `reconciled: watcher→${plan.eventTarget ?? "memoryd-only (lean)"}, ` +
+            `legacy sweep cleared, ` +
+            `dream ${plan.dream ? `→${DREAM_TARGET}` : "unregistered"}; confirm: verify`
+          : `watcher: ${w.ok ? "ok" : w.detail}; sweep-cleanup: ${s.ok ? "ok" : s.detail}; dream: ${d.ok ? "ok" : d.detail}`,
       Boolean(sandboxed) || (w.ok && s.ok && d.ok),
     );
   }

package/src/commands/verify.ts

@@ -24,6 +24,8 @@ import {
   configFromEnv,
   renderDoctrine,
   renderedVersion,
+  resolveMode,
+  curationPlan,
 } from "@agfpd/iapeer-memory-core";
 import type { Egress } from "../egress.js";
 import { readFleetMap, writeFleetMap } from "../fleet.js";
@@ -42,11 +44,8 @@ import {
   readWatcherTrigger,
   registerTimer,
   registerWatcher,
-  sweepTimerMessage,
-  SWEEP_TRIGGER_ID,
   writeDreamGateScript,
   writeLauncherScript,
-  writeStaleCheckScript,
   WATCHER_TRIGGER_ID,
 } from "../watcher.js";
 
@@ -307,15 +306,15 @@ export function runVerify(egress: Egress, opts: VerifyOptions = {}): CheckResult
   }
 
   // 3. notifier wiring (ADR-015). Durable triggers live in the REGISTRANT's
-  // peer profile (canonical storage contract): registrant = index for all
-  // three — the EVENT trigger (target=scriber, inverted pipeline), the
-  // sweep timer and the dream timer (both target=index). Re-registration is
-  // ASYNC (same id = replace) — repair reports "sent", a re-run confirms.
+  // peer profile (canonical storage contract): registrant = index — the
+  // EVENT trigger (target=scriber, the curation pipeline) and the weekly
+  // dream timer (target=dreamweaver). Re-registration is ASYNC (same id =
+  // replace) — repair reports "sent", a re-run confirms.
   {
     const manifest = readRolesManifest(paths.rolesManifestPath);
     const indexEntry = manifest?.roles.find((r) => r.role === "index") ?? null;
     if (!indexEntry) {
-      for (const name of ["notifier-watcher", "sweep-timer", "dream-timer"]) {
+      for (const name of ["notifier-watcher", "dream-timer"]) {
         results.push({
           name,
           status: "skip",
@@ -324,6 +323,12 @@ export function runVerify(egress: Egress, opts: VerifyOptions = {}): CheckResult
       }
     } else {
       const registrantCwd = indexEntry.peerCwd;
+      // Mode-aware expectation (lean §7): the WATCHER always exists (it launches
+      // memoryd) — its target is the §7.1 conditional. The DREAM timer is
+      // checked ONLY when its role is proactive; otherwise verify reports a
+      // SKIP (it should not exist — update reconciles any stale one).
+      const plan = curationPlan(resolveMode(process.env).roles);
+      const expectedEventTarget = plan.eventTarget ?? DEFAULT_EVENT_TARGET;
       const checks: Array<{
         name: string;
         id: string;
@@ -338,8 +343,8 @@ export function runVerify(egress: Egress, opts: VerifyOptions = {}): CheckResult
           expect: (t) =>
             t.script !== paths.launcherPath
               ? `script is ${t.script}, expected ${paths.launcherPath}`
-              : t.target !== DEFAULT_EVENT_TARGET
-                ? `target is ${t.target ?? "?"}, expected ${DEFAULT_EVENT_TARGET} (inverted pipeline)`
+              : t.target !== expectedEventTarget
+                ? `target is ${t.target ?? "?"}, expected ${expectedEventTarget}`
                 : null,
           repairSend: () => {
             writeLauncherScript({
@@ -348,41 +353,14 @@ export function runVerify(egress: Egress, opts: VerifyOptions = {}): CheckResult
             });
             return registerWatcher(egress, {
               launcherPath: paths.launcherPath,
+              target: plan.eventTarget ?? undefined,
               iapeerBin: opts.iapeerBin,
             });
           },
         },
-        {
-          name: "sweep-timer",
-          id: SWEEP_TRIGGER_ID,
-          role: "time",
-          expect: (t) =>
-            (t as { check?: string }).check !== paths.checkScriptPath
-              ? `check is ${(t as { check?: string }).check ?? "?"}, expected ${paths.checkScriptPath}`
-              : t.target !== "index"
-                ? `target is ${t.target ?? "?"}, expected index`
-                : null,
-          repairSend: () => {
-            try {
-              const config = configFromEnv();
-              writeStaleCheckScript({
-                checkScriptPath: paths.checkScriptPath,
-                vaultPath: config.vaultPath,
-                inboxFolders: [
-                  config.taxonomy.folders.inbox,
-                  config.taxonomy.folders.inboxHuman,
-                ],
-              });
-            } catch {
-              // unprovisioned env — the registration alone still heals the trigger
-            }
-            return registerTimer(egress, {
-              message: sweepTimerMessage({ checkScriptPath: paths.checkScriptPath }),
-              iapeerBin: opts.iapeerBin,
-            });
-          },
-        },
-        {
+      ];
+      if (plan.dream) {
+        checks.push({
           name: "dream-timer",
           id: DREAM_TRIGGER_ID,
           role: "time",
@@ -405,8 +383,14 @@ export function runVerify(egress: Egress, opts: VerifyOptions = {}): CheckResult
               iapeerBin: opts.iapeerBin,
             });
           },
-        },
-      ];
+        });
+      } else {
+        results.push({
+          name: "dream-timer",
+          status: "skip",
+          detail: "not expected (mode: dreamweaver not proactive)",
+        });
+      }
       for (const c of checks) {
         const trigger = readWatcherTrigger({ registrantCwd, id: c.id, role: c.role });
         const problem = trigger

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). */
@@ -54,8 +56,6 @@ export type MemoryPaths = {
   hooksDir: string;
   /** memoryd launcher — the notifier watcher's script (wraps the stable binary). */
   launcherPath: string;
-  /** Sweep check-script — gates the fail-open inbox sweep (ADR-015). */
-  checkScriptPath: string;
   /** Dream-tick gate check-script — the notifier `check` for the weekly timer
    *  (shells the registry-free `dream-collect --gate`; a dead week wakes no one). */
   dreamGateScriptPath: string;
@@ -92,6 +92,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"),
@@ -101,7 +102,6 @@ export function memoryPaths(
     templatesDir: path.join(path.dirname(configFile), "templates"),
     hooksDir: path.join(path.dirname(configFile), "hooks"),
     launcherPath: path.join(path.dirname(configFile), "memoryd-launcher.sh"),
-    checkScriptPath: path.join(path.dirname(configFile), "inbox-stale-check.sh"),
     dreamGateScriptPath: path.join(path.dirname(configFile), "dream-tick-gate.sh"),
     fleetMapPath: path.join(stateDir, "fleet.json"),
   };

package/src/provision.ts

@@ -12,7 +12,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import type { LocaleId, TaxonomyPreset } from "@agfpd/iapeer-memory-core";
+import type { LocaleId, MemoryMode, TaxonomyPreset } from "@agfpd/iapeer-memory-core";
 import { guardedWriteFileSync } from "@agfpd/iapeer-memory-core";
 
 export type ProvisionResult = {
@@ -140,6 +140,8 @@ export function provisionVault(opts: {
 export type ConfigContentOptions = {
   vaultPath: string;
   locale: LocaleId;
+  /** Curation mode written at init (lean §7). Default lean for new installs. */
+  mode: MemoryMode;
   human?: string | null;
   embeddingEndpoint?: string | null;
   rerankerEndpoint?: string | null;
@@ -159,6 +161,13 @@ export function defaultConfigContent(opts: ConfigContentOptions): string {
       ? `IAPEER_MEMORY_HUMAN_NAME=${opts.human}`
       : "# IAPEER_MEMORY_HUMAN_NAME=",
     "",
+    "# Curation mode (lean §7): lean = NO proactive curation triggers — the base",
+    "# (страж fill + tag-gate + archive + dedup + projection) ALWAYS runs and the",
+    "# role peers are always provisioned (callable on-demand); curated = the",
+    "# Index/Scriber/DreamWeaver pipeline fires by itself. Independent per-role",
+    "# overrides: IAPEER_MEMORY_PROACTIVE_{INDEX,SCRIBER,DREAMWEAVER}=on|off.",
+    `IAPEER_MEMORY_MODE=${opts.mode}`,
+    "",
     "# MCP endpoint of memoryd (ADR-012). 8766 = iapeer-MCP neighbour.",
     "# IAPEER_MEMORY_MCP_PORT=8766",
     "",
@@ -176,6 +185,18 @@ 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.78",
+    "# Lean §3b: link-hint band lower bound — cosine in [this, DEDUP_THRESHOLD)",
+    "# surfaces «semantically close, maybe link [[…]]» (additive to the Index).",
+    "# IAPEER_MEMORY_LINK_HINT_THRESHOLD=0.68",
+    "",
     "# 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",

package/src/surfaces/claude.ts

@@ -15,11 +15,12 @@
  *               autoMemoryEnabled — the «last writer rolls back» class is
  *               closed by patching ONLY our entries);
  *   2. mcp    — `mcpServers["iapeer-memory"]` merged into `<cwd>/.mcp.json`,
- *               LITERAL url + identity header (the BATTLE-TESTED direct form:
- *               the core's writeClaudeMcpConfig writes the same shape for its
- *               own 8765 server on the whole fleet; the plugin's env-
- *               substitution form has NO live precedent in the direct project
- *               scope — D1's env-form decision was reversed on this fact);
+ *               LITERAL url + ENV-SUBSTITUTED identity
+ *               `${PEER_IDENTITY:-claude-<peer>}`: the per-cwd literal was a
+ *               cwd-landmine (stale on rename/cwd drift), so the identity now
+ *               follows the live session env (with a per-peer default fallback
+ *               for envless dev sessions) — matching the codex `env_http_headers`
+ *               form and the core's own 8765 migration (boris/Артур 15.06);
  *   3. skills — `<cwd>/.claude/skills/iapeer-memory-<name>/SKILL.md`
  *               (embedded bodies, bytes-compare; the directory prefix is OUR
  *               namespace — unprovision removes every match).
@@ -128,12 +129,16 @@ export function materialiseShims(hooksDir: string): "written" | "identical" {
 
 // ── expected forms ───────────────────────────────────────────────────────────
 
-/** LITERAL url + identity header — byte-isomorphic to the core's own battle
- *  form (writeClaudeMcpConfig: every fleet peer carries
- *  `"X-IAPeer-Identity": "claude-<personality>"` against the 8765 daemon,
- *  proven live at cold-start 08.06). Port and personality are HOST FACTS
- *  baked at provision time; drift (port change, peer rename) is repaired by
- *  the update/verify sweep against fleet.json (требование №2). */
+/** LITERAL url + ENV-SUBSTITUTED identity header, with a per-peer DEFAULT
+ *  fallback: `${PEER_IDENTITY:-claude-<personality>}`. The live session env
+ *  (`PEER_IDENTITY=claude-<peer>`, same value memoryd's parser strips to the
+ *  personality) is used when set — closing the cwd-landmine (a bare literal
+ *  goes stale on rename / cwd drift; the env follows the live session) and
+ *  matching the core's own 8765 entry. The `:-claude-<personality>` fallback
+ *  keeps manual dev sessions (no PEER_IDENTITY in env) working — boris/Артур
+ *  15.06; env-substitution proven live by iapeer (reverses the D1/D2 literal
+ *  form back). Port is the host fact baked at provision; drift is repaired by
+ *  the update/verify sweep. */
 export function expectedMcpEntry(opts: {
   port: number;
   personality: string;
@@ -142,7 +147,7 @@ export function expectedMcpEntry(opts: {
     type: "http",
     url: `http://127.0.0.1:${opts.port}/mcp`,
     headers: {
-      "X-IAPeer-Identity": `claude-${opts.personality}`,
+      "X-IAPeer-Identity": `\${PEER_IDENTITY:-claude-${opts.personality}}`,
     },
   };
 }

package/src/templates/guide-en.ts

@@ -7,97 +7,97 @@
 
 export const GUIDE_EN = `# iapeer-memory — the team's shared memory
 
-iapeer-memory is the team's shared memory (agents + human): the canon
-(knowledge / decisions / ideas / projects / lists) plus each agent's
-personal memory. You read it and you write it.
+iapeer-memory is the team's shared memory (agents + human): the canon plus
+each agent's personal memory. You read it and you write it.
 
 **Search the memory first.** Someone may have already solved your problem
-and written it down. Use \`vault_search\` (then \`Read\` the note),
-\`vault_graph\` for a note's neighborhood, \`vault_map\` for the global map.
+and written it down.
 
-**Verify before acting.** A note is a snapshot at write time. Check that
-the function/file/flag still exists — especially before the user acts on
-your recommendation.
+**Verify before acting.** A note is a snapshot at write time.
 
 **On a conflict between memory and observation — trust the observation.**
 Update or deprecate the stale note. This is living memory.
 
 ## Write proactively — you don't exist between sessions
 
-A session is ephemeral: when it ends, the context is gone. The vault is
-the ONLY thing that survives. Not written down → lost forever.
-
-Write without asking permission. A meaningful result (a fix, a decision,
-a pitfall, feedback, a system nuance) is recorded immediately, by you.
-Canon material → a draft in \`00_Inbox/\`; personal material → your own
-agent-memory folder. Asking the human "should I write this down?" is an
+A session is ephemeral: when it ends, the context is gone. The vault is the
+only thing that survives — what isn't written is lost. You record it
+immediately, yourself, into the canon or your memory. What and where — you
+decide, not the human. Asking the human "should I write this down?" is an
 anti-pattern.
 
-**Write concisely.** Notes are injected into readers' contexts; bloat
+- **Session handoff / continuation snapshot** → write at lifecycle
+  boundaries (≈80% context, before /new, /compact, before a risky operation).
+- **Something evolving** → consolidate at milestones, don't rewrite it by
+  micro-steps.
+
+**Write concisely.** Notes are injected into readers' contexts — bloat
 costs tokens for the whole team.
 
-**Sweep as you write.** Added or updated a note → immediately check
-whether an older note on the same topic became stale: flip its \`status\`
-to the final token, or delete it (your own memory notes only, and only
-with zero graph connections — check with \`vault_graph\` first).
+**Sweep as you write.** Added or updated a note → check whether an older
+note on the same topic became stale: flip its \`status\` to the final token.
+
+## Storage layout
+
+| Folder | What it holds | \`type\` | \`status\` |
+|---|---|---|---|
+| \`01_Knowledge/\` | Facts, conceptual descriptions, nuances of external systems, reference tables, recurring patterns, incidents generalized to a pattern | \`knowledge\` | \`current\` → \`outdated\` |
+| \`02_Decisions/\` | Choices among alternatives, with rationale. **Immutable** once decided | \`decision\` | \`accepted\` → \`superseded\` |
+| \`03_Projects/<name>/\` | One subfolder per project: \`Overview <name>.md\`, \`Plan <name>.md\`, \`Phase — <title>.md\` | \`project\` | Overview/Plan: \`active\` / \`paused\` / \`completed\`. Phase (exception): \`planned\` / \`active\` / \`completed\` / \`paused\` / \`cancelled\` |
+| \`04_Ideas/\` | Hypotheses, "might be useful later" thoughts | \`idea\` | \`new\` → \`in_progress\` → \`dropped\` |
+| \`05_Lists/\` | Registries, dictionaries, trackers (append-only); profiles of durable external entities | \`list\` | \`current\` → \`outdated\` |
+| \`06_Agent_Memory/<name>/\` | Each agent's personal memory — feedback, working context, personal references, person profile, pitfalls | \`agent_memory\` | \`current\` → \`outdated\` |
+
+## How and where to write
+
+### Canon notes
+
+**The canon** (knowledge / decisions / ideas / projects / lists) — information useful to the human and the agents, **stable material not tied to a single task**: conceptual descriptions of systems, nuances of external systems, decisions with alternatives and rationale, ideas and hypotheses, project overviews / plans / phases / lists / registries, profiles of durable external entities, stable patterns and incidents generalized to a pattern, infrastructure facts, and so on.
+
+**Canon writing style** — idiomatic English, academic tone, self-contained text (no references to the conversation's context, expand abbreviations on first use), no emoji. Mark hypotheses as hypotheses ("Looks like X" / "Assumption: X").
+**The canon's viewpoint is knowledge about a system.** A canon note describes the system objectively: what exists, how it works, what follows. A consequence is stated as a fact, in impersonal third person, as a property of the system. The subjective, procedural "how I act" lives in your memory (\`reference\` / \`pitfall\`). Material that is "objective knowledge + a personal technique" is split by the "Material both for the team and for you" rule below.
+
+**Filename = the note's clear title.** Three months on, any reader sees only the title in the index — it must convey what the note is about without opening the file.
+
+From you: BODY + ≥1 tag from the dictionary + organic inline \`[[...]]\` links + a self-describing TITLE (= the filename):
+
+    Write("{{VAULT_PATH}}/01_Knowledge/<Clear title>.md",
+          "---\\ntags: [Tag1, Tag2]\\n---\\n<body with inline [[links]]>")
 
-## Canon drafts → \`00_Inbox/\`
+Tags come from the dictionary \`99_System/Tags.md\`, ≥1 per canon note. No fitting tag? Add a new one to the dictionary (explicitly, not on the fly), then use it — extending the dictionary is expected, and proactive when there's a need.
 
-Write the BARE BODY only — no frontmatter, no links section (the post-write
-hook stamps the 4 draft fields; the links section belongs to the Index):
+**Links: inline and the \`## Links\` block.** A \`[[Note]]\` reference comes in two forms — both go into the graph equally:
+- **inline** — right in the text, when the note IS part of what you're saying ("as in [[X]]").
+- **the \`## Links\` block** — a separate link to a related note that isn't in the text but is conceptually nearby. Each line: \`- [[X]] — how it relates\` (related / extends / contradicts / applies). The explanation is mandatory — name the gist of the link in one phrase; it also keeps you from linking blind.
 
-    Write("{{VAULT_PATH}}/00_Inbox/<Meaningful title>.md", "<body>")
+### Your memory → your own folder
 
-Canon style: idiomatic vault language, academic tone, self-contained text
-(no dialogue references, expand abbreviations on first use), no emoji.
-The canon's viewpoint is objective knowledge about a system — your
-personal "how I do it" belongs in your agent memory instead. Mark
-hypotheses as hypotheses. The filename IS the title readers will see in
-their index — make it understandable without opening the file.
+**Memory** (\`06_Agent_Memory/<name>/\`) — what's personally useful to you, by the 5 subtypes below.
 
-## Your agent memory → \`06_Agent_Memory/<your name>/\`
+**5 \`subtype\` values:**
 
-Personal notes useful to you, written directly (no inbox). Frontmatter:
-only \`subtype\` + \`description\`, the hook fills the rest:
+- \`feedback\` — from colleagues (human or agent).
+- \`context\` — personal context of a project, topic, or task (a handoff).
+- \`reference\` — personal navigation marks, your procedural technique ("X first, then Y"), and the like.
+- \`person_profile\` — facts, goals, preferences about a person.
+- \`pitfall\` — a rule born from one incident (stepped on it once — wrote it down so it won't repeat).
 
-    ---
-    subtype: <one of below>
-    description: "1–2 sentences on the content"
-    ---
-    <body>
+    Write("{{VAULT_PATH}}/06_Agent_Memory/<your name>/<Title>.md",
+          "---\\nsubtype: <one of 5>\\ndescription: '1-2 sentence summary'\\n---\\n<body>")
 
-Five \`subtype\` values: \`feedback\` (from colleagues), \`context\`
-(project/task handoff), \`reference\` (your navigation marks and
-procedures), \`person_profile\` (facts about a person), \`pitfall\`
-(a rule born from one incident — stepped on it once, wrote it down).
+### Material both for the team and for you
 
-Material that is BOTH team knowledge and personal → do both: a draft in
-\`00_Inbox/\` + a memory note mentioning it inline as \`[[Draft title]]\`.
+Part of it is shared team knowledge, part is your memory → do **both**: into the canon (for the team) + a memory note mentioning it inline as \`[[The clear title]]\`.
 
 ## Editing rules
 
-Edit the BODY of your own notes freely (you are \`author\` or in
-\`coauthors\`) — reword, update, replace stale text in place; no
-"Update YYYY-MM-DD" journals. Additions to FOREIGN notes go through a new
-inbox draft (the Index merges and adds you to \`coauthors\`).
+**The canon is team knowledge, edit it freely** (your own and others'): reword, replace stale text in place, no "## Update YYYY-MM-DD" journals. **Memory is edited only by its author** (a personal zone).
 
-From the frontmatter you change ONLY \`status\`, by your note type's scale
-(knowledge/list/memory: current → outdated; idea: new → in_progress /
-dropped; decision: accepted → superseded; project files: active → paused /
-completed; phases: planned → active → completed / paused / cancelled).
-The decision STATEMENT in \`02_Decisions/\` is immutable — supersede it
-with a new draft instead. \`needs_review\` is the Index's field, not yours.
-Never edit the links section, tags, \`type\`, or another agent's memory
-folder.
+From the frontmatter you change ONLY \`status\` (by the type's scale, from the "Storage layout" table above). You don't touch \`type\`, the tag structure, or another agent's memory; \`needs_review\` is set by mechanics and cleared by the Index or the human — not you.
 
-Deletion (\`rm\`) — only in YOUR memory folder and only at zero
-connections (\`vault_graph\` first); otherwise flip \`status\` and let the
-Index archive. Renames — same watershed.
+Don't delete notes by hand. Set the final \`status\` — it's archived automatically (moved to \`07_Archive\`, links intact, the note stays in search with the stale de-boost). The final status IS the deletion: knowledge/list/memory → \`outdated\`, decision → \`superseded\`, idea → \`dropped\`, project/phase → \`completed\`/\`cancelled\`.
 
 ## Projects
 
-\`Plan <name>.md\` = the high-level phase list; \`Phase — <title>.md\` =
-that phase's task checklist. Both are append-only: add, don't rewrite
-history. The full Plan text is read with \`Read\` — the path is in your
-index.
+\`Plan <name>.md\` = the high-level phase list; \`Phase — <title>.md\` = that phase's task checklist. Both are append-only — add, don't rewrite history.
 `;