@zenera/neo 1.1.11 → 1.1.14

package/dist/memory/recall.d.ts

@@ -0,0 +1,35 @@
+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_MAX_HOPS = 2;
+/** Past roughly this many nodes a rendered graph reads as soup, not structure. */
+export declare const DEFAULT_MAX_NODES = 25;
+/** Below this, a "match" is noise that costs context and buys nothing. */
+export declare const DEFAULT_MIN_SCORE = 0.15;
+export interface RecallInput {
+    graph: MemoryGraph;
+    query: MemoryQuery;
+    sees: readonly string[];
+    /** the embedded query; absent ranks by term overlap instead */
+    vector?: ArrayLike<number>;
+    vectors?: VectorBlock;
+    now?: number;
+    /** include what has been superseded; off by default, on for an audit */
+    stale?: boolean;
+}
+export declare function recall(input: RecallInput): Recollection;
+/**
+ * Decay orders, it does not admit. Relevance alone clears `minScore`, and
+ * recency only breaks the tie afterwards — folding decay in before the
+ * threshold would make every memory unreachable once it was old enough,
+ * however exactly it matched, which is the opposite of outliving a run.
+ */
+export declare function rank(input: RecallInput): ScoredNode[];
+/**
+ * Breadth-first from every seed at once, so a node two hops from one seed loses
+ * to a node one hop from another. Direction is ignored on the walk: a memory is
+ * as often reached from the artifact back to the request as the other way.
+ */
+export declare function stitch(graph: MemoryGraph, seeds: readonly ScoredNode[], query: MemoryQuery, sees: readonly string[], stale?: boolean): Recollection;
+//# sourceMappingURL=recall.d.ts.map

package/dist/memory/recall.js

@@ -0,0 +1,161 @@
+import { PREFERENCE_KIND, SPINE_RELATIONS, visible, } from "./types.js";
+import { overlap, recencyDecay, tokenize } from "./vectors.js";
+// ---------------------------------------------------------------------------
+// From a question to a subgraph
+//
+// A ranked list of node ids is not an answer. A remembered script is worth
+// having only alongside the request that asked for it and the endpoint it
+// calls, and two hits are one memory only if the graph joins them. So ranking
+// picks seeds and traversal decides what has to come with them.
+//
+// The budget is spent in tiers. Seeds first, then the spine — what a task
+// produced, what an artifact calls, what replaced it — and only then the
+// context that merely informed the work. A tight budget therefore degrades by
+// dropping background rather than by truncating the answer itself.
+//
+// Superseded nodes are dropped, not deleted. A corrected script hides the one
+// 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_MAX_HOPS = 2;
+/** Past roughly this many nodes a rendered graph reads as soup, not structure. */
+export const DEFAULT_MAX_NODES = 25;
+/** Below this, a "match" is noise that costs context and buys nothing. */
+export const DEFAULT_MIN_SCORE = 0.15;
+const SEED = 0;
+const LINK = 1;
+const FILL = 2;
+export function recall(input) {
+    const seeds = rank(input);
+    return stitch(input.graph, seeds, input.query, input.sees, input.stale ?? false);
+}
+/**
+ * Decay orders, it does not admit. Relevance alone clears `minScore`, and
+ * recency only breaks the tie afterwards — folding decay in before the
+ * threshold would make every memory unreachable once it was old enough,
+ * however exactly it matched, which is the opposite of outliving a run.
+ */
+export function rank(input) {
+    const { graph, query, sees } = input;
+    const now = input.now ?? Date.now();
+    const limit = query.limit ?? DEFAULT_SEEDS;
+    const minScore = query.minScore ?? DEFAULT_MIN_SCORE;
+    const stale = input.stale ? new Set() : graph.superseded(sees);
+    const admissible = (n) => eligible(n, query, sees) && !stale.has(n.id);
+    let scored;
+    if (input.vector && input.vectors) {
+        const hits = input.vectors.topK(input.vector, limit * 4, (id) => {
+            const node = graph.get(id);
+            return !!node && admissible(node);
+        });
+        scored = hits.flatMap((h) => {
+            const node = graph.get(h.id);
+            return node ? [{ node, score: h.score }] : [];
+        });
+    }
+    else {
+        const terms = tokenize(query.text ?? '');
+        scored = graph.nodes(sees).flatMap((node) => {
+            if (!admissible(node)) {
+                return [];
+            }
+            const score = terms.length ? overlap(terms, tokenize(node.text)) : 1;
+            return score > 0 ? [{ node, score }] : [];
+        });
+    }
+    // `score` stays the similarity the caller can reason about; the decayed
+    // value exists only to order, and is not reported.
+    return scored
+        .filter((s) => s.score >= minScore)
+        .map((s) => ({ ...s, rung: s.score * recencyDecay(s.node.lastUsedAt, now) }))
+        .sort((a, b) => b.rung - a.rung)
+        .slice(0, limit)
+        .map((s) => ({ node: s.node, score: s.score, seed: true }));
+}
+function eligible(node, query, sees) {
+    if (!visible(node, sees)) {
+        return false;
+    }
+    if (query.kinds?.length && !query.kinds.includes(node.kind)) {
+        return false;
+    }
+    // A preference is in the system prompt already. Recalling one would state
+    // the same standing instruction twice in two framings; asking for the kind
+    // by name still finds it, which is how an agent checks for a duplicate
+    // before committing another.
+    if (!query.kinds?.length && node.kind === PREFERENCE_KIND) {
+        return false;
+    }
+    if (query.newerThan && node.createdAt < query.newerThan) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Breadth-first from every seed at once, so a node two hops from one seed loses
+ * to a node one hop from another. Direction is ignored on the walk: a memory is
+ * as often reached from the artifact back to the request as the other way.
+ */
+export function stitch(graph, seeds, query, sees, stale = false) {
+    const maxHops = query.maxHops ?? DEFAULT_MAX_HOPS;
+    const maxNodes = query.maxNodes ?? DEFAULT_MAX_NODES;
+    const superseded = stale ? new Set() : graph.superseded(sees);
+    const tier = new Map();
+    const scores = new Map();
+    // What admitted each node, which is the branch the renderer hangs it from.
+    // A seed never gets one: its tier is 0 and no edge can better that.
+    const via = new Map();
+    for (const seed of seeds) {
+        tier.set(seed.node.id, SEED);
+        scores.set(seed.node.id, seed.score);
+    }
+    let frontier = seeds.map((s) => s.node.id);
+    for (let hop = 0; hop < maxHops && frontier.length; hop++) {
+        const next = [];
+        for (const id of frontier) {
+            for (const edge of graph.neighbors(id, sees)) {
+                const other = edge.source === id ? edge.target : edge.source;
+                if (superseded.has(other)) {
+                    continue;
+                }
+                const rung = SPINE_RELATIONS.has(edge.relation) ? LINK : FILL;
+                const known = tier.get(other);
+                if (known !== undefined && known <= rung) {
+                    continue;
+                }
+                if (known === undefined) {
+                    next.push(other);
+                }
+                tier.set(other, rung);
+                via.set(other, { from: id, relation: edge.relation, outbound: edge.source === id });
+            }
+        }
+        frontier = next;
+    }
+    // Seeds, then the spine, then context — and inside a tier, by seed score.
+    const ranked = [...tier.entries()]
+        .flatMap(([id, rung]) => {
+        const node = graph.get(id);
+        return node ? [{ node, rung, score: scores.get(id) ?? 0 }] : [];
+    })
+        .sort((a, b) => a.rung - b.rung || b.score - a.score);
+    const kept = ranked.slice(0, maxNodes);
+    const ids = new Set(kept.map((k) => k.node.id));
+    const edges = graph.between(ids, sees);
+    return {
+        nodes: kept.map((k) => {
+            const branch = via.get(k.node.id);
+            return {
+                node: k.node,
+                score: k.score,
+                seed: k.rung === SEED,
+                ...(branch ? { via: branch } : {}),
+            };
+        }),
+        edges,
+        seeds: seeds.map((s) => s.node.id),
+        truncated: ranked.length > kept.length,
+    };
+}
+//# sourceMappingURL=recall.js.map

package/dist/memory/render.d.ts

@@ -0,0 +1,10 @@
+import { type Recollection } from './types.ts';
+export declare const RECOLLECTION_TAG = "memory-recollection";
+export interface RenderOptions {
+    /** wrap in the <memory-recollection> element; off for CLI output */
+    tagged?: boolean;
+    clip?: number;
+    now?: number;
+}
+export declare function renderRecollection(rec: Recollection, opts?: RenderOptions): string;
+//# sourceMappingURL=render.d.ts.map

package/dist/memory/render.js

@@ -0,0 +1,228 @@
+import { SPINE_RELATIONS, } from "./types.js";
+// ---------------------------------------------------------------------------
+// What the model actually reads
+//
+// An outline, because the block has exactly one audience: `memory_search` and
+// auto-recall both hand it straight to a model, and nothing human or machine
+// consumes it — the HTML export draws its own diagram from the graph.
+//
+// It replaced a mermaid graph over a legend, which carried the same subgraph
+// twice: topology above, text below, joined only by the id. Answering "what
+// does this script call" meant carrying a 26-character id from one half into
+// the other, and the halves were sorted differently, so the answer sat as far
+// from the question as the sort could put it. An outline states each id once,
+// with its text under it and its neighbours around it.
+//
+// The tree is mostly the walk: `stitch` records the edge that admitted each
+// node, so nesting is how recall got there. Seeds are the exception — nothing
+// admitted them — and left as roots they turned a well-matched subgraph into a
+// flat list, so each adopts its best-connected higher-ranked neighbour instead.
+// Whatever edges that leaves over become back-references, always drawn under
+// the endpoint that appeared later, so a `+` line never points forward.
+//
+// No SUPERSEDES arrow can appear on the ordinary path: recall drops the node
+// one points at, so the edge loses an endpoint before it reaches here. It shows
+// up only under `stale`, which is the audit view, and `memory/instructions.ts`
+// therefore does not teach the model to look for one.
+// ---------------------------------------------------------------------------
+export const RECOLLECTION_TAG = 'memory-recollection';
+/** Enough to judge relevance; the model calls `memory_load` for the rest. */
+const TEXT_CLIP = 160;
+/** Two columns per level of nesting, so the tree is the indentation. */
+const STEP = 2;
+/** Where text sits under its header; a deeper walk pushes it right, never over it. */
+const TEXT_COLUMN = 6;
+export function renderRecollection(rec, opts = {}) {
+    if (!rec.nodes.length) {
+        return '';
+    }
+    const lines = [];
+    for (const [i, entry] of layout(rec).entries()) {
+        if (i && entry.depth === 0) {
+            lines.push('');
+        }
+        lines.push(...block(entry, opts));
+    }
+    if (rec.truncated) {
+        lines.push('', '(more memory matched than fits; narrow the query or raise max_nodes)');
+    }
+    const text = lines.join('\n');
+    return opts.tagged === false ? text : `<${RECOLLECTION_TAG}>\n${text}\n</${RECOLLECTION_TAG}>`;
+}
+/**
+ * Depth-first along the branches the walk took, roots in seed order. A node
+ * whose parent the budget cut is promoted to a root rather than dropped: it
+ * survived the ranking, so it belongs in the answer.
+ */
+function layout(rec) {
+    const at = new Map(rec.nodes.map((s, i) => [s.node.id, i]));
+    const parents = branches(rec, at);
+    const children = new Map();
+    const roots = [];
+    for (const scored of rec.nodes) {
+        const parent = parents.get(scored.node.id)?.from;
+        if (parent !== undefined) {
+            children.set(parent, [...(children.get(parent) ?? []), scored]);
+        }
+        else {
+            roots.push(scored);
+        }
+    }
+    const rank = new Map(rec.seeds.map((id, i) => [id, i]));
+    const place = (id) => rank.get(id) ?? Number.MAX_SAFE_INTEGER;
+    roots.sort((a, b) => place(a.node.id) - place(b.node.id));
+    const order = [];
+    const walk = (scored, depth) => {
+        order.push({ scored, depth, via: parents.get(scored.node.id), refs: [] });
+        for (const child of children.get(scored.node.id) ?? []) {
+            walk(child, depth + 1);
+        }
+    };
+    for (const root of roots) {
+        walk(root, 0);
+    }
+    // Everything the nesting has not already said, hung off whichever endpoint
+    // came out later — so resolving one only ever means looking back up.
+    const nested = new Set([...parents].map(([id, via]) => {
+        const [source, target] = via.outbound ? [via.from, id] : [id, via.from];
+        return edgeKey(source, target, via.relation);
+    }));
+    const position = new Map(order.map((entry, i) => [entry.scored.node.id, i]));
+    for (const edge of rec.edges) {
+        if (nested.has(edgeKey(edge.source, edge.target, edge.relation))) {
+            continue;
+        }
+        const source = position.get(edge.source);
+        const target = position.get(edge.target);
+        if (source !== undefined && target !== undefined) {
+            order[Math.max(source, target)]?.refs.push(edge);
+        }
+    }
+    return order;
+}
+/**
+ * Which branch each node hangs from. `stitch` records one for anything it had
+ * to walk to, but never for a seed — nothing reached a seed, it was the reason
+ * for the walk. Two seeds joined by an edge would then both sit at the left
+ * margin with the link between them demoted to a `+`, so the better a query
+ * matched the flatter it drew, which is backwards.
+ *
+ * So a node with no branch of its own adopts one, preferring the spine and then
+ * the best-ranked neighbour. Only a neighbour that ranked *higher* may be
+ * adopted, which is what makes this a forest: every parent is strictly earlier
+ * in one total order, so no chain of them can close into a cycle.
+ */
+function branches(rec, at) {
+    const parents = new Map();
+    const touching = new Map();
+    for (const scored of rec.nodes) {
+        const via = scored.via;
+        const from = via ? at.get(via.from) : undefined;
+        // Strictly earlier, on the same total order the adoption below uses:
+        // one rule for both is what keeps `walk` from ever meeting a cycle.
+        if (via && from !== undefined && from < at.get(scored.node.id)) {
+            parents.set(scored.node.id, via);
+        }
+    }
+    for (const edge of rec.edges) {
+        if (!at.has(edge.source) || !at.has(edge.target)) {
+            continue;
+        }
+        touching.set(edge.source, [...(touching.get(edge.source) ?? []), edge]);
+        touching.set(edge.target, [...(touching.get(edge.target) ?? []), edge]);
+    }
+    for (const scored of rec.nodes) {
+        const id = scored.node.id;
+        if (parents.has(id)) {
+            continue;
+        }
+        const mine = at.get(id);
+        let best;
+        for (const edge of touching.get(id) ?? []) {
+            const from = edge.source === id ? edge.target : edge.source;
+            const there = at.get(from);
+            if (there >= mine) {
+                continue;
+            }
+            const spine = SPINE_RELATIONS.has(edge.relation);
+            if (best && !(spine && !best.spine) && !(spine === best.spine && there < best.at)) {
+                continue;
+            }
+            best = {
+                spine,
+                at: there,
+                via: { from, relation: edge.relation, outbound: edge.source === from },
+            };
+        }
+        if (best) {
+            parents.set(id, best.via);
+        }
+    }
+    return parents;
+}
+function edgeKey(source, target, relation) {
+    return `${source}|${relation}|${target}`;
+}
+function block(entry, opts) {
+    const { node } = entry.scored;
+    const now = opts.now ?? Date.now();
+    const indent = ' '.repeat(Math.max(TEXT_COLUMN, (entry.depth + 2) * STEP));
+    const lines = [`${' '.repeat(entry.depth * STEP)}${header(entry)}`];
+    if (node.file) {
+        const facts = [node.file.path, bytes(node.file.bytes), used(node, now)];
+        lines.push(`${indent}${facts.join(' · ')}`);
+    }
+    const summary = clipped(node.text, opts.clip ?? TEXT_CLIP);
+    if (summary) {
+        lines.push(`${indent}${summary}`);
+    }
+    for (const ref of entry.refs) {
+        const outbound = ref.source === node.id;
+        const other = outbound ? ref.target : ref.source;
+        lines.push(`${indent}+ ${step(outbound, ref.relation)}  ${other}`);
+    }
+    return lines;
+}
+/**
+ * A root leads with its score, a child with the edge that reached it. A child
+ * that the ranker also matched leads with both: the arrow says how the outline
+ * got here, the score says it would have been worth reading regardless.
+ */
+function header(entry) {
+    const { node, seed, score } = entry.scored;
+    const via = entry.via;
+    const tail = `${label(node.kind)}  ${node.id}`;
+    if (!via || entry.depth === 0) {
+        return `${seed ? score.toFixed(2) : '  --'}  ${tail}`;
+    }
+    const reached = step(via.outbound, via.relation);
+    return seed ? `${reached}  ${score.toFixed(2)}  ${tail}` : `${reached}  ${tail}`;
+}
+/** `→` when the line above is the edge's source, `←` when it is the target. */
+function step(outbound, relation) {
+    return `${outbound ? '\u2192' : '\u2190'}${relation.toLowerCase()}`;
+}
+/** Kinds are a closed vocabulary, but a project may add its own — so still guard. */
+function label(kind) {
+    return kind.replace(/[^A-Za-z0-9_ -]/g, '') || 'node';
+}
+function clipped(text, clip) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    return flat.length > clip ? `${flat.slice(0, clip - 1)}…` : flat;
+}
+function bytes(n) {
+    return n < 1024
+        ? `${n} B`
+        : n < 1024 * 1024
+            ? `${(n / 1024).toFixed(1)} KB`
+            : `${(n / 1024 / 1024).toFixed(1)} MB`;
+}
+function used(node, now) {
+    if (!node.useCount) {
+        return 'unused';
+    }
+    const days = Math.floor((now - Date.parse(node.lastUsedAt)) / 86_400_000);
+    const ago = days <= 0 ? 'today' : days === 1 ? 'yesterday' : `${days}d ago`;
+    return `used ${node.useCount}\u00d7, ${ago}`;
+}
+//# sourceMappingURL=render.js.map

package/dist/memory/report.d.ts

@@ -0,0 +1,69 @@
+import type { MemoryStore } from './store.ts';
+import type { MemoryEdge, MemoryFile } from './types.ts';
+/** Beyond this a file is named and measured, not shown. */
+export declare const MAX_CONTENT_BYTES: number;
+/** Why a remembered file is not shown. */
+export type Omitted = 'too-big' | 'binary' | 'missing' | 'unreadable';
+export interface ReportNode {
+    id: string;
+    kind: string;
+    text: string;
+    audience: string[];
+    createdAt: string;
+    updatedAt: string;
+    lastUsedAt: string;
+    useCount: number;
+    revision: number;
+    metadata?: Record<string, unknown>;
+    file?: MemoryFile;
+    /** the file's text, when it is text and small enough to show */
+    content?: string;
+    /** an image file, as a data URL */
+    image?: string;
+    omitted?: Omitted;
+    /** superseded by a newer node; still here, because why it changed matters */
+    stale: boolean;
+    /** edges touching this node, in either direction */
+    degree: number;
+}
+export interface MemoryReport {
+    title: string;
+    dir: string;
+    generatedAt: string;
+    embedding?: {
+        model: string;
+        dimensions: number;
+    };
+    vectors?: {
+        rows: number;
+        dims: number;
+        bytes: number;
+    };
+    nodes: ReportNode[];
+    edges: MemoryEdge[];
+    /** every kind present, for the filter */
+    kinds: string[];
+    /** every audience present, for the filter */
+    audiences: string[];
+}
+export interface MemoryReportOptions {
+    title?: string;
+    /** ceiling on inlined file content; 0 to inline nothing */
+    maxContentBytes?: number;
+    /** override the clock, for tests */
+    now?: () => string;
+}
+/** Part of a memory, for a caller that already knows which part it wants. */
+export interface MemorySlice {
+    nodes: ReportNode[];
+    /** only the edges with both ends inside the slice */
+    edges: MemoryEdge[];
+}
+/**
+ * The nodes named, built exactly as the whole graph is — same inlining, same
+ * excuses, same degree, which is counted over every edge rather than over the
+ * slice: a node's degree is a fact about the memory, not about the cut.
+ */
+export declare function buildMemorySlice(store: MemoryStore, ids: readonly string[], opts?: Pick<MemoryReportOptions, 'maxContentBytes'>): Promise<MemorySlice>;
+export declare function buildMemoryReport(store: MemoryStore, opts?: MemoryReportOptions): Promise<MemoryReport>;
+//# sourceMappingURL=report.d.ts.map

package/dist/memory/report.js

@@ -0,0 +1,131 @@
+import { readFile, stat } from 'node:fs/promises';
+import { hostPath } from "./files.js";
+// ---------------------------------------------------------------------------
+// The memory, flattened for reading
+//
+// This is the debugging view, and it is deliberately the *whole* graph: no
+// mask, no ranking, no recall. Everything a mask would hide is exactly what
+// you are looking for when a mask is the thing that is wrong, so audiences
+// arrive as data to filter by rather than as a filter already applied.
+//
+// The one thing it does not do is grow without bound. A remembered file can be
+// two megabytes and there can be a lot of them, so content is inlined up to a
+// ceiling and replaced by a reason past it — a page that fails to open tells
+// you nothing about the memory it was supposed to show.
+// ---------------------------------------------------------------------------
+/** Beyond this a file is named and measured, not shown. */
+export const MAX_CONTENT_BYTES = 256 * 1024;
+/** Rendered inline as a data URL; anything else is offered as a path. */
+const IMAGE_FORMATS = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg']);
+const MIME = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    svg: 'image/svg+xml',
+};
+/**
+ * The nodes named, built exactly as the whole graph is — same inlining, same
+ * excuses, same degree, which is counted over every edge rather than over the
+ * slice: a node's degree is a fact about the memory, not about the cut.
+ */
+export async function buildMemorySlice(store, ids, opts = {}) {
+    const graph = store.graph;
+    const all = graph.edges();
+    const wanted = new Set(ids);
+    return {
+        nodes: await inline(store, graph.nodes().filter((n) => wanted.has(n.id)), degrees(all), graph.superseded(), opts.maxContentBytes ?? MAX_CONTENT_BYTES),
+        edges: all.filter((e) => wanted.has(e.source) && wanted.has(e.target)),
+    };
+}
+export async function buildMemoryReport(store, opts = {}) {
+    const graph = store.graph;
+    const nodes = graph.nodes();
+    const edges = graph.edges();
+    const limit = opts.maxContentBytes ?? MAX_CONTENT_BYTES;
+    const built = await inline(store, nodes, degrees(edges), graph.superseded(), limit);
+    const vectors = store.vectors;
+    return {
+        title: opts.title ?? 'Memory',
+        dir: store.dir,
+        generatedAt: (opts.now ?? (() => new Date().toISOString()))(),
+        embedding: store.embedding,
+        vectors: vectors
+            ? { rows: vectors.rows, dims: vectors.dims, bytes: vectors.rows * vectors.dims * 4 }
+            : undefined,
+        nodes: built,
+        edges,
+        kinds: [...new Set(nodes.map((n) => n.kind))].sort(),
+        audiences: [...new Set(nodes.flatMap((n) => n.audience))].sort(),
+    };
+}
+function degrees(edges) {
+    const degree = new Map();
+    for (const e of edges) {
+        degree.set(e.source, (degree.get(e.source) ?? 0) + 1);
+        degree.set(e.target, (degree.get(e.target) ?? 0) + 1);
+    }
+    return degree;
+}
+/** Files are read in parallel: one memory can hold hundreds, independently. */
+async function inline(store, nodes, degree, stale, limit) {
+    return Promise.all(nodes.map(async (n) => ({
+        ...plain(n),
+        stale: stale.has(n.id),
+        degree: degree.get(n.id) ?? 0,
+        ...(n.file ? await body(store.dir, n.file, limit) : {}),
+    })));
+}
+/** The node's own fields, without the graph attributes graphology adds. */
+function plain(n) {
+    return {
+        id: n.id,
+        kind: n.kind,
+        text: n.text,
+        audience: [...n.audience],
+        createdAt: n.createdAt,
+        updatedAt: n.updatedAt,
+        lastUsedAt: n.lastUsedAt,
+        useCount: n.useCount,
+        revision: n.revision,
+        metadata: n.metadata,
+        file: n.file,
+    };
+}
+/**
+ * A remembered file, as much of it as is worth carrying. The recorded size is
+ * not trusted for the decision — the bytes on disk are what the page would
+ * have to hold — and a file that has gone missing says so rather than making
+ * the node look contentless.
+ */
+async function body(dir, file, limit) {
+    const path = hostPath(dir, file);
+    let size;
+    try {
+        size = (await stat(path)).size;
+    }
+    catch {
+        return { omitted: 'missing' };
+    }
+    if (size > limit) {
+        return { omitted: 'too-big' };
+    }
+    let buf;
+    try {
+        buf = await readFile(path);
+    }
+    catch {
+        return { omitted: 'unreadable' };
+    }
+    if (IMAGE_FORMATS.has(file.format)) {
+        return { image: `data:${MIME[file.format]};base64,${buf.toString('base64')}` };
+    }
+    // A NUL byte in the first few KiB is the cheap, boring test for "this is
+    // not text", and it is right about every format anyone remembers on purpose.
+    if (buf.subarray(0, 8192).includes(0)) {
+        return { omitted: 'binary' };
+    }
+    return { content: buf.toString('utf8') };
+}
+//# sourceMappingURL=report.js.map

package/dist/memory/store.d.ts

@@ -0,0 +1,49 @@
+import { MemoryGraph } from './graph.ts';
+import { VectorBlock } from './vectors.ts';
+export declare const MEMORY_VERSION = 1;
+export declare const GRAPH_FILE = "graph.json";
+export declare const VECTORS_FILE = "vectors.f32";
+export declare const VECTOR_IDS_FILE = "vectors.json";
+export declare const MANIFEST_FILE = "manifest.json";
+export declare const FILES_DIR = "files";
+export declare const LOCK_FILE = ".lock";
+export interface MemoryEmbedding {
+    model: string;
+    dimensions: number;
+}
+export interface MemoryManifest {
+    version: number;
+    /** absent when the project configured no embedder and ranks lexically */
+    embedding?: MemoryEmbedding;
+    nodes: number;
+    edges: number;
+    updatedAt: 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;
+}
+export declare class MemoryStore {
+    #private;
+    readonly dir: string;
+    readonly graph: MemoryGraph;
+    private constructor();
+    static open(dir: string, opts?: OpenOptions): Promise<MemoryStore>;
+    get embedding(): MemoryEmbedding | undefined;
+    /**
+     * Records the vectoriser actually in use. A width is only knowable from a
+     * real response, so a memory embedded for the first time learns it here
+     * rather than making the caller declare a number it would have to keep in
+     * step with the model.
+     */
+    adopt(embedding: MemoryEmbedding): void;
+    /** Absent when no embedder is configured; recall then falls back to term overlap. */
+    get vectors(): VectorBlock | undefined;
+    filePath(name: string): string;
+    /** Manifest last: a torn commit reads as no memory, never as a partial one. */
+    commit(): Promise<void>;
+    release(): void;
+}
+//# sourceMappingURL=store.d.ts.map