Add official CLI commands to inspect, prune, delete, and scope Codex memories

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• #30159
• #29818

Powered by Codex Action

The product boundary I would make explicit is that memory is user-owned state, not just an internal cache. If the agent can accumulate durable influence across projects, the user needs a first-class way to inspect, scope, move, prune, and delete that influence without editing generated files by hand.

I would split the CLI surface into three safe layers:

1. read-only inventory: list, search, show, and explain why an entry is in scope for the current workspace;
2. scope repair: move a memory entry between global and project scope, or mark it excluded from a path;
3. destructive cleanup: delete, prune, and compact, with dry-run output before any write.

The important default is that destructive memory operations should behave like state-changing agent actions. They should show the exact entries affected, the scope being changed, the backup location, and the post-operation summary before the write is accepted. A memory delete command should not feel like deleting a saved chat session; it changes future model context and should have its own receipt.

The regression shape I would want is a fixture with one global memory, one project-scoped memory, and one stale rollout-derived memory. The CLI should prove that search finds all three, current-workspace scope explains only the applicable ones, dry-run delete changes nothing, move-to-project removes global leakage, and prune creates a restorable backup before compaction.

That would make memory useful without letting it become invisible policy.

Boundary: architecture and regression-test feedback only; no claim about running the product, validating implementation behavior, implementation correctness, roadmap fit, merge readiness, security review, production readiness, partnership, customer interest, official alignment, OpenAI usage, Codex usage, conformance certification, or Neura usage.

I pushed a read-only inspection slice for this here:

Branch: https://github.com/Nicolas0315/codex/tree/codex/memory-inspect-cli
Commits:

• 89b32c6302316b9c9af792e9ce04a9a639dcb9e1 feat(memory): expose memory inventory entries
• 1e7d8a8895d2d89f7e3c80caee0ec4ed2b3d9844 feat(memory): add CLI inspection commands

What it adds:

• codex memory list
• codex memory search <query>
• codex memory show <thread-id>
• human and --json output
• scope/source metadata in output: cwd, rollout_path, git_branch, memory_mode
• search over memory payload fields plus hydrated scope metadata

Boundary: this intentionally handles the non-destructive inspection/audit part first. It does not add prune/delete/scope mutation commands yet.

Local verification on rtx4090:

• cargo fmt passed; stable rustfmt emitted the repo's existing imports_granularity = Item warning
• cargo check -p codex-cli -p codex-state passed
• cargo test -p codex-cli --test memory -- --nocapture passed: 2/2
• git diff --check HEAD~2 HEAD passed
• cargo nextest run -p codex-cli -p codex-state --no-fail-fast: 450/451 passed. The only failure was doctor::thread_inventory::tests::thread_inventory_check_warns_for_missing_stale_and_mismatched_rows; I reproduced the same failure on clean merge-base d047c33a1 on this Windows host, so it appears pre-existing and unrelated to this branch.

SSH validation of exact HEAD 1e7d8a8895d2d89f7e3c80caee0ec4ed2b3d9844:

• cyberagent-mac-m5max: git diff --check, cargo check -p codex-cli -p codex-state, and cargo test -p codex-cli --test memory -- --nocapture passed
• nicolas2025: git diff --check, cargo check -p codex-cli -p codex-state, and cargo test -p codex-cli --test memory -- --nocapture passed
• nicolas-macbook-pro: git diff --check passed; cargo missing, compile tests skipped
• rtx5060ti: git diff --check passed; Rust build skipped due the host's known MSVC linker failure

I attempted to open a PR from Nicolas0315:codex/memory-inspect-cli, but GitHub returned Nicolas0315 does not have the correct permissions to execute CreatePullRequest for this repo.

This is the right first slice: make inspection boring, deterministic, and strictly read-only before adding any scope repair or destructive commands.

The acceptance boundary I would put around the inspection layer is that it is a projection of memory state, not a memory operation. Listing, searching, and showing entries should never hydrate new memory, rewrite scope metadata, compact stale rows, update access timestamps, or normalize anything in place. If the command changes future context, it has already crossed out of inspection.

For the first contract, I would make the JSON shape stable enough that other tooling can diff it:

1. entry identity and source identity are separate fields;
2. scope provenance is explicit: cwd, rollout_path, git branch when known, memory mode, and why the entry is in scope for the current workspace;
3. payload preview is bounded and clearly marked as preview, while full content requires an explicit show command;
4. missing, stale, or mismatched scope metadata is represented as data, not silently repaired;
5. human output is just a rendering of the same record shape as JSON, not a second authority path.

The regression shape I would want before mutation commands land:

1. list shows global, project, and rollout-derived entries without changing any backing file;
2. search matches both payload text and hydrated scope metadata;
3. show returns one stable entry record and fails closed on an unknown id;
4. JSON output round-trips through a fixture comparison without timestamp churn;
5. inspection against stale metadata reports the mismatch but does not repair it;
6. a read-only command leaves a byte-for-byte unchanged memory store.

That keeps the next step clean: once inspection is a stable, side-effect-free evidence layer, scope repair and prune/delete can require a separate dry-run plus receipt boundary instead of inheriting ambiguity from the read path.

Boundary: architecture and regression-test feedback only; no claim about using this branch, running this branch, validating implementation behavior, implementation correctness, merge readiness, security review, production readiness, partnership, customer interest, official alignment, OpenAI usage, Codex usage, conformance certification, or Neura usage.

Adding a current macOS Desktop data point that may help define the remaining control-surface gap.

Environment: Codex Desktop 26.715.52143 with bundled codex-cli 0.145.0-alpha.18.

A privacy-scrubbed local audit found roughly 2.8 MB in the native-memory storage tree, including hundreds of KB of consolidated and raw memory, two dozen pending notes, and more than 100 rollout summaries. The retained corpus mixed cross-project material with stale operational state and stale paths.

The current app-server schema exposes memory/reset. In this build, it behaved as an all-or-nothing operation: it cleared the memory directories and corresponding database rows. I could not find a supported selective-delete, manual-consolidate, or in-place rebuild control.

A controlled cleanup/disable check also clarified an important distinction:

With features.memories=true, use_memories=false, generate_memories=false, and disable_on_external_context=true, an existing corpus could remain on disk. Its presence alone does not establish that new memories were generated while those settings were false.

After memory/reset, setting features.memories=false while retaining the other false values resulted in no observed native-memory injection or corpus/database regrowth across multiple fresh Tasks in different working directories after ordinary read-only activity.

Project AGENTS.md instructions still loaded normally, so disabling native memory did not disable static project instructions.

This supports an official surface for inspection, selective deletion, pruning, and controlled rebuild, plus clearer semantics distinguishing “stop using,” “stop generating,” and “erase existing corpus.” The current reset is a useful recovery primitive, but it is too coarse for correcting one stale or mis-scoped memory.

The native Codex memory store still needs the official management surface proposed here. For users who need a user-controlled layer now, GoodMemory 0.7.1 can run alongside Codex without modifying the native ~/.codex/memories corpus:

npm install -g goodmemory@0.7.1
goodmemory setup --host codex --activation-mode workspace_opt_in --writeback off
cd /path/to/repo
goodmemory enable codex --workspace-root "$PWD" --workspace-id my-repo --writeback observe
goodmemory status codex --workspace-root "$PWD"

Its installed MCP surface is read-only by default and exposes goodmemory_inspect_memory, goodmemory_trace_recall, goodmemory_search_index, goodmemory_get_records, and goodmemory_stats. Durable records have stable IDs, explicit user/workspace/agent scope and provenance; a targeted record can be removed with:

goodmemory forget --host codex --workspace-root "$PWD" --memory-id <id>

This is deliberately a parallel workaround/reference implementation, not a way to inspect, prune, or repair Codex native memory. The useful product boundary is that read-only inspection stays side-effect-free, while a destructive operation is explicit and ID-scoped.

Disclosure: I maintain GoodMemory. No claim that it replaces Codex native memory or fixes this issue.