@seanhogg/builderforce-memory 2026.6.20 → 2026.6.28

package/dist/retrieval/chunk.js

@@ -0,0 +1,83 @@
+/**
+ * Document chunking — recursive character text splitter with overlap.
+ *
+ * The classic RAG ingestion step the memory layer was missing: large documents
+ * are split into smaller, semantically-coherent chunks before embedding so that
+ * retrieval returns precise passages rather than whole files. Mirrors the
+ * behaviour of LangChain's RecursiveCharacterTextSplitter (split on the largest
+ * natural boundary that fits, fall back to finer ones) but is zero-dependency.
+ */
+const DEFAULT_SEPARATORS = ['\n\n', '\n', '. ', ' ', ''];
+/**
+ * Splits `text` into overlapping chunks no larger than `chunkSize` characters,
+ * preferring the largest natural separator that keeps a piece under the limit.
+ * Returns `[]` for empty/whitespace input. Deterministic and pure.
+ */
+export function chunkText(text, opts = {}) {
+    const chunkSize = Math.max(1, opts.chunkSize ?? 1000);
+    const overlap = Math.min(Math.max(0, opts.chunkOverlap ?? 200), chunkSize - 1);
+    const separators = opts.separators ?? DEFAULT_SEPARATORS;
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return [];
+    if (trimmed.length <= chunkSize)
+        return [{ text: trimmed, index: 0, start: 0 }];
+    const pieces = splitRecursive(trimmed, chunkSize, separators);
+    // Merge adjacent pieces up to chunkSize, then stitch overlap between chunks.
+    const chunks = [];
+    let buf = '';
+    const flush = () => {
+        const t = buf.trim();
+        if (t.length > 0) {
+            const start = chunks.length === 0 ? 0 : Math.max(0, trimmed.indexOf(t));
+            chunks.push({ text: t, index: chunks.length, start });
+        }
+        buf = '';
+    };
+    for (const piece of pieces) {
+        if (buf.length + piece.length <= chunkSize) {
+            buf += piece;
+        }
+        else {
+            flush();
+            // Carry overlap from the previous chunk's tail.
+            const prev = chunks[chunks.length - 1]?.text ?? '';
+            buf = (overlap > 0 ? prev.slice(-overlap) : '') + piece;
+            // A single piece longer than chunkSize is hard-split.
+            while (buf.length > chunkSize) {
+                const head = buf.slice(0, chunkSize);
+                chunks.push({ text: head.trim(), index: chunks.length, start: 0 });
+                buf = (overlap > 0 ? head.slice(-overlap) : '') + buf.slice(chunkSize);
+            }
+        }
+    }
+    flush();
+    return chunks.map((c, i) => ({ ...c, index: i }));
+}
+/** Recursively splits text on the first separator that yields sub-chunkSize pieces. */
+function splitRecursive(text, chunkSize, separators) {
+    /* istanbul ignore next -- defensive base case; callers only recurse on parts > chunkSize */
+    if (text.length <= chunkSize)
+        return [text];
+    const [sep, ...rest] = separators;
+    if (sep === undefined)
+        return [text];
+    if (sep === '') {
+        // Last resort: hard character split.
+        const out = [];
+        for (let i = 0; i < text.length; i += chunkSize)
+            out.push(text.slice(i, i + chunkSize));
+        return out;
+    }
+    const parts = text.split(sep);
+    const out = [];
+    for (let i = 0; i < parts.length; i++) {
+        const part = i < parts.length - 1 ? parts[i] + sep : parts[i];
+        if (part.length > chunkSize)
+            out.push(...splitRecursive(part, chunkSize, rest));
+        else
+            out.push(part);
+    }
+    return out;
+}
+//# sourceMappingURL=chunk.js.map

package/dist/retrieval/chunk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.js","sourceRoot":"","sources":["../../src/retrieval/chunk.ts"],"names":[],"mappings":"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"}

package/dist/retrieval/fusion.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Rank fusion + diversity reranking.
+ *
+ *   • Reciprocal Rank Fusion (RRF) merges the dense (vector) and sparse (BM25)
+ *     rankings into one list without needing the two score scales to be
+ *     commensurable — it fuses on RANK, not raw score. This is the standard,
+ *     parameter-light way to combine hybrid retrieval signals.
+ *   • Maximal Marginal Relevance (MMR) reranks the fused list to trade off
+ *     relevance against novelty, so the top-k isn't five near-duplicate chunks.
+ *
+ * Pure and zero-dependency.
+ */
+export interface RankedList {
+    /** Ordered ids, most relevant first. */
+    ids: string[];
+    /** Optional weight for this list in the fusion (default 1). */
+    weight?: number;
+}
+export interface FusedHit {
+    id: string;
+    score: number;
+}
+/**
+ * Reciprocal Rank Fusion over any number of ranked lists.
+ * score(d) = Σ_lists weight / (k + rank(d)).  `k` (default 60) damps the
+ * contribution of low-ranked items; the canonical TREC value.
+ */
+export declare function reciprocalRankFusion(lists: RankedList[], k?: number): FusedHit[];
+export interface MmrCandidate {
+    id: string;
+    vector: Float32Array;
+}
+/**
+ * Maximal Marginal Relevance rerank. Greedily selects up to `topK` candidates,
+ * each step maximising `λ·sim(query, d) − (1−λ)·max sim(d, already-selected)`.
+ * λ=1 is pure relevance; lower λ injects diversity. Candidates without vectors
+ * should be filtered out by the caller (they cannot be MMR-scored).
+ */
+export declare function maximalMarginalRelevance(queryVec: Float32Array, candidates: MmrCandidate[], topK: number, lambda?: number): string[];
+//# sourceMappingURL=fusion.d.ts.map

package/dist/retrieval/fusion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fusion.d.ts","sourceRoot":"","sources":["../../src/retrieval/fusion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,WAAW,UAAU;IACvB,wCAAwC;IACxC,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC,SAAK,GAAG,QAAQ,EAAE,CAW5E;AAED,MAAM,WAAW,YAAY;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,YAAY,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACpC,QAAQ,EAAE,YAAY,EACtB,UAAU,EAAE,YAAY,EAAE,EAC1B,IAAI,EAAE,MAAM,EACZ,MAAM,SAAM,GACb,MAAM,EAAE,CAsBV"}

package/dist/retrieval/fusion.js

@@ -0,0 +1,64 @@
+/**
+ * Rank fusion + diversity reranking.
+ *
+ *   • Reciprocal Rank Fusion (RRF) merges the dense (vector) and sparse (BM25)
+ *     rankings into one list without needing the two score scales to be
+ *     commensurable — it fuses on RANK, not raw score. This is the standard,
+ *     parameter-light way to combine hybrid retrieval signals.
+ *   • Maximal Marginal Relevance (MMR) reranks the fused list to trade off
+ *     relevance against novelty, so the top-k isn't five near-duplicate chunks.
+ *
+ * Pure and zero-dependency.
+ */
+import { cosineSimilarity } from '../similarity/index.js';
+/**
+ * Reciprocal Rank Fusion over any number of ranked lists.
+ * score(d) = Σ_lists weight / (k + rank(d)).  `k` (default 60) damps the
+ * contribution of low-ranked items; the canonical TREC value.
+ */
+export function reciprocalRankFusion(lists, k = 60) {
+    const acc = new Map();
+    for (const list of lists) {
+        const weight = list.weight ?? 1;
+        list.ids.forEach((id, rank) => {
+            acc.set(id, (acc.get(id) ?? 0) + weight / (k + rank + 1));
+        });
+    }
+    return [...acc.entries()]
+        .map(([id, score]) => ({ id, score }))
+        .sort((a, b) => b.score - a.score);
+}
+/**
+ * Maximal Marginal Relevance rerank. Greedily selects up to `topK` candidates,
+ * each step maximising `λ·sim(query, d) − (1−λ)·max sim(d, already-selected)`.
+ * λ=1 is pure relevance; lower λ injects diversity. Candidates without vectors
+ * should be filtered out by the caller (they cannot be MMR-scored).
+ */
+export function maximalMarginalRelevance(queryVec, candidates, topK, lambda = 0.7) {
+    const remaining = [...candidates];
+    const selected = [];
+    const relevance = new Map();
+    for (const c of remaining)
+        relevance.set(c.id, cosineSimilarity(queryVec, c.vector));
+    while (selected.length < topK && remaining.length > 0) {
+        let bestIdx = 0;
+        let bestScore = -Infinity;
+        for (let i = 0; i < remaining.length; i++) {
+            const c = remaining[i];
+            let maxSimToSelected = 0;
+            for (const s of selected) {
+                const sim = cosineSimilarity(c.vector, s.vector);
+                if (sim > maxSimToSelected)
+                    maxSimToSelected = sim;
+            }
+            const mmr = lambda * relevance.get(c.id) - (1 - lambda) * maxSimToSelected;
+            if (mmr > bestScore) {
+                bestScore = mmr;
+                bestIdx = i;
+            }
+        }
+        selected.push(remaining.splice(bestIdx, 1)[0]);
+    }
+    return selected.map(s => s.id);
+}
+//# sourceMappingURL=fusion.js.map

package/dist/retrieval/fusion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fusion.js","sourceRoot":"","sources":["../../src/retrieval/fusion.ts"],"names":[],"mappings":"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"}

package/dist/retrieval/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Retrieval layer — chunking, BM25, rank fusion, and the HybridRetriever.
+ *
+ * The classic RAG pieces the memory stack previously lacked (chunking, hybrid
+ * dense+sparse search, reranking), implemented zero-dependency so they run in the
+ * browser, Node, and the SSM runtime alike.
+ */
+export { chunkText } from './chunk.js';
+export type { Chunk, ChunkOptions } from './chunk.js';
+export { bm25Search } from './bm25.js';
+export type { Bm25Doc, Bm25Hit, Bm25Options } from './bm25.js';
+export { reciprocalRankFusion, maximalMarginalRelevance } from './fusion.js';
+export type { RankedList, FusedHit, MmrCandidate } from './fusion.js';
+export { hybridRetrieve } from './HybridRetriever.js';
+export type { RetrievalCandidate, HybridQuery, HybridRetrieveOptions, HybridHit, } from './HybridRetriever.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/retrieval/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE/D,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC7E,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEtE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EACR,kBAAkB,EAClB,WAAW,EACX,qBAAqB,EACrB,SAAS,GACZ,MAAM,sBAAsB,CAAC"}

package/dist/retrieval/index.js

@@ -0,0 +1,12 @@
+/**
+ * Retrieval layer — chunking, BM25, rank fusion, and the HybridRetriever.
+ *
+ * The classic RAG pieces the memory stack previously lacked (chunking, hybrid
+ * dense+sparse search, reranking), implemented zero-dependency so they run in the
+ * browser, Node, and the SSM runtime alike.
+ */
+export { chunkText } from './chunk.js';
+export { bm25Search } from './bm25.js';
+export { reciprocalRankFusion, maximalMarginalRelevance } from './fusion.js';
+export { hybridRetrieve } from './HybridRetriever.js';
+//# sourceMappingURL=index.js.map

package/dist/retrieval/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGvC,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAG7E,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@seanhogg/builderforce-memory",
-  "version": "2026.6.20",
-  "description": "BuilderForce Agent Memory — runtime layer. SSM execution, Transformer orchestration, online distillation, and persistent agent memory for BuilderForce.ai agents.",
+  "version": "2026.6.28",
+  "description": "BuilderForce Agent Memory — runtime layer. SSM execution, Transformer orchestration, online distillation, hybrid RAG retrieval, and persistent agent memory for BuilderForce.ai agents.",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,6 +9,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./retrieval": {
+      "types": "./dist/retrieval/index.d.ts",
+      "import": "./dist/retrieval/index.js"
     }
   },
   "type": "module",
@@ -49,7 +53,7 @@
   },
   "homepage": "https://github.com/SeanHogg/builderforce-memory/tree/main/packages/memory#readme",
   "peerDependencies": {
-    "@seanhogg/builderforce-memory-engine": "^2026.6.20"
+    "@seanhogg/builderforce-memory-engine": "^2026.6.28"
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",
@@ -62,7 +66,7 @@
     "jest": "^29.7.0",
     "ts-jest": "^29.2.0",
     "typescript": "^5.0.0",
-    "@seanhogg/builderforce-memory-engine": "2026.6.20"
+    "@seanhogg/builderforce-memory-engine": "2026.6.28"
   },
   "jest": {
     "preset": "ts-jest/presets/default-esm",

package/src/cognition/EvermindCognition.ts

@@ -0,0 +1,156 @@
+/**
+ * Evermind — Write-Through Cognition engine.
+ *
+ * `commit()` is the model-knowledge analogue of a write-through cache write with
+ * a conflict resolver: Canonicalize (stable subject key) → Recall incumbent →
+ * Evaluate evidence → Reconcile (augment | confirm | supersede | reject) →
+ * write-through. `recall()` is the read side, served through a version-token
+ * cache that invalidates for free whenever knowledge changes.
+ *
+ * This is the layer the append-only knowledge loop skipped: it derives a STABLE
+ * subject key (not a per-run id) and replaces-on-write, so beliefs never drift
+ * into a manual reconciliation step.
+ */
+
+import type {
+    Claim,
+    CognitionFactStore,
+    CommitResult,
+    EvidenceGatherer,
+    EvidenceResult,
+    Verdict,
+} from './types.js';
+
+export interface EvermindCognitionOptions {
+    store: CognitionFactStore;
+    /** Default evidence gatherer used when `commit()` is not given one. */
+    gather?: EvidenceGatherer;
+    /**
+     * Optional embedding-capable runtime (e.g. SSMRuntime) forwarded to the
+     * store's `recallSimilar` so recall sharpens as the model adapts.
+     */
+    runtime?: unknown;
+}
+
+/** Subset of a store that can rank facts by semantic similarity. */
+interface SimilarityCapableStore {
+    recallSimilar(query: string, topK: number, runtime?: unknown): Promise<Array<{ content: string }>>;
+}
+
+function hasRecallSimilar(store: unknown): store is SimilarityCapableStore {
+    return typeof (store as SimilarityCapableStore).recallSimilar === 'function';
+}
+
+export class EvermindCognition {
+    private readonly _store: CognitionFactStore;
+    private readonly _defaultGather?: EvidenceGatherer;
+    private readonly _runtime?: unknown;
+
+    /**
+     * Knowledge-generation token. Bumped on every change to the fact set
+     * (augment / supersede). Doubles as the recall-cache namespace so a write
+     * invalidates cached reads for free — the "invalidate on write" rule applied
+     * to model knowledge.
+     */
+    private _version = 0;
+
+    /**
+     * L1 recall cache, namespaced by `_version`. After any knowledge change the
+     * version moves, so prior-generation entries are never read again (and are
+     * cleared to bound growth) — not an ad-hoc TTL map; a version-token cache.
+     */
+    private readonly _recallCache = new Map<string, string[]>();
+
+    constructor(opts: EvermindCognitionOptions) {
+        this._store = opts.store;
+        this._defaultGather = opts.gather;
+        this._runtime = opts.runtime;
+    }
+
+    /** Current knowledge-generation token. */
+    get version(): number {
+        return this._version;
+    }
+
+    /**
+     * Commit a candidate fact write-through. Evidence decides conflicts; a
+     * supersede replaces the incumbent under the same stable key and invalidates
+     * recall. Never appends a competing belief for the same subject.
+     */
+    async commit(claim: Claim, gather: EvidenceGatherer | undefined = this._defaultGather): Promise<CommitResult> {
+        const incumbent = await this._store.recall(claim.subjectKey);
+        const audit: string[] = [];
+
+        // ── Brand-new subject ────────────────────────────────────────────────
+        if (!incumbent) {
+            if (gather && claim.requireEvidence) {
+                const e = await gather({ claim });
+                audit.push(...e.notes);
+                if (!e.supportsNew) {
+                    return this._result('reject', claim.subjectKey, claim.content, undefined, audit);
+                }
+            }
+            await this._write(claim, claim.importance ?? 0.6);
+            this._bumpVersion();
+            return this._result('augment', claim.subjectKey, claim.content, undefined, audit);
+        }
+
+        // ── Identical incumbent — confirm (refresh confidence, no replace) ────
+        if (incumbent.content === claim.content) {
+            await this._write(claim, Math.min(1, (claim.importance ?? 0.6) + 0.1));
+            return this._result('confirm', claim.subjectKey, claim.content, undefined, audit);
+        }
+
+        // ── Conflict — evidence decides ──────────────────────────────────────
+        const e: EvidenceResult = gather
+            ? await gather({ claim, incumbent: incumbent.content })
+            : { supportsNew: true, notes: ['no evidence gatherer supplied; trusting newer observation'] };
+        audit.push(...e.notes);
+
+        if (e.supportsNew) {
+            await this._write(claim, Math.max(claim.importance ?? 0.6, 0.9));
+            this._bumpVersion();
+            return this._result('supersede', claim.subjectKey, claim.content, incumbent.content, audit);
+        }
+        return this._result('reject', claim.subjectKey, incumbent.content, undefined, audit);
+    }
+
+    /**
+     * Write-through recall: the top-K most relevant facts for `query`, served
+     * from a version-namespaced cache that invalidates on the next knowledge
+     * change. Falls back to an empty set when the store can't rank similarity.
+     */
+    async recall(query: string, topK = 5): Promise<string[]> {
+        const cacheKey = `${this._version}:${topK}:${query}`;
+        const cached = this._recallCache.get(cacheKey);
+        if (cached) return cached;
+
+        const facts = hasRecallSimilar(this._store)
+            ? (await this._store.recallSimilar(query, topK, this._runtime)).map((e) => e.content)
+            : [];
+
+        this._recallCache.set(cacheKey, facts);
+        return facts;
+    }
+
+    // ── internals ────────────────────────────────────────────────────────────
+
+    private async _write(claim: Claim, importance: number): Promise<void> {
+        await this._store.remember(claim.subjectKey, claim.content, { tags: claim.tags, importance });
+    }
+
+    private _bumpVersion(): void {
+        this._version++;
+        this._recallCache.clear();
+    }
+
+    private _result(
+        verdict: Verdict,
+        subjectKey: string,
+        content: string,
+        superseded: string | undefined,
+        evidence: string[],
+    ): CommitResult {
+        return { verdict, subjectKey, content, superseded, evidence, version: this._version };
+    }
+}

package/src/cognition/gatherers.ts

@@ -0,0 +1,40 @@
+/**
+ * Evermind — reusable evidence gatherers.
+ *
+ * Concrete, surface-agnostic evidence rules. The presence rule is the one the
+ * IDE self-correction loop uses (ground a claim by listing the workspace), kept
+ * here so the IDE, the proof harness, and tests share one implementation.
+ */
+
+import type { EvidenceGatherer } from './types.js';
+
+export interface WorkspacePresenceRule {
+    /** Lists the workspace (e.g. the IDE `list_files('.')` control tool). */
+    list: () => Promise<string[]>;
+    /** Entries that MUST be present for the new claim to hold. */
+    mustExist?: string[];
+    /** Entries that MUST be absent for the new claim to hold. */
+    mustBeAbsent?: string[];
+}
+
+/**
+ * Evidence rule: the new claim is supported iff every `mustExist` entry is
+ * present and every `mustBeAbsent` entry is gone from the listing.
+ */
+export function workspacePresenceGatherer(rule: WorkspacePresenceRule): EvidenceGatherer {
+    const mustExist = rule.mustExist ?? [];
+    const mustBeAbsent = rule.mustBeAbsent ?? [];
+    return async () => {
+        const listing = await rule.list();
+        const present = mustExist.filter((d) => listing.includes(d));
+        const absent = mustBeAbsent.filter((d) => !listing.includes(d));
+        const supportsNew = present.length === mustExist.length && absent.length === mustBeAbsent.length;
+        return {
+            supportsNew,
+            notes: [
+                `present: ${present.join(', ') || '—'}`,
+                `absent (as expected): ${absent.join(', ') || '—'}`,
+            ],
+        };
+    };
+}

package/src/cognition/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Evermind — Write-Through Cognition.
+ *
+ * The layer that keeps model knowledge current without a reconciliation step:
+ * stable-subject-key beliefs, evidence-gated conflict resolution, replace-on-write.
+ */
+
+export { EvermindCognition } from './EvermindCognition.js';
+export type { EvermindCognitionOptions } from './EvermindCognition.js';
+export { workspacePresenceGatherer } from './gatherers.js';
+export type { WorkspacePresenceRule } from './gatherers.js';
+export type {
+    Claim,
+    CognitionFactStore,
+    CommitResult,
+    EvidenceContext,
+    EvidenceGatherer,
+    EvidenceResult,
+    Verdict,
+} from './types.js';

package/src/cognition/types.ts

@@ -0,0 +1,88 @@
+/**
+ * Evermind — Write-Through Cognition types.
+ *
+ * The cognition layer is what lets the model's KNOWLEDGE stay current without a
+ * reconciliation step: every incoming fact is evaluated against EVIDENCE and the
+ * incumbent belief, then committed write-through (replace-on-write by a STABLE
+ * subject key) instead of being appended under a fresh per-run key. These types
+ * are intentionally store- and surface-agnostic so the same logic runs in the
+ * IDE, on-prem, cloud, and the browser.
+ */
+
+/** Outcome of evaluating a candidate fact against its incumbent + evidence. */
+export type Verdict =
+    /** No incumbent on this subject — stored as a new belief. */
+    | 'augment'
+    /** Incumbent identical — recency/confidence refreshed, nothing replaced. */
+    | 'confirm'
+    /** Incumbent conflicted and evidence favoured the new fact — replaced. */
+    | 'supersede'
+    /** Incumbent conflicted but evidence did NOT favour the new fact — dropped. */
+    | 'reject';
+
+/**
+ * Minimal write-through fact store the cognition layer needs. `MemoryStore`
+ * satisfies this structurally (no adapter required) — kept narrow so cloud
+ * (Postgres) / browser (IndexedDB) backends can satisfy it too.
+ */
+export interface CognitionFactStore {
+    remember(
+        key: string,
+        content: string,
+        opts?: { tags?: string[]; importance?: number; ttlMs?: number },
+    ): Promise<void>;
+    recall(key: string): Promise<{ content: string } | undefined>;
+    forget(key: string): Promise<void>;
+}
+
+/** A fact asserted about a subject, keyed by a STABLE canonical key. */
+export interface Claim {
+    /**
+     * STABLE canonical key naming the SUBJECT of the fact (e.g. `pkg:ssm-stack`).
+     * This is the anti-drift fix: logically-superseding facts collide on this key
+     * and replace, instead of accumulating under per-run keys.
+     */
+    subjectKey: string;
+    /** The asserted fact content. */
+    content: string;
+    tags?: string[];
+    importance?: number;
+    /**
+     * When true, a brand-new subject is only stored if the gatherer's evidence
+     * supports it (guards against recording unverified first-observations).
+     */
+    requireEvidence?: boolean;
+}
+
+/** The verdict of an evidence probe: does ground truth favour the new claim? */
+export interface EvidenceResult {
+    supportsNew: boolean;
+    /** Audit-readable lines describing what was checked and found. */
+    notes: string[];
+}
+
+export interface EvidenceContext {
+    claim: Claim;
+    /** Incumbent belief content for this subject, when one exists. */
+    incumbent?: string;
+}
+
+/**
+ * Gathers ground-truth evidence for a claim. Injected by the caller because the
+ * evidence source is surface-specific (IDE file tools, cloud DB, HTTP probe…).
+ */
+export type EvidenceGatherer = (ctx: EvidenceContext) => Promise<EvidenceResult>;
+
+/** Result of committing a claim through the cognition pipeline. */
+export interface CommitResult {
+    verdict: Verdict;
+    subjectKey: string;
+    /** The belief now held for this subject (incumbent's content on reject). */
+    content: string;
+    /** Prior content, present only when `verdict === 'supersede'`. */
+    superseded?: string;
+    /** Evidence audit trail. */
+    evidence: string[];
+    /** Knowledge-generation token after this commit (bumps on augment/supersede). */
+    version: number;
+}