@zenera/neo 1.1.10 → 1.1.12

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

package/dist/memory/index.d.ts

@@ -0,0 +1,93 @@
+import type { Embedder } from '../embedding.ts';
+import type { IdClock } from '../ids.ts';
+import type { MemoryGraph } from './graph.ts';
+import type { MemoryStore } from './store.ts';
+import { type MemoryNode, type MemoryQuery, type Recollection } from './types.ts';
+/** Past this a `load` returns the path and lets the agent open it itself. */
+export declare const INLINE_FILE_BYTES: number;
+/**
+ * Cosine at or above this is one memory written twice, not two memories. Set
+ * high on purpose: merging two things that only resembled each other loses a
+ * memory outright, while missing a merge only wastes a node.
+ */
+export declare const DUPLICATE_SCORE = 0.97;
+export interface MemoryIndexOptions {
+    store: MemoryStore;
+    /** absent ranks by term overlap and stores no vectors */
+    embedder?: Embedder;
+    /** the project's vocabulary, when it extends the built-in one */
+    kinds?: readonly string[];
+    relations?: readonly string[];
+}
+export interface CommitNode {
+    /** names this node within the transaction; for a node being created */
+    ref?: string;
+    /** an existing node to update; mutually exclusive with `ref` */
+    id?: string;
+    kind?: string;
+    text?: string;
+    audience?: string[];
+    metadata?: Record<string, unknown>;
+    /** absolute host path of a file to copy in, already resolved by the caller */
+    file?: {
+        source: string;
+    };
+    expectedRevision?: number;
+}
+export interface CommitEdge {
+    from: string;
+    to: string;
+    relation: string;
+}
+export interface MemoryTransaction {
+    nodes?: CommitNode[];
+    edges?: CommitEdge[];
+}
+export interface CommitOptions {
+    /** audience labels this agent may assign */
+    writes: readonly string[];
+    /** labels it may read; a duplicate is only a duplicate if it can see it */
+    sees: readonly string[];
+    clock: IdClock;
+}
+export interface CommitResult {
+    /** local ref (or id, for an update) to the id it resolved to */
+    ids: Record<string, string>;
+    created: number;
+    updated: number;
+    edges: number;
+    files: number;
+    /** new nodes that turned out to already exist, and were folded into them */
+    merged: number;
+}
+export interface LoadedNode {
+    node: MemoryNode;
+    /** the file's bytes, when it was small enough to inline */
+    content?: string;
+}
+export declare class MemoryIndex {
+    #private;
+    readonly store: MemoryStore;
+    constructor(opts: MemoryIndexOptions);
+    get graph(): MemoryGraph;
+    get kinds(): readonly string[];
+    get relations(): readonly string[];
+    /** Read-only: a search returns nodes the model has not read, so nothing is touched. */
+    search(query: MemoryQuery, sees: readonly string[]): Promise<Recollection>;
+    /**
+     * Listed rather than ranked, and deliberately not routed through `recall`:
+     * ranking decays by `lastUsedAt`, only `memory_load` bumps that, and a
+     * preference is injected rather than loaded — so it would age out of its
+     * own list. Ordered so the rendered block is byte-stable between runs,
+     * because an unstable one would invalidate the prompt prefix for nothing.
+     */
+    preferences(sees: readonly string[]): MemoryNode[];
+    /**
+     * The only path that counts as use — recency decay is meant to track what
+     * an agent actually read, and a search hands back context it never opened.
+     */
+    load(ids: readonly string[], sees: readonly string[], clock: IdClock): Promise<LoadedNode[]>;
+    commit(tx: MemoryTransaction, opts: CommitOptions): Promise<CommitResult>;
+    forget(ids: readonly string[], sees: readonly string[]): Promise<MemoryNode[]>;
+}
+//# sourceMappingURL=index.d.ts.map