@zenera/neo 1.1.11 → 1.1.14

package/dist/project/load.d.ts

@@ -1,7 +1,7 @@
 import { Agent, AgentRegistry } from '../agent.ts';
 import type { Embedder } from '../embedding.ts';
 import { RunStream } from '../events.ts';
-import type { MemoryStore } from '../memory.ts';
+import { MemoryIndex } from '../memory/index.ts';
 import { ModelRegistry, type EmbeddingRef, type ModelRef, type ProviderSpec } from '../models/factory.ts';
 import type { PayloadStore } from '../payload.ts';
 import { AgentRunner, type RunOptions, type RunnerOptions } from '../runner.ts';
@@ -54,7 +54,9 @@ export interface ProjectOptions<TCtx = unknown> {
      * project never reaches the network.
      */
     registry?: ModelRegistry;
-    memory?: MemoryStore[];
+    memory?: MemoryIndex;
+    /** turns an agent-visible path into a host path, so files can be remembered */
+    resolveFile?: (path: string) => string;
     payloads?: PayloadStore;
     /** extra providers merged with the ones the project declares */
     skills?: SkillProvider[];
@@ -99,6 +101,7 @@ interface ProjectParts<TCtx> {
     skillProviders: SkillProvider[];
     assets: string | undefined;
     models: ModelRegistry;
+    memory: MemoryIndex | undefined;
     embedders: (ref: string | undefined, where: string) => Embedder | undefined;
     options: ProjectOptions<TCtx>;
 }
@@ -129,7 +132,11 @@ export declare class AgentProject<TCtx = unknown> {
     readonly assets: string | undefined;
     /** the providers this project declared, and the clients behind them */
     readonly models: ModelRegistry;
+    /** the one memory graph, when this project has one */
+    readonly memory: MemoryIndex | undefined;
     constructor(parts: ProjectParts<TCtx>);
+    /** Releases the memory lock. A project that holds no memory need not be closed. */
+    close(): void;
     get agents(): readonly Agent<TCtx>[];
     /**
      * A declared vectoriser, memoized. Named or not: with no argument this is
@@ -153,6 +160,13 @@ export declare class AgentProject<TCtx = unknown> {
  * for, and only pay for it if an agent actually reaches for it.
  */
 export declare function projectRegistry<TCtx>(config: ProjectConfig, opts?: ProjectOptions<TCtx>): ModelRegistry;
+/**
+ * Where this project's memory lives, or `undefined` when it has none. Shared
+ * with the front end, which has to mount the same directory into the sandbox:
+ * two answers to this question would mean `/memory` pointing somewhere the
+ * graph is not.
+ */
+export declare function memoryDir(root: string, config: ProjectConfig): string | undefined;
 /**
  * Where each skill directory appears in the agent's namespace.
  *

package/dist/project/load.js

@@ -2,6 +2,8 @@ import { existsSync, readFileSync, statSync } from 'node:fs';
 import { basename, join } from 'node:path';
 import { Agent, AgentRegistry } from "../agent.js";
 import { RunStream } from "../events.js";
+import { MemoryIndex } from "../memory/index.js";
+import { MemoryStore } from "../memory/store.js";
 import { ModelRegistry, } from "../models/factory.js";
 import { promptFile } from "../prompt.js";
 import { AgentRunner } from "../runner.js";
@@ -59,6 +61,7 @@ export async function loadProject(dir, opts = {}) {
             handoffs: spec.handoffs,
             skills: bindingFor(spec, providers),
             fork: forkFor(spec),
+            memory: memoryFor(spec),
         });
     }
     validate(config, registry, providers, catalogs, models);
@@ -66,12 +69,14 @@ export async function loadProject(dir, opts = {}) {
     // The default is resolved here rather than on first use, so a broken
     // `embedding:` fails at load like a broken `model:` does.
     embedders(config.embedding, 'embedding');
+    const memory = opts.memory ?? (await openMemory(root, config, embedders));
     return new AgentProject({
         root,
         source,
         config,
         entry: entrypoint(config),
         registry,
+        memory,
         skillProviders: providers,
         assets,
         models,
@@ -105,6 +110,8 @@ export class AgentProject {
     assets;
     /** the providers this project declared, and the clients behind them */
     models;
+    /** the one memory graph, when this project has one */
+    memory;
     #embedders;
     #options;
     #runner;
@@ -117,9 +124,14 @@ export class AgentProject {
         this.skillProviders = parts.skillProviders;
         this.assets = parts.assets;
         this.models = parts.models;
+        this.memory = parts.memory;
         this.#embedders = parts.embedders;
         this.#options = parts.options;
     }
+    /** Releases the memory lock. A project that holds no memory need not be closed. */
+    close() {
+        this.memory?.store.release();
+    }
     get agents() {
         return [...this.registry.agents.values()];
     }
@@ -151,7 +163,8 @@ export class AgentProject {
     #build(overrides = {}) {
         const runner = new AgentRunner({
             payloads: this.#options.payloads,
-            memory: this.#options.memory,
+            memory: this.memory,
+            resolveFile: this.#options.resolveFile,
             skills: [...this.skillProviders],
             ...overrides,
         });
@@ -315,6 +328,59 @@ function forkFor(spec) {
     }
     return spec.fork === true ? {} : spec.fork;
 }
+/**
+ * `memory: true` is the whole feature working the obvious way: read and write,
+ * and recall before a turn that follows new user input. An agent that has to
+ * remember to go looking mostly does not, so auto-recall is on by default and
+ * `autoRecall: false` is how you turn it off.
+ */
+function memoryFor(spec) {
+    const b = spec.memory;
+    if (!b) {
+        return undefined;
+    }
+    const auto = b.autoRecall ?? true;
+    return {
+        access: b.access,
+        sees: b.sees,
+        writes: b.writes,
+        autoRecall: auto
+            ? { query: 'last_user_input', limit: auto === true ? 5 : auto.limit }
+            : undefined,
+    };
+}
+/**
+ * Where this project's memory lives, or `undefined` when it has none. Shared
+ * with the front end, which has to mount the same directory into the sandbox:
+ * two answers to this question would mean `/memory` pointing somewhere the
+ * graph is not.
+ */
+export function memoryDir(root, config) {
+    if (!config.memory && !config.agents.some((a) => a.memory)) {
+        return undefined;
+    }
+    return join(root, config.memory?.dir ?? 'memory');
+}
+/**
+ * Opened only when something will use it, so an ordinary project neither
+ * creates a directory nor takes a lock. A `memory:` block with no agent bound
+ * to it still counts: it is how a project declares the graph `zen memory`
+ * inspects between runs.
+ */
+async function openMemory(root, config, embedders) {
+    const dir = memoryDir(root, config);
+    if (!dir) {
+        return undefined;
+    }
+    const declared = config.memory;
+    const embedder = embedders(declared?.embedding ?? config.embedding, 'memory.embedding');
+    return new MemoryIndex({
+        store: await MemoryStore.open(dir),
+        embedder,
+        kinds: declared?.kinds,
+        relations: declared?.relations,
+    });
+}
 function skillProviders(root, config, opts) {
     const declared = skillDirs(root, config);
     if (!declared.length) {

package/dist/runner.d.ts

@@ -3,7 +3,7 @@ import { Agent, AgentRegistry, type AgentOptions } from './agent.ts';
 import { type Architecture } from './architecture.ts';
 import { RunStream } from './events.ts';
 import { type IdClock } from './ids.ts';
-import type { MemoryStore } from './memory.ts';
+import type { MemoryIndex } from './memory/index.ts';
 import type { Model } from './model.ts';
 import { PayloadResolver, type PayloadStore } from './payload.ts';
 import { Services } from './services.ts';
@@ -41,7 +41,9 @@ export interface RunnerOptions<TCtx = unknown> {
     context?: TCtx;
     services?: Services;
     payloads?: PayloadStore | PayloadResolver;
-    memory?: MemoryStore[];
+    memory?: MemoryIndex;
+    /** turns an agent-visible path into a host path, so files can be remembered */
+    resolveFile?: (path: string) => string;
     skills?: SkillProvider[];
     handoffPolicy?: HandoffPolicy;
     /** renders the nodes a policy selected; defaults to a structural note */

package/dist/runner.js

@@ -3,7 +3,7 @@ import { describeArchitecture } from "./architecture.js";
 import { EventQueue, RunStream, } from "./events.js";
 import { systemClock } from "./ids.js";
 import * as Kernel from "./kernel.js";
-import { renderMemories } from "./memory.js";
+import { renderRecollection } from "./memory/render.js";
 import { PayloadResolver } from "./payload.js";
 import { Services } from "./services.js";
 import { activeSkillNames } from "./skills.js";
@@ -76,19 +76,21 @@ export class AgentRunner {
     constructor(opts = {}) {
         this.#model = opts.model;
         this.#context = opts.context;
+        this.#clock = opts.clock ?? systemClock;
         this.services =
             opts.services ??
                 new Services({
                     payloads: opts.payloads,
                     memory: opts.memory,
+                    resolveFile: opts.resolveFile,
                     skills: opts.skills,
+                    clock: this.#clock,
                 });
         this.#handoffPolicy = opts.handoffPolicy;
         this.#summarizer = opts.summarizer ?? structuralSummarizer;
         this.#joinPolicy = opts.joinPolicy ?? defaultJoinPolicy;
         this.#stream = opts.stream ?? true;
         this.#recordRequests = opts.recordRequests ?? false;
-        this.#clock = opts.clock ?? systemClock;
     }
     /** Registers agents; chainable. */
     add(...agents) {
@@ -387,11 +389,12 @@ export class AgentRunner {
      * caching for a marginal gain.
      */
     async #autoRecall(state, env) {
-        const agent = this.registry.get(state.agentName);
-        const bindings = agent
-            .memoryBindings(state.context)
-            .filter((b) => b.autoRecall && b.autoRecall.query !== 'none');
-        if (!bindings.length || !shouldRecall(state)) {
+        const memory = this.services.memory;
+        const binding = this.registry.get(state.agentName).memoryBinding(state.context);
+        if (!memory || !binding?.autoRecall || binding.autoRecall.query === 'none') {
+            return state;
+        }
+        if (!shouldRecall(state)) {
             return state;
         }
         const input = Kernel.lastUserInput(state);
@@ -399,32 +402,28 @@ export class AgentRunner {
             return state;
         }
         const parts = await Promise.all(input.content.map((p) => p.type === 'text' ? this.services.payloads.get(p.text) : Promise.resolve('')));
-        const query = parts.filter(Boolean).join('\n');
-        if (!query) {
+        const text = parts.filter(Boolean).join('\n');
+        if (!text) {
             return state;
         }
-        let next = state;
-        for (const b of bindings) {
-            const hits = await this.services
-                .memoryStore(b.store)
-                .search(b.scope, { text: query, limit: b.autoRecall?.limit ?? 5 });
-            if (!hits.length) {
-                continue;
-            }
-            next = await Kernel.applyMemoryEffect(next, {
-                kind: 'recall',
-                store: b.store,
-                scope: b.scope,
-                query: { text: query, limit: b.autoRecall?.limit ?? 5 },
-                hits: hits.map((h) => ({
-                    id: h.record.id,
-                    score: h.score,
-                    revision: h.record.revision,
-                })),
-                content: renderMemories(hits),
-            }, env);
+        const query = { text, limit: binding.autoRecall.limit };
+        const rec = await memory.search(query, binding.sees);
+        const content = renderRecollection(rec);
+        if (!content) {
+            return state;
         }
-        return next;
+        return Kernel.applyMemoryEffect(state, {
+            kind: 'recall',
+            query,
+            seeds: [...rec.seeds],
+            nodes: rec.nodes.map((n) => ({
+                id: n.node.id,
+                kind: n.node.kind,
+                score: n.score,
+            })),
+            edges: [...rec.edges],
+            content,
+        }, env);
     }
     /**
      * Failure-tolerant on purpose: an unknown tool, malformed arguments or a

package/dist/services.d.ts

@@ -1,23 +1,40 @@
 import { PayloadResolver, type PayloadStore } from './payload.ts';
-import type { MemoryStore } from './memory.ts';
+import { type IdClock } from './ids.ts';
+import type { MemoryIndex } from './memory/index.ts';
 import type { SkillProvider } from './skills.ts';
 /**
- * The I/O the kernel is not allowed to do itself: payload resolution, memory
- * backends and skill catalogs. Held by the driver (runner or Temporal
+ * The I/O the kernel is not allowed to do itself: payload resolution, the
+ * memory graph and skill catalogs. Held by the driver (runner or Temporal
  * activity) and handed to the kernel and to tools explicitly, so nothing reads
  * ambient state.
+ *
+ * There is one memory, not a map of them: an agent sees a slice of the single
+ * graph through its `sees` mask, which is what makes a memory shareable
+ * between agents at all.
  */
 export declare class Services {
     #private;
     readonly payloads: PayloadResolver;
+    /** the one memory graph, when the project has one */
+    readonly memory?: MemoryIndex;
+    /**
+     * Turns a path the agent can see into a host path, for the one tool that
+     * needs it: remembering a file. Supplied by whoever built the workspace,
+     * because only it knows the mounts. Without it, files cannot be
+     * remembered — which is a refusal, not a crash.
+     */
+    readonly resolveFile?: (path: string) => string;
+    /** the driver's clock, so a tool that stamps a node stays replayable */
+    readonly clock: IdClock;
     constructor(opts?: {
         payloads?: PayloadResolver | PayloadStore;
-        memory?: MemoryStore[];
+        memory?: MemoryIndex;
         skills?: SkillProvider[];
+        clock?: IdClock;
+        resolveFile?: (path: string) => string;
     });
-    memoryStore(id: string): MemoryStore;
     skillProvider(id: string): SkillProvider;
-    hasMemory(id: string): boolean;
+    hasMemory(): boolean;
     hasSkills(id: string): boolean;
 }
 //# sourceMappingURL=services.d.ts.map

package/dist/services.js

@@ -1,32 +1,42 @@
 import { PayloadResolver } from "./payload.js";
+// The composition root is the one place in the core allowed to name a backend:
+// it has to fall back to something when the caller supplies no store.
+import { systemClock } from "./ids.js";
 import { InMemoryPayloadStore } from "./payload-stores/in-memory.js";
 /**
- * The I/O the kernel is not allowed to do itself: payload resolution, memory
- * backends and skill catalogs. Held by the driver (runner or Temporal
+ * The I/O the kernel is not allowed to do itself: payload resolution, the
+ * memory graph and skill catalogs. Held by the driver (runner or Temporal
  * activity) and handed to the kernel and to tools explicitly, so nothing reads
  * ambient state.
+ *
+ * There is one memory, not a map of them: an agent sees a slice of the single
+ * graph through its `sees` mask, which is what makes a memory shareable
+ * between agents at all.
  */
 export class Services {
     payloads;
-    #memory = new Map();
+    /** the one memory graph, when the project has one */
+    memory;
+    /**
+     * Turns a path the agent can see into a host path, for the one tool that
+     * needs it: remembering a file. Supplied by whoever built the workspace,
+     * because only it knows the mounts. Without it, files cannot be
+     * remembered — which is a refusal, not a crash.
+     */
+    resolveFile;
+    /** the driver's clock, so a tool that stamps a node stays replayable */
+    clock;
     #skills = new Map();
     constructor(opts = {}) {
         const p = opts.payloads ?? new InMemoryPayloadStore();
         this.payloads = p instanceof PayloadResolver ? p : new PayloadResolver(p);
-        for (const m of opts.memory ?? []) {
-            this.#memory.set(m.id, m);
-        }
+        this.memory = opts.memory;
+        this.resolveFile = opts.resolveFile;
+        this.clock = opts.clock ?? systemClock;
         for (const s of opts.skills ?? []) {
             this.#skills.set(s.id, s);
         }
     }
-    memoryStore(id) {
-        const s = this.#memory.get(id);
-        if (!s) {
-            throw new Error(`unknown memory store: ${id} (known: ${[...this.#memory.keys()]})`);
-        }
-        return s;
-    }
     skillProvider(id) {
         const p = this.#skills.get(id);
         if (!p) {
@@ -34,8 +44,8 @@ export class Services {
         }
         return p;
     }
-    hasMemory(id) {
-        return this.#memory.has(id);
+    hasMemory() {
+        return this.memory !== undefined;
     }
     hasSkills(id) {
         return this.#skills.has(id);