@zenera/neo 1.1.11 → 1.1.14

package/dist/memory/types.d.ts

@@ -0,0 +1,193 @@
+/**
+ * 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';
+    /** `load` is here rather than under recall: it hands the model whole bodies, and it writes. */
+    op: 'commit' | 'forget' | 'load';
+    /** sha256(runId, callId) — deterministic, so a replay is deduplicated */
+    opId: string;
+    /** nodes this op created, changed, removed or read in full */
+    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/project/config.d.ts

@@ -114,6 +114,34 @@ declare const embeddingSpec: z.ZodObject<{
     baseURL: z.ZodOptional<z.ZodString>;
     baseURLEnv: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
+/**
+ * What an agent may do with the project's one memory graph, and which slice of
+ * it it can see. Both lists are audience labels; `'*'` is the public slice and
+ * is always readable, so `sees` can only ever widen from there.
+ *
+ * `sees` and `writes` are here and not in any tool schema on purpose: an agent
+ * that could name its own audience could read another agent's slice just by
+ * asking for it.
+ */
+declare const memoryBinding: z.ZodObject<{
+    access: z.ZodDefault<z.ZodEnum<{
+        read: "read";
+        "read-write": "read-write";
+        full: "full";
+    }>>;
+    sees: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    writes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    autoRecall: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+        limit: z.ZodDefault<z.ZodInt>;
+    }, z.core.$strict>]>>;
+}, z.core.$strict>;
+/** Where the project's memory lives, and what vectorises it. */
+declare const memoryConfig: z.ZodObject<{
+    dir: z.ZodDefault<z.ZodString>;
+    embedding: z.ZodOptional<z.ZodString>;
+    kinds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    relations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
 /**
  * A Dockerfile to build instead of an image to pull, for the ordinary case the
  * `image:` key cannot serve: a project that needs two runtimes, or a pinned
@@ -272,6 +300,12 @@ export declare const projectSchema: z.ZodObject<{
         env: z.ZodOptional<z.ZodArray<z.ZodString>>;
         keys: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
+    memory: z.ZodOptional<z.ZodObject<{
+        dir: z.ZodDefault<z.ZodString>;
+        embedding: z.ZodOptional<z.ZodString>;
+        kinds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        relations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
     agents: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         description: z.ZodOptional<z.ZodString>;
@@ -282,8 +316,8 @@ export declare const projectSchema: z.ZodObject<{
         skills: z.ZodOptional<z.ZodObject<{
             provider: z.ZodOptional<z.ZodString>;
             discovery: z.ZodDefault<z.ZodEnum<{
-                search: "search";
                 none: "none";
+                search: "search";
                 index: "index";
             }>>;
             allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -294,6 +328,18 @@ export declare const projectSchema: z.ZodObject<{
             agents: z.ZodOptional<z.ZodArray<z.ZodString>>;
             maxBranches: z.ZodOptional<z.ZodInt>;
         }, z.core.$strict>]>>;
+        memory: z.ZodOptional<z.ZodPreprocess<z.ZodOptional<z.ZodObject<{
+            access: z.ZodDefault<z.ZodEnum<{
+                read: "read";
+                "read-write": "read-write";
+                full: "full";
+            }>>;
+            sees: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            writes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            autoRecall: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+                limit: z.ZodDefault<z.ZodInt>;
+            }, z.core.$strict>]>>;
+        }, z.core.$strict>>>>;
         sandbox: z.ZodOptional<z.ZodObject<{
             image: z.ZodOptional<z.ZodString>;
             build: z.ZodOptional<z.ZodObject<{
@@ -324,6 +370,8 @@ export type ModelConfig = z.infer<typeof modelSpec>;
 export type EmbeddingConfig = z.infer<typeof embeddingSpec>;
 export type SandboxConfig = z.infer<typeof sandbox>;
 export type SandboxBuildConfig = z.infer<typeof build>;
+export type MemoryConfig = z.infer<typeof memoryConfig>;
+export type MemoryBindingConfig = z.infer<typeof memoryBinding>;
 /**
  * Re-renders a zod failure as `agents.yaml: agents[1].skills.discovery — …`.
  *

package/dist/project/config.js

@@ -168,6 +168,52 @@ const forkBinding = z
     maxBranches: z.int().min(2).optional(),
 })
     .strict();
+/**
+ * What an agent may do with the project's one memory graph, and which slice of
+ * it it can see. Both lists are audience labels; `'*'` is the public slice and
+ * is always readable, so `sees` can only ever widen from there.
+ *
+ * `sees` and `writes` are here and not in any tool schema on purpose: an agent
+ * that could name its own audience could read another agent's slice just by
+ * asking for it.
+ */
+const memoryBinding = z
+    .object({
+    access: z.enum(['read', 'read-write', 'full']).default('read-write'),
+    /** audience labels this agent may read, on top of the public slice */
+    sees: z.array(name).optional(),
+    /** labels it may put on what it writes */
+    writes: z.array(name).optional(),
+    /**
+     * Recall before a turn that follows new user input, rather than before
+     * every call: recalling on every turn costs tokens and defeats prompt
+     * caching for a marginal gain. `false` leaves the agent the tools and
+     * lets it decide when to look.
+     */
+    autoRecall: z
+        .union([z.boolean(), z.object({ limit: z.int().positive().default(5) }).strict()])
+        .optional(),
+})
+    .strict();
+/** Where the project's memory lives, and what vectorises it. */
+const memoryConfig = z
+    .object({
+    /** relative to the project root */
+    dir: z.string().min(1).default('memory'),
+    /**
+     * A name from `embeddings:`. Without one, recall ranks by term overlap
+     * — which works, but only finds the words the agent happened to reuse.
+     */
+    embedding: modelRef.optional(),
+    /**
+     * Closed vocabularies. Absent means the built-in sets, which is almost
+     * always right: a kind nothing else understands is a kind no other
+     * agent can search for.
+     */
+    kinds: z.array(name).min(1).optional(),
+    relations: z.array(name).min(1).optional(),
+})
+    .strict();
 /**
  * The container command-line tools run in.
  *
@@ -275,6 +321,17 @@ const agent = z
     skills: skillsBinding.optional(),
     /** parallel sub-agents; `true` is the unrestricted form */
     fork: z.union([z.boolean(), forkBinding]).optional(),
+    /**
+     * The shared memory graph. `true` is the whole feature working the
+     * obvious way — read and write, with auto-recall on.
+     *
+     * Normalised before validation rather than unioned with a boolean, so
+     * that a misspelled key inside the block is reported as
+     * `agents[0].memory.scope` instead of collapsing to "invalid input".
+     */
+    memory: z
+        .preprocess((v) => (typeof v === 'boolean' ? (v ? {} : undefined) : v), memoryBinding.optional())
+        .optional(),
     /**
      * Overrides on the project's sandbox. An agent that overrides nothing
      * shares the container with everyone else, which is what a hand-off
@@ -316,6 +373,12 @@ export const projectSchema = z
     assets: z.string().min(1).optional(),
     /** the container `run_command` and friends execute in */
     sandbox: sandbox.optional(),
+    /**
+     * The one graph every agent's `memory:` binding is a view onto. Declare
+     * it to choose where it lives or what embeds it; an agent that opts in
+     * without this block gets the defaults.
+     */
+    memory: memoryConfig.optional(),
     agents: z.array(agent).min(1),
 })
     .strict();

package/dist/project/index.d.ts

@@ -1,4 +1,4 @@
-export { parseConfig, projectSchema, type AgentConfig, type EmbeddingConfig, type ModelConfig, type ProjectConfig, type ProviderConfig, type SandboxBuildConfig, type SandboxConfig, } from './config.ts';
-export { AgentProject, assetsDir, loadProject, projectRegistry, readProjectConfig, skillDirs, skillMounts, type ProjectOptions, type ProjectSource, } from './load.ts';
+export { parseConfig, projectSchema, type AgentConfig, type EmbeddingConfig, type MemoryBindingConfig, type MemoryConfig, type ModelConfig, type ProjectConfig, type ProviderConfig, type SandboxBuildConfig, type SandboxConfig, } from './config.ts';
+export { AgentProject, assetsDir, loadProject, memoryDir, projectRegistry, readProjectConfig, skillDirs, skillMounts, type ProjectOptions, type ProjectSource, } from './load.ts';
 export { projectDir, projectFile, projectPath, projectRoot } from './refs.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/project/index.js

@@ -1,4 +1,4 @@
 export { parseConfig, projectSchema, } from "./config.js";
-export { AgentProject, assetsDir, loadProject, projectRegistry, readProjectConfig, skillDirs, skillMounts, } from "./load.js";
+export { AgentProject, assetsDir, loadProject, memoryDir, projectRegistry, readProjectConfig, skillDirs, skillMounts, } from "./load.js";
 export { projectDir, projectFile, projectPath, projectRoot } from "./refs.js";
 //# sourceMappingURL=index.js.map