Context library

An agent that has to rediscover your architecture every conversation will keep making the same wrong guesses. The context library is the fix: a folder of Markdown in your repo that agents read — conventions, domain vocabulary, the reasoning behind decisions the code can’t explain.

Write it once, commit it, and stop pasting the same paragraphs into every chat.

Where it lives

Markdown files under .raven/context/ in the project, at any depth:

.raven/
  context/
    architecture.md
    api-conventions.md
    deploy/
      runbook.md
  config.json

Folders go one level deep. It’s committed alongside the code, and that’s the point. The docs are versioned with the thing they describe, they travel with the repo to everyone on the team, and a branch that changes the architecture can update the notes in the same commit.

Because it’s read from the workspace’s own checkout, what you see is the context on that branch — exactly like every other file in the workspace.

Reading and loading

The Context library surface in the right panel (⌘⇧E) browses the library with a built-in reader. It keeps its own reader, separate from Files, so opening a context doc doesn’t lose your place in the file tree. Folders open collapsed; Expand all on the root row opens them.

To pull a doc into a conversation by hand, @-mention it in the composer the way you would a file. Docs the current chat has loaded are tagged Active, and the transcript shows an Attached N docs from context row at the start of a chat that loaded any.

The agent writes here too. In Build mode it can create or update a context doc — when you settle a convention in conversation, ask it to save one — and the result shows as a card in the chat. Docs it creates load on mention until you say otherwise.

You can write here as well: the right-click menu has New doc, New folder (on the library root), Rename…, Delete, Reveal in Finder, and Copy reference or Copy path for pasting into a chat.

Always, or on mention

Some docs you want in every conversation without asking for them. Each doc — or each folder — carries a dial with three settings, set from the right-click menu — Loads upon… on a doc, Files here load upon… on a folder or the library root:

Setting	Behavior
Always	Loaded at the start of every new conversation in this project.
Mention-only	Available to @-mention, but never loaded on its own.
Inherit	Take whatever the enclosing folder says. This is the default.

Resolution walks outward: the doc’s own setting wins, then its folders from the inside out, then the setting on the library root. If nothing anywhere has an opinion, the doc is mention-only. That means you can set one folder to Always and everything you drop in it is loaded from then on, without touching each file.

The Inherit option in the menu spells out what it currently resolves to, and a doc or folder set to Always wears that tag in the tree. One exception to “every new conversation”: when a chat’s first message is a CLI slash command such as /compact, the Always docs wait for the first ordinary turn.

The config file

Dials live in .raven/config.json, beside the context folder:

{
  "context": {
    "default": "mention-only",
    "paths": {
      "architecture.md": "always",
      "deploy/": "mention-only"
    }
  }
}

Only deviations are written — an inherited doc has no entry at all. Paths are relative to .raven/context, and a trailing slash marks a folder.

Because the file is committed, dials are a project decision rather than a personal preference: everyone on the team gets the same starting context. There’s no per-user override layer.

If the file is malformed, Raven tells you exactly what’s wrong — a banner in the surface names the file and the error, and says no context loads for the project until it parses — and loads nothing. It won’t fall back to an empty config and let you believe docs are loading when they aren’t.

What to put in it

Things that stay true across conversations and are expensive to re-derive:

• How the system is put together, and why it’s put together that way.
• Conventions an agent would otherwise infer from whichever files it happened to read.
• Domain vocabulary — what your nouns actually mean in this codebase.
• Runbooks and procedures where the order of steps matters.
• A design board’s decisions — Raven pairs each board with a doc under designs/, so the reasoning behind a mockup is there when it’s built.

What not to put in it: anything the code already says. An agent can read the code. What it can’t read is the decision you made two years ago about why the code looks like that.

Keep the Always set small. Everything in it costs context on every single conversation, whether or not that conversation needed it — and a context window spent on background is a context window not spent on the work.