Codex¶
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@4c89772 (2026-05-16).
Stores¶
Coverage is not the same as default search. default stores are
searched normally; inspectable stores are discoverable only when an
inventory caller opts in; catalog stores are documented but not
searched by default; private stores are intentionally not
enumerated. Some catalog stores have safe sample parsers for
inspect_record_sample, but they do not join normal search.
- 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.
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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. 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- Default search:
no
codex.runtime_cache¶
Runtime cache, temporary files, and SQLite sidecar directories.
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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@4c89772 (2026-05-16) (2026-05-17)
- 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¶
codex.history¶
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:54).
codex.sessions¶
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:2783.
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.
codex.session_index¶
session_index.jsonl 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.