@zenera/neo 1.1.24 → 1.1.26

package/dist/memory/merge.js

@@ -4,6 +4,7 @@ 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 { comparable, sameContent, twinKey } from "./twin.js";
 import { MemoryError } from "./types.js";
 // ---------------------------------------------------------------------------
 // Folding several memories into one
@@ -251,15 +252,6 @@ function twinOf(target, src, node, lexical, stale) {
     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;
@@ -284,28 +276,6 @@ function reconcile(keep, other) {
 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()) {

package/dist/memory/store.d.ts

@@ -1,3 +1,4 @@
+import { type Lock } from '../lock.ts';
 import { MemoryGraph } from './graph.ts';
 import { VectorBlock } from './vectors.ts';
 export declare const MEMORY_VERSION = 1;
@@ -19,11 +20,6 @@ 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;

package/dist/memory/store.js

@@ -1,7 +1,7 @@
-import { readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { unlinkSync } from 'node:fs';
 import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
-import { hostname } from 'node:os';
 import { join } from 'node:path';
+import { claimLock, liveHolder, ownLock } from "../lock.js";
 import { MemoryGraph } from "./graph.js";
 import { MemoryError } from "./types.js";
 import { VectorBlock } from "./vectors.js";
@@ -115,12 +115,13 @@ export class MemoryStore {
         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()));
+        // Indented so a committed memory diffs per node rather than as one line.
+        await atomic(join(this.dir, GRAPH_FILE), `${JSON.stringify(this.graph.export(), null, 2)}\n`);
         const vectors = this.#vectors;
         if (vectors) {
             const raw = vectors.bytes();
             await atomic(join(this.dir, VECTORS_FILE), new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength));
-            await atomic(join(this.dir, VECTOR_IDS_FILE), JSON.stringify({ dims: vectors.dims, ids: vectors.ids }));
+            await atomic(join(this.dir, VECTOR_IDS_FILE), `${JSON.stringify({ dims: vectors.dims, ids: vectors.ids }, null, 2)}\n`);
         }
         const manifest = {
             version: MEMORY_VERSION,
@@ -143,33 +144,8 @@ export class MemoryStore {
             // Already gone, or taken over as stale: neither is worth failing a run for.
         }
     }
-    /**
-     * `wx` makes the create and the check one operation, so two runs racing for
-     * the same project cannot both win.
-     */
     #claim() {
-        const path = join(this.dir, LOCK_FILE);
-        const lock = {
-            pid: process.pid,
-            host: hostname(),
-            startedAt: new Date().toISOString(),
-        };
-        const body = `${JSON.stringify(lock, null, 4)}\n`;
-        try {
-            writeFileSync(path, body, { flag: 'wx' });
-            this.#locked = true;
-            return;
-        }
-        catch (err) {
-            if (err.code !== 'EEXIST') {
-                throw err;
-            }
-        }
-        const held = readLock(path);
-        if (held && held.host === hostname() && alive(held.pid)) {
-            throw new MemoryError(`this memory is in use (pid ${held.pid}, since ${held.startedAt})`, 'wait for that run to finish, or remove .lock if it crashed');
-        }
-        writeFileSync(path, body);
+        claimLock(join(this.dir, LOCK_FILE), ownLock(), (held) => new MemoryError(`this memory is in use (pid ${held.pid}, since ${held.startedAt})`, 'wait for that run to finish, or remove .lock if it crashed'));
         this.#locked = true;
     }
 }
@@ -226,28 +202,6 @@ async function atomic(path, body) {
  * 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'));
-    }
-    catch {
-        return undefined;
-    }
-}
-/**
- * `kill(pid, 0)` sends no signal and only asks whether the process exists.
- * EPERM means it exists and belongs to someone else, which still counts.
- */
-function alive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (err) {
-        return err.code === 'EPERM';
-    }
+    return liveHolder(join(dir, LOCK_FILE));
 }
 //# sourceMappingURL=store.js.map

package/dist/memory/twin.d.ts

@@ -0,0 +1,6 @@
+import type { MemoryNode } from './types.ts';
+export declare function comparable(a: MemoryNode, b: MemoryNode): boolean;
+export declare function twinKey(node: MemoryNode): string;
+export declare function audienceKey(node: MemoryNode): string;
+export declare function sameContent(a: MemoryNode, b: MemoryNode): boolean;
+//# sourceMappingURL=twin.d.ts.map

package/dist/memory/twin.js

@@ -0,0 +1,40 @@
+import { flatten } from "./index.js";
+// ---------------------------------------------------------------------------
+// When two memories are the same memory
+//
+// Shared by `merge`, which folds a twin onto the node already held, and `diff`,
+// which reports it. One rule, so what diff calls a re-commit is exactly what
+// merge would have folded.
+// ---------------------------------------------------------------------------
+export function comparable(a, b) {
+    return a.id !== b.id && a.kind === b.kind && !a.file && audienceKey(a) === audienceKey(b);
+}
+export function twinKey(node) {
+    return [node.kind, audienceKey(node), flatten(node.text)].join('\u0000');
+}
+export function audienceKey(node) {
+    return [...node.audience].sort().join('|');
+}
+export 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]));
+}
+//# sourceMappingURL=twin.js.map

package/dist/memory-stores/factory.d.ts

@@ -0,0 +1,15 @@
+import type { MemoryStore } from '../memory.ts';
+import { type FileMemoryStoreOptions } from './file.ts';
+export interface MemoryMemoryStoreSpec {
+    kind: 'memory';
+    id?: string;
+}
+export interface FileMemoryStoreSpec extends FileMemoryStoreOptions {
+    kind: 'file';
+}
+/** Grows a member per backend (`pgvector`, `redis`, …). */
+export type MemoryStoreSpec = MemoryMemoryStoreSpec | FileMemoryStoreSpec;
+/** Shorthand: `mem`, `memory`, `file:./.data/memory`. */
+export type MemoryStoreRef = MemoryStoreSpec | string;
+export declare function createMemoryStore(ref: MemoryStoreRef): MemoryStore;
+//# sourceMappingURL=factory.d.ts.map

package/dist/memory-stores/factory.js

@@ -0,0 +1,29 @@
+import { FileMemoryStore } from "./file.js";
+import { InMemoryMemoryStore } from "./in-memory.js";
+export function createMemoryStore(ref) {
+    const spec = typeof ref === 'string' ? parseRef(ref) : ref;
+    switch (spec.kind) {
+        case 'memory':
+            return new InMemoryMemoryStore(spec.id);
+        case 'file':
+            return new FileMemoryStore(spec);
+        default:
+            throw new TypeError(`unknown memory store kind: ${spec.kind}`);
+    }
+}
+function parseRef(ref) {
+    if (ref === 'mem' || ref === 'memory') {
+        return { kind: 'memory' };
+    }
+    const colon = ref.indexOf(':');
+    const scheme = colon < 0 ? ref : ref.slice(0, colon);
+    const rest = colon < 0 ? '' : ref.slice(colon + 1);
+    if (scheme === 'file') {
+        if (!rest) {
+            throw new TypeError(`missing directory in "${ref}" (expected file:<dir>)`);
+        }
+        return { kind: 'file', dir: rest };
+    }
+    throw new TypeError(`unknown memory store ref: "${ref}"`);
+}
+//# sourceMappingURL=factory.js.map

package/dist/memory-stores/file.d.ts

@@ -0,0 +1,37 @@
+import { type MemoryDraft, type MemoryHit, type MemoryPatch, type MemoryQuery, type MemoryRecord, type MemoryStore } from '../memory.ts';
+export interface FileMemoryStoreOptions {
+    /** root directory; created on demand */
+    dir: string;
+    /** logical store id agents bind to; defaults to `file` */
+    id?: string;
+}
+/**
+ * One JSON file per record, under one directory per scope:
+ *
+ * ```
+ * <dir>/<scope>/scope.json        the unescaped scope name, for humans
+ * <dir>/<scope>/records/<id>.json
+ * <dir>/<scope>/ops/<opId>.json   idempotency ledger
+ * ```
+ *
+ * A file per record (rather than one appended log) keeps writes atomic and
+ * deletes cheap without a compaction step. Search reads the whole scope and
+ * ranks in process, which is exactly the trade this backend makes: no server,
+ * no index, fine up to a few thousand records per scope.
+ *
+ * There is no cross-process lock. Concurrent writers to the *same* record can
+ * lose an update; `expectedRevision` narrows that window, and a deployment
+ * that needs real isolation should use a database-backed store.
+ */
+export declare class FileMemoryStore implements MemoryStore {
+    #private;
+    readonly id: string;
+    constructor(opts: FileMemoryStoreOptions | string);
+    get dir(): string;
+    search(scope: string, q: MemoryQuery): Promise<MemoryHit[]>;
+    get(scope: string, id: string): Promise<MemoryRecord | undefined>;
+    write(scope: string, rec: MemoryDraft, opId: string): Promise<MemoryRecord>;
+    update(scope: string, id: string, patch: MemoryPatch, opId: string): Promise<MemoryRecord>;
+    delete(scope: string, id: string, opId: string): Promise<void>;
+}
+//# sourceMappingURL=file.d.ts.map

package/dist/memory-stores/file.js

@@ -0,0 +1,174 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { rankMemories, } from "../memory.js";
+// ---------------------------------------------------------------------------
+// Filesystem-backed memory store
+// ---------------------------------------------------------------------------
+/**
+ * Record ids and op ids reach this store from model-authored tool arguments
+ * (`memory_update`, `memory_delete`), so they are validated before becoming
+ * path segments. Dots are excluded outright, which makes `.` and `..`
+ * unrepresentable.
+ */
+const SAFE_ID = /^[A-Za-z0-9_-]+$/;
+/**
+ * One JSON file per record, under one directory per scope:
+ *
+ * ```
+ * <dir>/<scope>/scope.json        the unescaped scope name, for humans
+ * <dir>/<scope>/records/<id>.json
+ * <dir>/<scope>/ops/<opId>.json   idempotency ledger
+ * ```
+ *
+ * A file per record (rather than one appended log) keeps writes atomic and
+ * deletes cheap without a compaction step. Search reads the whole scope and
+ * ranks in process, which is exactly the trade this backend makes: no server,
+ * no index, fine up to a few thousand records per scope.
+ *
+ * There is no cross-process lock. Concurrent writers to the *same* record can
+ * lose an update; `expectedRevision` narrows that window, and a deployment
+ * that needs real isolation should use a database-backed store.
+ */
+export class FileMemoryStore {
+    id;
+    #dir;
+    constructor(opts) {
+        const o = typeof opts === 'string' ? { dir: opts } : opts;
+        this.#dir = resolve(o.dir);
+        this.id = o.id ?? 'file';
+    }
+    get dir() {
+        return this.#dir;
+    }
+    async search(scope, q) {
+        return rankMemories(await this.#all(scope), q);
+    }
+    async get(scope, id) {
+        return this.#readJson(this.#recordPath(scope, id));
+    }
+    async write(scope, rec, opId) {
+        const known = await this.#readOp(scope, opId);
+        if (known) {
+            const existing = await this.get(scope, known);
+            if (existing) {
+                return existing;
+            }
+        }
+        const now = new Date().toISOString();
+        const record = {
+            id: randomUUID(),
+            scope,
+            kind: rec.kind ?? 'fact',
+            text: rec.text,
+            metadata: rec.metadata,
+            createdAt: now,
+            updatedAt: now,
+            revision: 1,
+        };
+        await this.#writeRecord(record);
+        await this.#writeOp(scope, opId, record.id);
+        return record;
+    }
+    async update(scope, id, patch, opId) {
+        const cur = await this.get(scope, id);
+        if (!cur) {
+            throw new Error(`memory record not found: ${scope}/${id}`);
+        }
+        if ((await this.#readOp(scope, opId)) === id) {
+            return cur;
+        }
+        if (patch.expectedRevision !== undefined && patch.expectedRevision !== cur.revision) {
+            throw new Error(`memory conflict on ${scope}/${id}: expected revision ` +
+                `${patch.expectedRevision}, found ${cur.revision}`);
+        }
+        const next = {
+            ...cur,
+            kind: patch.kind ?? cur.kind,
+            text: patch.text ?? cur.text,
+            metadata: patch.metadata ?? cur.metadata,
+            updatedAt: new Date().toISOString(),
+            revision: cur.revision + 1,
+        };
+        await this.#writeRecord(next);
+        await this.#writeOp(scope, opId, id);
+        return next;
+    }
+    async delete(scope, id, opId) {
+        await rm(this.#recordPath(scope, id), { force: true });
+        await this.#writeOp(scope, opId, id);
+    }
+    // --- layout -----------------------------------------------------------
+    /**
+     * Percent-encoding is reversible and, with dots escaped too, cannot
+     * produce a traversal segment out of a scope like `../etc`.
+     */
+    #scopeDir(scope) {
+        return join(this.#dir, encodeURIComponent(scope).replace(/\./g, '%2E'));
+    }
+    #recordPath(scope, id) {
+        return join(this.#scopeDir(scope), 'records', `${safeId(id, 'record id')}.json`);
+    }
+    #opPath(scope, opId) {
+        return join(this.#scopeDir(scope), 'ops', `${safeId(opId, 'op id')}.json`);
+    }
+    // --- io ---------------------------------------------------------------
+    async #all(scope) {
+        const dir = join(this.#scopeDir(scope), 'records');
+        let names;
+        try {
+            names = await readdir(dir);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                return [];
+            }
+            throw err;
+        }
+        const records = await Promise.all(names
+            .filter((n) => n.endsWith('.json'))
+            .map((n) => this.#readJson(join(dir, n))));
+        return records.filter((r) => r !== undefined);
+    }
+    async #readOp(scope, opId) {
+        const op = await this.#readJson(this.#opPath(scope, opId));
+        return op?.recordId;
+    }
+    async #writeOp(scope, opId, recordId) {
+        await writeJson(this.#opPath(scope, opId), { recordId });
+    }
+    async #writeRecord(record) {
+        await writeJson(join(this.#scopeDir(record.scope), 'scope.json'), { scope: record.scope });
+        await writeJson(this.#recordPath(record.scope, record.id), record);
+    }
+    async #readJson(path) {
+        try {
+            return JSON.parse(await readFile(path, 'utf8'));
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                return undefined;
+            }
+            throw err;
+        }
+    }
+}
+function safeId(value, what) {
+    if (!SAFE_ID.test(value)) {
+        throw new Error(`invalid ${what}: ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+async function writeJson(path, value) {
+    await mkdir(join(path, '..'), { recursive: true });
+    const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    await writeFile(tmp, JSON.stringify(value), 'utf8');
+    try {
+        await rename(tmp, path);
+    }
+    catch (err) {
+        await rm(tmp, { force: true });
+        throw err;
+    }
+}
+//# sourceMappingURL=file.js.map

package/dist/memory-stores/in-memory.d.ts

@@ -0,0 +1,17 @@
+import { type MemoryDraft, type MemoryHit, type MemoryPatch, type MemoryQuery, type MemoryRecord, type MemoryStore } from '../memory.ts';
+/**
+ * Reference implementation: scoped maps plus token-overlap scoring. Good enough
+ * for tests and local runs; production deployments swap in a vector store
+ * without touching the kernel.
+ */
+export declare class InMemoryMemoryStore implements MemoryStore {
+    #private;
+    readonly id: string;
+    constructor(id?: string);
+    search(scope: string, q: MemoryQuery): Promise<MemoryHit[]>;
+    get(scope: string, id: string): Promise<MemoryRecord | undefined>;
+    write(scope: string, rec: MemoryDraft, opId: string): Promise<MemoryRecord>;
+    update(scope: string, id: string, patch: MemoryPatch, opId: string): Promise<MemoryRecord>;
+    delete(scope: string, id: string, opId: string): Promise<void>;
+}
+//# sourceMappingURL=in-memory.d.ts.map

package/dist/memory-stores/in-memory.js

@@ -0,0 +1,80 @@
+import { rankMemories, } from "../memory.js";
+/**
+ * Reference implementation: scoped maps plus token-overlap scoring. Good enough
+ * for tests and local runs; production deployments swap in a vector store
+ * without touching the kernel.
+ */
+export class InMemoryMemoryStore {
+    id;
+    #scopes = new Map();
+    /** opId → record id, so a replayed op returns the original result */
+    #ops = new Map();
+    #seq = 0;
+    constructor(id = 'mem') {
+        this.id = id;
+    }
+    async search(scope, q) {
+        return rankMemories(this.#space(scope).values(), q);
+    }
+    async get(scope, id) {
+        return this.#space(scope).get(id);
+    }
+    async write(scope, rec, opId) {
+        const known = this.#ops.get(opId);
+        if (known) {
+            const existing = this.#space(scope).get(known);
+            if (existing) {
+                return existing;
+            }
+        }
+        const now = new Date().toISOString();
+        const record = {
+            id: `m${++this.#seq}`,
+            scope,
+            kind: rec.kind ?? 'fact',
+            text: rec.text,
+            metadata: rec.metadata,
+            createdAt: now,
+            updatedAt: now,
+            revision: 1,
+        };
+        this.#space(scope).set(record.id, record);
+        this.#ops.set(opId, record.id);
+        return record;
+    }
+    async update(scope, id, patch, opId) {
+        const space = this.#space(scope);
+        const cur = space.get(id);
+        if (!cur) {
+            throw new Error(`memory record not found: ${scope}/${id}`);
+        }
+        if (this.#ops.get(opId) === id) {
+            return cur;
+        }
+        if (patch.expectedRevision !== undefined && patch.expectedRevision !== cur.revision) {
+            throw new Error(`memory conflict on ${scope}/${id}: expected revision ` +
+                `${patch.expectedRevision}, found ${cur.revision}`);
+        }
+        const next = {
+            ...cur,
+            kind: patch.kind ?? cur.kind,
+            text: patch.text ?? cur.text,
+            metadata: patch.metadata ?? cur.metadata,
+            updatedAt: new Date().toISOString(),
+            revision: cur.revision + 1,
+        };
+        space.set(id, next);
+        this.#ops.set(opId, id);
+        return next;
+    }
+    async delete(scope, id, opId) {
+        this.#space(scope).delete(id);
+        this.#ops.set(opId, id);
+    }
+    #space(scope) {
+        const s = this.#scopes.get(scope) ?? new Map();
+        this.#scopes.set(scope, s);
+        return s;
+    }
+}
+//# sourceMappingURL=in-memory.js.map

package/dist/memory-stores/index.d.ts

@@ -0,0 +1,4 @@
+export * from './factory.ts';
+export * from './file.ts';
+export * from './in-memory.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/memory-stores/index.js

@@ -0,0 +1,5 @@
+// Backends for the `MemoryStore` contract in `../memory.ts`.
+export * from "./factory.js";
+export * from "./file.js";
+export * from "./in-memory.js";
+//# sourceMappingURL=index.js.map