memory-tool

Memory Tool

The Memory tool lets Claude read and write files in a client-managed directory, giving agents persistent state across sessions without RAG infrastructure.

When to Use

• Agents that need to remember user preferences, project context, or past decisions
• Coding agents that accumulate knowledge about a codebase over sessions
• Support/assistant agents that build up a history per user
• Replacing "dump everything into system prompt" with structured persistent state

Core Concept

The Memory tool is a server-side tool (provided by Anthropic) that Claude can call to read, write, and list files in a directory you manage. The API gives the tool calls; your app executes them against real storage (local fs, S3, DB-backed fs).

const response = await client.beta.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 4096,
  tools: [{ type: "memory_20250818", name: "memory" }],
  messages: [...],
});

Implementing the Memory Backend

When Claude calls the memory tool, your app handles the file operations. Minimal implementation:

import fs from "fs/promises";
import path from "path";

const MEMORY_ROOT = "/var/app/memory";

async function handleMemoryCall(input: any, userId: string) {
  const userRoot = path.join(MEMORY_ROOT, userId);
  const safe = (p: string) => {
    const resolved = path.resolve(userRoot, p.replace(/^\//, ""));
    if (!resolved.startsWith(userRoot + path.sep)) throw new Error("Path escapes root");
    return resolved;
  };

  switch (input.command) {
    case "view": {
      const target = safe(input.path);
      const stat = await fs.stat(target).catch(() => null);
      if (!stat) return { error: "not found" };
      if (stat.isDirectory()) {
        const entries = await fs.readdir(target);
        return { content: entries.join("\n") };
      }
      return { content: await fs.readFile(target, "utf-8") };
    }
    case "create": {
      await fs.mkdir(path.dirname(safe(input.path)), { recursive: true });
      await fs.writeFile(safe(input.path), input.file_text);
      return { content: "created" };
    }
    case "str_replace": {
      const f = safe(input.path);
      const text = await fs.readFile(f, "utf-8");
      if (!text.includes(input.old_str)) return { error: "old_str not found" };
      await fs.writeFile(f, text.replace(input.old_str, input.new_str));
      return { content: "replaced" };
    }
    case "insert": {
      const f = safe(input.path);
      const lines = (await fs.readFile(f, "utf-8")).split("\n");
      lines.splice(input.insert_line, 0, input.insert_text);
      await fs.writeFile(f, lines.join("\n"));
      return { content: "inserted" };
    }
    case "delete": {
      await fs.rm(safe(input.path), { recursive: true, force: true });
      return { content: "deleted" };
    }
    case "rename": {
      await fs.rename(safe(input.old_path), safe(input.new_path));
      return { content: "renamed" };
    }
  }
}