@zenera/neo 1.1.22 → 1.1.24

package/dist/memory/merge.js

@@ -0,0 +1,379 @@
+import { createHash } from 'node:crypto';
+import { readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { hostPath } from "./files.js";
+import { DUPLICATE_SCORE, flatten } from "./index.js";
+import { MANIFEST_FILE, MemoryStore, lockHolder } from "./store.js";
+import { MemoryError } from "./types.js";
+// ---------------------------------------------------------------------------
+// Folding several memories into one
+//
+// Warming a memory is embarrassingly parallel — N runs, N questions, N answers
+// — but the lock is per directory, so N runs cannot share one. They each write
+// their own, and this puts the results back together.
+//
+// Ids are ULIDs and are preserved, which makes the interesting case the one
+// where the same id appears twice: the runs started from a copy of the same
+// memory, so most of what they hold is a shared ancestor rather than a
+// collision. That case reconciles to nothing more than counters, and the
+// counters take the MAX rather than the sum, because merging the same source
+// twice has to be a no-op. Anything that is not a shared ancestor is a real
+// divergence and refuses the whole merge; `force` is the escape hatch, not the
+// default, because picking a winner silently loses a memory.
+//
+// Nothing here embeds. A merge is offline and fast, and the price of that is
+// that every side must already agree on the embedder.
+// ---------------------------------------------------------------------------
+/** How much of a diverged memory's text a conflict report carries. */
+const CLIP = 80;
+/**
+ * Refusal carrying what to look at. Thrown before anything is written, so a
+ * conflicted merge leaves the target exactly as it was.
+ */
+export class MergeConflicts extends MemoryError {
+    conflicts;
+    constructor(conflicts) {
+        super(`${conflicts.length} ${conflicts.length === 1 ? 'memory' : 'memories'} changed in more than one place`, 'compare them with `zen memory show <id>`, or take the newest with --force');
+        this.name = 'MergeConflicts';
+        this.conflicts = conflicts;
+    }
+}
+/**
+ * Fold `sources` into `target`, left to right.
+ *
+ * Order is visible: a memory folded onto a twin keeps the id of whichever copy
+ * arrived first, so `merge a b` and `merge b a` can differ in which id
+ * survives. They never differ in what is remembered.
+ *
+ * On `dryRun` the target is left with the merge applied in memory and nothing
+ * on disk. Report the result and discard the store; do not commit it.
+ */
+export async function mergeMemories(target, sources, opts = {}) {
+    const dedupe = opts.dedupe !== false;
+    const opened = await openSources(target, sources, opts.force === true);
+    const reports = new Map(opened.map((src) => [
+        src,
+        {
+            dir: src.dir,
+            nodes: src.graph.order,
+            edges: src.graph.size,
+            added: 0,
+            shared: 0,
+            twins: 0,
+            files: 0,
+        },
+    ]));
+    const embedding = agree(target, opened);
+    if (embedding) {
+        target.adopt(embedding);
+    }
+    // --- plan: everything refusable is refused here, before a single write ---
+    const plan = new Map();
+    for (const node of target.graph.nodes()) {
+        plan.set(node.id, { node, fresh: false });
+    }
+    const conflicts = [];
+    for (const src of opened) {
+        const report = reports.get(src);
+        for (const node of src.graph.nodes()) {
+            const held = plan.get(node.id);
+            if (!held) {
+                plan.set(node.id, { node, from: src, fresh: true });
+                continue;
+            }
+            if (held.node.revision === node.revision && sameContent(held.node, node)) {
+                plan.set(node.id, { ...held, node: reconcile(held.node, node) });
+                report.shared++;
+                continue;
+            }
+            if (!opts.force) {
+                conflicts.push({
+                    id: node.id,
+                    dir: src.dir,
+                    mine: held.node.revision,
+                    theirs: node.revision,
+                    text: clip(node.text),
+                });
+                continue;
+            }
+            report.shared++;
+            plan.set(node.id, newer(node, held.node)
+                ? { node: reconcile(node, held.node), from: src, fresh: held.fresh }
+                : { ...held, node: reconcile(held.node, node) });
+        }
+    }
+    if (conflicts.length) {
+        throw new MergeConflicts(conflicts);
+    }
+    await checkFiles(plan);
+    // --- fold, in memory ---
+    const before = target.graph.size;
+    const moved = new Map();
+    for (const planned of plan.values()) {
+        if (planned.fresh) {
+            continue;
+        }
+        target.graph.adopt(planned.node);
+        if (planned.from) {
+            carryVector(planned.from, target, planned.node.id);
+        }
+    }
+    const lexical = new Map();
+    for (const node of target.graph.nodes()) {
+        lexical.set(twinKey(node), node.id);
+    }
+    for (const src of opened) {
+        const report = reports.get(src);
+        const stale = target.graph.superseded();
+        for (const node of src.graph.nodes()) {
+            const planned = plan.get(node.id);
+            if (!planned.fresh || planned.from !== src || moved.has(node.id)) {
+                continue;
+            }
+            const twin = dedupe ? twinOf(target, src, planned.node, lexical, stale) : undefined;
+            if (twin) {
+                moved.set(node.id, twin);
+                report.twins++;
+                continue;
+            }
+            target.graph.adopt(planned.node);
+            carryVector(src, target, node.id);
+            lexical.set(twinKey(planned.node), node.id);
+            moved.set(node.id, node.id);
+            report.added++;
+        }
+        for (const link of src.graph.links()) {
+            const from = moved.get(link.source) ?? link.source;
+            const to = moved.get(link.target) ?? link.target;
+            // A self-edge is what a fold leaves behind when both ends collapsed
+            // onto the same memory; it says nothing and is dropped.
+            if (from === to || !target.graph.has(from) || !target.graph.has(to)) {
+                continue;
+            }
+            target.graph.adoptEdge(from, to, link.attrs);
+        }
+    }
+    const report = {
+        dir: target.dir,
+        sources: opened.map((src) => reports.get(src)),
+        added: 0,
+        shared: 0,
+        twins: 0,
+        edges: target.graph.size - before,
+        files: 0,
+        ...(target.embedding ? { embedding: target.embedding } : {}),
+        dryRun: opts.dryRun === true,
+    };
+    if (opts.dryRun) {
+        for (const [id, planned] of plan) {
+            if (copies(id, planned, moved)) {
+                reports.get(planned.from).files++;
+            }
+        }
+        return total(report);
+    }
+    await copyFiles(target, plan, moved, reports);
+    await target.commit();
+    return total(report);
+}
+async function openSources(target, sources, force) {
+    if (!sources.length) {
+        throw new MemoryError('no memories to merge', 'name at least one memory directory');
+    }
+    const here = resolve(target.dir);
+    const seen = new Set();
+    const out = [];
+    for (const dir of sources) {
+        const path = resolve(dir);
+        if (path === here) {
+            throw new MemoryError(`${dir} is the memory being merged into`, 'name only the memories to fold in');
+        }
+        if (seen.has(path)) {
+            throw new MemoryError(`${dir} was named twice`, 'name each memory once');
+        }
+        seen.add(path);
+        // `MemoryStore.open` creates what is missing, so a mistyped path would
+        // otherwise merge an empty memory it had just brought into existence.
+        try {
+            await stat(join(path, MANIFEST_FILE));
+        }
+        catch {
+            throw new MemoryError(`${dir} is not a memory`, `no ${MANIFEST_FILE} in it`);
+        }
+        const held = lockHolder(path);
+        if (held && !force) {
+            throw new MemoryError(`${dir} is in use (pid ${held.pid}, since ${held.startedAt})`, 'wait for that run to finish, or merge with --force');
+        }
+        out.push(await MemoryStore.open(path, { lock: false }));
+    }
+    return out;
+}
+/**
+ * The one embedder everything must already share. Sources that hold nothing are
+ * not asked: a warmup run that found nothing worth keeping never adopted one.
+ */
+function agree(target, sources) {
+    const holding = sources.filter((src) => src.graph.order > 0);
+    const chosen = target.embedding ?? holding.find((src) => src.embedding)?.embedding;
+    for (const src of holding) {
+        const theirs = src.embedding;
+        if (chosen && theirs) {
+            if (theirs.model !== chosen.model || theirs.dimensions !== chosen.dimensions) {
+                throw new MemoryError(`${src.dir} was embedded with ${theirs.model} (${theirs.dimensions}d), ` +
+                    `but this merge is ${chosen.model} (${chosen.dimensions}d)`, 'merge memories warmed with the same embedder');
+            }
+        }
+        else if (chosen) {
+            throw new MemoryError(`${src.dir} has no embedder, but this merge is ${chosen.model} (${chosen.dimensions}d)`, 'its memories would be invisible to search; re-warm it with that embedder');
+        }
+    }
+    return chosen;
+}
+/**
+ * The existing twin rule, applied across memories: same kind, same audience, no
+ * file, not superseded, and either near-identical by cosine or identical once
+ * whitespace and case stop counting.
+ */
+function twinOf(target, src, node, lexical, stale) {
+    if (node.file) {
+        return undefined;
+    }
+    const vector = src.vectors?.get(node.id);
+    const block = target.vectors;
+    if (vector && block && block.dims === vector.length && block.rows) {
+        const allow = (id) => {
+            const other = target.graph.get(id);
+            return !stale.has(id) && !!other && comparable(other, node);
+        };
+        const hit = block.topK(vector, 1, allow)[0];
+        return hit && hit.score >= DUPLICATE_SCORE ? hit.id : undefined;
+    }
+    const id = lexical.get(twinKey(node));
+    return id && !stale.has(id) ? id : undefined;
+}
+function comparable(a, b) {
+    return a.id !== b.id && a.kind === b.kind && !a.file && audienceKey(a) === audienceKey(b);
+}
+function twinKey(node) {
+    return [node.kind, audienceKey(node), flatten(node.text)].join('\u0000');
+}
+function audienceKey(node) {
+    return [...node.audience].sort().join('|');
+}
+function carryVector(from, to, id) {
+    const vector = from.vectors?.get(id);
+    const block = to.vectors;
+    if (vector && block && block.dims === vector.length) {
+        block.set(id, vector);
+    }
+}
+/**
+ * Use is not change: `touch` moves these and deliberately leaves `revision`
+ * alone, which is what lets two runs of the same memory reconcile instead of
+ * colliding. MAX and not sum, so merging a source twice changes nothing.
+ */
+function reconcile(keep, other) {
+    return {
+        ...keep,
+        // ISO-8601 in UTC is fixed width, so string order is time order.
+        createdAt: keep.createdAt <= other.createdAt ? keep.createdAt : other.createdAt,
+        lastUsedAt: keep.lastUsedAt >= other.lastUsedAt ? keep.lastUsedAt : other.lastUsedAt,
+        useCount: Math.max(keep.useCount, other.useCount),
+    };
+}
+function newer(a, b) {
+    return a.revision === b.revision ? a.updatedAt > b.updatedAt : a.revision > b.revision;
+}
+function sameContent(a, b) {
+    return (a.kind === b.kind &&
+        a.text === b.text &&
+        audienceKey(a) === audienceKey(b) &&
+        a.file?.sha256 === b.file?.sha256 &&
+        deep(a.metadata, b.metadata));
+}
+function deep(a, b) {
+    if (a === b) {
+        return true;
+    }
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) {
+        return false;
+    }
+    if (Array.isArray(a) !== Array.isArray(b)) {
+        return false;
+    }
+    const left = a;
+    const right = b;
+    const keys = Object.keys(left);
+    return keys.length === Object.keys(right).length && keys.every((k) => deep(left[k], right[k]));
+}
+/** Stat every file the merge would copy before it copies any of them. */
+async function checkFiles(plan) {
+    for (const planned of plan.values()) {
+        const file = planned.node.file;
+        if (!planned.from || !file) {
+            continue;
+        }
+        const source = hostPath(planned.from.dir, file);
+        const info = await stat(source).catch(() => undefined);
+        if (!info?.isFile()) {
+            throw new MemoryError(`${file.path} is missing from ${planned.from.dir}`, 'that memory is incomplete; re-run it, or forget the node that names the file');
+        }
+    }
+}
+/**
+ * Bytes last, and all or nothing: the digest is checked against the one the
+ * node records, and anything written before a failure is taken back, so a
+ * refused merge cannot leave files no graph mentions.
+ */
+async function copyFiles(target, plan, moved, reports) {
+    const written = [];
+    try {
+        for (const [id, planned] of plan) {
+            const file = planned.node.file;
+            if (!copies(id, planned, moved)) {
+                continue;
+            }
+            const source = hostPath(planned.from.dir, file);
+            const destination = hostPath(target.dir, file);
+            if (source === destination) {
+                continue;
+            }
+            const bytes = await readFile(source);
+            const sha = createHash('sha256').update(bytes).digest('hex');
+            if (sha !== file.sha256) {
+                throw new MemoryError(`${file.path} in ${planned.from.dir} does not match the digest its memory records`, 'that memory was modified outside zen; merge it after re-running it');
+            }
+            const existed = await stat(destination).then(() => true, () => false);
+            await writeFile(destination, bytes);
+            if (!existed) {
+                written.push(destination);
+            }
+            reports.get(planned.from).files++;
+        }
+    }
+    catch (err) {
+        await Promise.all(written.map((path) => rm(path, { force: true })));
+        throw err;
+    }
+}
+/** A file comes across when its node came from a source and survived the fold. */
+function copies(id, planned, moved) {
+    if (!planned.from || !planned.node.file) {
+        return false;
+    }
+    return !planned.fresh || moved.get(id) === id;
+}
+function total(report) {
+    for (const src of report.sources) {
+        report.added += src.added;
+        report.shared += src.shared;
+        report.twins += src.twins;
+        report.files += src.files;
+    }
+    return report;
+}
+function clip(text) {
+    const flat = flatten(text);
+    return flat.length > CLIP ? `${flat.slice(0, CLIP - 1)}…` : flat;
+}
+//# sourceMappingURL=merge.js.map

package/dist/memory/recall.d.ts

@@ -1,7 +1,7 @@
 import type { MemoryGraph } from './graph.ts';
 import { type MemoryQuery, type Recollection, type ScoredNode } from './types.ts';
 import { type VectorBlock } from './vectors.ts';
-export declare const DEFAULT_SEEDS = 5;
+export declare const DEFAULT_SEEDS = 10;
 export declare const DEFAULT_MAX_HOPS = 2;
 /** Past roughly this many nodes a rendered graph reads as soup, not structure. */
 export declare const DEFAULT_MAX_NODES = 25;

package/dist/memory/recall.js

@@ -17,7 +17,7 @@ import { overlap, recencyDecay, tokenize } from "./vectors.js";
 // it replaced from every recall, while the history stays on disk for anyone
 // asking how the correction came about.
 // ---------------------------------------------------------------------------
-export const DEFAULT_SEEDS = 5;
+export const DEFAULT_SEEDS = 10;
 export const DEFAULT_MAX_HOPS = 2;
 /** Past roughly this many nodes a rendered graph reads as soup, not structure. */
 export const DEFAULT_MAX_NODES = 25;

package/dist/memory/store.d.ts

@@ -19,16 +19,28 @@ export interface MemoryManifest {
     edges: number;
     updatedAt: string;
 }
+export interface Lock {
+    pid: number;
+    host: string;
+    startedAt: string;
+}
 export interface OpenOptions {
     /** the embedder the caller intends to use; a mismatch with the manifest is fatal */
     embedding?: MemoryEmbedding;
     /** take the directory lock; off for read-only inspection (`zen memory ls`) */
     lock?: boolean;
+    /**
+     * Recall, and nothing else. Writing is refused rather than dropped, the
+     * directory is never created, and no lock is taken — so any number of runs
+     * may share one graph at once, which is the whole point of it.
+     */
+    readOnly?: boolean;
 }
 export declare class MemoryStore {
     #private;
     readonly dir: string;
     readonly graph: MemoryGraph;
+    readonly readOnly: boolean;
     private constructor();
     static open(dir: string, opts?: OpenOptions): Promise<MemoryStore>;
     get embedding(): MemoryEmbedding | undefined;
@@ -46,4 +58,10 @@ export declare class MemoryStore {
     commit(): Promise<void>;
     release(): void;
 }
+/**
+ * Who is writing a memory right now, if anyone. Read-only on purpose: it never
+ * claims the lock and never clears a stale one, so it is safe to ask about a
+ * directory this process has no intention of opening for writing.
+ */
+export declare function lockHolder(dir: string): Lock | undefined;
 //# sourceMappingURL=store.d.ts.map

package/dist/memory/store.js

@@ -34,18 +34,29 @@ export const LOCK_FILE = '.lock';
 export class MemoryStore {
     dir;
     graph;
+    readOnly;
     #embedding;
     #vectors;
     #locked = false;
-    constructor(dir, graph, vectors, embedding) {
+    constructor(dir, graph, vectors, embedding, readOnly) {
         this.dir = dir;
         this.graph = graph;
         this.#vectors = vectors;
         this.#embedding = embedding;
+        this.readOnly = readOnly;
     }
     static async open(dir, opts = {}) {
-        await mkdir(join(dir, FILES_DIR), { recursive: true });
+        const readOnly = opts.readOnly === true;
+        if (!readOnly) {
+            await mkdir(join(dir, FILES_DIR), { recursive: true });
+        }
         const manifest = await readManifest(dir);
+        // Opening for writing brings a memory into existence; opening one to
+        // read from has to find it, or a mistyped path is an empty graph that
+        // answers every question with silence and reports no error.
+        if (readOnly && !manifest) {
+            throw new MemoryError(`${dir} is not a memory`, `no ${MANIFEST_FILE} in it, and a read-only open cannot create one`);
+        }
         if (manifest?.embedding && opts.embedding) {
             const a = manifest.embedding;
             const b = opts.embedding;
@@ -59,8 +70,10 @@ export class MemoryStore {
             : new MemoryGraph();
         const embedding = opts.embedding ?? manifest?.embedding;
         const vectors = manifest && embedding ? await readVectors(dir, embedding) : undefined;
-        const store = new MemoryStore(dir, graph, vectors, embedding);
-        if (opts.lock !== false) {
+        const store = new MemoryStore(dir, graph, vectors, embedding, readOnly);
+        // A reader that claimed the lock would only be refusing itself, and the
+        // readers of one graph are meant to be able to refuse each other least.
+        if (!readOnly && opts.lock !== false) {
             store.#claim();
         }
         return store;
@@ -97,6 +110,11 @@ export class MemoryStore {
     }
     /** Manifest last: a torn commit reads as no memory, never as a partial one. */
     async commit() {
+        // Loudly, not quietly. A write that is silently dropped is a run that
+        // believes it remembered something and did not.
+        if (this.readOnly) {
+            throw new MemoryError('this memory is open read-only', 'nothing this run learns can be kept — point it at a memory of its own');
+        }
         await atomic(join(this.dir, GRAPH_FILE), JSON.stringify(this.graph.export()));
         const vectors = this.#vectors;
         if (vectors) {
@@ -202,6 +220,15 @@ async function atomic(path, body) {
         throw err;
     }
 }
+/**
+ * Who is writing a memory right now, if anyone. Read-only on purpose: it never
+ * claims the lock and never clears a stale one, so it is safe to ask about a
+ * directory this process has no intention of opening for writing.
+ */
+export function lockHolder(dir) {
+    const held = readLock(join(dir, LOCK_FILE));
+    return held && held.host === hostname() && alive(held.pid) ? held : undefined;
+}
 function readLock(path) {
     try {
         return JSON.parse(readFileSync(path, 'utf8'));

package/dist/memory/tools.js

@@ -1,25 +1,30 @@
 /**
- * The four tools an agent gets. Deliberately four and not seven: `search` and
- * `load` are split because finding is not reading — search returns stitched
- * context the model never asked for, and counting that as use would poison
- * recency. `commit` is one transaction because a remembered thing is a
- * subgraph, and building it with three calls leaves the graph half-formed if
- * the model stops early. `forget` is separate because deleting rarely happens
- * in the same breath as creating, and a `forget` buried inside a truncated
- * commit preview would be both irreversible and invisible.
+ * The five tools an agent gets. `search` and `load` are split because finding
+ * is not reading — search returns stitched context the model never asked for,
+ * and counting that as use would poison recency. `grep` is separate from
+ * `search` because exactness is not a tuning of nearness: a ranking returns the
+ * top of a list, so it can say what is closest but never that nothing is there.
+ * `commit` is one transaction because a remembered thing is a subgraph, and
+ * building it with three calls leaves the graph half-formed if the model stops
+ * early. `forget` is separate because deleting rarely happens in the same
+ * breath as creating, and a `forget` buried inside a truncated commit preview
+ * would be both irreversible and invisible.
  *
  * `audience` reaches the schema only when the binding grants more than one
  * label, and `sees` never does: an agent that could name its own audience
  * could read another agent's slice just by asking for it.
  */
 import { hash } from "../payload.js";
-import { MEMORY_COMMIT_TOOL, MEMORY_FORGET_TOOL, MEMORY_LOAD_TOOL, MEMORY_SEARCH_TOOL, tool, withEffects, } from "../types.js";
+import { MEMORY_COMMIT_TOOL, MEMORY_FORGET_TOOL, MEMORY_GREP_TOOL, MEMORY_LOAD_TOOL, MEMORY_SEARCH_TOOL, tool, withEffects, } from "../types.js";
+import { GREP_FIELDS, grepMemory } from "./grep.js";
 import { renderRecollection } from "./render.js";
 import { canForget, canWrite, KIND_HELP, MemoryError, RELATION_HELP, } from "./types.js";
 /** Deterministic, so a replayed call is the same op and not a second one. */
 export function memoryOpId(runId, callId) {
     return hash(`${runId}\u0000${callId}`);
 }
+/** Enough nodes to settle a question, few enough not to be a context dump. */
+const GREPPED = 20;
 export function memoryTools(opts) {
     const { index, binding } = opts;
     const kinds = [...index.kinds];
@@ -131,6 +136,97 @@ export function memoryTools(opts) {
                 })), { kind: 'memory_op', spec });
             },
         }),
+        tool({
+            name: MEMORY_GREP_TOOL,
+            description: 'Find an exact string in memory, the way grep does: every node whose text, ' +
+                'metadata or remembered file contains it, with the matching lines. Use this ' +
+                `instead of ${MEMORY_SEARCH_TOOL} when the answer has to be complete rather ` +
+                'than close — whether something was already recorded, or where a name, path, ' +
+                'id or command appears. This is the only correct way to search the memory ' +
+                'directly; never run a shell grep over /memory. Read a whole node with ' +
+                `${MEMORY_LOAD_TOOL}.`,
+            parameters: {
+                type: 'object',
+                properties: {
+                    pattern: {
+                        type: 'string',
+                        description: 'the exact text to look for; matched case-insensitively',
+                    },
+                    regex: {
+                        type: 'boolean',
+                        description: 'read the pattern as a regular expression, matched per line',
+                    },
+                    case_sensitive: { type: 'boolean', description: 'match case exactly' },
+                    kinds: {
+                        type: 'array',
+                        items: { type: 'string', enum: kinds },
+                        description: 'restrict to these kinds',
+                    },
+                    in: {
+                        type: 'array',
+                        items: { type: 'string', enum: [...GREP_FIELDS] },
+                        description: 'which parts to look in; all of them by default',
+                    },
+                    include_superseded: {
+                        type: 'boolean',
+                        description: 'also search nodes that have been corrected by a newer one; they come back marked stale',
+                    },
+                    limit: { type: 'integer', description: `nodes to return; default ${GREPPED}` },
+                },
+                required: ['pattern'],
+                additionalProperties: false,
+            },
+            execute: async (args, tc) => {
+                const opId = memoryOpId(tc.state.runId, tc.callId);
+                let res;
+                try {
+                    res = await grepMemory(index.store, args.pattern, {
+                        sees: binding.sees,
+                        regex: args.regex,
+                        caseSensitive: args.case_sensitive,
+                        kinds: args.kinds,
+                        in: args.in,
+                        stale: args.include_superseded ? 'include' : 'exclude',
+                        limit: args.limit ?? GREPPED,
+                    });
+                }
+                catch (err) {
+                    return refusal(err);
+                }
+                // A complete answer, so nothing found is information rather than
+                // a failed lookup — that is the whole reason this tool exists.
+                if (!res.found && !res.skipped.length) {
+                    return `nothing in memory contains ${JSON.stringify(args.pattern)}`;
+                }
+                const spec = {
+                    kind: 'op',
+                    op: 'grep',
+                    opId,
+                    nodes: res.matches.map((m) => ({
+                        id: m.node.id,
+                        kind: m.node.kind,
+                        revision: m.node.revision,
+                    })),
+                    edges: [],
+                    files: 0,
+                };
+                return withEffects({
+                    found: res.found,
+                    truncated: res.truncated || undefined,
+                    matches: res.matches.map((m) => ({
+                        id: m.node.id,
+                        kind: m.node.kind,
+                        stale: m.stale || undefined,
+                        file: m.node.file?.path,
+                        hits: m.hits.map((h) => ({ in: h.where, line: h.line, text: h.text })),
+                        more: m.more || undefined,
+                    })),
+                    // Named, because a file that was not read means a hit in
+                    // it would not have been reported either.
+                    unsearched: res.skipped.length ? res.skipped : undefined,
+                }, { kind: 'memory_op', spec });
+            },
+        }),
     ];
     if (!canWrite(binding)) {
         return tools;

package/dist/memory/types.d.ts

@@ -169,8 +169,13 @@ export interface MemoryRecallSpec {
 }
 export interface MemoryOpSpec {
     kind: 'op';
-    /** `load` is here rather than under recall: it hands the model whole bodies, and it writes. */
-    op: 'commit' | 'forget' | 'load';
+    /**
+     * `load` is here rather than under recall: it hands the model whole bodies,
+     * and it writes. `grep` is here because it is not a recall either — there is
+     * no query vector, no subgraph and no ranking to record, only the nodes a
+     * pattern happened to hit.
+     */
+    op: 'commit' | 'forget' | 'load' | 'grep';
     /** sha256(runId, callId) — deterministic, so a replay is deduplicated */
     opId: string;
     /** nodes this op created, changed, removed or read in full */

package/dist/memory/vectors.d.ts

@@ -9,6 +9,8 @@ export declare class VectorBlock {
     get rows(): number;
     get ids(): readonly string[];
     has(id: string): boolean;
+    /** A copy, not a view: the row it came from moves the next time something is deleted. */
+    get(id: string): Float32Array | undefined;
     set(id: string, vector: ArrayLike<number>): void;
     remove(id: string): boolean;
     /** Exact kNN over the rows `allow` accepts. Ties break toward the earlier row. */