@zenera/neo 1.1.17 → 1.1.18

package/README.md

@@ -166,7 +166,7 @@ of surfacing three turns into a run as a confused model.
 [docs/projects.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/projects.md) ·
 [docs/agents-yaml.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/agents-yaml.md)
 · and
-[`examples/`](https://github.com/andreyryabov/ZeneraNeo/tree/main/examples) for
+[`examples/sdk/`](https://github.com/andreyryabov/ZeneraNeo/tree/main/examples/sdk) for
 eight worked demos, from a single agent to a project loaded entirely from a
 folder.
 

package/dist/memory/store.js

@@ -51,7 +51,7 @@ export class MemoryStore {
             const b = opts.embedding;
             if (a.model !== b.model || a.dimensions !== b.dimensions) {
                 throw new MemoryError(`this memory was embedded with ${a.model} (${a.dimensions}d), ` +
-                    `but ${b.model} (${b.dimensions}d) is configured`, 're-embed it with `zen memory reembed`, or restore the original model');
+                    `but ${b.model} (${b.dimensions}d) is configured`, 'restore the original model, or start a new memory');
             }
         }
         const graph = manifest
@@ -79,7 +79,7 @@ export class MemoryStore {
         if (held) {
             if (held.model !== embedding.model || held.dimensions !== embedding.dimensions) {
                 throw new MemoryError(`this memory was embedded with ${held.model} (${held.dimensions}d), ` +
-                    `but ${embedding.model} (${embedding.dimensions}d) is configured`, 're-embed it with `zen memory reembed`, or restore the original model');
+                    `but ${embedding.model} (${embedding.dimensions}d) is configured`, 'restore the original model, or start a new memory');
             }
             return;
         }

package/dist/project/load.d.ts

@@ -56,6 +56,13 @@ export interface ProjectOptions<TCtx = unknown> {
      */
     registry?: ModelRegistry;
     memory?: MemoryIndex;
+    /**
+     * Another directory to keep the memory graph in, relative to the project
+     * root when it is not absolute. Whoever sets it must mount that directory
+     * as `/memory` too, or the agent reads its remembered files from one graph
+     * and writes to another.
+     */
+    memoryDir?: string;
     /** turns an agent-visible path into a host path, so files can be remembered */
     resolveFile?: (path: string) => string;
     payloads?: PayloadStore;
@@ -166,8 +173,13 @@ export declare function projectRegistry<TCtx>(config: ProjectConfig, opts?: Proj
  * 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.
+ *
+ * `override` is the host pointing the run at another graph — `zen run
+ * --memory`. It answers for a project that declares no memory at all, because
+ * naming a directory is the declaration; the agents bound to it are still the
+ * ones that said `memory: true`.
  */
-export declare function memoryDir(root: string, config: ProjectConfig): string | undefined;
+export declare function memoryDir(root: string, config: ProjectConfig, override?: string): string | undefined;
 /**
  * Where each skill directory appears in the agent's namespace.
  *

package/dist/project/load.js

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { basename, join, relative, sep } from 'node:path';
+import { basename, join, relative, resolve, sep } from 'node:path';
 import { Agent, AgentRegistry } from "../agent.js";
 import { RunStream } from "../events.js";
 import { MemoryIndex } from "../memory/index.js";
@@ -74,7 +74,7 @@ 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));
+    const memory = opts.memory ?? (await openMemory(root, config, embedders, opts.memoryDir));
     return new AgentProject({
         root,
         source,
@@ -392,8 +392,16 @@ function memoryFor(spec) {
  * 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.
+ *
+ * `override` is the host pointing the run at another graph — `zen run
+ * --memory`. It answers for a project that declares no memory at all, because
+ * naming a directory is the declaration; the agents bound to it are still the
+ * ones that said `memory: true`.
  */
-export function memoryDir(root, config) {
+export function memoryDir(root, config, override) {
+    if (override) {
+        return resolve(root, override);
+    }
     if (!config.memory && !config.agents.some((a) => a.memory)) {
         return undefined;
     }
@@ -405,8 +413,8 @@ export function memoryDir(root, config) {
  * 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);
+async function openMemory(root, config, embedders, override) {
+    const dir = memoryDir(root, config, override);
     if (!dir) {
         return undefined;
     }

package/dist/prompt.d.ts

@@ -58,6 +58,8 @@ export interface ComposedPrompt {
     /** the editable contributors, in the order they were rendered */
     sources: PromptSource[];
 }
+/** `&`, `<` and `"` are the three that would end the attribute or the tag. */
+export declare function attribute(value: string): string;
 /**
  * Renders the authored parts, then the kernel's derived text, into one string —
  * and reports which documents went into it.

package/dist/prompt.js

@@ -22,7 +22,7 @@ export function promptFile(path, section, src) {
 }
 const SEPARATOR = '\n\n';
 /** `&`, `<` and `"` are the three that would end the attribute or the tag. */
-function attribute(value) {
+export function attribute(value) {
     return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/"/g, '&quot;');
 }
 /**

package/dist/skill-providers/file.js

@@ -1,5 +1,5 @@
 import { readFile, readdir } from 'node:fs/promises';
-import { basename, join, resolve } from 'node:path';
+import { basename, join, relative, resolve } from 'node:path';
 import { selectTools } from "../types.js";
 // ---------------------------------------------------------------------------
 // Filesystem-backed skill provider
@@ -83,6 +83,7 @@ export class FileSkillProvider {
             ...entry.summary,
             content: entry.content,
             file: entry.file,
+            src: entry.src,
             ...(tools.length ? { tools } : {}),
             ...(entry.at ? { path: entry.at } : {}),
         };
@@ -122,19 +123,20 @@ export class FileSkillProvider {
                 // Only a folder skill has files of its own to point at, and
                 // only when the host said where the directory can be reached.
                 const at = folder && dir.at ? `${dir.at}/${basename(folder)}` : undefined;
-                const entry = parse(raw, base, file, folder, at);
+                const entry = parse(raw, base, file, relative(dir.path, file), folder, at);
                 index.set(entry.summary.name, entry);
             }
         }
         return index;
     }
 }
-function parse(raw, base, file, folder, at) {
+function parse(raw, base, file, src, folder, at) {
     const { data, body } = frontmatter(raw);
     const tags = toList(data.tags);
     const tools = toList(data.tools);
     return {
         file,
+        src,
         folder,
         ...(at ? { at } : {}),
         content: body,

package/dist/skills.d.ts

@@ -33,6 +33,13 @@ export interface Skill extends SkillSummary {
     path?: string;
     /** absolute path of the source file, if known (set by file-backed providers) */
     file?: string;
+    /**
+     * The source document *as the model is told it*, written onto the block as
+     * `src`. Deliberately not `file`: that one is absolute, so it would put a
+     * home directory in the prompt and give two machines two different cache
+     * prefixes for the same catalog.
+     */
+    src?: string;
 }
 export interface SkillProvider {
     readonly id: string;

package/dist/skills.js

@@ -1,4 +1,5 @@
 import { hash } from "./payload.js";
+import { attribute } from "./prompt.js";
 import { projected } from "./trajectory.js";
 import { SKILL_LOAD_TOOL, SKILL_SEARCH_TOOL, tool, withEffects, } from "./types.js";
 export function skillContentHash(s) {
@@ -7,15 +8,21 @@ export function skillContentHash(s) {
 export function renderSkills(skills) {
     return skills
         .map((s) => {
-        const head = `## Skill: ${s.name}${s.version ? ` (${s.version})` : ''}`;
+        const attrs = [
+            ` name="${attribute(s.name)}"`,
+            s.version ? ` version="${attribute(s.version)}"` : '',
+            // Same contract as a prompt block's `src`: the document to edit,
+            // under a name that is the same on every machine.
+            s.src ? ` src="${attribute(s.src)}"` : '',
+        ].join('');
         // One line, and only when the files are reachable. Without it the
         // model has the instructions and no way to act on the half of them
         // that names a file.
         const where = s.path
-            ? `\nThis skill's files are at ${s.path}, read-only. Paths written in it are ` +
-                'relative to that directory.\n'
+            ? `This skill's files are at ${s.path}, read-only. Paths written in it are ` +
+                'relative to that directory.\n\n'
             : '';
-        return `${head}${where}\n${s.content}`;
+        return `<skill${attrs}>\n${where}${s.content}\n</skill>`;
     })
         .join('\n\n');
 }

package/package.json

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