@zenera/neo 1.1.26 → 1.1.28

package/README.md

@@ -1,7 +1,17 @@
+<div align="center"> 
+  <img
+    src="https://raw.githubusercontent.com/andreyryabov/ZeneraNeo/main/docs/imgs/zenera-logo-with-media-queries.svg"
+    alt="Zenera Logo"
+    width="20"
+  />
+  <div>Powered By Zenera</div>
+</div>
+<br>
+
 <div align="center">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/andreyryabov/ZeneraNeo/main/docs/imgs/banner-neo-dark.svg">
-  <img src="https://raw.githubusercontent.com/andreyryabov/ZeneraNeo/main/docs/imgs/banner-neo-light.svg" alt="ZENERA NEO" width="720">
+  <img src="https://raw.githubusercontent.com/andreyryabov/ZeneraNeo/main/docs/imgs/banner-neo-with-media-queries.svg" alt="ZENERA NEO" width="720">
 </picture>
 
 [![npm](https://img.shields.io/npm/v/@zenera/neo.svg)](https://www.npmjs.com/package/@zenera/neo)

package/dist/project/config.d.ts

@@ -48,10 +48,10 @@ declare const modelSpec: z.ZodObject<{
     thinkingBudgetTokens: z.ZodOptional<z.ZodInt>;
     thinkingBudget: z.ZodOptional<z.ZodInt>;
     thinkingLevel: z.ZodOptional<z.ZodEnum<{
-        minimal: "minimal";
         low: "low";
         medium: "medium";
         high: "high";
+        minimal: "minimal";
     }>>;
     includeThoughts: z.ZodOptional<z.ZodBoolean>;
     routing: z.ZodOptional<z.ZodObject<{
@@ -163,15 +163,15 @@ declare const sandbox: z.ZodObject<{
     cpus: z.ZodOptional<z.ZodNumber>;
     memory: z.ZodOptional<z.ZodInt>;
     network: z.ZodOptional<z.ZodEnum<{
-        bridge: "bridge";
         none: "none";
         host: "host";
+        bridge: "bridge";
     }>>;
     workdir: z.ZodOptional<z.ZodString>;
     timeout: z.ZodOptional<z.ZodInt>;
     hardening: z.ZodOptional<z.ZodEnum<{
-        standard: "standard";
         strict: "strict";
+        standard: "standard";
     }>>;
     user: z.ZodOptional<z.ZodString>;
     persist: z.ZodOptional<z.ZodBoolean>;
@@ -220,10 +220,10 @@ export declare const projectSchema: z.ZodObject<{
         thinkingBudgetTokens: z.ZodOptional<z.ZodInt>;
         thinkingBudget: z.ZodOptional<z.ZodInt>;
         thinkingLevel: z.ZodOptional<z.ZodEnum<{
-            minimal: "minimal";
             low: "low";
             medium: "medium";
             high: "high";
+            minimal: "minimal";
         }>>;
         includeThoughts: z.ZodOptional<z.ZodBoolean>;
         routing: z.ZodOptional<z.ZodObject<{
@@ -293,15 +293,15 @@ export declare const projectSchema: z.ZodObject<{
         cpus: z.ZodOptional<z.ZodNumber>;
         memory: z.ZodOptional<z.ZodInt>;
         network: z.ZodOptional<z.ZodEnum<{
-            bridge: "bridge";
             none: "none";
             host: "host";
+            bridge: "bridge";
         }>>;
         workdir: z.ZodOptional<z.ZodString>;
         timeout: z.ZodOptional<z.ZodInt>;
         hardening: z.ZodOptional<z.ZodEnum<{
-            standard: "standard";
             strict: "strict";
+            standard: "standard";
         }>>;
         user: z.ZodOptional<z.ZodString>;
         persist: z.ZodOptional<z.ZodBoolean>;
@@ -325,8 +325,8 @@ export declare const projectSchema: z.ZodObject<{
             provider: z.ZodOptional<z.ZodString>;
             discovery: z.ZodDefault<z.ZodEnum<{
                 none: "none";
-                index: "index";
                 search: "search";
+                index: "index";
             }>>;
             allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
             preload: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -357,15 +357,15 @@ export declare const projectSchema: z.ZodObject<{
             cpus: z.ZodOptional<z.ZodNumber>;
             memory: z.ZodOptional<z.ZodInt>;
             network: z.ZodOptional<z.ZodEnum<{
-                bridge: "bridge";
                 none: "none";
                 host: "host";
+                bridge: "bridge";
             }>>;
             workdir: z.ZodOptional<z.ZodString>;
             timeout: z.ZodOptional<z.ZodInt>;
             hardening: z.ZodOptional<z.ZodEnum<{
-                standard: "standard";
                 strict: "strict";
+                standard: "standard";
             }>>;
             user: z.ZodOptional<z.ZodString>;
             persist: z.ZodOptional<z.ZodBoolean>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/neo",
-    "version": "1.1.26",
+    "version": "1.1.28",
     "description": "A multi-agent runtime for Node.js: agents, models, tools, skills, memory and an append-only trajectory.",
     "keywords": [
         "agents",

package/dist/memory/instructions.d.ts

@@ -1,15 +0,0 @@
-import { type MemoryNode, type ResolvedMemoryBinding } from './types.ts';
-export declare const PREFERENCES_TAG = "memory-preferences";
-/**
- * Deliberately not a function of `sees`: those labels come from the run's
- * context, and naming them here would rewrite the prompt whenever the context
- * moved. It also tells an agent the shape of a slice it was not given.
- */
-export declare function memoryInstructions(binding: ResolvedMemoryBinding): string;
-/**
- * The id on each line is what makes a preference revisable rather than merely
- * readable: without it the model can read the instruction but cannot name the
- * thing it would supersede.
- */
-export declare function renderPreferences(nodes: readonly MemoryNode[]): string;
-//# sourceMappingURL=instructions.d.ts.map

package/dist/memory/instructions.js

@@ -1,103 +0,0 @@
-import { MEMORY_COMMIT_TOOL, MEMORY_FORGET_TOOL, MEMORY_LOAD_TOOL, MEMORY_SEARCH_TOOL, } from "../types.js";
-import { RECOLLECTION_TAG } from "./render.js";
-import { canForget, canWrite } from "./types.js";
-// ---------------------------------------------------------------------------
-// Teaching the model to read and write memory
-//
-// The tool schemas say what the arguments are; none of them says when a thing
-// is worth remembering, or that a recollection is a subgraph rather than a
-// ranked list. That is policy, it is the same for every agent, and it belongs
-// in the system prompt — which is also the only place it can be stated once
-// per run instead of once per call.
-//
-// Both halves go in through `composePrompt`'s `derived` array, so they sit in
-// the cacheable prefix and are recorded in the `system_prompt` node like every
-// other part of what the model read.
-//
-// The text is gated on the binding, not on the project: an agent that cannot
-// write is never told how to commit. A rule it cannot act on is a rule it can
-// only be confused by, and an unusable tool name in the prompt invites a call
-// that will be refused.
-// ---------------------------------------------------------------------------
-export const PREFERENCES_TAG = 'memory-preferences';
-/**
- * Deliberately not a function of `sees`: those labels come from the run's
- * context, and naming them here would rewrite the prompt whenever the context
- * moved. It also tells an agent the shape of a slice it was not given.
- */
-export function memoryInstructions(binding) {
-    const parts = [READING];
-    if (canWrite(binding)) {
-        parts.push(WRITING);
-    }
-    if (canForget(binding)) {
-        parts.push(FORGETTING);
-    }
-    return parts.join('\n\n');
-}
-const READING = `Memory is a graph shared with other agents, and it outlives this run.
-
-A <${RECOLLECTION_TAG}> block is a subgraph, not a ranked list — the links are
-as much of the answer as the nodes. It is an outline, and the indentation is
-the graph. A line at the left margin reads \`score kind id\` and is something
-the search matched. A line indented under it reads \`<arrow>relation kind id\`
-and is a neighbour: \`\u2192produced\` means the line above produced this one,
-\`\u2190informed\` means this one informed the line above. A neighbour the
-search matched in its own right carries a score too, after the arrow. Under
-each header, indented further, is that node's text — and for a \`file\`, the
-path under /memory you can open or run, its size and how often it has been read.
-
-A line beginning \`+\` is a link to an id already shown above, for an edge the
-outline could not nest. Text is clipped: copy an id into \`${MEMORY_LOAD_TOOL}\`
-to read a node whole. \`${MEMORY_SEARCH_TOOL}\` finds ids, it does not return
-contents.
-
-You see part of the graph, not all of it. Finding nothing means nothing you can
-see, not that it never happened.`;
-const WRITING = `Commit when a run produced something a later run would otherwise have to work
-out again: a script that ran, an interface that behaved differently from its
-documentation, a call sequence that turned out to be necessary. Commit it in
-one \`${MEMORY_COMMIT_TOOL}\` call — the artifact and what explains it are one
-memory, and splitting them leaves a later run holding a script with no idea why
-it exists.
-
-Do not commit the request restated, progress notes, anything you have not
-verified, or anything a search already returned. A node that says what one
-already in memory says is folded into it and its existing id comes back under
-your ref, so the links you asked for still land — on the memory that was
-already there.
-
-Never edit a memory to correct it. Add the new one and link it to the old with
-SUPERSEDES; the wrong answer is evidence too, and the link is what hides it
-from later recalls without destroying the history.
-
-Commit a preference only when the user's own words generalise — "always", "from
-now on", "I prefer", "never". A single request being fulfilled is not a
-standing instruction.`;
-const FORGETTING = `Forget only what is wrong and has no successor. A superseded memory is already
-hidden from recall and should stay for the history, so \`${MEMORY_FORGET_TOOL}\`
-is for what should never have been written, not for what has been replaced.`;
-/**
- * The id on each line is what makes a preference revisable rather than merely
- * readable: without it the model can read the instruction but cannot name the
- * thing it would supersede.
- */
-export function renderPreferences(nodes) {
-    if (!nodes.length) {
-        return '';
-    }
-    const lines = nodes.map((n) => `- ${oneLine(n.text)} [${n.id}]`);
-    return [
-        `<${PREFERENCES_TAG}>`,
-        "Standing instructions from earlier runs. They apply unless this run's",
-        'request contradicts them; to change one, commit the replacement and link',
-        'it to the id here with SUPERSEDES.',
-        ...lines,
-        `</${PREFERENCES_TAG}>`,
-    ].join('\n');
-}
-/** Never clipped: half an instruction is a different instruction. */
-function oneLine(text) {
-    return text.replace(/\s+/g, ' ').trim();
-}
-//# sourceMappingURL=instructions.js.map

package/dist/memory/match.d.ts

@@ -1,18 +0,0 @@
-/** Long enough for any honest pattern, short enough to bound a bad one. */
-export declare const MAX_PATTERN = 200;
-export declare class PatternError extends Error {
-}
-export interface MatchOptions {
-    /** read the pattern as a regular expression rather than as a literal */
-    regex?: boolean;
-    caseSensitive?: boolean;
-}
-/** The offset of the first match in `text`, or -1. */
-export type Matcher = (text: string) => number;
-/**
- * A finder over a string. Literal by default: someone typing `user.id` means
- * those seven characters, and a dot that quietly matched anything would be a
- * worse answer than no answer.
- */
-export declare function matcher(pattern: string, options?: MatchOptions): Matcher;
-//# sourceMappingURL=match.d.ts.map

package/dist/memory/match.js

@@ -1,61 +0,0 @@
-// ---------------------------------------------------------------------------
-// Matching, with nothing learned in between
-//
-// Everything here is exact. A substring is a substring, which is the whole
-// point of the surface built on it: the vector index answers "what is near
-// this", and near is a ranking, so it can only ever return the top of a list.
-// When the question is "does the word `password` appear anywhere at all", a
-// ranking is the wrong instrument and no amount of tuning makes it the right
-// one.
-//
-// This is a copy of `common/match.ts` in @zenera/rag, and has to be: the
-// dependency runs rag → cli → neo, so neo importing rag would close a cycle.
-// Two differences earn their place rather than being drift. A matcher returns
-// the offset it matched at, because grep reports *where*, not merely whether;
-// and there are no globs, because the haystack here is prose and a glob is
-// anchored to the whole string, so `error*` would match a line only when the
-// line began with the word.
-//
-// A pattern may arrive from a model, so a regex is a bounded promise: the
-// length is capped here and the scan that uses it keeps a deadline.
-// ---------------------------------------------------------------------------
-/** Long enough for any honest pattern, short enough to bound a bad one. */
-export const MAX_PATTERN = 200;
-export class PatternError extends Error {
-}
-/**
- * A finder over a string. Literal by default: someone typing `user.id` means
- * those seven characters, and a dot that quietly matched anything would be a
- * worse answer than no answer.
- */
-export function matcher(pattern, options = {}) {
-    guard(pattern);
-    if (!options.regex) {
-        if (options.caseSensitive) {
-            return (text) => text.indexOf(pattern);
-        }
-        const needle = pattern.toLowerCase();
-        return (text) => text.toLowerCase().indexOf(needle);
-    }
-    const expression = compile(pattern, options.caseSensitive ? '' : 'i');
-    // `lastIndex` is not carried between calls: the flags never include `g`.
-    return (text) => text.search(expression);
-}
-// ---------------------------------------------------------------------------
-function guard(pattern) {
-    if (pattern.length === 0) {
-        throw new PatternError('the pattern is empty');
-    }
-    if (pattern.length > MAX_PATTERN) {
-        throw new PatternError(`the pattern is longer than ${MAX_PATTERN} characters`);
-    }
-}
-function compile(source, flags) {
-    try {
-        return new RegExp(source, flags);
-    }
-    catch (err) {
-        throw new PatternError(`invalid pattern: ${err.message}`);
-    }
-}
-//# sourceMappingURL=match.js.map

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

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

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

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

@@ -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