Codex¶
Codex stores a prompt-recall log, JSONL session transcripts, rollout
summaries, and optional SQLite state. Normal search reads the prompt-recall
log. Targeted search can resolve a history record’s session UUID to one
verified rollout; --exhaustive also projects prompts from every eligible
session transcript. Metadata caches remain inventory or sample-only. The state
database is searchable only under explicit conversations and all scopes,
not through targeted prompt routing.
Base path: ~/.codex (env override: CODEX_HOME).
SQLite path: CODEX_SQLITE_HOME, then sqlite_home from
config.toml, then CODEX_HOME.
observed_version: github.com/openai/codex@3fb81667 (2026-06-21).
Stores¶
Default-search coverage marks eligibility, not an unconditional read.
Fast prompt effort opens only prompt-history roles; exhaustive effort and
broad scopes may add searchable chat stores. Catalog-only stores remain
outside search, and private stores are not enumerated. Some catalog stores
have safe sample parsers for inspect_record_sample.
- Role:
prompt_history- Format:
jsonl- Coverage:
default_search- Adapter:
codex.history_json.v1codex.history_jsonl.v1
- Role:
primary_chat- Format:
jsonl- Coverage:
default_search- Adapter:
codex.sessions_jsonl.v1codex.sessions_legacy_json.v1
- Role:
app_state- Format:
jsonl- Coverage:
inspectable- Adapter:
codex.session_index_jsonl.v1
- Role:
app_state- Format:
sqlite- Coverage:
inspectable- Adapter:
codex.state_sqlite.v1
- Role:
app_state- Format:
sqlite- Coverage:
catalog_only- Adapter:
codex.logs_sqlite.v1
- Role:
persistent_memory- Format:
sqlite- Coverage:
inspectable- Adapter:
codex.memories_sqlite.v1
- Role:
plan- Format:
sqlite- Coverage:
inspectable- Adapter:
codex.goals_sqlite.v1
- Role:
app_state- Format:
json_object- Coverage:
catalog_only- Adapter:
codex.external_imports_json.v1
- Role:
instruction- Format:
text- Coverage:
inspectable- Adapter:
codex.instructions_text.v1
- Role:
persistent_memory- Format:
md_frontmatter- Coverage:
inspectable- Adapter:
codex.memories_text.v1
- Role:
app_state- Format:
text- Coverage:
catalog_only- Adapter:
codex.config_toml.v1
- Role:
app_state- Format:
text- Coverage:
catalog_only- Adapter:
codex.config_backup_toml.v1
- Role:
app_state- Format:
json_object- Coverage:
private- Adapter:
-
- Role:
app_state- Format:
text- Coverage:
private- Adapter:
-
- Role:
app_state- Format:
opaque- Coverage:
private- Adapter:
-
- Role:
app_state- Format:
json_object- Coverage:
catalog_only- Adapter:
codex.app_state_json_summary.v1
- Role:
app_state- Format:
json_object- Coverage:
catalog_only- Adapter:
codex.app_state_json_summary.v1
- Role:
app_state- Format:
text- Coverage:
catalog_only- Adapter:
codex.file_metadata_summary.v1
- Role:
cache- Format:
json_object- Coverage:
catalog_only- Adapter:
codex.app_state_json_summary.v1
- Role:
app_state- Format:
json_object- Coverage:
catalog_only- Adapter:
codex.app_state_json_summary.v1
- Role:
instruction- Format:
opaque- Coverage:
inspectable- Adapter:
codex.plugin_manifest_json.v1codex.plugin_instruction_text.v1codex.plugin_hooks_json.v1
- Role:
app_state- Format:
json_object- Coverage:
inspectable- Adapter:
codex.plugin_marketplace_json.v1
- Role:
instruction- Format:
text- Coverage:
inspectable- Adapter:
codex.skills_text.v1
- Role:
instruction- Format:
text- Coverage:
inspectable- Adapter:
codex.rules_text.v1
- Role:
app_state- Format:
json_object- Coverage:
catalog_only- Adapter:
codex.hooks_json.v1
- Role:
app_state- Format:
text- Coverage:
catalog_only- Adapter:
codex.project_config_toml.v1
- Role:
instruction- Format:
text- Coverage:
inspectable- Adapter:
codex.project_skill_text.v1
- Role:
app_state- Format:
opaque- Coverage:
private- Adapter:
-
- Role:
cache- Format:
opaque- Coverage:
catalog_only- Adapter:
-
- Role:
app_state- Format:
json_object- Coverage:
catalog_only- Adapter:
codex.app_state_json_summary.v1
- Role:
cache- Format:
opaque- Coverage:
catalog_only- Adapter:
-
- Role:
app_state- Format:
text- Coverage:
catalog_only- Adapter:
codex.file_metadata_summary.v1
- Role:
app_state- Format:
json_object- Coverage:
catalog_only- Adapter:
codex.app_state_json_summary.v1
- Role:
app_state- Format:
opaque- Coverage:
catalog_only- Adapter:
codex.file_metadata_summary.v1
codex.history¶
HistoryEntry { session_id: String, ts: u64 (unix seconds), text: String } — one record per user prompt, append-only across all threads. The legacy history.json array uses {command, timestamp}, where timestamp is a number in milliseconds rather than a string. Neither shape records a cwd, branch, or model: this is a flat prompt log, so records carry no origin and no model by design — codex.sessions is the store that has them.
- Agent:
Codex
- Role:
prompt_history- Format:
jsonl- Coverage:
default_search- Path:
${CODEX_HOME or ${HOME}/.codex}/history.jsonl- Adapter:
codex.history_json.v1, codex.history_jsonl.v1- Data version:
codex.history_json.legacy, codex.history_jsonl.current- Version strategies:
version_check, shape_inference, catalog_observation- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
yes
codex.sessions¶
JSONL RolloutItem tagged enum (type + payload): session_meta | response_item | compacted | turn_context | event_msg. First line is a SessionMetaLine with id, timestamp, cwd, cli_version, optional git info — but no model slug: it carries model_provider (openai), while the slug lives on the per-turn turn_context payload (model). Older root-level sessions/rollout-*.json files are JSON objects with session metadata and an items array of message-like records.
- Agent:
Codex
- Role:
primary_chat- Format:
jsonl- Coverage:
default_search- Path:
${CODEX_HOME or ${HOME}/.codex}/sessions/YYYY/MM/DD/rollout-YYYY-MM-DDThh-mm-ss-<uuid>.jsonl- Adapter:
codex.sessions_jsonl.v1, codex.sessions_legacy_json.v1- Data version:
codex.sessions.rollout.v1, codex.sessions.legacy_json.v1- Version strategies:
embedded_metadata, shape_inference, catalog_observation- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
yes
Full per-thread transcript with tool calls; codex.history is the user-prompts-only audit log.
codex.session_index¶
Append-only JSONL session index with id, thread_name, and updated_at. It summarizes sessions but does not replace the full sessions/**/*.jsonl transcripts.
- Agent:
Codex
- Role:
app_state- Format:
jsonl- Coverage:
inspectable- Path:
${CODEX_HOME or ${HOME}/.codex}/session_index.jsonl- Adapter:
codex.session_index_jsonl.v1- Data version:
codex.session_index.jsonl.v1- Version strategies:
shape_inference, catalog_observation- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.state_db¶
Codex state DB; schema managed via migrations. Observed prompt-bearing columns include threads.first_user_message, threads.preview, threads.title, and agent_jobs.instruction.
- Agent:
Codex
- Role:
app_state- Format:
sqlite- Coverage:
inspectable- Path:
${CODEX_SQLITE_HOME or ${CODEX_HOME or ${HOME}/.codex}}/state_5.sqlite- Adapter:
codex.state_sqlite.v1- Data version:
codex.state.sqlite.v5- Version strategies:
shape_inference, catalog_observation- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.logs_db¶
Codex logs DB (LOGS_DB_FILENAME in codex-rs/state/src/lib.rs). The _N.sqlite files at the Codex root (logs_2.sqlite, state_5.sqlite) belong to the Codex CLI, not Cursor.
- Agent:
Codex
- Role:
app_state- Format:
sqlite- Coverage:
catalog_only- Path:
${CODEX_SQLITE_HOME or ${CODEX_HOME or ${HOME}/.codex}}/logs_2.sqlite- Adapter:
codex.logs_sqlite.v1- Data version:
codex.logs.sqlite.v2- Version strategies:
shape_inference, catalog_observation- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.memories_db¶
SQLite memory pipeline state. Observed tables include stage1_outputs with raw memory, rollout summary, slug, usage, and selection columns.
- Agent:
Codex
- Role:
persistent_memory- Format:
sqlite- Coverage:
inspectable- Path:
${CODEX_SQLITE_HOME or ${CODEX_HOME or ${HOME}/.codex}}/memories_1.sqlite- Adapter:
codex.memories_sqlite.v1- Data version:
codex.memories.sqlite.v1- Version strategies:
shape_inference, catalog_observation- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.goals_db¶
SQLite goal tracker with thread_goals(objective, status, token_budget, tokens_used, time_used_seconds, created_at_ms, updated_at_ms).
- Agent:
Codex
- Role:
plan- Format:
sqlite- Coverage:
inspectable- Path:
${CODEX_SQLITE_HOME or ${CODEX_HOME or ${HOME}/.codex}}/goals_1.sqlite- Adapter:
codex.goals_sqlite.v1- Data version:
codex.goals.sqlite.v1- Version strategies:
shape_inference, catalog_observation- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.external_agent_imports¶
Import ledger with records carrying source path, content hash, imported thread id, and import timestamp.
- Agent:
Codex
- Role:
app_state- Format:
json_object- Coverage:
catalog_only- Path:
${CODEX_HOME or ${HOME}/.codex}/external_agent_session_imports.json- Adapter:
codex.external_imports_json.v1- Data version:
codex.external_imports.json.v1- Version strategies:
shape_inference, catalog_observation- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.instructions¶
User-level Codex instructions loaded into new sessions.
- Agent:
Codex
- Role:
instruction- Format:
text- Coverage:
inspectable- Path:
${CODEX_HOME or ${HOME}/.codex}/instructions.md- Adapter:
codex.instructions_text.v1- Data version:
-- Version strategies:
-- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.memories¶
Persistent memory workspace: MEMORY.md, memory_summary.md, raw_memories.md, rollout summaries, and skill memory folders.
- Agent:
Codex
- Role:
persistent_memory- Format:
md_frontmatter- Coverage:
inspectable- Path:
${CODEX_HOME or ${HOME}/.codex}/memories/- Adapter:
codex.memories_text.v1- Data version:
codex.memories.markdown.v1- Version strategies:
shape_inference, catalog_observation- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.config¶
Codex TOML configuration, including optional sqlite_home. It can affect discovery roots but is not prompt history.
- Agent:
Codex
- Role:
app_state- Format:
text- Coverage:
catalog_only- Path:
${CODEX_HOME or ${HOME}/.codex}/{config.toml,*.toml}- Adapter:
codex.config_toml.v1- Data version:
codex.config.toml.v1, codex.managed_config.toml.v1, codex.environments.toml.v1- Version strategies:
-- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.config_backups¶
Historical config backups. Catalogued separately from active config.
- Agent:
Codex
- Role:
app_state- Format:
text- Coverage:
catalog_only- Path:
${CODEX_HOME or ${HOME}/.codex}/{config.toml.bak*,config.toml.backup-*}- Adapter:
codex.config_backup_toml.v1- Data version:
codex.config_backup.toml.v1- Version strategies:
-- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.auth¶
Authentication state. Documented but never enumerated or searched.
- Agent:
Codex
- Role:
app_state- Format:
json_object- Coverage:
private- Path:
${CODEX_HOME or ${HOME}/.codex}/auth.json- Adapter:
-
- Data version:
-- Version strategies:
-- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.installation_id¶
Stable local installation identifier. Documented but never enumerated.
- Agent:
Codex
- Role:
app_state- Format:
text- Coverage:
private- Path:
${CODEX_HOME or ${HOME}/.codex}/installation_id- Adapter:
-
- Data version:
-- Version strategies:
-- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.secrets¶
Local secret store. Documented but never enumerated or searched.
- Agent:
Codex
- Role:
app_state- Format:
opaque- Coverage:
private- Path:
${CODEX_HOME or ${HOME}/.codex}/secrets/- Adapter:
-
- Data version:
-- Version strategies:
-- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.env¶
Environment file for local runtime configuration. Private inventory only.
- Agent:
Codex
- Role:
app_state- Format:
text- Coverage:
private- Path:
${CODEX_HOME or ${HOME}/.codex}/.env- Adapter:
-
- Data version:
-- Version strategies:
-- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.update_check¶
Update-check cache metadata; not prompt history.
- Agent:
Codex
- Role:
app_state- Format:
json_object- Coverage:
catalog_only- Path:
${CODEX_HOME or ${HOME}/.codex}/update-check.json- Adapter:
codex.app_state_json_summary.v1- Data version:
codex.update_check.json.v1- Version strategies:
-- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.version_file¶
Local app-version cache used as an inventory hint.
- Agent:
Codex
- Role:
app_state- Format:
json_object- Coverage:
catalog_only- Path:
${CODEX_HOME or ${HOME}/.codex}/version.json- Adapter:
codex.app_state_json_summary.v1- Data version:
codex.version_file.json.v1- Version strategies:
-- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.personality_migration¶
Migration marker for Codex personality defaults; not prompt history.
- Agent:
Codex
- Role:
app_state- Format:
text- Coverage:
catalog_only- Path:
${CODEX_HOME or ${HOME}/.codex}/.personality_migration- Adapter:
codex.file_metadata_summary.v1- Data version:
codex.personality_migration.marker.v1- Version strategies:
-- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.model_cache¶
Cached model metadata: client version, ETag, fetch time, and models.
- Agent:
Codex
- Role:
cache- Format:
json_object- Coverage:
catalog_only- Path:
${CODEX_HOME or ${HOME}/.codex}/models_cache.json- Adapter:
codex.app_state_json_summary.v1- Data version:
codex.model_cache.json.v1- Version strategies:
-- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.internal_storage¶
Small app flags and migration markers.
- Agent:
Codex
- Role:
app_state- Format:
json_object- Coverage:
catalog_only- Path:
${CODEX_HOME or ${HOME}/.codex}/internal_storage.json- Adapter:
codex.app_state_json_summary.v1- Data version:
codex.internal_storage.json.v1- Version strategies:
-- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.plugins¶
Installed plugin bundles, commands, skills, and cached metadata.
- Agent:
Codex
- Role:
instruction- Format:
opaque- Coverage:
inspectable- Path:
${CODEX_HOME or ${HOME}/.codex}/plugins/- Adapter:
codex.plugin_manifest_json.v1, codex.plugin_instruction_text.v1, codex.plugin_hooks_json.v1- Data version:
codex.plugin_manifest.json.v1, codex.plugin_instruction.markdown.v1, codex.plugin_hooks.json.v1- Version strategies:
shape_inference, catalog_observation- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.plugin_marketplace¶
Plugin marketplace metadata for installed or project-local plugin roots. Summarized structurally, not searched as prompt history.
- Agent:
Codex
- Role:
app_state- Format:
json_object- Coverage:
inspectable- Path:
${CODEX_HOME or ${HOME}/.codex}/plugins/**/marketplace.json- Adapter:
codex.plugin_marketplace_json.v1- Data version:
codex.plugin_marketplace.json.v1- Version strategies:
shape_inference, catalog_observation- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.skills¶
User-level Codex skill instructions.
- Agent:
Codex
- Role:
instruction- Format:
text- Coverage:
inspectable- Path:
${CODEX_HOME or ${HOME}/.codex}/skills/- Adapter:
codex.skills_text.v1- Data version:
codex.skills.markdown.v1- Version strategies:
shape_inference, catalog_observation- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.rules¶
User-defined rule files that can affect agent behavior.
- Agent:
Codex
- Role:
instruction- Format:
text- Coverage:
inspectable- Path:
${CODEX_HOME or ${HOME}/.codex}/rules/- Adapter:
codex.rules_text.v1- Data version:
codex.rules.text.v1, codex.rules.markdown.v1- Version strategies:
shape_inference, catalog_observation- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.hooks¶
Hook configuration JSON. User/project hook shape is summarized without raw command values.
- Agent:
Codex
- Role:
app_state- Format:
json_object- Coverage:
catalog_only- Path:
${CODEX_HOME or ${HOME}/.codex}/hooks.json and ${HOME}/<known_project_root>/.codex/hooks.json- Adapter:
codex.hooks_json.v1- Data version:
codex.hooks.json.v1, codex.project_hooks.json.v1- Version strategies:
shape_inference, catalog_observation- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.project_config¶
Project-local Codex configuration discovered only from roots already referenced by local Codex sessions.
- Agent:
Codex
- Role:
app_state- Format:
text- Coverage:
catalog_only- Path:
${HOME}/<known_project_root>/.codex/config.toml- Adapter:
codex.project_config_toml.v1- Data version:
codex.project_config.toml.v1- Version strategies:
shape_inference, catalog_observation- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.project_skills¶
Project-local Codex skill Markdown from known project roots. Kept non-default because project instructions are broader than chat history.
- Agent:
Codex
- Role:
instruction- Format:
text- Coverage:
inspectable- Path:
${HOME}/<known_project_root>/.codex/skills/- Adapter:
codex.project_skill_text.v1- Data version:
codex.project_skills.markdown.v1- Version strategies:
shape_inference, catalog_observation- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.policy¶
Policy state and downloaded policy metadata.
- Agent:
Codex
- Role:
app_state- Format:
opaque- Coverage:
private- Path:
${CODEX_HOME or ${HOME}/.codex}/policy/- Adapter:
-
- Data version:
-- Version strategies:
-- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.runtime_cache¶
Runtime cache and temporary files. The sqlite/ subdir is a nested/alternate SQLite home (a candidate CODEX_SQLITE_HOME / config sqlite_home target) holding full same-schema DB copies, not -wal/-shm sidecars — those belong to codex.sqlite_sidecars.
- Agent:
Codex
- Role:
cache- Format:
opaque- Coverage:
catalog_only- Path:
${CODEX_HOME or ${HOME}/.codex}/{cache,tmp,.tmp,sqlite}/- Adapter:
-
- Data version:
-- Version strategies:
-- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.arg0_runtime¶
Arg0 runtime coordination state, summarized without raw values.
- Agent:
Codex
- Role:
app_state- Format:
json_object- Coverage:
catalog_only- Path:
${CODEX_HOME or ${HOME}/.codex}/tmp/arg0/- Adapter:
codex.app_state_json_summary.v1- Data version:
codex.arg0_runtime.json.v1- Version strategies:
-- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.sqlite_sidecars¶
SQLite WAL/SHM sidecars for Codex databases.
- Agent:
Codex
- Role:
cache- Format:
opaque- Coverage:
catalog_only- Path:
${CODEX_SQLITE_HOME or ${CODEX_HOME or ${HOME}/.codex}}/*.sqlite-{wal,shm}- Adapter:
-
- Data version:
-- Version strategies:
-- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.log_files¶
Runtime log files. Search the structured logs DB only by explicit inspection.
- Agent:
Codex
- Role:
app_state- Format:
text- Coverage:
catalog_only- Path:
${CODEX_HOME or ${HOME}/.codex}/log/- Adapter:
codex.file_metadata_summary.v1- Data version:
codex.log_file.text.v1- Version strategies:
-- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.process_manager¶
Process-manager state for background jobs.
- Agent:
Codex
- Role:
app_state- Format:
json_object- Coverage:
catalog_only- Path:
${CODEX_HOME or ${HOME}/.codex}/process_manager/- Adapter:
codex.app_state_json_summary.v1- Data version:
codex.process_manager.json.v1- Version strategies:
-- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
codex.shell_snapshots¶
Shell/runtime snapshots, not prompt history.
- Agent:
Codex
- Role:
app_state- Format:
opaque- Coverage:
catalog_only- Path:
${CODEX_HOME or ${HOME}/.codex}/shell_snapshots/- Adapter:
codex.file_metadata_summary.v1- Data version:
codex.shell_snapshot.text.v1- Version strategies:
-- Observed:
github.com/openai/codex@3fb81667 (2026-06-21) (2026-06-21)
- Default search:
no
Version detection¶
Codex exposes both app-version context and concrete data-shape
versions in source discovery. models_cache.json.client_version
provides app-version context when present; version.json.latest_version
is not treated as the installed version. Session transcripts can carry
session_meta.payload.cli_version, which is stronger evidence for
that transcript than the global cache.
Metadata-rich discovery reads the root client-version cache once per discovery pass and reuses it for every Codex source. Normal search and find paths skip version evidence entirely, so broad all-agent lookups do not reread root metadata before the query planner narrows the source set.
Data-shape detection is based on the source itself. history.jsonl
records with session_id, ts, and text are reported as
codex.history_jsonl.current; legacy history.json array records with
command and timestamp are reported as
codex.history_json.legacy. Legacy root sessions/rollout-*.json
objects with session and items are reported as
codex.sessions.legacy_json.v1. SQLite stores derive data versions
from their migration suffixes, such as state_5.sqlite →
codex.state.sqlite.v5. Config, app-state, skill, rule, and plugin
adapters infer shape from TOML keys, JSON keys, manifest keys, hook
event names, marketplace keys, file metadata, or instruction paths
while keeping those sources outside default search.
Record schemas¶
Prompt history¶
codex.history is one record per user prompt, append-only across
all threads. Modern Codex writes history.jsonl records with session_id,
Unix-second ts, and text; older installs may carry history.json records
with command and timestamp. agentgrep supports both shapes but reports the
JSONL shape through codex.history_jsonl.v1.
{"session_id": "...", "ts": 1747509826, "text": "<user prompt>"}
Upstream type: HistoryEntry { session_id: String, ts: u64, text: String }
(codex-rs/message-history/src/lib.rs:56).
Session transcripts¶
codex.sessions is a JSONL RolloutItem tagged enum (type +
payload): session_meta | response_item | compacted | turn_context |
event_msg.
{"type": "response_item", "payload": {"role": "user", "content": "<prompt>"}}
Upstream type: codex-rs/protocol/src/protocol.rs:2929.
Older installs can also have root-level
sessions/rollout-YYYY-MM-DD-*.json files. Those are JSON objects
with session metadata and an items array carrying message-like
records with role, type, and content. agentgrep treats them as
the same primary chat store through codex.sessions_legacy_json.v1.
Session index¶
codex.session_index is an append-only index with id,
thread_name, and updated_at. It is useful for inventory and session
selection, but the full transcript remains sessions/YYYY/MM/DD/rollout-*.jsonl
or the legacy root sessions/rollout-*.json shape.
SQLite Stores¶
Codex resolves SQLite storage from CODEX_SQLITE_HOME, then
sqlite_home in config.toml, then CODEX_HOME. The known DB files
are:
Store |
File |
Notes |
|---|---|---|
|
Threads, previews, dynamic tools, agent jobs, spawn edges, and job instructions. |
|
|
Structured logs and feedback log payloads; catalog-only samples read |
|
|
Memory pipeline outputs, rollout summaries, usage, and selection state. |
|
|
Thread goal objectives, statuses, token budgets, and usage. |
These DBs are not searched by default because they can duplicate transcripts, contain runtime state, or mix prompt-bearing fields with operational metadata.
Instructions, Memory, And Runtime State¶
instructions.md, skills/, rules/, project .codex/skills/, and
plugin bundles are instruction surfaces rather than chat transcripts.
The root instructions file, user skills, project skills, rules, plugin
manifests, plugin marketplace metadata, plugin hooks, and plugin
command/agent/skill/custom-skill Markdown are inspectable but stay
outside default search. Project-local files are discovered only from
roots already referenced by local Codex session metadata; agentgrep
does not recursively scan $HOME for arbitrary .codex directories.
memories/ and memories_1.sqlite hold retained memory and rollout
summaries; the Markdown workspace is inspectable through
codex.memories_text.v1. The external-agent import ledger exposes
imported thread ids and source file names for explicit inspection
without indexing full imported content. Config TOML, managed config,
environment TOML, config backups, project config,
update/version/model/internal JSON, hooks, arg0 runtime state, and
process-manager state expose only key/type summaries. Raw logs, shell
snapshots, and personality-migration markers expose metadata-only file
summaries.
Auth, installation id, secrets, .env, and policy state are private;
caches, SQLite sidecars, and temp directories are catalogued for audits
but stay outside default search.
Project context¶
Store |
|
|
|
|---|---|---|---|
first |
|
|
|
|
|
|
|
— |
— |
— |
The two stores that know where a session ran write the path literally, so
they land in the lossless tier and answer
--cwd, cwd:, and branch: with the real values.
A rollout’s session_meta header names model_provider — the provider
id, not a model slug — so the session model is read from the first valid
per-turn turn_context record instead, which is where Codex writes the
slug the session actually ran as. The reader scans complete JSONL records,
discarding unrelated large records in bounded chunks rather than imposing a
fixed byte cutoff. session_meta is the fallback only when the rollout has
no valid model-bearing turn_context record.
A codex.state_db threads row keeps the model, the
working directory, the git branch, and the remote URL beside the prompt
text, so those records carry an origin without re-reading the rollout
file. git_origin_url lands on origin.remote. The agent_jobs rows in
the same database stay origin-less: the shipped table has no thread_id
column to reach a threads row through. The database is reachable at
--scope conversations, not at the default prompt scope.
The state database is an index and fallback, not a second canonical
transcript. When a matching first_user_message row and a matching rollout
prompt have the same text and identify the same conversation by exact rollout
path or thread id, agentgrep keeps the rollout result. Resolution happens
across matching candidates before ranking and limits, so index-only matches
such as a state-database title, model, or working directory remain searchable.
Explicit store, path, and adapter filters still select the physical state row;
--no-dedupe and genuinely different state previews remain unchanged.
codex.history carries no project context in any shape
Codex has shipped: the JSONL rows are session_id, ts, and text, and
the legacy JSON rows are command and timestamp. That store is
searchable by text, agent, and time, and it does not satisfy an origin
filter.