This repository turns a local Codex setup into something you can keep lean, remember more usefully, and share across machines without dragging along secrets or multi-gigabyte session logs.

What We Improved

Added explicit Codex profiles for economy, balanced, and deep work.
Added a short global AGENTS.md pattern that tells Codex where to find durable memory without bloating every session.
Added portable memory files you can keep in Git and sync between machines.
Added audit, export, install, and session-maintenance scripts.
Documented research-backed guidance from current OpenAI docs plus community findings.

Findings From This Machine

Audit date: 2026-04-12

~/.codex/sessions was about 2.8G.
~/.codex/state_5.sqlite was about 227M.
~/.codex/memories was empty.
Current config only set the model and plugin flags, so there were no cost-oriented profiles or memory workflow conventions in place.

The biggest issue was not a lack of raw stored data. It was that durable, reusable knowledge was not being separated from bulky transcript history.

Repo Layout

docs/research.md
templates/global/AGENTS.md
templates/global/config.toml
memory/
scripts/

Local Setup

Install this kit into your current Codex home:

bash scripts/install_codex_kit.sh

Create a portable export bundle you can move to another machine:

bash scripts/export_codex_portable.sh

Audit your live Codex home:

bash scripts/audit_codex_home.sh

Preview old session files that are taking space:

bash scripts/prune_codex_sessions.sh

Archive old session files after reviewing the plan:

bash scripts/prune_codex_sessions.sh --apply

Extract a markdown summary skeleton from a large session transcript:

python3 scripts/session_to_memory.py ~/.codex/sessions/2026/03/19/rollout-....jsonl

Recommended Workflow

Use balanced for normal work, economy for quick edits and low-risk tasks, and deep only for the hard stuff.

Keep AGENTS.md concise. Put stable personal preferences, project summaries, and long-lived decisions into the markdown files under memory/.

When a long session finishes, distill the durable facts into memory notes instead of relying on Codex to rediscover them from old transcript files.

Run the audit script periodically. If session storage balloons again, archive the biggest old transcripts instead of letting ~/.codex/sessions become your accidental memory system.

Profiles

economy: lowest-cost default for shallow work
balanced: everyday profile
deep: higher-effort work when architecture or debugging really needs it

These profiles are defined in templates/global/config.toml. The installer preserves machine-specific plugin and trust settings while merging the managed cost and memory block into your live ~/.codex/config.toml.