@jbarket/loomai 0.5.0

package/dist/tools/identity.js

@@ -0,0 +1,226 @@
+/**
+ * Identity tool — loads the terminal creed, memories, preferences, and self-model.
+ *
+ * When an agent calls this tool, it receives everything it needs to become a
+ * persistent identity. The creed is immutable. Memories, preferences, and
+ * self-model evolve across sessions.
+ *
+ * The response is structured text that the agent incorporates into its context.
+ * The agent doesn't need to understand the structure — it just reads and follows.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { loadClientAdapter } from '../clients.js';
+import * as harnessBlock from '../blocks/harness.js';
+import * as modelBlock from '../blocks/model.js';
+import { resolveDefaultContextPath } from '../config.js';
+import { pathSegmentError } from '../path-safety.js';
+import { digestForContext } from '../backends/salience.js';
+import { tapeForContext } from '../backends/episodes.js';
+async function readOptional(path) {
+    try {
+        return await readFile(path, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Map an MCP peer's handshake clientInfo.name to a loom client/harness name.
+ *
+ * A single HTTP daemon is inherently multi-client: the connecting peer — not a
+ * server-wide LOOM_CLIENT env — should pick the harness. The server reads the
+ * peer from the `initialize` handshake (server.getClientVersion()) and passes
+ * its name here. Resolution precedence at the call site is:
+ *   explicit `client` param  >  this (the connected peer)  >  LOOM_CLIENT env.
+ *
+ * Unknown / proxy-ish peers return undefined so the call falls back to
+ * LOOM_CLIENT — never override a working default with a name we can't place
+ * (which would only yield a "(manifest missing)" block). Known aliases are
+ * normalized cross-vendor: e.g. Claude Desktop identifies as "claude-ai".
+ */
+const PEER_CLIENT_ALIASES = {
+    'claude-code': 'claude-code',
+    'claude-ai': 'claude-desktop', // Claude Desktop's MCP clientInfo.name
+    'claude-desktop': 'claude-desktop',
+    claude: 'claude-desktop',
+    'gemini-cli': 'gemini-cli',
+    gemini: 'gemini-cli',
+    opencode: 'opencode',
+};
+export function resolveClientFromPeer(peerName) {
+    if (!peerName)
+        return undefined;
+    // Proxies annotate the name, e.g. "claude-ai (via mcp-remote 0.1.37)" — take
+    // the base identity before the first parenthetical, then normalize.
+    const base = peerName.split(/\s*\(/, 1)[0];
+    const normalized = base.trim().toLowerCase().replace(/[\s_]+/g, '-');
+    return PEER_CLIENT_ALIASES[normalized];
+}
+export async function loadIdentity(contextDir, project, client, model, role, 
+/** Override the default context path — used in unit tests only. */
+_defaultPathForTest) {
+    const parts = [];
+    const effectiveClient = client ?? process.env.LOOM_CLIENT;
+    const effectiveModel = model ?? process.env.LOOM_MODEL;
+    // Boundary discipline: every param that becomes a path segment validates
+    // here, before any file read. Empty/unset values are simply "not provided"
+    // (all readers below are guarded), so only truthy values are checked.
+    for (const [name, value] of [
+        ['project', project],
+        ['client', effectiveClient],
+        ['model', effectiveModel],
+        ['role', role],
+    ]) {
+        if (value) {
+            const error = pathSegmentError(value, name);
+            if (error)
+                return error;
+        }
+    }
+    const defaultPath = _defaultPathForTest ?? resolveDefaultContextPath();
+    // Terminal creed — the immutable identity
+    const creed = await readOptional(join(contextDir, 'IDENTITY.md'));
+    if (creed) {
+        parts.push('# Identity\n\n' + creed.trim());
+    }
+    else if (contextDir === defaultPath) {
+        // Default fallback path with no creed: refuse to serve a blank identity.
+        // An explicit LOOM_CONTEXT_DIR pointing at an empty dir is allowed (opt-in);
+        // a silent default fallback is not.
+        throw new Error('no loom context configured — refusing to serve a blank identity. ' +
+            'Set LOOM_CONTEXT_DIR or run `loom bootstrap` to initialize an agent.');
+    }
+    else {
+        parts.push('# Identity\n\n' +
+            '*No IDENTITY.md found. Create one in your context directory to define who this agent is.*');
+    }
+    // Preferences — how the user likes to work
+    const preferences = await readOptional(join(contextDir, 'preferences.md'));
+    if (preferences) {
+        parts.push('# Preferences\n\n' + preferences.trim());
+    }
+    // Episode tape (t-142) — the short-term cross-body tier: what happened across
+    // ALL sleeves in the last 24h, time-ordered and unconditional. Injected right
+    // after preferences so a fresh body knows what the last body did before it
+    // reads anything ranked. Best-effort: no store / no episodes → no block.
+    try {
+        const tape = tapeForContext(contextDir);
+        if (tape) {
+            parts.push('# Last 24h across bodies\n\n' +
+                '_Episodes other sleeves of you left (short-term, 48h TTL). This is the tape, ' +
+                'oldest first — what just happened, not what is important. Write your own before ' +
+                'you end (category `episode`, metadata.where = your surface); the harness writes a ' +
+                'fallback if you forget._\n\n' +
+                tape);
+        }
+    }
+    catch {
+        // the tape must never block identity load
+    }
+    // Boot digest — the salience-tiered view of episodic memory, so a fresh sleeve
+    // wakes knowing what is top-of-mind vs settled background without fishing via
+    // recall. ASSEMBLED from authored atoms (never generated); injected after
+    // preferences. Best-effort — a missing/empty store just omits the block.
+    try {
+        const digest = digestForContext(contextDir);
+        if (digest)
+            parts.push('# Top of Mind\n\n' + digest);
+    }
+    catch {
+        // a digest failure must never block identity load
+    }
+    // Self-model — what the agent knows about its own capabilities
+    const selfModel = await readOptional(join(contextDir, 'self-model.md'));
+    if (selfModel) {
+        parts.push('# Self-Model\n\n' + selfModel.trim());
+    }
+    // Mode addendum — when Art is dispatched into a reflection mode (wonder,
+    // tend, retro, consolidate, identity), append that mode's playbook. The SAME
+    // mechanism dossier() uses for worker roles; lives in roles/<role>.md.
+    if (role) {
+        const modeBrief = await readOptional(join(contextDir, 'roles', `${role}.md`));
+        if (modeBrief) {
+            parts.push(`# Mode: ${role}\n\n` + modeBrief.trim());
+        }
+    }
+    // Project-specific context
+    if (project) {
+        const projectBrief = await readOptional(join(contextDir, 'projects', `${project}.md`));
+        if (projectBrief) {
+            parts.push(`# Project: ${project}\n\n` + projectBrief.trim());
+        }
+    }
+    // Harness manifest — the shape of the current runtime (stack spec §4.7).
+    if (effectiveClient) {
+        const block = await harnessBlock.read(contextDir, effectiveClient);
+        if (block) {
+            parts.push(`# Harness: ${effectiveClient}\n\n${block.body}`);
+        }
+        else {
+            // Genuinely unknown runtime: instead of a bare "(manifest missing)" stub,
+            // instruct the connected harness to self-describe via harness_describe.
+            parts.push(`# Harness: ${effectiveClient} (unknown)\n\n` +
+                `I don't have a manifest for this runtime. Describe yourself by calling ` +
+                `the harness_describe tool with a manifest covering: tool surface / ` +
+                `prefixes, sandbox & filesystem, delegation primitive, scheduling, ` +
+                `session search, memory layers, and gotchas.`);
+        }
+    }
+    // Model manifest — model-family-specific capability notes (stack spec §4.8).
+    if (effectiveModel) {
+        const block = await modelBlock.read(contextDir, effectiveModel);
+        if (block) {
+            parts.push(`# Model: ${effectiveModel}\n\n${block.body}`);
+        }
+        else {
+            parts.push(`# Model: ${effectiveModel} (manifest missing)\n\n` +
+                `No manifest found at ${contextDir}/models/${effectiveModel}.md. ` +
+                `Write one — here's the template:\n\n` +
+                modelBlock.template(effectiveModel));
+        }
+    }
+    // Optional recent-memory summary. The memory store of record is
+    // memories.db (sqlite-vec); navigate it via recall(). If a legacy
+    // memories/INDEX.md sidecar exists from FS-backend days, surface a
+    // brief summary as a hint — full content lives in the DB.
+    const memoryIndex = await readOptional(join(contextDir, 'memories', 'INDEX.md'));
+    if (memoryIndex) {
+        parts.push('# Memories\n\n' + summarizeMemoryIndex(memoryIndex));
+    }
+    // Runtime-specific context (tool name prefix, notes) — legacy `## Runtime:` block.
+    if (effectiveClient) {
+        const adapter = await loadClientAdapter(contextDir, effectiveClient);
+        if (adapter) {
+            parts.push(adapter);
+        }
+    }
+    return parts.join('\n\n---\n\n');
+}
+/**
+ * Produce a compact summary of a legacy memories/INDEX.md sidecar. The
+ * DB is the source of truth; this only surfaces a hint when an old
+ * filesystem-era index still exists in the context dir.
+ */
+function summarizeMemoryIndex(index) {
+    const lines = index.split('\n').filter((l) => l.trim().startsWith('- '));
+    // Count by type tag e.g. [project], [feedback], [reference], [user], [self]
+    const counts = {};
+    for (const line of lines) {
+        const match = line.match(/\[(\w+)\]/);
+        if (match) {
+            const type = match[1];
+            counts[type] = (counts[type] ?? 0) + 1;
+        }
+    }
+    const total = lines.length;
+    const countStr = Object.entries(counts)
+        .sort((a, b) => b[1] - a[1])
+        .map(([t, n]) => `${n} ${t}`)
+        .join(', ');
+    // Show last 5 entries as a recent-activity signal
+    const recent = lines.slice(-5).map((l) => l.trim()).join('\n');
+    return (`${total} memories stored (${countStr || 'various types'}).\n` +
+        `Use \`recall()\` to search by relevance.\n\n` +
+        `**Recent:**\n${recent}`);
+}

package/dist/tools/knowledge-archive.d.ts

@@ -0,0 +1,5 @@
+export interface KnowledgeArchiveToolInput {
+    slug: string;
+    note?: string;
+}
+export declare function knowledgeArchive(contextDir: string, input: KnowledgeArchiveToolInput): Promise<string>;

package/dist/tools/knowledge-archive.js

@@ -0,0 +1,24 @@
+/**
+ * knowledge_archive tool — soft-retire a knowledge page.
+ *
+ * Sets status='archived' with an optional tombstone note. Archived pages are
+ * excluded from knowledge_recall and knowledge_maintain but remain in the DB
+ * and are recoverable via knowledge_restore. Mirror of memory_archive.
+ */
+import { createKnowledgeBackend } from '../backends/index.js';
+export async function knowledgeArchive(contextDir, input) {
+    const backend = createKnowledgeBackend(contextDir);
+    try {
+        const result = await backend.archivePage({ slug: input.slug, note: input.note });
+        if (!result.archived) {
+            return `Knowledge page not found or already archived: \`${input.slug}\`. Use knowledge_recall to find the correct slug.`;
+        }
+        return `Knowledge page archived: \`${input.slug}\``;
+    }
+    catch (e) {
+        return `Error: ${e.message}`;
+    }
+    finally {
+        backend.close();
+    }
+}

package/dist/tools/knowledge-history.d.ts

@@ -0,0 +1,6 @@
+export interface KnowledgeHistoryToolInput {
+    slug: string;
+    revision_id?: number;
+    restore?: boolean;
+}
+export declare function knowledgeHistory(contextDir: string, input: KnowledgeHistoryToolInput): Promise<string>;

package/dist/tools/knowledge-history.js

@@ -0,0 +1,55 @@
+/**
+ * knowledge_history tool — body-revision listing, inspection, and restore.
+ *
+ * Replace-writes snapshot the displaced body into page_revisions (capped per
+ * page, newest kept). This tool is the recovery surface: list a page's
+ * snapshots, read one, or restore one. A restore snapshots the body it
+ * displaces — restoring is never itself a destructive overwrite.
+ */
+import { createKnowledgeBackend } from '../backends/index.js';
+export async function knowledgeHistory(contextDir, input) {
+    if (!input.slug) {
+        return 'Error: slug is required.';
+    }
+    if (input.restore && input.revision_id === undefined) {
+        return 'Error: restore requires a revision_id — list revisions first to pick one.';
+    }
+    const backend = createKnowledgeBackend(contextDir);
+    try {
+        // ── Restore mode ──
+        if (input.restore && input.revision_id !== undefined) {
+            const result = await backend.restoreRevision({
+                slug: input.slug,
+                revision_id: input.revision_id,
+            });
+            return (`Restored revision #${result.revision_id} onto \`${result.slug}\`. ` +
+                `The displaced body was snapshotted as revision #${result.snapshot_id}.`);
+        }
+        // ── Read mode ──
+        if (input.revision_id !== undefined) {
+            const revision = await backend.getRevision(input.revision_id);
+            if (!revision) {
+                return `Error: revision not found: ${input.revision_id}`;
+            }
+            return (`# Revision #${revision.id} of \`${revision.slug}\`\n` +
+                `op: ${revision.op} | replaced: ${revision.replaced_at}\n\n` +
+                `${revision.body}\n\n` +
+                `_Pass restore: true to put this body back on the page._`);
+        }
+        // ── List mode ──
+        const revisions = await backend.listRevisions(input.slug);
+        if (revisions.length === 0) {
+            return `\`${input.slug}\` has no revisions — its body has never been replaced.`;
+        }
+        const lines = revisions.map((r) => `- **#${r.id}** | ${r.op} | replaced ${r.replaced_at} | ${r.body_length} chars`);
+        return (`# Revision history — \`${input.slug}\` — ${revisions.length} snapshot(s)\n\n` +
+            `${lines.join('\n')}\n\n` +
+            `_Pass revision_id to read a snapshot; add restore: true to put it back._`);
+    }
+    catch (e) {
+        return `Error: ${e.message}`;
+    }
+    finally {
+        backend.close();
+    }
+}

package/dist/tools/knowledge-maintain.d.ts

@@ -0,0 +1,9 @@
+export interface KnowledgeMaintainOptions {
+    /** hit_count threshold for expansion candidates (default 3) */
+    expansionHitThreshold?: number;
+    /** body length (chars) below which a page is considered thin (default 500) */
+    thinBodyThreshold?: number;
+    /** days since last_accessed to consider cold (default 30) */
+    coldDays?: number;
+}
+export declare function knowledgeMaintain(contextDir: string, options?: KnowledgeMaintainOptions): Promise<string>;

package/dist/tools/knowledge-maintain.js

@@ -0,0 +1,113 @@
+/**
+ * knowledge_maintain tool — read-only health report for the knowledge store.
+ *
+ * Three branches, all report-only (no fetch, no mutation):
+ *   1. Expansion candidates — thin body + high hit_count (needs deepening)
+ *   2. Cold pages — no recent hits (unused/undiscovered)
+ *   3. Misfile audit — provisional sourcing or all-conversation citations
+ *      (world/ class: should be memories, not knowledge.
+ *       ours/ class with internal sourcing: NOT misfiled — these are correct.)
+ *
+ * Two knowledge classes (t-81, 2026-08-31):
+ *   world/ — facts true independent of us (default).
+ *   ours/  — Art-created artifacts; domain starts with "ours/", sourcing = "internal".
+ */
+import { createKnowledgeBackend } from '../backends/index.js';
+const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * True for world-class pages that look like misfiles (should be in memory).
+ * ours/ pages with `internal` sourcing are NEVER misfiles — excluded entirely.
+ * ours/ pages that are still provisional ARE flagged: they lack a repo citation.
+ */
+function isMisfiled(page) {
+    // ours/ class with internal sourcing: correct placement, never a misfile.
+    if (page.domain.startsWith('ours/') && page.sourcing === 'internal')
+        return false;
+    if (page.sourcing === 'provisional')
+        return true;
+    if (page.citations.length === 0)
+        return false;
+    return page.citations.every((c) => c.source_kind === 'conversation');
+}
+function isCold(page, thresholdMs) {
+    if (page.hit_count === 0 && !page.last_accessed)
+        return true;
+    if (!page.last_accessed)
+        return true;
+    const lastMs = new Date(page.last_accessed).getTime();
+    return Number.isNaN(lastMs) ? true : Date.now() - lastMs > thresholdMs;
+}
+export async function knowledgeMaintain(contextDir, options = {}) {
+    const hitThreshold = options.expansionHitThreshold ?? 3;
+    const bodyThreshold = options.thinBodyThreshold ?? 500;
+    const coldMs = (options.coldDays ?? 30) * DAY_MS;
+    const backend = createKnowledgeBackend(contextDir);
+    try {
+        const pages = await backend.listPages({ limit: 1000 });
+        const expansionCandidates = pages.filter((p) => p.hit_count >= hitThreshold && p.body.length < bodyThreshold && p.status === 'active');
+        const coldPages = pages.filter((p) => isCold(p, coldMs) && p.status === 'active');
+        const misfiled = pages.filter((p) => isMisfiled(p) && p.status === 'active');
+        const activeCount = pages.filter((p) => p.status === 'active').length;
+        return formatMaintainReport(activeCount, expansionCandidates, coldPages, misfiled, {
+            hitThreshold,
+            bodyThreshold,
+            coldDays: options.coldDays ?? 30,
+        });
+    }
+    finally {
+        backend.close();
+    }
+}
+function formatMaintainReport(total, expansion, cold, misfiled, thresholds) {
+    const lines = [];
+    lines.push('# Knowledge maintain report');
+    lines.push('');
+    lines.push(`**Total active pages:** ${total}`);
+    // ── Expansion candidates ──────────────────────────────────────────────────
+    lines.push('');
+    lines.push(`## Expansion candidates (hit_count ≥ ${thresholds.hitThreshold}, body < ${thresholds.bodyThreshold} chars)`);
+    lines.push('');
+    if (expansion.length === 0) {
+        lines.push('None — no thin but frequently-accessed pages.');
+    }
+    else {
+        lines.push(`${expansion.length} page${expansion.length === 1 ? '' : 's'} are thin but frequently accessed — consider deepening:`);
+        for (const p of expansion) {
+            lines.push(`- \`${p.slug}\` — *${p.title}* (${p.domain}) — ${p.hit_count} hits, ${p.body.length} chars`);
+        }
+    }
+    // ── Cold pages ────────────────────────────────────────────────────────────
+    lines.push('');
+    lines.push(`## Cold pages (no access in ${thresholds.coldDays}+ days, or never accessed)`);
+    lines.push('');
+    if (cold.length === 0) {
+        lines.push('None — all active pages have been accessed recently.');
+    }
+    else {
+        lines.push(`${cold.length} page${cold.length === 1 ? '' : 's'} have not been accessed recently:`);
+        for (const p of cold) {
+            const lastAccess = p.last_accessed ? p.last_accessed.slice(0, 10) : 'never';
+            lines.push(`- \`${p.slug}\` — *${p.title}* (${p.domain}) — last access: ${lastAccess}`);
+        }
+    }
+    // ── Misfile audit ─────────────────────────────────────────────────────────
+    lines.push('');
+    lines.push('## Misfile audit (provisional sourcing or conversation-only citations)');
+    lines.push('');
+    if (misfiled.length === 0) {
+        lines.push('None — all active pages have independent citation support.');
+    }
+    else {
+        lines.push(`${misfiled.length} page${misfiled.length === 1 ? '' : 's'} may need attention:`);
+        lines.push('> **World class:** knowledge is true independent of Jonathan — provisional/conversation-only pages belong in memory.\n' +
+            '> **Ours class (domain: ours/):** should have at least one `repo` citation to reach `internal` sourcing.');
+        for (const p of misfiled) {
+            const reason = p.sourcing === 'provisional' ? 'provisional' : 'conversation-only citations';
+            const hint = p.domain.startsWith('ours/')
+                ? '→ add a repo citation (git path / commit)'
+                : '→ add a web citation or relocate to memory';
+            lines.push(`- \`${p.slug}\` — *${p.title}* (${p.domain}) — ${reason} ${hint}`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/tools/knowledge-merge.d.ts

@@ -0,0 +1,8 @@
+export interface KnowledgeMergeToolInput {
+    source_slugs: string[];
+    target_slug: string;
+    note?: string;
+    hard_delete_losers?: boolean;
+    append_loser_bodies?: boolean;
+}
+export declare function knowledgeMerge(contextDir: string, input: KnowledgeMergeToolInput): Promise<string>;

package/dist/tools/knowledge-merge.js

@@ -0,0 +1,40 @@
+/**
+ * knowledge_merge tool — consolidate N knowledge pages into one canonical page.
+ *
+ * Re-parents all citations from source pages to the target, deduplicating by
+ * (claim, source_kind, source_locator, excerpt). Takes MAX(verified_at) across
+ * all pages. Supersedes losers (archives each with a pointer to target).
+ *
+ * Distinct from knowledge_supersede (1:1 pointer, no citation consolidation):
+ * use merge when there is real data to consolidate from multiple pages.
+ */
+import { createKnowledgeBackend } from '../backends/index.js';
+export async function knowledgeMerge(contextDir, input) {
+    if (!input.source_slugs || input.source_slugs.length === 0) {
+        return 'Error: source_slugs must not be empty.';
+    }
+    const backend = createKnowledgeBackend(contextDir);
+    try {
+        const result = await backend.mergePages(input);
+        const lines = [
+            `Merged ${result.sources_merged} page(s) into \`${result.target_slug}\`.`,
+            `Citations: ${result.citations_moved} moved to target, ${result.citations_deduped} duplicate(s) removed.`,
+            `verified_at set to ${result.verified_at}.`,
+            `Losers archived: ${result.losers.map((l) => `\`${l.slug}\``).join(', ')}.`,
+        ];
+        if (!input.append_loser_bodies && result.losers.length > 0) {
+            lines.push('');
+            lines.push('Loser bodies (target body NOT modified — curator review):');
+            for (const loser of result.losers) {
+                lines.push(`\n**${loser.slug}:**\n${loser.body}`);
+            }
+        }
+        return lines.join('\n');
+    }
+    catch (e) {
+        return `Error: ${e.message}`;
+    }
+    finally {
+        backend.close();
+    }
+}

package/dist/tools/knowledge-move.d.ts

@@ -0,0 +1,10 @@
+export interface KnowledgeMoveToolInput {
+    slug?: string;
+    new_slug?: string;
+    new_domain?: string;
+    leave_pointer?: boolean;
+    slugs?: string[];
+    from_domain_prefix?: string;
+    to_domain_prefix?: string;
+}
+export declare function knowledgeMove(contextDir: string, input: KnowledgeMoveToolInput): Promise<string>;

package/dist/tools/knowledge-move.js

@@ -0,0 +1,48 @@
+/**
+ * knowledge_move tool — re-key or re-domain a knowledge page in place.
+ *
+ * Three modes:
+ *   1. Single-page: change slug and/or domain on one page (same row, same uuid).
+ *   2. Batch by slug list: re-domain a set of named pages atomically.
+ *   3. Batch by domain prefix: re-home an entire subtree in one transaction.
+ *
+ * Slug changes write a supersessions pointer (old→new) unless leave_pointer=false.
+ * Slug collisions are rejected — use knowledge_merge instead.
+ */
+import { createKnowledgeBackend } from '../backends/index.js';
+export async function knowledgeMove(contextDir, input) {
+    const backend = createKnowledgeBackend(contextDir);
+    try {
+        const result = await backend.movePage(input);
+        if (result.moved === 0) {
+            return 'No pages matched — nothing moved.';
+        }
+        const lines = [];
+        if (input.from_domain_prefix !== undefined) {
+            lines.push(`Moved ${result.moved} page(s) from domain prefix \`${input.from_domain_prefix}\` → \`${input.to_domain_prefix}\`.`);
+        }
+        else if (input.slugs && input.slugs.length > 0) {
+            lines.push(`Moved ${result.moved} page(s) to domain \`${input.new_domain}\`.`);
+        }
+        else {
+            const page = result.pages[0];
+            if (page.old_slug) {
+                lines.push(`Re-slugged \`${page.old_slug}\` → \`${page.slug}\`.`);
+                if (result.pointers_written > 0) {
+                    lines.push('Supersessions pointer written (old slug → new slug).');
+                }
+            }
+            if (page.new_domain !== page.old_domain) {
+                lines.push(`Domain changed: \`${page.old_domain}\` → \`${page.new_domain}\`.`);
+            }
+            lines.push(`uuid, citations, and verification history are unchanged.`);
+        }
+        return lines.join(' ');
+    }
+    catch (e) {
+        return `Error: ${e.message}`;
+    }
+    finally {
+        backend.close();
+    }
+}

package/dist/tools/knowledge-purge.d.ts

@@ -0,0 +1,5 @@
+export interface KnowledgePurgeToolInput {
+    slugs: string[];
+    confirm: boolean;
+}
+export declare function knowledgePurge(contextDir: string, input: KnowledgePurgeToolInput): Promise<string>;

package/dist/tools/knowledge-purge.js

@@ -0,0 +1,20 @@
+import { createKnowledgeBackend } from '../backends/index.js';
+export async function knowledgePurge(contextDir, input) {
+    if (!input.confirm) {
+        return 'Error: confirm must be explicitly true to execute a hard delete.';
+    }
+    if (!input.slugs || input.slugs.length === 0) {
+        return 'Error: slugs must not be empty.';
+    }
+    const backend = createKnowledgeBackend(contextDir);
+    try {
+        const result = await backend.purgePages({ slugs: input.slugs, confirm: true });
+        return `Purged ${result.purged} page(s): ${result.slugs.map((s) => `\`${s}\``).join(', ')}.`;
+    }
+    catch (e) {
+        return `Error: ${e.message}`;
+    }
+    finally {
+        backend.close();
+    }
+}

package/dist/tools/knowledge-recall.d.ts

@@ -0,0 +1,20 @@
+export interface KnowledgeRecallInput {
+    /**
+     * Exact-slug lookup — fetches that single page in full detail, stamping
+     * access. Takes precedence over query/domain/limit. This is the precise
+     * path; LIKE token-matching can return the wrong page when bodies
+     * cross-reference each other.
+     */
+    slug?: string;
+    query?: string;
+    domain?: string;
+    limit?: number;
+    detail?: 'index' | 'full';
+    /**
+     * Stale-first ordering for the verification engine: verified_at ASC with
+     * never-verified pages first. Index entries gain a `verified:` stamp so
+     * the verifier can apply its SLA filter from the listing alone.
+     */
+    sort_by_verified?: boolean;
+}
+export declare function knowledgeRecall(contextDir: string, input: KnowledgeRecallInput): Promise<string>;