How to teach Codex your knowledge

Start with global instructions

Create ~/.codex/AGENTS.md for reusable preferences that apply across repositories (Codex documentation). Codex reads AGENTS.override.md if it exists at global scope, otherwise it reads AGENTS.md, and it uses only the first non-empty global instruction file (Codex documentation).

Add project rules

Add AGENTS.md at the repository root for repository norms (Codex documentation). At project scope, Codex searches from the project root down to the current working directory, checking AGENTS.override.md, then AGENTS.md, then configured fallback names, with at most one instruction file per directory (Codex documentation).

Use overrides near the work

Put specialized overrides close to the relevant work because Codex stops its search at the current directory (Codex documentation). Files closer to the current directory appear later in the combined prompt and override earlier guidance (Codex documentation). If a repository already uses a name such as TEAM_GUIDE.md, add it to project_doc_fallback_filenames (Codex documentation).

Keep instructions within Codex limits

Codex skips empty instruction files and stops adding files when the combined size reaches project_doc_max_bytes, which defaults to 32 KiB (Codex documentation). Codex builds its instruction chain once per run, usually once per launched TUI session, so restart it in the target directory when guidance changes (Codex documentation).

Check what Codex loaded

Ask Codex to summarize its current instructions, for example with codex --ask-for-approval never "Summarize the current instructions." (Codex documentation). To audit loaded files, enable a plaintext TUI log with codex -c log_dir=./.codex-log and inspect ./.codex-log/codex-tui.log (Codex documentation).

Separate instructions from knowledge

Use AGENTS.md for durable instructions that Codex should apply while working. KnowMan saves articles and links, reads and tags them, answers questions with citations, and keeps claims, decisions, and playbooks (KnowMan overview). A confirmed Codex connection is needed before treating saved KnowMan items as context for Codex.

Keep the knowledge library local

KnowMan runs locally with npx -y @knowman/mcp and as a hosted server at https://api.knowman.io/mcp with OAuth sign-in or an API key (KnowMan MCP guide). KnowMan documents MCP setups for Claude Desktop, Claude Code, and Cursor, but not Codex.

Plan a Codex connection carefully

KnowMan's MCP package is @knowman/mcp. It requires Node 22 or newer and uses a KNOWMAN_API_KEY or a saved CLI sign-in credential. Before attempting a Codex setup, confirm that the client supports local stdio MCP servers and that its configuration supports the mcpServers format.

Connect Codex to the hosted KnowMan server

In clients that support remote MCP servers, you add the server URL https://api.knowman.io/mcp and sign in with OAuth. The client opens the KnowMan consent page, where you approve the knowman.read scope for search, read, and ask tools and knowman.write for saving links. Access tokens last one hour and refresh automatically.

The alternative is an API key, created in KnowMan settings and sent as an Authorization: Bearer header to https://api.knowman.io/mcp. A key cannot create other keys, and you disconnect an app by deleting its OAuth entry in your KnowMan API-keys list.

Once connected, the same six tools are available as with the local server: kb_search, kb_ask, kb_get_item, kb_save, kb_recent, and the read-only kb_memories. You can then ask Codex to search your KnowMan for a topic or save a URL.