chapterhouse 0.3.26 → 0.4.1

package/dist/memory/inbox.js

@@ -0,0 +1,73 @@
+import { getDb } from "../store/db.js";
+import { getActiveScope } from "./active-scope.js";
+import { getScope } from "./scopes.js";
+function toInboxItem(row) {
+    return {
+        id: row.id,
+        scopeId: row.scope_id ?? undefined,
+        kind: row.kind,
+        payload: row.payload,
+        sourceAgent: row.source_agent,
+        sourceTaskId: row.source_task_id ?? undefined,
+        status: row.status,
+        createdAt: row.created_at,
+        resolvedAt: row.resolved_at ?? undefined,
+        resolutionReason: row.resolution_reason ?? undefined,
+    };
+}
+export function resolveProposalScope(scopeSlug) {
+    if (scopeSlug) {
+        const explicit = getScope(scopeSlug);
+        if (!explicit) {
+            throw new Error(`Unknown memory scope '${scopeSlug}'.`);
+        }
+        return { scopeId: explicit.id, scopeSlug: explicit.slug };
+    }
+    const activeScope = getActiveScope();
+    if (!activeScope) {
+        throw new Error("No active memory scope is set. Use memory_set_scope or pass scope_slug explicitly.");
+    }
+    return { scopeId: activeScope.id, scopeSlug: activeScope.slug };
+}
+export function queueMemoryProposal(input) {
+    const { scopeId, scopeSlug } = resolveProposalScope(input.scopeSlug);
+    const envelope = {
+        kind: input.kind,
+        scope_slug: scopeSlug,
+        confidence: input.confidence ?? 0.5,
+        reason: input.reason,
+        payload: input.payload,
+    };
+    const result = getDb().prepare(`
+    INSERT INTO mem_inbox (scope_id, kind, payload, source_agent, source_task_id, status, created_at)
+    VALUES (?, 'memory_proposal', ?, ?, ?, 'pending', CURRENT_TIMESTAMP)
+  `).run(scopeId, JSON.stringify(envelope), input.sourceAgent, input.sourceTaskId ?? null);
+    return getInboxItem(Number(result.lastInsertRowid));
+}
+export function getInboxItem(id) {
+    const row = getDb().prepare(`
+    SELECT id, scope_id, kind, payload, source_agent, source_task_id, status, created_at, resolved_at, resolution_reason
+    FROM mem_inbox
+    WHERE id = ?
+  `).get(id);
+    return row ? toInboxItem(row) : undefined;
+}
+export function listPendingMemoryProposalsForTask(taskId) {
+    const rows = getDb().prepare(`
+    SELECT id, scope_id, kind, payload, source_agent, source_task_id, status, created_at, resolved_at, resolution_reason
+    FROM mem_inbox
+    WHERE source_task_id = ?
+      AND status = 'pending'
+      AND kind = 'memory_proposal'
+    ORDER BY id ASC
+  `).all(taskId);
+    return rows.map(toInboxItem);
+}
+export function resolveInboxItem(id, status, reason) {
+    getDb().prepare(`
+    UPDATE mem_inbox
+    SET status = ?, resolution_reason = ?, resolved_at = CURRENT_TIMESTAMP
+    WHERE id = ?
+  `).run(status, reason, id);
+}
+//# sourceMappingURL=inbox.js.map

package/dist/memory/index.js

@@ -0,0 +1,11 @@
+export { getActiveScope, inferScopeFromText, setActiveScope } from "./active-scope.js";
+export { recordDecision, getDecision, listDecisions, supersedeDecision } from "./decisions.js";
+export { getEntity, findEntityByName, listEntities, upsertEntity } from "./entities.js";
+export { getHotTierEntries, renderHotTierForActiveScope, renderHotTierXML } from "./hot-tier.js";
+export { compactInboxPass, decayPass, dedupDecisionsPass, dedupObservationsPass, isHousekeepingInFlight, orphanCleanupPass, runHousekeeping, } from "./housekeeping.js";
+export { getInboxItem, listPendingMemoryProposalsForTask, queueMemoryProposal, resolveInboxItem, resolveProposalScope } from "./inbox.js";
+export { recordObservation, getObservation, listObservations, deleteObservation } from "./observations.js";
+export { recall } from "./recall.js";
+export { createScope, deactivateScope, getScope, listScopes, updateScope } from "./scopes.js";
+export { demoteToCold, demoteToWarm, inferTierFromSignals, promoteToHot, tieringPass } from "./tiering.js";
+//# sourceMappingURL=index.js.map

package/dist/memory/observations.js

@@ -0,0 +1,46 @@
+import { getDb } from "../store/db.js";
+function toObservation(row) {
+    return {
+        id: row.id,
+        scopeId: row.scope_id,
+        entityId: row.entity_id ?? undefined,
+        content: row.content,
+        source: row.source,
+        tier: row.tier,
+        confidence: row.confidence,
+        embedding: row.embedding ?? undefined,
+        supersededBy: row.superseded_by ?? undefined,
+        archivedAt: row.archived_at ?? undefined,
+        createdAt: row.created_at,
+    };
+}
+export function recordObservation(input) {
+    const result = getDb().prepare(`
+    INSERT INTO mem_observations (scope_id, entity_id, content, source, tier, confidence, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
+  `).run(input.scope_id, input.entity_id ?? null, input.content, input.source, input.tier ?? "warm", input.confidence ?? 1.0);
+    return getObservation(Number(result.lastInsertRowid));
+}
+export function getObservation(id) {
+    const row = getDb().prepare(`
+    SELECT id, scope_id, entity_id, content, source, tier, confidence, embedding, superseded_by, archived_at, created_at
+    FROM mem_observations
+    WHERE id = ?
+  `).get(id);
+    return row ? toObservation(row) : undefined;
+}
+export function listObservations(input = {}) {
+    const rows = getDb().prepare(`
+    SELECT id, scope_id, entity_id, content, source, tier, confidence, embedding, superseded_by, archived_at, created_at
+    FROM mem_observations
+    WHERE (? IS NULL OR scope_id = ?)
+      AND (? IS NULL OR entity_id = ?)
+    ORDER BY id DESC
+    LIMIT ? OFFSET ?
+  `).all(input.scope_id ?? null, input.scope_id ?? null, input.entity_id ?? null, input.entity_id ?? null, input.limit ?? 50, input.offset ?? 0);
+    return rows.map(toObservation);
+}
+export function deleteObservation(id) {
+    getDb().prepare(`DELETE FROM mem_observations WHERE id = ?`).run(id);
+}
+//# sourceMappingURL=observations.js.map

package/dist/memory/observations.test.js

@@ -0,0 +1,86 @@
+import assert from "node:assert/strict";
+import { mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+const repoRoot = process.cwd();
+const sandboxRoot = join(repoRoot, ".test-work", `memory-observations-${process.pid}`);
+const chapterhouseHome = join(sandboxRoot, ".chapterhouse");
+process.env.CHAPTERHOUSE_HOME = sandboxRoot;
+function resetSandbox() {
+    mkdirSync(join(repoRoot, ".test-work"), { recursive: true });
+    rmSync(sandboxRoot, { recursive: true, force: true });
+    mkdirSync(chapterhouseHome, { recursive: true });
+}
+async function loadModules() {
+    const dbModule = await import(new URL("../store/db.js", import.meta.url).href);
+    const memoryModule = await import(new URL("./index.js", import.meta.url).href);
+    return { dbModule, memoryModule };
+}
+function getFunction(module, name) {
+    const value = module[name];
+    assert.equal(typeof value, "function", `expected ${name} to be exported`);
+    return value;
+}
+test.beforeEach(async () => {
+    const dbModule = await import(new URL("../store/db.js", import.meta.url).href);
+    dbModule.closeDb();
+    resetSandbox();
+});
+test.after(async () => {
+    const dbModule = await import(new URL("../store/db.js", import.meta.url).href);
+    dbModule.closeDb();
+    rmSync(sandboxRoot, { recursive: true, force: true });
+});
+test("recordObservation supports CRUD and keeps the observation FTS index in sync", async () => {
+    const { dbModule, memoryModule } = await loadModules();
+    const db = dbModule.getDb();
+    const getScope = getFunction(memoryModule, "getScope");
+    const recordObservation = getFunction(memoryModule, "recordObservation");
+    const getObservation = getFunction(memoryModule, "getObservation");
+    const listObservations = getFunction(memoryModule, "listObservations");
+    const deleteObservation = getFunction(memoryModule, "deleteObservation");
+    const chapterhouse = getScope("chapterhouse");
+    assert.ok(chapterhouse, "chapterhouse scope should be seeded");
+    const created = recordObservation({
+        scope_id: chapterhouse.id,
+        content: "SQLite WAL mode keeps Chapterhouse memory writes fast.",
+        source: "user",
+        tier: "hot",
+        confidence: 0.9,
+    });
+    assert.equal(created.content, "SQLite WAL mode keeps Chapterhouse memory writes fast.");
+    assert.deepEqual(getObservation(created.id)?.content, created.content);
+    assert.equal(listObservations({ scope_id: chapterhouse.id }).some((row) => row.id === created.id), true);
+    const initialHits = db.prepare(`
+    SELECT rowid
+    FROM mem_observations_fts
+    WHERE mem_observations_fts MATCH 'WAL'
+  `).all();
+    assert.deepEqual(initialHits, [{ rowid: created.id }]);
+    db.prepare(`
+    UPDATE mem_observations
+    SET content = ?
+    WHERE id = ?
+  `).run("FTS rebuild test for hot-tier prompts and scoped recall.", created.id);
+    const walHits = db.prepare(`
+    SELECT rowid
+    FROM mem_observations_fts
+    WHERE mem_observations_fts MATCH 'WAL'
+  `).all();
+    const rebuildHits = db.prepare(`
+    SELECT rowid
+    FROM mem_observations_fts
+    WHERE mem_observations_fts MATCH 'rebuild'
+  `).all();
+    assert.deepEqual(walHits, []);
+    assert.deepEqual(rebuildHits, [{ rowid: created.id }]);
+    deleteObservation(created.id);
+    assert.equal(getObservation(created.id), undefined);
+    const postDeleteHits = db.prepare(`
+    SELECT rowid
+    FROM mem_observations_fts
+    WHERE mem_observations_fts MATCH 'rebuild'
+  `).all();
+    assert.deepEqual(postDeleteHits, []);
+});
+//# sourceMappingURL=observations.test.js.map

package/dist/memory/recall.js

@@ -0,0 +1,210 @@
+import { config } from "../config.js";
+import { getDb, isFts5Available } from "../store/db.js";
+import { getActiveScope } from "./active-scope.js";
+function quoteFts5QueryTerms(query) {
+    return query
+        .trim()
+        .split(/\s+/)
+        .filter((term) => term.length > 0)
+        .map((term) => {
+        const unquoted = term.replace(/^["']|["']$/g, "");
+        return `"${unquoted.replace(/"/g, "\"\"")}"`;
+    })
+        .join(" ");
+}
+function recallHotTier(scopeId, options = {}) {
+    const rows = getDb().prepare(`
+    SELECT 'observation' AS kind, id, content
+    FROM mem_observations
+    WHERE scope_id = ? AND tier = 'hot'
+      AND (? = 1 OR superseded_by IS NULL)
+      AND (? = 1 OR archived_at IS NULL)
+    UNION ALL
+    SELECT 'decision' AS kind, id, title || ' — ' || rationale AS content
+    FROM mem_decisions
+    WHERE scope_id = ? AND tier = 'hot'
+      AND (? = 1 OR superseded_by IS NULL)
+      AND (? = 1 OR archived_at IS NULL)
+    UNION ALL
+    SELECT 'entity' AS kind, id, name || COALESCE(' — ' || summary, '') AS content
+    FROM mem_entities
+    WHERE scope_id = ? AND tier = 'hot'
+    ORDER BY id DESC
+    LIMIT 10
+  `).all(scopeId, options.includeSuperseded ? 1 : 0, options.includeArchived ? 1 : 0, scopeId, options.includeSuperseded ? 1 : 0, options.includeArchived ? 1 : 0, scopeId);
+    return rows;
+}
+function recallObservationHits(query, scopeId, options = {}) {
+    if (isFts5Available()) {
+        const ftsQuery = quoteFts5QueryTerms(query);
+        const rows = getDb().prepare(`
+      SELECT
+        o.id,
+        o.scope_id,
+        s.slug AS scope,
+        o.content,
+        o.tier,
+        -bm25(mem_observations_fts) * CASE WHEN o.tier = 'hot' THEN ? ELSE 1 END AS score,
+        snippet(mem_observations_fts, 0, '[', ']', '…', 12) AS snippet
+      FROM mem_observations o
+      JOIN mem_scopes s ON s.id = o.scope_id
+      JOIN mem_observations_fts ON mem_observations_fts.rowid = o.id
+      WHERE mem_observations_fts MATCH ?
+        AND (? IS NULL OR o.scope_id = ?)
+        AND (? = 1 OR o.tier != 'cold')
+        AND (? = 1 OR o.superseded_by IS NULL)
+        AND (? = 1 OR o.archived_at IS NULL)
+      ORDER BY score DESC, o.id DESC
+    `).all(config.memoryHotRecallBoost, ftsQuery, scopeId ?? null, scopeId ?? null, options.includeCold ? 1 : 0, options.includeSuperseded ? 1 : 0, options.includeArchived ? 1 : 0);
+        return rows.map((row) => ({
+            kind: "observation",
+            id: row.id,
+            scopeId: row.scope_id,
+            scope: row.scope,
+            content: row.content,
+            score: row.score,
+            snippet: row.snippet ?? row.content,
+        }));
+    }
+    const pattern = `%${query}%`;
+    const rows = getDb().prepare(`
+    SELECT o.id, o.scope_id, s.slug AS scope, o.content, o.tier
+    FROM mem_observations o
+    JOIN mem_scopes s ON s.id = o.scope_id
+    WHERE (? IS NULL OR o.scope_id = ?)
+      AND (? = 1 OR o.tier != 'cold')
+      AND (? = 1 OR o.superseded_by IS NULL)
+      AND (? = 1 OR o.archived_at IS NULL)
+      AND o.content LIKE ?
+    ORDER BY o.id DESC
+  `).all(scopeId ?? null, scopeId ?? null, options.includeCold ? 1 : 0, options.includeSuperseded ? 1 : 0, options.includeArchived ? 1 : 0, pattern);
+    return rows.map((row) => ({
+        kind: "observation",
+        id: row.id,
+        scopeId: row.scope_id,
+        scope: row.scope,
+        content: row.content,
+        score: row.tier === "hot" ? config.memoryHotRecallBoost : 1,
+        snippet: row.content,
+    }));
+}
+function recallDecisionHits(query, scopeId, options = {}) {
+    if (isFts5Available()) {
+        const ftsQuery = quoteFts5QueryTerms(query);
+        const rows = getDb().prepare(`
+      SELECT
+        d.id,
+        d.scope_id,
+        s.slug AS scope,
+        d.title,
+        d.rationale,
+        d.decided_at,
+        d.tier,
+        -bm25(mem_decisions_fts) * CASE WHEN d.tier = 'hot' THEN ? ELSE 1 END AS score,
+        snippet(mem_decisions_fts, 0, '[', ']', '…', 8) || ' — ' ||
+          snippet(mem_decisions_fts, 1, '[', ']', '…', 12) AS snippet
+      FROM mem_decisions d
+      JOIN mem_scopes s ON s.id = d.scope_id
+      JOIN mem_decisions_fts ON mem_decisions_fts.rowid = d.id
+      WHERE mem_decisions_fts MATCH ?
+        AND (? IS NULL OR d.scope_id = ?)
+        AND (? = 1 OR d.tier != 'cold')
+        AND (? = 1 OR d.superseded_by IS NULL)
+        AND (? = 1 OR d.archived_at IS NULL)
+      ORDER BY score DESC, d.id DESC
+    `).all(config.memoryHotRecallBoost, ftsQuery, scopeId ?? null, scopeId ?? null, options.includeCold ? 1 : 0, options.includeSuperseded ? 1 : 0, options.includeArchived ? 1 : 0);
+        return rows.map((row) => ({
+            kind: "decision",
+            id: row.id,
+            scopeId: row.scope_id,
+            scope: row.scope,
+            content: `${row.title} — ${row.rationale}`,
+            decidedAt: row.decided_at,
+            score: row.score,
+            snippet: row.snippet ?? `${row.title} — ${row.rationale}`,
+        }));
+    }
+    const pattern = `%${query}%`;
+    const rows = getDb().prepare(`
+    SELECT d.id, d.scope_id, s.slug AS scope, d.title, d.rationale, d.decided_at, d.tier
+    FROM mem_decisions d
+    JOIN mem_scopes s ON s.id = d.scope_id
+    WHERE (? IS NULL OR d.scope_id = ?)
+      AND (? = 1 OR d.tier != 'cold')
+      AND (? = 1 OR d.superseded_by IS NULL)
+      AND (? = 1 OR d.archived_at IS NULL)
+      AND (d.title LIKE ? OR d.rationale LIKE ?)
+    ORDER BY d.decided_at DESC, d.id DESC
+  `).all(scopeId ?? null, scopeId ?? null, options.includeCold ? 1 : 0, options.includeSuperseded ? 1 : 0, options.includeArchived ? 1 : 0, pattern, pattern);
+    return rows.map((row) => ({
+        kind: "decision",
+        id: row.id,
+        scopeId: row.scope_id,
+        scope: row.scope,
+        content: `${row.title} — ${row.rationale}`,
+        decidedAt: row.decided_at,
+        score: row.tier === "hot" ? config.memoryHotRecallBoost : 1,
+        snippet: `${row.title} — ${row.rationale}`,
+    }));
+}
+function recallEntityHits(query, scopeId, options = {}) {
+    const pattern = `%${query}%`;
+    const rows = getDb().prepare(`
+    SELECT e.id, e.scope_id, s.slug AS scope, e.name, e.summary, e.tier
+    FROM mem_entities e
+    JOIN mem_scopes s ON s.id = e.scope_id
+    WHERE (? IS NULL OR e.scope_id = ?)
+      AND (e.name LIKE ? OR COALESCE(e.summary, '') LIKE ?)
+      AND (? = 1 OR e.tier != 'cold')
+    ORDER BY e.updated_at DESC, e.id DESC
+  `).all(scopeId ?? null, scopeId ?? null, pattern, pattern, options.includeCold ? 1 : 0);
+    return rows.map((row) => ({
+        kind: "entity",
+        id: row.id,
+        scopeId: row.scope_id,
+        scope: row.scope,
+        content: `${row.name}${row.summary ? ` — ${row.summary}` : ""}`,
+        score: (row.name.toLowerCase().includes(query.toLowerCase()) ? 2 : 1)
+            * (row.tier === "hot" ? config.memoryHotRecallBoost : 1),
+        snippet: `${row.name}${row.summary ? ` — ${row.summary}` : ""}`,
+    }));
+}
+export function recall(input) {
+    const activeScope = getActiveScope();
+    const effectiveScopeId = input.scope_id ?? activeScope?.id;
+    const requestedKinds = new Set(input.kinds ?? ["observation", "decision", "entity"]);
+    const hotTier = activeScope && (!effectiveScopeId || activeScope.id === effectiveScopeId)
+        ? recallHotTier(activeScope.id, input)
+        : [];
+    const hits = [
+        ...(requestedKinds.has("observation") ? recallObservationHits(input.query, effectiveScopeId, input) : []),
+        ...(requestedKinds.has("decision") ? recallDecisionHits(input.query, effectiveScopeId, input) : []),
+        ...(requestedKinds.has("entity") ? recallEntityHits(input.query, effectiveScopeId, input) : []),
+    ]
+        .sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return b.id - a.id;
+    })
+        .slice(0, input.limit ?? 10);
+    if (hits.length > 0) {
+        const db = getDb();
+        const tables = {
+            observation: "mem_observations",
+            decision: "mem_decisions",
+            entity: "mem_entities",
+        };
+        for (const kind of Object.keys(tables)) {
+            const ids = hits.filter((hit) => hit.kind === kind).map((hit) => hit.id);
+            if (ids.length > 0) {
+                db.prepare(`UPDATE ${tables[kind]} SET last_recalled_at = CURRENT_TIMESTAMP WHERE id IN (${ids.map(() => "?").join(",")})`).run(...ids);
+            }
+        }
+    }
+    return {
+        activeScope,
+        hotTier,
+        hits,
+    };
+}
+//# sourceMappingURL=recall.js.map

package/dist/memory/recall.test.js

@@ -0,0 +1,238 @@
+import assert from "node:assert/strict";
+import { mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+const repoRoot = process.cwd();
+const sandboxRoot = join(repoRoot, ".test-work", `memory-recall-${process.pid}`);
+const chapterhouseHome = join(sandboxRoot, ".chapterhouse");
+process.env.CHAPTERHOUSE_HOME = sandboxRoot;
+function resetSandbox() {
+    mkdirSync(join(repoRoot, ".test-work"), { recursive: true });
+    rmSync(sandboxRoot, { recursive: true, force: true });
+    mkdirSync(chapterhouseHome, { recursive: true });
+}
+async function loadModules() {
+    const dbModule = await import(new URL("../store/db.js", import.meta.url).href);
+    const memoryModule = await import(new URL("./index.js", import.meta.url).href);
+    return { dbModule, memoryModule };
+}
+function getFunction(module, name) {
+    const value = module[name];
+    assert.equal(typeof value, "function", `expected ${name} to be exported`);
+    return value;
+}
+test.beforeEach(async () => {
+    const dbModule = await import(new URL("../store/db.js", import.meta.url).href);
+    dbModule.closeDb();
+    resetSandbox();
+});
+test.after(async () => {
+    const dbModule = await import(new URL("../store/db.js", import.meta.url).href);
+    dbModule.closeDb();
+    rmSync(sandboxRoot, { recursive: true, force: true });
+});
+test("recall returns active-scope hot-tier entries before ranked FTS hits and respects filters", async () => {
+    const { dbModule, memoryModule } = await loadModules();
+    dbModule.getDb();
+    const getScope = getFunction(memoryModule, "getScope");
+    const setActiveScope = getFunction(memoryModule, "setActiveScope");
+    const recordObservation = getFunction(memoryModule, "recordObservation");
+    const recordDecision = getFunction(memoryModule, "recordDecision");
+    const upsertEntity = getFunction(memoryModule, "upsertEntity");
+    const recall = getFunction(memoryModule, "recall");
+    const chapterhouse = getScope("chapterhouse");
+    const global = getScope("global");
+    assert.ok(chapterhouse && global, "seeded scopes should be available");
+    setActiveScope("chapterhouse");
+    const hotObservation = recordObservation({
+        scope_id: chapterhouse.id,
+        content: "Hot memory: build with npm run build before releasing scoped memory changes.",
+        source: "user",
+        tier: "hot",
+    });
+    const bestDecision = recordDecision({
+        scope_id: chapterhouse.id,
+        title: "Use SQLite FTS5 for scoped recall",
+        rationale: "SQLite FTS5 gives ranked scoped recall and snippet generation for agent memory.",
+        decided_at: "2026-05-13",
+    });
+    recordObservation({
+        scope_id: chapterhouse.id,
+        content: "SQLite recall fallback exists, but FTS5 is preferred for ranked snippet output.",
+        source: "user",
+        tier: "warm",
+    });
+    recordObservation({
+        scope_id: global.id,
+        content: "Global memory should not leak into chapterhouse-scoped recall.",
+        source: "user",
+        tier: "hot",
+    });
+    upsertEntity({
+        scope_id: chapterhouse.id,
+        kind: "tool",
+        name: "better-sqlite3",
+        summary: "SQLite driver backing FTS5 recall and scope settings.",
+        tier: "warm",
+        confidence: 0.9,
+    });
+    const full = recall({ query: "SQLite FTS5 scoped recall", scope_id: chapterhouse.id, limit: 10 });
+    assert.equal(full.activeScope?.slug, "chapterhouse");
+    assert.equal(full.hotTier.some((entry) => entry.id === hotObservation.id), true);
+    assert.equal(full.hits.some((entry) => entry.id === bestDecision.id && entry.kind === "decision"), true);
+    assert.equal(full.hits.every((entry) => entry.snippet.toLowerCase().includes("sqlite")), true);
+    assert.equal(full.hits[0]?.id, bestDecision.id);
+    const decisionOnly = recall({
+        query: "SQLite FTS5 scoped recall",
+        scope_id: chapterhouse.id,
+        kinds: ["decision"],
+        limit: 10,
+    });
+    assert.equal(decisionOnly.hits.every((entry) => entry.kind === "decision"), true);
+    const limited = recall({
+        query: "SQLite FTS5 scoped recall",
+        scope_id: chapterhouse.id,
+        limit: 1,
+    });
+    assert.equal(limited.hits.length, 1);
+});
+test("recall excludes superseded and archived rows by default with opt-in inclusion", async () => {
+    const { dbModule, memoryModule } = await loadModules();
+    const db = dbModule.getDb();
+    const getScope = getFunction(memoryModule, "getScope");
+    const recordObservation = getFunction(memoryModule, "recordObservation");
+    const recordDecision = getFunction(memoryModule, "recordDecision");
+    const recall = getFunction(memoryModule, "recall");
+    const chapterhouse = getScope("chapterhouse");
+    assert.ok(chapterhouse);
+    const liveObservation = recordObservation({
+        scope_id: chapterhouse.id,
+        content: "retention sentinel live observation",
+        source: "test",
+    });
+    const supersededObservation = recordObservation({
+        scope_id: chapterhouse.id,
+        content: "retention sentinel superseded observation",
+        source: "test",
+    });
+    const archivedObservation = recordObservation({
+        scope_id: chapterhouse.id,
+        content: "retention sentinel archived observation",
+        source: "test",
+    });
+    const liveDecision = recordDecision({
+        scope_id: chapterhouse.id,
+        title: "retention sentinel live decision",
+        rationale: "visible decision",
+    });
+    const supersededDecision = recordDecision({
+        scope_id: chapterhouse.id,
+        title: "retention sentinel superseded decision",
+        rationale: "hidden decision",
+        decided_at: "2026-05-12",
+    });
+    const archivedDecision = recordDecision({
+        scope_id: chapterhouse.id,
+        title: "retention sentinel archived decision",
+        rationale: "hidden decision",
+        decided_at: "2026-05-11",
+    });
+    db.prepare(`UPDATE mem_observations SET superseded_by = ? WHERE id = ?`).run(liveObservation.id, supersededObservation.id);
+    db.prepare(`UPDATE mem_observations SET archived_at = CURRENT_TIMESTAMP WHERE id = ?`).run(archivedObservation.id);
+    db.prepare(`UPDATE mem_decisions SET superseded_by = ? WHERE id = ?`).run(liveDecision.id, supersededDecision.id);
+    db.prepare(`UPDATE mem_decisions SET archived_at = CURRENT_TIMESTAMP WHERE id = ?`).run(archivedDecision.id);
+    const defaults = recall({ query: "retention sentinel", scope_id: chapterhouse.id, limit: 20 });
+    assert.equal(defaults.hits.some((hit) => hit.id === liveObservation.id && hit.kind === "observation"), true);
+    assert.equal(defaults.hits.some((hit) => hit.id === liveDecision.id && hit.kind === "decision"), true);
+    assert.equal(defaults.hits.some((hit) => hit.id === supersededObservation.id && hit.kind === "observation"), false);
+    assert.equal(defaults.hits.some((hit) => hit.id === archivedObservation.id && hit.kind === "observation"), false);
+    assert.equal(defaults.hits.some((hit) => hit.id === supersededDecision.id && hit.kind === "decision"), false);
+    assert.equal(defaults.hits.some((hit) => hit.id === archivedDecision.id && hit.kind === "decision"), false);
+    const included = recall({
+        query: "retention sentinel",
+        scope_id: chapterhouse.id,
+        limit: 20,
+        includeSuperseded: true,
+        includeArchived: true,
+    });
+    assert.equal(included.hits.some((hit) => hit.id === supersededObservation.id && hit.kind === "observation"), true);
+    assert.equal(included.hits.some((hit) => hit.id === archivedObservation.id && hit.kind === "observation"), true);
+    assert.equal(included.hits.some((hit) => hit.id === supersededDecision.id && hit.kind === "decision"), true);
+    assert.equal(included.hits.some((hit) => hit.id === archivedDecision.id && hit.kind === "decision"), true);
+});
+test("recall boosts hot rows and excludes cold rows unless includeCold is set", async () => {
+    const { dbModule, memoryModule } = await loadModules();
+    dbModule.getDb();
+    const getScope = getFunction(memoryModule, "getScope");
+    const recordObservation = getFunction(memoryModule, "recordObservation");
+    const recall = getFunction(memoryModule, "recall");
+    const chapterhouse = getScope("chapterhouse");
+    assert.ok(chapterhouse);
+    const warm = recordObservation({
+        scope_id: chapterhouse.id,
+        content: "tierboost sentinel equal lexical match",
+        source: "test",
+        tier: "warm",
+    });
+    const hot = recordObservation({
+        scope_id: chapterhouse.id,
+        content: "tierboost sentinel equal lexical match",
+        source: "test",
+        tier: "hot",
+    });
+    const cold = recordObservation({
+        scope_id: chapterhouse.id,
+        content: "tierboost sentinel cold lexical match",
+        source: "test",
+        tier: "cold",
+    });
+    const defaults = recall({ query: "tierboost sentinel", scope_id: chapterhouse.id, kinds: ["observation"], limit: 10 });
+    assert.equal(defaults.hits[0]?.id, hot.id);
+    assert.equal(defaults.hits.some((hit) => hit.id === warm.id), true);
+    assert.equal(defaults.hits.some((hit) => hit.id === cold.id), false);
+    const withCold = recall({ query: "tierboost sentinel", scope_id: chapterhouse.id, kinds: ["observation"], limit: 10, includeCold: true });
+    assert.equal(withCold.hits.some((hit) => hit.id === cold.id), true);
+});
+test("recall matches multi-word observation queries with exact tokens", async () => {
+    const { dbModule, memoryModule } = await loadModules();
+    dbModule.getDb();
+    const getScope = getFunction(memoryModule, "getScope");
+    const recordObservation = getFunction(memoryModule, "recordObservation");
+    const recall = getFunction(memoryModule, "recall");
+    const chapterhouse = getScope("chapterhouse");
+    assert.ok(chapterhouse);
+    const observation = recordObservation({
+        scope_id: chapterhouse.id,
+        content: "Chapterhouse memory P1 shipped on 2026-05-13",
+        source: "test",
+    });
+    const result = recall({
+        query: "memory P1 shipped",
+        scope_id: chapterhouse.id,
+        kinds: ["observation"],
+        limit: 10,
+    });
+    assert.equal(result.hits.some((hit) => hit.id === observation.id), true);
+});
+test("recall treats hyphenated observation query terms literally", async () => {
+    const { dbModule, memoryModule } = await loadModules();
+    dbModule.getDb();
+    const getScope = getFunction(memoryModule, "getScope");
+    const recordObservation = getFunction(memoryModule, "recordObservation");
+    const recall = getFunction(memoryModule, "recall");
+    const chapterhouse = getScope("chapterhouse");
+    assert.ok(chapterhouse);
+    const observation = recordObservation({
+        scope_id: chapterhouse.id,
+        content: "Chapterhouse agent-memory recall shipped safely",
+        source: "test",
+    });
+    const result = recall({
+        query: "agent-memory",
+        scope_id: chapterhouse.id,
+        kinds: ["observation"],
+        limit: 10,
+    });
+    assert.equal(result.hits.some((hit) => hit.id === observation.id), true);
+});
+//# sourceMappingURL=recall.test.js.map