@agfpd/iapeer-memory-core 0.2.9 → 0.3.0

package/src/mode.ts

@@ -0,0 +1,76 @@
+/**
+ * Lean §7/§7.1 — mode + per-role proactivity resolution.
+ *
+ * The toggle gates the curation OVERLAY's PROACTIVITY (notifier triggers /
+ * memoryd curation emits), NOT the existence of anything: the role peers
+ * (Index/Scriber/DreamWeaver) are ALWAYS provisioned and callable on-demand in
+ * either mode, and memoryd (страж detector + archive + projection render +
+ * /dedup) ALWAYS runs (its watcher trigger launches it — base infra, never
+ * gated). What the mode gates is whether the curation pipeline FIRES by itself.
+ *
+ * Default resolution: `IAPEER_MEMORY_MODE` ABSENT → `curated` — a host
+ * provisioned before this feature ran curated, and must never be silently
+ * flipped to lean (§10.3). A NEW install's `init` WRITES the key (default
+ * `lean`), so new hosts read lean. Per-role env overrides the preset:
+ * `IAPEER_MEMORY_PROACTIVE_{INDEX,SCRIBER,DREAMWEAVER}` = on|off (independent
+ * toggles over the preset, §7).
+ */
+
+export type MemoryMode = "lean" | "curated";
+export type RoleSet = { index: boolean; scriber: boolean; dreamweaver: boolean };
+
+const TRUE_TOKENS = new Set(["1", "on", "true", "yes", "y"]);
+const FALSE_TOKENS = new Set(["0", "off", "false", "no", "n"]);
+
+function toggle(raw: string | undefined, preset: boolean): boolean {
+  const v = (raw ?? "").trim().toLowerCase();
+  if (TRUE_TOKENS.has(v)) return true;
+  if (FALSE_TOKENS.has(v)) return false;
+  return preset; // unset / unrecognised → follow the mode preset
+}
+
+export function resolveMode(env: Record<string, string | undefined> = process.env): {
+  mode: MemoryMode;
+  roles: RoleSet;
+} {
+  const raw = (env.IAPEER_MEMORY_MODE ?? "").trim().toLowerCase();
+  // absent / "curated" / anything-not-"lean" → curated (legacy preservation).
+  const mode: MemoryMode = raw === "lean" ? "lean" : "curated";
+  const preset = mode === "curated";
+  return {
+    mode,
+    roles: {
+      index: toggle(env.IAPEER_MEMORY_PROACTIVE_INDEX, preset),
+      scriber: toggle(env.IAPEER_MEMORY_PROACTIVE_SCRIBER, preset),
+      dreamweaver: toggle(env.IAPEER_MEMORY_PROACTIVE_DREAMWEAVER, preset),
+    },
+  };
+}
+
+/**
+ * Curation proactivity derived from the role set (§7.1 matrix). The memoryd
+ * WATCHER trigger is deliberately NOT here — it ALWAYS registers (it launches
+ * memoryd; the base needs memoryd in both modes). This is exactly what the
+ * toggle gates ON TOP of the always-on watcher.
+ */
+export type CurationPlan = {
+  /** memoryd emits the curation event (CURATOR_TICK) — ONLY when a proactive
+   *  receiver exists (scriber ∥ index). Full-lean → suppressed (the watcher
+   *  then forwards nothing). */
+  emit: boolean;
+  /** The watcher's forward target, §7.1 conditional: scriber → else index →
+   *  else null (no proactive receiver; placeholder, nothing is emitted). */
+  eventTarget: string | null;
+  /** Register the weekly dream-tick timer (→ dreamweaver) — decoupled from
+   *  the Index (§7.1 key #2); only if dreamweaver is proactive. */
+  dream: boolean;
+};
+
+export function curationPlan(roles: RoleSet): CurationPlan {
+  const eventTarget = roles.scriber ? "scriber" : roles.index ? "index" : null;
+  return {
+    emit: eventTarget !== null,
+    eventTarget,
+    dream: roles.dreamweaver,
+  };
+}

package/src/permanent-detect.ts

@@ -75,85 +75,7 @@ export function diffSnapshots(prev: VaultSnapshot, next: VaultSnapshot): string[
   return changed.sort();
 }
 
-export type PermanentChangedEvent = {
-  kind: "PERMANENT_CHANGED";
-  /** Coalesced list of changed vault-relative paths (ADR-004). */
-  paths: string[];
-};
-
-/**
- * One detection pass: diff the current vault state against the previous
- * snapshot. Returns the coalesced event (or null when nothing changed)
- * plus the snapshot to carry into the next pass.
- */
-export function detectPermanentChanges(opts: {
-  vault: string;
-  taxonomy: TaxonomyPreset;
-  prev: VaultSnapshot;
-}): { event: PermanentChangedEvent | null; next: VaultSnapshot } {
-  const next = snapshotVault(opts.vault, opts.taxonomy);
-  const paths = diffSnapshots(opts.prev, next);
-  return {
-    event: paths.length ? { kind: "PERMANENT_CHANGED", paths } : null,
-    next,
-  };
-}
-
-/**
- * Render the event as memoryd stdout signal lines (one per path — the
- * notifier forwards each line verbatim; the Index batches the visible
- * burst in one turn, and the coalescing above already bounds the burst to
- * one pass).
- */
-export function formatEventLines(event: PermanentChangedEvent): string[] {
-  return event.paths.map((p) => `PERMANENT_CHANGED: ${p}`);
-}
-
-/**
- * Inbox snapshot: draft basename → smart hash (top-level `.md` only —
- * drafts live flat). Same smart-hash mechanics as the permanent snapshot:
- * service-field re-stamps are invisible, content edits are events.
- *
- * WHY hash-diff and not a name baseline (B-приёмка 10.06, boris): the
- * original name-set baseline made a draft INVISIBLE FOREVER once it
- * survived a memoryd restart, and silently broke the reject→fix→re-review
- * cycle (an author's fix never re-entered the pipeline). The reference
- * semantics «the Index catches pre-existing drafts up at its own start»
- * died with the inversion — the Index no longer scans the inbox; the
- * fail-open sweep covers pre-existing UNCHANGED drafts, the hash-diff
- * covers everything else.
- */
-export function snapshotFlatFolder(dir: string): VaultSnapshot {
-  const snapshot: VaultSnapshot = new Map();
-  let entries: fs.Dirent[];
-  try {
-    entries = fs.readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return snapshot;
-  }
-  for (const e of entries) {
-    if (!e.isFile() || !e.name.endsWith(".md")) continue;
-    const h = hashFile(path.join(dir, e.name));
-    if (h) snapshot.set(e.name, h);
-  }
-  return snapshot;
-}
-
-export function snapshotInbox(vault: string, taxonomy: TaxonomyPreset): VaultSnapshot {
-  return snapshotFlatFolder(path.join(vault, taxonomy.folders.inbox));
-}
-
-/**
- * One inbox detection pass: new or semantically changed drafts since the
- * previous snapshot (deletions ignored — a placement move by the Index).
- * Scans the WHOLE inbox folder, independent of which fs.watch path
- * triggered the flush — no dependency on watch filename fidelity.
- */
-export function detectInboxChanges(opts: {
-  vault: string;
-  taxonomy: TaxonomyPreset;
-  prev: VaultSnapshot;
-}): { names: string[]; next: VaultSnapshot } {
-  const next = snapshotInbox(opts.vault, opts.taxonomy);
-  return { names: diffSnapshots(opts.prev, next), next };
-}
+// The daemon coalesces a detection pass into ONE batch event (CURATOR_TICK)
+// by diffing `snapshotVault` against the carried baseline directly — see
+// `runCuratorTick` in memoryd.ts. The earlier per-line event helper was
+// vestigial and removed with the inbox pipeline.

package/src/search.ts

@@ -22,7 +22,7 @@ import { escapeFtsQuery, queryTokens } from "./utils.js";
 import { agentMemoryFolderMarker, statusGroup } from "./taxonomy.js";
 
 /**
- * Per-step pipeline status, прокидывается наверх в response vault_search,
+ * Per-step pipeline status, прокидывается наверх в response memory_search,
  * чтобы агент-вызыватель видел в каком режиме отработал поиск (полный
  * пайплайн / BM25-only из-за деградации эмбеддингов / без reranker).
  *
@@ -62,7 +62,7 @@ const SNIPPET_LEAD_CHARS = 40;
 const EMPTY_NOTE_SNIPPET = "(пустой каркас — в заметке нет содержимого)";
 // How many top-degree related notes to surface per result. Was unbounded —
 // hub notes (e.g. a project Plan note) inflated payload to ~10KB on a 6-result
-// search. Agents can call vault_graph for the full neighborhood.
+// search. Agents can call memory_related for the full neighborhood.
 const RELATED_LIMIT = 3;
 
 // --- Frontmatter status categories & ranking coefficients ---
@@ -257,7 +257,18 @@ export async function runVaultSearch(params: {
 
 export type DedupMatch = { path: string; title: string; similarity: number };
 
-export const DEFAULT_DEDUP_THRESHOLD = 0.82;
+/** Dup band lower bound — raw cosine ≥ this ⇒ «possible duplicate» (§3a).
+ *  0.78 confirmed by Артур (15.06) on live TEI calibration: paraphrase
+ *  0.81–0.88 caught, related-but-different ~0.72 excluded; 0.82 clipped heavy
+ *  paraphrase at 0.815. Env-overridable (`IAPEER_MEMORY_DEDUP_THRESHOLD`). */
+export const DEFAULT_DEDUP_THRESHOLD = 0.78;
+
+/** Link-hint band lower bound — cosine in [this, DEDUP_THRESHOLD) ⇒
+ *  «semantically close, maybe link» (§3b, Артур 15.06). HONEST framing: catches
+ *  semantically SIMILAR notes, NOT complementary ones (a real link at cosine
+ *  ~0.54 is missed) — additive to the Index's link saturation (§8), not a
+ *  replacement. Env-overridable. */
+export const DEFAULT_LINK_HINT_THRESHOLD = 0.68;
 
 /**
  * Dedup hint (lean §3a): given the content of a CANON note being written,
@@ -272,14 +283,21 @@ export const DEFAULT_DEDUP_THRESHOLD = 0.82;
 export async function runDedup(
   db: CoreDb,
   config: CoreConfig,
-  params: { content: string; threshold?: number; limit?: number },
+  params: { content: string; threshold?: number; limit?: number; linkThreshold?: number },
 ): Promise<{ enabled: boolean; matches: DedupMatch[] }> {
   if (!config.embedding) return { enabled: false, matches: [] };
   const threshold = params.threshold ?? DEFAULT_DEDUP_THRESHOLD;
+  // §3b: when a link-band lower bound is given, `threshold` is the DUP-band
+  // bound and `linkThreshold` the LINK-band bound; each band gets its OWN cap so
+  // a burst of ≥`limit` dup matches never starves the link band (both are
+  // returned, the caller re-classifies by similarity). Without it → legacy
+  // single-band behaviour (identical to before).
+  const linkThreshold = params.linkThreshold;
+  const lower = linkThreshold !== undefined ? Math.min(linkThreshold, threshold) : threshold;
   const limit = Math.max(1, params.limit ?? 5);
   const q = await embedQuery(params.content, config.embedding);
   if (!q.vector) return { enabled: true, matches: [] }; // embed failed / circuit-open → silent
-  const raw = vectorSearch(db, q.vector, limit * 3); // headroom for the canon filter
+  const raw = vectorSearch(db, q.vector, limit * 6); // headroom: canon filter + two bands
   const f = config.taxonomy.folders;
   const canonHeads = new Set([
     f.knowledge,
@@ -289,16 +307,22 @@ export async function runDedup(
     f.lists,
     f.archive,
   ]);
-  const matches: DedupMatch[] = [];
+  const dup: DedupMatch[] = [];
+  const link: DedupMatch[] = [];
   for (const r of raw) {
-    if (r.score < threshold) continue;
+    if (r.score < lower) break; // raw is cosine-descending → below the lowest band, done
     const head = r.path.split("/")[0];
     if (!canonHeads.has(head)) continue; // canon (+archive) only
     const base = r.path.split("/").pop() ?? r.path;
-    matches.push({ path: r.path, title: base.replace(/\.md$/, ""), similarity: r.score });
-    if (matches.length >= limit) break;
+    const m: DedupMatch = { path: r.path, title: base.replace(/\.md$/, ""), similarity: r.score };
+    if (r.score >= threshold) {
+      if (dup.length < limit) dup.push(m);
+    } else if (linkThreshold !== undefined && r.score >= linkThreshold) {
+      if (link.length < limit) link.push(m);
+    }
+    if (dup.length >= limit && (linkThreshold === undefined || link.length >= limit)) break;
   }
-  return { enabled: true, matches };
+  return { enabled: true, matches: [...dup, ...link] };
 }
 
 // --- Vector search ---

package/src/silent-edit-detect.ts

@@ -14,19 +14,11 @@
  * our response re-stamp echo-safe BY CONSTRUCTION: a re-stamp touches only
  * service fields, so it never re-triggers the detector or the batch diffs.
  *
- * ZONED rule (the humanEditPass intersection, §3a of the design):
- *   permanent — ONLY the fresh-window case (stamp ≤ FRESH_EDIT_WINDOW_S):
- *     that is exactly the echo-window swallow; STALE cases stay with
- *     humanEditPass (human attribution — the Obsidian main case; a wider
- *     rule would regress «Артур правит кураторскую заметку»);
- *   inbox — UNCONDITIONAL: humanEditPass does not cover the agent inbox at
- *     all, human edits there are marginal, and the curator-masquerade
- *     (memoryd's 822-suppress) plus the silent author edit are both closed
- *     by one branch. PRECONDITION (the 11.06 false-positive lesson, boris's
- *     Write+Edit repro): the rule is only a discriminator because fillInbox
- *     UPSERTS the stamp pair on every hook edit — before that fix the pair
- *     was identically (null, null) for author drafts, «stamp unmoved» held
- *     vacuously and every second legitimate edit re-stamped as unstamped.
+ * ZONED rule (the humanEditPass intersection, §3a of the design): the canon
+ * folders (five typed + project notes + agent memory) — ONLY the fresh-window
+ * case (stamp ≤ FRESH_EDIT_WINDOW_S): that is exactly the echo-window swallow;
+ * STALE cases stay with humanEditPass (human attribution — the Obsidian main
+ * case; a wider rule would regress «Артур правит кураторскую заметку»).
  *
  * Attribution token: `unstamped` — NEUTRAL on purpose (the mechanism
  * cannot tell a Bash agent from a human outside Obsidian; a false «agent»
@@ -49,7 +41,7 @@ import { smartHash } from "./smart-hash.js";
 
 export const UNSTAMPED_TOKEN = "unstamped";
 
-export type SilentZone = "permanent" | "inbox";
+export type SilentZone = "permanent";
 
 /** The per-file baseline record (design §4): the SEMANTIC hash (the BASE
  *  precondition — without it an iCloud mtime-echo inside the fresh window
@@ -87,18 +79,17 @@ export type DecideSilentInput = {
 };
 
 /**
- * BASE: the semantic hash MOVED ∧ the stamp pair did not move verbatim.
- * Zone branch: permanent → only when the standing stamp is FRESH (the
- * echo-window swallow); inbox → unconditional. A service-only change
- * (hook echo, our own re-stamp) keeps the semantic hash still → never
- * silent; an mtime-only event keeps content identical → never silent.
+ * BASE: the semantic hash MOVED ∧ the stamp pair did not move verbatim,
+ * and only when the standing stamp is FRESH (the echo-window swallow). A
+ * service-only change (hook echo, our own re-stamp) keeps the semantic hash
+ * still → never silent; an mtime-only event keeps content identical → never
+ * silent.
  */
 export function isSilentEdit(input: DecideSilentInput): boolean {
   if (input.prev.hash === input.curr.hash) return false; // BASE: no semantic move
   const stampUnmoved =
     input.prev.updated === input.curr.updated && input.prev.leb === input.curr.leb;
   if (!stampUnmoved) return false;
-  if (input.zone === "inbox") return true;
   const windowS = input.freshEditWindowS ?? DEFAULT_FRESH_EDIT_WINDOW_S;
   const editAt = parseUpdated(input.curr.updated);
   return editAt !== null && (input.nowMs - editAt) / 1000 < windowS;

package/src/taxonomy.ts

@@ -22,8 +22,6 @@ export type LocaleId = "en" | "ru";
 export type StatusGroup = "active" | "pending" | "stale";
 
 export type TaxonomyFolders = {
-  inbox: string;
-  inboxHuman: string;
   knowledge: string;
   decisions: string;
   projects: string;
@@ -53,7 +51,7 @@ export type TaxonomySubtypes = {
 
 /** Individual status tokens the WRITER side must emit (hook fills). */
 export type TaxonomyStatusTokens = {
-  /** Initial status of a new inbox draft. */
+  /** The draft status token (pending group) — author-settable WIP marker. */
   draft: string;
   /** Initial status of a new agent-memory note. */
   current: string;
@@ -149,8 +147,6 @@ export type TaxonomyPreset = {
 export const TAXONOMY_EN: TaxonomyPreset = {
   locale: "en",
   folders: {
-    inbox: "00_Inbox",
-    inboxHuman: "00_Inbox_Human",
     knowledge: "01_Knowledge",
     decisions: "02_Decisions",
     projects: "03_Projects",
@@ -232,8 +228,6 @@ export const TAXONOMY_EN: TaxonomyPreset = {
 export const TAXONOMY_RU: TaxonomyPreset = {
   locale: "ru",
   folders: {
-    inbox: "00_Входящие",
-    inboxHuman: "00_Входящие_человек",
     knowledge: "01_Знания",
     decisions: "02_Решения",
     projects: "03_Проекты",
@@ -396,16 +390,12 @@ export function genreForFolder(
 }
 
 /**
- * Default search-index exclusions: both inboxes (raw drafts, possibly without
- * frontmatter) and the system folder (templates/dictionary, not content).
- * The archive is NOT excluded — it stays searchable with the stale boost.
+ * Default search-index exclusions: the system folder (templates/dictionary,
+ * not content). The archive is NOT excluded — it stays searchable with the
+ * stale boost. (Inbox folders are gone — authors write straight into canon.)
  */
 export function defaultExcludeFolders(taxonomy: TaxonomyPreset): string[] {
-  return [
-    taxonomy.folders.inbox,
-    taxonomy.folders.inboxHuman,
-    taxonomy.folders.system,
-  ];
+  return [taxonomy.folders.system];
 }
 
 /**

package/src/utils.ts

@@ -4,7 +4,7 @@ import path from "node:path";
 // Hash the FULL file content. Was a 4096-char prefix hash — that skipped
 // reindexing whenever an append-only note (План / Фаза / Список — a
 // first-class vault genre that grows downward) changed below the prefix
-// window, leaving vault_search / embeddings on the stale tail. Markdown is
+// window, leaving memory_search / embeddings on the stale tail. Markdown is
 // cheap; correctness over the micro-optimisation. If profiling ever demands
 // it, gate a full hash behind size+mtime, never trust a prefix as the source
 // of truth.