brief

Context Contract

This document defines the contract between brief --agent and brief context. It is the authoritative reference for P2 (brief context implementation) and for anyone extending or calling these interfaces.

Organizing principle

Both --agent and brief context are constitutions — authoritative context packs — but at different scopes:

Command	Scope	Nature
brief --agent	User-scope	Who the agent is and how it should behave across all sessions and environments
brief context	Env-scope	What the agent needs to know about this specific repo, folder, or environment

This scope distinction is the organizing principle for every boundary decision in this document.

brief --agent contract

Scope: User-level. Valid across all sessions, all repos, all environments.

What it owns:

• Behavioral preferences authored by the user
• session_guide — stable tool onboarding (how to use brief)

Stability: Stable API. Callers (~/.claude/CLAUDE.md, scripts, agent runtimes) may depend on this shape without version guards.

JSON shape (current, stable):

{
  "preferences": [{ "title": "...", "content": "..." }],
  "session_guide": "..."
}

What it never contains:

• Source evidence (crawl store chunks)
• Environment- or repo-specific memories
• Dynamic or task-scoped content of any kind

brief context contract

Scope: Env-level. Scoped to a specific repo, folder, or environment.

What it owns:

• Memories surfaced by recency (recent mode) or query relevance (find mode) — not path-filtered (from the entries store)
• Source evidence scoped to the nearest indexed source containing --cwd (from the crawl store)
• Preferences naturally surfaced alongside memories, if any exist in brief

Stability: Evolving surface. brief context is where the context lifecycle matures. --agent is the stable anchor.

JSON shape (contract for P2 to implement against):

{
  "scope": "<resolved path or env identifier>",
  "memories": [],
  "sources": [],
  "preferences": []
}

• scope — the resolved path or env identifier this pack is scoped to
• memories — relevant entries (non-preference categories) from the entries store for this env
• sources — indexed source chunks from the crawl store for this env
• preferences — preference entries naturally surfaced by the env-scoped search; not the full --agent set; may be empty

Preferences in context: Preferences appear in brief context as a result of natural function — they are entries like any other, and if they are relevant to the env scope, they surface. This is not an opt-in flag. It is different from the user-global preference set returned by --agent.

Empty sections (memories, sources, preferences) are always present as empty arrays, never omitted.

Boundary rules

These are prohibitions, not suggestions:

1. --agent never includes source evidence or env-specific memories.
2. brief context never replicates the full --agent preference set; only preferences naturally relevant to this environment appear.
3. Memory and source evidence are never blended into a single ranked list; memories and sources remain separate keys.
4. session_guide stays in --agent until its long-term placement is resolved in a future scope. It does not belong in brief context responses.

Five resolved questions

Question	Resolution
What remains in --agent?	User-scope constitution: behavioral preferences and session_guide. Stable. Valid for any session, any repo.
What does brief context own?	Env-scope constitution: memories, source evidence, and env-relevant preferences for the current repo/folder/env.
Can context include preferences?	Yes — as a natural function, not an opt-in flag. Preference entries surface when they are relevant to the env scope, just as memories do.
Where does session_guide belong long-term?	Deferred. Currently lives in --agent. Long-term placement is out of scope for P1.
Is --agent stable API or eventually a compatibility alias?	Stable now. Post-maturation (after preference maturation primitives exist), --agent may become a shortcut to its equivalent context call. The binding form is not decided here.

Implementation notes for P2

• brief --agent is implemented in internal/cli/onboard.go (runOnboarding, agentOnboardPayload). Do not modify its shape.
• brief context is a new command: internal/cli/context.go, registered under the memory group in internal/cli/root.go.
• The scope field resolves to the path passed via --cwd (default: current working directory).
• memories and preferences both come from the entries store (internal/db/entries.go, SearchEntries) — filtered by category to separate them.
• sources comes from the crawl store (internal/db/crawl.go, SearchChunks) scoped to the nearest indexed source containing --cwd.
• The embed backend is resolved once and passed to both memory and source search paths.
• Resolve the --cwd → source path mapping via ListSources() using longest-prefix matching.
• Related: #49 (original brief context proposal), #48 (unified search scope), #39.