How to give Codex better memory

What Codex reads on each run

AGENTS.md is the documented way to give Codex extra instructions and context for your project (Codex docs). Codex builds an instruction chain from these files when it starts, once per run, which in the TUI usually means once per launched session (Codex docs).

The chain is rebuilt on every run and at the start of each TUI session, so there is no cache to clear manually (Codex docs).

Set global defaults in ~/.codex

Global guidance lives in the Codex home directory, which defaults to ~/.codex unless CODEX_HOME is set (Codex docs). At this level, Codex uses only the first non-empty instruction file it finds (Codex docs). A global AGENTS.md here creates persistent defaults, so every repository inherits your working agreements (Codex docs).

Layering global guidance with project-specific overrides lets every task start with consistent expectations, no matter which repository you open (Codex docs).

Override guidance temporarily

In the Codex home directory, Codex also reads AGENTS.override.md if it exists (Codex docs). Use it when you need a temporary global override without deleting the base file, and remove it to restore the shared guidance (Codex docs).

Note the precedence: in a directory that has both files, AGENTS.md is ignored because an AGENTS.override.md exists (Codex docs).

Add repository-level AGENTS.md files

Starting at the project root, typically the Git root, Codex walks down to your current working directory (Codex docs). If no project root exists, it only checks the current directory (Codex docs). It includes at most one instruction file per directory (Codex docs).

Files are concatenated from the root down and joined with blank lines, so files closer to your current directory override earlier guidance (Codex docs). Repository-level files keep Codex aware of project norms while still inheriting your global defaults (Codex docs).

For Codex code review in GitHub, add a ## Code Review Rules section to the AGENTS.md closest to the code the rules govern (Codex docs). Keep rules concise, explain the behavior to flag and any safe path or exception, and reserve formatting and lint checks for CI (Codex docs).

Know the limits

Codex skips empty files and stops adding instruction files once the combined size reaches project_doc_max_bytes, 32 KiB by default (Codex docs). When you hit the cap, the documented remedy is to raise the limit or split instructions across nested directories (Codex docs).

Codex stops searching once it reaches your current directory, so place overrides as close to specialized work as possible (Codex docs). Alternate filenames such as TEAM_GUIDE.md and .agents.md can be listed in project_doc_fallback_filenames, and filenames not on that list are ignored during instruction discovery (Codex docs).

Check that your setup loads

Restart Codex or run a new command so the updated configuration loads (Codex docs). To verify, Codex should echo guidance from global and project files in precedence order (Codex docs).

If nothing loads, ensure the instruction files contain content, because Codex ignores empty files (Codex docs). If instructions are truncated, raise project_doc_max_bytes or split large files across nested directories (Codex docs). You can also set CODEX_HOME to use a different profile, such as a project-specific automation user (Codex docs).

Where KnowMan fits

AGENTS.md is the documented home for instructions and project context (Codex docs). KnowMan adds a different layer: a knowledge base that saves articles and links, reads and tags them, answers questions with citations, and keeps memories as claims, decisions, and playbooks. For the wider pattern, see persistent memory for AI agents.

KnowMan offers a local stdio MCP server, the package @knowman/mcp, started with npx -y @knowman/mcp (Node 22 or newer), and a hosted server at https://api.knowman.io/mcp. The local server authenticates to KnowMan's HTTP API with a Bearer key in KNOWMAN_API_KEY created at Settings > Connections > Connect an AI agent (MCP server knowledge base). Its tools include kb_search for saved items by keyword or meaning, kb_ask for answers with citations, and kb_memories for saved claims, decisions, and playbooks (MCP server knowledge base). The hosted server lets clients that accept remote MCP servers connect to KnowMan (MCP server knowledge base).

Connect Codex to hosted KnowMan

For Codex workflows in clients that support remote MCP servers, add https://api.knowman.io/mcp as the server URL. Sign in through the KnowMan consent page with OAuth and approve access, or use an API key created in KnowMan settings.

With an API key, configure the client to send Authorization: Bearer <key>. Once connected, ask the assistant to search your KnowMan or save a URL.