@zenera/neo 1.1.11 → 1.1.14

package/dist/inspect/css.js

@@ -87,6 +87,55 @@ table.st tfoot td:first-child { color: var(--dim); text-transform: uppercase;
 .gtools button:hover { border-color: var(--accent); }
 .gtools .hint:first-of-type { margin-left: 8px; }
 .gtools .lvl { margin-left: auto; font-family: var(--mono); }
+.gtools label.check { display: flex; align-items: center; gap: 5px; margin-left: 8px;
+  color: var(--dim); font-size: 12px; cursor: pointer; user-select: none; }
+/* The memory view reads left to right: the graph is the index, the panel is
+   the page. Putting the body under a tab of its own would mean losing the
+   picture every time you asked what a node actually says. */
+#memory .split { display: flex; flex: 1; overflow: hidden; }
+#mdetail { width: 380px; flex: none; padding: 16px; overflow: auto;
+  border-right: none; border-left: 1px solid var(--line); }
+#mdetail .dt { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; margin: 0 0 10px; }
+#mdetail .idrow { display: flex; gap: 8px; align-items: center; margin: 0 0 14px; }
+#mdetail .idrow code { flex: 1; min-width: 0; font: 12px var(--mono); color: var(--fg);
+  background: var(--bg); border: 1px solid var(--line); border-radius: 6px;
+  padding: 4px 8px; word-break: break-all; }
+#mdetail .idrow button { flex: 0 0 auto; background: var(--bg); border: 1px solid var(--line);
+  color: var(--dim); border-radius: 6px; padding: 4px 9px; font: 11px var(--mono);
+  cursor: pointer; }
+#mdetail .idrow button:hover { border-color: var(--accent); color: var(--fg); }
+#mdetail dl.props { display: grid; grid-template-columns: auto minmax(0, 1fr); gap: 5px 14px;
+  margin: 0 0 14px; font: 12px var(--mono); }
+#mdetail dl.props dt { color: var(--dim); }
+#mdetail dl.props dd { margin: 0; word-break: break-word; }
+/* A block that shares the panel's own background has no edges to show. */
+#mdetail section.blk { background: var(--bg); }
+#mdetail ul.links { list-style: none; margin: 0; padding: 0; }
+#mdetail ul.links li { display: grid; grid-template-columns: 96px auto minmax(0, 1fr);
+  gap: 8px; align-items: baseline; padding: 6px 12px; }
+#mdetail ul.links li + li { border-top: 1px solid var(--line); }
+#mdetail ul.links .rel { font: 11px var(--mono); color: var(--warn); white-space: nowrap; }
+#mdetail button.link { font: 12px/1.4 system-ui, sans-serif; padding: 0; text-align: left;
+  overflow-wrap: anywhere; }
+#mdetail button.link:hover { text-decoration: underline; }
+#mcount .ok { color: var(--ok); }
+#mcount .bad { color: var(--err); }
+/* The kind palette is the memory page's, so a node reads the same in both. */
+.kind { font-size: 11px; letter-spacing: .04em; text-transform: uppercase;
+  padding: 1px 6px; border-radius: 4px; background: #232a38; color: var(--dim); }
+.kind.task { background: #1e3357; color: #9dc1ff; }
+.kind.plan { background: #3a2450; color: #d1a6ff; }
+.kind.fact { background: #14392c; color: #8ee0c2; }
+.kind.snippet { background: #1e3d33; color: #8ee0c2; }
+.kind.file { background: #40331a; color: #f0dfb4; }
+.kind.operation { background: #3d2a1b; color: #f2d9c2; }
+.kind.preference { background: #3d1f2c; color: #f5b8cd; }
+/* Selection is a class rather than attributes written onto the shapes: the
+   previous pick has to lose its outline without a redraw. White, because the
+   accent already means "the recall matched this one". */
+#memory .node.picked rect, #memory .node.picked polygon,
+#memory .node.picked path, #memory .node.picked circle {
+  stroke: var(--fg) !important; stroke-width: 4px !important; }
 /* The canvas is transformed, not scrolled: panning has to work past the edges
    of the diagram, which overflow:auto would forbid. */
 .viewport { flex: 1; overflow: hidden; position: relative; cursor: grab; touch-action: none;

package/dist/inspect/index.d.ts

@@ -1,7 +1,7 @@
-import { type ReportOptions, type RunReport } from './report.ts';
-import type { AgentState } from '../state.ts';
 import type { PayloadResolver } from '../payload.ts';
-export { buildRunReport, MAX_BLOB_BYTES, MERMAID_URL, type ReportOptions, type RunReport, } from './report.ts';
+import type { AgentState } from '../state.ts';
+import { type ReportOptions, type RunReport } from './report.ts';
+export { buildRunReport, MAX_BLOB_BYTES, MAX_MEMORY_FILE_BYTES, MERMAID_URL, type ReportOptions, type RunMemory, type RunReport, } from './report.ts';
 /** Report → one standalone HTML document. */
 export declare function renderReportHtml(report: RunReport, opts?: ReportOptions): string;
 /** The usual entry point: state in, HTML out. */

package/dist/inspect/index.js

@@ -1,6 +1,6 @@
 import { page } from "./page.js";
 import { buildRunReport, MERMAID_URL } from "./report.js";
-export { buildRunReport, MAX_BLOB_BYTES, MERMAID_URL, } from "./report.js";
+export { buildRunReport, MAX_BLOB_BYTES, MAX_MEMORY_FILE_BYTES, MERMAID_URL, } from "./report.js";
 /** Report → one standalone HTML document. */
 export function renderReportHtml(report, opts = {}) {
     return page(report, opts.mermaidUrl ?? MERMAID_URL);

package/dist/inspect/page.js

@@ -29,6 +29,7 @@ export function page(report, mermaidUrl) {
       <button data-view="detail">Detail</button>
       <button data-view="stats">Stats</button>
       <button data-view="agents">Agents</button>
+      <button data-view="memory" hidden>Memory</button>
     </div>
     <div id="graph" class="pane">
       <div class="gtools">
@@ -54,6 +55,21 @@ export function page(report, mermaidUrl) {
       </div>
       <div class="viewport"><div class="canvas"><div class="hint pad">rendering…</div></div></div>
     </div>
+    <div id="memory" class="pane" hidden>
+      <div class="gtools">
+        <button data-zoom="out" title="zoom out">−</button>
+        <button data-zoom="in" title="zoom in">+</button>
+        <button data-zoom="fit" title="fit to window (double-click the canvas)">fit</button>
+        <button data-zoom="reset" title="actual size">1:1</button>
+        <label class="check"><input type="checkbox" id="madded"> show what it wrote</label>
+        <span class="hint" id="mcount"></span>
+        <span class="hint lvl">100%</span>
+      </div>
+      <div class="split">
+        <div class="viewport"><div class="canvas"><div class="hint pad">rendering…</div></div></div>
+        <aside id="mdetail"><div class="hint pad">Pick a node.</div></aside>
+      </div>
+    </div>
   </section>
 </main>
 <script id="run-data" type="application/json">${embedJson(report)}</script>

package/dist/inspect/report.d.ts

@@ -1,10 +1,16 @@
 import type { Architecture } from '../architecture.ts';
+import { type ReportNode } from '../memory/report.ts';
+import type { MemoryStore } from '../memory/store.ts';
+import type { MemoryEdge } from '../memory/types.ts';
 import { type PayloadResolver } from '../payload.ts';
 import type { AgentState } from '../state.ts';
 /** Default per-payload inline cap. Keeps one runaway tool result from turning
  *  a report into a file no editor will open. */
 export declare const MAX_BLOB_BYTES: number;
 export declare const MERMAID_URL = "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+/** Deliberately meaner than the memory page's own cap: this file already holds
+ *  a whole run, and one remembered artifact should not decide whether it opens. */
+export declare const MAX_MEMORY_FILE_BYTES: number;
 export interface ReportOptions {
     title?: string;
     /** per-payload inline cap; larger values are cut, with a visible marker */
@@ -22,6 +28,14 @@ export interface ReportOptions {
      * strictly smaller picture but never a wrong one.
      */
     architecture?: Architecture;
+    /**
+     * The memory to resolve recalled and committed nodes against. A trajectory
+     * records ids, kinds and edges but no bodies, so without this the memory
+     * view can draw the shape of what was read and not a word of it.
+     */
+    memory?: MemoryStore;
+    /** ceiling on an inlined remembered file; 0 to inline none */
+    maxMemoryFileBytes?: number;
 }
 /** Everything the page needs, and nothing that needs a store to interpret. */
 export interface RunReport {
@@ -44,6 +58,17 @@ export interface RunReport {
     media: string[];
     /** the declared wiring, when the caller had a runner to ask */
     architecture?: Architecture;
+    /**
+     * The memory nodes this run read or wrote, as the graph holds them *now* —
+     * which is later than the run. The page says so where it matters: a node
+     * can have moved on a revision since, or be gone from the graph entirely.
+     */
+    memory?: RunMemory;
+}
+export interface RunMemory {
+    dir: string;
+    nodes: ReportNode[];
+    edges: MemoryEdge[];
 }
 /**
  * Resolves a state into a self-describing report. Separate from rendering so a

package/dist/inspect/report.js

@@ -1,3 +1,4 @@
+import { buildMemorySlice } from "../memory/report.js";
 import { collectPayloads } from "../payload.js";
 // ---------------------------------------------------------------------------
 // Run inspector — a single HTML file that explains a run
@@ -12,6 +13,9 @@ import { collectPayloads } from "../payload.js";
  *  a report into a file no editor will open. */
 export const MAX_BLOB_BYTES = 512 * 1024;
 export const MERMAID_URL = 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+/** Deliberately meaner than the memory page's own cap: this file already holds
+ *  a whole run, and one remembered artifact should not decide whether it opens. */
+export const MAX_MEMORY_FILE_BYTES = 64 * 1024;
 /** Base64 data uris only: the charset ends at the closing JSON quote. */
 const DATA_URL = /data:[\w.+-]+\/[\w.+-]+;base64,[A-Za-z0-9+/=]+/g;
 /** Below this a uri is cheaper to leave in place than to indirect through. */
@@ -57,6 +61,47 @@ export async function buildRunReport(state, payloads, opts = {}) {
         truncated,
         media,
         architecture: opts.architecture,
+        memory: opts.memory ? await remembered(opts.memory, state, media, opts) : undefined,
+    };
+}
+/** Every memory node the run touched, branches included. */
+function memoryIds(nodes, into) {
+    for (const node of nodes) {
+        if (node.type === 'memory_recall' || node.type === 'memory_op') {
+            for (const n of node.nodes) {
+                into.add(n.id);
+            }
+        }
+        else if (node.type === 'join') {
+            for (const branch of node.branches) {
+                memoryIds(branch.nodes, into);
+            }
+        }
+    }
+    return into;
+}
+async function remembered(store, state, media, opts) {
+    const ids = memoryIds(state.trajectory, new Set());
+    if (!ids.size) {
+        return undefined;
+    }
+    let slice;
+    try {
+        slice = await buildMemorySlice(store, [...ids], {
+            maxContentBytes: opts.maxMemoryFileBytes ?? MAX_MEMORY_FILE_BYTES,
+        });
+    }
+    catch {
+        // A memory that cannot be read is a view the page does without; it is
+        // not a reason to lose the record of the run.
+        return undefined;
+    }
+    return {
+        dir: store.dir,
+        // Remembered images go through the same table as the run's own, so a
+        // picture the agent both saw and filed is carried once.
+        nodes: slice.nodes.map((n) => (n.image ? { ...n, image: hoistMedia(n.image, media) } : n)),
+        edges: slice.edges,
     };
 }
 //# sourceMappingURL=report.js.map

package/dist/kernel.d.ts

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { Agent, AgentRegistry } from './agent.ts';
 import type { PendingToolCall } from './events.ts';
 import { type IdClock } from './ids.ts';
-import { type MemoryOpSpec, type MemoryRecallSpec } from './memory.ts';
+import type { MemoryOpSpec, MemoryRecallSpec } from './memory/types.ts';
 import type { ModelRequest, ModelResponse } from './model.ts';
 import type { Services } from './services.ts';
 import { type Skill } from './skills.ts';

package/dist/kernel.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
 import { Agent, AgentRegistry, handoffTarget, handoffTool } from "./agent.js";
 import { systemClock } from "./ids.js";
-import { memoryTools } from "./memory.js";
+import { memoryInstructions, renderPreferences } from "./memory/instructions.js";
+import { memoryTools } from "./memory/tools.js";
 import { hash } from "./payload.js";
 import { composePrompt } from "./prompt.js";
 import { allows, lockedSkillTools, renderSkillIndex, renderSkills, skillContentHash, skillTools, } from "./skills.js";
@@ -285,7 +286,10 @@ export async function resolveTools(state, reg, env) {
     for (const name of agent.handoffs) {
         tools.push(handoffTool(name, reg.find(name)?.description));
     }
-    tools.push(...memoryTools(agent.memoryBindings(ctx)));
+    const binding = agent.memoryBinding(ctx);
+    if (binding && env.services.memory) {
+        tools.push(...memoryTools({ index: env.services.memory, binding }));
+    }
     if (agent.skills) {
         const binding = agent.skills;
         tools.push(...skillTools(binding));
@@ -318,14 +322,24 @@ function toSchema(t) {
     return { name: t.name, description: t.description, parameters: t.parameters };
 }
 /**
- * Prompt text the runtime owns rather than the author: the skill index and the
- * `final_output` instruction. Both used to be appended inside `buildRequest`,
- * which meant part of the system prompt existed in no node and showed up in no
- * audit. Composed in now, always last, so the volatile tail never invalidates
- * the cacheable prefix.
+ * Prompt text the runtime owns rather than the author: how to use memory, the
+ * user's standing preferences, the skill index and the `final_output`
+ * instruction. Most used to be appended inside `buildRequest`, which meant part
+ * of the system prompt existed in no node and showed up in no audit. Composed
+ * in now, always last, so the volatile tail never invalidates the cacheable
+ * prefix.
  */
 async function derivedPrompt(agent, state, env) {
     const out = [];
+    const memory = agent.memoryBinding(state.context);
+    if (memory && env.services.memory) {
+        // The one part of the prompt that reads mutable state. It is allowed
+        // because preferences change at most once in a run and
+        // `applySystemPrompt` is keyed on the rendered bytes, so a commit
+        // re-renders the prefix once rather than every turn.
+        out.push(memoryInstructions(memory));
+        out.push(renderPreferences(env.services.memory.preferences(memory.sees)));
+    }
     if (agent.skills?.discovery === 'index') {
         const binding = agent.skills;
         const provider = env.services.skillProvider(binding.provider);
@@ -654,11 +668,14 @@ export async function applyToolResult(state, callId, outcome, env) {
         durationMs: outcome.durationMs,
     });
     for (const effect of outcome.effects ?? []) {
-        if (effect.kind === 'memory_op') {
+        if (effect.kind === 'skill_load') {
+            await addSkillLoad(b, env, effect.spec);
+        }
+        else if (effect.spec.kind === 'op') {
             await addMemoryOp(b, env, effect.spec);
         }
         else {
-            await addSkillLoad(b, env, effect.spec);
+            await addMemoryRecall(b, env, effect.spec);
         }
     }
     const target = outcome.isError ? undefined : handoffTarget(call.name);
@@ -694,13 +711,20 @@ async function addMemoryOp(b, env, spec) {
     b.add({
         type: 'memory_op',
         op: spec.op,
-        store: spec.store,
-        scope: spec.scope,
         opId: spec.opId,
-        recordId: spec.recordId,
-        revision: spec.revision,
-        before: spec.before === undefined ? undefined : await put(env, spec.before),
-        after: spec.after === undefined ? undefined : await put(env, spec.after),
+        nodes: spec.nodes,
+        edges: spec.edges,
+        files: spec.files,
+    });
+}
+async function addMemoryRecall(b, env, spec) {
+    b.add({
+        type: 'memory_recall',
+        query: spec.query,
+        seeds: spec.seeds,
+        nodes: spec.nodes,
+        edges: spec.edges,
+        content: await put(env, spec.content),
     });
 }
 async function addSkillLoad(b, env, spec) {
@@ -724,14 +748,7 @@ export async function applyMemoryEffect(state, effect, env) {
         await addMemoryOp(b, env, effect);
     }
     else {
-        b.add({
-            type: 'memory_recall',
-            store: effect.store,
-            scope: effect.scope,
-            query: effect.query,
-            hits: effect.hits,
-            content: await put(env, effect.content),
-        });
+        await addMemoryRecall(b, env, effect);
     }
     return b.commit({});
 }

package/dist/memory/files.d.ts

@@ -0,0 +1,24 @@
+import { type MemoryFile } from './types.ts';
+/** Where remembered files appear in the agent's namespace. */
+export declare const MEMORY_MOUNT = "/memory";
+/**
+ * Big enough for any script or config worth re-running, small enough that the
+ * memory directory cannot become a place where build outputs go to hide.
+ */
+export declare const MAX_FILE_BYTES: number;
+export interface RememberOptions {
+    maxBytes?: number;
+}
+/**
+ * Copy `source` into the memory directory under `id` and describe it.
+ *
+ * The bytes are read once and both hashed and written from that one buffer, so
+ * the digest provably belongs to the copy that was kept — re-reading the source
+ * to hash it would leave a window for it to change in between.
+ */
+export declare function rememberFile(dir: string, source: string, id: string, opts?: RememberOptions): Promise<MemoryFile>;
+/** The host path of a remembered file, for reading it back or deleting it. */
+export declare function hostPath(dir: string, file: MemoryFile): string;
+/** Drop the bytes of a forgotten node. Missing is success — the goal is absence. */
+export declare function forgetFile(dir: string, file: MemoryFile): Promise<void>;
+//# sourceMappingURL=files.d.ts.map

package/dist/memory/files.js

@@ -0,0 +1,85 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { basename, extname, join } from 'node:path';
+import { FILES_DIR } from "./store.js";
+import { MemoryError } from "./types.js";
+// ---------------------------------------------------------------------------
+// Remembered files
+//
+// An agent that writes a working script should be able to run it again next
+// week, and a summary of a script is not a script. So the bytes are copied out
+// of the workspace — which is disposable, and may be a container that is about
+// to be discarded — into the memory directory, under the id of the node that
+// describes them. The copy is the point: a reference to a workspace path would
+// dangle the moment the run ends.
+//
+// The tree is mounted read-only at /memory. Nothing writes there through the
+// file tools, so every file under it has a node that explains what it is, and
+// the graph cannot acquire orphans that no recollection can ever surface.
+// ---------------------------------------------------------------------------
+/** Where remembered files appear in the agent's namespace. */
+export const MEMORY_MOUNT = '/memory';
+/**
+ * Big enough for any script or config worth re-running, small enough that the
+ * memory directory cannot become a place where build outputs go to hide.
+ */
+export const MAX_FILE_BYTES = 2 * 1024 * 1024;
+/** Extensions are for `run_command` and syntax hints, not a type system. */
+const MAX_FORMAT_LEN = 16;
+/**
+ * Copy `source` into the memory directory under `id` and describe it.
+ *
+ * The bytes are read once and both hashed and written from that one buffer, so
+ * the digest provably belongs to the copy that was kept — re-reading the source
+ * to hash it would leave a window for it to change in between.
+ */
+export async function rememberFile(dir, source, id, opts = {}) {
+    const maxBytes = opts.maxBytes ?? MAX_FILE_BYTES;
+    const info = await describe(source);
+    if (!info.isFile()) {
+        throw new MemoryError(`${source} is not a regular file`, 'only files can be remembered; write a `fact` node describing a directory instead');
+    }
+    if (info.size > maxBytes) {
+        throw new MemoryError(`${source} is ${info.size} bytes, over the ${maxBytes} byte limit for a remembered file`, 'keep the artifact in the workspace and remember a `snippet` of the part that matters');
+    }
+    const bytes = await readFile(source);
+    if (bytes.byteLength > maxBytes) {
+        throw new MemoryError(`${source} grew past the ${maxBytes} byte limit while being read`);
+    }
+    const format = formatOf(source);
+    const name = id + (format ? `.${format}` : '');
+    await mkdir(join(dir, FILES_DIR), { recursive: true });
+    await writeFile(join(dir, FILES_DIR, name), bytes);
+    return {
+        path: `${MEMORY_MOUNT}/${name}`,
+        bytes: bytes.byteLength,
+        sha256: createHash('sha256').update(bytes).digest('hex'),
+        format,
+    };
+}
+/** The host path of a remembered file, for reading it back or deleting it. */
+export function hostPath(dir, file) {
+    // Through `basename` so a stored path can never climb out of the tree.
+    return join(dir, FILES_DIR, basename(file.path));
+}
+/** Drop the bytes of a forgotten node. Missing is success — the goal is absence. */
+export async function forgetFile(dir, file) {
+    await rm(hostPath(dir, file), { force: true });
+}
+async function describe(source) {
+    try {
+        return await stat(source);
+    }
+    catch {
+        throw new MemoryError(`${source} does not exist`, 'remember a file the run actually wrote, by the path the file tools use');
+    }
+}
+/**
+ * The extension drives how the file is run and rendered, so it is kept, but it
+ * becomes part of a filename this module chooses — hence the character class.
+ */
+function formatOf(source) {
+    const ext = extname(source).slice(1).toLowerCase();
+    return /^[a-z0-9]+$/.test(ext) && ext.length <= MAX_FORMAT_LEN ? ext : '';
+}
+//# sourceMappingURL=files.js.map

package/dist/memory/graph.d.ts

@@ -0,0 +1,56 @@
+import { MultiDirectedGraph } from 'graphology';
+import { type MemoryEdge, type MemoryEdgeAttrs, type MemoryNode, type Relation } from './types.ts';
+export type Graphology = MultiDirectedGraph<MemoryNode, MemoryEdgeAttrs>;
+export interface NodeDraft {
+    id: string;
+    kind: string;
+    text: string;
+    audience: string[];
+    metadata?: Record<string, unknown>;
+    file?: MemoryNode['file'];
+}
+export interface NodePatch {
+    kind?: string;
+    text?: string;
+    audience?: string[];
+    metadata?: Record<string, unknown>;
+    file?: MemoryNode['file'];
+    /** when given, the update fails unless the stored revision matches */
+    expectedRevision?: number;
+}
+/** Deterministic, so the same link committed twice stays one edge. */
+export declare const edgeKey: (source: string, target: string, relation: Relation) => string;
+export declare class MemoryGraph {
+    #private;
+    static from(serialized: unknown): MemoryGraph;
+    export(): ReturnType<Graphology['export']>;
+    get order(): number;
+    get size(): number;
+    has(id: string): boolean;
+    get(id: string): MemoryNode | undefined;
+    add(draft: NodeDraft, at: string): MemoryNode;
+    update(id: string, patch: NodePatch, at: string): MemoryNode;
+    /** Reading is what counts as use — see `memory_load`, not `memory_search`. */
+    touch(id: string, at: string): MemoryNode | undefined;
+    link(source: string, target: string, relation: Relation, at: string): void;
+    /** Drops the node and every edge touching it; the file it names is the store's to unlink. */
+    forget(id: string): MemoryNode | undefined;
+    nodes(sees?: readonly string[]): MemoryNode[];
+    edges(sees?: readonly string[]): MemoryEdge[];
+    /** Both directions: a memory is as often reached from its artifact as from its request. */
+    neighbors(id: string, sees?: readonly string[]): MemoryEdge[];
+    /** Edges between nodes already chosen — what makes a materialized subgraph closed. */
+    between(ids: Iterable<string>, sees?: readonly string[]): MemoryEdge[];
+    /**
+     * The nodes some visible node replaces. Recall drops these, which is what
+     * makes a correction take effect without erasing what was corrected.
+     */
+    superseded(sees?: readonly string[]): Set<string>;
+}
+export declare class RevisionMismatch extends Error {
+    readonly id: string;
+    readonly expected: number;
+    readonly actual: number;
+    constructor(id: string, expected: number, actual: number);
+}
+//# sourceMappingURL=graph.d.ts.map

package/dist/memory/graph.js

@@ -0,0 +1,159 @@
+import { MultiDirectedGraph } from 'graphology';
+import { edgeVisible, visible, } from "./types.js";
+/** Deterministic, so the same link committed twice stays one edge. */
+export const edgeKey = (source, target, relation) => `${source}|${relation}|${target}`;
+export class MemoryGraph {
+    #graph = new MultiDirectedGraph();
+    static from(serialized) {
+        const g = new MemoryGraph();
+        g.#graph.import(serialized);
+        return g;
+    }
+    export() {
+        return this.#graph.export();
+    }
+    get order() {
+        return this.#graph.order;
+    }
+    get size() {
+        return this.#graph.size;
+    }
+    has(id) {
+        return this.#graph.hasNode(id);
+    }
+    get(id) {
+        return this.#graph.hasNode(id) ? this.#graph.getNodeAttributes(id) : undefined;
+    }
+    add(draft, at) {
+        const node = {
+            id: draft.id,
+            kind: draft.kind,
+            text: draft.text,
+            audience: draft.audience.length ? [...draft.audience] : ['*'],
+            createdAt: at,
+            updatedAt: at,
+            lastUsedAt: at,
+            useCount: 0,
+            revision: 1,
+            ...(draft.metadata ? { metadata: draft.metadata } : {}),
+            ...(draft.file ? { file: draft.file } : {}),
+        };
+        this.#graph.addNode(node.id, node);
+        return node;
+    }
+    update(id, patch, at) {
+        const current = this.#graph.getNodeAttributes(id);
+        if (patch.expectedRevision !== undefined && patch.expectedRevision !== current.revision) {
+            throw new RevisionMismatch(id, patch.expectedRevision, current.revision);
+        }
+        const next = {
+            ...current,
+            ...(patch.kind !== undefined ? { kind: patch.kind } : {}),
+            ...(patch.text !== undefined ? { text: patch.text } : {}),
+            ...(patch.audience !== undefined ? { audience: [...patch.audience] } : {}),
+            ...(patch.metadata !== undefined ? { metadata: patch.metadata } : {}),
+            ...(patch.file !== undefined ? { file: patch.file } : {}),
+            updatedAt: at,
+            revision: current.revision + 1,
+        };
+        this.#graph.replaceNodeAttributes(id, next);
+        return next;
+    }
+    /** Reading is what counts as use — see `memory_load`, not `memory_search`. */
+    touch(id, at) {
+        if (!this.#graph.hasNode(id)) {
+            return undefined;
+        }
+        const node = this.#graph.getNodeAttributes(id);
+        const next = { ...node, lastUsedAt: at, useCount: node.useCount + 1 };
+        this.#graph.replaceNodeAttributes(id, next);
+        return next;
+    }
+    link(source, target, relation, at) {
+        this.#graph.mergeEdgeWithKey(edgeKey(source, target, relation), source, target, {
+            relation,
+            createdAt: at,
+        });
+    }
+    /** Drops the node and every edge touching it; the file it names is the store's to unlink. */
+    forget(id) {
+        const node = this.get(id);
+        if (node) {
+            this.#graph.dropNode(id);
+        }
+        return node;
+    }
+    nodes(sees) {
+        const out = [];
+        this.#graph.forEachNode((_id, attrs) => {
+            if (!sees || visible(attrs, sees)) {
+                out.push(attrs);
+            }
+        });
+        return out;
+    }
+    edges(sees) {
+        const out = [];
+        this.#graph.forEachEdge((_key, attrs, source, target) => {
+            if (sees && !this.#passable(source, target, attrs, sees)) {
+                return;
+            }
+            out.push({ source, target, relation: attrs.relation });
+        });
+        return out;
+    }
+    /** Both directions: a memory is as often reached from its artifact as from its request. */
+    neighbors(id, sees) {
+        if (!this.#graph.hasNode(id)) {
+            return [];
+        }
+        const out = [];
+        this.#graph.forEachEdge(id, (_key, attrs, source, target) => {
+            if (sees && !this.#passable(source, target, attrs, sees)) {
+                return;
+            }
+            out.push({ source, target, relation: attrs.relation });
+        });
+        return out;
+    }
+    /** Edges between nodes already chosen — what makes a materialized subgraph closed. */
+    between(ids, sees) {
+        const set = new Set(ids);
+        return this.edges(sees).filter((e) => set.has(e.source) && set.has(e.target));
+    }
+    /**
+     * The nodes some visible node replaces. Recall drops these, which is what
+     * makes a correction take effect without erasing what was corrected.
+     */
+    superseded(sees) {
+        const out = new Set();
+        this.#graph.forEachEdge((_key, attrs, source, target) => {
+            if (attrs.relation !== 'SUPERSEDES') {
+                return;
+            }
+            if (sees && !this.#passable(source, target, attrs, sees)) {
+                return;
+            }
+            out.add(target);
+        });
+        return out;
+    }
+    #passable(source, target, attrs, sees) {
+        return (edgeVisible(attrs, sees) &&
+            visible(this.#graph.getNodeAttributes(source), sees) &&
+            visible(this.#graph.getNodeAttributes(target), sees));
+    }
+}
+export class RevisionMismatch extends Error {
+    id;
+    expected;
+    actual;
+    constructor(id, expected, actual) {
+        super(`memory ${id} has revision ${actual}, not ${expected}`);
+        this.name = 'RevisionMismatch';
+        this.id = id;
+        this.expected = expected;
+        this.actual = actual;
+    }
+}
+//# sourceMappingURL=graph.js.map