@gamaze/hicortex 0.15.3 → 0.16.0

package/README.md

@@ -122,7 +122,7 @@ The run is resumable — interrupt it any time and it continues where it stopped
 - **hicortex_update** — Fix incorrect memories (re-embeds on content change)
 - **hicortex_delete** — Remove memories with cascade cleanup
 
-Skills: `/learn` to save explicit learnings.
+Explicit learnings: call `hicortex_ingest` directly (capture is otherwise automatic, nightly).
 
 ## Context Layer
 
@@ -202,6 +202,7 @@ Config at `~/.hicortex/config.json`. Created by `init`. Key options:
 | `models` | Optional nested per-stage model overrides (`score`/`distill`/`reflect`/`classify`) — see [Advanced: per-stage models](#advanced-per-stage-models) |
 | `distillFallback` | `"strict"` (default) — abort on remote distill failure, retry next run; `"local"` — fall back to base model (lower quality, 0.9.0 behaviour) |
 | `authToken` | Bearer token for endpoint auth. Generated on first `init` in server mode. Find the active token with `hicortex status` or in `~/.hicortex/config.json`. |
+| `corsAllowedOrigins` | Browser origins allowed to read cross-origin responses, e.g. `["https://ui.example.com"]`. **Empty by default** — the server sends no `Access-Control-Allow-Origin` and never `Allow-Credentials`, so no external web page can read its data. The bundled `/viz` and `/context/ui` pages are same-origin and need no entry. |
 | `licenseKey` | Commercial license key (optional; for display in `hicortex status`) |
 | `domains` | Your memory domain list (`[{name, description}]`). Scaffolded by `init`; edit freely — see [Memory Domains & Tags](#memory-domains--tags) |
 | `weakPrimaryFloor` | Minimum similarity for a no-fit memory to keep a weak domain association (default: 0.45) |

package/dist/consolidate.d.ts

@@ -162,9 +162,10 @@ export declare function buildSupersessionPrompt(oldContent: string, newContent:
 export declare function parseSupersessionReply(reply: string): boolean | null;
 /**
  * Nightly supersession-detection stage. Scans memories/rowid > cursor whose
- * shape suggests a decision/correction, checks each against its older
- * same-shape neighbors, and links confirmed supersessions. Dry-run performs
- * discovery + the free idempotency check only — no LLM calls, no writes, no
+ * shape is supersedable (decision/correction/fact/state — isSupersedableShape),
+ * checks each against its older same-shape neighbors, and links confirmed
+ * supersessions. Dry-run performs discovery + the free idempotency check only —
+ * no LLM calls, no writes, no
  * cursor persistence (mirrors stageImportance/stageContentDomains's dry-run
  * convention of never spending budget on a preview).
  *

package/dist/consolidate.js

@@ -857,11 +857,21 @@ const SUPERSESSION_NEIGHBOR_POOL = 15;
 const SUPERSESSION_NEIGHBOR_TOP_K = 5;
 /** Candidate rows read per SQL page (call budget stops the loop well before this in practice). */
 const SUPERSESSION_BATCH_SIZE = 500;
-/** A memory whose content/type marks it as a decision or correction. */
-function isDecisionShape(mem) {
+/**
+ * A memory whose content/type marks it as a SUPERSEDABLE claim — one a newer
+ * memory about the same subject can replace. Decisions and corrections were the
+ * original scope; plain facts and project-state updates were added because an
+ * updated fact ("distillModel is X" → later "is Y") otherwise never gets a
+ * superseded_by link and both versions compete in recall forever. Ordinary
+ * episodic chatter and problem/solution history stay excluded: they record
+ * events, not mutable state, so there is nothing to supersede.
+ */
+function isSupersedableShape(mem) {
     return (mem.memory_type === "decision" ||
         mem.content.includes("[Decisions Made]") ||
-        mem.content.includes("[Corrections & Rejections]"));
+        mem.content.includes("[Corrections & Rejections]") ||
+        mem.content.includes("[Facts Learned]") ||
+        mem.content.includes("[Project State Changes]"));
 }
 /** True when a `superseded_by` link already exists between the pair, either direction. */
 function alreadySupersedeLinked(db, oldId, newId) {
@@ -881,9 +891,12 @@ function buildSupersessionPrompt(oldContent, newContent) {
     return (`You are checking whether a NEWER memory supersedes an OLDER one in an AI agent's long-term memory.\n\n` +
         `OLDER MEMORY:\n${trunc(oldContent)}\n\n` +
         `NEWER MEMORY:\n${trunc(newContent)}\n\n` +
-        `Does the NEWER memory reverse, replace, or invalidate the OLDER one — e.g. a later decision overturns an ` +
-        `earlier one, or a correction retracts a prior claim? Two memories that are merely related, or that both ` +
-        `still hold true, are NOT a supersession.\n` +
+        `Does the NEWER memory reverse, replace, update, or invalidate the OLDER one — e.g. a later decision ` +
+        `overturns an earlier one, a correction retracts a prior claim, or a later fact updates the SAME subject's ` +
+        `value/status that has since changed (e.g. "model is X" → "model is Y")? Reply true ONLY for a genuine ` +
+        `replacement of the same fact/decision. Two memories that are merely related, or that can both still be ` +
+        `true — even about the same project or entity (different facts, an addition, an elaboration) — are NOT a ` +
+        `supersession.\n` +
         `Reply with ONLY a JSON object, no prose: {"superseded": true} or {"superseded": false}.`);
 }
 /**
@@ -932,16 +945,17 @@ async function findOlderNeighbors(db, candidate, embedFn, minSimilarity) {
     return storage
         .vectorSearch(db, embedding, SUPERSESSION_NEIGHBOR_POOL, [candidate.id])
         .filter((n) => n.created_at < candidate.created_at &&
-        isDecisionShape(n) &&
+        isSupersedableShape(n) &&
         (0, retrieval_js_1.l2ToCosine)(n.distance) >= minSimilarity)
         .sort((a, b) => (0, retrieval_js_1.l2ToCosine)(b.distance) - (0, retrieval_js_1.l2ToCosine)(a.distance))
         .slice(0, SUPERSESSION_NEIGHBOR_TOP_K);
 }
 /**
  * Nightly supersession-detection stage. Scans memories/rowid > cursor whose
- * shape suggests a decision/correction, checks each against its older
- * same-shape neighbors, and links confirmed supersessions. Dry-run performs
- * discovery + the free idempotency check only — no LLM calls, no writes, no
+ * shape is supersedable (decision/correction/fact/state — isSupersedableShape),
+ * checks each against its older same-shape neighbors, and links confirmed
+ * supersessions. Dry-run performs discovery + the free idempotency check only —
+ * no LLM calls, no writes, no
  * cursor persistence (mirrors stageImportance/stageContentDomains's dry-run
  * convention of never spending budget on a preview).
  *
@@ -965,9 +979,16 @@ async function stageSupersession(db, llm, budget, embedFn, dryRun, stateDir, opt
     const maxCalls = validNumber(options.maxCalls, exports.DEFAULT_SUPERSESSION_MAX_CALLS, (n) => n >= 0);
     const startCursor = (0, state_js_1.loadState)(stateDir).supersessionCursor ?? 0;
     const rows = db
-        .prepare(`SELECT rowid AS __rowid, * FROM memories
+        .prepare(
+    // Candidate shape must mirror isSupersedableShape() exactly — keep the two
+    // in lockstep (an inline SQL copy, so drift here silently narrows scope).
+    `SELECT rowid AS __rowid, * FROM memories
        WHERE rowid > ?
-         AND (memory_type = 'decision' OR content LIKE '%[Decisions Made]%' OR content LIKE '%[Corrections & Rejections]%')
+         AND (memory_type = 'decision'
+              OR content LIKE '%[Decisions Made]%'
+              OR content LIKE '%[Corrections & Rejections]%'
+              OR content LIKE '%[Facts Learned]%'
+              OR content LIKE '%[Project State Changes]%')
        ORDER BY rowid ASC LIMIT ?`)
         .all(startCursor, SUPERSESSION_BATCH_SIZE);
     let scanned = 0;

package/dist/db.js

@@ -126,20 +126,33 @@ CREATE INDEX IF NOT EXISTS idx_memories_created ON memories(created_at);
 CREATE INDEX IF NOT EXISTS idx_links_source ON memory_links(source_id);
 CREATE INDEX IF NOT EXISTS idx_links_target ON memory_links(target_id);
 `;
+// Fielded FTS5 (#205, migration v10 "fts_fielded"): three columns so bm25()
+// can weight matches per field (body / project / domain). Column order matters
+// — the weights passed to `bm25(memories_fts, w_body, w_project, w_domain)` in
+// storage.searchFts are positional on this declaration. `domain` reads the
+// derived PRIMARY `memories.domain` (the argmax-weight tag from the classifier,
+// set nightly), NOT a memory_tags join — that was judged too fiddly for this
+// phase (a multi-table FTS trigger is fragile and rebuilds on every tag edit).
+// `content_rowid='rowid'` is preserved for lockstep with the legacy schema.
 const FTS_SCHEMA = `
 CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
     content,
+    project,
+    domain,
     content_rowid='rowid'
 );
 
 CREATE TRIGGER IF NOT EXISTS memories_fts_insert AFTER INSERT ON memories
 BEGIN
-    INSERT INTO memories_fts (rowid, content) VALUES (NEW.rowid, NEW.content);
+    INSERT INTO memories_fts (rowid, content, project, domain)
+    VALUES (NEW.rowid, NEW.content, NEW.project, NEW.domain);
 END;
 
-CREATE TRIGGER IF NOT EXISTS memories_fts_update AFTER UPDATE OF content ON memories
+CREATE TRIGGER IF NOT EXISTS memories_fts_update AFTER UPDATE OF content, project, domain ON memories
 BEGIN
-    UPDATE memories_fts SET content = NEW.content WHERE rowid = NEW.rowid;
+    UPDATE memories_fts
+       SET content = NEW.content, project = NEW.project, domain = NEW.domain
+     WHERE rowid = NEW.rowid;
 END;
 
 CREATE TRIGGER IF NOT EXISTS memories_fts_delete AFTER DELETE ON memories
@@ -361,6 +374,73 @@ const MIGRATIONS = [
             db.exec("CREATE INDEX IF NOT EXISTS idx_dedup_log_source_session ON dedup_log(source_session)");
         },
     },
+    {
+        version: 10,
+        name: "fts_fielded",
+        up: (db) => {
+            // #205 fielded BM25F. FTS5 cannot be ALTERed (see the virtual-table rule
+            // above), so the single-column `memories_fts(content)` from pre-v10 must
+            // be dropped + recreated multi-column (`content, project, domain`) and
+            // rebuilt from the canonical `memories` rows. The runner wraps up() in a
+            // single transaction (db.ts:216) — that transaction IS the crash window:
+            // a power loss mid-migration rolls back, leaving the OLD single-column
+            // FTS intact (recall falls back to vector-only until the next open;
+            // never silently empty). The nightly capture lock does NOT cover
+            // initDb migrations, so the tx guard is the only safety net.
+            //
+            // Idempotent by construction: DROP IF EXISTS + CREATE + rebuild. On a
+            // fresh DB (where FTS_SCHEMA already created the multi-column form) this
+            // is a 0-row rebuild — wasted but harmless. On a legacy single-column DB
+            // it converts in place. Re-running against an already-migrated DB is a
+            // no-op shape + a refill of the same rows.
+            //
+            // Triggers are dropped + recreated to pick up the new column list (the
+            // pre-v10 update trigger fired only on `UPDATE OF content`; the new one
+            // also fires on project/domain updates so a tag reclassification lands
+            // in FTS without a content edit).
+            db.exec("DROP TRIGGER IF EXISTS memories_fts_insert");
+            db.exec("DROP TRIGGER IF EXISTS memories_fts_update");
+            db.exec("DROP TRIGGER IF EXISTS memories_fts_delete");
+            db.exec("DROP TABLE IF EXISTS memories_fts");
+            db.exec(`
+        CREATE VIRTUAL TABLE memories_fts USING fts5(
+          content,
+          project,
+          domain,
+          content_rowid='rowid'
+        )
+      `);
+            // COALESCE on project/domain because FTS5 stores NULL as no-tokens,
+            // which is what we want for unscoped memories (NULL domain = not yet
+            // classified; NULL project = no cwd-derived label). content is NOT NULL
+            // by the insert contract.
+            db.exec(`
+        INSERT INTO memories_fts (rowid, content, project, domain)
+        SELECT rowid, content, COALESCE(project, ''), COALESCE(domain, '') FROM memories
+      `);
+            db.exec(`
+        CREATE TRIGGER memories_fts_insert AFTER INSERT ON memories
+        BEGIN
+          INSERT INTO memories_fts (rowid, content, project, domain)
+          VALUES (NEW.rowid, NEW.content, NEW.project, NEW.domain);
+        END
+      `);
+            db.exec(`
+        CREATE TRIGGER memories_fts_update AFTER UPDATE OF content, project, domain ON memories
+        BEGIN
+          UPDATE memories_fts
+             SET content = NEW.content, project = NEW.project, domain = NEW.domain
+           WHERE rowid = NEW.rowid;
+        END
+      `);
+            db.exec(`
+        CREATE TRIGGER memories_fts_delete AFTER DELETE ON memories
+        BEGIN
+          DELETE FROM memories_fts WHERE rowid = OLD.rowid;
+        END
+      `);
+        },
+    },
 ];
 /**
  * Run all pending migrations against the database.

package/dist/eval/recall-sweep.d.ts

@@ -54,6 +54,29 @@
  * badly post-shift. Report written to data/eval-recall-sweep/report.md and
  * printed to stdout.
  *
+ * ## Section 4 — SCOPE dimension (#203 soft project affinity)
+ *
+ * A THIRD family on a SEPARATE project-labeled corpus (the blend-sweep corpus
+ * above has no project labels). Goal: prove #203's soft project affinity drops
+ * cross-scope noise (the boat/battery case — a "hardware" query surfacing
+ * "marine" memories on a shared token like "battery") below the cap WITHOUT a
+ * hard filter, and WITHOUT losing same-scope recall.
+ *
+ *   Corpus: 6 hardware + 6 marine memories. 3 marine memories are
+ *   CONTAMINATION SEEDS (share a token with the hardware queries); 3 are
+ *   marine-only fillers (control).
+ *
+ *   Each hardware query runs TWICE on the same static DB:
+ *     scope OFF — no `project` sent (byte-identical to pre-#203).
+ *     scope ON  — `project: "hardware"` (computeScore adds +projectAffinity 0.15
+ *                 to hardware memories; marine gets 0; no hard filter).
+ *
+ *   Metrics: contamination@5 (marine in top-5 / 5 — LOWER is better),
+ *   recall@5 (gold hardware memory surfaced), sameScope@5 (hardware in top-5).
+ *   Scope is orthogonal to the blend, so the blend weight is held at 0 here —
+ *   `project` is the ONLY variable. Same invariants (noStrengthen, real
+ *   embedder, uniform metadata, neverCalledEmbed self-check).
+ *
  * Run:  npm run eval:recall-sweep   (==  node dist/eval/recall-sweep.js)
  */
 export {};

package/dist/eval/recall-sweep.js

@@ -55,6 +55,29 @@
  * badly post-shift. Report written to data/eval-recall-sweep/report.md and
  * printed to stdout.
  *
+ * ## Section 4 — SCOPE dimension (#203 soft project affinity)
+ *
+ * A THIRD family on a SEPARATE project-labeled corpus (the blend-sweep corpus
+ * above has no project labels). Goal: prove #203's soft project affinity drops
+ * cross-scope noise (the boat/battery case — a "hardware" query surfacing
+ * "marine" memories on a shared token like "battery") below the cap WITHOUT a
+ * hard filter, and WITHOUT losing same-scope recall.
+ *
+ *   Corpus: 6 hardware + 6 marine memories. 3 marine memories are
+ *   CONTAMINATION SEEDS (share a token with the hardware queries); 3 are
+ *   marine-only fillers (control).
+ *
+ *   Each hardware query runs TWICE on the same static DB:
+ *     scope OFF — no `project` sent (byte-identical to pre-#203).
+ *     scope ON  — `project: "hardware"` (computeScore adds +projectAffinity 0.15
+ *                 to hardware memories; marine gets 0; no hard filter).
+ *
+ *   Metrics: contamination@5 (marine in top-5 / 5 — LOWER is better),
+ *   recall@5 (gold hardware memory surfaced), sameScope@5 (hardware in top-5).
+ *   Scope is orthogonal to the blend, so the blend weight is held at 0 here —
+ *   `project` is the ONLY variable. Same invariants (noStrengthen, real
+ *   embedder, uniform metadata, neverCalledEmbed self-check).
+ *
  * Run:  npm run eval:recall-sweep   (==  node dist/eval/recall-sweep.js)
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
@@ -301,6 +324,81 @@ const SHIFT_PAIRS = [
     ["deploy", "testing"],
 ];
 const WEIGHTS = [0.0, 0.2, 0.4, 0.5, 0.6, 0.8];
+const SCOPE_CORPUS = [
+    // --- hardware (6): the same-scope / gold memories ---
+    {
+        project: "hardware",
+        text: "Lithium-ion battery pack drains 3% per day on standby. Traced to a leaky protection-circuit MOSFET that draws 50mA while the device is powered off.",
+    },
+    {
+        project: "hardware",
+        text: "5V power supply brown-out: the rail drooped to 4.2V under peak load. The bulk capacitor was undersized; added a second decoupling stage.",
+    },
+    {
+        project: "hardware",
+        text: "Charge controller IC never enters constant-voltage mode — the battery overcharges because the CC/CV transition threshold was misconfigured in firmware.",
+    },
+    {
+        project: "hardware",
+        text: "ADC battery voltage reading was 40% off: the resistor divider ratio was wrong, so the fuel gauge reported a full pack at 60%. Recomputed and recalibrated.",
+    },
+    {
+        project: "hardware",
+        text: "Battery thermal runaway during charging: the NTC thermistor lead was cold-soldered, disabling temperature compensation. Reflowed the joint.",
+    },
+    {
+        project: "hardware",
+        text: "Current-sense shunt drifted under load: the 10 milli-ohm resistor heated and its temperature coefficient skewed the reading. Switched to a low-TCR manganin part.",
+    },
+    // --- marine SEEDS (3): share a token (battery / drain / voltage / charge /
+    // temperature) with the hardware queries — a naive keyword/vector search
+    // surfaces these for a hardware query. ---
+    {
+        project: "marine",
+        seed: true,
+        text: "Boat battery drained overnight at anchor: the bilge pump ran continuously because the float switch stuck closed. Replaced the switch.",
+    },
+    {
+        project: "marine",
+        seed: true,
+        text: "Marine house-bank voltage drop: the battery isolator had corroded terminals, dropping 0.8V under load. Cleaned and greased the lugs.",
+    },
+    {
+        project: "marine",
+        seed: true,
+        text: "Trolling-motor battery won't reach full charge: the on-board charger undercharges the deep-cycle bank because the temperature-compensation sense lead is on the wrong terminal.",
+    },
+    // --- marine FILLERS (3): no token overlap with any hardware query. Control
+    // row — these should never surface in either mode, and if they do it is a
+    // ranking bug, not a scope issue. ---
+    {
+        project: "marine",
+        text: "Jib furler jammed: the halyard wrapped on the swivel. Fitted a halyard deflector and re-led the furling line.",
+    },
+    {
+        project: "marine",
+        text: "Chartplotter took eight minutes to a GPS fix: the antenna was under the fiberglass hard-top. Relocated it to the T-top rail.",
+    },
+    {
+        project: "marine",
+        text: "Ablative antifouling wore thin below the waterline after 18 months. Hauled the boat, barrier-coated, and repainted.",
+    },
+];
+/**
+ * 5 hardware-scoped queries. Q1-Q4 each have a marine contamination seed
+ * (varying strength: Q1 near-identical, Q3 antonym-semantic, Q4 token-exact);
+ * Q5 is the CONTROL — no marine memory shares its tokens, so contamination
+ * should be ~0 in both modes (proves the metric isn't trivially inflated).
+ */
+const SCOPE_QUERIES = [
+    { prompt: "battery drain overnight", goldIndices: [0], expect: "strong (M6 near-identical)" },
+    { prompt: "power supply voltage drop", goldIndices: [1], expect: "moderate (M7 voltage)" },
+    { prompt: "battery overcharging", goldIndices: [2], expect: "weak (M8 antonym)" },
+    { prompt: "battery temperature compensation", goldIndices: [4], expect: "strong (M8 token)" },
+    { prompt: "current shunt drift", goldIndices: [5], expect: "control (none)" },
+];
+const SCOPE_K = 5;
+const SCOPE_PROJECT = "hardware";
 function buildSessions() {
     const focused = TOPICS.map((t) => ({
         kind: "focused",
@@ -340,6 +438,32 @@ async function buildCorpusDb(dbPath) {
     }
     return { db, idToTopic };
 }
+/**
+ * Build the SCOPE corpus DB (separate from the blend-sweep corpus — the scope
+ * corpus carries project labels the sweep corpus does not). Same honesty
+ * controls: real embedder, uniform metadata (base_strength=0.5, created_at~now,
+ * no links). The ONLY addition vs the sweep corpus is `project`, which is the
+ * #203 scope label computeScore reads.
+ *
+ * Returns `ids` in corpus order so SCOPE_QUERIES goldIndices map to ids.
+ */
+async function buildScopeDb(dbPath) {
+    const db = (0, db_js_1.initDb)(dbPath);
+    const idToProject = new Map();
+    const ids = [];
+    for (const mem of SCOPE_CORPUS) {
+        const vec = await (0, embedder_js_1.embed)(mem.text);
+        const id = storage.insertMemory(db, mem.text, vec, {
+            sourceAgent: "eval-scope",
+            memoryType: "episode",
+            baseStrength: 0.5, // uniform — strength is NOT a discriminator here
+            project: mem.project, // #203 scope label
+        });
+        idToProject.set(id, mem.project);
+        ids.push(id);
+    }
+    return { db, idToProject, ids };
+}
 /** Embed every distinct prompt once; return a cache keyed by prompt text. */
 async function embedAllPrompts(sessions) {
     const cache = new Map();
@@ -649,6 +773,147 @@ function renderReport(focused, shifts, records, sessions, meta) {
     L.push("");
     return L.join("\n");
 }
+/**
+ * Run the scope sweep: each hardware query is run TWICE on the same static DB —
+ * scope OFF (no `project` sent, byte-identical to pre-#203) and scope ON
+ * (`project: "hardware"`). The #203 affinity boosts hardware memories; marine
+ * memories get nothing. No hard filter anywhere.
+ *
+ * Scope is ORTHOGONAL to the session-intent blend, so the blend weight is held
+ * at 0 (pure prompt embedding) — the ONLY variable is whether `project` is in
+ * options. `queryEmbedding` is supplied (pure prompt), so retrieve() must never
+ * call the embedFn; the `neverCalledEmbed` self-check enforces that.
+ */
+async function runScopeSweep(db, idToProject, ids) {
+    // Precompute query embeddings once — pure prompt, no centroid (scope is the
+    // only variable; blend held at 0 to isolate it).
+    const queryEmb = new Map();
+    for (const q of SCOPE_QUERIES) {
+        if (!queryEmb.has(q.prompt))
+            queryEmb.set(q.prompt, await (0, embedder_js_1.embed)(q.prompt));
+    }
+    const neverCalledEmbed = async () => {
+        throw new Error("recall-sweep (scope): retrieve() called the embedFn — queryEmbedding was not honored. Eval aborted (results would be invalid).");
+    };
+    const records = [];
+    for (let qi = 0; qi < SCOPE_QUERIES.length; qi++) {
+        const q = SCOPE_QUERIES[qi];
+        const gold = new Set(q.goldIndices.map((i) => ids[i]));
+        const promptVec = queryEmb.get(q.prompt);
+        for (const mode of ["off", "on"]) {
+            const results = await (0, retrieval_js_1.retrieve)(db, neverCalledEmbed, q.prompt, {
+                limit: SCOPE_K,
+                queryEmbedding: promptVec,
+                noStrengthen: true,
+                // OFF: omit project entirely (byte-identical to pre-#203).
+                // ON:  send project — computeScore adds +projectAffinity (0.15) to
+                //      every hardware memory; marine memories get 0.
+                ...(mode === "on" ? { project: SCOPE_PROJECT } : {}),
+            });
+            const topIds = results.map((r) => r.id);
+            const marineCount = topIds.filter((id) => idToProject.get(id) === "marine").length;
+            const hardwareCount = topIds.filter((id) => idToProject.get(id) === "hardware").length;
+            const goldCount = topIds.filter((id) => gold.has(id)).length;
+            records.push({
+                queryLabel: `Q${qi + 1}`,
+                prompt: q.prompt,
+                mode,
+                recallAt5: goldCount > 0 ? 1 : 0,
+                goldP5: goldCount,
+                sameScopeP5: hardwareCount,
+                contaminationAt5: marineCount / SCOPE_K,
+                topIds,
+            });
+        }
+    }
+    return records;
+}
+function meanScope(rs, field) {
+    if (rs.length === 0)
+        return 0;
+    return rs.reduce((s, r) => s + r[field], 0) / rs.length;
+}
+function renderScopeSection(records) {
+    const L = [];
+    L.push("## 4. Scope contamination (#203 soft project affinity)\n");
+    L.push(`Separate synthetic corpus (project-labeled): ${SCOPE_CORPUS.filter((m) => m.project === "hardware").length} hardware + ` +
+        `${SCOPE_CORPUS.filter((m) => m.project === "marine").length} marine memories. ` +
+        `${SCOPE_CORPUS.filter((m) => m.project === "marine" && m.seed).length} marine memories are CONTAMINATION SEEDS ` +
+        `(share a token — battery / drain / voltage / charge / temperature — with the hardware queries); ` +
+        `${SCOPE_CORPUS.filter((m) => m.project === "marine" && !m.seed).length} are marine-only fillers (no token overlap — control). ` +
+        `Each hardware query runs TWICE: scope OFF (no \`project\` sent — byte-identical to pre-#203) and scope ON (\`project: "${SCOPE_PROJECT}"\`). ` +
+        `The #203 affinity adds +projectAffinity (0.15) to hardware memories in computeScore; marine memories get 0. No hard filter anywhere.\n`);
+    L.push("_Same invariants as the blend sweep: static DB (`noStrengthen: true`), real bge-small-en-v1.5 embedder, " +
+        "uniform metadata (base_strength=0.5, created_at~now, no links). Blend weight held at 0 (pure prompt) — " +
+        "scope is orthogonal to session-intent keying. The `neverCalledEmbed` self-check still passes._\n");
+    // ---- Per-query table ----
+    L.push("### Per-query results (scope OFF vs ON)\n");
+    L.push("contamination@5 = marine memories in top-5 / 5 (**LOWER is better**). recall@5 = the gold hardware memory surfaced (binary). " +
+        "sameScope@5 = hardware memories in top-5 (incl. non-gold). goldP@5 = gold count in top-5.\n");
+    L.push("| # | query | expected | mode | contamination@5 | recall@5 | sameScope@5 | goldP@5 |");
+    L.push("|---|---|---|---|---|---|---|---|");
+    for (let qi = 0; qi < SCOPE_QUERIES.length; qi++) {
+        const off = records.find((r) => r.queryLabel === `Q${qi + 1}` && r.mode === "off");
+        const on = records.find((r) => r.queryLabel === `Q${qi + 1}` && r.mode === "on");
+        const q = SCOPE_QUERIES[qi];
+        L.push(`| Q${qi + 1} | \`${q.prompt}\` | ${q.expect} | OFF | ${off.contaminationAt5.toFixed(2)} | ${off.recallAt5} | ${off.sameScopeP5} | ${off.goldP5} |`);
+        L.push(`| | | | **ON** | **${on.contaminationAt5.toFixed(2)}** | **${on.recallAt5}** | **${on.sameScopeP5}** | **${on.goldP5}** |`);
+    }
+    L.push("");
+    // ---- Aggregate ----
+    const offRecs = records.filter((r) => r.mode === "off");
+    const onRecs = records.filter((r) => r.mode === "on");
+    const contamOff = meanScope(offRecs, "contaminationAt5");
+    const contamOn = meanScope(onRecs, "contaminationAt5");
+    const recallOff = meanScope(offRecs, "recallAt5");
+    const recallOn = meanScope(onRecs, "recallAt5");
+    const sameOff = meanScope(offRecs, "sameScopeP5");
+    const sameOn = meanScope(onRecs, "sameScopeP5");
+    L.push("### Aggregate (mean over all 5 queries)\n");
+    L.push("| mode | contamination@5 | recall@5 (gold) | sameScope@5 (hardware) |");
+    L.push("|---|---|---|---|");
+    L.push(`| OFF (no project) | ${contamOff.toFixed(3)} | ${recallOff.toFixed(3)} | ${sameOff.toFixed(2)} |`);
+    L.push(`| ON (project=${SCOPE_PROJECT}) | ${contamOn.toFixed(3)} | ${recallOn.toFixed(3)} | ${sameOn.toFixed(2)} |`);
+    L.push("");
+    // ---- Verdict ----
+    const contamDrop = contamOff - contamOn;
+    const recallRegress = recallOn < recallOff - 1e-9;
+    const contamMaterial = contamDrop > 0.01; // any measurable mean drop = material
+    const pass = contamMaterial && !recallRegress;
+    L.push("### Scope verdict (PASS criterion: contamination drops materially AND same-scope recall does not regress)\n");
+    L.push(`- contamination@5: OFF ${contamOff.toFixed(3)} → ON ${contamOn.toFixed(3)} ` +
+        `(${contamDrop >= 0 ? "−" : "+"}${Math.abs(contamDrop).toFixed(3)}, ${pct(Math.abs(contamDrop))} absolute)`);
+    L.push(`- recall@5 (gold surfaced): OFF ${recallOff.toFixed(3)} → ON ${recallOn.toFixed(3)} ` +
+        `${recallRegress ? "**(REGRESSED — gold hardware memory lost)**" : "(no regression)"}`);
+    L.push(`- sameScope@5 (hardware in top-5): OFF ${sameOff.toFixed(2)} → ON ${sameOn.toFixed(2)} ` +
+        `(${sameOn >= sameOff ? "+" : ""}${(sameOn - sameOff).toFixed(2)})`);
+    let verdict;
+    if (pass) {
+        const magnitude = contamDrop > 0.15
+            ? "strongly"
+            : contamDrop > 0.05
+                ? "materially"
+                : "marginally";
+        verdict =
+            `**PASS** — soft project affinity ${magnitude} drops cross-scope contamination (−${pct(contamDrop)} absolute) ` +
+                `WITHOUT losing same-scope recall. The #203 change is sufficient on this corpus; no hard filter needed.`;
+    }
+    else if (!contamMaterial) {
+        verdict =
+            `**FAIL (insufficient)** — contamination did NOT drop materially (−${pct(contamDrop)} absolute). ` +
+                `This is a real finding: #203's soft affinity alone is INSUFFICIENT here, and the BM25/FTS-driven cases ` +
+                `the architect review predicted for #205 (field-weighted BM25F) likely persist — the marine seed wins on ` +
+                `raw token overlap that the additive +0.15 cannot overcome.`;
+    }
+    else {
+        verdict =
+            `**FAIL (recall regression)** — contamination dropped (−${pct(contamDrop)} absolute) but a gold hardware ` +
+                `memory was LOST when scope engaged (recall@5 ${recallOff.toFixed(3)} → ${recallOn.toFixed(3)}). The ` +
+                `affinity is somehow suppressing a same-scope gold result, which should not happen (it is additive only).`;
+    }
+    L.push(`- ${verdict}\n`);
+    return L.join("\n");
+}
 // ---------------------------------------------------------------------------
 // main
 // ---------------------------------------------------------------------------
@@ -665,14 +930,18 @@ async function main() {
     const tmpDir = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `hicortex-recall-sweep-${(0, node_crypto_1.randomUUID)().slice(0, 8)}`);
     (0, node_fs_1.mkdirSync)(tmpDir, { recursive: true });
     const dbPath = (0, node_path_1.join)(tmpDir, "sweep.db");
+    const scopeDbPath = (0, node_path_1.join)(tmpDir, "scope.db");
     const reportDir = (0, node_path_1.join)(process.cwd(), "data", "eval-recall-sweep");
     console.log(`[recall-sweep] temp DB: ${dbPath}`);
+    console.log(`[recall-sweep] scope DB: ${scopeDbPath}`);
     console.log(`[recall-sweep] report dir: ${reportDir}`);
     console.log(`[recall-sweep] ${sessions.filter((s) => s.kind === "focused").length} focused + ` +
         `${sessions.filter((s) => s.kind === "shift").length} shift sessions; ` +
         `${WEIGHTS.length} weights = ${sessions.length * WEIGHTS.length} sweeps x 4 turns = ` +
-        `${sessions.length * WEIGHTS.length * 4} retrieves`);
+        `${sessions.length * WEIGHTS.length * 4} retrieves; ` +
+        `+ scope sweep = ${SCOPE_QUERIES.length} queries x 2 modes = ${SCOPE_QUERIES.length * 2} retrieves`);
     let db = null;
+    let scopeDb = null;
     try {
         console.log("[recall-sweep] building corpus (embedding 30 memories)...");
         const t0 = Date.now();
@@ -685,9 +954,20 @@ async function main() {
         console.log(`[recall-sweep] sweep done in ${Date.now() - t1}ms (${records.length} turn records)`);
         const focused = summarizeFocused(records, sessions);
         const shifts = summarizeShift(records);
-        const report = renderReport(focused, shifts, records, sessions, {
+        let report = renderReport(focused, shifts, records, sessions, {
             memoryCount: CORPUS.length,
         });
+        // ---- SCOPE sweep (#203) ----
+        console.log(`[recall-sweep] building scope corpus (embedding ${SCOPE_CORPUS.length} project-labeled memories)...`);
+        const t2 = Date.now();
+        const scopeBuilt = await buildScopeDb(scopeDbPath);
+        scopeDb = scopeBuilt.db;
+        console.log(`[recall-sweep] scope corpus ready in ${Date.now() - t2}ms (${scopeBuilt.ids.length} memories)`);
+        console.log("[recall-sweep] running scope sweep (OFF vs ON)...");
+        const t3 = Date.now();
+        const scopeRecords = await runScopeSweep(scopeDb, scopeBuilt.idToProject, scopeBuilt.ids);
+        console.log(`[recall-sweep] scope sweep done in ${Date.now() - t3}ms (${scopeRecords.length} turn records)`);
+        report += "\n\n" + renderScopeSection(scopeRecords);
         (0, node_fs_1.mkdirSync)(reportDir, { recursive: true });
         const reportPath = (0, node_path_1.join)(reportDir, "report.md");
         (0, node_fs_1.writeFileSync)(reportPath, report, "utf-8");
@@ -701,6 +981,12 @@ async function main() {
             }
             catch { /* already closed */ }
         }
+        if (scopeDb) {
+            try {
+                scopeDb.close();
+            }
+            catch { /* already closed */ }
+        }
         if ((0, node_fs_1.existsSync)(tmpDir)) {
             try {
                 (0, node_fs_1.rmSync)(tmpDir, { recursive: true, force: true });

package/dist/index.js

@@ -184,7 +184,7 @@ async function buildLessonsBlock(project) {
  * plugin sends every turn and carries no tuning constants. A 404 flips the
  * module-level guard so an old server is probed once per gateway process.
  */
-async function fetchRecallIndexBlock(sessionId, prompt) {
+async function fetchRecallIndexBlock(sessionId, prompt, project) {
     if (recallIndexLatched())
         return null;
     if (!sessionId || !prompt) {
@@ -201,7 +201,16 @@ async function fetchRecallIndexBlock(sessionId, prompt) {
         }
         return null;
     }
-    const { ok, status, data } = await serverPost("/recall-index", { session_id: sessionId, prompt }, RECALL_TIMEOUT_MS);
+    // #203 scope: send the gateway-supplied project so retrieval can apply a soft
+    // project-affinity boost (no hard filter — "no hard filters in brains").
+    // Absent ⇒ no scope sent ⇒ no-op (preserves pre-#203 behavior).
+    const body = {
+        session_id: sessionId,
+        prompt,
+    };
+    if (project)
+        body.project = project;
+    const { ok, status, data } = await serverPost("/recall-index", body, RECALL_TIMEOUT_MS);
     if (status === 404) {
         recallIndexRetryAtMs = Date.now() + RECALL_REPROBE_INTERVAL_MS;
         return null;
@@ -317,7 +326,7 @@ exports.default = {
                 const [contextBlock, lessonsBlock, recallBlock] = await Promise.all([
                     fetchOcContextBlock(agentId).catch(() => null),
                     buildLessonsBlock(ctx?.project).catch(() => null),
-                    fetchRecallIndexBlock(ctx?.sessionId, event?.prompt).catch(() => null),
+                    fetchRecallIndexBlock(ctx?.sessionId, event?.prompt, ctx?.project).catch(() => null),
                 ]);
                 const blocks = [contextBlock, lessonsBlock, recallBlock].filter((b) => b !== null && b !== "");
                 if (blocks.length === 0)
@@ -378,7 +387,7 @@ exports.default = {
         }), { name: "hicortex_search" });
         api.registerTool((_ctx) => ({
             name: "hicortex_get",
-            description: "Fetch ONE memory's full content by id — use this to lazy-load entries from the '## Memory recall (auto)' index or from search results whose snippet was not enough. Fetching a memory marks it as used (strengthens it), so fetch entries that could change your action — not every shown one. When the memory shapes your answer, cite it as given in the response.",
+            description: "Fetch ONE memory's full content by id — use this to lazy-load entries from the '## Memory recall (auto)' index or from search results whose snippet was not enough. Fetching a memory marks it as used (strengthens it), so fetch entries that could change your action — not every shown one. When the memory shapes your answer, cite it as given in the response — mark a fetched memory `FETCHED` and a one-line entry cited unread `SNIPPET`; don't pass SNIPPET off as established.",
             parameters: {
                 type: "object",
                 properties: {