@jbarket/loomai 0.5.0

package/dist/tools/knowledge-recall.js

@@ -0,0 +1,142 @@
+/**
+ * knowledge_recall tool — LIKE search over the knowledge store.
+ *
+ * Two detail tiers:
+ *   'full'  — whole entity pages with citations (the synthesis unit).
+ *             Stamps last_accessed / hit_count via queryPages — the usage
+ *             signal the Phase-4 expansion engine depends on.
+ *   'index' — one compact entry per page (slug, domain, sourcing, anchor,
+ *             snippet). Does NOT stamp access: appearing in a listing is
+ *             not a read.
+ *
+ * Default tier: 'full' when a query is given, 'index' when browsing
+ * (no query). Full output is size-guarded — once the budget is spent,
+ * remaining pages degrade to index entries instead of blowing the
+ * tool-result limit. Never surfaces archived pages.
+ */
+import { createKnowledgeBackend } from '../backends/index.js';
+/**
+ * Character budget for full-page output. ~24k chars ≈ 6k tokens — well under
+ * typical MCP tool-result caps, with room for the citations and framing.
+ */
+const FULL_OUTPUT_CHAR_BUDGET = 24_000;
+/** Max characters of body shown per index entry snippet. */
+const SNIPPET_LENGTH = 200;
+function formatPage(page) {
+    const lines = [];
+    lines.push(`## ${page.title}`);
+    lines.push(`**Slug:** \`${page.slug}\` | **Domain:** ${page.domain} | **Sourcing:** ${page.sourcing}`);
+    if (page.sourcing === 'provisional') {
+        lines.push('> ⚠️ Provisional — needs independent citation to be sourced.');
+    }
+    if (page.provenance) {
+        lines.push(`> Provenance: ${page.provenance}`);
+    }
+    lines.push('');
+    lines.push(page.body);
+    if (page.citations.length > 0) {
+        lines.push('');
+        lines.push('**Citations:**');
+        for (const cit of page.citations) {
+            const loc = cit.source_locator ? ` (${cit.source_locator})` : '';
+            lines.push(`- [${cit.source_kind}${loc}] *${cit.claim}* — "${cit.excerpt}"`);
+        }
+    }
+    return lines.join('\n');
+}
+/** First non-heading, non-blank line of the body, truncated to SNIPPET_LENGTH. */
+function snippet(body) {
+    for (const raw of body.split('\n')) {
+        const line = raw.trim();
+        if (line.length === 0 || line.startsWith('#'))
+            continue;
+        return line.length > SNIPPET_LENGTH ? `${line.slice(0, SNIPPET_LENGTH - 1)}…` : line;
+    }
+    return '';
+}
+function formatIndexEntry(page, showVerified = false) {
+    const anchor = page.freshness_anchor ? ` | anchor: ${page.freshness_anchor}` : '';
+    const provisional = page.sourcing === 'provisional' ? ' | ⚠️ provisional' : '';
+    const verified = showVerified
+        ? ` | verified: ${page.verified_at ? page.verified_at.slice(0, 10) : 'never'}`
+        : '';
+    const lines = [
+        `- **${page.title}** (\`${page.slug}\`)`,
+        `  ${page.domain}${anchor}${verified}${provisional} | ${page.citations.length} citation${page.citations.length === 1 ? '' : 's'} | hits: ${page.hit_count}`,
+    ];
+    const snip = snippet(page.body);
+    if (snip)
+        lines.push(`  ${snip}`);
+    return lines.join('\n');
+}
+export async function knowledgeRecall(contextDir, input) {
+    const detail = input.detail ?? (input.query ? 'full' : 'index');
+    const backend = createKnowledgeBackend(contextDir);
+    try {
+        // Exact-slug lookup short-circuits the search path entirely.
+        if (input.slug) {
+            const peek = await backend.getPage(input.slug);
+            if (!peek) {
+                return `No knowledge page found for slug \`${input.slug}\`.`;
+            }
+            if (peek.status === 'archived') {
+                // Not stamped — an archived page surfacing in an error message is
+                // not a read, and a phantom hit would survive a later restore.
+                return (`No active knowledge page for slug \`${input.slug}\` — it is archived. ` +
+                    `Use knowledge_restore to bring it back.`);
+            }
+            const page = await backend.getPage(input.slug, { stampAccess: true });
+            return `# Knowledge recall — 1 result\n\n${formatPage(page)}`;
+        }
+        const pages = await backend.queryPages({
+            query: input.query,
+            domain: input.domain,
+            excludeStatus: 'archived',
+            // Index entries are cheap — browse wide by default. Full pages are
+            // expensive — keep the default narrow.
+            limit: input.limit ?? (detail === 'index' ? 50 : 10),
+            // Index browsing must not inflate hit_count (expansion-engine signal).
+            stampAccess: detail === 'full',
+            sortByVerified: input.sort_by_verified,
+        });
+        if (pages.length === 0) {
+            const q = input.query ? `"${input.query}"` : '(no query)';
+            return `No knowledge pages found for ${q}.`;
+        }
+        const plural = pages.length === 1 ? '' : 's';
+        if (detail === 'index') {
+            const entries = pages.map((p) => formatIndexEntry(p, input.sort_by_verified === true));
+            return (`# Knowledge index — ${pages.length} page${plural}\n\n` +
+                `${entries.join('\n')}\n\n` +
+                `_Pass slug: "<slug>" (or detail: "full") to read whole pages._`);
+        }
+        // Full mode with a size guard: emit whole pages until the budget is
+        // spent, then degrade the remainder to index entries.
+        const fullParts = [];
+        const overflow = [];
+        let spent = 0;
+        for (const page of pages) {
+            const formatted = formatPage(page);
+            // Always include at least one full page — the first result is what
+            // the caller asked for even if it alone exceeds the budget.
+            if (fullParts.length > 0 && spent + formatted.length > FULL_OUTPUT_CHAR_BUDGET) {
+                overflow.push(page);
+                continue;
+            }
+            fullParts.push(formatted);
+            spent += formatted.length;
+        }
+        let out = `# Knowledge recall — ${pages.length} result${plural}\n\n${fullParts.join('\n\n---\n\n')}`;
+        if (overflow.length > 0) {
+            const entries = overflow.map((p) => formatIndexEntry(p, input.sort_by_verified === true));
+            out +=
+                `\n\n---\n\n` +
+                    `**${overflow.length} more match${overflow.length === 1 ? '' : 'es'}** (output budget reached — shown as index; ` +
+                    `recall by slug for full pages):\n\n${entries.join('\n')}`;
+        }
+        return out;
+    }
+    finally {
+        backend.close();
+    }
+}

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

@@ -0,0 +1,4 @@
+export interface KnowledgeRestoreToolInput {
+    slug: string;
+}
+export declare function knowledgeRestore(contextDir: string, input: KnowledgeRestoreToolInput): Promise<string>;

package/dist/tools/knowledge-restore.js

@@ -0,0 +1,24 @@
+/**
+ * knowledge_restore tool — return an archived knowledge page to active status.
+ *
+ * Clears status back to 'active' and wipes the tombstone note. The page
+ * becomes visible to knowledge_recall and knowledge_maintain again.
+ * Mirror of memory_restore.
+ */
+import { createKnowledgeBackend } from '../backends/index.js';
+export async function knowledgeRestore(contextDir, input) {
+    const backend = createKnowledgeBackend(contextDir);
+    try {
+        const result = await backend.restorePage({ slug: input.slug });
+        if (!result.restored) {
+            return `Archived knowledge page not found: \`${input.slug}\`. It may not be archived, or the slug may be wrong.`;
+        }
+        return `Knowledge page restored: \`${input.slug}\``;
+    }
+    catch (e) {
+        return `Error: ${e.message}`;
+    }
+    finally {
+        backend.close();
+    }
+}

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

@@ -0,0 +1,6 @@
+export interface KnowledgeSupersededToolInput {
+    old_slug: string;
+    new_slug: string;
+    note?: string;
+}
+export declare function knowledgeSupersede(contextDir: string, input: KnowledgeSupersededToolInput): Promise<string>;

package/dist/tools/knowledge-supersede.js

@@ -0,0 +1,36 @@
+/**
+ * knowledge_supersede tool — retire a duplicate page in favour of the canonical one.
+ *
+ * Archives old_slug with a tombstone referencing new_slug, then records the
+ * supersession in the supersessions table. This is the dedup-merge primitive:
+ *   1. knowledge_write the canonical page (or confirm it exists)
+ *   2. knowledge_supersede(loser → canonical)
+ *
+ * Both pages must already exist. new_slug need not be active (archiving a
+ * superseded chain is allowed), but old_slug must not already be archived —
+ * if it is, the call returns without error but reports archived=false.
+ */
+import { createKnowledgeBackend } from '../backends/index.js';
+export async function knowledgeSupersede(contextDir, input) {
+    if (input.old_slug === input.new_slug) {
+        return 'Error: old_slug and new_slug must be different.';
+    }
+    const backend = createKnowledgeBackend(contextDir);
+    try {
+        const result = await backend.supersedePage({
+            old_slug: input.old_slug,
+            new_slug: input.new_slug,
+            note: input.note,
+        });
+        const archiveNote = result.archived
+            ? ` \`${result.old_slug}\` archived with supersession tombstone.`
+            : ` \`${result.old_slug}\` was already archived.`;
+        return (`Knowledge supersession recorded: \`${result.old_slug}\` → \`${result.new_slug}\`.${archiveNote}`);
+    }
+    catch (e) {
+        return `Error: ${e.message}`;
+    }
+    finally {
+        backend.close();
+    }
+}

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

@@ -0,0 +1,8 @@
+export interface KnowledgeVerifyToolInput {
+    slug?: string;
+    slugs?: string[];
+    verified_at?: string;
+    freshness_anchor?: string;
+    note?: string;
+}
+export declare function knowledgeVerify(contextDir: string, input: KnowledgeVerifyToolInput): Promise<string>;

package/dist/tools/knowledge-verify.js

@@ -0,0 +1,39 @@
+/**
+ * knowledge_verify tool — the stamp-only verification primitive.
+ *
+ * Sets verified_at / freshness_anchor WITHOUT touching the page body. This is
+ * the primitive whose absence caused the 2026-06-01 incident: the verify role
+ * had no way to stamp a page, so it pushed its notes through knowledge_write
+ * and replaced 13 page bodies. An optional note appends a dated
+ * "## Verification" section — append-only, never replace.
+ */
+import { createKnowledgeBackend } from '../backends/index.js';
+export async function knowledgeVerify(contextDir, input) {
+    const backend = createKnowledgeBackend(contextDir);
+    try {
+        const result = await backend.verifyPages({
+            slug: input.slug,
+            slugs: input.slugs,
+            verified_at: input.verified_at,
+            freshness_anchor: input.freshness_anchor,
+            note: input.note,
+        });
+        const stamp = result.verified_at;
+        if (result.verified === 1) {
+            const extras = [];
+            if (input.freshness_anchor)
+                extras.push(`anchor → ${input.freshness_anchor}`);
+            if (result.noted)
+                extras.push('note appended');
+            const suffix = extras.length > 0 ? ` (${extras.join(', ')})` : '';
+            return `Verified \`${result.slugs[0]}\` — verified_at stamped to ${stamp}${suffix}. Body untouched${result.noted ? ' except appended note' : ''}.`;
+        }
+        return `Verified ${result.verified} page(s) — verified_at stamped to ${stamp}: ${result.slugs.map((s) => `\`${s}\``).join(', ')}. Bodies untouched.`;
+    }
+    catch (e) {
+        return `Error: ${e.message}`;
+    }
+    finally {
+        backend.close();
+    }
+}

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

@@ -0,0 +1,25 @@
+export interface KnowledgeWriteInput {
+    domain: string;
+    title: string;
+    body: string;
+    slug?: string;
+    freshness_anchor?: string;
+    /**
+     * Body combine mode when the slug already exists: 'replace' (default)
+     * overwrites the stored body; 'append' adds this body after the existing
+     * one. Citations are always appended (with exact-duplicate dedup),
+     * regardless of mode.
+     */
+    mode?: 'replace' | 'append';
+    citations: Array<{
+        claim: string;
+        source_kind: 'web' | 'loom_memory' | 'conversation' | 'repo';
+        source_locator?: string;
+        excerpt: string;
+    }>;
+    /** ours/ class: who created or last owned this artifact (e.g. "art", "jonathan"). */
+    created_by?: string;
+    /** ours/ class: artifact version or revision tag (e.g. "v2", "2026-08-19"). */
+    version?: string;
+}
+export declare function knowledgeWrite(contextDir: string, input: KnowledgeWriteInput): Promise<string>;

package/dist/tools/knowledge-write.js

@@ -0,0 +1,87 @@
+/**
+ * knowledge_write tool — upsert an entity page by slug/title.
+ *
+ * Two knowledge classes:
+ *   world/  — facts true independent of us (default; domain = "music/gear", etc.)
+ *   ours/   — Art-created artifacts revised-in-place (domain starts with "ours/").
+ *             Cited to repo paths/commits, loom_memory refs, or live-system probes.
+ *
+ * Epistemic gate (§E1):
+ *   - conversation-only citations → provisional (both classes).
+ *   - any repo citation → internal (ours/ class; overrides the sourced gate).
+ *   - any web citation (no repo) → sourced (world/ default).
+ *
+ * Filing test for world/ pages: knowledge is true independent of Jonathan; if
+ * it's about Jonathan / our work use memory or ours/ instead, not the world class.
+ */
+import { createKnowledgeBackend } from '../backends/index.js';
+function slugify(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 128);
+}
+/**
+ * §E1: Epistemic gate.
+ * - conversation-only → provisional (both classes).
+ * - any repo citation → internal (ours/ class; repo = git path/commit/ref).
+ * - any web citation, no repo → sourced (world/ default).
+ */
+function determineSourcing(citations) {
+    if (citations.length === 0)
+        return 'provisional';
+    if (citations.every((c) => c.source_kind === 'conversation'))
+        return 'provisional';
+    if (citations.some((c) => c.source_kind === 'repo'))
+        return 'internal';
+    return 'sourced';
+}
+export async function knowledgeWrite(contextDir, input) {
+    if (input.citations.length === 0) {
+        return ('Error: at least one citation is required — knowledge must be supported. ' +
+            'If this is a conversation-distilled insight, pass source_kind="conversation" ' +
+            'and the page will be stored provisional.');
+    }
+    const slug = input.slug ?? slugify(input.title);
+    if (!slug) {
+        return 'Error: could not derive a slug from the title. Provide an explicit slug.';
+    }
+    const sourcing = determineSourcing(input.citations);
+    const backend = createKnowledgeBackend(contextDir);
+    try {
+        const result = await backend.writePage({
+            slug,
+            title: input.title,
+            domain: input.domain,
+            body: input.body,
+            sourcing,
+            freshness_anchor: input.freshness_anchor,
+            bodyMode: input.mode,
+            citations: input.citations,
+            created_by: input.created_by,
+            version: input.version,
+        });
+        const sourcingNote = sourcing === 'provisional'
+            ? '\n> **Provisional** — sole support is conversation citations. ' +
+                'Add a web or repo citation to promote to sourced/internal.'
+            : sourcing === 'internal'
+                ? '\n> **Internal** — ours/ class artifact; cited to repo/live-system sources.'
+                : '';
+        const action = result.bodyMode === 'create' ? 'created'
+            : result.bodyMode === 'append' ? 'updated (body appended)'
+                : 'updated (body replaced)';
+        const dedupNote = result.citationsDeduped > 0
+            ? ` (${result.citationsDeduped} duplicate${result.citationsDeduped === 1 ? '' : 's'} skipped)`
+            : '';
+        return (`Knowledge page ${action}: **${result.title}** (\`${result.slug}\`)\n` +
+            `Domain: ${input.domain} | Citations added: ${result.citationsAdded}${dedupNote} | Sourcing: ${sourcing}` +
+            sourcingNote);
+    }
+    catch (e) {
+        return `Error: ${e.message}`;
+    }
+    finally {
+        backend.close();
+    }
+}

package/dist/tools/memory-audit.d.ts

@@ -0,0 +1,3 @@
+import type { AuditOptions, AuditReport } from '../backends/types.js';
+export declare function formatAuditReport(report: AuditReport): string;
+export declare function memoryAudit(contextDir: string, options?: AuditOptions): Promise<string>;

package/dist/tools/memory-audit.js

@@ -0,0 +1,47 @@
+/**
+ * memory_audit tool — one-shot health report for the memory store.
+ * Surfaces counts, stale memories, near-duplicate pairs, and expired refs.
+ * Read-only: never deletes. Pair with `forget` / `update` to act on findings.
+ */
+import { createBackend } from '../backends/index.js';
+export function formatAuditReport(report) {
+    const lines = [];
+    lines.push(`# Memory audit`);
+    lines.push('');
+    lines.push(`**Total memories:** ${report.totalMemories}`);
+    const cats = Object.entries(report.byCategory).sort((a, b) => b[1] - a[1]);
+    if (cats.length > 0) {
+        lines.push('');
+        lines.push('**By category:**');
+        for (const [c, n] of cats)
+            lines.push(`- ${c}: ${n}`);
+    }
+    lines.push('');
+    lines.push(`**Expired (would be pruned):** ${report.expired.length}`);
+    for (const ref of report.expired.slice(0, 20))
+        lines.push(`- ${ref}`);
+    if (report.expired.length > 20) {
+        lines.push(`- … and ${report.expired.length - 20} more`);
+    }
+    lines.push('');
+    lines.push(`**Stale (untouched beyond threshold):** ${report.stale.length}`);
+    for (const s of report.stale.slice(0, 20)) {
+        const proj = s.project ? ` [${s.project}]` : '';
+        lines.push(`- ${s.ref} — *${s.title}*${proj} (last touch ${s.lastTouch.slice(0, 10)})`);
+    }
+    if (report.stale.length > 20) {
+        lines.push(`- … and ${report.stale.length - 20} more`);
+    }
+    lines.push('');
+    lines.push(`**Near-duplicate pairs:** ${report.duplicates.length}`);
+    for (const d of report.duplicates) {
+        lines.push(`- ${d.relevance.toFixed(3)}  ${d.a.ref} ↔ ${d.b.ref}  ` +
+            `(*${d.a.title}* vs *${d.b.title}*)`);
+    }
+    return lines.join('\n');
+}
+export async function memoryAudit(contextDir, options) {
+    const backend = createBackend(contextDir);
+    const report = await backend.audit(options);
+    return formatAuditReport(report);
+}

package/dist/tools/memory-list.d.ts

@@ -0,0 +1,4 @@
+import type { ListInput, MemoryEntry } from '../backends/types.js';
+export declare function formatEntry(e: MemoryEntry): string;
+export declare function formatEntries(entries: MemoryEntry[]): string;
+export declare function memoryList(contextDir: string, input: ListInput): Promise<string>;

package/dist/tools/memory-list.js

@@ -0,0 +1,23 @@
+/**
+ * Memory list tool — browse memories without semantic search.
+ *
+ * Lists memories with optional category/project filters. Unlike recall,
+ * this doesn't require a search query — useful for auditing, browsing,
+ * and memory maintenance.
+ */
+import { createBackend } from '../backends/index.js';
+export function formatEntry(e) {
+    const projectTag = e.project ? ` [${e.project}]` : '';
+    return `- **${e.title}** — ${e.category}${projectTag} (${e.created.slice(0, 10)})\n  ref: \`${e.ref}\``;
+}
+export function formatEntries(entries) {
+    if (entries.length === 0)
+        return 'No memories found.';
+    const formatted = entries.map(formatEntry);
+    return `Found ${entries.length} memories:\n\n${formatted.join('\n')}`;
+}
+export async function memoryList(contextDir, input) {
+    const backend = createBackend(contextDir);
+    const entries = await backend.list(input);
+    return formatEntries(entries);
+}

package/dist/tools/prune.d.ts

@@ -0,0 +1,4 @@
+export declare function prune(contextDir: string, options?: {
+    dryRun?: boolean;
+    staleDays?: number;
+}): Promise<string>;

package/dist/tools/prune.js

@@ -0,0 +1,28 @@
+/**
+ * Prune tool — removes expired memories and reports stale ones.
+ *
+ * Delegates to the configured memory backend for TTL-based cleanup.
+ */
+import { createBackend } from '../backends/index.js';
+export async function prune(contextDir, options) {
+    const backend = createBackend(contextDir);
+    const result = await backend.prune(options);
+    const lines = [];
+    if (result.expired.length > 0) {
+        const verb = options?.dryRun ? 'Would expire' : 'Expired';
+        lines.push(`**${verb} ${result.expired.length} memories (TTL elapsed):**`);
+        for (const ref of result.expired) {
+            lines.push(`- ${ref}`);
+        }
+    }
+    if (result.stale.length > 0) {
+        lines.push(`\n**${result.stale.length} stale memories (not accessed in ${options?.staleDays ?? 30}+ days):**`);
+        for (const ref of result.stale) {
+            lines.push(`- ${ref}`);
+        }
+    }
+    if (result.expired.length === 0 && result.stale.length === 0) {
+        return 'No expired or stale memories found. Memory store is healthy.';
+    }
+    return lines.join('\n');
+}

package/dist/tools/recall.d.ts

@@ -0,0 +1,4 @@
+import type { RecallInput, MemoryMatch } from '../backends/types.js';
+export declare function formatMatchResult(m: MemoryMatch): string;
+export declare function formatResults(matches: MemoryMatch[]): string;
+export declare function recall(contextDir: string, input: RecallInput): Promise<string>;

package/dist/tools/recall.js

@@ -0,0 +1,24 @@
+/**
+ * Recall tool — retrieves memories relevant to a query.
+ *
+ * Delegates to the configured memory backend for search, then formats
+ * results for display. The backend handles the actual search strategy
+ * (keyword, vector, etc.).
+ */
+import { createBackend } from '../backends/index.js';
+export function formatMatchResult(m) {
+    const projectTag = m.project ? ` [${m.project}]` : '';
+    return `## ${m.title}\n*${m.category}${projectTag} — ${m.created.slice(0, 10)}*\n\n${m.content}`;
+}
+export function formatResults(matches) {
+    const results = matches.map(formatMatchResult);
+    return `Found ${matches.length} matching memories:\n\n${results.join('\n\n---\n\n')}`;
+}
+export async function recall(contextDir, input) {
+    const backend = createBackend(contextDir);
+    const matches = await backend.recall(input);
+    if (matches.length === 0) {
+        return `No memories found matching "${input.query}".`;
+    }
+    return formatResults(matches);
+}

package/dist/tools/remember.d.ts

@@ -0,0 +1,10 @@
+import type { MemoryInput, MemoryRef } from '../backends/types.js';
+/**
+ * Lint-on-write (c-loom-strictness §lint): validate the record BEFORE it reaches
+ * the backend, so a malformed write is refused with a typed reason and the store
+ * is left untouched — never an empty/torn memory committed then discovered. The
+ * knowledge wing already gates its writes (a citation is required); this brings
+ * the memory wing to parity. Returns a reason string when invalid, else null.
+ */
+export declare function validateMemoryInput(input: MemoryInput): string | null;
+export declare function remember(contextDir: string, input: MemoryInput): Promise<MemoryRef>;

package/dist/tools/remember.js

@@ -0,0 +1,43 @@
+/**
+ * Remember tool — stores an episodic memory that persists across sessions.
+ *
+ * Delegates to the configured MemoryBackend. v0.3.1 ships a single
+ * backend (sqlite-vec + fastembed); the interface stays generic so
+ * future stacks can swap in without changing the tool contract.
+ */
+import { createBackend } from '../backends/index.js';
+import { EPISODE_CATEGORY, EPISODE_DEFAULT_TTL } from '../categories.js';
+/**
+ * Lint-on-write (c-loom-strictness §lint): validate the record BEFORE it reaches
+ * the backend, so a malformed write is refused with a typed reason and the store
+ * is left untouched — never an empty/torn memory committed then discovered. The
+ * knowledge wing already gates its writes (a citation is required); this brings
+ * the memory wing to parity. Returns a reason string when invalid, else null.
+ */
+export function validateMemoryInput(input) {
+    if (typeof input.content !== 'string' || input.content.trim() === '') {
+        return 'memory content is required and cannot be empty';
+    }
+    if (typeof input.title !== 'string' || input.title.trim() === '') {
+        return 'memory title is required and cannot be empty';
+    }
+    if (typeof input.category !== 'string' || input.category.trim() === '') {
+        return 'memory category is required and cannot be empty';
+    }
+    return null;
+}
+export async function remember(contextDir, input) {
+    const reason = validateMemoryInput(input);
+    if (reason !== null) {
+        // Rejected pre-commit: nothing is opened or written. The thrown reason is
+        // the typed rejection (dispatch wraps it into a typed envelope at the edge).
+        throw new Error(`Error: ${reason}`);
+    }
+    const backend = createBackend(contextDir);
+    // An episode is short-term by definition: without an explicit ttl it gets the
+    // tier default, so a body can never accidentally leave a permanent episode.
+    if (input.category === EPISODE_CATEGORY && !input.ttl) {
+        input = { ...input, ttl: EPISODE_DEFAULT_TTL };
+    }
+    return backend.remember(input);
+}

package/dist/tools/restore.d.ts

@@ -0,0 +1,2 @@
+import type { RestoreInput } from '../backends/types.js';
+export declare function restore(contextDir: string, input: RestoreInput): Promise<string>;

package/dist/tools/restore.js

@@ -0,0 +1,20 @@
+/**
+ * Restore tool — return an archived memory to the active set.
+ *
+ * Clears the archived flag and wipes the tombstone note. The memory
+ * becomes visible to recall, list, audit, and findSimilar again.
+ */
+import { createBackend } from '../backends/index.js';
+export async function restore(contextDir, input) {
+    const isSingle = input.ref || (input.category && input.title);
+    if (!isSingle) {
+        return 'Nothing to restore. Provide a ref or category+title.';
+    }
+    const backend = createBackend(contextDir);
+    const result = await backend.restore(input);
+    if (result.restored.length === 0) {
+        const identifier = input.ref ?? `${input.category}/${input.title}`;
+        return `Archived memory not found: "${identifier}". It may not be archived, or the ref may be wrong.`;
+    }
+    return `Memory restored: ${result.restored[0]}`;
+}

package/dist/tools/update-identity.d.ts

@@ -0,0 +1,34 @@
+export interface IdentitySection {
+    header: string;
+    content: string;
+    startLine: number;
+    endLine: number;
+}
+/**
+ * Parse a markdown file into H2 sections.
+ * Content before the first H2 is captured as a preamble (header: '').
+ *
+ * Fence-aware: a `## ` line inside a ``` or ~~~ code fence is body content,
+ * not a section boundary. Closing fences must use the same character and be
+ * at least as long as the opener (CommonMark-style).
+ */
+export declare function parseSections(text: string): IdentitySection[];
+/**
+ * Rebuild a markdown file from sections.
+ */
+export declare function rebuildMarkdown(sections: IdentitySection[]): string;
+export type UpdateMode = 'replace' | 'append';
+export interface UpdateIdentityInput {
+    file: string;
+    section?: string;
+    content?: string;
+    mode?: UpdateMode;
+}
+/**
+ * List sections in an identity file.
+ */
+export declare function listSections(contextDir: string, file: string): Promise<string>;
+/**
+ * Update or append a section in an identity file.
+ */
+export declare function updateIdentity(contextDir: string, input: UpdateIdentityInput): Promise<string>;