# Research Notes

Research date: `2026-04-12`

## Reliable Takeaways

1. OpenAI's `Codex Prompting Guide` says `medium` reasoning effort is the recommended all-around default, while `high` or `xhigh` should be reserved for harder work. It also calls out compaction as a first-class way to support long-running conversations without hitting context limits.
Source: [Codex Prompting Guide](https://developers.openai.com/cookbook/examples/gpt-5/codex_prompting_guide)

2. OpenAI's configuration reference supports profile-scoped overrides, including `profiles.<name>.model`, `profiles.<name>.model_reasoning_effort`, `profiles.<name>.model_instructions_file`, `profiles.<name>.web_search`, `project_doc_max_bytes`, and `history.max_bytes`.
Source: [Configuration Reference](https://developers.openai.com/codex/config-reference)

3. OpenAI's slash-command docs show that `/status` exposes token usage and `/statusline` can persist footer items like model, context, limits, tokens, and session id. That makes it easier to notice expensive sessions before they sprawl.
Source: [Slash commands in Codex CLI](https://developers.openai.com/codex/cli/slash-commands)

4. The `GPT-5.3-Codex` model page lists a large discount for cached input tokens compared with regular input tokens. This supports a strategy of keeping stable instructions and repeated context in consistent, reusable front-loaded text instead of rewriting them ad hoc every session.
Source: [GPT-5.3-Codex model page](https://developers.openai.com/api/docs/models/gpt-5.3-codex)

5. An arXiv paper published in 2026 found that adding repository-level `AGENTS.md` files was associated with lower median runtime and reduced output-token usage while keeping comparable task completion behavior.
Source: [On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents](https://arxiv.org/abs/2601.20404)

## Community Signals

1. Community writeups consistently recommend small, specific `AGENTS.md` files instead of large prose dumps. The basic pattern is to keep the instruction layer lean and push durable knowledge into separate reusable notes.
Source: [Codex CLI reference guide](https://blakecrosley.com/guides/codex)

2. There is active experimentation around external or MCP-backed memory systems so that project knowledge survives across restarts and across tools. I treated these as directional input rather than source-of-truth guidance because they are not official OpenAI docs.
Source: [Memory for Codex discussion](https://www.reddit.com/r/codex/comments/1rmhtmr/memory_for_codex/)

## Design Decisions For This Kit

- Keep the always-loaded instruction surface short.
- Use profiles instead of one global "best" model choice.
- Separate durable markdown memory from bulky session history.
- Default maintenance scripts to audit and dry-run, not deletion.
- Export only portable assets: config, instructions, memory, and scripts. Do not export auth or giant local databases.