Project instructions and memory.

Project instructions describe how work should be done. Project memory records durable facts and decisions worth carrying into future turns. Both are files you can review; neither is unlimited automatic recollection. This guide covers CLI 0.9.0.

#Put guidance at the right scope

Use AGENTS.md for a folder's instructions. Code falls back to CLAUDE.md only when that folder has no AGENTS.md. In a trusted workspace, it can also load ancestor instructions up to the containing Git root, within its parent-depth bound, and Markdown memory files in .kaitoi/.

Personal global instructions belong in AGENTS.md inside Code's user config directory, beside config.json. Other products' global ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md are not automatically imported.

Global Code instructions set broad preferences. Repository and workspace AGENTS.md files provide closer guidance, with CLAUDE.md as a fallback within each folder. Workspace .kaitoi/context.md records curated memory. Nested instructions under src arrive with the first applicable read or edit in a turn, rather than every nested file loading at startup. All content is bounded and cannot expand tool permissions.

The opened src/feature/search.ts file sits inside its applicable nested guidance. A bounded context tray distinguishes global, repository and feature excerpts; curated memory remains a separate notebook.

Nested instructions below the workspace are attached when Code first reads or edits the relevant area in a turn. Do not assume every nested document is in context before that area is touched. File trust, exclusions, and safe path resolution still apply.

#Write instructions that survive reuse

Keep the root guide short: project purpose, important entry points, style rules, relevant checks, and actions that need special care. Put subsystem details in the applicable folder. Favor concrete criteria over long histories of earlier conversations.

The default shared read budget is 14,000 characters, with a separate 4,000-character bound for nested instruction material. Budget selection prioritizes workspace instructions and memory, then nearby parents and global guidance. Rendering places general guidance before more specific workspace context. Long files may be truncated; location does not guarantee every word will be loaded.

#Keep a curated memory file

Workspace .kaitoi/context.md is read first among the memory files. Use it for current architecture decisions, accepted constraints, and the next useful verification step. Keep secrets and rapidly changing runtime output out of it.

You can ask Code to update project memory. The local.remember tool replaces the curated overview, subject to edit permissions and a 6,000-character limit. Review the replacement so it does not discard useful existing decisions. There is no separate /memory slash command established by this interface.

#Check what reached the session

Use /status and /doctor for source/configuration diagnostics and /context for the next request's context pressure. If guidance is absent, check workspace trust, the exact path, fallback precedence, file policy, and length before duplicating it into every prompt.

Instructions can guide an allowed action; they cannot grant sandbox access, approve spending, or override unavailable account capabilities. Keep execution authority in the actual permission controls.