@lossless-claude/lcm 0.2.0

package/dist/src/transcript.js

@@ -0,0 +1,51 @@
+import { readFileSync } from "node:fs";
+function extractText(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((b) => {
+            if (b.type === "text" && typeof b.text === "string")
+                return b.text;
+            if (b.type === "tool_result")
+                return extractText(b.content);
+            return "";
+        })
+            .filter(Boolean)
+            .join("\n");
+    }
+    return "";
+}
+export function estimateTokens(text) {
+    return Math.max(1, Math.ceil(text.length / 4));
+}
+export function parseTranscript(transcriptPath) {
+    let raw;
+    try {
+        raw = readFileSync(transcriptPath, "utf-8");
+    }
+    catch {
+        return [];
+    }
+    const messages = [];
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const obj = JSON.parse(trimmed);
+            const role = obj.message?.role;
+            if (!role || !["user", "assistant", "system"].includes(role))
+                continue;
+            const content = extractText(obj.message?.content);
+            if (!content.trim())
+                continue;
+            messages.push({ role, content, tokenCount: estimateTokens(content) });
+        }
+        catch {
+            // skip malformed lines
+        }
+    }
+    return messages;
+}
+//# sourceMappingURL=transcript.js.map

package/dist/src/transcript.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript.js","sourceRoot":"","sources":["../../src/transcript.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAsBvC,SAAS,WAAW,CAAC,OAA0C;IAC7D,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAChD,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,OAAO,OAAO;aACX,GAAG,CAAC,CAAC,CAAe,EAAE,EAAE;YACvB,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;gBAAE,OAAO,CAAC,CAAC,IAAI,CAAC;YACnE,IAAI,CAAC,CAAC,IAAI,KAAK,aAAa;gBAAE,OAAO,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;YAC5D,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;aACD,MAAM,CAAC,OAAO,CAAC;aACf,IAAI,CAAC,IAAI,CAAC,CAAC;IAChB,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,cAAsB;IACpD,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,QAAQ,GAAoB,EAAE,CAAC;IACrC,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,CAAC,OAAO;YAAE,SAAS;QACvB,IAAI,CAAC;YACH,MAAM,GAAG,GAAmB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAChD,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC;YAC/B,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,SAAS;YACvE,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAClD,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE;gBAAE,SAAS;YAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACxE,CAAC;QAAC,MAAM,CAAC;YACP,uBAAuB;QACzB,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/src/types.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Core type definitions for the LCM plugin.
+ *
+ * These types define the contracts between LCM and Claude Code,
+ * abstracting away direct imports from core internals.
+ */
+import type { LcmConfig } from "./db/config.js";
+/**
+ * Minimal LLM completion interface needed by LCM for summarization.
+ * Matches the signature of completeSimple from @mariozechner/pi-ai.
+ */
+export type CompletionContentBlock = {
+    type: string;
+    text?: string;
+    [key: string]: unknown;
+};
+export type CompletionResult = {
+    content: CompletionContentBlock[];
+    [key: string]: unknown;
+};
+export type CompleteFn = (params: {
+    provider?: string;
+    model: string;
+    apiKey?: string;
+    providerApi?: string;
+    authProfileId?: string;
+    agentDir?: string;
+    runtimeConfig?: unknown;
+    messages: Array<{
+        role: string;
+        content: unknown;
+    }>;
+    system?: string;
+    maxTokens: number;
+    temperature?: number;
+    reasoning?: string;
+}) => Promise<CompletionResult>;
+/**
+ * Gateway RPC call interface.
+ */
+export type CallGatewayFn = (params: {
+    method: string;
+    params?: Record<string, unknown>;
+    timeoutMs?: number;
+}) => Promise<unknown>;
+/**
+ * Model resolution function — resolves model aliases and defaults.
+ * When providerHint is supplied, it takes precedence over env/defaults.
+ */
+export type ResolveModelFn = (modelRef?: string, providerHint?: string) => {
+    provider: string;
+    model: string;
+};
+/**
+ * API key resolution function.
+ */
+export type ApiKeyLookupOptions = {
+    profileId?: string;
+    preferredProfile?: string;
+};
+export type GetApiKeyFn = (provider: string, model: string, options?: ApiKeyLookupOptions) => Promise<string | undefined>;
+export type RequireApiKeyFn = (provider: string, model: string, options?: ApiKeyLookupOptions) => Promise<string>;
+/**
+ * Session key utilities.
+ */
+export type ParseAgentSessionKeyFn = (sessionKey: string) => {
+    agentId: string;
+    suffix: string;
+} | null;
+export type IsSubagentSessionKeyFn = (sessionKey: string) => boolean;
+/**
+ * Dependencies injected into the LCM engine at registration time.
+ * These replace all direct imports from Claude Code.
+ */
+export interface LcmDependencies {
+    /** LCM configuration (from env vars + plugin config) */
+    config: LcmConfig;
+    /** LLM completion function for summarization */
+    complete: CompleteFn;
+    /** Gateway RPC call function (for subagent spawning, session ops) */
+    callGateway: CallGatewayFn;
+    /** Resolve model alias to provider/model pair */
+    resolveModel: ResolveModelFn;
+    /** Get API key for a provider/model pair */
+    getApiKey: GetApiKeyFn;
+    /** Require API key (throws if missing) */
+    requireApiKey: RequireApiKeyFn;
+    /** Parse agent session key into components */
+    parseAgentSessionKey: ParseAgentSessionKeyFn;
+    /** Check if a session key is a subagent key */
+    isSubagentSessionKey: IsSubagentSessionKeyFn;
+    /** Normalize an agent ID */
+    normalizeAgentId: (id?: string) => string;
+    /** Build system prompt for subagent sessions */
+    buildSubagentSystemPrompt: (params: {
+        depth: number;
+        maxDepth: number;
+        taskSummary?: string;
+    }) => string;
+    /** Read the latest assistant reply from a session's messages */
+    readLatestAssistantReply: (messages: unknown[]) => string | undefined;
+    /** Sanitize tool use/result pairing in message arrays */
+    /** Resolve the Claude Code agent directory */
+    resolveAgentDir: () => string;
+    /** Resolve runtime session id from an agent session key */
+    resolveSessionIdFromSessionKey: (sessionKey: string) => Promise<string | undefined>;
+    /** Agent lane constant for subagents */
+    agentLaneSubagent: string;
+    /** Logger */
+    log: {
+        info: (msg: string) => void;
+        warn: (msg: string) => void;
+        error: (msg: string) => void;
+        debug: (msg: string) => void;
+    };
+}

package/dist/src/types.js

@@ -0,0 +1,8 @@
+/**
+ * Core type definitions for the LCM plugin.
+ *
+ * These types define the contracts between LCM and Claude Code,
+ * abstracting away direct imports from core internals.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/docs/agent-tools.md

@@ -0,0 +1,187 @@
+# Agent tools
+
+LCM provides four tools for agents to search, inspect, and recall information from compacted conversation history.
+
+## Usage patterns
+
+### Escalation pattern: grep → describe → expand_query
+
+Most recall tasks follow this escalation:
+
+1. **`lcm_grep`** — Find relevant summaries or messages by keyword/regex
+2. **`lcm_describe`** — Inspect a specific summary's full content (cheap, no sub-agent)
+3. **`lcm_expand_query`** — Deep recall: spawn a sub-agent to expand the DAG and answer a focused question
+
+Start with grep. If the snippet is enough, stop. If you need full summary content, use describe. If you need details that were compressed away, use expand_query.
+
+### When to expand
+
+Summaries are lossy by design. The "Expand for details about:" footer at the end of each summary lists what was dropped. Use `lcm_expand_query` when you need:
+
+- Exact commands, error messages, or config values
+- File paths and specific code changes
+- Decision rationale beyond what the summary captured
+- Tool call sequences and their outputs
+- Verbatim quotes or specific data points
+
+`lcm_expand_query` is bounded (~120s, scoped sub-agent) and relatively cheap. Don't ration it.
+
+## Tool reference
+
+### lcm_grep
+
+Search across messages and/or summaries using regex or full-text search.
+
+**Parameters:**
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `pattern` | string | ✅ | — | Search pattern |
+| `mode` | string | | `"regex"` | `"regex"` or `"full_text"` |
+| `scope` | string | | `"both"` | `"messages"`, `"summaries"`, or `"both"` |
+| `conversationId` | number | | current | Specific conversation to search |
+| `allConversations` | boolean | | `false` | Search all conversations |
+| `since` | string | | — | ISO timestamp lower bound |
+| `before` | string | | — | ISO timestamp upper bound |
+| `limit` | number | | 50 | Max results (1–200) |
+
+**Returns:** Array of matches with:
+- `id` — Message or summary ID
+- `type` — `"message"` or `"summary"`
+- `snippet` — Truncated content around the match
+- `conversationId` — Which conversation
+- `createdAt` — Timestamp
+- For summaries: `depth`, `kind`, `summaryId`
+
+**Examples:**
+
+```
+# Full-text search across all conversations
+lcm_grep(pattern: "database migration", mode: "full_text", allConversations: true)
+
+# Regex search in summaries only
+lcm_grep(pattern: "config\\.threshold.*0\\.[0-9]+", scope: "summaries")
+
+# Recent messages containing a specific term
+lcm_grep(pattern: "deployment", since: "2026-02-19T00:00:00Z", scope: "messages")
+```
+
+### lcm_describe
+
+Look up metadata and content for a specific summary or stored file.
+
+**Parameters:**
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `id` | string | ✅ | — | `sum_xxx` for summaries, `file_xxx` for files |
+| `conversationId` | number | | current | Scope to a specific conversation |
+| `allConversations` | boolean | | `false` | Allow cross-conversation lookups |
+
+**Returns for summaries:**
+- Full summary content
+- Metadata: depth, kind, token count, created timestamp
+- Time range (earliestAt, latestAt)
+- Descendant count
+- Parent summary IDs (for condensed summaries)
+- Child summary IDs
+- Source message IDs (for leaf summaries)
+- File IDs referenced in the summary
+
+**Returns for files:**
+- File content (full text)
+- Metadata: fileName, mimeType, byteSize
+- Exploration summary
+- Storage path
+
+**Examples:**
+
+```
+# Inspect a summary from context
+lcm_describe(id: "sum_abc123def456")
+
+# Retrieve a stored large file
+lcm_describe(id: "file_789abc012345")
+```
+
+### lcm_expand_query
+
+Answer a focused question by expanding summaries through the DAG. Spawns a bounded sub-agent that walks parent links down to source material and returns a compact answer.
+
+**Parameters:**
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `prompt` | string | ✅ | — | The question to answer |
+| `query` | string | ✅* | — | Text query to find summaries (if no `summaryIds`) |
+| `summaryIds` | string[] | ✅* | — | Specific summary IDs to expand (if no `query`) |
+| `maxTokens` | number | | 2000 | Answer length cap |
+| `conversationId` | number | | current | Scope to a specific conversation |
+| `allConversations` | boolean | | `false` | Search across all conversations |
+
+*One of `query` or `summaryIds` is required.
+
+**Returns:**
+- `answer` — The focused answer text
+- `citedIds` — Summary IDs that contributed to the answer
+- `expandedSummaryCount` — How many summaries were expanded
+- `totalSourceTokens` — Total tokens read from the DAG
+- `truncated` — Whether the answer was truncated to fit maxTokens
+
+**Examples:**
+
+```
+# Find and expand summaries about a topic
+lcm_expand_query(
+  query: "OAuth authentication fix",
+  prompt: "What was the root cause and what commits fixed it?"
+)
+
+# Expand specific summaries you already have
+lcm_expand_query(
+  summaryIds: ["sum_abc123", "sum_def456"],
+  prompt: "What were the exact file changes?"
+)
+
+# Cross-conversation search
+lcm_expand_query(
+  query: "deployment procedure",
+  prompt: "What's the current deployment process?",
+  allConversations: true
+)
+```
+
+### lcm_expand
+
+Low-level DAG expansion tool. **Only available to sub-agents** spawned by `lcm_expand_query`. Main agents should always use `lcm_expand_query` instead.
+
+This tool is what the expansion sub-agent uses internally to walk the summary DAG, read source messages, and build its answer.
+
+## Tips for agent developers
+
+### Configuring agent prompts
+
+Add instructions to your agent's system prompt so it knows when to use LCM tools:
+
+```markdown
+## Memory & Context
+
+Use LCM tools for recall:
+1. `lcm_grep` — Search all conversations by keyword/regex
+2. `lcm_describe` — Inspect a specific summary (cheap, no sub-agent)
+3. `lcm_expand_query` — Deep recall with sub-agent expansion
+
+When summaries in context have an "Expand for details about:" footer
+listing something you need, use `lcm_expand_query` to get the full detail.
+```
+
+### Conversation scoping
+
+By default, tools operate on the current conversation. Use `allConversations: true` to search across all of them (all agents, all sessions). Use `conversationId` to target a specific conversation you already know about (from previous grep results).
+
+### Performance considerations
+
+- `lcm_grep` and `lcm_describe` are fast (direct database queries)
+- `lcm_expand_query` spawns a sub-agent and takes ~30–120 seconds
+- The sub-agent has a 120-second timeout with cleanup guarantees
+- Token caps (`LCM_MAX_EXPAND_TOKENS`) prevent runaway expansion

package/docs/architecture.md

@@ -0,0 +1,224 @@
+# Architecture
+
+This document describes how lossless-claude works internally — the data model, compaction lifecycle, context assembly, and expansion system.
+
+## Data model
+
+### Conversations and messages
+
+Every Claude Code session maps to a **conversation**. The first time a session ingests a message, LCM creates a conversation record keyed by the runtime session ID.
+
+Messages are stored with:
+- **seq** — Monotonically increasing sequence number within the conversation
+- **role** — `user`, `assistant`, `system`, or `tool`
+- **content** — Plain text extraction of the message
+- **tokenCount** — Estimated token count (~4 chars/token)
+- **createdAt** — Insertion timestamp
+
+Each message also has **message_parts** — structured content blocks that preserve the original shape (text blocks, tool calls, tool results, reasoning, file content, etc.). This allows the assembler to reconstruct rich content when building model context, not just flat text.
+
+### The summary DAG
+
+Summaries form a directed acyclic graph with two node types:
+
+**Leaf summaries** (depth 0, kind `"leaf"`):
+- Created from a chunk of raw messages
+- Linked to source messages via `summary_messages`
+- Contain a narrative summary with timestamps
+- Typically 800–1200 tokens
+
+**Condensed summaries** (depth 1+, kind `"condensed"`):
+- Created from a chunk of summaries at the same depth
+- Linked to parent summaries via `summary_parents`
+- Each depth tier uses a progressively more abstract prompt
+- Typically 1500–2000 tokens
+
+Every summary carries:
+- **summaryId** — `sum_` + 16 hex chars (SHA-256 of content + timestamp)
+- **conversationId** — Which conversation it belongs to
+- **depth** — Position in the hierarchy (0 = leaf)
+- **earliestAt / latestAt** — Time range of source material
+- **descendantCount** — Total number of ancestor summaries (transitive)
+- **fileIds** — References to large files mentioned in the source
+- **tokenCount** — Estimated tokens
+
+### Context items
+
+The **context_items** table maintains the ordered list of what the model sees for each conversation. Each entry is either a message reference or a summary reference, identified by ordinal.
+
+When compaction creates a summary from a range of messages (or summaries), the source items are replaced by a single summary item. This keeps the context list compact while preserving ordering.
+
+## Compaction lifecycle
+
+### Ingestion
+
+When Claude Code processes a turn, it calls the context engine's lifecycle hooks:
+
+1. **bootstrap** — On session start, reconciles the JSONL session file with the LCM database. Imports any messages that exist in the file but not in LCM (crash recovery).
+2. **ingest** / **ingestBatch** — Persists new messages to the database and appends them to context_items.
+3. **afterTurn** — After the model responds, ingests new messages, then evaluates whether compaction should run.
+
+### Leaf compaction
+
+The **leaf pass** converts raw messages into leaf summaries:
+
+1. Identify the oldest contiguous chunk of raw messages outside the **fresh tail** (protected recent messages).
+2. Cap the chunk at `leafChunkTokens` (default 20k tokens).
+3. Concatenate message content with timestamps.
+4. Resolve the most recent prior summary for continuity (passed as `previous_context` so the LLM avoids repeating known information).
+5. Send to the LLM with the leaf prompt.
+6. Normalize provider response blocks (Anthropic/OpenAI text, output_text, and nested content/summary shapes) into plain text.
+7. If normalization is empty, log provider/model/block-type diagnostics and fall back to deterministic truncation.
+8. If the summary is larger than the input (LLM failure), retry with the aggressive prompt. If still too large, fall back to deterministic truncation.
+9. Persist the summary, link to source messages, and replace the message range in context_items.
+
+### Condensation
+
+The **condensed pass** merges summaries at the same depth into a higher-level summary:
+
+1. Find the shallowest depth with enough contiguous same-depth summaries (≥ `leafMinFanout` for d0, ≥ `condensedMinFanout` for d1+).
+2. Concatenate their content with time range headers.
+3. Send to the LLM with the depth-appropriate prompt (d1, d2, or d3+).
+4. Apply the same escalation strategy (normal → aggressive → truncation fallback).
+5. Persist with depth = targetDepth + 1, link to parent summaries, replace the range in context_items.
+
+### Compaction modes
+
+**Incremental (after each turn):**
+- Checks if raw tokens outside the fresh tail exceed `leafChunkTokens`
+- If so, runs one leaf pass
+- If `incrementalMaxDepth != 0`, follows with condensation passes up to that depth (`-1` for unlimited)
+- Best-effort: failures don't break the conversation
+
+**Full sweep (manual `/compact` or overflow):**
+- Phase 1: Repeatedly runs leaf passes until no more eligible chunks
+- Phase 2: Repeatedly runs condensation passes starting from the shallowest eligible depth
+- Each pass checks for progress; stops if no tokens were saved
+
+**Budget-targeted (`compactUntilUnder`):**
+- Runs up to `maxRounds` (default 10) of full sweeps
+- Stops when context is under the target token count
+- Used by the overflow recovery path
+
+### Three-level escalation
+
+Every summarization attempt follows this escalation:
+
+1. **Normal** — Standard prompt, temperature 0.2
+2. **Aggressive** — Tighter prompt requesting only durable facts, temperature 0.1, lower target tokens
+3. **Fallback** — Deterministic truncation to ~512 tokens with `[Truncated for context management]` marker
+
+This ensures compaction always makes progress, even if the LLM produces poor output.
+
+## Context assembly
+
+The assembler runs before each model turn and builds the message array:
+
+```
+[summary₁, summary₂, ..., summaryₙ, message₁, message₂, ..., messageₘ]
+ ├── budget-constrained ──┤  ├──── fresh tail (always included) ────┤
+```
+
+### Steps
+
+1. Fetch all context_items ordered by ordinal.
+2. Resolve each item — summaries become user messages with XML wrappers; messages are reconstructed from parts.
+3. Split into evictable prefix and protected fresh tail (last `freshTailCount` raw messages).
+4. Compute fresh tail token cost (always included, even if over budget).
+5. Fill remaining budget from the evictable set, keeping newest items and dropping oldest.
+6. Normalize assistant content to array blocks (Anthropic API compatibility).
+7. Sanitize tool-use/result pairing (ensures every tool_result has a matching tool_use).
+
+### XML summary format
+
+Summaries are presented to the model as user messages wrapped in XML:
+
+```xml
+<summary id="sum_abc123" kind="leaf" depth="0" descendant_count="0"
+         earliest_at="2026-02-17T07:37:00" latest_at="2026-02-17T08:23:00">
+  <content>
+    ...summary text with timestamps...
+
+    Expand for details about: exact error messages, full config diff, intermediate debugging steps
+  </content>
+</summary>
+```
+
+Condensed summaries also include parent references:
+
+```xml
+<summary id="sum_def456" kind="condensed" depth="1" descendant_count="8" ...>
+  <parents>
+    <summary_ref id="sum_aaa111" />
+    <summary_ref id="sum_bbb222" />
+  </parents>
+  <content>...</content>
+</summary>
+```
+
+The XML attributes give the model enough metadata to reason about summary age, scope, and how to drill deeper. The `<parents>` section enables targeted expansion of specific source summaries.
+
+## Expansion system
+
+When summaries are too compressed for a task, agents use `lcm_expand_query` to recover detail.
+
+### How it works
+
+1. Agent calls `lcm_expand_query` with a `prompt` and either `summaryIds` or a `query`.
+2. If `query` is provided, `lcm_grep` finds matching summaries first.
+3. A **delegation grant** is created, scoping the sub-agent to the relevant conversation(s) with a token cap.
+4. A sub-agent session is spawned with the expansion task.
+5. The sub-agent walks the DAG: it can read summary content, follow parent links, access source messages, and inspect stored files.
+6. The sub-agent returns a focused answer (default ≤ 2000 tokens) with cited summary IDs.
+7. The grant is revoked and the sub-agent session is cleaned up.
+
+### Security model
+
+Expansion uses a delegation grant system:
+
+- **Grants** are created at spawn time, scoped to specific conversation IDs
+- **Token caps** limit how much content the sub-agent can access
+- **TTL** ensures grants expire even if cleanup fails
+- **Revocation** happens on completion, cancellation, or sweep
+
+The sub-agent only gets `lcm_expand` (the low-level tool), not `lcm_expand_query` — preventing recursive sub-agent spawning.
+
+## Large file handling
+
+Files embedded in user messages (typically via `<file>` blocks from tool output) are checked at ingestion:
+
+1. Parse file blocks from message content.
+2. For each block exceeding `largeFileTokenThreshold` (default 25k tokens):
+   - Generate a unique file ID (`file_` prefix)
+   - Store the content to `~/.claude/lcm-files/<conversation_id>/<file_id>.<ext>`
+   - Generate a ~200 token exploration summary (structural analysis, key sections, etc.)
+   - Insert a `large_files` record with metadata
+   - Replace the file block in the message with a compact reference
+3. The `lcm_describe` tool can retrieve full file content by ID.
+
+This prevents a single large file paste from consuming the entire context window while keeping the content accessible.
+
+## Session reconciliation
+
+LCM handles crash recovery through **bootstrap reconciliation**:
+
+1. On session start, read the JSONL session file (Claude Code's ground truth).
+2. Compare against the LCM database.
+3. Find the most recent message that exists in both (the "anchor").
+4. Import any messages after the anchor that are in JSONL but not in LCM.
+
+This handles the case where Claude Code wrote messages to the session file but crashed before LCM could persist them.
+
+## Operation serialization
+
+All mutating operations (ingest, compact) are serialized per-session using a promise queue. This prevents races between concurrent afterTurn/compact calls for the same conversation without blocking operations on different conversations.
+
+## Authentication
+
+LCM needs to call an LLM for summarization. It resolves credentials through a three-tier cascade:
+
+1. **Auth profiles** — Claude Code's OAuth/token/API-key profile system (`auth-profiles.json`), checked in priority order
+2. **Environment variables** — Standard provider env vars (`ANTHROPIC_API_KEY`, etc.)
+3. **Custom provider key** — From models config (e.g., `models.json`)
+
+For OAuth providers (e.g., Anthropic via Claude Max), LCM handles token refresh and credential persistence automatically.