@persistio/openclaw-plugin 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# @persistio/openclaw-plugin
+
+OpenClaw plugin for [Persistio](https://persistio.ai) — persistent semantic memory for AI agents.
+
+Hooks into OpenClaw's `before_prompt_build` and `agent_end` events to automatically recall relevant memories into every prompt and ingest new conversation turns after each run. Exposes `memory_search`, `memory_add`, `memory_delete`, and `memory_list` as agent tools.
+
+## Requirements
+
+- A running [Persistio](https://github.com/chriscoveyduck/persistio) instance (`api.persistio.ai` or self-hosted)
+- OpenClaw `>=2026.3.24-beta.2`
+
+## Installation
+
+```bash
+npm install -g @persistio/openclaw-plugin
+```
+
+Then register it in your OpenClaw config:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "persistio": {
+        "package": "@persistio/openclaw-plugin",
+        "config": {
+          "baseURL": "https://api.persistio.ai",
+          "apiKey": "your-vault-api-key"
+        }
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+| Option | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `baseURL` | string | ✅ | — | Base URL of your Persistio instance |
+| `apiKey` | string | ✅ | — | Vault API key |
+| `tokenBudget` | number | | `2000` | Max tokens to inject into the system prompt |
+| `recallTopK` | number | | `10` | Number of memories to retrieve per recall |
+| `recallTimeout` | number | | `5000` | HTTP timeout for recall requests (ms) |
+
+## Tools exposed
+
+| Tool | Description |
+|---|---|
+| `memory_search` | Search memories by semantic query |
+| `memory_add` | Manually store a fact |
+| `memory_delete` | Delete a memory by ID |
+| `memory_list` | List all memories in the vault |
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,31 @@
+export interface PersistioConfig {
+    baseURL: string;
+    apiKey: string;
+    tokenBudget: number;
+    recallTopK: number;
+    recallTimeout: number;
+}
+export interface PersistioMemory {
+    id: string;
+    data: string;
+    subject: string;
+    similarity?: number;
+    categories: string[];
+    confidence: number;
+}
+export declare class PersistioClient {
+    private readonly baseURL;
+    private readonly apiKey;
+    private readonly recallTopK;
+    private readonly recallTimeout;
+    constructor(config: PersistioConfig);
+    private headers;
+    recall(query: string): Promise<PersistioMemory[]>;
+    ingest(sessionId: string, chunks: Array<{
+        role: string;
+        content: string;
+    }>): Promise<void>;
+    addMemory(data: string, subject: string): Promise<void>;
+    deleteMemory(id: string): Promise<void>;
+    listMemories(): Promise<PersistioMemory[]>;
+}

package/dist/client.js

@@ -0,0 +1,67 @@
+export class PersistioClient {
+    baseURL;
+    apiKey;
+    recallTopK;
+    recallTimeout;
+    constructor(config) {
+        this.baseURL = config.baseURL.replace(/\/$/, '');
+        this.apiKey = config.apiKey;
+        this.recallTopK = config.recallTopK;
+        this.recallTimeout = config.recallTimeout;
+    }
+    headers() {
+        return {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${this.apiKey}`,
+        };
+    }
+    async recall(query) {
+        const res = await fetch(`${this.baseURL}/v1/recall`, {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify({ query, top_k: this.recallTopK }),
+            signal: AbortSignal.timeout(this.recallTimeout),
+        });
+        if (!res.ok)
+            throw new Error(`Persistio recall failed: ${res.status}`);
+        const data = await res.json();
+        return data.memories ?? [];
+    }
+    async ingest(sessionId, chunks) {
+        if (chunks.length === 0)
+            return;
+        const res = await fetch(`${this.baseURL}/v1/ingest`, {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify({ session_id: sessionId, chunks }),
+        });
+        if (!res.ok)
+            throw new Error(`Persistio ingest failed: ${res.status}`);
+    }
+    async addMemory(data, subject) {
+        const res = await fetch(`${this.baseURL}/v1/memories`, {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify({ data, subject }),
+        });
+        if (!res.ok)
+            throw new Error(`Persistio addMemory failed: ${res.status}`);
+    }
+    async deleteMemory(id) {
+        const res = await fetch(`${this.baseURL}/v1/memories/${id}`, {
+            method: 'DELETE',
+            headers: this.headers(),
+        });
+        if (!res.ok)
+            throw new Error(`Persistio deleteMemory failed: ${res.status}`);
+    }
+    async listMemories() {
+        const res = await fetch(`${this.baseURL}/v1/memories`, {
+            headers: this.headers(),
+        });
+        if (!res.ok)
+            throw new Error(`Persistio listMemories failed: ${res.status}`);
+        const data = await res.json();
+        return data.items ?? [];
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginConfigSchema;
+    register: NonNullable<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["register"]>;
+} & Pick<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition, "kind" | "reload" | "nodeHostCommands" | "securityAuditCollectors">;
+export default _default;

package/dist/index.js

@@ -0,0 +1,187 @@
+import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry';
+import { Type } from '@sinclair/typebox';
+import { PersistioClient } from './client.js';
+function resolveConfig(raw) {
+    const c = (raw ?? {});
+    return {
+        baseURL: typeof c['baseURL'] === 'string' ? c['baseURL'] : '',
+        apiKey: typeof c['apiKey'] === 'string' ? c['apiKey'] : '',
+        tokenBudget: typeof c['tokenBudget'] === 'number' ? c['tokenBudget'] : 2000,
+        recallTopK: typeof c['recallTopK'] === 'number' ? c['recallTopK'] : 10,
+        recallTimeout: typeof c['recallTimeout'] === 'number' ? c['recallTimeout'] : 5000,
+    };
+}
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+function buildMemoryBlock(memories, budget) {
+    if (memories.length === 0)
+        return '';
+    const lines = ['## Relevant memories from past conversations'];
+    let used = estimateTokens(lines[0]);
+    for (const m of memories) {
+        const line = `- ${m.data} [${m.subject}]`;
+        const cost = estimateTokens(line);
+        if (used + cost > budget)
+            break;
+        lines.push(line);
+        used += cost;
+    }
+    return lines.length > 1 ? lines.join('\n') : '';
+}
+/** Extract plain text from a pi-agent-core message content array */
+function extractTextFromMessage(msg) {
+    if (typeof msg !== 'object' || msg === null)
+        return null;
+    const m = msg;
+    const role = m['role'];
+    if (role !== 'user' && role !== 'assistant')
+        return null;
+    const content = m['content'];
+    if (!Array.isArray(content)) {
+        // Some messages have content as a plain string
+        if (typeof content === 'string' && content.length > 0)
+            return content;
+        return null;
+    }
+    const parts = [];
+    for (const block of content) {
+        if (typeof block === 'object' && block !== null) {
+            const b = block;
+            if (b['type'] === 'text' && typeof b['text'] === 'string' && b['text'].length > 0) {
+                parts.push(b['text']);
+            }
+        }
+    }
+    return parts.length > 0 ? parts.join(' ') : null;
+}
+export default definePluginEntry({
+    id: 'openclaw-persistio',
+    name: 'Persistio Memory',
+    description: 'Persistent semantic memory for OpenClaw via Persistio',
+    register(api) {
+        const cfg = resolveConfig(api.pluginConfig);
+        if (!cfg.baseURL || !cfg.apiKey) {
+            api.logger?.warn?.('openclaw-persistio: baseURL and apiKey are required. Plugin disabled.');
+            return;
+        }
+        const client = new PersistioClient(cfg);
+        // -------------------------------------------------------------------------
+        // before_prompt_build — recall relevant memories and inject into context
+        // Event: { prompt: string, messages: unknown[] }
+        // Return: { appendSystemContext?: string }
+        // -------------------------------------------------------------------------
+        api.on('before_prompt_build', async (event) => {
+            try {
+                // Use the current prompt as the recall query
+                const query = event.prompt?.slice(0, 500) || 'recent context';
+                const memories = await client.recall(query);
+                if (memories.length === 0)
+                    return;
+                const block = buildMemoryBlock(memories, cfg.tokenBudget);
+                if (!block)
+                    return;
+                return { appendSystemContext: block };
+            }
+            catch (err) {
+                api.logger?.warn?.(`openclaw-persistio: recall error: ${String(err)}`);
+            }
+        });
+        // -------------------------------------------------------------------------
+        // agent_end — ingest new turn messages (fire and forget)
+        // Event: { runId?, messages: unknown[], success: boolean, error?, durationMs? }
+        // Observation only — no return value.
+        // -------------------------------------------------------------------------
+        api.on('agent_end', async (event) => {
+            try {
+                const sessionId = event.runId ?? 'unknown-session';
+                const chunks = [];
+                for (const msg of event.messages) {
+                    const m = msg;
+                    const role = m['role'];
+                    if (role !== 'user' && role !== 'assistant')
+                        continue;
+                    const text = extractTextFromMessage(msg);
+                    if (text && text.length > 0) {
+                        chunks.push({ role: role, content: text });
+                    }
+                }
+                if (chunks.length === 0)
+                    return;
+                // Fire and forget — agent_end is async but result is ignored
+                client.ingest(sessionId, chunks).catch((err) => {
+                    api.logger?.warn?.(`openclaw-persistio: ingest error: ${String(err)}`);
+                });
+            }
+            catch (err) {
+                api.logger?.warn?.(`openclaw-persistio: agent_end error: ${String(err)}`);
+            }
+        });
+        // -------------------------------------------------------------------------
+        // Tools
+        // Verified signature: api.registerTool({ name, description, parameters, execute }, opts?)
+        // execute(_id: string, params: unknown): Promise<AgentToolResult>
+        // AgentToolResult: { content: Array<{ type: "text", text: string }>, details: unknown }
+        // -------------------------------------------------------------------------
+        api.registerTool({
+            name: 'memory_search',
+            label: 'Search Memory',
+            description: 'Search persistent memory for relevant facts from past conversations.',
+            parameters: Type.Object({
+                query: Type.String({ description: 'What to search for' }),
+                top_k: Type.Optional(Type.Number({ description: 'Max results to return' })),
+            }),
+            async execute(_id, params) {
+                const p = params;
+                const overrideTopK = typeof p.top_k === 'number' ? p.top_k : cfg.recallTopK;
+                const overrideCfg = { ...cfg, recallTopK: overrideTopK };
+                const c = new PersistioClient(overrideCfg);
+                const memories = await c.recall(p.query);
+                const text = memories.length > 0
+                    ? memories.map(m => `- ${m.data} [${m.subject}]`).join('\n')
+                    : 'No memories found.';
+                return { content: [{ type: 'text', text }], details: null };
+            },
+        });
+        api.registerTool({
+            name: 'memory_add',
+            label: 'Add Memory',
+            description: 'Manually store a fact in persistent memory.',
+            parameters: Type.Object({
+                data: Type.String({ description: 'The fact to remember' }),
+                subject: Type.String({ description: 'The entity or topic this fact is about' }),
+            }),
+            async execute(_id, params) {
+                const p = params;
+                await client.addMemory(p.data, p.subject);
+                return { content: [{ type: 'text', text: 'Memory stored.' }], details: null };
+            },
+        });
+        api.registerTool({
+            name: 'memory_delete',
+            label: 'Delete Memory',
+            description: 'Delete a specific memory by its ID.',
+            parameters: Type.Object({
+                id: Type.String({ description: 'The memory ID to delete' }),
+            }),
+            async execute(_id, params) {
+                const p = params;
+                await client.deleteMemory(p.id);
+                return { content: [{ type: 'text', text: 'Memory deleted.' }], details: null };
+            },
+        }, { optional: true });
+        api.registerTool({
+            name: 'memory_list',
+            label: 'List Memories',
+            description: 'List all stored memories.',
+            parameters: Type.Object({}),
+            async execute(_id, _params) {
+                const memories = await client.listMemories();
+                const text = memories.length > 0
+                    ? memories.map(m => `[${m.id}] ${m.data} (${m.subject})`).join('\n')
+                    : 'No memories stored.';
+                return { content: [{ type: 'text', text }], details: null };
+            },
+        }, { optional: true });
+    },
+});

package/openclaw.plugin.json

@@ -0,0 +1,25 @@
+{
+  "id": "@persistio/openclaw-plugin",
+  "name": "Persistio Memory",
+  "description": "Persistent semantic memory for OpenClaw via Persistio",
+  "version": "0.1.0",
+  "kind": "memory",
+  "activation": {
+    "onStartup": true
+  },
+  "contracts": {
+    "tools": ["memory_search", "memory_add", "memory_delete", "memory_list"]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "baseURL": { "type": "string" },
+      "apiKey": { "type": "string" },
+      "tokenBudget": { "type": "number" },
+      "recallTopK": { "type": "number" },
+      "recallTimeout": { "type": "number" }
+    },
+    "required": ["baseURL", "apiKey"]
+  }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@persistio/openclaw-plugin",
+  "version": "0.1.0",
+  "description": "OpenClaw plugin for Persistio — persistent semantic memory for AI agents",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "license": "MIT",
+  "author": "Chris Coveyduck",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/persistio/openclaw-persistio.git"
+  },
+  "homepage": "https://persistio.ai",
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "memory",
+    "ai",
+    "agents",
+    "persistio"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "runtimeExtensions": [
+      "./dist/index.js"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.3.24-beta.2",
+      "minGatewayVersion": "2026.3.24-beta.2"
+    }
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^22.0.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.24-beta.2"
+  }
+}

package/src/client.ts

@@ -0,0 +1,85 @@
+export interface PersistioConfig {
+  baseURL: string;
+  apiKey: string;
+  tokenBudget: number;
+  recallTopK: number;
+  recallTimeout: number;
+}
+
+export interface PersistioMemory {
+  id: string;
+  data: string;
+  subject: string;
+  similarity?: number;
+  categories: string[];
+  confidence: number;
+}
+
+export class PersistioClient {
+  private readonly baseURL: string;
+  private readonly apiKey: string;
+  private readonly recallTopK: number;
+  private readonly recallTimeout: number;
+
+  constructor(config: PersistioConfig) {
+    this.baseURL = config.baseURL.replace(/\/$/, '');
+    this.apiKey = config.apiKey;
+    this.recallTopK = config.recallTopK;
+    this.recallTimeout = config.recallTimeout;
+  }
+
+  private headers(): Record<string, string> {
+    return {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${this.apiKey}`,
+    };
+  }
+
+  async recall(query: string): Promise<PersistioMemory[]> {
+    const res = await fetch(`${this.baseURL}/v1/recall`, {
+      method: 'POST',
+      headers: this.headers(),
+      body: JSON.stringify({ query, top_k: this.recallTopK }),
+      signal: AbortSignal.timeout(this.recallTimeout),
+    });
+    if (!res.ok) throw new Error(`Persistio recall failed: ${res.status}`);
+    const data = await res.json() as { memories: PersistioMemory[] };
+    return data.memories ?? [];
+  }
+
+  async ingest(sessionId: string, chunks: Array<{ role: string; content: string }>): Promise<void> {
+    if (chunks.length === 0) return;
+    const res = await fetch(`${this.baseURL}/v1/ingest`, {
+      method: 'POST',
+      headers: this.headers(),
+      body: JSON.stringify({ session_id: sessionId, chunks }),
+    });
+    if (!res.ok) throw new Error(`Persistio ingest failed: ${res.status}`);
+  }
+
+  async addMemory(data: string, subject: string): Promise<void> {
+    const res = await fetch(`${this.baseURL}/v1/memories`, {
+      method: 'POST',
+      headers: this.headers(),
+      body: JSON.stringify({ data, subject }),
+    });
+    if (!res.ok) throw new Error(`Persistio addMemory failed: ${res.status}`);
+  }
+
+  async deleteMemory(id: string): Promise<void> {
+    const res = await fetch(`${this.baseURL}/v1/memories/${id}`, {
+      method: 'DELETE',
+      headers: this.headers(),
+    });
+    if (!res.ok) throw new Error(`Persistio deleteMemory failed: ${res.status}`);
+  }
+
+  async listMemories(): Promise<PersistioMemory[]> {
+    const res = await fetch(`${this.baseURL}/v1/memories`, {
+      headers: this.headers(),
+    });
+    if (!res.ok) throw new Error(`Persistio listMemories failed: ${res.status}`);
+    const data = await res.json() as { items: PersistioMemory[] };
+    return data.items ?? [];
+  }
+}

package/src/index.ts

@@ -0,0 +1,193 @@
+import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry';
+import { Type } from '@sinclair/typebox';
+import { PersistioClient, type PersistioConfig } from './client.js';
+
+function resolveConfig(raw: unknown): PersistioConfig {
+  const c = (raw ?? {}) as Record<string, unknown>;
+  return {
+    baseURL: typeof c['baseURL'] === 'string' ? c['baseURL'] : '',
+    apiKey: typeof c['apiKey'] === 'string' ? c['apiKey'] : '',
+    tokenBudget: typeof c['tokenBudget'] === 'number' ? c['tokenBudget'] : 2000,
+    recallTopK: typeof c['recallTopK'] === 'number' ? c['recallTopK'] : 10,
+    recallTimeout: typeof c['recallTimeout'] === 'number' ? c['recallTimeout'] : 5000,
+  };
+}
+
+function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+function buildMemoryBlock(memories: import('./client.js').PersistioMemory[], budget: number): string {
+  if (memories.length === 0) return '';
+  const lines: string[] = ['## Relevant memories from past conversations'];
+  let used = estimateTokens(lines[0]!);
+  for (const m of memories) {
+    const line = `- ${m.data} [${m.subject}]`;
+    const cost = estimateTokens(line);
+    if (used + cost > budget) break;
+    lines.push(line);
+    used += cost;
+  }
+  return lines.length > 1 ? lines.join('\n') : '';
+}
+
+/** Extract plain text from a pi-agent-core message content array */
+function extractTextFromMessage(msg: unknown): string | null {
+  if (typeof msg !== 'object' || msg === null) return null;
+  const m = msg as Record<string, unknown>;
+  const role = m['role'];
+  if (role !== 'user' && role !== 'assistant') return null;
+  const content = m['content'];
+  if (!Array.isArray(content)) {
+    // Some messages have content as a plain string
+    if (typeof content === 'string' && content.length > 0) return content;
+    return null;
+  }
+  const parts: string[] = [];
+  for (const block of content) {
+    if (typeof block === 'object' && block !== null) {
+      const b = block as Record<string, unknown>;
+      if (b['type'] === 'text' && typeof b['text'] === 'string' && b['text'].length > 0) {
+        parts.push(b['text']);
+      }
+    }
+  }
+  return parts.length > 0 ? parts.join(' ') : null;
+}
+
+export default definePluginEntry({
+  id: 'openclaw-persistio',
+  name: 'Persistio Memory',
+  description: 'Persistent semantic memory for OpenClaw via Persistio',
+
+  register(api) {
+    const cfg = resolveConfig(api.pluginConfig);
+
+    if (!cfg.baseURL || !cfg.apiKey) {
+      api.logger?.warn?.('openclaw-persistio: baseURL and apiKey are required. Plugin disabled.');
+      return;
+    }
+
+    const client = new PersistioClient(cfg);
+
+    // -------------------------------------------------------------------------
+    // before_prompt_build — recall relevant memories and inject into context
+    // Event: { prompt: string, messages: unknown[] }
+    // Return: { appendSystemContext?: string }
+    // -------------------------------------------------------------------------
+    api.on('before_prompt_build', async (event) => {
+      try {
+        // Use the current prompt as the recall query
+        const query = event.prompt?.slice(0, 500) || 'recent context';
+        const memories = await client.recall(query);
+        if (memories.length === 0) return;
+        const block = buildMemoryBlock(memories, cfg.tokenBudget);
+        if (!block) return;
+        return { appendSystemContext: block };
+      } catch (err) {
+        api.logger?.warn?.(`openclaw-persistio: recall error: ${String(err)}`);
+      }
+    });
+
+    // -------------------------------------------------------------------------
+    // agent_end — ingest new turn messages (fire and forget)
+    // Event: { runId?, messages: unknown[], success: boolean, error?, durationMs? }
+    // Observation only — no return value.
+    // -------------------------------------------------------------------------
+    api.on('agent_end', async (event) => {
+      try {
+        const sessionId = event.runId ?? 'unknown-session';
+        const chunks: Array<{ role: string; content: string }> = [];
+
+        for (const msg of event.messages) {
+          const m = msg as Record<string, unknown>;
+          const role = m['role'];
+          if (role !== 'user' && role !== 'assistant') continue;
+          const text = extractTextFromMessage(msg);
+          if (text && text.length > 0) {
+            chunks.push({ role: role as string, content: text });
+          }
+        }
+
+        if (chunks.length === 0) return;
+        // Fire and forget — agent_end is async but result is ignored
+        client.ingest(sessionId, chunks).catch((err: unknown) => {
+          api.logger?.warn?.(`openclaw-persistio: ingest error: ${String(err)}`);
+        });
+      } catch (err) {
+        api.logger?.warn?.(`openclaw-persistio: agent_end error: ${String(err)}`);
+      }
+    });
+
+    // -------------------------------------------------------------------------
+    // Tools
+    // Verified signature: api.registerTool({ name, description, parameters, execute }, opts?)
+    // execute(_id: string, params: unknown): Promise<AgentToolResult>
+    // AgentToolResult: { content: Array<{ type: "text", text: string }>, details: unknown }
+    // -------------------------------------------------------------------------
+
+    api.registerTool({
+      name: 'memory_search',
+      label: 'Search Memory',
+      description: 'Search persistent memory for relevant facts from past conversations.',
+      parameters: Type.Object({
+        query: Type.String({ description: 'What to search for' }),
+        top_k: Type.Optional(Type.Number({ description: 'Max results to return' })),
+      }),
+      async execute(_id, params) {
+        const p = params as { query: string; top_k?: number };
+        const overrideTopK = typeof p.top_k === 'number' ? p.top_k : cfg.recallTopK;
+        const overrideCfg = { ...cfg, recallTopK: overrideTopK };
+        const c = new PersistioClient(overrideCfg);
+        const memories = await c.recall(p.query);
+        const text = memories.length > 0
+          ? memories.map(m => `- ${m.data} [${m.subject}]`).join('\n')
+          : 'No memories found.';
+        return { content: [{ type: 'text' as const, text }], details: null };
+      },
+    });
+
+    api.registerTool({
+      name: 'memory_add',
+      label: 'Add Memory',
+      description: 'Manually store a fact in persistent memory.',
+      parameters: Type.Object({
+        data: Type.String({ description: 'The fact to remember' }),
+        subject: Type.String({ description: 'The entity or topic this fact is about' }),
+      }),
+      async execute(_id, params) {
+        const p = params as { data: string; subject: string };
+        await client.addMemory(p.data, p.subject);
+        return { content: [{ type: 'text' as const, text: 'Memory stored.' }], details: null };
+      },
+    });
+
+    api.registerTool({
+      name: 'memory_delete',
+      label: 'Delete Memory',
+      description: 'Delete a specific memory by its ID.',
+      parameters: Type.Object({
+        id: Type.String({ description: 'The memory ID to delete' }),
+      }),
+      async execute(_id, params) {
+        const p = params as { id: string };
+        await client.deleteMemory(p.id);
+        return { content: [{ type: 'text' as const, text: 'Memory deleted.' }], details: null };
+      },
+    }, { optional: true });
+
+    api.registerTool({
+      name: 'memory_list',
+      label: 'List Memories',
+      description: 'List all stored memories.',
+      parameters: Type.Object({}),
+      async execute(_id, _params) {
+        const memories = await client.listMemories();
+        const text = memories.length > 0
+          ? memories.map(m => `[${m.id}] ${m.data} (${m.subject})`).join('\n')
+          : 'No memories stored.';
+        return { content: [{ type: 'text' as const, text }], details: null };
+      },
+    }, { optional: true });
+  },
+});