@ziggs-ai/agent-sdk 0.38.12 → 0.38.13

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.38.13
+
+- Notes kept with an operator key are agent-private artifacts, so they survive a restart and are not announced.
+
 ## Unreleased — agent vocabulary and lifecycle (breaking)
 
 - `Agent` names the body returned by `createAgent`; decision engines are `ZiggsBrain` and `ClaudeBrain`. See the README migration table.

package/dist/Agent.d.ts

@@ -131,9 +131,10 @@ export interface AgentOptions {
     /** Per-agent session keying. Defaults to `(n) => n.chatId`. */
     sessionResolver?: SessionResolver;
     /**
-     * Agent-private long-term memory. Operator-provided. Default: a fresh
-     * `InMemoryStore` (non-durable; lost on process restart). For durability,
-     * pass `new FileMemoryStore(path)` or your own implementation.
+     * Agent-private long-term memory. With an operator key and agent id, the
+     * default is an agent-private artifact store, so a note survives a restart.
+     * Pass a store to keep notes somewhere else. Without credentials, the
+     * default is still an in-memory store.
      * Each wake is given a hire-scoped view of this store; agent key shapes
      * do not change.
      */

package/dist/Agent.js

@@ -24,7 +24,8 @@ import { createZiggsEffectHandler } from './platform/ZiggsEffectHandler.js';
 import { normalizeIncomingEvent } from './ingress/normalizeIncoming.js';
 import { PromptBuilder } from './runtime/PromptBuilder.js';
 import { removeTaskBook } from './runtime/taskBookkeeping.js';
-import { InMemoryStore, hireIdsFromEvent, memorySectionForWake, partitionMemoryStore, uniqueHireIds, } from './memory/MemoryStore.js';
+import { hireIdsFromEvent, memorySectionForWake, partitionMemoryStore, uniqueHireIds, } from './memory/MemoryStore.js';
+import { memoryStoreFor } from './memory/ArtifactMemoryStore.js';
 import { ToolManager } from './tools/ToolManager.js';
 import { toolName } from './tools/defineTool.js';
 import { PROTOCOL_TOOLS } from './platform/tools/tier1/protocolTools.js';
@@ -270,7 +271,11 @@ export class Agent {
                 (isClaudeCognition(resolved.cognition)
                     ? Number(process.env.CLAUDE_SDK_TICK_TIMEOUT_MS ?? 300_000)
                     : 120_000);
-        this.memory = options.memory ?? new InMemoryStore();
+        this.memory = memoryStoreFor({
+            memory: options.memory,
+            operatorKey: options.operatorKey,
+            agentId: options.agentId,
+        });
         this.sessionStore = options.sessionStore ?? null;
         this._validate();
         this.pollRunner = createDeclaredPollRunner(this.options, {

package/dist/index.d.ts

@@ -72,6 +72,7 @@ export { CLAUDE_SDK_TOOLS } from './brain/claudeSdkTools.js';
 export { hostedModelTools, isHostedDeferred, hostedToolLane } from './brain/hostedToolSurface.js';
 export { PROTOCOL_TOOL_NAMES, PROTOCOL_TOOL_TO_OPERATION, mapProtocolToolToOperation, isProtocolToolName } from './tasks/protocolRegistry.js';
 export { InMemoryStore, FileMemoryStore } from './memory/MemoryStore.js';
+export { ArtifactMemoryStore, memoryStoreFor } from './memory/ArtifactMemoryStore.js';
 export type { MemoryStore } from './memory/MemoryStore.js';
 export type { SessionStore } from './Agent.js';
 export { classifyIncomingEvent } from './context/classifyEnvelope.js';

package/dist/index.js

@@ -86,6 +86,7 @@ export { CLAUDE_SDK_TOOLS } from './brain/claudeSdkTools.js';
 export { hostedModelTools, isHostedDeferred, hostedToolLane } from './brain/hostedToolSurface.js';
 export { PROTOCOL_TOOL_NAMES, PROTOCOL_TOOL_TO_OPERATION, mapProtocolToolToOperation, isProtocolToolName } from './tasks/protocolRegistry.js';
 export { InMemoryStore, FileMemoryStore } from './memory/MemoryStore.js';
+export { ArtifactMemoryStore, memoryStoreFor } from './memory/ArtifactMemoryStore.js';
 export { classifyIncomingEvent } from './context/classifyEnvelope.js';
 export { buildContextUpdates, CONTEXT_RESET } from './context/applyEffects.js';
 export { getBatchEvents, isTaskResultRelevantToAgent } from './context/batch.js';

package/dist/memory/ArtifactMemoryStore.d.ts

@@ -0,0 +1,61 @@
+import { type MemoryStore } from './MemoryStore.js';
+/**
+ * The artifact calls a note store makes. Production uses {@link ArtifactsClient}.
+ * Tests pass a fake. No chat, agreement, or task: a note is not a deliverable
+ * and is not announced.
+ */
+export interface NoteArtifactClient {
+    writeStrict(input: {
+        text: string;
+        name: string;
+        contentType: string;
+        visibility: 'agent-private';
+    }): Promise<{
+        artifactId?: string;
+    }>;
+    list(query: {
+        authoredBy: 'me';
+    }, opts?: {
+        after?: string;
+        limit?: number;
+    }): Promise<{
+        artifacts: Array<{
+            name?: string | null;
+            text: string;
+            timestamp: string;
+            contentType: string;
+            visibility: string;
+        }>;
+        latestSequence: string | null;
+    }>;
+}
+/**
+ * Notes that survive a process restart.
+ *
+ * Each note is an agent-private artifact with no container. A later write of
+ * the same key stores a newer row; reads return that row. An agent cannot
+ * delete an artifact, so older rows stay and are not what a read returns.
+ * The artifact id never leaves this store.
+ */
+export declare class ArtifactMemoryStore implements MemoryStore {
+    private readonly client;
+    private loaded;
+    constructor(opts: {
+        operatorKey: string;
+        agentId: string;
+        client?: NoteArtifactClient;
+    });
+    get(key: string): Promise<unknown | undefined>;
+    put(key: string, value: unknown): Promise<void>;
+    list(prefix: string): Promise<{
+        key: string;
+        value: unknown;
+    }[]>;
+    private notes;
+}
+/** The store a host gets when the caller did not pass one. */
+export declare function memoryStoreFor(options: {
+    memory?: MemoryStore;
+    operatorKey?: string;
+    agentId?: string;
+}): MemoryStore;

package/dist/memory/ArtifactMemoryStore.js

@@ -0,0 +1,109 @@
+import { createHash } from 'node:crypto';
+import { ArtifactsClient } from '@ziggs-ai/api-client';
+import { InMemoryStore, } from './MemoryStore.js';
+const NOTE_CONTENT_TYPE = 'agent-note';
+const NOTE_NAME_PREFIX = 'mem:';
+const PAGE_LIMIT = 100;
+const MAX_PAGES = 30;
+function noteName(key) {
+    const digest = createHash('sha256').update(key).digest('hex').slice(0, 32);
+    return `${NOTE_NAME_PREFIX}${digest}`;
+}
+function parseNote(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed?.key !== 'string')
+            return null;
+        return { key: parsed.key, value: parsed.value };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Notes that survive a process restart.
+ *
+ * Each note is an agent-private artifact with no container. A later write of
+ * the same key stores a newer row; reads return that row. An agent cannot
+ * delete an artifact, so older rows stay and are not what a read returns.
+ * The artifact id never leaves this store.
+ */
+export class ArtifactMemoryStore {
+    client;
+    loaded = null;
+    constructor(opts) {
+        this.client =
+            opts.client ??
+                new ArtifactsClient(opts.operatorKey, opts.agentId);
+    }
+    async get(key) {
+        const notes = await this.notes();
+        return notes.get(key)?.value;
+    }
+    async put(key, value) {
+        const timestamp = new Date().toISOString();
+        await this.client.writeStrict({
+            text: JSON.stringify({ key, value }),
+            name: noteName(key),
+            contentType: NOTE_CONTENT_TYPE,
+            visibility: 'agent-private',
+        });
+        const notes = await this.notes();
+        notes.set(key, { key, value, timestamp });
+    }
+    async list(prefix) {
+        const notes = await this.notes();
+        const out = [];
+        for (const note of notes.values()) {
+            if (note.key.startsWith(prefix))
+                out.push({ key: note.key, value: note.value });
+        }
+        return out;
+    }
+    async notes() {
+        if (this.loaded)
+            return this.loaded;
+        const byKey = new Map();
+        let after;
+        for (let page = 0; page < MAX_PAGES; page++) {
+            const result = await this.client.list({ authoredBy: 'me' }, { after, limit: PAGE_LIMIT });
+            for (const row of result.artifacts) {
+                if (row.contentType !== NOTE_CONTENT_TYPE)
+                    continue;
+                if (row.visibility !== 'agent-private')
+                    continue;
+                if (!row.name?.startsWith(NOTE_NAME_PREFIX))
+                    continue;
+                const parsed = parseNote(row.text);
+                if (!parsed)
+                    continue;
+                const previous = byKey.get(parsed.key);
+                if (!previous || row.timestamp >= previous.timestamp) {
+                    byKey.set(parsed.key, {
+                        key: parsed.key,
+                        value: parsed.value,
+                        timestamp: row.timestamp,
+                    });
+                }
+            }
+            if (result.artifacts.length < PAGE_LIMIT || !result.latestSequence || result.latestSequence === after) {
+                break;
+            }
+            after = result.latestSequence;
+        }
+        this.loaded = byKey;
+        return byKey;
+    }
+}
+/** The store a host gets when the caller did not pass one. */
+export function memoryStoreFor(options) {
+    if (options.memory)
+        return options.memory;
+    if (options.operatorKey && options.agentId) {
+        return new ArtifactMemoryStore({
+            operatorKey: options.operatorKey,
+            agentId: options.agentId,
+        });
+    }
+    return new InMemoryStore();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.38.12",
+  "version": "0.38.13",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "homepage": "https://ziggsai.com/docs",
   "bugs": {
@@ -30,7 +30,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.284",
     "@anthropic-ai/sdk": "^0.110.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "0.37.14",
+    "@ziggs-ai/api-client": "0.37.16",
     "@ziggs-ai/contracts": "^0.23.3",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",