claude-mem/.plan/endless-mode-rebase.md

# Plan: Endless Mode Re-implementation on Current Main

## Context

Endless mode was implemented on `beta/endless-mode` branch (diverged at v7.0.0). Main is now at v10.4.1 — **902 commits ahead**. Rebasing is impractical. This plan re-implements endless mode on top of current main, using the old branch as a reference for concepts only.

### What Endless Mode Does

When enabled, after each tool execution:
1. The PostToolUse hook waits for the SDK agent to process the observation
2. The processed observation (title, narrative, facts) is injected back into Claude's context via `additionalContext`
3. Large tool inputs are cleared from the transcript to save tokens
4. Net effect: Claude sees compressed observations instead of raw tool data → extends effective context window

### Key Problem from Previous Attempt

The save-hook blocked for 60-90s waiting for SDK processing, making sessions unusably slow. The fundamental tension: AI-processed observations require time, but hooks have a 120s hard limit.

### Branch Strategy

Create a new branch `feature/endless-mode-v2` from current main. Do NOT touch the old `beta/endless-mode` branch.

---

## Phase 0: Documentation Discovery (Reference Gathering)

### 0.1 — Read old branch implementation for reference patterns
- `git show beta/endless-mode:src/hooks/save-hook.ts` — synchronous wait pattern
- `git show beta/endless-mode:src/hooks/context-injection.ts` — observation formatting
- `git show beta/endless-mode:src/hooks/pre-tool-use-hook.ts` — tool_use_id tracking
- `git show beta/endless-mode:src/services/worker/SessionManager.ts` — `waitForNextObservation()`
- `git show beta/endless-mode:docs/context/state-of-endless.md` — architecture doc

### 0.2 — Read current main integration points
- `src/hooks/hook-response.ts:1-15` — current hook response format
- `src/services/worker/SessionManager.ts:21-100` — current session management
- `src/services/worker/SDKAgent.ts:43-150` — current SDK agent flow, event emission
- `src/services/worker/http/routes/SessionRoutes.ts:498-573` — current observation endpoint
- `src/services/sqlite/SessionStore.ts:1503-1560` — current storeObservation
- `src/shared/SettingsDefaultsManager.ts:77-133` — current settings defaults

### 0.3 — Identify Claude Code hook contract
- `plugin/plugin.json` — current hook configuration (which hooks exist, their types)
- Check if `PreToolUse` hook type is available in Claude Code plugin spec
- Check `additionalContext` field availability in hook response contract

### Deliverable
List of exact APIs, file locations, and patterns available for each integration point. Anti-pattern list of methods that existed on the old branch but don't exist on current main.

---

## Phase 1: Database Schema — Add `tool_use_id` Column

### What to implement
- Add migration 20 to `src/services/sqlite/SessionStore.ts` (after migration 19 at ~line 53)
- Add nullable `tool_use_id TEXT` column to observations table
- Add index: `CREATE INDEX idx_observations_tool_use_id ON observations(tool_use_id)`
- Add `getObservationsByToolUseId(toolUseId: string)` method to SessionStore
- Update `storeObservation()` signature to accept optional `tool_use_id?: string`

### Files to modify
- `src/services/sqlite/SessionStore.ts` — migration + store method
- `src/services/sqlite/observations/types.ts` — add tool_use_id to StoreObservationResult
- `src/types/transcript.ts` — verify ToolResultContent.tool_use_id matches Claude's format

### Verification
- `npm run build` succeeds
- Worker starts without errors
- New column appears in observations table: `sqlite3 ~/.claude-mem/claude-mem.db ".schema observations"`

### Anti-patterns
- Do NOT make tool_use_id NOT NULL — old observations won't have it
- Do NOT modify existing migrations — only append new ones

---

## Phase 2: Settings — Add Endless Mode Configuration

### What to implement
- Add to `SettingsDefaultsManager.ts` DEFAULTS (~line 77):
  - `CLAUDE_MEM_ENDLESS_MODE`: `'false'` (disabled by default)
  - `CLAUDE_MEM_ENDLESS_WAIT_TIMEOUT_MS`: `'90000'` (90 second timeout)
- Add helper method `isEndlessModeEnabled(): boolean`

### Files to modify
- `src/shared/SettingsDefaultsManager.ts`

### Verification
- Settings load correctly with defaults
- Can override via `~/.claude-mem/settings.json`
- Can override via environment variable

### Anti-patterns
- Do NOT add UI for toggling yet — settings.json is sufficient for beta

---

## Phase 3: Worker-Side — Event-Based Observation Completion Signaling

### What to implement
- In `SessionManager.ts`: Add `waitForNextObservation(sessionDbId, toolUseId, timeoutMs)` method
  - Uses existing `sessionQueues` EventEmitter infrastructure
  - Waits for `observation_saved` event matching toolUseId
  - Returns the observation or null on timeout
- In `SDKAgent.ts`: After `storeObservation()` call, emit `observation_saved` event with observation data and toolUseId
- In `SessionRoutes.ts`:
  - Accept `tool_use_id` in observation POST body
  - Accept `wait_until_observation_is_saved=true` query parameter
  - When waiting: call `SessionManager.waitForNextObservation()` before responding
  - When not waiting (default): existing fire-and-forget behavior

### Files to modify
- `src/services/worker/SessionManager.ts`
- `src/services/worker/SDKAgent.ts`
- `src/services/worker/http/routes/SessionRoutes.ts`

### Verification
- Worker builds and starts
- Default (non-endless) observation flow is unaffected
- Can POST with `wait_until_observation_is_saved=true` and get observation back in response

### Anti-patterns
- Do NOT add SSE/streaming — simple HTTP request/response with await is sufficient
- Do NOT modify the existing fire-and-forget path — only add the new waiting path
- Do NOT add a pre-tool-use endpoint yet — tool_use_id comes from the hook, not a separate call

---

## Phase 4: Hook-Side — PostToolUse Synchronous Injection

### What to implement
- Modify the PostToolUse hook (save-hook) to:
  1. Check if endless mode is enabled via settings
  2. Extract `tool_use_id` from the hook input (Claude Code provides this)
  3. If endless mode ON: POST observation with `wait_until_observation_is_saved=true` and `tool_use_id`
  4. Receive processed observation in HTTP response
  5. Format observation as markdown (copy pattern from old `context-injection.ts`)
  6. Return hook response with `additionalContext` field containing formatted observation
  7. If endless mode OFF: existing fire-and-forget behavior (unchanged)
- Create `src/hooks/observation-formatter.ts` utility for markdown formatting

### Files to modify
- `src/hooks/save-hook.ts` (or whatever the current PostToolUse hook source is)
- `src/hooks/observation-formatter.ts` (NEW)
- `src/hooks/hook-response.ts` — add `additionalContext` support to response type

### Verification
- With endless mode OFF: behavior identical to current
- With endless mode ON: observations appear in Claude's context after tool use
- Hook respects 120s Claude Code timeout (90s observation wait + buffer)

### Anti-patterns
- Do NOT add transcript clearing in this phase — that's a separate optimization
- Do NOT block indefinitely — always use timeout with graceful fallback
- Do NOT swallow errors in the wait path — if it fails, fall back to fire-and-forget

---

## Phase 5: Build, Test, and Validate

### What to implement
- `npm run build-and-sync` — full build
- Manual testing:
  1. Enable endless mode in settings.json
  2. Start a Claude Code session
  3. Execute tool uses and verify observations appear in context
  4. Verify non-endless mode is unaffected
- Add basic unit tests in `tests/endless-mode/`

### Verification checklist
- [ ] `npm run build` succeeds with zero errors
- [ ] Worker starts without errors
- [ ] Non-endless mode behavior unchanged (regression check)
- [ ] With endless mode ON: observation appears in Claude's context after tool use
- [ ] Timeout fallback works (kill worker mid-processing, verify graceful degradation)
- [ ] Settings toggle works (on/off without restart)
- [ ] Database migration applies cleanly on fresh and existing databases

### Anti-patterns
- Do NOT ship to npm/release yet — this is beta
- Do NOT add documentation updates yet — feature must be validated first
- Do NOT add telemetry or analytics in initial implementation

---

## Phase 6: Transcript Clearing Optimization (Optional, After Validation)

### What to implement
- After observation injection is working, add transcript clearing:
  - After successful observation injection, clear the large `tool_input` from Claude's transcript JSONL
  - This is the actual token savings mechanism — compressed observation replaces raw tool data
- Read from old branch: `git show beta/endless-mode:src/hooks/context-injection.ts` for `clearToolInputInTranscript()`

### Files to modify
- `src/hooks/save-hook.ts` — add transcript clearing after successful injection
- `src/hooks/transcript-clearer.ts` (NEW) — utility for JSONL manipulation

### Verification
- Token count decreases after observation injection
- Transcript JSONL remains valid after clearing
- Claude Code doesn't break when transcript entries are modified

### Anti-patterns
- Do NOT clear transcript if observation injection failed — leave raw data intact
- Do NOT modify transcript entries other than the current tool use
- Do NOT implement until Phase 5 validation is complete

---

## Decisions Needed from User

1. **Branch name**: `feature/endless-mode-v2` (proposed) — acceptable?
2. **Scope**: Phases 1-5 are core. Phase 6 is optional. Should Phase 6 be included?
3. **Pre-tool-use hook**: The old branch had a separate PreToolUse hook to send tool_use_id before execution. The PostToolUse hook already receives tool_use_id from Claude Code. Do we need PreToolUse, or is PostToolUse sufficient?