Memory systems let agents retain context, learn from experience, and stay consistent across sessions.

SDK focusresumeforkSession()continuesessionStorepersistSessionPreCompact

Memory types

Agent memory borrows human-memory vocabulary as an engineering analogy, not a biological model:

Working Memory (Short-term)

Episodic Memory

Semantic Memory

Long-term Storage (Vector DB / File System)

Working memory

The current conversation context, held directly in the LLM's context window:

The user's current request
Recent conversation history
Current task state
Recently read file contents

sessions.ts

import { forkSession, query } from "@anthropic-ai/claude-agent-sdk";

// 1. Start a session — capture session_id from the result message
let sessionId: string | undefined;
for await (const msg of query({ prompt: "Analyze src/ directory structure" })) {
  if (msg.type === "result") {
    sessionId = msg.session_id;
  }
}
if (!sessionId) throw new Error("No session id returned");

// 2. Resume by ID — precise, good for one session per user/task
for await (const msg of query({
  prompt: "Now refactor the largest file you found",
  options: { resume: sessionId }
})) {
  if (msg.type === "result") console.log(msg.subtype);
}

// 3. Continue — no ID; resumes the most recent session in cwd
for await (const msg of query({
  prompt: "Also add error handling",
  options: { continue: true }
})) {
  if (msg.type === "result") console.log(msg.subtype);
}

// 4. Fork out-of-band, then resume the branch
const { sessionId: branchId } = await forkSession(sessionId, {
  title: "GraphQL alternative"
});
for await (const msg of query({
  prompt: "Try a different approach using GraphQL",
  options: { resume: branchId }
})) {
  if (msg.type === "result") console.log(msg.subtype);
}

PiPi equivalent— Stateful session object plus SessionManager files and trees

typescript

// sessions.ts
import { createAgentSession, SessionManager } from "@earendil-works/pi-coding-agent";

const cwd = process.cwd();

// 1. Start a persisted session — the default location is
//    ~/.pi/agent/sessions/<encoded-cwd>/.
const sessionManager = SessionManager.create(cwd);
const { session } = await createAgentSession({
  sessionManager,
  tools: ["read", "glob"],
});
// 2. Multi-turn = keep the same stateful object and prompt it again.
await session.prompt("Analyze src/ directory structure");
await session.prompt("Now refactor the largest file you found");

// 3. Continue the most recent persisted session for this cwd.
const continuedManager = SessionManager.continueRecent(cwd);
const { session: continued } = await createAgentSession({
  sessionManager: continuedManager,
  tools: ["read", "glob"],
});
await continued.prompt("Also add error handling");

// 4. Branch inside the same JSONL tree, then append a different path.
const targetEntryId = sessionManager.getLeafId();
if (targetEntryId) {
  await session.navigateTree(targetEntryId, {
    summarize: true,
    label: "graphql-alternative",
  });
  await session.prompt("Try a different approach using GraphQL");
}

// 5. Fork/clone-style workflows use SessionManager files.
const sessions = await SessionManager.list(cwd);
const forkManager = SessionManager.forkFrom(sessions[0].path, cwd);
const { session: forked } = await createAgentSession({ sessionManager: forkManager });
await forked.prompt("Try a different approach using GraphQL");

// 6. Ephemeral runs can opt out of files entirely.
const scratch = SessionManager.inMemory(cwd);
await createAgentSession({ sessionManager: scratch, tools: ["read"] });

Key mappings

Resume model:

SessionManager.open(path) / continueRecent(cwd) plus a live AgentSession vs resume: id on query().

Fork:

branch inside the JSONL tree with navigateTree() or create a separate session file with SessionManager.forkFrom() / CLI /fork and /clone vs forkSession(sessionId).

Continue:

continueRecent(cwd) for a new process, or .prompt() again on the live object, vs continue: true in Claude Agent SDK.

Memory Systems

Memory types

Working memory

Episodic memory