# Codex Ops Kit

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
bash scripts/install_codex_kit.sh
```

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

```bash
bash scripts/export_codex_portable.sh
```

Audit your live Codex home:

```bash
bash scripts/audit_codex_home.sh
```

Preview old session files that are taking space:

```bash
bash scripts/prune_codex_sessions.sh
```

Archive old session files after reviewing the plan:

```bash
bash scripts/prune_codex_sessions.sh --apply
```

Extract a markdown summary skeleton from a large session transcript:

```bash
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](/Users/timevans/Documents/New%20project/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`.