Claude Agent SDK Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Claude Agent SDK integration within Claude-mem facilitates persistent memory by spawning a background observer agent. This system monitors active sessions, captures tool usage, and generates semantic summaries. Unlike the primary agent, the SDK-managed agent acts exclusively as an observer to process and compress context for future retrieval. Sources: CLAUDE.md, src/services/worker/SDKAgent.ts:1-12
Core Architecture and Data Flow
The integration relies on the SDKAgent class to orchestrate a subprocess via the @anthropic-ai/claude-agent-sdk. The worker service manages the lifecycle of this agent, which processes input from hook scripts and synchronizes results with the SQLite and Chroma databases. Sources: src/services/worker/SDKAgent.ts:25-30, src/services/worker/README.md:5-10
Message Processing Pipeline
The system utilizes an event-driven query loop. Instead of polling, it uses an AsyncIterableIterator to yield messages from the SessionManager directly to the SDK agent. Sources: src/services/worker/SDKAgent.ts:36-40, src/services/worker/SDKAgent.ts:211-215
This diagram illustrates the flow from initial hook trigger to the eventual storage of processed memory. Sources: src/services/worker/README.md:7-12, src/services/worker/SDKAgent.ts:80-90
Observer Role and Security
The SDK agent is strictly configured as an observer. It is explicitly denied access to destructive or investigative tools to prevent infinite loops or unauthorized file system modifications. Sources: plugin/modes/code.json:96-105
Disallowed Tools
The following tools are restricted for the SDK Agent:
| Tool Name | Reason for Restriction |
|---|---|
Bash | Prevents infinite execution loops |
Read / Write / Edit | Prevents file system modification |
Grep / Glob | Restricts code searching capability |
WebFetch / WebSearch | Prevents external network access |
Task | Prevents spawning sub-agents |
Sources: src/services/worker/SDKAgent.ts:50-64
Memory Processing and Storage
The SDKAgent processes incoming "Assistant" messages from the SDK stream. It tracks token usage (including cache creation and reads) and handles the persistence of extracted metadata. Sources: src/services/worker/SDKAgent.ts:106-125
Observation Extraction
The system parses XML-formatted output from the agent into structured observations.
The SDKAgent coordinates with the parser to translate raw text into database entries and vector embeddings. Sources: src/services/worker/SDKAgent.ts:300-345, src/sdk/parser.ts
Prompt Engineering for Memory
The system uses specific templates to guide the SDK agent in its role as a memory agent. These prompts are defined in src/sdk/prompts.ts and utilized by the createMessageGenerator method. Sources: src/services/worker/SDKAgent.ts:211-220, src/sdk/prompts.ts
| Prompt Type | Usage Scenario | Purpose |
|---|---|---|
buildInitPrompt | lastPromptNumber === 1 | Sets up the agent's context and instructions for a new session. |
buildContinuationPrompt | lastPromptNumber > 1 | Resumes an existing session with context. |
buildObservationPrompt | During tool use | Formats tool inputs/outputs for processing. |
buildSummaryPrompt | Session completion | Triggers the generation of progress summaries. |
Sources: src/services/worker/SDKAgent.ts:223-235, src/sdk/prompts.ts
Recording Focus
The agent is instructed to record specific types of project progress:
- Deliverables: Features, fixes, and configurations.
- Technical Domains: Auth, data, UI, infra, and DevOps.
- Omission Rules: Skip empty status checks, simple file listings, or repetitive operations.
Sources: plugin/modes/code.json:106-125
Token and Session Management
The integration captures and persists the memorySessionId. This allows the system to resume the observer agent's state across restarts, ensuring continuity without re-processing the entire session history. Sources: src/services/worker/SDKAgent.ts:80-95
Token Usage Tracking
The SDKAgent calculates "discovery tokens" by measuring the delta in cumulative input and output tokens for each response. This provides visibility into the cost of memory processing. Sources: src/services/worker/SDKAgent.ts:106-120, src/services/worker/SDKAgent.ts:133-135
Summary
The Claude Agent SDK integration transforms Claude Code sessions into a persistent knowledge base. By utilizing a restricted background agent, the system captures structured observations and summaries while maintaining strict security boundaries. The architecture ensures that memory processing is asynchronous, token-efficient, and fully integrated with both relational and vector storage for intelligent context retrieval. Sources: CLAUDE.md, src/services/worker/SDKAgent.ts:400-410