# Project instructions and memory

> Put durable project guidance where Code can load it, understand parent and nested instruction scope, and keep bounded project memory concise and current.

Source: https://kaitoi.io/docs/cli/instructions-and-memory/
Section: Kaitoi CLI / Extending Kaitoi Code
Written for: Teams maintaining consistent guidance for Code.
Prerequisites: A trusted workspace
Last reviewed: 2026-10-24

---

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.

*Figure: Specific guidance is loaded within a budget; nested instructions arrive when that area is used.*

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.