How do I make Codex remember project context?

Put maintained project instructions in AGENTS.md so Codex reads them at startup, and keep detailed decisions in linked repository documents. Use private memory for personal preferences and conversation context that should follow you across sessions or assistants. Cairn.ink Memory's Cloud installer adds automatic Codex capture and prompt recall; Local provides explicit memory tools on one computer.

What should Codex learn from AGENTS.md?

Write the working context you would otherwise repeat at the beginning of a task: how to find the right tests, which contribution rules apply and where important decisions are maintained. Keep instructions specific enough that a new contributor could act on them too.

A small example for a hypothetical repository is:

## Working rules

- Read package.json before choosing build or test commands.
- Use the existing focused test for the component you change.
- Read docs/architecture.md before changing persistence behavior.
- Report the actual check result and any unresolved failure.

Adapt these example rules to the real project. Point to maintained files for volatile details, such as runtime versions or package scripts. Keep the root instructions concise and put longer explanations in ordinary documentation. That makes the entry point easier for both people and Codex to review.

Team instructions belong in version control when the team wants them shared. Review changes alongside the behavior they describe, particularly when a new script replaces an old command or a migration changes a supported workflow.

How does Codex find the instruction files?

The official AGENTS.md guide, accessed 2026-11-12, describes an instruction chain built at startup. Codex first reads global guidance from its home directory, normally ~/.codex unless CODEX_HOME selects another location. It checks AGENTS.override.md before AGENTS.md and uses the first non-empty file there.

For project guidance, it walks from the project root to the current working directory. In each directory it checks AGENTS.override.md, then AGENTS.md, then configured fallback filenames. It includes at most one instruction file per directory. Files nearer the working directory appear later and override earlier guidance.

The combined project-document size limit is 32 KiB by default, controlled by project_doc_max_bytes. Keep essential rules short and use nested instructions for specialized work. A service-specific file is useful when you launch Codex in that service's directory and want its additional working rules included.

How do I check what Codex actually loaded?

Restart Codex from the intended directory after changing instruction files. Then ask it to list active instruction sources and summarize the relevant rule. Compare its answer with the files and explain how the rule should affect the task before starting a risky edit.

Check the current directory, Codex home and any override file when the wrong instructions appear. An override in the same directory takes priority over AGENTS.md. Empty files are skipped. A custom CODEX_HOME points Codex at a different set of global guidance, which matters when you use separate profiles.

Instruction files provide context, not an enforcement guarantee. Keep permissions and required validation in the mechanisms that actually govern operations. For a normal project task, checking the loaded guidance and the resulting test command gives you practical evidence that the setup is doing what you intended.

What belongs in private memory instead?

Use user-level instructions for stable preferences you want Codex to read broadly. Use private Memory for selected personal context you want retrieved across supported assistants: explanation style, a preference you clarified during a discussion, or private working context for one project.

Keep a team's release procedure in its reviewed source. A private reminder can point you to that procedure, while the shared document remains the place contributors maintain it. If a conversation changes a project decision, record the accepted decision in the repository before treating it as a team rule.

In Cairn.ink Memory, a Memory is private user-owned context. Personal scope follows you across projects; project-private scope uses an opaque project identity. A Knowledge Card is a separate durable knowledge document, and publishing it to a shared collection requires a separate human decision.

How do I enable Cairn.ink Memory's Codex integration?

Start with:

npx @cairn-ink/memory setup

Choose Cloud for automatic capture and prompt recall. You need Node 22.16 or later and the selected CLIs on your path. Setup finds Claude Code and Codex and asks about new connections. Approve the clients you want; when connecting both, close them fully and wait for background work before confirming sharing.

One browser sign-in connects a first paired installation. A memory ID links the same project across tools, so use the installer's identity instead of guessing from folder names. Reopen Codex and review and allow the four Cairn.ink Memory hooks in /hooks.

Hooks run integration actions at client events. In the installer README, Cloud uses them for automatic conversation capture and prompt recall, alongside explicit MCP tools. Automatic memory requires a qualified Codex format; automated codex exec runs skip capture and prompt recall by default. Follow setup's diagnostics if your format needs attention.

Cloud saves conversation text after best-effort local masking and sends a masked, length-limited prompt copy for recall. Review the privacy controls for that data flow. To pause and resume a paired installation, use:

npx @cairn-ink/memory pause
npx @cairn-ink/memory resume

How do I use Local or explicit hosted tools?

Choose Local in setup for free, no-account explicit tools on one computer, without automatic capture or cross-computer sync. It registers cairn-local; supported clients share the same database and owner. Ask for an explicit save, then use inspect_memory to check its ID, content and receipts. Model-guided semantic recall needs a configured model key; saving and inspecting work without one.

For hosted explicit tools only, the release README documents manual codex mcp add as an alternative to the automatic installer. Keep its bearer-token environment variable outside committed configuration. The official Codex MCP guide, accessed 2026-11-12, explains client registration and authentication. Follow the existing connection walkthrough if you choose that path.

What should I verify before relying on remembered context?

Test the two layers separately. After restarting, ask Codex to identify the repository instruction that governs the task. Then ask it to retrieve a harmless saved private preference from a fresh session, showing the returned identifier and source. For Cloud, also check a harmless ordinary-conversation capture if that is the behavior you plan to use.

Compare technical memories with maintained project files before changing implementation. Use the existing cross-client sharing and stale-memory guides for those longer workflows. This keeps AGENTS.md focused on project expectations while private Memory carries personal continuity.

Use the connection guide to configure Codex alongside your maintained project instructions.