@zenera/neo 1.1.10 → 1.1.12

package/README.md

@@ -134,8 +134,9 @@ of surfacing three turns into a run as a confused model.
   wildcard. Workspace file tools and a Podman sandbox ship with the library.
 - **Skills** — instruction bundles discovered and loaded on demand instead of
   permanently occupying the prompt, optionally owning their own tools.
-- **Memory** — pluggable `MemoryStore`s, with scopes deciding what is private to
-  an agent and what is shared.
+- **Memory** — a timed, masked knowledge graph that outlives a run: recall
+  returns a stitched subgraph rather than a ranked list, remembered files are
+  mounted at `/memory`, and standing preferences go into the system prompt.
 - **Trajectory** — an append-only log of everything that happened. What is sent
   to a provider is derived from it, and compaction _covers_ nodes rather than
   deleting them, so the full record survives even when older turns have to be
@@ -150,7 +151,6 @@ of surfacing three turns into a run as a confused model.
 | `@zenera/neo`                 | agents, models, tools, kernel, inspection |
 | `@zenera/neo/project`         | loading a project folder                  |
 | `@zenera/neo/skill-providers` | skill discovery and loading               |
-| `@zenera/neo/memory-stores`   | `MemoryStore` implementations             |
 | `@zenera/neo/payload-stores`  | payload persistence                       |
 
 ## Documentation

package/dist/agent.d.ts

@@ -1,4 +1,4 @@
-import type { MemoryBinding, ResolvedBinding } from './memory.ts';
+import { type MemoryBinding, type ResolvedMemoryBinding } from './memory/types.ts';
 import type { Model } from './model.ts';
 import type { Instructions } from './prompt.ts';
 import type { SkillBinding } from './skills.ts';
@@ -22,8 +22,8 @@ export interface AgentOptions<TCtx = unknown> {
     tools?: AnyTool<TCtx>[];
     /** agents this one may hand the conversation over to (by name or instance) */
     handoffs?: (string | Agent<TCtx>)[];
-    /** long-lived memory spaces this agent may read and/or write */
-    memory?: MemoryBinding<TCtx>[];
+    /** how this agent sees the shared memory graph */
+    memory?: MemoryBinding<TCtx>;
     /** on-demand instruction bundles */
     skills?: SkillBinding;
     /** opt-in to parallel sub-agents */
@@ -40,16 +40,17 @@ export declare class Agent<TCtx = unknown> {
     readonly model?: Model;
     readonly tools: AnyTool<TCtx>[];
     readonly handoffs: string[];
-    readonly memory: MemoryBinding<TCtx>[];
+    readonly memory?: MemoryBinding<TCtx>;
     readonly skills?: SkillBinding;
     readonly fork?: ForkOptions;
     constructor(opts: AgentOptions<TCtx>);
     /**
-     * Memory bindings with their scope resolved against the run context. The
+     * The memory mask with `sees` resolved against the run context. The
      * resolved value is what gets recorded in the trajectory, so a resumed run
-     * cannot drift into another user's space.
+     * cannot drift into another agent's slice. Everyone always sees the public
+     * label, so a binding can only ever widen from there.
      */
-    memoryBindings(ctx: TCtx): ResolvedBinding[];
+    memoryBinding(ctx: TCtx): ResolvedMemoryBinding | undefined;
 }
 export declare class AgentRegistry<TCtx = unknown> {
     readonly agents: Map<string, Agent<TCtx>>;

package/dist/agent.js

@@ -1,3 +1,4 @@
+import { ALL_AGENTS } from "./memory/types.js";
 import { HANDOFF_PREFIX } from "./types.js";
 /**
  * Note what is *not* here any more: `maxTurns`. A run ends on a final answer,
@@ -20,22 +21,28 @@ export class Agent {
         this.model = opts.model;
         this.tools = opts.tools ?? [];
         this.handoffs = (opts.handoffs ?? []).map((h) => (typeof h === 'string' ? h : h.name));
-        this.memory = opts.memory ?? [];
+        this.memory = opts.memory;
         this.skills = opts.skills;
         this.fork = opts.fork;
     }
     /**
-     * Memory bindings with their scope resolved against the run context. The
+     * The memory mask with `sees` resolved against the run context. The
      * resolved value is what gets recorded in the trajectory, so a resumed run
-     * cannot drift into another user's space.
+     * cannot drift into another agent's slice. Everyone always sees the public
+     * label, so a binding can only ever widen from there.
      */
-    memoryBindings(ctx) {
-        return this.memory.map((b) => ({
-            store: b.store,
-            scope: typeof b.scope === 'function' ? b.scope(ctx) : (b.scope ?? `agent:${this.name}`),
+    memoryBinding(ctx) {
+        const b = this.memory;
+        if (!b) {
+            return undefined;
+        }
+        const sees = typeof b.sees === 'function' ? b.sees(ctx) : (b.sees ?? []);
+        return {
             access: b.access,
+            sees: [...new Set([ALL_AGENTS, ...sees])],
+            writes: b.writes ?? [ALL_AGENTS],
             autoRecall: b.autoRecall,
-        }));
+        };
     }
 }
 // ---------------------------------------------------------------------------

package/dist/architecture.d.ts

@@ -1,4 +1,5 @@
 import type { AgentRegistry } from './agent.ts';
+import { type MemoryAccess } from './memory/types.ts';
 import type { Model } from './model.ts';
 import type { Services } from './services.ts';
 import type { SkillBinding } from './skills.ts';
@@ -18,10 +19,11 @@ export interface ArchSkill {
     toolNames?: string[];
 }
 export interface ArchMemory {
-    store: string;
-    /** `(per run)` when the binding resolves its scope from the run context */
-    scope: string;
-    access: 'read' | 'read-write';
+    access: MemoryAccess;
+    /** audience labels this agent may read; `(per run)` when resolved from context */
+    sees: string[] | '(per run)';
+    /** labels it may write */
+    writes: string[];
     autoRecall?: boolean;
 }
 export interface ArchAgent {
@@ -42,7 +44,7 @@ export interface ArchAgent {
         /** the binding names a provider the services do not know */
         unresolved?: boolean;
     };
-    memory: ArchMemory[];
+    memory?: ArchMemory;
     fork?: {
         agents?: string[];
         maxBranches?: number;

package/dist/architecture.js

@@ -1,3 +1,4 @@
+import { ALL_AGENTS } from "./memory/types.js";
 import { HANDOFF_PREFIX } from "./types.js";
 /**
  * Projects a registry into a snapshot. Async only because a skill catalog is
@@ -83,23 +84,30 @@ function allowFilter(binding) {
 }
 /**
  * With a context in hand this is exactly what the run will record. Without
- * one, a scope function is left symbolic rather than called: it would be
- * handed `undefined` and either throw or invent a space no run ever uses.
+ * one, a `sees` function is left symbolic rather than called: it would be
+ * handed `undefined` and either throw or invent a mask no run ever uses.
  */
 function describeMemory(agent, context) {
+    const b = agent.memory;
+    if (!b) {
+        return undefined;
+    }
     if (context !== undefined) {
-        return agent.memoryBindings(context).map((b) => ({
-            store: b.store,
-            scope: b.scope,
-            access: b.access,
-            autoRecall: b.autoRecall ? true : undefined,
-        }));
+        const r = agent.memoryBinding(context);
+        return {
+            access: r.access,
+            sees: r.sees,
+            writes: r.writes,
+            autoRecall: r.autoRecall ? true : undefined,
+        };
     }
-    return agent.memory.map((b) => ({
-        store: b.store,
-        scope: typeof b.scope === 'function' ? '(per run)' : (b.scope ?? `agent:${agent.name}`),
+    return {
         access: b.access,
+        sees: typeof b.sees === 'function'
+            ? '(per run)'
+            : [...new Set([ALL_AGENTS, ...(b.sees ?? [])])],
+        writes: b.writes ?? [ALL_AGENTS],
         autoRecall: b.autoRecall ? true : undefined,
-    }));
+    };
 }
 //# sourceMappingURL=architecture.js.map

package/dist/embedding.d.ts

@@ -11,7 +11,11 @@ import type { TokenUsage } from './types.ts';
  */
 export type EmbeddingTaskType = 'query' | 'document';
 export interface EmbeddingRequest {
-    /** the texts to encode, in the order the vectors come back */
+    /**
+     * The texts to encode, in the order the vectors come back. Any length: the
+     * adapter splits it to whatever the model accepts per request and issues
+     * those in parallel, so a caller never has to know the cap or invent one.
+     */
     input: string[];
     taskType?: EmbeddingTaskType;
     /** truncate to this width, where the model supports it */
@@ -21,6 +25,19 @@ export interface EmbeddingRequest {
      * Turn it off to see what the model actually returned.
      */
     normalize?: boolean;
+    /**
+     * Texts finished so far, out of the whole input. A large batch is minutes
+     * of one `await`, and a caller with nothing to say for that long is
+     * indistinguishable from a hung one.
+     */
+    onProgress?: (done: number, total: number) => void;
+    /**
+     * Each slice of the input as it comes back, `at` being where it started in
+     * `input`. A large request is many round trips, and a caller that persists
+     * them can survive a crash without paying for the same vectors twice.
+     * Vectors arrive normalised, exactly as the response will carry them.
+     */
+    onSlice?: (at: number, vectors: number[][]) => void;
     signal?: AbortSignal;
 }
 export interface EmbeddingResponse {
@@ -57,4 +74,6 @@ export interface Embedder {
  * provider without three copies of the same loop.
  */
 export declare function embeddingResponse(vectors: number[][], req: EmbeddingRequest, usage?: TokenUsage): EmbeddingResponse;
+/** Idempotent, so settling a vector that is already unit length changes nothing. */
+export declare function unitVector(vector: number[]): number[];
 //# sourceMappingURL=embedding.d.ts.map

package/dist/embedding.js

@@ -4,12 +4,13 @@
  */
 export function embeddingResponse(vectors, req, usage) {
     return {
-        vectors: req.normalize === false ? vectors : vectors.map(unit),
+        vectors: req.normalize === false ? vectors : vectors.map(unitVector),
         dimensions: vectors[0]?.length ?? 0,
         usage,
     };
 }
-function unit(vector) {
+/** Idempotent, so settling a vector that is already unit length changes nothing. */
+export function unitVector(vector) {
     let sum = 0;
     for (const x of vector) {
         sum += x * x;

package/dist/embeddings/fanout.d.ts

@@ -0,0 +1,51 @@
+import { type EmbeddingRequest, type EmbeddingResponse } from '../embedding.ts';
+import type { ProviderNamed } from '../failure.ts';
+import { RateLimiter } from './limiter.ts';
+/** What one request came back with, before it is joined to the others. */
+export interface EmbeddingSlice {
+    vectors: number[][];
+    /** absent where the vendor reports characters, or nothing */
+    inputTokens?: number;
+}
+/** The per-model knobs every adapter shares, and the connection they share it with. */
+export interface BatchOptions extends ProviderNamed {
+    /** texts per request; the model's own cap applies when unset */
+    maxBatch?: number;
+    /** estimated tokens per request; the model's own cap applies when unset */
+    maxBatchTokens?: number;
+    /**
+     * Paces every embedding request on one connection. Supplied by the registry
+     * so two embedders on one account cannot each ramp up to the full limit;
+     * an adapter built by hand gets one of its own.
+     */
+    limiter?: RateLimiter;
+}
+export interface FanoutPlan {
+    /** the embedder's id, for the one error message that needs it */
+    id: string;
+    limiter: RateLimiter;
+    maxBatch: number;
+    maxBatchTokens: number;
+    send(input: string[]): Promise<EmbeddingSlice>;
+}
+/**
+ * Four characters to a token: within about 15% for English prose, wrong for CJK
+ * and for long identifiers. It only has to be right enough to stay under a cap
+ * that is already generous, and being wrong costs an extra request, not a
+ * failed one.
+ */
+export declare const estimateTokens: (text: string) => number;
+export declare function fanout(req: EmbeddingRequest, plan: FanoutPlan): Promise<EmbeddingResponse>;
+interface Part {
+    /** where these texts started in the caller's array */
+    at: number;
+    texts: string[];
+}
+/**
+ * Greedy, on both caps at once. A single text over the token budget goes alone
+ * and is sent as it is: truncating it would answer with a vector for something
+ * the caller did not ask about, which is worse than the error it will get.
+ */
+export declare function sliceBatch(input: readonly string[], maxBatch: number, maxBatchTokens: number): Part[];
+export {};
+//# sourceMappingURL=fanout.d.ts.map

package/dist/embeddings/fanout.js

@@ -0,0 +1,76 @@
+import { embeddingResponse, unitVector, } from "../embedding.js";
+import { zeroUsage } from "../types.js";
+import { RateLimiter } from "./limiter.js";
+/**
+ * Four characters to a token: within about 15% for English prose, wrong for CJK
+ * and for long identifiers. It only has to be right enough to stay under a cap
+ * that is already generous, and being wrong costs an extra request, not a
+ * failed one.
+ */
+export const estimateTokens = (text) => Math.ceil(text.length / 4);
+export async function fanout(req, plan) {
+    if (req.input.length === 0) {
+        return embeddingResponse([], req);
+    }
+    const parts = sliceBatch(req.input, plan.maxBatch, plan.maxBatchTokens);
+    const settle = req.normalize !== false;
+    let done = 0;
+    const slices = await Promise.all(parts.map((part) => plan.limiter.run(async () => {
+        const slice = await plan.send(part.texts);
+        if (slice.vectors.length !== part.texts.length) {
+            throw new Error(`embedder "${plan.id}": answered ${slice.vectors.length} vectors ` +
+                `for ${part.texts.length} texts`);
+        }
+        const unit = settle ? slice.vectors.map(unitVector) : slice.vectors;
+        done += part.texts.length;
+        req.onSlice?.(part.at, unit);
+        req.onProgress?.(done, req.input.length);
+        return { ...slice, vectors: unit };
+    }, req.signal)));
+    const vectors = new Array(req.input.length);
+    for (const [at, part] of parts.entries()) {
+        for (const [i, vector] of slices[at].vectors.entries()) {
+            vectors[part.at + i] = vector;
+        }
+    }
+    // Settled slice by slice above. Doing it again over the join would hold a
+    // second copy of every vector at once, which for a large corpus is GBs.
+    return embeddingResponse(vectors, { ...req, normalize: false }, usageOf(slices));
+}
+/**
+ * Greedy, on both caps at once. A single text over the token budget goes alone
+ * and is sent as it is: truncating it would answer with a vector for something
+ * the caller did not ask about, which is worse than the error it will get.
+ */
+export function sliceBatch(input, maxBatch, maxBatchTokens) {
+    const parts = [];
+    let texts = [];
+    let at = 0;
+    let tokens = 0;
+    for (const [i, text] of input.entries()) {
+        const cost = estimateTokens(text);
+        if (texts.length > 0 && (texts.length >= maxBatch || tokens + cost > maxBatchTokens)) {
+            parts.push({ at, texts });
+            texts = [];
+            at = i;
+            tokens = 0;
+        }
+        texts.push(text);
+        tokens += cost;
+    }
+    if (texts.length > 0) {
+        parts.push({ at, texts });
+    }
+    return parts;
+}
+/** Undefined unless something reported a number: a zero would read as free. */
+function usageOf(slices) {
+    let total;
+    for (const slice of slices) {
+        if (slice.inputTokens !== undefined) {
+            total = (total ?? 0) + slice.inputTokens;
+        }
+    }
+    return total === undefined ? undefined : { ...zeroUsage(), inputTokens: total };
+}
+//# sourceMappingURL=fanout.js.map

package/dist/embeddings/gemini.d.ts

@@ -1,19 +1,12 @@
 import type { GoogleGenAI } from '@google/genai';
-import { type Embedder, type EmbeddingRequest, type EmbeddingResponse } from '../embedding.ts';
+import type { Embedder, EmbeddingRequest, EmbeddingResponse } from '../embedding.ts';
+import { type BatchOptions } from './fanout.ts';
 /** Provider-specific knobs. */
-export interface GeminiEmbedderOptions {
+export interface GeminiEmbedderOptions extends BatchOptions {
     /** default width; a request may override it */
     dimensions?: number;
     /** a document's title, which the retrieval task type takes into account */
     title?: string;
-    /**
-     * Texts this model accepts per request. One is the default because that is
-     * what every `gemini-embedding-*` model takes — `embedContent` is a
-     * single-document endpoint there, and the batch path is a separate,
-     * job-based API. The older `text-embedding-*` models accept far more and
-     * can say so.
-     */
-    maxBatch?: number;
 }
 export declare class GeminiEmbedder implements Embedder {
     #private;

package/dist/embeddings/gemini.js

@@ -1,4 +1,6 @@
-import { embeddingResponse, } from "../embedding.js";
+import { callSites, called } from "../failure.js";
+import { fanout } from "./fanout.js";
+import { RateLimiter } from "./limiter.js";
 // ---------------------------------------------------------------------------
 // Google Gemini embeddings adapter
 //
@@ -15,16 +17,36 @@ const TASK_TYPES = {
     query: 'RETRIEVAL_QUERY',
     document: 'RETRIEVAL_DOCUMENT',
 };
-/** Requests in flight at once when a batch has to be split across several. */
-const CONCURRENCY = 8;
+/**
+ * One, because `embedContent` is a single-document endpoint for every
+ * `gemini-embedding-*` model — it answers more than one content with *"The
+ * embedContent API for this model only supports one content at a time"* — and
+ * the batch path is a separate, job-based API. The older `text-embedding-*`
+ * models take far more.
+ *
+ * This is why the fan-out matters most here: a corpus is one request per chunk,
+ * so how many may be in flight is the entire runtime of a build.
+ */
+const MAX_BATCH = 1;
+const LEGACY_MAX_BATCH = 250;
+const MAX_BATCH_TOKENS = 20_000;
+const LEGACY_MODEL = /^text-embedding-/;
 export class GeminiEmbedder {
     id;
     #client;
     #options;
+    #limiter;
+    #maxBatch;
+    #maxBatchTokens;
+    #site;
     constructor(id, client, options = {}) {
         this.id = id;
         this.#client = client;
         this.#options = options;
+        this.#limiter = options.limiter ?? new RateLimiter();
+        this.#site = callSites(id, options.provider);
+        this.#maxBatch = options.maxBatch ?? (LEGACY_MODEL.test(id) ? LEGACY_MAX_BATCH : MAX_BATCH);
+        this.#maxBatchTokens = options.maxBatchTokens ?? MAX_BATCH_TOKENS;
     }
     async embed(req) {
         const config = {
@@ -34,38 +56,32 @@ export class GeminiEmbedder {
             title: this.#options.title,
             outputDimensionality: req.dimensions ?? this.#options.dimensions,
             abortSignal: req.signal,
+            // The SDK retries nothing unless `retryOptions` is present, and the
+            // client was built with some; one attempt hands a refusal back out
+            // to the limiter, which is the only thing that can slow the run down.
+            httpOptions: { retryOptions: { attempts: 1 } },
         };
-        // The contract is batch-first and this endpoint usually is not, so the
-        // splitting happens here rather than in every caller. Chunks are issued
-        // in waves and their results concatenated in order, so a caller cannot
-        // tell how many requests it took.
-        const size = Math.max(1, this.#options.maxBatch ?? 1);
-        const chunks = [];
-        for (let i = 0; i < req.input.length; i += size) {
-            chunks.push(req.input.slice(i, i + size));
-        }
-        const vectors = [];
-        for (let i = 0; i < chunks.length; i += CONCURRENCY) {
-            const wave = await Promise.all(chunks.slice(i, i + CONCURRENCY).map((chunk) => this.#send(chunk, config)));
-            for (const part of wave) {
-                vectors.push(...part);
-            }
-        }
         // Usage stays undefined on purpose: this API reports billable
         // *characters*, on Vertex only, which is not a token count and would be
         // a lie in `TokenUsage`.
-        return embeddingResponse(vectors, req);
-    }
-    async #send(input, config) {
-        const res = await this.#client.models.embedContent({
-            model: this.id,
-            // Spelled out as one `Content` per text. `ContentListUnion` also
-            // accepts a `string[]`, and reads it as the *parts of a single
-            // document* — six sentences in, one vector back, and no error.
-            contents: input.map((text) => ({ parts: [{ text }] })),
-            config,
+        return await fanout(req, {
+            id: this.id,
+            limiter: this.#limiter,
+            maxBatch: this.#maxBatch,
+            maxBatchTokens: this.#maxBatchTokens,
+            send: async (input) => {
+                const res = await called(this.#site('embedding', 'models.embedContent'), () => this.#client.models.embedContent({
+                    model: this.id,
+                    // Spelled out as one `Content` per text.
+                    // `ContentListUnion` also accepts a `string[]`, and
+                    // reads it as the *parts of a single document* — six
+                    // sentences in, one vector back, and no error.
+                    contents: input.map((text) => ({ parts: [{ text }] })),
+                    config,
+                }));
+                return { vectors: (res.embeddings ?? []).map((e) => e.values ?? []) };
+            },
         });
-        return (res.embeddings ?? []).map((e) => e.values ?? []);
     }
 }
 //# sourceMappingURL=gemini.js.map

package/dist/embeddings/index.d.ts

@@ -1,4 +1,7 @@
+export * from './fanout.ts';
 export * from './gemini.ts';
+export * from './limiter.ts';
 export * from './openai.ts';
 export * from './openrouter.ts';
+export * from './rate-limit.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/embeddings/index.js

@@ -1,4 +1,7 @@
+export * from "./fanout.js";
 export * from "./gemini.js";
+export * from "./limiter.js";
 export * from "./openai.js";
 export * from "./openrouter.js";
+export * from "./rate-limit.js";
 //# sourceMappingURL=index.js.map

package/dist/embeddings/limiter.d.ts

@@ -0,0 +1,36 @@
+export interface LimiterOptions {
+    /** never go below this many in flight */
+    min?: number;
+    /** where to start, before anything is known */
+    start?: number;
+    /** never go above this many, whatever the provider tolerates */
+    max?: number;
+    /** consecutive successes, while saturated, that earn one more slot */
+    stride?: number;
+    /** the first wait after a refusal, doubling while they continue */
+    initialBackoffMs?: number;
+    maxBackoffMs?: number;
+    /** attempts after the first, per task */
+    maxRetries?: number;
+}
+export declare const DEFAULT_MIN = 1;
+export declare const DEFAULT_START = 4;
+export declare const DEFAULT_MAX = 16;
+export declare const DEFAULT_STRIDE = 8;
+export declare const DEFAULT_INITIAL_BACKOFF_MS = 1000;
+export declare const DEFAULT_MAX_BACKOFF_MS = 60000;
+export declare const DEFAULT_MAX_RETRIES = 4;
+export declare class RateLimiter {
+    #private;
+    constructor(options?: LimiterOptions);
+    /** How many may be in flight as things stand. Moves; read it for reporting only. */
+    get limit(): number;
+    get inFlight(): number;
+    /**
+     * Runs the task when there is room, retries it when the failure allows, and
+     * gives up when it does not. The slot is released before any wait, so a
+     * task serving its backoff is not also holding the concurrency down.
+     */
+    run<T>(task: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+}
+//# sourceMappingURL=limiter.d.ts.map