@zenera/neo 1.1.11 → 1.1.14

package/dist/memory-stores/file.js

@@ -1,174 +0,0 @@
-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

@@ -1,17 +0,0 @@
-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

@@ -1,80 +0,0 @@
-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

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

package/dist/memory-stores/index.js

@@ -1,5 +0,0 @@
-// 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

@@ -1,115 +0,0 @@
-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

package/dist/memory.js

@@ -1,213 +0,0 @@
-import { hash } from "./payload.js";
-import { MEMORY_DELETE_TOOL, MEMORY_SEARCH_TOOL, MEMORY_UPDATE_TOOL, MEMORY_WRITE_TOOL, tool, withEffects, } from "./types.js";
-export function memoryOpId(runId, callId) {
-    return hash(`${runId}\u0000${callId}`);
-}
-export function renderMemories(hits) {
-    if (!hits.length) {
-        return '';
-    }
-    const lines = hits.map((h) => `- [${h.record.id}] (${h.record.kind}, score ${h.score.toFixed(2)}) ${h.record.text}`);
-    return `Relevant memories:\n${lines.join('\n')}`;
-}
-// ---------------------------------------------------------------------------
-// Shared ranking
-// ---------------------------------------------------------------------------
-/**
- * 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 function rankMemories(records, q) {
-    const limit = q.limit ?? 8;
-    const terms = tokenize(q.text ?? '');
-    const hits = [];
-    for (const rec of records) {
-        if (q.kind && rec.kind !== q.kind) {
-            continue;
-        }
-        if (q.filter && !matches(rec.metadata, q.filter)) {
-            continue;
-        }
-        const score = terms.length ? overlap(terms, tokenize(rec.text)) : 1;
-        if (score <= 0 || (q.minScore !== undefined && score < q.minScore)) {
-            continue;
-        }
-        hits.push({ record: rec, score });
-    }
-    return hits.sort((a, b) => b.score - a.score).slice(0, limit);
-}
-function tokenize(v) {
-    return v
-        .toLowerCase()
-        .split(/[^a-z0-9]+/)
-        .filter((t) => t.length > 2);
-}
-function overlap(a, b) {
-    const set = new Set(b);
-    const shared = a.filter((t) => set.has(t)).length;
-    return a.length ? shared / a.length : 0;
-}
-function matches(meta, filter) {
-    return Object.entries(filter).every(([k, v]) => meta?.[k] === v);
-}
-// ---------------------------------------------------------------------------
-// Built-in memory tools
-// ---------------------------------------------------------------------------
-function spaceParam(bindings) {
-    return bindings.length > 1
-        ? { type: 'string', enum: bindings.map((b) => b.scope), description: 'memory space' }
-        : undefined;
-}
-function pick(bindings, space) {
-    const b = space ? bindings.find((x) => x.scope === space) : bindings[0];
-    if (!b) {
-        throw new Error(`unknown memory space: ${space ?? '(default)'}`);
-    }
-    return b;
-}
-/**
- * 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 function memoryTools(bindings) {
-    if (!bindings.length) {
-        return [];
-    }
-    const writable = bindings.filter((b) => b.access === 'read-write');
-    const space = spaceParam(bindings);
-    const withSpace = (props) => (space ? { ...props, space } : props);
-    const tools = [
-        tool({
-            name: MEMORY_SEARCH_TOOL,
-            description: 'Search long-lived memories.',
-            parameters: {
-                type: 'object',
-                properties: withSpace({
-                    query: { type: 'string' },
-                    kind: { type: 'string' },
-                    limit: { type: 'integer' },
-                }),
-                required: ['query'],
-                additionalProperties: false,
-            },
-            execute: async (args, tc) => {
-                const b = pick(bindings, args.space);
-                const store = tc.services.memoryStore(b.store);
-                const hits = await store.search(b.scope, {
-                    text: args.query,
-                    kind: args.kind,
-                    limit: args.limit,
-                });
-                return hits.map((h) => ({
-                    id: h.record.id,
-                    kind: h.record.kind,
-                    text: h.record.text,
-                    revision: h.record.revision,
-                    score: Number(h.score.toFixed(3)),
-                }));
-            },
-        }),
-    ];
-    if (!writable.length) {
-        return tools;
-    }
-    const wSpace = spaceParam(writable);
-    const withWSpace = (props) => wSpace ? { ...props, space: wSpace } : props;
-    tools.push(tool({
-        name: MEMORY_WRITE_TOOL,
-        description: 'Store a new long-lived memory.',
-        parameters: {
-            type: 'object',
-            properties: withWSpace({ text: { type: 'string' }, kind: { type: 'string' } }),
-            required: ['text'],
-            additionalProperties: false,
-        },
-        execute: async (args, tc) => {
-            const b = pick(writable, args.space);
-            const opId = memoryOpId(tc.state.runId, tc.callId);
-            const rec = await tc.services
-                .memoryStore(b.store)
-                .write(b.scope, { text: args.text, kind: args.kind }, opId);
-            return withEffects(`stored memory ${rec.id}`, {
-                kind: 'memory_op',
-                spec: {
-                    kind: 'op',
-                    op: 'write',
-                    store: b.store,
-                    scope: b.scope,
-                    opId,
-                    recordId: rec.id,
-                    revision: rec.revision,
-                    after: rec.text,
-                },
-            });
-        },
-    }), tool({
-        name: MEMORY_UPDATE_TOOL,
-        description: 'Update an existing memory by id.',
-        parameters: {
-            type: 'object',
-            properties: withWSpace({
-                id: { type: 'string' },
-                text: { type: 'string' },
-                kind: { type: 'string' },
-            }),
-            required: ['id'],
-            additionalProperties: false,
-        },
-        execute: async (args, tc) => {
-            const b = pick(writable, args.space);
-            const store = tc.services.memoryStore(b.store);
-            const before = await store.get(b.scope, args.id);
-            const opId = memoryOpId(tc.state.runId, tc.callId);
-            const rec = await store.update(b.scope, args.id, { text: args.text, kind: args.kind }, opId);
-            return withEffects(`updated memory ${rec.id}`, {
-                kind: 'memory_op',
-                spec: {
-                    kind: 'op',
-                    op: 'update',
-                    store: b.store,
-                    scope: b.scope,
-                    opId,
-                    recordId: rec.id,
-                    revision: rec.revision,
-                    before: before?.text,
-                    after: rec.text,
-                },
-            });
-        },
-    }), tool({
-        name: MEMORY_DELETE_TOOL,
-        description: 'Delete a memory by id.',
-        parameters: {
-            type: 'object',
-            properties: withWSpace({ id: { type: 'string' } }),
-            required: ['id'],
-            additionalProperties: false,
-        },
-        execute: async (args, tc) => {
-            const b = pick(writable, args.space);
-            const store = tc.services.memoryStore(b.store);
-            const before = await store.get(b.scope, args.id);
-            const opId = memoryOpId(tc.state.runId, tc.callId);
-            await store.delete(b.scope, args.id, opId);
-            return withEffects(`deleted memory ${args.id}`, {
-                kind: 'memory_op',
-                spec: {
-                    kind: 'op',
-                    op: 'delete',
-                    store: b.store,
-                    scope: b.scope,
-                    opId,
-                    recordId: args.id,
-                    revision: before?.revision ?? 0,
-                    before: before?.text,
-                },
-            });
-        },
-    }));
-    return tools;
-}
-//# sourceMappingURL=memory.js.map