getmnemo-anthropic 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mnemo, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# @ledgermem/anthropic
+
+LedgerMem helper for the Anthropic SDK. Wraps `messages.create` with a single
+`memory` tool (search + add), prompt caching on the system block, and
+optional extended thinking — the recommended setup for any long-lived Claude
+assistant.
+
+## Install
+
+```bash
+npm install @ledgermem/anthropic @ledgermem/memory @anthropic-ai/sdk
+```
+
+## Quickstart (30 seconds)
+
+```ts
+import Anthropic from "@anthropic-ai/sdk";
+import { LedgerMem } from "@ledgermem/memory";
+import { withMemoryTool } from "@ledgermem/anthropic";
+
+const claude = new Anthropic();
+const ledgermem = new LedgerMem({
+  apiKey: process.env.LEDGERMEM_API_KEY!,
+  workspaceId: process.env.LEDGERMEM_WORKSPACE_ID!,
+});
+
+const agent = withMemoryTool({
+  client: claude,
+  ledgermem,
+  model: "claude-sonnet-4-7",
+  thinkingBudgetTokens: 4000,
+});
+
+const result = await agent.run({
+  system: "You are a personal assistant. Use memory before answering.",
+  messages: [{ role: "user", content: "What did I tell you about my schedule?" }],
+  metadata: { userId: "user-42" },
+});
+
+console.log(result.text);
+console.log("memory tool calls:", result.memoryToolCalls);
+```
+
+## What the wrapper does
+
+- Exposes one tool `memory` with `action: "search" | "add"` — the model
+  decides when to recall and when to remember.
+- Runs the tool-use loop for you (default cap: 6 iterations).
+- Adds `cache_control: { type: "ephemeral" }` to the system prompt so
+  long stable instructions hit the prompt cache.
+- Optionally enables extended thinking with a configurable token budget.
+- Returns the final transcript so you can persist it elsewhere.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { withMemoryTool, MEMORY_TOOL_NAME, type WithMemoryToolOptions, type WithMemoryToolWrapper, type WithMemoryRunInput, type WithMemoryRunResult, } from "./memory-tool.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { withMemoryTool, MEMORY_TOOL_NAME, } from "./memory-tool.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,gBAAgB,GAKjB,MAAM,kBAAkB,CAAC"}

package/dist/memory-tool.d.ts

@@ -0,0 +1,80 @@
+import type { Mnemo } from "getmnemo";
+/** Structural subset of `Anthropic` we depend on — keeps the peer dep loose. */
+interface AnthropicLike {
+    messages: {
+        create: (params: Record<string, unknown>) => Promise<MessagesCreateResult>;
+    };
+}
+interface MessagesCreateResult {
+    id: string;
+    content: Array<MessageBlock>;
+    stop_reason: string;
+    usage?: Record<string, number>;
+    [key: string]: unknown;
+}
+type MessageBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "thinking";
+    thinking: string;
+} | {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+};
+interface ChatMessage {
+    role: "user" | "assistant";
+    content: string | Array<Record<string, unknown>>;
+}
+export interface WithMemoryToolOptions {
+    client: AnthropicLike;
+    getmnemo: Mnemo;
+    /** Defaults to claude-sonnet-4-7. Override per call too. */
+    model?: string;
+    /** Defaults to 1024. */
+    maxTokens?: number;
+    /** Default top-k for memory search. */
+    searchLimit?: number;
+    /** Wrap the system prompt with `cache_control: { type: "ephemeral" }`. */
+    cacheSystem?: boolean;
+    /** Enable extended thinking with this token budget. */
+    thinkingBudgetTokens?: number;
+    /** Extra static metadata merged into every persisted memory. */
+    metadata?: Record<string, unknown>;
+    /** Hard cap on tool-use loop iterations. */
+    maxIterations?: number;
+}
+export interface WithMemoryRunInput {
+    system?: string;
+    messages: ChatMessage[];
+    /** Per-call overrides. */
+    model?: string;
+    maxTokens?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface WithMemoryRunResult {
+    /** Final assistant text concatenated across blocks. */
+    text: string;
+    /** All raw API responses produced during the tool-use loop. */
+    responses: MessagesCreateResult[];
+    /** Number of memory tool invocations. */
+    memoryToolCalls: number;
+    /** Final messages array after tool loop (useful for storing transcript). */
+    messages: ChatMessage[];
+}
+export interface WithMemoryToolWrapper {
+    run(input: WithMemoryRunInput): Promise<WithMemoryRunResult>;
+}
+export declare const MEMORY_TOOL_NAME = "memory";
+/**
+ * Wrap an `Anthropic` client so a single `memory` tool (with `search`/`add`
+ * actions) is exposed to the model and the tool-use loop is handled for you.
+ *
+ * Also opts into prompt caching of the system prompt and (optionally) extended
+ * thinking — both are recommended for any long-lived assistant.
+ */
+export declare function withMemoryTool(options: WithMemoryToolOptions): WithMemoryToolWrapper;
+export {};
+//# sourceMappingURL=memory-tool.d.ts.map

package/dist/memory-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-tool.d.ts","sourceRoot":"","sources":["../src/memory-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAEtC,gFAAgF;AAChF,UAAU,aAAa;IACrB,QAAQ,EAAE;QACR,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;KAC5E,CAAC;CACH;AAED,UAAU,oBAAoB;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,KAAK,YAAY,GACb;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACtC;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,CAAC;AAEN,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAClD;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,EAAE,KAAK,CAAC;IAChB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,uDAAuD;IACvD,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,4CAA4C;IAC5C,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,0BAA0B;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,mBAAmB;IAClC,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,SAAS,EAAE,oBAAoB,EAAE,CAAC;IAClC,yCAAyC;IACzC,eAAe,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAC9D;AAED,eAAO,MAAM,gBAAgB,WAAW,CAAC;AAEzC;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,qBAAqB,GAC7B,qBAAqB,CAgIvB"}

package/dist/memory-tool.js

@@ -0,0 +1,173 @@
+export const MEMORY_TOOL_NAME = "memory";
+/**
+ * Wrap an `Anthropic` client so a single `memory` tool (with `search`/`add`
+ * actions) is exposed to the model and the tool-use loop is handled for you.
+ *
+ * Also opts into prompt caching of the system prompt and (optionally) extended
+ * thinking — both are recommended for any long-lived assistant.
+ */
+export function withMemoryTool(options) {
+    const defaults = {
+        model: options.model ?? "claude-sonnet-4-7",
+        maxTokens: options.maxTokens ?? 1024,
+        searchLimit: options.searchLimit ?? 5,
+        cacheSystem: options.cacheSystem ?? true,
+        thinkingBudgetTokens: options.thinkingBudgetTokens,
+        metadata: options.metadata ?? {},
+        maxIterations: options.maxIterations ?? 6,
+    };
+    const tool = {
+        name: MEMORY_TOOL_NAME,
+        description: "Long-term memory store. Use action='search' to recall facts about the user before answering, and action='add' to save a new fact worth remembering across conversations.",
+        input_schema: {
+            type: "object",
+            // additionalProperties:false lets Anthropic enforce strict JSON schema
+            // for tool inputs — without it the model can pass arbitrary keys
+            // (including keys that look like trusted metadata) and we silently
+            // accept them.
+            additionalProperties: false,
+            properties: {
+                action: {
+                    type: "string",
+                    enum: ["search", "add"],
+                    description: "Whether to read from or write to memory.",
+                },
+                query: {
+                    type: "string",
+                    description: "Required when action='search'. Natural-language query.",
+                },
+                content: {
+                    type: "string",
+                    description: "Required when action='add'. The fact to remember.",
+                },
+                limit: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: 50,
+                    description: "Optional max results for search.",
+                },
+                tags: {
+                    type: "object",
+                    description: "Optional metadata merged into the stored memory.",
+                    additionalProperties: true,
+                },
+            },
+            required: ["action"],
+        },
+    };
+    return {
+        async run(input) {
+            const messages = [...input.messages];
+            const responses = [];
+            let toolCalls = 0;
+            const system = buildSystem(input.system, defaults.cacheSystem);
+            const baseParams = {
+                model: input.model ?? defaults.model,
+                max_tokens: input.maxTokens ?? defaults.maxTokens,
+                tools: [tool],
+                ...(system ? { system } : {}),
+            };
+            if (defaults.thinkingBudgetTokens) {
+                baseParams.thinking = {
+                    type: "enabled",
+                    budget_tokens: defaults.thinkingBudgetTokens,
+                };
+            }
+            for (let i = 0; i < defaults.maxIterations; i++) {
+                const resp = await options.client.messages.create({
+                    ...baseParams,
+                    messages,
+                });
+                responses.push(resp);
+                // Anthropic requires every tool_use block in an assistant turn to be
+                // answered with a matching tool_result in the next user turn. Collect
+                // ALL tool_use blocks (not just memory ones) so the message list stays
+                // valid; non-memory tools get a structured error result.
+                const allToolUses = resp.content.filter((b) => b.type === "tool_use");
+                messages.push({ role: "assistant", content: resp.content });
+                if (resp.stop_reason !== "tool_use" || allToolUses.length === 0) {
+                    return finalize(messages, responses, toolCalls);
+                }
+                const toolResults = [];
+                for (const use of allToolUses) {
+                    if (use.name !== MEMORY_TOOL_NAME) {
+                        toolResults.push({
+                            type: "tool_result",
+                            tool_use_id: use.id,
+                            is_error: true,
+                            content: JSON.stringify({
+                                error: `Unknown tool: ${use.name}. Only '${MEMORY_TOOL_NAME}' is available.`,
+                            }),
+                        });
+                        continue;
+                    }
+                    toolCalls += 1;
+                    const result = await runMemoryTool(use.input, options.getmnemo, 
+                    // Trusted server metadata (input.metadata, defaults.metadata)
+                    // wins over any tool input fields a model could fabricate.
+                    { ...defaults.metadata, ...(input.metadata ?? {}) }, defaults.searchLimit);
+                    toolResults.push({
+                        type: "tool_result",
+                        tool_use_id: use.id,
+                        content: JSON.stringify(result),
+                    });
+                }
+                messages.push({ role: "user", content: toolResults });
+            }
+            return finalize(messages, responses, toolCalls);
+        },
+    };
+}
+function finalize(messages, responses, memoryToolCalls) {
+    const last = responses[responses.length - 1];
+    const text = last
+        ? last.content
+            .filter((b) => b.type === "text")
+            .map((b) => b.text)
+            .join("\n")
+            .trim()
+        : "";
+    return { text, responses, memoryToolCalls, messages };
+}
+function buildSystem(system, cache) {
+    if (!system)
+        return undefined;
+    if (!cache)
+        return [{ type: "text", text: system }];
+    return [
+        { type: "text", text: system, cache_control: { type: "ephemeral" } },
+    ];
+}
+async function runMemoryTool(raw, client, baseMetadata, defaultLimit) {
+    const action = String(raw.action ?? "");
+    if (action === "search") {
+        const query = String(raw.query ?? "").trim();
+        if (!query)
+            return { error: "query is required for search" };
+        // Clamp the limit into [1, 50] regardless of what the model asked for —
+        // a hostile/buggy tool input could otherwise pass a huge value (or 0)
+        // that bypasses the JSON-schema bounds and torches the context window.
+        const requested = Number(raw.limit ?? defaultLimit);
+        const limit = Number.isFinite(requested)
+            ? Math.min(50, Math.max(1, Math.floor(requested)))
+            : defaultLimit;
+        const results = (await client.search({ query, limit })).hits ?? [];
+        return { results };
+    }
+    if (action === "add") {
+        const content = String(raw.content ?? "").trim();
+        if (!content)
+            return { error: "content is required for add" };
+        const tags = typeof raw.tags === "object" && raw.tags
+            ? raw.tags
+            : {};
+        // Model-supplied `tags` are merged FIRST so trusted server-controlled
+        // baseMetadata (userId, workspaceId, etc.) cannot be overwritten by an
+        // LLM via prompt injection — e.g. a model that emits
+        // tags={"userId":"victim"} would otherwise reattribute the memory.
+        const memory = await client.add({ content, metadata: { ...tags, ...baseMetadata } });
+        return { memory };
+    }
+    return { error: `unknown action: ${action}` };
+}
+//# sourceMappingURL=memory-tool.js.map

package/dist/memory-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-tool.js","sourceRoot":"","sources":["../src/memory-tool.ts"],"names":[],"mappings":"AA2EA,MAAM,CAAC,MAAM,gBAAgB,GAAG,QAAQ,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,OAA8B;IAE9B,MAAM,QAAQ,GAAG;QACf,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,mBAAmB;QAC3C,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI;QACpC,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,CAAC;QACrC,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI;QACxC,oBAAoB,EAAE,OAAO,CAAC,oBAAoB;QAClD,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,EAAE;QAChC,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,CAAC;KAC1C,CAAC;IAEF,MAAM,IAAI,GAAG;QACX,IAAI,EAAE,gBAAgB;QACtB,WAAW,EACT,0KAA0K;QAC5K,YAAY,EAAE;YACZ,IAAI,EAAE,QAAiB;YACvB,uEAAuE;YACvE,iEAAiE;YACjE,mEAAmE;YACnE,eAAe;YACf,oBAAoB,EAAE,KAAK;YAC3B,UAAU,EAAE;gBACV,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC;oBACvB,WAAW,EAAE,0CAA0C;iBACxD;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,wDAAwD;iBACtE;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,mDAAmD;iBACjE;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,SAAS;oBACf,OAAO,EAAE,CAAC;oBACV,OAAO,EAAE,EAAE;oBACX,WAAW,EAAE,kCAAkC;iBAChD;gBACD,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,kDAAkD;oBAC/D,oBAAoB,EAAE,IAAI;iBAC3B;aACF;YACD,QAAQ,EAAE,CAAC,QAAQ,CAAC;SACrB;KACF,CAAC;IAEF,OAAO;QACL,KAAK,CAAC,GAAG,CAAC,KAAyB;YACjC,MAAM,QAAQ,GAAkB,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC;YACpD,MAAM,SAAS,GAA2B,EAAE,CAAC;YAC7C,IAAI,SAAS,GAAG,CAAC,CAAC;YAElB,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;YAC/D,MAAM,UAAU,GAA4B;gBAC1C,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,QAAQ,CAAC,KAAK;gBACpC,UAAU,EAAE,KAAK,CAAC,SAAS,IAAI,QAAQ,CAAC,SAAS;gBACjD,KAAK,EAAE,CAAC,IAAI,CAAC;gBACb,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC9B,CAAC;YACF,IAAI,QAAQ,CAAC,oBAAoB,EAAE,CAAC;gBAClC,UAAU,CAAC,QAAQ,GAAG;oBACpB,IAAI,EAAE,SAAS;oBACf,aAAa,EAAE,QAAQ,CAAC,oBAAoB;iBAC7C,CAAC;YACJ,CAAC;YAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,aAAa,EAAE,CAAC,EAAE,EAAE,CAAC;gBAChD,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;oBAChD,GAAG,UAAU;oBACb,QAAQ;iBACT,CAAC,CAAC;gBACH,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAErB,qEAAqE;gBACrE,sEAAsE;gBACtE,uEAAuE;gBACvE,yDAAyD;gBACzD,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CACrC,CAAC,CAAC,EAAoD,EAAE,CACtD,CAAC,CAAC,IAAI,KAAK,UAAU,CACxB,CAAC;gBAEF,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;gBAE5D,IAAI,IAAI,CAAC,WAAW,KAAK,UAAU,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBAChE,OAAO,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;gBAClD,CAAC;gBAED,MAAM,WAAW,GAAmC,EAAE,CAAC;gBACvD,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;oBAC9B,IAAI,GAAG,CAAC,IAAI,KAAK,gBAAgB,EAAE,CAAC;wBAClC,WAAW,CAAC,IAAI,CAAC;4BACf,IAAI,EAAE,aAAa;4BACnB,WAAW,EAAE,GAAG,CAAC,EAAE;4BACnB,QAAQ,EAAE,IAAI;4BACd,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC;gCACtB,KAAK,EAAE,iBAAiB,GAAG,CAAC,IAAI,WAAW,gBAAgB,iBAAiB;6BAC7E,CAAC;yBACH,CAAC,CAAC;wBACH,SAAS;oBACX,CAAC;oBACD,SAAS,IAAI,CAAC,CAAC;oBACf,MAAM,MAAM,GAAG,MAAM,aAAa,CAChC,GAAG,CAAC,KAAK,EACT,OAAO,CAAC,QAAQ;oBAChB,8DAA8D;oBAC9D,2DAA2D;oBAC3D,EAAE,GAAG,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,EACnD,QAAQ,CAAC,WAAW,CACrB,CAAC;oBACF,WAAW,CAAC,IAAI,CAAC;wBACf,IAAI,EAAE,aAAa;wBACnB,WAAW,EAAE,GAAG,CAAC,EAAE;wBACnB,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;qBAChC,CAAC,CAAC;gBACL,CAAC;gBACD,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;YACxD,CAAC;YAED,OAAO,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;QAClD,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CACf,QAAuB,EACvB,SAAiC,EACjC,eAAuB;IAEvB,MAAM,IAAI,GAAG,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC7C,MAAM,IAAI,GAAG,IAAI;QACf,CAAC,CAAC,IAAI,CAAC,OAAO;aACT,MAAM,CAAC,CAAC,CAAC,EAAgD,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;aAC9E,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;aAClB,IAAI,CAAC,IAAI,CAAC;aACV,IAAI,EAAE;QACX,CAAC,CAAC,EAAE,CAAC;IACP,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,eAAe,EAAE,QAAQ,EAAE,CAAC;AACxD,CAAC;AAED,SAAS,WAAW,CAClB,MAA0B,EAC1B,KAAc;IAEd,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,IAAI,CAAC,KAAK;QAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACpD,OAAO;QACL,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE;KACrE,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,aAAa,CAC1B,GAA4B,EAC5B,MAAa,EACb,YAAqC,EACrC,YAAoB;IAEpB,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IACxC,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAC7C,IAAI,CAAC,KAAK;YAAE,OAAO,EAAE,KAAK,EAAE,8BAA8B,EAAE,CAAC;QAC7D,wEAAwE;QACxE,sEAAsE;QACtE,uEAAuE;QACvE,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,IAAI,YAAY,CAAC,CAAC;QACpD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC;YACtC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;YAClD,CAAC,CAAC,YAAY,CAAC;QACjB,MAAM,OAAO,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;QACnE,OAAO,EAAE,OAAO,EAAE,CAAC;IACrB,CAAC;IACD,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;QACrB,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACjD,IAAI,CAAC,OAAO;YAAE,OAAO,EAAE,KAAK,EAAE,6BAA6B,EAAE,CAAC;QAC9D,MAAM,IAAI,GACR,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI;YACtC,CAAC,CAAE,GAAG,CAAC,IAAgC;YACvC,CAAC,CAAC,EAAE,CAAC;QACT,sEAAsE;QACtE,uEAAuE;QACvE,qDAAqD;QACrD,mEAAmE;QACnE,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,GAAG,IAAI,EAAE,GAAG,YAAY,EAAE,EAAE,CAAC,CAAC;QACrF,OAAO,EAAE,MAAM,EAAE,CAAC;IACpB,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,mBAAmB,MAAM,EAAE,EAAE,CAAC;AAChD,CAAC"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "getmnemo-anthropic",
+  "version": "0.1.0",
+  "description": "Mnemo helper for the Anthropic SDK — memory tool, prompt caching, and extended thinking wired together.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": [
+    "getmnemo",
+    "anthropic",
+    "claude",
+    "memory",
+    "tool-use",
+    "prompt-caching"
+  ],
+  "author": "Mnemo <founders@getmnemo.xyz>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ledgermem/getmnemo-anthropic.git"
+  },
+  "dependencies": {
+    "getmnemo": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/sdk": ">=0.30.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "homepage": "https://getmnemo.xyz"
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export {
+  withMemoryTool,
+  MEMORY_TOOL_NAME,
+  type WithMemoryToolOptions,
+  type WithMemoryToolWrapper,
+  type WithMemoryRunInput,
+  type WithMemoryRunResult,
+} from "./memory-tool.js";

package/src/memory-tool.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it, vi } from "vitest";
+import { withMemoryTool, MEMORY_TOOL_NAME } from "./memory-tool.js";
+
+function fakeMnemo() {
+  return {
+    search: vi
+      .fn()
+      .mockResolvedValue([{ id: "m1", content: "user prefers dark mode" }]),
+    add: vi.fn().mockResolvedValue({ id: "m2", content: "stored" }),
+    update: vi.fn(),
+    delete: vi.fn(),
+    list: vi.fn(),
+  } as any;
+}
+
+describe("withMemoryTool", () => {
+  it("short-circuits when the model returns text without tool use", async () => {
+    const client = {
+      messages: {
+        create: vi.fn().mockResolvedValue({
+          id: "r1",
+          stop_reason: "end_turn",
+          content: [{ type: "text", text: "Hi there." }],
+        }),
+      },
+    };
+    const wrap = withMemoryTool({ client, getmnemo: fakeMnemo() });
+    const out = await wrap.run({
+      system: "You are helpful.",
+      messages: [{ role: "user", content: "Hello" }],
+    });
+    expect(out.text).toBe("Hi there.");
+    expect(out.memoryToolCalls).toBe(0);
+    expect(client.messages.create).toHaveBeenCalledOnce();
+  });
+
+  it("runs the memory tool loop and feeds tool_result back", async () => {
+    const getmnemo = fakeMnemo();
+    const client = {
+      messages: {
+        create: vi
+          .fn()
+          .mockResolvedValueOnce({
+            id: "r1",
+            stop_reason: "tool_use",
+            content: [
+              {
+                type: "tool_use",
+                id: "tu_1",
+                name: MEMORY_TOOL_NAME,
+                input: { action: "search", query: "ui prefs" },
+              },
+            ],
+          })
+          .mockResolvedValueOnce({
+            id: "r2",
+            stop_reason: "end_turn",
+            content: [{ type: "text", text: "You prefer dark mode." }],
+          }),
+      },
+    };
+    const wrap = withMemoryTool({ client, getmnemo });
+    const out = await wrap.run({
+      messages: [{ role: "user", content: "What do I prefer?" }],
+    });
+    expect(out.text).toBe("You prefer dark mode.");
+    expect(out.memoryToolCalls).toBe(1);
+    expect(getmnemo.search).toHaveBeenCalledWith("ui prefs", { limit: 5 });
+    // 2nd call should include the tool_result
+    const secondCall = client.messages.create.mock.calls[1]![0] as any;
+    const toolResultMsg = secondCall.messages.at(-1);
+    expect(toolResultMsg.role).toBe("user");
+    expect((toolResultMsg.content as any[])[0].type).toBe("tool_result");
+  });
+
+  it("opts into prompt caching on the system block by default", async () => {
+    const client = {
+      messages: {
+        create: vi.fn().mockResolvedValue({
+          id: "r1",
+          stop_reason: "end_turn",
+          content: [{ type: "text", text: "ok" }],
+        }),
+      },
+    };
+    const wrap = withMemoryTool({ client, getmnemo: fakeMnemo() });
+    await wrap.run({
+      system: "stable instructions",
+      messages: [{ role: "user", content: "hi" }],
+    });
+    const params = client.messages.create.mock.calls[0]![0] as any;
+    expect(params.system[0].cache_control).toEqual({ type: "ephemeral" });
+  });
+
+  it("enables extended thinking when configured", async () => {
+    const client = {
+      messages: {
+        create: vi.fn().mockResolvedValue({
+          id: "r1",
+          stop_reason: "end_turn",
+          content: [{ type: "text", text: "ok" }],
+        }),
+      },
+    };
+    const wrap = withMemoryTool({
+      client,
+      getmnemo: fakeMnemo(),
+      thinkingBudgetTokens: 4000,
+    });
+    await wrap.run({ messages: [{ role: "user", content: "hi" }] });
+    const params = client.messages.create.mock.calls[0]![0] as any;
+    expect(params.thinking).toEqual({ type: "enabled", budget_tokens: 4000 });
+  });
+
+  it("respects maxIterations and stops the loop", async () => {
+    const getmnemo = fakeMnemo();
+    const client = {
+      messages: {
+        create: vi.fn().mockResolvedValue({
+          id: "r",
+          stop_reason: "tool_use",
+          content: [
+            {
+              type: "tool_use",
+              id: "tu",
+              name: MEMORY_TOOL_NAME,
+              input: { action: "search", query: "x" },
+            },
+          ],
+        }),
+      },
+    };
+    const wrap = withMemoryTool({
+      client,
+      getmnemo,
+      maxIterations: 2,
+    });
+    const out = await wrap.run({
+      messages: [{ role: "user", content: "loop" }],
+    });
+    expect(client.messages.create).toHaveBeenCalledTimes(2);
+    expect(out.memoryToolCalls).toBe(2);
+  });
+});

package/src/memory-tool.ts

@@ -0,0 +1,279 @@
+import type { Mnemo } from "getmnemo";
+
+/** Structural subset of `Anthropic` we depend on — keeps the peer dep loose. */
+interface AnthropicLike {
+  messages: {
+    create: (params: Record<string, unknown>) => Promise<MessagesCreateResult>;
+  };
+}
+
+interface MessagesCreateResult {
+  id: string;
+  content: Array<MessageBlock>;
+  stop_reason: string;
+  usage?: Record<string, number>;
+  [key: string]: unknown;
+}
+
+type MessageBlock =
+  | { type: "text"; text: string }
+  | { type: "thinking"; thinking: string }
+  | {
+      type: "tool_use";
+      id: string;
+      name: string;
+      input: Record<string, unknown>;
+    };
+
+interface ChatMessage {
+  role: "user" | "assistant";
+  content: string | Array<Record<string, unknown>>;
+}
+
+export interface WithMemoryToolOptions {
+  client: AnthropicLike;
+  getmnemo: Mnemo;
+  /** Defaults to claude-sonnet-4-7. Override per call too. */
+  model?: string;
+  /** Defaults to 1024. */
+  maxTokens?: number;
+  /** Default top-k for memory search. */
+  searchLimit?: number;
+  /** Wrap the system prompt with `cache_control: { type: "ephemeral" }`. */
+  cacheSystem?: boolean;
+  /** Enable extended thinking with this token budget. */
+  thinkingBudgetTokens?: number;
+  /** Extra static metadata merged into every persisted memory. */
+  metadata?: Record<string, unknown>;
+  /** Hard cap on tool-use loop iterations. */
+  maxIterations?: number;
+}
+
+export interface WithMemoryRunInput {
+  system?: string;
+  messages: ChatMessage[];
+  /** Per-call overrides. */
+  model?: string;
+  maxTokens?: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface WithMemoryRunResult {
+  /** Final assistant text concatenated across blocks. */
+  text: string;
+  /** All raw API responses produced during the tool-use loop. */
+  responses: MessagesCreateResult[];
+  /** Number of memory tool invocations. */
+  memoryToolCalls: number;
+  /** Final messages array after tool loop (useful for storing transcript). */
+  messages: ChatMessage[];
+}
+
+export interface WithMemoryToolWrapper {
+  run(input: WithMemoryRunInput): Promise<WithMemoryRunResult>;
+}
+
+export const MEMORY_TOOL_NAME = "memory";
+
+/**
+ * Wrap an `Anthropic` client so a single `memory` tool (with `search`/`add`
+ * actions) is exposed to the model and the tool-use loop is handled for you.
+ *
+ * Also opts into prompt caching of the system prompt and (optionally) extended
+ * thinking — both are recommended for any long-lived assistant.
+ */
+export function withMemoryTool(
+  options: WithMemoryToolOptions,
+): WithMemoryToolWrapper {
+  const defaults = {
+    model: options.model ?? "claude-sonnet-4-7",
+    maxTokens: options.maxTokens ?? 1024,
+    searchLimit: options.searchLimit ?? 5,
+    cacheSystem: options.cacheSystem ?? true,
+    thinkingBudgetTokens: options.thinkingBudgetTokens,
+    metadata: options.metadata ?? {},
+    maxIterations: options.maxIterations ?? 6,
+  };
+
+  const tool = {
+    name: MEMORY_TOOL_NAME,
+    description:
+      "Long-term memory store. Use action='search' to recall facts about the user before answering, and action='add' to save a new fact worth remembering across conversations.",
+    input_schema: {
+      type: "object" as const,
+      // additionalProperties:false lets Anthropic enforce strict JSON schema
+      // for tool inputs — without it the model can pass arbitrary keys
+      // (including keys that look like trusted metadata) and we silently
+      // accept them.
+      additionalProperties: false,
+      properties: {
+        action: {
+          type: "string",
+          enum: ["search", "add"],
+          description: "Whether to read from or write to memory.",
+        },
+        query: {
+          type: "string",
+          description: "Required when action='search'. Natural-language query.",
+        },
+        content: {
+          type: "string",
+          description: "Required when action='add'. The fact to remember.",
+        },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 50,
+          description: "Optional max results for search.",
+        },
+        tags: {
+          type: "object",
+          description: "Optional metadata merged into the stored memory.",
+          additionalProperties: true,
+        },
+      },
+      required: ["action"],
+    },
+  };
+
+  return {
+    async run(input: WithMemoryRunInput): Promise<WithMemoryRunResult> {
+      const messages: ChatMessage[] = [...input.messages];
+      const responses: MessagesCreateResult[] = [];
+      let toolCalls = 0;
+
+      const system = buildSystem(input.system, defaults.cacheSystem);
+      const baseParams: Record<string, unknown> = {
+        model: input.model ?? defaults.model,
+        max_tokens: input.maxTokens ?? defaults.maxTokens,
+        tools: [tool],
+        ...(system ? { system } : {}),
+      };
+      if (defaults.thinkingBudgetTokens) {
+        baseParams.thinking = {
+          type: "enabled",
+          budget_tokens: defaults.thinkingBudgetTokens,
+        };
+      }
+
+      for (let i = 0; i < defaults.maxIterations; i++) {
+        const resp = await options.client.messages.create({
+          ...baseParams,
+          messages,
+        });
+        responses.push(resp);
+
+        // Anthropic requires every tool_use block in an assistant turn to be
+        // answered with a matching tool_result in the next user turn. Collect
+        // ALL tool_use blocks (not just memory ones) so the message list stays
+        // valid; non-memory tools get a structured error result.
+        const allToolUses = resp.content.filter(
+          (b): b is Extract<MessageBlock, { type: "tool_use" }> =>
+            b.type === "tool_use",
+        );
+
+        messages.push({ role: "assistant", content: resp.content });
+
+        if (resp.stop_reason !== "tool_use" || allToolUses.length === 0) {
+          return finalize(messages, responses, toolCalls);
+        }
+
+        const toolResults: Array<Record<string, unknown>> = [];
+        for (const use of allToolUses) {
+          if (use.name !== MEMORY_TOOL_NAME) {
+            toolResults.push({
+              type: "tool_result",
+              tool_use_id: use.id,
+              is_error: true,
+              content: JSON.stringify({
+                error: `Unknown tool: ${use.name}. Only '${MEMORY_TOOL_NAME}' is available.`,
+              }),
+            });
+            continue;
+          }
+          toolCalls += 1;
+          const result = await runMemoryTool(
+            use.input,
+            options.getmnemo,
+            // Trusted server metadata (input.metadata, defaults.metadata)
+            // wins over any tool input fields a model could fabricate.
+            { ...defaults.metadata, ...(input.metadata ?? {}) },
+            defaults.searchLimit,
+          );
+          toolResults.push({
+            type: "tool_result",
+            tool_use_id: use.id,
+            content: JSON.stringify(result),
+          });
+        }
+        messages.push({ role: "user", content: toolResults });
+      }
+
+      return finalize(messages, responses, toolCalls);
+    },
+  };
+}
+
+function finalize(
+  messages: ChatMessage[],
+  responses: MessagesCreateResult[],
+  memoryToolCalls: number,
+): WithMemoryRunResult {
+  const last = responses[responses.length - 1];
+  const text = last
+    ? last.content
+        .filter((b): b is Extract<MessageBlock, { type: "text" }> => b.type === "text")
+        .map((b) => b.text)
+        .join("\n")
+        .trim()
+    : "";
+  return { text, responses, memoryToolCalls, messages };
+}
+
+function buildSystem(
+  system: string | undefined,
+  cache: boolean,
+): Array<Record<string, unknown>> | undefined {
+  if (!system) return undefined;
+  if (!cache) return [{ type: "text", text: system }];
+  return [
+    { type: "text", text: system, cache_control: { type: "ephemeral" } },
+  ];
+}
+
+async function runMemoryTool(
+  raw: Record<string, unknown>,
+  client: Mnemo,
+  baseMetadata: Record<string, unknown>,
+  defaultLimit: number,
+): Promise<unknown> {
+  const action = String(raw.action ?? "");
+  if (action === "search") {
+    const query = String(raw.query ?? "").trim();
+    if (!query) return { error: "query is required for search" };
+    // Clamp the limit into [1, 50] regardless of what the model asked for —
+    // a hostile/buggy tool input could otherwise pass a huge value (or 0)
+    // that bypasses the JSON-schema bounds and torches the context window.
+    const requested = Number(raw.limit ?? defaultLimit);
+    const limit = Number.isFinite(requested)
+      ? Math.min(50, Math.max(1, Math.floor(requested)))
+      : defaultLimit;
+    const results = (await client.search({ query, limit })).hits ?? [];
+    return { results };
+  }
+  if (action === "add") {
+    const content = String(raw.content ?? "").trim();
+    if (!content) return { error: "content is required for add" };
+    const tags =
+      typeof raw.tags === "object" && raw.tags
+        ? (raw.tags as Record<string, unknown>)
+        : {};
+    // Model-supplied `tags` are merged FIRST so trusted server-controlled
+    // baseMetadata (userId, workspaceId, etc.) cannot be overwritten by an
+    // LLM via prompt injection — e.g. a model that emits
+    // tags={"userId":"victim"} would otherwise reattribute the memory.
+    const memory = await client.add({ content, metadata: { ...tags, ...baseMetadata } });
+    return { memory };
+  }
+  return { error: `unknown action: ${action}` };
+}