brief

Claude Code Integration

This guide shows how to wire brief into Claude Code so the agent carries your preferences and memory across sessions.

How it works

Claude Code reads CLAUDE.md files as persistent agent instructions. By adding a brief section to your CLAUDE.md, you tell the agent to load your preferences at session start and query brief on demand throughout the session.

brief --agent returns your preferences as JSON:

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

The agent consumes this at the start of a session. From that point, it can query brief find whenever it needs specific context, and save new lessons or decisions before the session ends.

Where to place CLAUDE.md

Location Scope
~/.claude/CLAUDE.md All Claude Code sessions on this machine
CLAUDE.md (repo root) or .claude/CLAUDE.md One project only

For brief, the global location (~/.claude/CLAUDE.md) is the right fit — brief is a cross-project, cross-session tool. A per-project CLAUDE.md can supplement it with repo-specific instructions.

Minimal CLAUDE.md shape

The following is a proven minimal shape. Paste it into ~/.claude/CLAUDE.md and adapt it.

## brief — On-Demand Knowledge Store

`brief` is your persistent memory layer. Query it scoped to the current task.
At session start, run `brief --agent` to load preferences as JSON.

### Query patterns

    brief find "<topic>" --category preference --json   # preference lookup
    brief find "<query>" --json                         # full-text search
    brief find --id <id>                                # single entry, full content

### Rules

- Query `brief` before asking the user a question that memory might answer
- Do not duplicate brief entries into session memory or any secondary store
- brief is the source of truth — trust it over assumptions
- Save lessons, decisions, and preferences to brief before the session ends

What brief owns vs. what Claude Code owns

brief Claude Code
Preferences, decisions, lessons, workflows, snippets Tool permissions (settings.json)
Cross-session persistent memory Hooks and automation
Cross-LLM portable context (any agent that can run a shell command) IDE keybindings and settings
Source of truth for user preferences and past decisions Model selection and session behavior

brief entries are yours — they travel across sessions, across LLMs, and across machines via a portable SQLite file. Claude Code settings are local to a machine or project.

Authoring preferences for --agent

brief --agent loads entries that match both category=preference and tag=onboard:

brief save \
  --title "Always check brief before asking" \
  --category preference \
  --tag onboard \
  "Query brief find before asking me a question that memory might answer."

The --tag onboard is required. Without it, the entry only appears in --agent via the fallback path, which loads preferences that have no tags at all. A preference tagged with anything other than onboard (e.g. --tag work) is excluded from both the primary and fallback load. Tag every preference you want reliably loaded at session start with --tag onboard.

--agent is capped at default_limit entries (default: 10). Keep preferences focused — one clear behavioral rule per entry.

To review what --agent will load before an agent session:

brief --user

Integration status

Agent Status Notes
Claude Code Validated This guide.
Codex Planned — discovery Integration shape not yet validated.
Cursor Planned — discovery Integration shape not yet validated.
Shell hooks Planned — discovery Integration shape not yet validated.

Each planned integration requires independent validation before documentation. No broad agent support is implied.