cognitive-core 0.1.0 → 0.2.0

package/docs/DESIGN-session-bank.md

@@ -0,0 +1,1134 @@
+# Design: Session Bank (Entire-backed)
+
+> **Status**: Proposed
+> **Authors**: Alex Ngai, Claude
+> **Date**: 2026-02-24
+> **Related**: [Entire CLI](https://github.com/entireio/cli), [ReMem](https://arxiv.org/abs/2501.00662)
+
+## 1. Motivation
+
+cognitive-core's learning pipeline operates on **Trajectory** objects — structured sequences of thought/action/observation steps with an outcome. Today, trajectories are constructed synthetically (tests, manual creation) or extracted in-memory from `AgentSession` objects that are discarded after execution.
+
+This creates three problems:
+
+1. **No durable session capture** — When an agent runs outside cognitive-core (e.g. Claude Code sessions, standalone CLI agents), there is no mechanism to ingest those sessions as trajectories. The richest source of learning data — real developer interactions — is lost.
+
+2. **No raw transcript preservation** — The `Trajectory` type is a lossy abstraction. It discards conversational context, partial reasoning, tool call timing, and multi-turn structure. Once converted, the original session is gone.
+
+3. **No session-level queries** — The existing `ExperienceMemory` stores compressed experience tuples. There is no way to ask "show me all sessions where the agent debugged a TypeScript error" at the raw session level, before lossy compression.
+
+### The Entire Opportunity
+
+[Entire](https://github.com/entireio/cli) is a Go CLI tool that captures full agent session transcripts via Claude Code (and Gemini CLI) hooks. It stores data on an orphan git branch (`entire/checkpoints/v1`), providing:
+
+- **Automatic capture** — 7 hook events: session-start, session-end, stop, user-prompt-submit, pre-task, post-task, post-todo
+- **Full fidelity** — JSONL transcripts preserve every message, tool call, and observation in the agent's native format
+- **Rich metadata** — token usage, file attribution, AI-generated summaries (intent, outcome, learnings, friction points)
+- **Git-native storage** — checkpoint-sharded orphan branch, pushed alongside your code
+- **Commit linking** — git trailers (`Entire-Checkpoint`, `Entire-Session`) bidirectionally link code commits to session data
+
+By using Entire as the capture and storage layer, cognitive-core gains a durable session archive without building its own capture infrastructure.
+
+### Standalone Package Philosophy
+
+The session bank is designed as a **standalone TypeScript package** (`@entire-sessions/reader` or similar) that can be used independently of cognitive-core. It reads from Entire's orphan branch and exposes a generic session query API. cognitive-core then adapts it via a thin `EntireTrajectorySource` implementing the existing `TrajectorySource` interface.
+
+This keeps the boundary clean:
+- **session-bank** knows about Entire's data format, not about Trajectories
+- **cognitive-core** knows about Trajectories, not about Entire's internals
+- The adapter is the only code that bridges the two
+
+## 2. Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     cognitive-core                               │
+│                                                                 │
+│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐       │
+│  │  Playbook    │  │  Experience  │  │  Knowledge Bank   │       │
+│  │  Library     │  │  Memory      │  │  (semantic)       │       │
+│  └──────┬──────┘  └──────┬───────┘  └───────┬───────────┘       │
+│         │                │                   │                   │
+│         │     ┌──────────┴──────────┐        │                   │
+│         └─────┤   Learning Pipeline ├────────┘                   │
+│               └─────────┬───────────┘                            │
+│                         │                                        │
+│               ┌─────────┴───────────┐                            │
+│               │ EntireTrajectory    │  ← adapter (in cognitive-  │
+│               │ Source              │     core, implements        │
+│               │                     │     TrajectorySource)       │
+│               └─────────┬───────────┘                            │
+│                         │                                        │
+└─────────────────────────┼────────────────────────────────────────┘
+                          │ uses
+┌─────────────────────────▼────────────────────────────────────────┐
+│               session-bank (standalone package)                   │
+│                                                                   │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐   │
+│  │ EntireGit    │  │ Transcript   │  │ SessionBank           │   │
+│  │ Reader       │  │ Parser       │  │ (facade: discover,    │   │
+│  │ (git plumb)  │  │ (JSONL→types)│  │  query, get, count)   │   │
+│  └──────┬───────┘  └──────┬───────┘  └──────────┬────────────┘   │
+│         │                 │                      │               │
+│         └────────┬────────┘                      │               │
+│                  │ reads                          │ exposes       │
+│                  ▼                                ▼               │
+│         git show / ls-tree              SessionRecord[]          │
+└──────────────────┬───────────────────────────────────────────────┘
+                   │
+              reads from
+                   │
+       ┌───────────▼─────────────┐
+       │ entire/checkpoints/v1   │  (orphan branch)
+       │                         │
+       │ <id[:2]>/<id[2:]>/      │  checkpoint-sharded
+       │ ├── metadata.json       │  root summary
+       │ ├── 0/                  │  session subdirectory
+       │ │   ├── metadata.json   │  committed metadata
+       │ │   ├── full.jsonl      │  raw transcript
+       │ │   ├── prompt.txt      │  user prompts
+       │ │   └── context.md      │  generated context
+       │ └── tasks/              │  subagent checkpoints
+       └─────────────────────────┘
+```
+
+### Data Flow
+
+```
+1. Developer uses Claude Code (Entire hooks installed)
+         │
+         ▼
+2. Entire hooks fire on session events → capture to shadow branch
+         │
+         ▼
+3. Developer commits → post-commit hook condenses to entire/checkpoints/v1
+         │
+         ▼
+4. session-bank: SessionBank.discover() reads orphan branch via git plumbing
+         │
+         ▼
+5. session-bank: Parser converts JSONL → SessionRecord (with metadata, events, summary)
+         │
+         ▼
+6. cognitive-core: EntireTrajectorySource.load() calls SessionBank, synthesizes Trajectories
+         │
+         ▼
+7. cognitive-core: LearningPipeline.processTrajectory() → playbooks, experiences, knowledge
+```
+
+## 3. Entire's Real Storage Format
+
+Based on analysis of [`entireio/cli`](https://github.com/entireio/cli) source code.
+
+### Branch Structure
+
+Entire uses the `entire/checkpoints/v1` orphan branch. Checkpoints are **sharded by the first 2 hex chars** of the checkpoint ID (256 possible buckets):
+
+```
+entire/checkpoints/v1 branch tree:
+<checkpointId[:2]>/<checkpointId[2:]>/
+├── metadata.json              # CheckpointSummary (root-level, aggregated)
+├── 0/                         # First session subdirectory
+│   ├── metadata.json          # CommittedMetadata for this session
+│   ├── full.jsonl             # Complete transcript (Claude native JSONL)
+│   ├── prompt.txt             # Concatenated user prompts
+│   ├── context.md             # Generated context document
+│   └── content_hash.txt       # Deduplication hash
+├── 1/                         # Second session (if concurrent)
+│   └── ...
+└── tasks/                     # Task/subagent checkpoints (optional)
+    └── <tool-use-id>/
+        ├── checkpoint.json    # Task checkpoint metadata
+        ├── agent-<id>.jsonl   # Subagent transcript
+        └── checkpoints/
+            └── NNN-<id>.json  # Incremental checkpoints
+```
+
+### ID Formats
+
+- **Checkpoint ID**: 12 lowercase hex chars (e.g. `a3b2c4d5e6f7`), generated from 6 random bytes
+- **Session ID**: `YYYY-MM-DD-<UUID>` (e.g. `2026-01-08-abc123de-f456-7890-abcd-ef1234567890`)
+
+### Transcript Format (full.jsonl)
+
+Each line is Claude's native JSONL format:
+
+```jsonl
+{"type":"user","uuid":"abc123","message":{"content":"Fix the bug in auth.ts"}}
+{"type":"assistant","uuid":"def456","message":{"content":[{"type":"text","text":"I'll fix that..."},{"type":"tool_use","name":"Edit","input":{"file_path":"/src/auth.ts","old_string":"...","new_string":"..."}}]}}
+{"type":"user","uuid":"ghi789","message":{"content":[{"type":"tool_result","tool_use_id":"...","content":"File edited successfully"}]}}
+```
+
+The `message.content` is either:
+- A string (user text messages)
+- An array of `ContentBlock` objects (assistant responses with text + tool_use, or user messages with tool_results)
+
+Transcripts exceeding 50MB are chunked: `full.jsonl.001`, `full.jsonl.002`, etc.
+
+### Session Metadata (per-session metadata.json)
+
+```typescript
+// Entire's CommittedMetadata (Go struct → TypeScript equivalent)
+interface EntireCommittedMetadata {
+  cli_version: string;
+  checkpoint_id: string;              // 12-hex-char
+  session_id: string;                 // YYYY-MM-DD-<UUID>
+  strategy: 'manual-commit' | 'auto-commit';
+  created_at: string;                 // RFC3339
+  branch: string;                     // source code branch
+  files_touched: string[];            // files modified during session
+  agent: string;                      // "Claude Code", "Gemini CLI", etc.
+  is_task: boolean;
+  tool_use_id?: string;               // for task checkpoints
+  checkpoint_transcript_start: number; // line offset into JSONL
+  token_usage: EntireTokenUsage;
+  summary?: EntireSummary;            // AI-generated (optional)
+  initial_attribution?: EntireAttribution;
+}
+
+interface EntireTokenUsage {
+  input_tokens: number;
+  cache_creation_tokens: number;
+  cache_read_tokens: number;
+  output_tokens: number;
+  api_call_count: number;
+  subagent_usage?: EntireTokenUsage[];
+}
+
+interface EntireSummary {
+  intent: string;                     // What the user was trying to do
+  outcome: string;                    // What happened
+  learnings: {
+    repo_patterns: string[];          // Repository-specific patterns
+    code_findings: string[];          // Code-specific findings
+    workflow_practices: string[];     // Workflow learnings
+  };
+  friction_points: string[];          // Where things went wrong
+  open_items: string[];               // Unfinished work
+}
+
+interface EntireAttribution {
+  agent_lines_added: number;
+  human_additions: number;
+  human_modifications: number;
+  human_removals: number;
+  total_committed_lines: number;
+  agent_contribution: number;         // 0-1 percentage
+}
+```
+
+### Root Checkpoint Summary (root metadata.json)
+
+```typescript
+interface EntireCheckpointSummary {
+  sessions: Array<{
+    metadata: string;      // path: "0/metadata.json"
+    transcript: string;    // path: "0/full.jsonl"
+    context: string;       // path: "0/context.md"
+    content_hash: string;  // path: "0/content_hash.txt"
+    prompt: string;        // path: "0/prompt.txt"
+  }>;
+}
+```
+
+### Commit Trailers
+
+Entire writes trailers into user git commits for bidirectional linking:
+
+```
+Entire-Checkpoint: a3b2c4d5e6f7
+Entire-Session: 2026-01-08-abc123de-f456-7890-abcd-ef1234567890
+Entire-Strategy: manual-commit
+```
+
+## 4. Standalone Package: Type Definitions
+
+These types are defined by the session-bank package — they represent parsed, normalized Entire data. They are deliberately **not** cognitive-core types.
+
+### SessionRecord — The Core Type
+
+```typescript
+/**
+ * A parsed Entire checkpoint session — the primary data type exposed
+ * by the session bank. Contains the full transcript, metadata, and
+ * Entire's AI-generated summary.
+ *
+ * This is the intermediate representation between Entire's raw files
+ * on the orphan branch and any downstream consumer (cognitive-core,
+ * analytics, UI, etc.).
+ */
+export interface SessionRecord {
+  /** Entire session ID (YYYY-MM-DD-<UUID>) */
+  sessionId: string;
+
+  /** Entire checkpoint ID (12-hex-char) */
+  checkpointId: string;
+
+  /** Parsed metadata from per-session metadata.json */
+  metadata: SessionMetadata;
+
+  /** Parsed transcript events from full.jsonl */
+  transcript: TranscriptMessage[];
+
+  /** AI-generated summary (from Entire's summarize feature, if enabled) */
+  summary?: SessionSummary;
+
+  /** Token usage statistics */
+  tokenUsage: TokenUsage;
+
+  /** Line-level code attribution */
+  attribution?: Attribution;
+
+  /** Provenance: where this data came from on the orphan branch */
+  source: SessionSource;
+}
+
+export interface SessionMetadata {
+  /** Entire CLI version that captured this */
+  cliVersion: string;
+  /** Checkpoint strategy used */
+  strategy: 'manual-commit' | 'auto-commit';
+  /** When the checkpoint was created */
+  createdAt: Date;
+  /** Source code branch the session was on */
+  branch: string;
+  /** Agent that ran the session */
+  agent: string;
+  /** Working directory (if available from context) */
+  cwd?: string;
+  /** Files modified during the session */
+  filesTouched: string[];
+  /** Whether this is a task (subagent) checkpoint */
+  isTask: boolean;
+  /** Tool use ID (for task checkpoints) */
+  toolUseId?: string;
+}
+
+export interface TranscriptMessage {
+  /** Message role */
+  role: 'user' | 'assistant';
+  /** Unique message identifier */
+  uuid: string;
+  /** Content blocks */
+  content: ContentBlock[];
+  /** Computed: index in original JSONL */
+  lineIndex: number;
+}
+
+export type ContentBlock =
+  | TextBlock
+  | ToolUseBlock
+  | ToolResultBlock;
+
+export interface TextBlock {
+  type: 'text';
+  text: string;
+}
+
+export interface ToolUseBlock {
+  type: 'tool_use';
+  id: string;
+  name: string;
+  input: Record<string, unknown>;
+}
+
+export interface ToolResultBlock {
+  type: 'tool_result';
+  toolUseId: string;
+  content: string;
+  isError?: boolean;
+}
+
+export interface SessionSummary {
+  /** What the user was trying to accomplish */
+  intent: string;
+  /** What actually happened */
+  outcome: string;
+  /** Learnings from the session */
+  learnings: {
+    repoPatterns: string[];
+    codeFindings: string[];
+    workflowPractices: string[];
+  };
+  /** Where things went wrong or caused friction */
+  frictionPoints: string[];
+  /** Unfinished work or follow-ups */
+  openItems: string[];
+}
+
+export interface TokenUsage {
+  inputTokens: number;
+  cacheCreationTokens: number;
+  cacheReadTokens: number;
+  outputTokens: number;
+  apiCallCount: number;
+  subagentUsage?: TokenUsage[];
+  /** Computed: total tokens across all categories */
+  total: number;
+}
+
+export interface Attribution {
+  agentLinesAdded: number;
+  humanAdditions: number;
+  humanModifications: number;
+  humanRemovals: number;
+  totalCommittedLines: number;
+  /** 0-1 percentage of agent contribution */
+  agentContribution: number;
+}
+
+export interface SessionSource {
+  /** Orphan branch name */
+  branch: string;
+  /** Path on branch: "<id[:2]>/<id[2:]>" */
+  checkpointPath: string;
+  /** Session subdirectory index: "0", "1", etc. */
+  sessionIndex: string;
+  /** Git commit SHA on the orphan branch containing this data */
+  commitSha?: string;
+  /** Git commit SHA on the source branch linked via Entire-Checkpoint trailer */
+  linkedCommitSha?: string;
+}
+```
+
+### SessionQuery — Query Interface
+
+```typescript
+/**
+ * Query options for filtering sessions in the bank.
+ */
+export interface SessionQuery {
+  /** Only checkpoints created after this date */
+  since?: Date;
+  /** Only checkpoints created before this date */
+  before?: Date;
+  /** Filter by source code branch (exact match) */
+  branch?: string;
+  /** Filter by agent type (e.g. "Claude Code") */
+  agent?: string;
+  /** Full-text search across user messages */
+  search?: string;
+  /** Filter by checkpoint strategy */
+  strategy?: 'manual-commit' | 'auto-commit';
+  /** Only include sessions with/without summaries */
+  hasSummary?: boolean;
+  /** Maximum number of sessions to return */
+  limit?: number;
+  /** Sort order (default: newest first) */
+  sort?: 'newest' | 'oldest';
+  /** Only sessions not yet marked as processed */
+  unprocessedOnly?: boolean;
+}
+
+export interface SessionQueryResult {
+  sessions: SessionRecord[];
+  total: number;
+}
+```
+
+### CheckpointRef — Lightweight Reference
+
+```typescript
+/**
+ * Lightweight reference to a checkpoint, for enumeration without
+ * loading full transcripts.
+ */
+export interface CheckpointRef {
+  checkpointId: string;
+  sessionIds: string[];
+  path: string;
+  /** Available without loading full metadata */
+  sessionCount: number;
+}
+```
+
+## 5. Standalone Package: Core Components
+
+### 5.1 EntireGitReader
+
+Low-level git plumbing for reading from the orphan branch without checkout.
+
+```typescript
+export class EntireGitReader {
+  constructor(options: { repoPath: string; branch?: string });
+
+  /** Check if the orphan branch exists in this repo */
+  async branchExists(): Promise<boolean>;
+
+  /**
+   * List all checkpoint directories (top-level shard + inner dirs).
+   * Returns paths like ["a3/b2c4d5e6f7", "f1/0a9b8c7d6e5f", ...]
+   */
+  async listCheckpoints(): Promise<string[]>;
+
+  /**
+   * List session subdirectories within a checkpoint.
+   * Returns ["0", "1", ...] (numeric session indices)
+   */
+  async listSessions(checkpointPath: string): Promise<string[]>;
+
+  /** Read a single file from the orphan branch */
+  async readFile(path: string): Promise<string>;
+
+  /**
+   * Read multiple files in batch (minimizes git process spawns).
+   * Returns Map<path, content>. Missing files are omitted.
+   */
+  async readFiles(paths: string[]): Promise<Map<string, string>>;
+
+  /**
+   * Read a file, returning null if it doesn't exist (no throw).
+   */
+  async readFileOrNull(path: string): Promise<string | null>;
+
+  /**
+   * Get the HEAD commit SHA of the orphan branch.
+   * Useful for cache invalidation.
+   */
+  async getBranchHead(): Promise<string | null>;
+}
+```
+
+**Implementation:**
+
+```bash
+# Branch existence
+git rev-parse --verify entire/checkpoints/v1
+
+# List shard directories (top-level: "a3", "f1", etc.)
+git ls-tree --name-only entire/checkpoints/v1
+
+# List checkpoints within a shard
+git ls-tree --name-only entire/checkpoints/v1 a3/
+
+# List session subdirs within a checkpoint
+git ls-tree --name-only entire/checkpoints/v1 a3/b2c4d5e6f7/
+
+# Read a file
+git show entire/checkpoints/v1:a3/b2c4d5e6f7/0/metadata.json
+
+# Batch read (single git process via cat-file --batch)
+echo "entire/checkpoints/v1:a3/b2c4d5e6f7/0/metadata.json" | git cat-file --batch
+```
+
+### 5.2 EntireTranscriptParser
+
+Parses Entire's raw files into `SessionRecord` objects.
+
+```typescript
+export class EntireTranscriptParser {
+  /**
+   * Parse a full session from its component files.
+   */
+  parseSession(
+    metadataJson: string,
+    transcriptJsonl: string,
+    checkpointPath: string,
+    sessionIndex: string
+  ): SessionRecord;
+
+  /**
+   * Parse just the per-session metadata (fast path for listing).
+   */
+  parseMetadata(metadataJson: string): SessionMetadata & {
+    sessionId: string;
+    checkpointId: string;
+    summary?: SessionSummary;
+    tokenUsage: TokenUsage;
+    attribution?: Attribution;
+  };
+
+  /**
+   * Parse a JSONL transcript into structured messages.
+   * Handles Claude's native JSONL format:
+   *   {"type":"user"|"assistant", "uuid":"...", "message":{...}}
+   *
+   * Tolerant of malformed lines (skips with warning).
+   */
+  parseTranscript(jsonlContent: string): TranscriptMessage[];
+
+  /**
+   * Parse chunked transcripts (full.jsonl.001, .002, etc.)
+   * by concatenating chunks before parsing.
+   */
+  parseChunkedTranscript(chunks: string[]): TranscriptMessage[];
+
+  /**
+   * Parse the root checkpoint summary to discover session subdirectories.
+   */
+  parseCheckpointSummary(metadataJson: string): CheckpointRef;
+}
+```
+
+**JSONL parsing details:**
+
+Each line in Entire's transcript follows Claude's format:
+
+```typescript
+// Raw JSONL line shape
+interface RawTranscriptLine {
+  type: 'user' | 'assistant';
+  uuid: string;
+  message: {
+    content: string | RawContentBlock[];
+  };
+}
+
+interface RawContentBlock {
+  type: 'text' | 'tool_use' | 'tool_result';
+  text?: string;          // for type === 'text'
+  name?: string;          // for type === 'tool_use'
+  input?: Record<string, unknown>; // for type === 'tool_use'
+  tool_use_id?: string;   // for type === 'tool_result'
+  content?: string;       // for type === 'tool_result'
+}
+```
+
+The parser normalizes this into `TranscriptMessage` with typed `ContentBlock` discriminated union. String content is wrapped into `[{ type: 'text', text: content }]` for consistency.
+
+### 5.3 SessionBank — Main Facade
+
+```typescript
+export class SessionBank {
+  constructor(options?: SessionBankOptions);
+
+  /**
+   * Initialize: verify orphan branch exists, optionally build index.
+   * @throws if repoPath is not a git repository
+   */
+  async init(): Promise<void>;
+
+  /** Whether the Entire orphan branch exists in this repo */
+  isAvailable(): boolean;
+
+  // ── Discovery ──────────────────────────────────────────────
+
+  /**
+   * List all checkpoint references without loading transcripts.
+   * Fast: only reads directory listings and root metadata.json files.
+   */
+  async listCheckpoints(): Promise<CheckpointRef[]>;
+
+  /**
+   * Discover all sessions across all checkpoints.
+   * Loads metadata but NOT transcripts (lazy loading).
+   */
+  async discover(): Promise<SessionRecord[]>;
+
+  /**
+   * Count sessions matching a query.
+   */
+  async count(query?: SessionQuery): Promise<number>;
+
+  // ── Querying ───────────────────────────────────────────────
+
+  /**
+   * Query sessions with filtering and sorting.
+   * Loads full transcripts only for matching sessions.
+   */
+  async query(query?: SessionQuery): Promise<SessionQueryResult>;
+
+  /**
+   * Get a single session by session ID.
+   * Searches across all checkpoints.
+   */
+  async getBySessionId(sessionId: string): Promise<SessionRecord | undefined>;
+
+  /**
+   * Get all sessions within a specific checkpoint.
+   */
+  async getByCheckpointId(checkpointId: string): Promise<SessionRecord[]>;
+
+  /**
+   * Find the session(s) linked to a specific git commit.
+   * Uses git log to find Entire-Checkpoint trailers.
+   */
+  async getByCommit(commitSha: string): Promise<SessionRecord[]>;
+
+  // ── Processing Tracking ────────────────────────────────────
+
+  /**
+   * Mark a session as processed by an external consumer.
+   * Tracked in a local state file to avoid re-processing.
+   */
+  async markProcessed(
+    sessionId: string,
+    metadata?: Record<string, unknown>
+  ): Promise<void>;
+
+  /** Check if a session has been marked as processed */
+  isProcessed(sessionId: string): boolean;
+
+  /** Get all processing log entries */
+  getProcessingLog(): ProcessingLogEntry[];
+
+  // ── Cache Management ───────────────────────────────────────
+
+  /**
+   * Invalidate cached data (forces re-read from git on next query).
+   * Called automatically when orphan branch HEAD changes.
+   */
+  invalidateCache(): void;
+
+  // ── Lifecycle ──────────────────────────────────────────────
+
+  async close(): Promise<void>;
+}
+
+export interface SessionBankOptions {
+  /** Git repository path (default: process.cwd()) */
+  repoPath?: string;
+  /** Orphan branch name (default: 'entire/checkpoints/v1') */
+  branch?: string;
+  /** Directory to store processing state (default: '.atlas/session-bank') */
+  stateDir?: string;
+  /** Enable in-memory caching of parsed sessions */
+  cache?: boolean;
+}
+
+export interface ProcessingLogEntry {
+  sessionId: string;
+  processedAt: Date;
+  metadata?: Record<string, unknown>;
+}
+```
+
+### Lazy Loading Strategy
+
+The session bank uses a two-tier loading approach:
+
+1. **Metadata-only (fast)**: `listCheckpoints()` and `discover()` read only `metadata.json` files. This is fast because it avoids parsing potentially large JSONL transcripts.
+
+2. **Full load (on demand)**: `query()`, `getBySessionId()`, `getByCheckpointId()` load the full `full.jsonl` transcript. The transcript is parsed lazily — only when a query actually matches.
+
+This matters because JSONL transcripts can be large (Entire chunks at 50MB).
+
+## 6. cognitive-core Adapter: EntireTrajectorySource
+
+This lives in cognitive-core, not in the standalone package. It adapts `SessionRecord` into `Trajectory`.
+
+```typescript
+// src/learning/trajectory-sources/entire.ts
+
+import type { SessionRecord, SessionBank } from '@entire-sessions/reader';
+import type {
+  TrajectorySource,
+  TrajectoryWithAnalysis,
+  TrajectoryLoadOptions,
+} from '../../types/trajectory-source.js';
+import type { Trajectory, Step, Task, Outcome } from '../../types/index.js';
+
+export interface EntireSynthesisOptions {
+  /** Domain to assign (default: inferred from branch/files) */
+  domain?: string;
+  /** How to determine success/failure (default: 'summary') */
+  outcomeStrategy?: 'summary' | 'heuristic' | 'llm';
+}
+
+export class EntireTrajectorySource implements TrajectorySource {
+  readonly name = 'entire';
+
+  constructor(
+    private sessionBank: SessionBank,
+    private options?: EntireSynthesisOptions
+  ) {}
+
+  async load(options?: TrajectoryLoadOptions): Promise<TrajectoryWithAnalysis[]> {
+    const result = await this.sessionBank.query({
+      since: options?.since,
+      limit: options?.limit,
+      unprocessedOnly: false,
+    });
+
+    return result.sessions
+      .map(session => {
+        try {
+          return {
+            trajectory: this.synthesize(session),
+            analysis: undefined, // consumer computes this
+          };
+        } catch {
+          return null;
+        }
+      })
+      .filter((t): t is TrajectoryWithAnalysis => t !== null)
+      .filter(t => {
+        if (options?.domain && t.trajectory.task.domain !== options.domain) return false;
+        if (options?.successOnly && !t.trajectory.outcome.success) return false;
+        return true;
+      });
+  }
+
+  async count(options?: TrajectoryLoadOptions): Promise<number> {
+    return this.sessionBank.count({
+      since: options?.since,
+      limit: options?.limit,
+    });
+  }
+
+  /**
+   * Convert an Entire SessionRecord into a cognitive-core Trajectory.
+   */
+  synthesize(session: SessionRecord): Trajectory {
+    return {
+      id: `entire-${session.checkpointId}-${session.sessionId}`,
+      task: this.extractTask(session),
+      steps: this.extractSteps(session),
+      outcome: this.inferOutcome(session),
+      agentId: session.metadata.agent,
+      timestamp: session.metadata.createdAt,
+      llmCalls: session.tokenUsage.apiCallCount,
+      totalTokens: session.tokenUsage.total,
+      wallTimeSeconds: 0, // not available from metadata alone
+      metadata: {
+        source: 'entire',
+        checkpointId: session.checkpointId,
+        sessionId: session.sessionId,
+        branch: session.metadata.branch,
+        filesTouched: session.metadata.filesTouched,
+        strategy: session.metadata.strategy,
+        attribution: session.attribution,
+      },
+    };
+  }
+
+  // ── Private helpers ──────────────────────────────────────
+
+  private extractTask(session: SessionRecord): Task {
+    // Prefer Entire's summary intent over raw first message
+    const description = session.summary?.intent
+      ?? this.getFirstUserMessage(session)
+      ?? 'Unknown task';
+
+    return {
+      id: `task-${session.sessionId}`,
+      domain: this.options?.domain ?? this.inferDomain(session),
+      description,
+      context: {
+        filesTouched: session.metadata.filesTouched,
+        branch: session.metadata.branch,
+      },
+      metadata: {},
+      createdAt: session.metadata.createdAt,
+    };
+  }
+
+  private extractSteps(session: SessionRecord): Step[] {
+    const steps: Step[] = [];
+
+    for (const msg of session.transcript) {
+      if (msg.role !== 'assistant') continue;
+
+      // Extract text blocks as thought
+      const textBlocks = msg.content.filter(b => b.type === 'text');
+      const thought = textBlocks.map(b => (b as { text: string }).text).join('\n');
+
+      // Extract tool_use blocks as actions
+      const toolBlocks = msg.content.filter(b => b.type === 'tool_use');
+
+      if (toolBlocks.length === 0) {
+        // Pure reasoning step (no tool calls)
+        if (thought) {
+          steps.push({
+            thought,
+            action: '',
+            observation: '',
+            timestamp: session.metadata.createdAt, // approximation
+            metadata: { messageUuid: msg.uuid },
+          });
+        }
+      } else {
+        // One step per tool call, sharing the thought
+        for (const tool of toolBlocks) {
+          const t = tool as { name: string; id: string; input: Record<string, unknown> };
+          const observation = this.findToolResult(session.transcript, t.id);
+
+          steps.push({
+            thought: steps.length === 0 || thought ? thought : undefined,
+            action: `${t.name}(${JSON.stringify(t.input)})`,
+            observation: observation ?? '',
+            timestamp: session.metadata.createdAt,
+            metadata: {
+              messageUuid: msg.uuid,
+              toolName: t.name,
+              toolUseId: t.id,
+            },
+          });
+        }
+      }
+    }
+
+    return steps;
+  }
+
+  private inferOutcome(session: SessionRecord): Outcome {
+    const strategy = this.options?.outcomeStrategy ?? 'summary';
+
+    if (strategy === 'summary' && session.summary) {
+      // Use Entire's AI-generated outcome
+      const outcome = session.summary.outcome.toLowerCase();
+      const success = !outcome.includes('fail') &&
+                      !outcome.includes('error') &&
+                      !outcome.includes('unable') &&
+                      !outcome.includes('could not');
+      return {
+        success,
+        partialScore: success ? 1.0 : 0.0,
+        verificationDetails: {
+          entireOutcome: session.summary.outcome,
+          frictionPoints: session.summary.frictionPoints,
+          openItems: session.summary.openItems,
+        },
+      };
+    }
+
+    // Heuristic fallback
+    const hasFiles = session.metadata.filesTouched.length > 0;
+    return {
+      success: hasFiles, // if files were touched, something was accomplished
+      partialScore: hasFiles ? 0.7 : 0.3,
+      verificationDetails: { strategy: 'heuristic' },
+    };
+  }
+
+  private inferDomain(session: SessionRecord): string {
+    const files = session.metadata.filesTouched;
+    if (files.some(f => f.match(/\.(test|spec)\.(ts|js|tsx|jsx)$/))) return 'testing';
+    if (files.some(f => f.match(/\.(ts|tsx)$/))) return 'typescript';
+    if (files.some(f => f.match(/\.(py)$/))) return 'python';
+    if (files.some(f => f.match(/\.(go)$/))) return 'go';
+    if (files.some(f => f.match(/\.(rs)$/))) return 'rust';
+    return 'code';
+  }
+
+  private getFirstUserMessage(session: SessionRecord): string | undefined {
+    const firstUser = session.transcript.find(m => m.role === 'user');
+    if (!firstUser) return undefined;
+    const textBlock = firstUser.content.find(b => b.type === 'text');
+    return textBlock ? (textBlock as { text: string }).text : undefined;
+  }
+
+  private findToolResult(
+    messages: SessionRecord['transcript'],
+    toolUseId: string
+  ): string | undefined {
+    for (const msg of messages) {
+      if (msg.role !== 'user') continue;
+      for (const block of msg.content) {
+        if (block.type === 'tool_result' && (block as { toolUseId: string }).toolUseId === toolUseId) {
+          return (block as { content: string }).content;
+        }
+      }
+    }
+    return undefined;
+  }
+}
+```
+
+### Key Synthesis Decisions
+
+| Decision | Approach | Rationale |
+|----------|----------|-----------|
+| Task description | Use `summary.intent` (prefer) or first user message | Entire's AI summary produces cleaner task descriptions than raw prompts |
+| Outcome | Use `summary.outcome` keywords | Entire already runs outcome analysis; avoids duplicate LLM call |
+| Domain | Infer from `filesTouched` extensions | Simple heuristic; can be overridden via options |
+| Step grouping | One step per tool_use, shared thought | Matches ReAct format; preserves tool-level granularity |
+| Token count | Use `tokenUsage.total` directly | Entire captures real API usage, no need to estimate |
+| Trajectory ID | `entire-{checkpointId}-{sessionId}` | Globally unique, traceable back to source |
+
+## 7. cognitive-core Integration
+
+### Config Addition
+
+```typescript
+// Add to AtlasConfigSchema
+const SessionBankConfigSchema = z.object({
+  /** Enable session bank integration */
+  enabled: z.boolean().default(false),
+  /** Orphan branch name */
+  branch: z.string().default('entire/checkpoints/v1'),
+  /** State directory (relative to storage.baseDir) */
+  stateDir: z.string().default('session-bank'),
+  /** Default outcome strategy for synthesis */
+  outcomeStrategy: z.enum(['summary', 'heuristic', 'llm']).default('summary'),
+  /** Auto-ingest unprocessed sessions on init */
+  autoIngest: z.boolean().default(false),
+  /** Maximum sessions per auto-ingest batch */
+  maxIngestBatch: z.number().default(20),
+});
+```
+
+### Atlas Integration
+
+```typescript
+class Atlas {
+  // Existing...
+
+  getSessionBank(): SessionBank | null;
+
+  /**
+   * Ingest unprocessed Entire sessions into the learning pipeline.
+   * Each session is: parsed → synthesized to Trajectory → processTrajectory()
+   */
+  async ingestEntireSessions(options?: {
+    limit?: number;
+    domain?: string;
+    outcomeStrategy?: 'summary' | 'heuristic' | 'llm';
+  }): Promise<IngestResult>;
+}
+```
+
+### Ingestion Flow (inside Atlas)
+
+```typescript
+async ingestEntireSessions(options) {
+  const bank = this.getSessionBank();
+  if (!bank) throw new Error('Session bank not enabled');
+
+  const source = new EntireTrajectorySource(bank, {
+    domain: options?.domain,
+    outcomeStrategy: options?.outcomeStrategy,
+  });
+
+  const sessions = await bank.query({
+    unprocessedOnly: true,
+    limit: options?.limit ?? this.config.sessionBank.maxIngestBatch,
+  });
+
+  const results = [];
+  for (const session of sessions.sessions) {
+    try {
+      const trajectory = source.synthesize(session);
+      const processResult = await this.processTrajectory(trajectory);
+      await bank.markProcessed(session.sessionId, {
+        trajectoryId: trajectory.id,
+      });
+      results.push({ sessionId: session.sessionId, trajectoryId: trajectory.id, success: true });
+    } catch (error) {
+      results.push({ sessionId: session.sessionId, success: false, error: String(error) });
+    }
+  }
+
+  return { discovered: sessions.total, ingested: results.filter(r => r.success).length, ... };
+}
+```
+
+## 8. Package Structure
+
+### Standalone Package
+
+```
+session-bank/                          # standalone npm package
+├── package.json                       # @entire-sessions/reader (or similar)
+├── tsconfig.json
+├── src/
+│   ├── index.ts                       # Barrel: SessionBank, types, parser
+│   ├── session-bank.ts                # SessionBank class
+│   ├── git-reader.ts                  # EntireGitReader
+│   ├── parser.ts                      # EntireTranscriptParser
+│   └── types.ts                       # SessionRecord, SessionQuery, etc.
+└── tests/
+    ├── fixtures/                       # Sample JSONL + metadata files
+    │   ├── simple-session/
+    │   │   ├── metadata.json
+    │   │   └── full.jsonl
+    │   └── multi-tool-session/
+    │       ├── metadata.json
+    │       └── full.jsonl
+    ├── parser.test.ts
+    ├── git-reader.test.ts
+    └── session-bank.test.ts
+```
+
+### cognitive-core Additions
+
+```
+src/
+├── learning/
+│   └── trajectory-sources/
+│       ├── entire.ts                  # EntireTrajectorySource (NEW)
+│       └── index.ts                   # Updated barrel
+└── types/
+    └── config.ts                      # SessionBankConfigSchema addition
+```
+
+## 9. Implementation Plan
+
+### Phase 1: Standalone Reader (session-bank package)
+- `EntireGitReader` — git plumbing, branch existence, file reading
+- `EntireTranscriptParser` — JSONL parsing, metadata parsing, chunked transcripts
+- Types (`SessionRecord`, `TranscriptMessage`, `ContentBlock`, etc.)
+- Unit tests with real Entire fixture data
+
+### Phase 2: Session Bank Facade
+- `SessionBank` class — discover, query, get, count
+- Lazy loading (metadata-first, transcript-on-demand)
+- Processing log persistence
+- Cache invalidation via orphan branch HEAD comparison
+
+### Phase 3: cognitive-core Adapter
+- `EntireTrajectorySource` implementing `TrajectorySource`
+- `synthesize()` — SessionRecord → Trajectory conversion
+- ReAct step grouping, outcome inference (summary-based + heuristic)
+- `SessionBankConfigSchema` addition to `AtlasConfig`
+- `Atlas.ingestEntireSessions()` integration
+
+### Phase 4: Polish
+- Commit-linked queries (`getByCommit()` via trailer parsing)
+- `search` filter (full-text across user messages)
+- Task/subagent checkpoint support
+- Error tolerance for corrupt/partial data
+- Integration test against a real Entire-enabled repo
+
+## 10. Design Decisions
+
+### Why a standalone package?
+
+The session bank reads Entire's data format — it doesn't need cognitive-core's Trajectory type, learning pipeline, or memory system. Keeping it standalone means:
+- Entire's data can be consumed by other tools (analytics, dashboards, review UIs)
+- The package has zero dependencies beyond Node.js built-ins
+- Testing is simpler (no cognitive-core setup needed)
+- cognitive-core's `EntireTrajectorySource` adapter is a thin 100-line bridge
+
+### Why `summary.intent` over first user message for task description?
+
+Entire's AI-generated summaries distill multi-turn sessions into coherent task descriptions. The first user message might be "fix this" with no context. The summary's `intent` field is "Fix the authentication token refresh bug in the middleware" — much better for learning.
+
+### Why `summary`-based outcome inference by default?
+
+Entire already runs an LLM to generate session summaries with an `outcome` field. Using this avoids a duplicate LLM call during ingestion. The summary-based strategy examines the outcome text for failure indicators — this is nearly as accurate as a dedicated outcome classifier, at zero additional cost.
+
+### Why checkpoint-indexed, not session-indexed?
+
+Entire's storage is organized by checkpoint ID, not session ID. A single checkpoint can contain multiple concurrent sessions. The session bank follows this structure rather than fighting it — `getByCheckpointId()` returns all sessions in a checkpoint, while `getBySessionId()` searches across checkpoints.
+
+### Why processing log rather than modifying Entire's data?
+
+The session bank never writes to the orphan branch. Processing state is kept in a local file (`.atlas/session-bank/processed.json`). This means:
+- Multiple consumers can independently track their own processing state
+- Entire's data stays immutable and authoritative
+- No risk of corrupting the orphan branch
+
+## 11. Entire Features We Leverage
+
+| Entire Feature | How We Use It |
+|---|---|
+| `summary.intent` | Task description for Trajectory |
+| `summary.outcome` | Outcome inference (success/failure) |
+| `summary.learnings` | Candidate knowledge notes for KnowledgeBank |
+| `summary.friction_points` | Anti-pattern identification for playbooks |
+| `files_touched` | Domain inference, file-level context |
+| `token_usage` | Direct `totalTokens` on Trajectory (no estimation) |
+| `initial_attribution` | Code contribution metrics for meta-learning |
+| `Entire-Checkpoint` trailers | Commit↔session linking |
+| Checkpoint sharding | Efficient git tree enumeration |
+| Transcript chunking | Handle large sessions (>50MB) gracefully |
+
+## 12. Future Extensions
+
+- **Learnings → KnowledgeBank pipeline** — `summary.learnings` maps directly to KnowledgeBank observations; auto-extract without re-analyzing the transcript
+- **Friction → anti-pattern extraction** — `summary.friction_points` can seed `playbook.applicability.antiPatterns`
+- **Attribution-weighted learning** — weight trajectory importance by `agentContribution` score; sessions where the human did most of the work may be less useful for agent learning
+- **Cross-repo federation** — aggregate session banks from multiple repos into a shared learning corpus
+- **Incremental sync** — track orphan branch commit SHA; only re-scan checkpoints added since last sync
+- **Gemini CLI support** — Entire captures Gemini sessions too; parser can be extended to handle Gemini's JSON format alongside Claude's JSONL