@zenera/neo 1.1.0

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

package/dist/memory.d.ts

@@ -0,0 +1,115 @@
+import { type AnyTool } from './types.ts';
+export interface MemoryRecord {
+    id: string;
+    /** memory space this record belongs to */
+    scope: string;
+    /** app-defined: 'fact' | 'preference' | 'episode' | … */
+    kind: string;
+    text: string;
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+    /** optimistic-concurrency token */
+    revision: number;
+}
+export interface MemoryDraft {
+    kind?: string;
+    text: string;
+    metadata?: Record<string, unknown>;
+}
+export interface MemoryPatch {
+    kind?: string;
+    text?: string;
+    metadata?: Record<string, unknown>;
+    /** when given, the update fails unless the stored revision matches */
+    expectedRevision?: number;
+}
+export interface MemoryQuery {
+    /** semantic query; omitted ⇒ pure filter listing */
+    text?: string;
+    filter?: Record<string, unknown>;
+    kind?: string;
+    limit?: number;
+    minScore?: number;
+}
+export interface MemoryHit {
+    record: MemoryRecord;
+    /** 0..1, backend-normalized */
+    score: number;
+}
+/**
+ * Embedding generation is the store's business, not the kernel's: a pgvector
+ * implementation embeds inside `write`/`search`, the in-memory one below falls
+ * back to token overlap. The kernel never sees vectors.
+ */
+export interface MemoryStore {
+    readonly id: string;
+    search(scope: string, q: MemoryQuery): Promise<MemoryHit[]>;
+    get(scope: string, id: string): Promise<MemoryRecord | undefined>;
+    /** `opId` makes writes idempotent under retry/replay */
+    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>;
+}
+export interface MemoryBinding<TCtx = unknown> {
+    /** MemoryStore id */
+    store: string;
+    /** namespace; default `agent:${agent.name}`. A function is resolved per run. */
+    scope?: string | ((ctx: TCtx) => string);
+    access: 'read' | 'read-write';
+    /** inject top-k matches before an LLM call */
+    autoRecall?: {
+        query: 'last_user_input' | 'none';
+        limit: number;
+    };
+}
+/** A binding with its scope already resolved against the run context. */
+export interface ResolvedBinding {
+    store: string;
+    scope: string;
+    access: 'read' | 'read-write';
+    autoRecall?: {
+        query: 'last_user_input' | 'none';
+        limit: number;
+    };
+}
+export interface MemoryRecallSpec {
+    kind: 'recall';
+    store: string;
+    scope: string;
+    query: MemoryQuery;
+    hits: {
+        id: string;
+        score: number;
+        revision: number;
+    }[];
+    /** the rendered block the model actually saw */
+    content: string;
+}
+export interface MemoryOpSpec {
+    kind: 'op';
+    op: 'write' | 'update' | 'delete';
+    store: string;
+    scope: string;
+    /** sha256(runId, callId) — deterministic, so replay re-issues the same write */
+    opId: string;
+    recordId: string;
+    revision: number;
+    before?: string;
+    after?: string;
+}
+export declare function memoryOpId(runId: string, callId: string): string;
+export declare function renderMemories(hits: MemoryHit[]): string;
+/**
+ * Filtering plus token-overlap scoring, shared by the backends that have no
+ * embeddings of their own. A vector store ignores this and ranks in the
+ * database instead — the kernel only ever sees `MemoryHit[]`.
+ */
+export declare function rankMemories(records: Iterable<MemoryRecord>, q: MemoryQuery): MemoryHit[];
+/**
+ * Memory is reachable both explicitly (these tools) and implicitly (auto-recall
+ * in the runner). Both land in the trajectory; only the explicit path is
+ * visible to the model as a tool.
+ */
+export declare function memoryTools<TCtx>(bindings: ResolvedBinding[]): AnyTool<TCtx>[];
+//# sourceMappingURL=memory.d.ts.map