Claude Memory Tool

Claude has a native memory tool that allows it to store and retrieve information across conversations. Supermemory provides a backend implementation that maps Claude’s memory commands to persistent storage.

This integration works with Claude’s built-in memory tool type, introduced in the Anthropic API. It requires the context-management beta flag.

Installation

npm install @supermemory/tools @anthropic-ai/sdk

Quick start

import Anthropic from "@anthropic-ai/sdk"
import { createClaudeMemoryTool } from "@supermemory/tools/claude-memory"

const anthropic = new Anthropic()

const memoryTool = createClaudeMemoryTool(process.env.SUPERMEMORY_API_KEY!, {
  namespace: "my-app",
})

async function chatWithMemory(userMessage: string) {
  // Send message to Claude with memory tool
  const response = await anthropic.beta.messages.create({
    model: "claude-sonnet-4-5",
    max_tokens: 2048,
    messages: [{ role: "user", content: userMessage }],
    tools: [{ type: "memory_20250818", name: "memory" }],
    betas: ["context-management-2025-06-27"],
  })

  // Handle any memory tool calls
  const toolResults = []
  for (const block of response.content) {
    if (block.type === "tool_use" && block.name === "memory") {
      const toolResult = await memoryTool.handleCommandForToolResult(
        block.input as any,
        block.id
      )
      toolResults.push(toolResult)
    }
  }

  // Send tool results back to Claude if needed
  if (toolResults.length > 0) {
    const finalResponse = await anthropic.beta.messages.create({
      model: "claude-sonnet-4-5",
      max_tokens: 2048,
      messages: [
        { role: "user", content: userMessage },
        { role: "assistant", content: response.content },
        { role: "user", content: toolResults },
      ],
      tools: [{ type: "memory_20250818", name: "memory" }],
      betas: ["context-management-2025-06-27"],
    })

    return finalResponse
  }

  return response
}

// Example usage
const response = await chatWithMemory(
  "Remember that I prefer React with TypeScript for my projects"
)
console.log(response.content[0])

Configuration

import { createClaudeMemoryTool } from "@supermemory/tools/claude-memory"

const memoryTool = createClaudeMemoryTool(process.env.SUPERMEMORY_API_KEY!, {
  // Scope memories to a project or user (default: "sm_project_default")
  namespace: "user-123",

  // Custom API endpoint
  baseUrl: "https://custom.api.com",
})

How it works

Claude’s memory tool uses a file-system metaphor. Supermemory maps these operations to document storage:

Claude Command	Supermemory Action
`view`	Search/retrieve documents
`create`	Add new document
`str_replace`	Update document content
`insert`	Insert content at line
`delete`	Delete document
`rename`	Move document to new path

Memory path structure

All memory paths must start with /memories/:

/memories/preferences.txt       # User preferences
/memories/projects/react.txt    # Project-specific notes
/memories/context/current.txt   # Current context

Each file is stored as one document in the namespace, tagged with metadata.source = "claude-memory". Its document ID is a reversible encoding of the path: /memories/preferences.txt is stored as cm_memories_s_preferences_d_txt.

Commands reference

View (read/list)

// List directory contents
{ command: "view", path: "/memories/" }

// Read file contents
{ command: "view", path: "/memories/preferences.txt" }

// Read specific lines
{ command: "view", path: "/memories/notes.txt", view_range: [1, 10] }

Create

{
  command: "create",
  path: "/memories/preferences.txt",
  file_text: "User prefers dark mode\nFavorite language: TypeScript"
}

String replace

{
  command: "str_replace",
  path: "/memories/preferences.txt",
  old_str: "dark mode",
  new_str: "light mode"
}

Insert

{
  command: "insert",
  path: "/memories/notes.txt",
  insert_line: 5,
  insert_text: "New note added here"
}

Delete

{ command: "delete", path: "/memories/old-notes.txt" }

Rename

{
  command: "rename",
  old_path: "/memories/old-name.txt",
  new_path: "/memories/new-name.txt"
}

Complete example

import Anthropic from "@anthropic-ai/sdk"
import { createClaudeMemoryTool } from "@supermemory/tools/claude-memory"

const anthropic = new Anthropic()
const memoryTool = createClaudeMemoryTool(process.env.SUPERMEMORY_API_KEY!, {
  namespace: "assistant",
})

async function runConversation() {
  const messages: Anthropic.Beta.BetaMessageParam[] = []

  // Helper to chat with memory
  async function chat(userMessage: string) {
    messages.push({ role: "user", content: userMessage })

    let response = await anthropic.beta.messages.create({
      model: "claude-sonnet-4-5",
      max_tokens: 2048,
      messages,
      tools: [{ type: "memory_20250818", name: "memory" }],
      betas: ["context-management-2025-06-27"],
    })

    // Handle tool calls
    while (response.stop_reason === "tool_use") {
      const toolResults = []

      for (const block of response.content) {
        if (block.type === "tool_use" && block.name === "memory") {
          const result = await memoryTool.handleCommandForToolResult(
            block.input as any,
            block.id
          )
          toolResults.push(result)
        }
      }

      messages.push({ role: "assistant", content: response.content })
      messages.push({ role: "user", content: toolResults })

      response = await anthropic.beta.messages.create({
        model: "claude-sonnet-4-5",
        max_tokens: 2048,
        messages,
        tools: [{ type: "memory_20250818", name: "memory" }],
        betas: ["context-management-2025-06-27"],
      })
    }

    messages.push({ role: "assistant", content: response.content })
    return response
  }

  // Have a conversation with persistent memory
  await chat("My name is Alex and I'm a backend developer")
  await chat("I prefer Go for systems programming")
  await chat("What do you remember about me?")
}

runConversation()

Environment variables

SUPERMEMORY_API_KEY=your_supermemory_key
ANTHROPIC_API_KEY=your_anthropic_key

Comparison with other approaches

Feature	Claude Memory Tool	OpenAI SDK Tools	AI SDK Tools
Automatic memory	✅ Claude decides	❌ Manual control	❌ Manual control
Filesystem metaphor	✅ Files/directories	❌ Flat storage	❌ Flat storage
Path organization	✅ Hierarchical	❌ Tags only	❌ Tags only
Integration	Anthropic SDK only	OpenAI SDK only	Vercel AI SDK

Migration guides

Installation

Quick start

Configuration

How it works

Memory path structure

Commands reference

View (read/list)

Create

String replace

Insert

Delete

Rename

Complete example

Environment variables

Comparison with other approaches

Next steps

AI SDK integration

OpenAI SDK

​Installation

​Quick start

​Configuration

​How it works

​Memory path structure

​Commands reference

​View (read/list)

​Create

​String replace

​Insert

​Delete

​Rename

​Complete example

​Environment variables

​Comparison with other approaches

​Next steps

AI SDK integration

OpenAI SDK

Installation

Quick start

Configuration

How it works

Memory path structure

Commands reference

View (read/list)

Create

String replace

Insert

Delete

Rename

Complete example

Environment variables

Comparison with other approaches

Next steps