@jbarket/loomai 0.5.0

package/dist/backends/recall-log.js

@@ -0,0 +1,143 @@
+/**
+ * Recall observation log — local-only telemetry for memory search.
+ *
+ * One JSON line per search, appended to `<contextDir>/telemetry/recall.jsonl`.
+ * Nothing leaves the machine: it is a file in the agent's own context dir,
+ * kept so `loom memory recall-stats` can answer "does recall actually
+ * work?" — hit rate, latency, score distribution, what missed. Set
+ * `LOOM_RECALL_LOG=0` to turn it off.
+ *
+ * Writes never throw. A failed write must never fail a search.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { resolveTelemetryDir } from '../config.js';
+export const RECALL_LOG_FILE = 'recall.jsonl';
+export const QUERY_MAX_CHARS = 120;
+export function recallLogPath(contextDir) {
+    return resolve(resolveTelemetryDir(contextDir), RECALL_LOG_FILE);
+}
+/** `LOOM_RECALL_LOG=0|off|false|no` disables the log; anything else (or unset) keeps it on. */
+export function isRecallLogEnabled(env = process.env) {
+    const v = env.LOOM_RECALL_LOG?.trim().toLowerCase();
+    return !(v === '0' || v === 'off' || v === 'false' || v === 'no');
+}
+/**
+ * Append one observation. Synchronous and cheap (one appendFileSync);
+ * creates the telemetry dir on first write; swallows every error.
+ */
+export function appendRecallObservation(contextDir, obs, env = process.env) {
+    if (!isRecallLogEnabled(env))
+        return;
+    try {
+        const dir = resolveTelemetryDir(contextDir);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const line = { ...obs, query: obs.query.slice(0, QUERY_MAX_CHARS) };
+        appendFileSync(resolve(dir, RECALL_LOG_FILE), JSON.stringify(line) + '\n', 'utf-8');
+    }
+    catch {
+        // Telemetry is best-effort by contract: never let it fail a search.
+    }
+}
+/** Read observations, oldest first. Malformed lines are skipped. */
+export function readRecallObservations(contextDir, opts = {}) {
+    const path = recallLogPath(contextDir);
+    if (!existsSync(path))
+        return [];
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    const sinceMs = opts.since?.getTime();
+    const out = [];
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        let obs;
+        try {
+            obs = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (typeof obs !== 'object' || obs === null || typeof obs.ts !== 'string')
+            continue;
+        if (sinceMs !== undefined && Date.parse(obs.ts) < sinceMs)
+            continue;
+        out.push(obs);
+    }
+    return out;
+}
+const SINCE_RE = /^(\d+)(m|h|d|w)$/;
+/** Parse a `--since` window like "30m", "24h", "7d", "2w" into milliseconds. */
+export function parseSinceDuration(spec) {
+    const m = spec.trim().match(SINCE_RE);
+    if (!m)
+        throw new Error(`Invalid --since "${spec}". Use e.g. 30m, 24h, 7d, 2w.`);
+    const n = Number.parseInt(m[1], 10);
+    switch (m[2]) {
+        case 'm': return n * 60_000;
+        case 'h': return n * 3_600_000;
+        case 'd': return n * 86_400_000;
+        default: return n * 7 * 86_400_000;
+    }
+}
+function median(values) {
+    if (values.length === 0)
+        return null;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = sorted.length >> 1;
+    return sorted.length % 2 === 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+export function summarizeRecallObservations(rows, opts = {}) {
+    const cap = opts.recentMisses ?? 10;
+    const hits = rows.filter((r) => r.hit);
+    const misses = rows.filter((r) => !r.hit);
+    return {
+        searches: rows.length,
+        hits: hits.length,
+        misses: misses.length,
+        hitRate: rows.length === 0 ? null : hits.length / rows.length,
+        medianLatencyMs: median(rows.map((r) => r.latencyMs).filter(Number.isFinite)),
+        medianTopScore: median(hits.map((r) => r.topScore).filter((s) => typeof s === 'number' && Number.isFinite(s))),
+        diversityDrops: rows.reduce((s, r) => s + (r.diversityDrops || 0), 0),
+        recentMisses: misses
+            .slice(-cap)
+            .reverse()
+            .map((r) => ({
+            ts: r.ts,
+            tool: r.tool,
+            query: r.query,
+            category: r.category,
+            project: r.project,
+            candidates: r.candidates,
+        })),
+    };
+}
+export function formatRecallStats(stats, windowLabel) {
+    const pct = (x) => (x === null ? 'n/a' : `${Math.round(x * 100)}%`);
+    const num = (x, digits, unit = '') => x === null ? 'n/a' : `${x.toFixed(digits)}${unit}`;
+    const lines = [
+        `Recall observations (last ${windowLabel}): ${stats.searches} search${stats.searches === 1 ? '' : 'es'}`,
+    ];
+    if (stats.searches === 0) {
+        lines.push('  (nothing logged in this window)');
+        return lines.join('\n');
+    }
+    lines.push(`  hit rate         ${stats.hits}/${stats.searches} (${pct(stats.hitRate)})`, `  median latency   ${num(stats.medianLatencyMs, 0, ' ms')}`, `  median topScore  ${num(stats.medianTopScore, 3)} (hits only)`, `  diversity drops  ${stats.diversityDrops} candidate${stats.diversityDrops === 1 ? '' : 's'} displaced by MMR`);
+    if (stats.recentMisses.length > 0) {
+        lines.push(`Recent misses (newest first):`);
+        for (const m of stats.recentMisses) {
+            const scope = [
+                m.category ? `category=${m.category}` : null,
+                m.project ? `project=${m.project}` : null,
+            ].filter(Boolean).join(' ');
+            lines.push(`  ${m.ts.slice(0, 16).replace('T', ' ')}  "${m.query}"${scope ? `  [${scope}]` : ''}`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/backends/retry.d.ts

@@ -0,0 +1,29 @@
+/**
+ * SQLITE_BUSY retry ladder with exponential backoff + jitter.
+ *
+ * better-sqlite3 is synchronous; these retries are synchronous too.
+ * Atomics.wait() provides a blocking sleep without busy-spinning — available
+ * on the main thread in Node >= 22 (our minimum engine requirement).
+ *
+ * Reference design: Memori core/src/storage/manager.rs::write_batch —
+ * retries SQLSTATE 40001 with exponential backoff + up to 50% jitter,
+ * folding commit() into the retried result. t-326.
+ */
+export interface RetryWriteOptions {
+    /** Maximum number of attempts (including the first). Default: 5. */
+    maxAttempts?: number;
+    /** Base delay in ms before the first retry; doubles each round. Default: 10. */
+    baseMs?: number;
+}
+/**
+ * Run fn(), retrying on SQLITE_BUSY with exponential back-off + up-to-50%
+ * random jitter. Any other error is rethrown immediately. SQLITE_BUSY after
+ * all attempts are exhausted is also rethrown.
+ *
+ * Delays: attempt 1→2 = baseMs, 2→3 = baseMs*2, … each + [0, delay*0.5)
+ * jitter. With defaults (maxAttempts=5, baseMs=10ms): 10, 20, 40, 80ms
+ * before each retry (plus jitter), worst-case ~220ms total wait.
+ */
+export declare function retryWrite<T>(fn: () => T, opts?: RetryWriteOptions): T;
+/** Synchronous sleep using Atomics.wait — blocks the thread without busy-spinning. */
+export declare function sleepMs(ms: number): void;

package/dist/backends/retry.js

@@ -0,0 +1,60 @@
+/**
+ * SQLITE_BUSY retry ladder with exponential backoff + jitter.
+ *
+ * better-sqlite3 is synchronous; these retries are synchronous too.
+ * Atomics.wait() provides a blocking sleep without busy-spinning — available
+ * on the main thread in Node >= 22 (our minimum engine requirement).
+ *
+ * Reference design: Memori core/src/storage/manager.rs::write_batch —
+ * retries SQLSTATE 40001 with exponential backoff + up to 50% jitter,
+ * folding commit() into the retried result. t-326.
+ */
+/**
+ * Run fn(), retrying on SQLITE_BUSY with exponential back-off + up-to-50%
+ * random jitter. Any other error is rethrown immediately. SQLITE_BUSY after
+ * all attempts are exhausted is also rethrown.
+ *
+ * Delays: attempt 1→2 = baseMs, 2→3 = baseMs*2, … each + [0, delay*0.5)
+ * jitter. With defaults (maxAttempts=5, baseMs=10ms): 10, 20, 40, 80ms
+ * before each retry (plus jitter), worst-case ~220ms total wait.
+ */
+export function retryWrite(fn, opts) {
+    const maxAttempts = opts?.maxAttempts ?? 5;
+    const baseMs = opts?.baseMs ?? 10;
+    let lastErr;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        try {
+            return fn();
+        }
+        catch (err) {
+            if (isSqliteBusy(err)) {
+                lastErr = err;
+                if (attempt < maxAttempts - 1) {
+                    const delay = baseMs * Math.pow(2, attempt);
+                    const jitter = delay * Math.random() * 0.5;
+                    sleepMs(Math.round(delay + jitter));
+                }
+                continue;
+            }
+            // Non-SQLITE_BUSY errors propagate immediately — never retry them.
+            throw err;
+        }
+    }
+    // Exhausted all attempts — rethrow the last SQLITE_BUSY.
+    throw lastErr;
+}
+function isSqliteBusy(err) {
+    if (!(err instanceof Error))
+        return false;
+    const e = err;
+    // better-sqlite3 sets .code = 'SQLITE_BUSY' on lock-contention errors.
+    return e.code === 'SQLITE_BUSY' || e.message.includes('SQLITE_BUSY');
+}
+/** Synchronous sleep using Atomics.wait — blocks the thread without busy-spinning. */
+export function sleepMs(ms) {
+    if (ms <= 0)
+        return;
+    // Node >= 22 allows Atomics.wait on the main thread; SharedArrayBuffer is
+    // available without flags. This is the canonical sync sleep in Node.js.
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}

package/dist/backends/salience.d.ts

@@ -0,0 +1,57 @@
+import { type Database } from 'better-sqlite3';
+/** Per-category half-life in days: hot working categories cool fast, identity-level facts cool slow. */
+export declare const HALF_LIVES: Record<string, number>;
+export declare const DEFAULT_HALF_LIFE_DAYS = 30;
+/**
+ * Temperature in (0, 1]: 1.0 at the moment of last touch, 0.5 after one
+ * category half-life, decaying exponentially after. `lastTouchIso` is the most
+ * recent of last_accessed / updated / created.
+ */
+export declare function temperature(lastTouchIso: string, category: string, nowMs: number): number;
+export type Tier = 'Hot' | 'Warm' | 'Cool';
+export declare function tierOf(temp: number): Tier;
+/**
+ * Recompute and STORE the salience scalar for every non-archived memory. Called
+ * by the consolidation lane (stored + lane-refresh, not computed-on-read).
+ * Returns the number of memories recomputed.
+ */
+export declare function recomputeSalience(db: Database, nowMs: number): number;
+export interface DigestRow {
+    title: string;
+    category: string;
+    content: string;
+    salience: number;
+}
+export interface DigestOptions {
+    /** Approximate token budget for the whole digest. */
+    tokenBudget?: number;
+    /** Rough chars-per-token for the budget estimate. */
+    charsPerToken?: number;
+}
+/**
+ * Assemble the boot digest from already-recomputed salience: order hottest-first,
+ * fill the token budget, group the included atoms under their tier headers. Pure
+ * selection + ordering of authored content — no generated prose, no persisted
+ * glue. Returns null when there is nothing to show.
+ */
+export declare function assembleDigest(rows: DigestRow[], opts?: DigestOptions): string | null;
+/** Lane entry point: recompute + store salience for a context. Returns count (or null if no store). */
+export declare function recomputeSalienceForContext(contextDir: string, nowMs: number): number | null;
+export interface DigestAtom {
+    title: string;
+    category: string;
+    content: string;
+    salience: number;
+    tier: Tier;
+}
+/**
+ * Structured salience digest for a UI widget: the hottest authored atoms,
+ * tier-labeled, ordered hot→cold, plus the total memory count. Same
+ * assemble-not-generate view as the text digest — just shaped for rendering.
+ */
+export declare function digestData(contextDir: string, limit?: number): {
+    atoms: DigestAtom[];
+    total: number;
+} | null;
+/** Assemble the boot digest for a context from stored salience. Returns null if no store / nothing hot. */
+export declare function digestForContext(contextDir: string, opts?: DigestOptions): string | null;

package/dist/backends/salience.js

@@ -0,0 +1,186 @@
+/**
+ * Salience temperature + the assembled boot digest (c-loom-memory: it-loom-salience).
+ *
+ * A memory's temperature is a stored scalar that DECAYS by a per-category
+ * half-life and REHEATS on access (recall stamps last_accessed; write/update
+ * stamps updated) — so a frequently-touched fact stays warm and an untouched one
+ * cools. The consolidation lane recomputes the stored field; the digest assembler
+ * fills a token budget HOTTEST-FIRST from existing authored atoms, labeled into
+ * tiers. It ASSEMBLES a view over authored memories — it never generates new
+ * prose (the integrity line: loom holds the pen, unlike Anthropic's native digest
+ * which is generated).
+ */
+import { existsSync } from 'node:fs';
+import BetterSqlite3 from 'better-sqlite3';
+import { resolveSqliteDbPath } from '../config.js';
+import { runMigrations } from './migrations.js';
+import { EPISODE_CATEGORY } from '../categories.js';
+import { retryWrite } from './retry.js';
+function hasColumn(db, table, column) {
+    return db.pragma(`table_info(${table})`).some((c) => c.name === column);
+}
+/** Per-category half-life in days: hot working categories cool fast, identity-level facts cool slow. */
+export const HALF_LIVES = {
+    episode: 1,
+    pursuit: 7,
+    project: 10,
+    self: 30,
+    feedback: 30,
+    reference: 45,
+    user: 90,
+};
+export const DEFAULT_HALF_LIFE_DAYS = 30;
+const DAY_MS = 86_400_000;
+/**
+ * Temperature in (0, 1]: 1.0 at the moment of last touch, 0.5 after one
+ * category half-life, decaying exponentially after. `lastTouchIso` is the most
+ * recent of last_accessed / updated / created.
+ */
+export function temperature(lastTouchIso, category, nowMs) {
+    const ageDays = Math.max(0, (nowMs - Date.parse(lastTouchIso)) / DAY_MS);
+    const halfLife = HALF_LIVES[category] ?? DEFAULT_HALF_LIFE_DAYS;
+    return Math.pow(2, -ageDays / halfLife);
+}
+export function tierOf(temp) {
+    if (temp >= 0.6)
+        return 'Hot';
+    if (temp >= 0.2)
+        return 'Warm';
+    return 'Cool';
+}
+/** Most-recent-touch timestamp for a row (recall/write reheat through these). */
+function lastTouch(r) {
+    return r.last_accessed ?? r.updated ?? r.created;
+}
+/**
+ * Recompute and STORE the salience scalar for every non-archived memory. Called
+ * by the consolidation lane (stored + lane-refresh, not computed-on-read).
+ * Returns the number of memories recomputed.
+ */
+export function recomputeSalience(db, nowMs) {
+    const rows = db
+        .prepare('SELECT id, category, created, updated, last_accessed FROM memories WHERE archived = 0')
+        .all();
+    const upd = db.prepare('UPDATE memories SET salience = ? WHERE id = ?');
+    const tx = db.transaction(() => {
+        for (const r of rows)
+            upd.run(temperature(lastTouch(r), r.category, nowMs), r.id);
+    });
+    // The nightly full-table recompute is the heaviest write in loom; wrap it so
+    // a concurrent remember() call during the recompute retries instead of throwing.
+    retryWrite(() => tx());
+    return rows.length;
+}
+const DEFAULT_TOKEN_BUDGET = 1200;
+const DEFAULT_CHARS_PER_TOKEN = 4;
+/** One line per atom: a trimmed, single-line view — selected, never synthesized. */
+function atomLine(r) {
+    const body = r.content.replace(/\s+/g, ' ').trim();
+    const clipped = body.length > 200 ? body.slice(0, 197).trimEnd() + '…' : body;
+    return `- **${r.title}** (${r.category}) — ${clipped}`;
+}
+/**
+ * Assemble the boot digest from already-recomputed salience: order hottest-first,
+ * fill the token budget, group the included atoms under their tier headers. Pure
+ * selection + ordering of authored content — no generated prose, no persisted
+ * glue. Returns null when there is nothing to show.
+ */
+export function assembleDigest(rows, opts = {}) {
+    const budgetChars = (opts.tokenBudget ?? DEFAULT_TOKEN_BUDGET) * (opts.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN);
+    const ordered = [...rows].sort((a, b) => b.salience - a.salience);
+    const picked = [];
+    let used = 0;
+    for (const r of ordered) {
+        const line = atomLine(r);
+        if (used + line.length > budgetChars && picked.length > 0)
+            break; // hottest-first to the cap
+        picked.push({ tier: tierOf(r.salience), line });
+        used += line.length + 1;
+    }
+    if (picked.length === 0)
+        return null;
+    const tierOrder = ['Hot', 'Warm', 'Cool'];
+    const tierLabel = {
+        Hot: 'Top of mind',
+        Warm: 'Recent',
+        Cool: 'Background',
+    };
+    const sections = [];
+    for (const tier of tierOrder) {
+        const lines = picked.filter((p) => p.tier === tier).map((p) => p.line);
+        if (lines.length)
+            sections.push(`## ${tierLabel[tier]}\n${lines.join('\n')}`);
+    }
+    return sections.join('\n\n');
+}
+// ── context-dir wrappers (open memories.db directly; no embedder needed) ──
+/** Open memories.db without the vector/embedder stack — salience is plain SQL. */
+function openMemoriesDb(contextDir, readonly) {
+    const dbPath = resolveSqliteDbPath(contextDir);
+    if (!existsSync(dbPath))
+        return null;
+    const db = new BetterSqlite3(dbPath, { readonly });
+    db.pragma('busy_timeout = 0');
+    return db;
+}
+/** Lane entry point: recompute + store salience for a context. Returns count (or null if no store). */
+export function recomputeSalienceForContext(contextDir, nowMs) {
+    const db = openMemoriesDb(contextDir, false);
+    if (!db)
+        return null;
+    try {
+        // Self-heal: a store that predates the salience migration gets it here, so
+        // the lane works on any store (migrations are idempotent).
+        if (!hasColumn(db, 'memories', 'salience'))
+            runMigrations(db, { strict: false });
+        return recomputeSalience(db, nowMs);
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Structured salience digest for a UI widget: the hottest authored atoms,
+ * tier-labeled, ordered hot→cold, plus the total memory count. Same
+ * assemble-not-generate view as the text digest — just shaped for rendering.
+ */
+export function digestData(contextDir, limit = 40) {
+    const db = openMemoriesDb(contextDir, true);
+    if (!db)
+        return null;
+    try {
+        if (!hasColumn(db, 'memories', 'salience'))
+            return { atoms: [], total: 0 };
+        const total = db.prepare('SELECT COUNT(*) AS n FROM memories WHERE archived = 0').get().n;
+        const rows = db
+            .prepare('SELECT title, category, content, salience FROM memories WHERE archived = 0 AND category != ? ORDER BY salience DESC LIMIT ?')
+            .all(EPISODE_CATEGORY, limit);
+        const atoms = rows.map((r) => ({ ...r, tier: tierOf(r.salience) }));
+        return { atoms, total };
+    }
+    finally {
+        db.close();
+    }
+}
+/** Assemble the boot digest for a context from stored salience. Returns null if no store / nothing hot. */
+export function digestForContext(contextDir, opts = {}) {
+    const db = openMemoriesDb(contextDir, true);
+    if (!db)
+        return null;
+    try {
+        // A store not yet migrated to salience simply has no digest yet (read-only
+        // path can't migrate; the lane / normal backend connect will add the column).
+        if (!hasColumn(db, 'memories', 'salience'))
+            return null;
+        const rows = db
+            .prepare(
+        // Episodes are the tape, not the digest: a fresh episode is always
+        // salience 1.0 and would crowd Top of Mind with what just happened.
+        'SELECT title, category, content, salience FROM memories WHERE archived = 0 AND category != ? ORDER BY salience DESC LIMIT 100')
+            .all(EPISODE_CATEGORY);
+        return assembleDigest(rows, opts);
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/backends/sqlite-knowledge.d.ts

@@ -0,0 +1,37 @@
+import type { KnowledgeBackend, KnowledgePageInput, KnowledgeCitationInput, KnowledgePageWithCitations, KnowledgeQueryInput, KnowledgeWriteResult, KnowledgeArchiveInput, KnowledgeArchiveResult, KnowledgeRestoreInput, KnowledgeRestoreResult, KnowledgeSupersededInput, KnowledgeSupersededResult, KnowledgeMoveInput, KnowledgeMoveResult, KnowledgeMergeInput, KnowledgeMergeResult, KnowledgePurgeInput, KnowledgePurgeResult, KnowledgeVerifyInput, KnowledgeVerifyResult, KnowledgeRevision, KnowledgeRevisionMeta, KnowledgeRevisionRestoreInput, KnowledgeRevisionRestoreResult } from './types.js';
+export interface SqliteKnowledgeConfig {
+    /** Absolute path to the knowledge SQLite database file */
+    dbPath: string;
+}
+export declare class SqliteKnowledgeBackend implements KnowledgeBackend {
+    private readonly config;
+    private db;
+    constructor(config: SqliteKnowledgeConfig);
+    writePage(input: KnowledgePageInput): Promise<KnowledgeWriteResult>;
+    getPage(slug: string, opts?: {
+        stampAccess?: boolean;
+    }): Promise<KnowledgePageWithCitations | null>;
+    listPages(input?: KnowledgeQueryInput): Promise<KnowledgePageWithCitations[]>;
+    queryPages(input: KnowledgeQueryInput): Promise<KnowledgePageWithCitations[]>;
+    archivePage(input: KnowledgeArchiveInput): Promise<KnowledgeArchiveResult>;
+    restorePage(input: KnowledgeRestoreInput): Promise<KnowledgeRestoreResult>;
+    supersedePage(input: KnowledgeSupersededInput): Promise<KnowledgeSupersededResult>;
+    movePage(input: KnowledgeMoveInput): Promise<KnowledgeMoveResult>;
+    mergePages(input: KnowledgeMergeInput): Promise<KnowledgeMergeResult>;
+    purgePages(input: KnowledgePurgeInput): Promise<KnowledgePurgeResult>;
+    verifyPages(input: KnowledgeVerifyInput): Promise<KnowledgeVerifyResult>;
+    listRevisions(slug: string): Promise<KnowledgeRevisionMeta[]>;
+    getRevision(revisionId: number): Promise<KnowledgeRevision | null>;
+    restoreRevision(input: KnowledgeRevisionRestoreInput): Promise<KnowledgeRevisionRestoreResult>;
+    /**
+     * Insert a body snapshot and prune beyond the per-page cap. Caller owns the
+     * transaction when called from restoreRevision; called bare from writePage.
+     * Each statement is wrapped in retryWrite so both call sites are safe.
+     */
+    private snapshotRevision;
+    addCitations(slug: string, citations: KnowledgeCitationInput[]): Promise<number>;
+    close(): void;
+    private ensureOpen;
+    private fetchCitationsForPage;
+    private initSchema;
+}