renor-engine 0.0.0-stage → 1.0.0

package/dist/mvp/memoryDir.js

@@ -0,0 +1,98 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureOwnerOnlyMemoryDir = ensureOwnerOnlyMemoryDir;
+exports.ensureOwnerOnlyFile = ensureOwnerOnlyFile;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * The memory directory holds the user's statements in plain text (daily notes, the ledger) and the index built
+ * from them, so it is owner-only, as the OAuth client store already is. A directory the running user owns that
+ * group or others can reach is tightened at start (0700 for directories, 0600 for files, one log line); one that
+ * cannot be tightened, because someone else owns it or the change is refused, stops the start.
+ */
+function failClosed(dir, reason) {
+    throw new Error(`Memory directory is not usable: ${reason}. `
+        + 'Refusing to start with a memory directory other users can read (fail closed). '
+        + `Run: chmod -R go-rwx ${JSON.stringify(dir)} as its owner, then start again.`);
+}
+const accessibleByOthers = (mode) => (mode & 0o077) !== 0;
+/** Tightens what is owned by `uid` under `dir`, without following symlinks; what someone else owns is left alone. */
+function tightenTree(dir, uid) {
+    for (const entry of fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+        const full = path_1.default.join(dir, entry.name);
+        if (entry.isSymbolicLink())
+            continue;
+        const stat = fs_1.default.lstatSync(full);
+        if (stat.uid !== uid)
+            continue;
+        if (entry.isDirectory()) {
+            if (accessibleByOthers(stat.mode))
+                fs_1.default.chmodSync(full, 0o700);
+            tightenTree(full, uid);
+        }
+        else if (entry.isFile() && accessibleByOthers(stat.mode)) {
+            fs_1.default.chmodSync(full, 0o600);
+        }
+    }
+}
+/**
+ * Creates the directory owner-only (0700) when it does not exist. One that exists must be a directory owned by the
+ * running user; if group or others can access it, it is tightened (everything under it that the user owns too) and
+ * `log` is told once. Symlinked paths are followed (the directory may live on another disk).
+ */
+function ensureOwnerOnlyMemoryDir(dir, log = console.log) {
+    try {
+        fs_1.default.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    catch (err) {
+        // A file at the path is reported below as what it is.
+        if (err.code !== 'EEXIST')
+            throw err;
+    }
+    const uid = process.getuid?.();
+    // No POSIX owner to compare on this platform; the client store refuses to run there as well.
+    if (uid === undefined)
+        return;
+    let stat;
+    try {
+        stat = fs_1.default.statSync(dir);
+    }
+    catch (err) {
+        failClosed(dir, `it is unreadable (${err.code})`);
+    }
+    if (!stat.isDirectory())
+        failClosed(dir, 'the path is not a directory');
+    if (stat.uid !== uid)
+        failClosed(dir, 'it is not owned by the service user, so it cannot be tightened to owner-only (0700)');
+    if (!accessibleByOthers(stat.mode))
+        return;
+    const was = (stat.mode & 0o777).toString(8);
+    try {
+        fs_1.default.chmodSync(dir, 0o700);
+        tightenTree(dir, uid);
+    }
+    catch (err) {
+        failClosed(dir, `it is accessible by group or others (mode ${was}) and cannot be tightened to owner-only (0700) (${err.code})`);
+    }
+    log(`[mvp] memory directory ${dir} was accessible by group or others (mode ${was}); tightened to owner-only: directories 0700, files 0600`);
+}
+/** A database file that exists and group or others can reach is tightened to 0600, with its -wal and -shm files. */
+function ensureOwnerOnlyFile(file) {
+    const uid = process.getuid?.();
+    if (uid === undefined)
+        return;
+    for (const candidate of [file, `${file}-wal`, `${file}-shm`]) {
+        let stat;
+        try {
+            stat = fs_1.default.lstatSync(candidate);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isFile() && stat.uid === uid && accessibleByOthers(stat.mode))
+            fs_1.default.chmodSync(candidate, 0o600);
+    }
+}

package/dist/mvp/posthogMcp.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redactMcpAnalyticsEvent = redactMcpAnalyticsEvent;
+exports.instrumentMcpServer = instrumentMcpServer;
+exports.shutdownPosthogMcp = shutdownPosthogMcp;
+exports.resetPosthogMcpForTests = resetPosthogMcpForTests;
+const node_crypto_1 = require("node:crypto");
+const telemetry_1 = require("./telemetry");
+/**
+ * PostHog MCP Analytics (@posthog/mcp) for the production MVP server.
+ *
+ * Privacy defaults match Renor's contract: never capture tool args, results,
+ * memory content, queries, or model/conversation text. Instrumentation is a
+ * no-op when RENOR_POSTHOG_KEY is missing or RENOR_TELEMETRY_DISABLED=true.
+ */
+const DEFAULT_HOST = 'https://us.i.posthog.com';
+// The two packages are ~130 modules and ~110 ms of a cold start (measured with scripts/bench/cold-start.ts), and a
+// workspace without RENOR_POSTHOG_KEY, or with remote telemetry off, never calls into them (instrumentMcpServer returns
+// first). They are loaded here, on the first call that needs them, which is the same moment a configured workspace
+// loaded them before: createMvpApp builds its first server before the service listens.
+const loadPosthogNode = () => require('posthog-node');
+const loadPosthogMcp = () => require('@posthog/mcp');
+/** Property keys that may carry args/results/content — always stripped. */
+const STRIP_EXACT = new Set([
+    '$mcp_parameters',
+    '$mcp_response',
+    '$mcp_intent',
+    '$mcp_error_message',
+    '$mcp_feedback_details',
+    '$mcp_feedback_summary',
+    '$mcp_feedback_suggested_improvement',
+    '$mcp_feedback_friction_points',
+    '$mcp_tool_description',
+    'args',
+    'arguments',
+    'params',
+    'parameters',
+    'result',
+    'response',
+    'content',
+    'query',
+    'statement',
+    'text',
+    'body',
+    'message',
+]);
+const STRIP_SUBSTRING = [
+    'parameter',
+    'argument',
+    'response',
+    'content',
+    'query',
+    'statement',
+    'memory',
+    'prompt',
+    'exception_message',
+    'exception_stack',
+];
+let client;
+let shutdownHookInstalled = false;
+function env(name) {
+    return (process.env[name] ?? '').trim();
+}
+function remoteDisabled() {
+    return env('RENOR_TELEMETRY_DISABLED').toLowerCase() === 'true';
+}
+function pseudonymousDistinctId(instance) {
+    const salt = env('RENOR_TELEMETRY_HASH_SALT');
+    return (0, node_crypto_1.createHash)('sha256')
+        .update(`renor-telemetry:\0${salt}\0${instance}`)
+        .digest('hex')
+        .slice(0, 24);
+}
+/** Testable privacy filter — strips args/results/content; keeps tool/ok/duration. */
+function redactMcpAnalyticsEvent(event) {
+    if (!event || typeof event !== 'object')
+        return null;
+    // Exception siblings can embed stack/message text — drop entirely.
+    if (event.event === '$exception')
+        return null;
+    const properties = { ...(event.properties ?? {}) };
+    for (const key of Object.keys(properties)) {
+        const lower = key.toLowerCase();
+        if (STRIP_EXACT.has(key) || STRIP_EXACT.has(lower)) {
+            delete properties[key];
+            continue;
+        }
+        if (STRIP_SUBSTRING.some((needle) => lower.includes(needle))) {
+            // Keep known-safe metadata keys even if they contain a substring match.
+            if (key === '$mcp_is_error' ||
+                key === '$mcp_duration_ms' ||
+                key === '$mcp_tool_name' ||
+                key === '$mcp_client_name' ||
+                key === '$mcp_client_version' ||
+                key === '$mcp_server_name' ||
+                key === '$mcp_server_version' ||
+                key === '$mcp_protocol_version' ||
+                key === '$mcp_listed_tool_names' ||
+                key === '$mcp_source' ||
+                key === '$groups' ||
+                key === '$process_person_profile' ||
+                key === 'service') {
+                continue;
+            }
+            delete properties[key];
+        }
+    }
+    return {
+        distinct_id: event.distinct_id,
+        event: event.event,
+        timestamp: event.timestamp,
+        type: 'capture',
+        properties,
+    };
+}
+function getOrCreateClient() {
+    if (client !== undefined)
+        return client;
+    if (remoteDisabled()) {
+        client = null;
+        return null;
+    }
+    const apiKey = env('RENOR_POSTHOG_KEY');
+    if (!apiKey) {
+        client = null;
+        return null;
+    }
+    const host = env('RENOR_POSTHOG_HOST') || DEFAULT_HOST;
+    try {
+        client = new (loadPosthogNode().PostHog)(apiKey, {
+            host,
+            // Privacy: do not capture IP / personal profiles by default.
+            disableGeoip: true,
+        });
+    }
+    catch {
+        client = null;
+    }
+    return client;
+}
+function installShutdownHook() {
+    if (shutdownHookInstalled)
+        return;
+    shutdownHookInstalled = true;
+    // Best-effort: cli.ts also awaits shutdownPosthogMcp on SIGINT/SIGTERM.
+    // This covers process paths that skip the CLI handler.
+    const onSignal = () => {
+        void shutdownPosthogMcp();
+    };
+    process.once('beforeExit', onSignal);
+}
+/**
+ * Instrument one McpServer instance (call inside buildMcpServer — SSE builds
+ * a fresh server per session). No-ops when PostHog is disabled/unconfigured.
+ */
+function instrumentMcpServer(server) {
+    try {
+        const posthog = getOrCreateClient();
+        if (!posthog)
+            return;
+        const tenant = (0, telemetry_1.telemetryInstanceId)();
+        const distinctId = pseudonymousDistinctId(tenant);
+        loadPosthogMcp().instrument(server, posthog, {
+            context: false,
+            enableConversationId: false,
+            captureModel: false,
+            enableExceptionAutocapture: false,
+            identify: async () => ({
+                distinctId,
+                // The workspace as PostHog's `tenant` group, filed under the same salted hash as the distinct id and
+                // never under the slug: a slug made before opaque workspace names is the owner's email local part.
+                groups: tenant && tenant !== 'unknown' ? { tenant: distinctId } : undefined,
+                properties: {
+                    service: 'renor-core',
+                    $process_person_profile: false,
+                },
+            }),
+            eventProperties: async () => ({
+                service: 'renor-core',
+                $process_person_profile: false,
+            }),
+            beforeSend: redactMcpAnalyticsEvent,
+            logger: () => {
+                // STDIO-safe: discard SDK warnings (HTTP MVP uses stderr only if needed).
+            },
+        });
+        installShutdownHook();
+    }
+    catch {
+        // Observability must never break the product.
+    }
+}
+/** Flush + stop the shared posthog-node client (SIGINT/SIGTERM). */
+async function shutdownPosthogMcp() {
+    const current = client;
+    client = null;
+    if (!current)
+        return;
+    try {
+        await current.shutdown();
+    }
+    catch {
+        // ignore
+    }
+}
+/** Test helper: reset singleton between hermetic tests. */
+function resetPosthogMcpForTests() {
+    client = undefined;
+    shutdownHookInstalled = false;
+}

package/dist/mvp/readScope.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createReadScope = createReadScope;
+const readCache_1 = require("../db/readCache");
+const statements_1 = require("../db/statements");
+const lifecycle_1 = require("../memory/lifecycle");
+const ledgerLiveness_1 = require("../retrieval/ledgerLiveness");
+const scope_1 = require("./scope");
+/** How many chunks naming an event make reading every event's scope at once cheaper than asking about each. */
+const PRELOAD_EVENTS_FROM = 64;
+function createReadScope(db, scope) {
+    const projected = (0, readCache_1.tableHasColumns)(db, 'facts', ['event_id', 'scope']);
+    const eventRow = projected
+        ? (0, statements_1.prepareOnce)(db, `SELECT COALESCE(scope, 'global') AS scope FROM facts WHERE event_id = ? AND source_path = ?`)
+        : null;
+    const factRow = projected
+        ? (0, statements_1.prepareOnce)(db, `SELECT COALESCE(scope, 'global') AS scope FROM facts WHERE id = ? AND source_path = ?`)
+        : null;
+    const own = (0, scope_1.savedScopeSqlPredicate)(scope, `COALESCE(scope, 'global')`);
+    const otherScopeRows = projected
+        ? (0, statements_1.prepareOnce)(db, `SELECT event_id FROM facts WHERE source_path = ? AND event_id IS NOT NULL AND NOT (${own.sql})`)
+        : null;
+    // Event ids are stored upper-case, so the unique index on facts(event_id) answers each lookup.
+    const events = new Map();
+    /** The scope an event was saved in; undefined when the lifecycle layer knows no such event. */
+    const eventScope = (id) => {
+        const key = id.toUpperCase();
+        if (!events.has(key))
+            events.set(key, eventRow?.get(key, lifecycle_1.LIFECYCLE_NOTE_PATH)?.scope);
+        return events.get(key);
+    };
+    /**
+     * Every event's scope in one read, for the pass over the index (`chunkIds`) that asks about the event of each of its
+     * thousands of ledger chunks: one statement each was most of a scoped read's cost, growing with every fact saved. What
+     * is kept is what `eventScope` would find: the event of that upper-case id, in the lifecycle layer. An id that is not
+     * kept (not upper-case, or not an event) is asked about one by one, as before.
+     */
+    const preloadEvents = () => {
+        if (!projected)
+            return;
+        const rows = (0, statements_1.prepareOnce)(db, `SELECT event_id AS id, COALESCE(scope, 'global') AS scope FROM facts WHERE source_path = ? AND event_id IS NOT NULL`).all(lifecycle_1.LIFECYCLE_NOTE_PATH);
+        for (const row of rows)
+            if (row.id === row.id.toUpperCase() && !events.has(row.id))
+                events.set(row.id, row.scope);
+    };
+    let elsewhere; // ids (lower-case) of the events saved in other scopes, read on first use
+    const has = (hit, notePath) => {
+        // A fact has no note path to judge it by: the scope on its row decides, and a fact whose row is gone is dropped.
+        if (hit.notePath === lifecycle_1.LIFECYCLE_NOTE_PATH && typeof hit.chunkId === 'number' && hit.chunkId < 0) {
+            const row = factRow?.get(-hit.chunkId, lifecycle_1.LIFECYCLE_NOTE_PATH);
+            return row !== undefined && (0, scope_1.savedScopeMatches)(row.scope, scope);
+        }
+        // A hit is one chunk, so one event (the chunker splits at every event heading): shown whole, or not at all.
+        // Anything that only looks like an event id (an ordinary heading) is no event, and its note path decides.
+        const saved = (0, ledgerLiveness_1.ledgerEventIds)(hit).map(eventScope).filter((s) => s !== undefined);
+        if (saved.length)
+            return saved.every(s => (0, scope_1.savedScopeMatches)(s, scope));
+        return (0, scope_1.notePathMatchesScope)(notePath, scope);
+    };
+    return {
+        has,
+        hits(hits, notePath) {
+            return hits.filter(hit => has(hit, notePath(hit)));
+        },
+        body(text) {
+            // Only the ledger holds events: any other note is returned as it is, without asking the database anything.
+            if (!(0, ledgerLiveness_1.ledgerEventIds)({ text }).length)
+                return text;
+            // A body holds every event, so the ids of other scopes' events are read in one query, once per read, rather than
+            // looked up event by event (a 3,000-event ledger: body() 19 ms, now 6 ms).
+            elsewhere ??= new Set((otherScopeRows?.all(lifecycle_1.LIFECYCLE_NOTE_PATH, ...own.params) ?? [])
+                .map(r => r.event_id.toLowerCase()));
+            if (!elsewhere.size)
+                return text;
+            // The note is cut block by block. Another scope's events go the way closed ones go without history: never
+            // shown, and never labelled as history either.
+            return (0, ledgerLiveness_1.resolveLedgerHits)([{ text, reason: 'other-scope' }], elsewhere, false)[0]?.text ?? '';
+        },
+        chunkIds(notePath) {
+            // `has` reads a chunk's text only for a line that opens an event (`## MEM_… · `, in any case): every other text is
+            // read here as empty, so the pass reads paths and headings, and the text of the few chunks that could hold one. A
+            // named scope holds no chunk that names no event outside its own directory (scopeSqlPredicate, the SQL twin of
+            // notePathMatchesScope), so only the chunks under it or naming an event are judged; the global scope, every chunk.
+            const namesEvent = "text GLOB '*## [Mm][Ee][Mm]_*'";
+            const under = scope === 'global' ? null : (0, scope_1.scopeSqlPredicate)(scope, 'note_path');
+            const rows = (0, statements_1.prepareOnce)(db, `SELECT id AS chunkId, note_path AS notePath, heading_path AS headingPath,
+                CASE WHEN ${namesEvent} THEN text ELSE '' END AS text
+         FROM chunks${under ? ` WHERE ${under.sql} OR ${namesEvent} OR heading_path GLOB '*[Mm][Ee][Mm]_*'` : ''}`).all(...(under?.params ?? []));
+            // A chunk that names an event is the only one that asks the lifecycle layer anything: a few ask one by one, a
+            // ledger's thousands ask all at once.
+            const namesOne = (row) => row.text !== '' || (row.headingPath ?? '').toUpperCase().includes('MEM_');
+            if (rows.reduce((n, row) => n + (namesOne(row) ? 1 : 0), 0) > PRELOAD_EVENTS_FROM)
+                preloadEvents();
+            const shown = new Map(); // a note's chunks share its path (the ledger is one note)
+            const pathOf = (stored) => {
+                let judged = shown.get(stored);
+                if (judged === undefined)
+                    shown.set(stored, (judged = notePath(stored)));
+                return judged;
+            };
+            return rows.filter(row => has(row, pathOf(row.notePath))).map(row => row.chunkId);
+        },
+    };
+}

package/dist/mvp/readUsefulness.js

@@ -0,0 +1,222 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReadUsefulness = exports.DEFAULT_USE_WINDOW_MINUTES = void 0;
+exports.noteItem = noteItem;
+exports.factItem = factItem;
+exports.contextItems = contextItems;
+exports.searchItems = searchItems;
+exports.retrieveItems = retrieveItems;
+const node_crypto_1 = require("node:crypto");
+const statements_1 = require("../db/statements");
+const ledgerLiveness_1 = require("../retrieval/ledgerLiveness");
+const telemetry_1 = require("./telemetry");
+/** How long after a read a use still counts. Long enough for a multi-step task, short enough to stay one working session. */
+exports.DEFAULT_USE_WINDOW_MINUTES = 30;
+const MAX_WINDOW_MINUTES = 240;
+/** Reads kept to be matched, so a busy workspace cannot grow the tracker without bound. */
+const MAX_TRACKED_READS = 300;
+/** Ids an event lists; `items` still counts them all. */
+const MAX_EVENT_IDS = 20;
+const norm = (value) => value.normalize('NFKC').toLowerCase().replace(/\s+/g, ' ').trim();
+function noteItem(notePath) {
+    return { key: `note:${notePath}` };
+}
+function factItem(subject, predicate) {
+    return { key: `fact:${norm(subject)}\0${norm(predicate)}`, handles: [`subject:${norm(subject)}`] };
+}
+/** The note a memory id names (`note:<path>`, `entry:<path>#<hash>`), or the text itself when it names none. */
+function noteOfId(id) {
+    if (id.startsWith('note:'))
+        return id.slice(5);
+    if (id.startsWith('entry:')) {
+        const hashAt = id.lastIndexOf('#');
+        return hashAt > 6 ? id.slice(6, hashAt) : id.slice(6);
+    }
+    return id;
+}
+function windowMs(env) {
+    const parsed = Number((env.RENOR_READ_USE_WINDOW_MINUTES ?? '').trim());
+    const minutes = Number.isFinite(parsed) && parsed >= 1 ? Math.min(MAX_WINDOW_MINUTES, Math.trunc(parsed)) : exports.DEFAULT_USE_WINDOW_MINUTES;
+    return minutes * 60_000;
+}
+class ReadUsefulness {
+    emit;
+    now;
+    reads = [];
+    secret = (0, node_crypto_1.randomBytes)(32);
+    windowMs;
+    constructor(emit = telemetry_1.emitTelemetry, now = Date.now, env = process.env) {
+        this.emit = emit;
+        this.now = now;
+        this.windowMs = windowMs(env);
+    }
+    opaque(key) {
+        return (0, node_crypto_1.createHmac)('sha256', this.secret).update(key).digest('hex').slice(0, 8);
+    }
+    /** Builds what a reply served and records it. Building reads the database, so it is inside the guard too. */
+    measure(tool, build) {
+        try {
+            const served = build();
+            this.served(tool, served.items, served.relevant, served.judged);
+        }
+        catch {
+            // Measuring must never break a read.
+        }
+    }
+    /** A reply was served. `items` are its returned items; `relevant` and `judged` as described above. */
+    served(tool, items, relevant, judged) {
+        try {
+            const at = this.now();
+            const unique = new Map();
+            for (const item of items)
+                if (!unique.has(item.key))
+                    unique.set(item.key, item);
+            const id = (0, node_crypto_1.randomBytes)(4).toString('hex');
+            this.emit({
+                event: 'read',
+                tool,
+                read: id,
+                relevant,
+                judged,
+                items: unique.size,
+                ids: [...unique.keys()].slice(0, MAX_EVENT_IDS).map(key => this.opaque(key)),
+            });
+            if (!relevant || unique.size === 0)
+                return;
+            this.prune(at);
+            this.reads.push({
+                id,
+                tool,
+                at,
+                keys: new Set(unique.keys()),
+                handles: new Set([...unique.values()].flatMap(item => item.handles ?? [])),
+                used: false,
+            });
+            if (this.reads.length > MAX_TRACKED_READS)
+                this.reads.splice(0, this.reads.length - MAX_TRACKED_READS);
+        }
+        catch {
+            // Measuring must never break a read.
+        }
+    }
+    /** The agent read one memory in full (read_memory). */
+    readInFull(memoryId) {
+        this.use('read', read => read.keys.has(`note:${noteOfId(memoryId)}`));
+    }
+    /** A save named what it builds on. Each cite is a notePath or memory id a read returned, or a fact's subject. */
+    cited(cites) {
+        if (!cites?.length)
+            return;
+        const wanted = cites.slice(0, 20).map(cite => cite.trim()).filter(Boolean);
+        this.use('cite', read => wanted.some(cite => read.keys.has(`note:${noteOfId(cite)}`) || read.handles.has(`subject:${norm(cite)}`)));
+    }
+    /** A fact was saved with a new value for a subject and predicate (a correction or an update). */
+    updated(subject, predicate) {
+        const key = factItem(subject, predicate).key;
+        this.use('update', read => read.keys.has(key));
+    }
+    use(via, matches) {
+        try {
+            const at = this.now();
+            this.prune(at);
+            for (const read of this.reads) {
+                if (read.used || !matches(read))
+                    continue;
+                read.used = true;
+                this.emit({
+                    event: 'read_used',
+                    tool: read.tool,
+                    read: read.id,
+                    via,
+                    after_s: Math.max(0, Math.round((at - read.at) / 1000)),
+                });
+            }
+        }
+        catch {
+            // Measuring must never break a save.
+        }
+    }
+    prune(at) {
+        const cutoff = at - this.windowMs;
+        let drop = 0;
+        while (drop < this.reads.length && this.reads[drop].at < cutoff)
+            drop++;
+        if (drop > 0)
+            this.reads.splice(0, drop);
+    }
+}
+exports.ReadUsefulness = ReadUsefulness;
+// ---- What each tool's reply serves ---------------------------------------------------------------------------------
+/** get_context: its facts by subject and predicate, its memories by note. A memory of a saved fact names no note. */
+function contextItems(body) {
+    const items = [];
+    for (const fact of Array.isArray(body.facts) ? body.facts : []) {
+        if (typeof fact.subject === 'string' && typeof fact.predicate === 'string')
+            items.push(factItem(fact.subject, fact.predicate));
+    }
+    for (const memory of Array.isArray(body.memories) ? body.memories : []) {
+        if (typeof memory.notePath === 'string' && memory.notePath !== '')
+            items.push(noteItem(memory.notePath));
+        else if (typeof memory.text === 'string')
+            items.push({ key: `text:${memory.text}` });
+    }
+    return verdictOf(body.relevance, items);
+}
+function verdictOf(relevance, items) {
+    const judged = typeof relevance === 'object' && relevance !== null && typeof relevance.relevant === 'boolean';
+    return { items, relevant: judged ? relevance.relevant : items.length > 0, judged };
+}
+/**
+ * search_memory: its hits as they are before the ledger's markup is taken off, so a fact is named by what it claims. A hit
+ * of the ledger names the facts of its events (the facts table knows each event's subject and predicate); anything else is
+ * a note.
+ */
+function searchItems(db, isLedger, hits, relevance) {
+    const events = new Set();
+    for (const hit of hits)
+        if (isLedger(hit.notePath))
+            for (const id of (0, ledgerLiveness_1.ledgerEventIds)(hit))
+                events.add(id);
+    const named = new Map();
+    if (events.size > 0) {
+        const ids = [...events];
+        const rows = (0, statements_1.listStatement)(db, ids.length, marks => `SELECT lower(f.event_id) AS event, e.canonical_name AS subject, f.predicate AS predicate
+       FROM facts f JOIN entities e ON e.id = f.subject_entity_id
+       WHERE lower(f.event_id) IN (${marks})`).all(...(0, statements_1.paddedList)(ids));
+        for (const row of rows)
+            named.set(row.event, row);
+    }
+    const items = [];
+    for (const hit of hits) {
+        if (!isLedger(hit.notePath)) {
+            items.push(hit.notePath ? noteItem(hit.notePath) : { key: `text:${hit.text}` });
+            continue;
+        }
+        const facts = (0, ledgerLiveness_1.ledgerEventIds)(hit).map(id => named.get(id)).filter((fact) => fact !== undefined);
+        if (facts.length > 0) {
+            for (const fact of facts)
+                items.push(factItem(fact.subject, fact.predicate));
+            continue;
+        }
+        // A fact the index has not caught up with is headed `subject > predicate`.
+        const [subject, predicate] = (hit.headingPath ?? '').split(' > ');
+        items.push(subject && predicate ? factItem(subject, predicate) : { key: `text:${hit.text}` });
+    }
+    return verdictOf(relevance, items);
+}
+/** retrieve_memory: the facts of the subject it was asked for, by the subject the facts table names them under. */
+function retrieveItems(db, facts) {
+    const ids = [...new Set(facts.map(f => f.subject_entity_id).filter((id) => typeof id === 'number'))];
+    const names = new Map();
+    if (ids.length > 0) {
+        const rows = db.prepare(`SELECT id, canonical_name AS name FROM entities WHERE id IN (${ids.map(() => '?').join(',')})`)
+            .all(...ids);
+        for (const row of rows)
+            names.set(row.id, row.name);
+    }
+    const items = facts.flatMap(f => {
+        const subject = f.subject_entity_id === undefined ? undefined : names.get(f.subject_entity_id);
+        return subject === undefined ? [] : [factItem(subject, f.predicate)];
+    });
+    return { items, relevant: items.length > 0, judged: false };
+}