Claude Memory Tool

Enable Claude’s native memory tool functionality with Supermemory as the persistent storage backend. Claude can automatically store and retrieve information across conversations using familiar filesystem operations.

Supermemory tools on npm

Check out the NPM page for more details

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({
  apiKey: process.env.ANTHROPIC_API_KEY!,
})

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

async function chatWithMemory(userMessage: string) {
  const response = await anthropic.beta.messages.create({
    model: 'claude-sonnet-4-5',
    max_tokens: 8096,
    tools: [{ type: 'memory_20250818', name: 'memory' }],
    betas: ['context-management-2025-06-27'],
    messages: [{ role: 'user', content: userMessage }],
  })

  // Handle memory tool calls
  for (const block of response.content) {
    if (block.type === 'tool_use' && block.name === 'memory') {
      const result = await memoryTool.handleCommandForToolResult(
        block.input as MemoryCommand,
        block.id
      )
      console.log('Memory operation result:', result)
    }
  }

  return response
}

How It Works

Claude’s memory tool uses a filesystem metaphor to manage persistent information:

Files: Individual memory items stored as Supermemory documents
Directories: Organized using path structure (e.g., /memories/user-preferences)
Operations: View, create, edit, delete, and rename files
Path Normalization: Paths like /memories/preferences are stored as --memories--preferences

Configuration

Basic Configuration

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

const memoryTool = createClaudeMemoryTool(
  process.env.SUPERMEMORY_API_KEY!,
  {
    projectId: 'my-app',           // Project identifier
    baseUrl: 'https://api.supermemory.ai', // Optional: custom API endpoint
  }
)

Using Container Tags

const memoryTool = createClaudeMemoryTool(
  process.env.SUPERMEMORY_API_KEY!,
  {
    containerTags: ['user:alice', 'app:chat'],
  }
)

Memory Operations

Claude automatically performs these operations when managing memory:

View Files

List directory contents or read file contents:

// Claude will automatically check /memories/ directory
// This maps to searching Supermemory documents with path prefix

Create Files

Store new information:

// Claude creates: /memories/user-preferences.txt
// Stored as document with customId: "--memories--user-preferences.txt"

Edit Files

Update existing memories using string replacement:

// Claude performs str_replace on file contents
// Updates the corresponding Supermemory document

Delete Files

Remove information:

// Claude deletes: /memories/old-data.txt
// Removes document from Supermemory

Rename Files

Reorganize memory structure:

// Claude renames: /memories/temp.txt -> /memories/final.txt
// Updates document customId in Supermemory

Complete Chat Example

Here’s a full example with conversation handling:

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

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY!,
})

const memoryTool = createClaudeMemoryTool(process.env.SUPERMEMORY_API_KEY!, {
  projectId: 'chat-app',
})

async function chat() {
  const messages: Anthropic.MessageParam[] = []

  // First message: store information
  messages.push({
    role: 'user',
    content: 'Remember that I prefer dark mode and use TypeScript'
  })

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

  // Process tool calls
  const toolResults: Anthropic.ToolResultBlockParam[] = []

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

  // Continue conversation with tool results
  if (toolResults.length > 0) {
    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: 8096,
      tools: [{ type: 'memory_20250818', name: 'memory' }],
      betas: ['context-management-2025-06-27'],
      messages,
    })
  }

  console.log(response.content)
}

chat()

Advanced Usage

Custom Path Management

Control where Claude stores information:

// Claude automatically organizes by path
// /memories/preferences/editor.txt
// /memories/projects/current.txt
// /memories/notes/meeting-2024.txt

// Each path is normalized and stored with appropriate metadata

Error Handling

Handle operations gracefully:

const result = await memoryTool.handleCommandForToolResult(command, toolUseId)

if (result.is_error) {
  console.error('Memory operation failed:', result.content)
  // Handle error appropriately
} else {
  console.log('Success:', result.content)
}

Monitoring Operations

Track memory operations:

for (const block of response.content) {
  if (block.type === 'tool_use' && block.name === 'memory') {
    console.log('Operation:', block.input.command)
    console.log('Path:', block.input.path)

    const result = await memoryTool.handleCommandForToolResult(
      block.input as MemoryCommand,
      block.id
    )

    console.log('Result:', result.is_error ? 'Failed' : 'Success')
  }
}

Memory Organization

Best Practices

Use Descriptive Paths: /memories/user-preferences/theme.txt is better than /mem1.txt
Organize by Category: Group related information under directories
Keep Files Focused: Store specific information in separate files
Use Clear Naming: Make file names self-explanatory

Path Structure Examples

/memories/
  ├── user-profile/
  │   ├── name.txt
  │   ├── preferences.txt
  │   └── settings.txt
  ├── projects/
  │   ├── current-task.txt
  │   └── goals.txt
  └── notes/
      ├── meeting-notes.txt
      └── ideas.txt

API Reference

`createClaudeMemoryTool(apiKey, config)`

Creates a memory tool instance for Claude. Parameters:

apiKey (string): Your Supermemory API key
config (optional):
- projectId (string): Project identifier
- containerTags (string[]): Alternative to projectId
- baseUrl (string): Custom API endpoint

Returns: ClaudeMemoryTool instance

`handleCommandForToolResult(command, toolUseId)`

Processes a memory command and returns formatted result. Parameters:

command (MemoryCommand): The memory operation from Claude
toolUseId (string): Tool use ID from Claude’s response

Returns: Promise<MemoryToolResult> with:

type: “tool_result”
tool_use_id: The tool use ID
content: Operation result or error message
is_error: Boolean indicating success/failure

Memory Commands

Claude uses these command types internally:

Command	Description	Example
`view`	List directory or read file	`/memories/` or `/memories/file.txt`
`create`	Create new file	Create `/memories/new.txt` with content
`str_replace`	Edit file contents	Replace “old text” with “new text”
`insert`	Add content at line	Insert at line 5
`delete`	Remove file	Delete `/memories/old.txt`
`rename`	Rename/move file	Rename `old.txt` to `new.txt`

Environment Variables

ANTHROPIC_API_KEY=your_anthropic_key
SUPERMEMORY_API_KEY=your_supermemory_key

When to Use

The Claude Memory Tool is ideal for:

Conversational AI: Claude automatically remembers user preferences and context
Personal Assistants: Store and retrieve user-specific information
Documentation Bots: Maintain knowledge across conversations
Project Management: Track tasks and project state
Note-Taking Apps: Persistent memory for meeting notes and ideas

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

Limitations

Requires Anthropic SDK with beta features enabled
Path separators (/) are normalized to -- for storage
Maximum 100 files per directory listing
File operations are asynchronous

Next Steps

OpenAI SDK Tools

Use memory tools with OpenAI function calling

AI SDK Integration

Integrate with Vercel AI SDK

Memory API

Direct API access for advanced control

Cookbook

See real-world examples

Getting Started

Concepts

Using supermemory

Connectors and sync

Migration Guides

Supermemory tools on npm

Installation

Quick Start

How It Works

Configuration

Basic Configuration

Using Container Tags

Memory Operations

View Files

Create Files

Edit Files

Delete Files

Rename Files

Complete Chat Example

Advanced Usage

Custom Path Management

Error Handling

Monitoring Operations

Memory Organization

Best Practices

Path Structure Examples

API Reference

`createClaudeMemoryTool(apiKey, config)`

`handleCommandForToolResult(command, toolUseId)`

Memory Commands

Environment Variables

When to Use

Comparison with Other Approaches

Limitations

Next Steps

OpenAI SDK Tools

AI SDK Integration

Memory API

Cookbook

Getting Started

Concepts

Using supermemory

Connectors and sync

Migration Guides

Supermemory tools on npm

​Installation

​Quick Start

​How It Works

​Configuration

​Basic Configuration

​Using Container Tags

​Memory Operations

​View Files

​Create Files

​Edit Files

​Delete Files

​Rename Files

​Complete Chat Example

​Advanced Usage

​Custom Path Management

​Error Handling

​Monitoring Operations

​Memory Organization

​Best Practices

​Path Structure Examples

​API Reference

​createClaudeMemoryTool(apiKey, config)

​handleCommandForToolResult(command, toolUseId)

​Memory Commands

​Environment Variables

​When to Use

​Comparison with Other Approaches

​Limitations

​Next Steps

OpenAI SDK Tools

AI SDK Integration

Memory API

Cookbook

Installation

Quick Start

How It Works

Configuration

Basic Configuration

Using Container Tags

Memory Operations

View Files

Create Files

Edit Files

Delete Files

Rename Files

Complete Chat Example

Advanced Usage

Custom Path Management

Error Handling

Monitoring Operations

Memory Organization

Best Practices

Path Structure Examples

API Reference

`createClaudeMemoryTool(apiKey, config)`

`handleCommandForToolResult(command, toolUseId)`

Memory Commands

Environment Variables

When to Use

Comparison with Other Approaches

Limitations

Next Steps