Memory Services

Claude Code has three complementary memory systems that persist context across and within sessions. Each uses the forked agent pattern (a sub-agent that shares the parent conversation's prompt cache) to extract and maintain knowledge without interrupting the main conversation.

Session Memory

Location: src/services/SessionMemory/sessionMemory.ts

Session Memory automatically maintains a markdown file with notes about the current conversation. It runs periodically in the background using a forked subagent, extracting key information from the conversation without interrupting the user.

How It Works

1. A post-sampling hook fires after each model response
2. The hook checks whether the conversation has grown enough to warrant extraction (based on message count and tool call thresholds)
3. When thresholds are met, a forked agent reads the conversation and updates the session memory file
4. The memory file is stored at a session-specific path under ~/.claude/

Configuration

Session Memory is controlled by a remote config (tengu_sm_config) with local defaults:

Extraction Flow

User query --> Model response --> Post-sampling hook
                                       |
                            Check thresholds met?
                                       |
                              Yes: Run forked agent
                                       |
                            Read existing memory file
                                       |
                          Update with new observations
                                       |
                            Write session memory file

Session Memory and Compaction

Session Memory has a special relationship with the compact service. When auto-compact triggers, the system first attempts session memory compaction: replacing old messages with the session memory summary rather than running full LLM-based compaction. This is faster and preserves more structured context.

Auto-Memory (Extract Memories)

Location: src/services/extractMemories/extractMemories.ts

The auto-memory system extracts durable, cross-session memories at the end of each complete query loop. Unlike Session Memory (which tracks the current conversation), auto-memory captures learnings that should persist across future sessions.

Trigger Conditions

Auto-memory runs once when:

• The model produces a final response with no tool calls (end of query loop)
• The conversation has enough model-visible messages since the last extraction
• The feature is enabled via isAutoMemoryEnabled()

Memory Storage

Extracted memories are written to the auto-memory directory:

~/.claude/projects/<project-path>/memory/

The system uses scanMemoryFiles() and formatMemoryManifest() to:

1. Scan existing memory files in the directory
2. Build a manifest of current memories
3. Let the forked agent decide what to add, update, or leave unchanged

Available Tools

The extraction agent has access to a limited set of tools for managing memory files:

• FileRead: Read existing memory files
• FileEdit: Update existing memories
• FileWrite: Create new memory files
• Bash: Execute commands if needed
• Glob / Grep: Search for relevant files

Combined vs Auto-Only Extraction

The system supports two prompt modes:

Magic Docs

Location: src/services/MagicDocs/magicDocs.ts

Magic Docs is a system for automatically maintaining documentation files. When a markdown file with a special header is read during a conversation, Magic Docs periodically updates it with new learnings.

Header Pattern

A file is recognized as a Magic Doc when its first line matches:

# MAGIC DOC: Architecture Overview
_Focus on module boundaries and data flow patterns_

The pattern # MAGIC DOC: [title] triggers registration. An optional italicized line immediately after the header provides instructions to guide the update agent.

Detection and Registration

const MAGIC_DOC_HEADER_PATTERN = /^#\s*MAGIC\s+DOC:\s*(.+)$/im

export function detectMagicDocHeader(content: string): {
  title: string
  instructions?: string
} | null

When FileReadTool reads a file, a listener checks for the Magic Doc header. If found, the file path is registered in a tracked set (trackedMagicDocs).

Update Cycle

1. A file read listener detects Magic Doc headers when files are read
2. A post-sampling hook fires after each model response
3. If the model produced a final response (no pending tool calls), the hook checks all tracked Magic Docs
4. For each tracked doc, a built-in agent reads the current file content, reviews the conversation, and updates the document
5. The agent uses FileRead and FileEdit tools to modify the Magic Doc in place

function getMagicDocsAgent(): BuiltInAgentDefinition {
  return {
    // Agent with FileRead + FileEdit tools
    // Uses buildMagicDocsUpdatePrompt() for instructions
  }
}

Use Cases

Comparison