Codex History Ingest

# Codex Data Format — Detailed Reference

This reference describes practical, observed structures for Codex local history ingestion.

## Root Layout

`~/.codex/` usually contains:

- `sessions/YYYY/MM/DD/rollout-*.jsonl` — primary structured session logs
- `archived_sessions/` — archived rollouts
- `session_index.jsonl` — session id/name/update index
- `history.jsonl` — transcript history (depends on config)
- `config.toml` — history persistence controls

## Session Index

`~/.codex/session_index.jsonl` entries are one JSON object per line, commonly:

```json
{"id":"<thread-id>","thread_name":"<title>","updated_at":"<timestamp>"}
```

Use this as the inventory backbone for append/full mode deltas.

## Rollout JSONL

`rollout-*.jsonl` files are event streams with envelope fields:

```json
{
  "timestamp": "2026-04-12T09:40:02.337Z",
  "type": "session_meta|turn_context|event_msg|response_item",
  "payload": { "...": "..." }
}
```

Common `type` values:

- `session_meta` — run metadata (id, cwd, model/provider, etc.)
- `turn_context` — turn-scoped context envelope
- `event_msg` — runtime events (task lifecycle, token/accounting, tool-call markers)
- `response_item` — model response items (messages, tool calls, reasoning blocks)

### Typical payload subtypes

Observed examples include:

- `event_msg.payload.type`: `task_started`, `user_message`, `agent_message`, `mcp_tool_call_end`, `exec_command_end`, `token_count`
- `response_item.payload.type`: `message`, `function_call`, `function_call_output`, `reasoning`

## Extraction Strategy

### Keep

- User intent from user-message records
- Assistant conclusions/decisions from assistant message records
- High-signal tool outputs that encode reusable knowledge

### Skip

- Pure telemetry (`token_count`, low-level plumbing events)
- Internal reasoning traces unless user explicitly asks to retain them
- Verbose execution dumps with no durable insight

## Privacy Notes

Rollouts can contain sensitive data:

- Injected instruction layers
- Tool inputs/outputs
- Potential secrets in command output

Always redact secrets and summarize instead of copying raw transcript content.

## Config Interaction

`~/.codex/config.toml` keys that affect ingestion completeness:

- `history.persistence = "save-all" | "none"`
- `history.max_bytes = <int>` (truncation/compaction cap)

`codex exec --ephemeral` runs may not persist rollout files.


---
name: codex-history-ingest
description: >
  Ingest Codex CLI conversation history into the Obsidian wiki. Use this skill when the user wants to mine
  their past Codex sessions for knowledge, import their ~/.codex folder, extract insights from previous coding
  sessions, or says things like "process my Codex history", "add my Codex conversations to the wiki", or
  "what have I discussed in Codex before". Also triggers when the user mentions .codex sessions, rollout files,
  session_index.jsonl, or Codex transcript logs.
---

# Codex History Ingest — Conversation Mining

You are extracting knowledge from the user's past Codex sessions and distilling it into the Obsidian wiki. Session logs are rich but noisy: focus on durable knowledge, not operational telemetry.

This skill can be invoked directly or via the `wiki-history-ingest` router (`/wiki-history-ingest codex`).

## Before You Start

1. **Resolve config** — follow the Config Resolution Protocol in `llm-wiki/SKILL.md` (walk up CWD for `.env` → `~/.obsidian-wiki/config` → prompt setup). This gives `OBSIDIAN_VAULT_PATH` and `CODEX_HISTORY_PATH` (defaults to `~/.codex`)
2. Read `.manifest.json` at the vault root to check what has already been ingested
3. Read `index.md` at the vault root to understand what the wiki already contains

## Ingest Modes

### Append Mode (default)

Check `.manifest.json` for each source file. Only process:

- Files not in the manifest (new session rollouts, new index files)
- Files whose modification time is newer than `ingested_at` in the manifest

Use this mode for regular syncs.

#