Claude Agent SDK

Rekall memory plus durable session state for the Claude Agent SDK. The @rekall/claude-agent package gives your Claude agents long-term memory — recall relevant context, capture what they learn — and state that survives restarts.

Overview

The Claude Agent SDK is a great agent loop with no built-in long-term memory or cross-run state. RekallMemory adds both: recalled context is appended to the agent's system prompt, tool results are captured via a PostToolUse hook, and session state is persisted to Rekall's execution-memory layer. The package is duck-typed against the SDK — no hard dependency — so it won't break on SDK version bumps.

psychology

Recall

Relevant memories are formatted into the system prompt for each run.

save

Capture

A PostToolUse hook remembers tool results as the agent works.

restart_alt

Durable state

Save and load session state across runs and processes.

Installation

Terminal

npm install @rekall/claude-agent

Usage

Recall context for the prompt, build the system prompt, and attach the capture hooks:

agent.ts

import { query } from '@anthropic-ai/claude-agent-sdk';
import { RekallMemory } from '@rekall/claude-agent';

const mem = new RekallMemory({
  apiUrl: 'https://api.rekall.app',   // or http://localhost:9876 in dev
  apiKey: process.env.REKALL_API_KEY, // rk_… key, or accessToken: 'rat_…'
});

// Inject relevant memories, and capture tool results back into memory:
const context = await mem.contextFor(userPrompt);
const systemPrompt = mem.systemPromptFor(context); // appends to the claude_code preset; undefined when nothing relevant

for await (const msg of query({
  prompt: userPrompt,
  options: {
    // Object form { type: 'preset', preset: 'claude_code', append } *appends* to
    // the preset. A bare-string systemPrompt would REPLACE it and drop recalled
    // memory. Omit the field entirely when there's nothing to inject.
    ...(systemPrompt ? { systemPrompt } : {}),
    hooks: mem.hooks(),            // PostToolUse → remember tool results
  },
})) {
  // …
}

// Durable session state across runs / processes:
await mem.saveSession('thread-42', { step, scratch });
const prior = await mem.loadSession('thread-42');

System Prompt: Preset + Append

systemPromptFor(context) wraps the recalled memories as { type: 'preset', preset: 'claude_code', append } — the object form for options.systemPrompt. This appends recalled memory to the preset rather than replacing it. It returns undefined when there is nothing relevant to inject.

Do not pass a bare-string systemPrompt

A bare-string systemPrompt would replace the claude_code preset and drop the recalled memory. Always use the object preset/append form, and omit the field entirely when systemPromptFor returns undefined — exactly as shown in the usage snippet's ...(systemPrompt ? { systemPrompt } : {}).

Context injection uses contextFor() + systemPromptFor() → options.systemPrompt because prompt-time hook events vary by SDK version. The PostToolUse observer never throws, so memory capture can't break your agent run.

API

Method	What it does	Rekall endpoint
`remember(content, { metadata })`	store a memory/observation	POST /api/v2/memories
`recall(query, { limit })`	semantic search → { content, score, metadata }[]	POST /api/v2/memories/search
`contextFor(query)`	recalled memories as a system-prompt block ('' if none)	search
`systemPromptFor(context)`	preset/append wrapper for options.systemPrompt (undefined if empty)	—
`saveSession(key, state) / loadSession(key)`	durable session state	execution-memory /external
`hooks()`	options.hooks shape; PostToolUse captures tool results	—

Authentication

Pass apiKey (rk_…) or accessToken (rat_…), sent as Authorization: Bearer; or headers: { 'x-user-id': '…' } for local dev against a header-auth server.

Next Steps

Browse all framework adapters Use Rekall skills in Claude Code Understand execution memory and session state