25. Memory & project instructions#
Rayu reads standing instructions at the start of every session, before you type
anything. They are how you stop repeating yourself: "we use pnpm, not npm", "a
single test runs with cargo test -p foo bar", "migrations need a database on
5434".
There are two systems:
- Instruction files — markdown you write. Rayu reads them in full and treats them as overriding instructions.
- Auto-memory — a per-project store Rayu writes for itself as you work, which you review and prune.
Instruction files#
v3 loads these, in this order. Later files add to earlier ones; when two disagree, the later one wins.
| Order | File | Scope |
|---|---|---|
| 1 | AGENTS.md | Project |
| 2 | RAYU.md | Project |
| 3 | .rayu/RAYU.md | Project |
| 4 | RAYU.local.md | Project, personal (keep out of git) |
| 5 | ~/AGENTS.md | Global |
| 6 | ~/.rayu/RAYU.md | Global, personal |
Two optional overlays append to the system prompt without being instructions in the same sense:
| File | Purpose |
|---|---|
.rayu/prompt-overlay.md | Project-specific prompt text |
~/ | Global prompt text |
Files are deduplicated by canonical path, so a symlink cannot load the same content twice.
What belongs in them#
- Non-obvious build, lint and test commands, especially single-test commands.
- Architecture that takes several files to understand.
- Repo etiquette: branch names, commit style, required env vars.
- Short, specific style rules that differ from the language defaults.
Leave out what Rayu can discover: directory listings, standard commands, generic advice. A long instruction file costs tokens every turn and receives less attention.
Example#
# AGENTS.md
## Build
- `cargo build --locked --bin rayu` builds the CLI.
- `cargo check -p rayucode-tui --lib` is the fast inner loop for TUI work.
- Never run the whole workspace test suite; name the crate.
## Style
- No `unwrap()` in library code.
- Keep public functions documented with one sentence.
## Do not touch
- `vendor/` is a vendored crate tree.Auto-memory#
Auto-memory is a per-project store of notes Rayu keeps about you: which commands
worked, which files matter, what you corrected it on. It lives under
~/.rayu/memory, is loaded selectively, and can be turned off.
[features]
memory = false # disable memory retrieval and extractionToggle it for one session with /memory on or /memory off.
Inspect and prune the store from the shell:
rayu memory stats
rayu memory list -s project
rayu memory list -s global -t build
rayu memory search "test command"
rayu memory export memories.json -s all
rayu memory import memories.json -s project/skills is unrelated, but /initiatives tracks longer-running goals the agent
keeps across sessions.
Memory and the model#
Memory is injected as a request-only suffix by default, so it does not pollute
your transcript. Set persist_memory_injections = true if you want recalled
memory to be part of the recorded conversation.
[features]
memory = true
persist_memory_injections = false
message_timestamps = true # send timestamps with messages and tool resultsProject instructions vs configuration#
Do not confuse these:
| You want | Put it in |
|---|---|
| Rules the model must follow | AGENTS.md / RAYU.md |
| TUI behaviour, hooks, tool exposure | ~/.rayu/config.toml |
| MCP servers for this repo | ./.mcp.json or ./.rayu/mcp.json |
| Skills for this repo | . |
Next#
Next: Skills & plugins →