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 .astra/context/ in the project, at any depth:

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

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 space’s own checkout, what you see is the context on that branch — exactly like every other file in the space.

Reading and loading

Open the Context tab in the right panel (⌘⇧E) to browse the library with a built-in reader. It keeps its own reader, separate from the Files tab, so opening a context doc doesn’t lose your place in the file tree.

To pull a doc into a conversation by hand, @-mention it in the composer the way you would a file.

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:

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 Context view tags each doc with what it actually resolves to, so “what will this conversation load?” is something you can read rather than work out.

The config file

Dials live in .astra/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 .astra/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, Astra tells you exactly what’s wrong 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.

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.