Vendor-neutral conversation index: read Codex (then Gemini) sessions into cldctrl search

[RyanSeanPhillips]

Summary

Make cldctrl's conversation memory/search vendor-neutral by indexing other agents' sessions (starting with OpenAI Codex), so search_conversations — and the dashboard's recent/per-project views — span Claude and Codex (later Gemini). Because the search tool is exposed over the cldctrl MCP, this also gives the reverse: a Codex or Claude session searches one unified cross-vendor history.

This is the differentiation that first parties structurally won't build (Anthropic won't index Codex; OpenAI won't index Claude). Today cldctrl's "vendor-neutral" is only ~1 layer deep (terminals + filesystem project discovery); the brain (search/sessions/stats) reads only ~/.claude.

Codex data layout (verified on a real machine, June 2026)

• Sessions: ~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<uuid>.jsonl (organized by DATE, not project).
• Each rollout is JSONL of events. Useful lines:
  • {"type":"session_meta","payload":{"id","timestamp","cwd": "<PROJECT PATH>"}} → project association comes from cwd.
  • {"type":"event_msg","payload":{"type":"user_message","message":"…"}} and …"type":"agent_message","message":"…" → clean conversation text for indexing.
  • response_item (role/content) and function_call items → tool names + touched files (deeper extraction, optional).
• ~/.codex/session_index.jsonl = {id, thread_name, updated_at} → human titles + a fast index (avoids parsing every rollout).
• Distilled memory/state in SQLite (memories_*.sqlite, state_*.sqlite) — optional later source.
• Gemini CLI would be analogous (~/.gemini, GEMINI.md) — not installed on this machine yet.

Design

1. Adapter interface. Define a small SessionSource abstraction: listSessions(), readTranscript(id), projectOf(session), title(session), usage(session). Implement ClaudeSource (refactor current logic) + CodexSource.
2. Index. Extend core/conversation-search.ts to ingest from all sources, each result tagged vendor. Cache by (mtime,size) per file as today; use session_index.jsonl to skip unchanged Codex rollouts cheaply.
3. Surface. SearchResult gains vendor; dashboard shows a small per-vendor chip; resume/open routes to the right CLI (cockpit already vendor-aware).
4. Reverse (mostly free). search_conversations is already an MCP tool registered in Codex's config.toml, so a cross-vendor index immediately makes unified search reachable from Codex sessions too.

Scope / phases

1. CodexSource + search indexing (proof) — rollouts → unified search_conversations. Highest-leverage first slice.
2. Per-project session list + recent-conversations include Codex (dashboard).
3. Codex usage → Stats tab (needs mapping Codex token accounting; separate from Claude's usage fields).
4. Gemini source when present.
5. (Optional) read Codex's memories_*.sqlite as an extra recall source.

Non-goals / risks

• Not trying to unify the agents' native memories into one store — just make cldctrl's index span them.
• Codex rollout schema is owned by OpenAI and may change; keep the adapter defensive (tolerate unknown event types).

Relates to the strategic reframe (vendor-neutral brain = the moat) and #10 (cross-project coordination, which becomes far more useful when the brain spans vendors).

[RyanSeanPhillips]

Codex's own review of this plan (via consult_agent, read-only, on this machine) — corrections to bake into the adapter:

Format corrections

• session_meta.payload has more than id/timestamp/cwd: also originator, cli_version, source (exec|vscode), model_provider, base_instructions, git{}.
• Prefer turn_context.cwd / turn_context.workspace_roots over session_meta.cwd for project association — turn_context is per-turn/per-resume and also carries model, sandbox_policy, approval_policy, timezone. Normalize Windows extended paths (\\?\C:\…); use git root when available.
• Transcript: index event_msg.user_message + event_msg.agent_message first. response_item records exist too (message role user/assistant/developer; function_call {name, arguments, call_id}; function_call_output; reasoning with encrypted_content — do not index that). Don't blindly index response_item.message (it repeats user/developer context → dedupe).
• session_index.jsonl is STALE / not authoritative on this install — use only as a legacy title hint.
• The real catalog is state_5.sqlite → threads table: id, rollout_path, cwd, title, created_at_ms, updated_at_ms, source, model_provider, model, tokens_used, git_branch, preview, first_user_message, archived. Best source for listing/titles/cwd (still internal/unsupported).

Usage (Stats tab CAN work for Codex) — there's a token_count event:
event_msg.payload.type == "token_count", info.total_token_usage + info.last_token_usage = {input_tokens, cached_input_tokens, output_tokens, reasoning_output_tokens, total_tokens}, plus info.model_context_window and rate_limits. Map: cached_input_tokens ≈ Claude cache_read; reasoning_output_tokens is separate (chartable). Group by turn_id (task_started/turn_context/task_complete); last_token_usage is one model call (sum across the turn), or delta the cumulative total_token_usage.

Memory SQLite — memories_1.sqlite.stage1_outputs is EMPTY here; no stable public contract. Index rollouts as source of truth; treat state_*.sqlite as a best-effort metadata accelerator only. (goals_1.sqlite.thread_goals exists too.)

Resumes/dedupe — resumes APPEND to the same rollout file, so one file can hold multiple task_started/turn_context/user_message/token_count events. One JSONL ≠ one turn. Canonical identity = session_meta.payload.id (also in the filename); dedupe by id + normalized rollout_path; incremental-index by line offset/timestamp; turn via turn_context.turn_id.

Adapter shape Codex recommends: listSessions() prefer state_*.sqlite.threads (validate rollout_path exists) + merge a filesystem scan for anything missing; readTranscript() JSONL line-by-line, tolerate unknown event types, parse function_call.arguments as JSON when possible; usage() parse token_count. Treat all Codex storage as an internal schema-versioned cache, not an API — build defensively.

[RyanSeanPhillips]

Phase 1 shipped — CodexSource + unified cross-vendor search (d7b0e22)

search_conversations and the dashboard search now span Claude + OpenAI Codex in one index.

What landed (core/conversation-search.ts):

• CodexSource reads ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl into the same per-session index, each entry tagged vendor.
• Transcript text from event_msg user/agent_message; "what was done" signal from function_call (name + file path) and mcp_tool_call_end (tool); project from session_meta.payload.cwd (fallback turn_context.cwd / workspace_roots[0]).
• SearchResult gained vendor; index version 1→2 (v1 caches ignored, one re-parse).

Codex's own corrections (consulted twice — it read its real files): tolerate multiple session_meta lines (first is canonical); use lastTs = max timestamp for recency (the date-dir is creation time, and resume appends to the same file with later timestamps); skip base_instructions + duplicate response_item.message (dev/env noise); read cap raised to 12MB (a resumed rollout can hit ~6MB). Resume CLI for later phases: codex exec resume <id> "prompt" (non-interactive) / codex resume <id> (interactive).

Surfacing: MCP search_conversations is now vendor-neutral (results carry vendor, per-vendor resume hint). Dashboard shows a CODEX chip and guards the Claude-only resume paths (search rows show "found in Codex"; the cockpit Add-picker filters out Codex) since cockpit Codex-resume is a later phase.

Verified e2e: 16 Codex + 18 Claude hits across queries with correct project resolution (cwd → known project name); vendor chip + guards render, no console errors.

Remaining #11 slices: (2) Codex in per-project session lists + recent-conversations; resume Codex-in-cockpit (wire codex exec resume); (3) Codex usage → Stats; (4) Gemini source; (5) optional memories_*.sqlite.

[RyanSeanPhillips]

Codex verified the shipped implementation (and found one bug — fixed)

Ran a second consult_agent pass asking Codex to verify the shipped code against its own real files. It read conversation-search.ts and spot-checked ~/.codex/sessions:

Confirmed correct against real data:

• Enumeration: the 4-level YYYY/MM/DD walk found all 47 rollouts (matched a recursive search); filename UUIDs matched the first session_meta.payload.id in every file.
• Field paths: event_msg.payload.message (string), response_item.payload.type==="function_call" with payload.name + payload.arguments as a JSON string (171/171), event_msg.payload.type==="mcp_tool_call_end" with payload.invocation.tool (4/4 — and 0/4 had invocation.name, so .tool is the right path).
• session_meta.payload.id / payload.cwd resolved correctly; 47 unique session ids, no filename↔metadata mismatches.

Bug it found (now fixed, 8191125→ next commit): lastTs only covered lines parsed before the 40k doc cap, so recency was stale for long sessions (cited a file: true last activity 22:34, parsed lastTs stopped 22:26). Fixed to max(parsed ts, file mtime); index v2→v3 to recompute caches.

Deferred (shared with Claude): the 40k-char doc cap fills from the file start, so very long rollouts only index their opening — later turns aren't searchable. Right fix is semantic/FTS (the vector-search roadmap item), not a bigger linear cap. Tracking as a #11 refinement.

[RyanSeanPhillips]

Closing as done — phases 1–4 shipped end-to-end (verified against the current tree):

• Phase 1 — CodexSource + unified index: core/conversation-search.ts reads ~/.codex/sessions/**/rollout-*.jsonl (walkCodexSessionFiles/extractCodexDoc), folds Claude + Codex into one index, every result tagged vendor. Feeds search_conversations and the Tier-1 vector index.
• Phase 2 — sidebar/per-project lists: serve.ts merges Codex (vendor:'codex') and Antigravity (vendor:'antigravity') sessions into the unified list; web/views.ts renders per-vendor chips (⬡ Codex / ✦ Antigravity) and resume routes per vendor (codex resume, agy --conversation <id>).
• Phase 3 — Codex usage in Stats: core/codex-stats.ts + core/stats.ts add tokensByVendor and codexRateLimit; web/stats.ts renders the tokens-by-vendor card + Codex rate-limit chip.
• Phase 4 — Gemini source: substituted by Google Antigravity (agy) as anticipated in the issue — core/antigravity-sessions.ts reads its SQLite conversations via built-in node:sqlite. No standalone Gemini-CLI reader (that CLI is dead).

Only the optional note-5 (reading Codex memories_*.sqlite as an extra recall source) is not implemented — spinning that out is easy later if wanted, but it was explicitly optional.