@zenera/neo 1.1.10 → 1.1.12

package/dist/memory/types.d.ts

@@ -0,0 +1,192 @@
+/**
+ * The built-in vocabulary. A kind earns its place only when ranking, rendering
+ * or loading branches on it — anything else is free text wearing an enum
+ * costume, and it costs the model accuracy when it has to choose one.
+ *
+ * A project may declare its own set (`memory.kinds` in the config), which
+ * *replaces* this one; the tool schema is built from the result, so the
+ * provider constrains decoding to labels that actually exist.
+ *
+ * `preference` is the exception, and `MemoryIndex` re-adds it to whatever a
+ * project declares: the engine itself reads that kind to build the system
+ * prompt, so a project able to define it away would silently lose the feature
+ * rather than opt out of it.
+ */
+export declare const MEMORY_KINDS: readonly ["task", "plan", "fact", "snippet", "file", "operation", "preference"];
+export type MemoryKind = (typeof MEMORY_KINDS)[number];
+export declare const KIND_HELP: Readonly<Record<MemoryKind, string>>;
+/**
+ * Four relations, and only `SUPERSEDES` changes a traversal: recall follows it
+ * forward and drops what it points at, so a corrected artifact hides the one it
+ * replaced without deleting the history. The other three shape which tier of
+ * the budget a node is pulled in on, and read as prose in the rendered graph.
+ *
+ * `SUPERSEDES` itself never reaches the renderer on the ordinary path — recall
+ * drops the node it points at, so the edge has no second endpoint to draw. It
+ * appears only under `stale`, which is the audit view.
+ */
+export declare const MEMORY_RELATIONS: readonly ["PRODUCED", "INFORMED", "CALLS", "SUPERSEDES"];
+export type Relation = (typeof MEMORY_RELATIONS)[number];
+export declare const RELATION_HELP: Readonly<Record<Relation, string>>;
+/**
+ * The relations that carry the work forward, as opposed to the ones that merely
+ * supply context. Recall walks these first when spending its budget, and the
+ * renderer prefers them when a node has more than one branch it could hang from.
+ */
+export declare const SPINE_RELATIONS: ReadonlySet<string>;
+/** An audience label every agent holds implicitly. */
+export declare const ALL_AGENTS = "*";
+/** Read by the engine, not just by the model: it becomes part of the system prompt. */
+export declare const PREFERENCE_KIND = "preference";
+/**
+ * `hint` is the recovery step, kept separate from the message because the tool
+ * layer returns both to the model as `{error, hint}` rather than throwing.
+ */
+export declare class MemoryError extends Error {
+    readonly hint?: string;
+    constructor(message: string, hint?: string);
+}
+export interface MemoryFile {
+    /** what the agent sees, e.g. `/memory/01J8….py` — a mount path, not a host path */
+    path: string;
+    bytes: number;
+    sha256: string;
+    /** extension without the dot, '' when there was none */
+    format: string;
+}
+export interface MemoryNode {
+    id: string;
+    kind: string;
+    /** the searchable, embeddable summary — the only text that is ranked */
+    text: string;
+    /** who may see this node; `['*']` is everyone */
+    audience: string[];
+    createdAt: string;
+    updatedAt: string;
+    /** last time a `memory_load` returned it; the input to recency decay */
+    lastUsedAt: string;
+    useCount: number;
+    /** optimistic-concurrency token */
+    revision: number;
+    metadata?: Record<string, unknown>;
+    file?: MemoryFile;
+}
+/** Graphology holds source and target itself, so they are not attributes. */
+export interface MemoryEdgeAttrs {
+    relation: Relation;
+    createdAt: string;
+    /** narrower than either endpoint when set; usually absent */
+    audience?: string[];
+}
+export interface MemoryEdge {
+    source: string;
+    target: string;
+    relation: Relation;
+}
+export interface MemoryQuery {
+    /** semantic query; omitted means a pure filter listing */
+    text?: string;
+    kinds?: string[];
+    /** how many seed nodes the ranker returns before the graph is stitched */
+    limit?: number;
+    maxHops?: number;
+    maxNodes?: number;
+    /** ISO timestamp; nodes created before it are excluded */
+    newerThan?: string;
+    minScore?: number;
+}
+/**
+ * The edge a stitched node was reached by. A recollection renders as a tree,
+ * and this is the branch each node hangs from; the edges left over once every
+ * node has used its own are the ones the tree cannot carry.
+ */
+export interface NodeVia {
+    from: string;
+    relation: Relation;
+    /** the edge runs from `from` to this node rather than back the other way */
+    outbound: boolean;
+}
+export interface ScoredNode {
+    node: MemoryNode;
+    score: number;
+    /** the ranker found this one; everything else is here to connect it */
+    seed: boolean;
+    /** absent on a seed: nothing reached it, it was the reason for the walk */
+    via?: NodeVia;
+}
+export interface Recollection {
+    nodes: ScoredNode[];
+    edges: MemoryEdge[];
+    /** ids of the seeds, in rank order */
+    seeds: string[];
+    /** nodes were dropped to stay inside the budget */
+    truncated: boolean;
+}
+export type MemoryAccess = 'read' | 'read-write' | 'full';
+/**
+ * `sees` and `writes` are the mask, and they are resolved from config before a
+ * tool is ever built. Neither is a tool parameter: an agent that could name its
+ * own audience could read another agent's slice just by asking.
+ */
+export interface MemoryBinding<TCtx = unknown> {
+    access: MemoryAccess;
+    /** audience labels this agent may read; `'*'` is implicit */
+    sees?: string[] | ((ctx: TCtx) => string[]);
+    /** labels it may write; defaults to `['*']` */
+    writes?: string[];
+    autoRecall?: AutoRecall;
+}
+export interface AutoRecall {
+    query: 'last_user_input' | 'none';
+    limit: number;
+}
+export interface ResolvedMemoryBinding {
+    access: MemoryAccess;
+    sees: string[];
+    writes: string[];
+    autoRecall?: AutoRecall;
+}
+export declare const canWrite: (b: ResolvedMemoryBinding) => boolean;
+export declare const canForget: (b: ResolvedMemoryBinding) => boolean;
+/**
+ * What a tool did, in the form the trajectory keeps it. Ids and counts only —
+ * the prose lives in a payload, so a replay can be reasoned about without
+ * rehydrating every body.
+ */
+export interface MemoryRecallSpec {
+    kind: 'recall';
+    query: MemoryQuery;
+    /** the matches; the rest of `nodes` is stitched context */
+    seeds: string[];
+    nodes: {
+        id: string;
+        kind: string;
+        score: number;
+    }[];
+    edges: MemoryEdge[];
+    /** the rendered block the model actually saw */
+    content: string;
+}
+export interface MemoryOpSpec {
+    kind: 'op';
+    op: 'commit' | 'forget';
+    /** sha256(runId, callId) — deterministic, so a replay is deduplicated */
+    opId: string;
+    /** nodes this op created, changed or removed */
+    nodes: {
+        id: string;
+        kind: string;
+        revision: number;
+    }[];
+    edges: MemoryEdge[];
+    /** remembered files copied in, or bytes dropped */
+    files: number;
+}
+/**
+ * Deny by default: a node is visible when it is public, or when the reader
+ * holds one of the labels it carries.
+ */
+export declare function visible(node: MemoryNode, sees: readonly string[]): boolean;
+/** An edge needs both endpoints visible before its own labels are consulted. */
+export declare function edgeVisible(attrs: MemoryEdgeAttrs, sees: readonly string[]): boolean;
+//# sourceMappingURL=types.d.ts.map

package/dist/memory/types.js

@@ -0,0 +1,105 @@
+// ---------------------------------------------------------------------------
+// Memory — knowledge that outlives a run (the trajectory is one run's record)
+//
+// A graph, not a list of records. The reason is the shape of what is worth
+// remembering: a script an agent wrote is useless without the request that
+// asked for it, the plan that shaped it and the endpoint it calls, and those
+// four things are one memory even though they are four pieces of text. A store
+// that can only return a ranked list of rows leaves the joining to the model,
+// every single time.
+//
+// Every node is timed. `createdAt` is provenance, but `lastUsedAt` is what
+// ranking actually leans on: memory that keeps proving useful should surface
+// ahead of memory that was written once and never read, and neither an
+// embedding nor an edge can tell you that.
+//
+// Visibility is per node, by label, denied by default. One graph serves every
+// agent in a project; `audience` decides which of them may see a node at all.
+// A second user is a second graph, not a second label: `audience` is about
+// which agent may read a node, never about whose memory it is.
+// ---------------------------------------------------------------------------
+/**
+ * The built-in vocabulary. A kind earns its place only when ranking, rendering
+ * or loading branches on it — anything else is free text wearing an enum
+ * costume, and it costs the model accuracy when it has to choose one.
+ *
+ * A project may declare its own set (`memory.kinds` in the config), which
+ * *replaces* this one; the tool schema is built from the result, so the
+ * provider constrains decoding to labels that actually exist.
+ *
+ * `preference` is the exception, and `MemoryIndex` re-adds it to whatever a
+ * project declares: the engine itself reads that kind to build the system
+ * prompt, so a project able to define it away would silently lose the feature
+ * rather than opt out of it.
+ */
+export const MEMORY_KINDS = [
+    'task',
+    'plan',
+    'fact',
+    'snippet',
+    'file',
+    'operation',
+    'preference',
+];
+export const KIND_HELP = {
+    task: 'a request that started a piece of work',
+    plan: 'an approach that worked, worth reusing on a similar request',
+    fact: 'a durable truth about the environment or the domain',
+    snippet: 'a short piece of code or configuration, too small to be a file',
+    file: 'an artifact kept whole under /memory and re-runnable',
+    operation: 'an external call that was made — an endpoint, command or query',
+    preference: 'a standing instruction from the user that applies to every run',
+};
+/**
+ * Four relations, and only `SUPERSEDES` changes a traversal: recall follows it
+ * forward and drops what it points at, so a corrected artifact hides the one it
+ * replaced without deleting the history. The other three shape which tier of
+ * the budget a node is pulled in on, and read as prose in the rendered graph.
+ *
+ * `SUPERSEDES` itself never reaches the renderer on the ordinary path — recall
+ * drops the node it points at, so the edge has no second endpoint to draw. It
+ * appears only under `stale`, which is the audit view.
+ */
+export const MEMORY_RELATIONS = ['PRODUCED', 'INFORMED', 'CALLS', 'SUPERSEDES'];
+export const RELATION_HELP = {
+    PRODUCED: 'the source led to the target being made (task -> artifact)',
+    INFORMED: 'the source was context the target was built from',
+    CALLS: 'the source invokes the target',
+    SUPERSEDES: 'the source replaces the target; the target is stale',
+};
+/**
+ * The relations that carry the work forward, as opposed to the ones that merely
+ * supply context. Recall walks these first when spending its budget, and the
+ * renderer prefers them when a node has more than one branch it could hang from.
+ */
+export const SPINE_RELATIONS = new Set(['PRODUCED', 'CALLS', 'SUPERSEDES']);
+/** An audience label every agent holds implicitly. */
+export const ALL_AGENTS = '*';
+/** Read by the engine, not just by the model: it becomes part of the system prompt. */
+export const PREFERENCE_KIND = 'preference';
+/**
+ * `hint` is the recovery step, kept separate from the message because the tool
+ * layer returns both to the model as `{error, hint}` rather than throwing.
+ */
+export class MemoryError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.name = 'MemoryError';
+        this.hint = hint;
+    }
+}
+export const canWrite = (b) => b.access !== 'read';
+export const canForget = (b) => b.access === 'full';
+/**
+ * Deny by default: a node is visible when it is public, or when the reader
+ * holds one of the labels it carries.
+ */
+export function visible(node, sees) {
+    return node.audience.some((a) => a === ALL_AGENTS || sees.includes(a));
+}
+/** An edge needs both endpoints visible before its own labels are consulted. */
+export function edgeVisible(attrs, sees) {
+    return (!attrs.audience?.length || attrs.audience.some((a) => a === ALL_AGENTS || sees.includes(a)));
+}
+//# sourceMappingURL=types.js.map

package/dist/memory/vectors.d.ts

@@ -0,0 +1,29 @@
+export interface Scored {
+    id: string;
+    score: number;
+}
+export declare class VectorBlock {
+    #private;
+    constructor(dims: number, capacity?: number);
+    get dims(): number;
+    get rows(): number;
+    get ids(): readonly string[];
+    has(id: string): boolean;
+    set(id: string, vector: ArrayLike<number>): void;
+    remove(id: string): boolean;
+    /** Exact kNN over the rows `allow` accepts. Ties break toward the earlier row. */
+    topK(query: ArrayLike<number>, k: number, allow?: (id: string) => boolean): Scored[];
+    /** The raw block, trimmed to the rows in use — what goes to disk. */
+    bytes(): Float32Array;
+    static load(dims: number, ids: readonly string[], data: Float32Array): VectorBlock;
+}
+export declare function tokenize(v: string): string[];
+export declare function overlap(a: readonly string[], b: readonly string[]): number;
+/** Half-life in days: how fast a memory nobody reads falls behind one that is read. */
+export declare const DECAY_HALF_LIFE_DAYS = 30;
+/**
+ * Multiplied into similarity, never added: a stale exact match should still beat
+ * a fresh irrelevant one, so decay narrows the field rather than reordering it.
+ */
+export declare function recencyDecay(lastUsedAt: string, now: number): number;
+//# sourceMappingURL=vectors.d.ts.map

package/dist/memory/vectors.js

@@ -0,0 +1,152 @@
+// ---------------------------------------------------------------------------
+// Vectors — a dense block and a linear scan
+//
+// No vector database. At the scale agent memory actually reaches — tens of
+// thousands of nodes at the very outside — an exact scan over one contiguous
+// Float32Array beats an approximate index that costs a native dependency, and
+// it is exact, which an ANN index is not. `@zenera/neo` has two runtime
+// dependencies for a reason, and none of them ship a `.node` binary.
+//
+// `Embedder` guarantees unit vectors (`embeddingResponse` normalizes before it
+// returns), so cosine similarity here is a bare dot product. If that guarantee
+// ever moves, this is the file that silently starts lying.
+//
+// Deletion is a swap-remove: the last row moves into the hole. That keeps the
+// block dense — no tombstones, no compaction pass — at the cost of row indices
+// not being stable, which is why nothing outside this file ever holds one.
+// ---------------------------------------------------------------------------
+const GROWTH = 2;
+const INITIAL_ROWS = 64;
+export class VectorBlock {
+    #dims;
+    #ids = [];
+    #index = new Map();
+    #data;
+    #rows = 0;
+    constructor(dims, capacity = INITIAL_ROWS) {
+        this.#dims = dims;
+        this.#data = new Float32Array(Math.max(capacity, 1) * dims);
+    }
+    get dims() {
+        return this.#dims;
+    }
+    get rows() {
+        return this.#rows;
+    }
+    get ids() {
+        return this.#ids;
+    }
+    has(id) {
+        return this.#index.has(id);
+    }
+    set(id, vector) {
+        if (vector.length !== this.#dims) {
+            throw new Error(`expected a ${this.#dims}-dimension vector, got ${vector.length}`);
+        }
+        let row = this.#index.get(id);
+        if (row === undefined) {
+            this.#grow(this.#rows + 1);
+            row = this.#rows++;
+            this.#ids[row] = id;
+            this.#index.set(id, row);
+        }
+        this.#data.set(vector, row * this.#dims);
+    }
+    remove(id) {
+        const row = this.#index.get(id);
+        if (row === undefined) {
+            return false;
+        }
+        const last = this.#rows - 1;
+        if (row !== last) {
+            const moved = this.#ids[last];
+            this.#data.copyWithin(row * this.#dims, last * this.#dims, (last + 1) * this.#dims);
+            this.#ids[row] = moved;
+            this.#index.set(moved, row);
+        }
+        this.#ids.length = last;
+        this.#index.delete(id);
+        this.#rows = last;
+        return true;
+    }
+    /** Exact kNN over the rows `allow` accepts. Ties break toward the earlier row. */
+    topK(query, k, allow) {
+        if (query.length !== this.#dims) {
+            throw new Error(`expected a ${this.#dims}-dimension query, got ${query.length}`);
+        }
+        const out = [];
+        for (let row = 0; row < this.#rows; row++) {
+            const id = this.#ids[row];
+            if (allow && !allow(id)) {
+                continue;
+            }
+            out.push({ id, score: this.#dot(query, row) });
+        }
+        out.sort((a, b) => b.score - a.score);
+        return out.slice(0, k);
+    }
+    /** The raw block, trimmed to the rows in use — what goes to disk. */
+    bytes() {
+        return this.#data.subarray(0, this.#rows * this.#dims);
+    }
+    static load(dims, ids, data) {
+        const block = new VectorBlock(dims, Math.max(ids.length, 1));
+        block.#ids = [...ids];
+        block.#rows = ids.length;
+        for (let row = 0; row < ids.length; row++) {
+            block.#index.set(ids[row], row);
+        }
+        block.#data.set(data.subarray(0, ids.length * dims), 0);
+        return block;
+    }
+    #dot(query, row) {
+        const base = row * this.#dims;
+        let sum = 0;
+        for (let i = 0; i < this.#dims; i++) {
+            sum += query[i] * this.#data[base + i];
+        }
+        return sum;
+    }
+    #grow(needed) {
+        const capacity = this.#data.length / this.#dims;
+        if (needed <= capacity) {
+            return;
+        }
+        const next = new Float32Array(Math.max(needed, capacity * GROWTH) * this.#dims);
+        next.set(this.#data, 0);
+        this.#data = next;
+    }
+}
+// ---------------------------------------------------------------------------
+// Lexical fallback
+//
+// Used when a project configures no embedder. It is worse than embeddings and
+// is meant to be: the alternative is memory that silently does nothing, and a
+// term-overlap hit on a remembered task is still a hit.
+// ---------------------------------------------------------------------------
+export function tokenize(v) {
+    return v
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 2);
+}
+export 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;
+}
+/** Half-life in days: how fast a memory nobody reads falls behind one that is read. */
+export const DECAY_HALF_LIFE_DAYS = 30;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * Multiplied into similarity, never added: a stale exact match should still beat
+ * a fresh irrelevant one, so decay narrows the field rather than reordering it.
+ */
+export function recencyDecay(lastUsedAt, now) {
+    const age = now - Date.parse(lastUsedAt);
+    if (!Number.isFinite(age) || age <= 0) {
+        return 1;
+    }
+    return 2 ** (-age / DAY_MS / DECAY_HALF_LIFE_DAYS);
+}
+//# sourceMappingURL=vectors.js.map

package/dist/models/anthropic.d.ts

@@ -1,5 +1,6 @@
 import type Anthropic from '@anthropic-ai/sdk';
 import type { StreamDelta } from '../events.ts';
+import { type ProviderNamed } from '../failure.ts';
 import type { Model, ModelRequest, ModelResponse } from '../model.ts';
 /**
  * Provider-specific knobs.
@@ -9,7 +10,7 @@ import type { Model, ModelRequest, ModelResponse } from '../model.ts';
  * exist. 8192 is the largest value every current Claude model accepts, which
  * makes it the only safe default — raise it per model when you know better.
  */
-export interface AnthropicModelOptions {
+export interface AnthropicModelOptions extends ProviderNamed {
     /** hard cap on output tokens; required by the API, so it always has a value */
     maxTokens?: number;
     /**

package/dist/models/anthropic.js

@@ -1,3 +1,4 @@
+import { callSites, called, reading } from "../failure.js";
 import { zeroUsage, } from "../types.js";
 /** Every current Claude model accepts at least this many output tokens. */
 const DEFAULT_MAX_TOKENS = 8192;
@@ -16,9 +17,11 @@ export class AnthropicModel {
     #client;
     #maxTokens;
     #thinkingBudget;
+    #site;
     constructor(id, client, options = {}) {
         this.id = id;
         this.#client = client;
+        this.#site = callSites(id, options.provider);
         this.#thinkingBudget =
             options.thinkingBudgetTokens && options.thinkingBudgetTokens >= MIN_THINKING_BUDGET
                 ? options.thinkingBudgetTokens
@@ -28,7 +31,7 @@ export class AnthropicModel {
         this.#maxTokens = Math.max(options.maxTokens ?? DEFAULT_MAX_TOKENS, (this.#thinkingBudget ?? 0) + MIN_THINKING_BUDGET);
     }
     async generate(req) {
-        const res = await this.#client.messages.create(this.#params(req), { signal: req.signal });
+        const res = await called(this.#site('llm generation', 'messages.create'), () => this.#client.messages.create(this.#params(req), { signal: req.signal }));
         return {
             ...readBlocks(res.content),
             usage: toUsage(res.usage),
@@ -36,11 +39,15 @@ export class AnthropicModel {
         };
     }
     async stream(req, onDelta) {
-        const stream = this.#client.messages.stream(this.#params(req), { signal: req.signal });
+        const site = this.#site('llm streaming', 'messages.stream');
+        // Reassigned when a broken stream is reopened, so that `finalMessage()`
+        // below is asked of whichever stream actually delivered the answer.
+        let stream = this.#client.messages.stream(this.#params(req), { signal: req.signal });
+        const open = async () => (stream = this.#client.messages.stream(this.#params(req), { signal: req.signal }));
         // Blocks are addressed by index, and a tool call's id and name arrive in
         // its `content_block_start` while the arguments trickle in afterwards.
         const calls = new Map();
-        for await (const event of stream) {
+        for await (const event of reading(site, stream, open)) {
             if (event.type === 'content_block_start') {
                 const block = event.content_block;
                 if (block.type === 'tool_use') {
@@ -79,7 +86,7 @@ export class AnthropicModel {
         // The accumulated message is authoritative: it has the parsed tool
         // inputs and the final usage, so the deltas above are for the UI only
         // and nothing here depends on having reassembled them correctly.
-        const final = await stream.finalMessage();
+        const final = await called(site, () => stream.finalMessage());
         return {
             ...readBlocks(final.content),
             usage: toUsage(final.usage),

package/dist/models/factory.d.ts

@@ -64,6 +64,16 @@ export interface ProviderSpec extends Credentials {
     headers?: Record<string, string>;
     timeoutMs?: number;
     maxRetries?: number;
+    /**
+     * Ceiling on embedding requests in flight against this connection. The
+     * floor and the actual number are discovered from the provider's own
+     * refusals, so this only says how high the discovery may climb — set it
+     * when an account is shared with something else that also needs quota.
+     *
+     * On the provider rather than on a model because a rate limit belongs to
+     * the key: two embedders on one account are one budget, not two.
+     */
+    concurrency?: number;
     /**
      * Pre-built client — bypasses credential resolution entirely. The seam for
      * auth no configuration can express: Vertex service accounts, Bedrock
@@ -182,6 +192,11 @@ export declare class ModelRegistry {
     requirement(ref: ModelRef | EmbeddingRef): ModelRequirement;
     /** `[provider[/api]:]model` → spec. Exposed so a caller can validate a ref. */
     parse(ref: string): ModelSpec;
+    /**
+     * Splits `[provider:]model` into the spec it stands for, so a caller holding
+     * a shorthand can still set the knobs a shorthand has no room for.
+     */
+    parseEmbedding(ref: string): EmbeddingSpec;
     /** A declared kind wins; otherwise a built-in name is its own kind. */
     kindOf(name: string): ProviderKind;
 }