Session State Management
Relevant source files
The following files were used as context for generating this wiki page:
Session State Management in Claude-Mem is the system responsible for tracking the lifecycle, data persistence, and asynchronous processing of AI development sessions. It ensures that observations, summaries, and user prompts are correctly associated with specific sessions and that memory remains persistent across multiple developer interactions.
The architecture relies on a "Database as the Single Source of Truth" principle, moving away from fragile in-memory synchronization to a robust SQLite-backed state machine. This system handles the transition of messages from pending to processed states, coordinates with the Claude Agent SDK, and manages session-specific metadata such as project names and prompt counts.
Sources: QUEUE-SIMPLIFICATION-PLAN.md:7-12, src/services/worker/SDKAgent.ts:16-25
Session Lifecycle and Persistence
Sessions are identified by two primary IDs: the contentSessionId (representing the user's Claude Code session) and the memorySessionId (representing the internal memory agent's session for resume functionality).
Session State Machine
A session's messages move through a defined set of states to ensure reliable processing and recovery from crashes or timeouts.
The state machine ensures that messages are not lost if the worker service crashes mid-processing. Stuck messages (processing > 5 minutes) are automatically reset to pending upon service restart.
Sources: QUEUE-SYSTEM-ANALYSIS.md:52-85, src/services/worker-service.ts:627-633
Key Data Structures
| Field | Type | Description |
|---|---|---|
content_session_id | String | The ID of the Claude Code session being observed. |
memory_session_id | String | The internal ID used by the SDK Agent for conversation resume. |
status | String | Current state: pending, processing, processed, or failed. |
retry_count | Integer | Number of failed attempts to process the message. |
project | String | Name of the project associated with the session. |
| Sources: tests/session_id_refactor.test.ts:25-60, QUEUE-SYSTEM-ANALYSIS.md:92-110 |
The "Queue Pump" Architecture
The system utilizes a "Queue Pump" (Unified Processor) model to handle message consumption. Instead of recursive polling, the SDKAgent consumes messages via an event-driven AsyncIterableIterator provided by the SessionManager.
This architecture eliminates race conditions by using atomic claimNextMessage() transactions in SQLite, replacing the previous "peek then mark" logic.
Sources: QUEUE-SIMPLIFICATION-PLAN.md:37-64, QUEUE-SYSTEM-ANALYSIS.md:208-245
SDK Agent Coordination
The SDKAgent manages the connection to the Claude Agent SDK. It is responsible for spawning the Claude subprocess and feeding it the session context.
Prompt Generation Logic
The agent generates different prompts based on the session's current state:
- Init Prompt: Used when
lastPromptNumber === 1. Contains full system instructions and project context. - Continuation Prompt: Used for subsequent prompts. Resumes the existing conversation using the
memorySessionId. - Observation/Summary Prompts: Specific synthetic prompts created from queued database messages.
// From SDKAgent.ts:202-230
const initPrompt = isInitPrompt
? buildInitPrompt(session.project, session.contentSessionId, session.userPrompt, mode)
: buildContinuationPrompt(session.userPrompt, session.lastPromptNumber, session.contentSessionId, mode);
yield {
type: 'user',
message: { role: 'user', content: initPrompt },
session_id: session.contentSessionId,
isSynthetic: true
};
Sources: src/services/worker/SDKAgent.ts:202-230, QUEUE-SYSTEM-ANALYSIS.md:410-445
HTTP Entry Points and API
The SessionRoutes class handles the lifecycle requests from the plugin hooks.
Critical API Endpoints
| Endpoint | Method | Purpose |
|---|---|---|
/api/sessions/init | POST | Initializes a session, increments prompt count, and saves the user prompt. |
/api/sessions/observations | POST | Queues a tool usage observation by Claude ID. |
/api/sessions/summarize | POST | Triggers a progress summary for the current session. |
/sessions/:id/status | GET | Returns the processing status and queue depth for a session. |
| Sources: src/services/worker/http/routes/SessionRoutes.ts:160-190, src/services/worker/README.md:46-55 |
Recovery and Maintenance
The system includes several automated recovery mechanisms to handle unexpected failures:
- Startup Recovery: Upon worker initialization, the
DatabaseManagerandPendingMessageStoreidentify and reset messages that were left in theprocessingstate for more than 5 minutes. - Recursive Restarts: If the
SDKAgentexits but the database still contains pending work, theSessionRouteslogic triggers an automatic restart of the generator. - Orphaned Process Cleanup: The worker service identifies and kills orphaned
chroma-mcpprocesses on startup to prevent memory leaks and port conflicts.
Sources: src/services/worker-service.ts:627-633, src/services/worker/http/routes/SessionRoutes.ts:125-155, src/services/worker-service.ts:400-450
Conclusion
Session State Management in Claude-Mem provides a resilient, database-backed foundation for long-term AI memory. By centralizing state in SQLite and using an atomic "claim-and-process" queue, the system ensures that developer context is captured accurately, preserved across crashes, and efficiently indexed for future retrieval.