Sessions

A session represents a continuous period of AI-assisted coding activity within a project. Sessions group raw events (commits, saves, captures) into logical units that can be enriched into memory items.

Data Model

Session Lifecycle

Sessions follow a three-state lifecycle:

stateDiagram-v2
    [*] --> active : First event arrives
    active --> active : More events within 4h window
    active --> closed : 4h timeout / explicit close
    closed --> compacted : Compaction runs

The 4-Hour Window

Sessions use a 4-hour sliding window to group related activity:

1. When a new event arrives for a project, the system looks for an existing active session.
2. If an active session exists and was started less than 4 hours ago, the event is added to that session.
3. If the active session is older than 4 hours, it is automatically closed and a new session is created.
4. If no active session exists, a new session is created.

This window-based approach means a developer working on a feature across multiple tool interactions (MCP saves, VS Code commits, CLI scans) will have all their activity grouped into a single session, as long as the gap between events does not exceed the 4-hour boundary.

Auto-Creation

Sessions are created automatically -- there is no explicit "start session" action. The first event ingested for a project (after any previous session has expired) triggers the creation of a new session. This happens transparently inside the POST /api/v2/ingest endpoint.

Closing

Sessions are closed in two ways:

1. Timeout -- When a new event arrives and the current session is older than 4 hours, the old session is closed with endedAt set to the current time.
2. Explicit close -- The dashboard can close a session manually, and when all enrichment jobs for a session complete, the session is auto-closed.

Compaction

After a session is closed, it may be compacted -- a process that summarizes the session's events into a single compressed record. This reduces storage usage while preserving the essential information. Compacted sessions have status compacted.

Event Sources

Sessions can receive events from four different sources:

A single session can receive events from multiple sources. For example, a session might start with a VS Code commit capture and later receive an MCP save event when the developer switches to using Claude.

Files Modified Tracking

As events arrive, the session accumulates a merged, deduplicated list of all files that were modified during the session. This list is capped at 500 entries to prevent unbounded growth.

// Files from new events are merged into the existing list
const merged = [...new Set([...existingFiles, ...newFiles])].slice(0, 500);

The files list is used by the enrichment pipeline to provide file-path context to the AI model and by the dashboard to show what was worked on.

Session and Enrichment

Enrichment is not automatically triggered when events arrive. Instead:

1. Events are ingested and stored as raw_events associated with the session.
2. The user reviews the session in the dashboard and clicks "Generate Memory" to trigger enrichment.
3. The enrichment pipeline processes all unprocessed raw events for that session, creating memory items.

This manual trigger ensures the user has control over when AI processing runs and avoids unnecessary costs for sessions that may not need enrichment.

Managing Sessions in the Dashboard

Sessions are managed from the Memory page under the Sessions tab. Each session card shows:

• Source icon and label (MCP, CLI, VS Code, Scan)
• Event count and files modified count
• Start time and duration
• Enrichment status (pending, processing, completed, failed)

Session Detail View

Click a session to open its detail view, which includes:

• Events tab — Browse all raw events captured during the session, including timestamps and payload summaries
• Jobs tab — View enrichment job history with status, duration per stage, and error details for failed jobs
• Pipeline Timeline — A visual progress indicator showing the current stage (Enrich → Embed → Dedup → Drift Check)

Triggering Enrichment

Click the Generate Memory button on any completed session to start the enrichment pipeline. You can watch the pipeline progress in real time through the visual timeline.

Closing Sessions

From the dashboard, you can manually close an active session to finalize it. When a session is closed from the dashboard, the VS Code extension automatically creates a new session for subsequent activity.