Memory & project instructions
Guides

Memory & project instructions

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.

OrderFileScope
1AGENTS.mdProject
2RAYU.mdProject
3.rayu/RAYU.mdProject
4RAYU.local.mdProject, personal (keep out of git)
5~/AGENTS.mdGlobal
6~/.rayu/RAYU.mdGlobal, personal

Two optional overlays append to the system prompt without being instructions in the same sense:

FilePurpose
.rayu/prompt-overlay.mdProject-specific prompt text
~/.rayu/prompt-overlay.mdGlobal 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#

markdown
# 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.

toml
[features]
memory = false   # disable memory retrieval and extraction

Toggle it for one session with /memory on or /memory off.

Inspect and prune the store from the shell:

bash
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.

toml
[features]
memory = true
persist_memory_injections = false
message_timestamps = true      # send timestamps with messages and tool results

Project instructions vs configuration#

Do not confuse these:

You wantPut it in
Rules the model must followAGENTS.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./.rayu/skills/<name>/SKILL.md

Next#

Next: Skills & plugins →