Automated Session Summarization
Relevant source files
The following files were used as context for generating this wiki page:
Automated Session Summarization is a core feature of the Claude-Mem system designed to capture the progress, findings, and completed tasks of an AI development session. It operates by monitoring a primary session, processing tool usage observations, and generating structured summaries that are persisted in a SQLite database and synchronized to a Chroma vector database for future context retrieval. Sources: README.md, src/services/worker/SDKAgent.ts:14-25
The system utilizes a specialized "observer" agent that remains "observer-only," meaning it does not execute tools itself but instead records what was learned or built in the primary session. This information is then used to generate a "Progress Summary Checkpoint" that captures the current trajectory of work. Sources: plugin/modes/code.json:115-135
Architecture and Data Flow
The summarization process is triggered by lifecycle hooks and managed through a worker service that orchestrates the AI processing.
Summarization Sequence
The flow begins when a session lifecycle event (like a summary checkpoint or session end) triggers a request to the Worker Service. Sources: src/hooks/summary-hook.ts, src/services/worker/http/routes/SessionRoutes.ts:466-508
The diagram above illustrates the asynchronous path from a hook trigger to final storage in the project's databases. Sources: src/services/worker/http/routes/SessionRoutes.ts:470-490, src/services/worker/SDKAgent.ts:360-405
Components involved in Summarization
| Component | Responsibility | Relevant Files |
|---|---|---|
| Summary Hook | Detects summary checkpoints and sends last messages to the worker. | summary-hook.ts |
| SessionRoutes | Handles HTTP requests, performs privacy checks, and queues requests. | SessionRoutes.ts |
| SessionManager | Manages the in-memory state and the message queue for the SDK Agent. | SessionManager.ts |
| SDKAgent | Spawns the AI process, feeds it the summary prompt, and parses the XML output. | SDKAgent.ts |
| DatabaseManager | Persists summaries in SQLite and triggers vector embedding in Chroma. | DatabaseManager.ts |
Sources: src/services/worker/README.md:27-50, src/services/worker/SDKAgent.ts:25-45
Summarization Logic and Prompts
The summarization process relies on a structured prompt that instructs the AI to generate progress notes without referencing its own actions.
Summary XML Structure
The system expects the AI to respond in a specific XML format, which includes several key sections:
- request: A short title capturing the user's request and the substance of what was done.
- investigated: What has been explored or examined so far.
- learned: New knowledge acquired about how things work.
- completed: Work that has shipped, changed, or been delivered.
- next_steps: The current trajectory of work for the session.
- notes: Additional insights or observations.
Sources: plugin/modes/code.json:152-160, src/sdk/prompts.ts:160-185
Prompt Engineering
The buildSummaryPrompt function constructs the final instruction for the AI, combining the session metadata with the latest conversation transcript. Sources: src/sdk/prompts.ts:160-165
// src/sdk/prompts.ts:160-170
export function buildSummaryPrompt(data: SummaryPromptData, mode: ModeConfig): string {
const { project, user_prompt, last_user_message, last_assistant_message } = data;
const { prompts } = mode;
return `
${prompts.header_summary_checkpoint}
PROJECT: ${project}
INITIAL REQUEST: ${user_prompt}
${prompts.summary_instruction}
${prompts.summary_context_label}
USER: ${last_user_message}
ASSISTANT: ${last_assistant_message}
${prompts.summary_format_instruction}
<summary>
<request>${prompts.xml_summary_request_placeholder}</request>
<investigated>${prompts.xml_summary_investigated_placeholder}</investigated>
<learned>${prompts.xml_summary_learned_placeholder}</learned>
<completed>${prompts.xml_summary_completed_placeholder}</completed>
<next_steps>${prompts.xml_summary_next_steps_placeholder}</next_steps>
<notes>${prompts.xml_summary_notes_placeholder}</notes>
</summary>
${prompts.summary_footer}`;
}
Sources: src/sdk/prompts.ts:160-188
Storage and Synchronization
Once generated, summaries are processed by the SDKAgent to ensure they are properly stored and indexed.
Processing the Response
The SDKAgent uses parseSummary to extract data from the AI's XML response. If successful, it performs three primary actions:
- SQLite Persistence: Stores the summary in the
summariestable. Sources: src/services/worker/SDKAgent.ts:363-370 - Chroma Sync: Generates embeddings for the summary to enable semantic search in future sessions. Sources: src/services/worker/SDKAgent.ts:385-395
- Real-time Update: Broadcasts the new summary via Server-Sent Events (SSE) to the Web Viewer UI. Sources: src/services/worker/SDKAgent.ts:405-415
Cursor Context Updates
Summarization also triggers updates to external IDE integrations. For projects using the Cursor IDE, the worker service updates the .cursor/rules/claude-mem-context.mdc file immediately after a summary is saved. This ensures that the AI in Cursor has immediate access to the latest session findings. Sources: src/services/worker-service.ts:100-125, src/services/worker/SDKAgent.ts:420-425
Session Completion
The SessionCompletionHandler manages the final state of a session. When a session is completed (manually or via SessionEnd hook), it ensures all pending summarization tasks are finished before the session is marked as closed. Sources: src/services/worker/session/SessionCompletionHandler.ts:15-35