CLI Reference

The braingent command is the public API for creating, checking, searching, updating, and serving a Braingent memory repo.

Run commands from the memory repo root, or pass --root /path/to/repo.

braingent --help
braingent --root ~/Documents/repos/braingent doctor

Install

pipx install braingent          # or: uv tool install braingent
braingent --version

Optional extras: braingent[mcp] (MCP retrieval server, also installs the braingent-mcp command) and braingent[tokens] (token-count helpers). Combine as braingent[mcp,tokens].

pipx install "braingent[mcp]"   # add --force to add the extra to an existing install

braingent init

Create a new memory repo from the packaged starter template.

braingent init ~/Documents/repos/braingent
braingent init ~/Documents/repos/braingent --dry-run
braingent init ~/Documents/repos/braingent --force

Flag	Description
--dry-run	Show what would be copied.
--force	Allow copying into a non-empty target.

braingent update

Update starter template files in an existing memory repo.

braingent update ~/Documents/repos/braingent --dry-run
braingent update ~/Documents/repos/braingent --write
braingent update ~/Documents/repos/braingent --write --force

Flag	Description
--dry-run	Show add/update/conflict counts without writing.
--write	Apply non-conflicting updates.
--force	Overwrite conflicted template files when used with --write.

braingent doctor

Report memory-repo health: missing entrypoints, placeholder leftovers, frontmatter issues, stale indexes, possible private paths, possible secrets, and stale records.

braingent doctor
braingent doctor --json
braingent doctor --strict

Flag	Description
--json	Emit the report as JSON.
--strict	Exit non-zero when warnings are present.
--stale-days <n>	Age threshold for stale profile/learning records. Default 180.

braingent validate

Validate record frontmatter against preferences/taxonomy.yml.

braingent validate
braingent validate orgs/org--example/projects/project--example--memory/records/example.md

Arguments are optional Markdown paths. With no paths, the whole repo is validated.

braingent reindex

Regenerate derived indexes under indexes/ and .braingent.db.

braingent reindex
braingent reindex --check

Flag	Description
--check	Fail if generated indexes are stale, without writing changes.
--dashboard-e2e	Also run dashboard checks when the dashboard exists.

braingent find

Search durable records by structured frontmatter filters.

braingent find kind=decision
braingent find repo=repo--example--owner--repo status=active --limit 5
braingent find q="pagination state" --json

Flag / Argument	Description
key=value	Filter by frontmatter or body text. Common keys: kind, org, project, repo, topic, tool, ticket, status, q.
--json	Emit JSON.
--paths	Emit only matching paths.
--count	Emit only the result count.
--limit <n>	Limit result count.
--epic <slug>	Only records tagged with one epic. Takes a slug or a full epic--<org>--<slug> id.

braingent recall

Build a focused context pack for an agent before planning or implementation.

braingent recall repo=repo--example--owner--repo
braingent recall ticket=ACME-123 --json

Flag / Argument	Description
key=value	Same filter style as find.
--json	Emit JSON.
--limit <n>	Number of must_read records. Default 8.
--stale-days <n>	Staleness threshold. Default 180.
--epic <slug>	Only records tagged with one epic.

braingent qa generate

Generate a strict QA plan from ticket + memory + optional Gather Step evidence. See QA Test Planning.

braingent qa generate \
  --ticket-key ACME-1492 \
  --evidence-pack ./build/qa-evidence.json \
  --emit-format markdown \
  --output ./qa-plans/ACME-1492.md \
  ./tickets/ACME-1492.md

Flag	Description
<ticket-path-or-inline-ticket-text>	Source ticket text or path. Required.
--ticket-key <key>	Ticket key used in the output title and filename.
--allow-missing-ac	Allow product-intent-derived REQ-* cases when explicit AC is missing.
--source <path-or-text>	Supporting spec, PRD, note, design source, or pasted text. Repeatable.
--implementation-state <state>	pre-implementation, in-progress, or post-implementation.
--no-diff	Skip white-box implementation evidence.
--diff <base..head>	Diff range for implementation evidence.
--gather-workspace <path>	Workspace where Gather Step should run.
--gather-target <target>	Symbol, route, or event target for Gather Step.
--projection-target <target>	Optional field/contract target for projection impact evidence.
--evidence-pack <path>	Existing qa-evidence.v1 manifest.
--budget-tokens <n>	Default 160000.
--emit-format <fmt>	markdown, xray-json, testrail-csv, or gherkin.
--output <path>	Explicit output path.
--output-dir <path>	Output directory. Defaults to .test-plans/.
--repo, --project, --topic, --tool	Braingent memory filters.
--print	Print generated output after writing it.

braingent synthesize

Generate a source-indexed synthesis page from records.

braingent synthesize --topic topic--ai-memory
braingent synthesize --repo repo--example--owner--repo
braingent synthesize --project project--example--memory
braingent synthesize --epic checkout-latency

Exactly one of --topic, --repo, --project, or --epic is required. An epic synthesis also lists the epic’s config ledger.

braingent factcheck

Audit research records for source credibility and unsourced claims. Read-only: it makes no network calls and no edits. It does the mechanical part of fact-checking so a human or AI reviewer spends effort only on judgment (does this source support this claim?).

braingent factcheck path/to/report.md   # audit one record
braingent factcheck --all                # audit every in-scope record
braingent factcheck --next               # print the next unverified record path
braingent factcheck --all --json         # machine-readable punch-list

A record is in scope when it carries a verification frontmatter field or when its topics intersect [factcheck] scope_topics in config. The audit tiers each cited source (slop / PR-wire / tier-1-2 / primary-or-other) using the configured domain lists, flags [UNVERIFIED] and [SINGLE-SOURCE] markers, and lists unsourced list bullets. Numbered lists and prose paragraphs are out of scope. Citations are GFM footnote definitions ([^id]: URL); a [^id] marker on a claim line counts it as sourced only when that id has a definition. Domain tiers match the host and its subdomains (uk.reuters.com counts as reuters.com).

Exit codes: 0 if the audit is mechanically clean, 1 if any item still needs judgment (or --next finds nothing), 2 for usage or a missing file.

Configure the tiers under [factcheck] (see the configuration reference).

Live Task Commands

Coordinate optional live BGT-NNNN task files under tasks/.

Command	Purpose
braingent task-new "<title>"	Create a live task.
braingent task-claim BGT-0001 --as agent--codex-cli	Claim a task.
braingent task-comment BGT-0001 "note" --as agent--codex-cli	Append activity.
braingent task-status BGT-0001 in-review --as agent--codex-cli	Change status.
braingent task-list	List live and archived tasks.
braingent task-list --count	Print status counts.
braingent task-archive BGT-0001 --resolution completed --as agent--codex-cli	Close and archive.

Epic Commands

An epic groups work across tickets and repositories. See STRUCTURE.md for the page layout and the config-to-enable/v1 block format.

config-ledger trusts PRs by the active GitHub account (@me) by default. Use repeatable --author options or [config_ledger] authors to select trusted authors. Closed, unmerged PRs are excluded. Values longer than 300 characters are rejected, and reaching the search limit stops collection before any sync.

Command	Purpose
braingent new epic --org acme --slug checkout-latency [--title "<text>"] [--parent <slug>]	Create orgs/org--acme/epics/epic--acme--checkout-latency/README.md from templates/epic.md.
braingent config-ledger --epic checkout-latency --owner acme	Merge config-to-enable/v1 blocks from PRs labelled epic:checkout-latency (via gh search prs) with the epic page ledger and print the table. Repeat --owner for several owners, add --json for machine output.
braingent config-ledger --epic checkout-latency --owner acme --sync	Also rewrite the page’s ## Config to enable section, after saving the page as README.md.bak. Other sections are untouched.
braingent config-drift --contracts <dir> --deployed <dir> [--json]	Compare per-service JSON environment contracts with a deployed mirror. Reports keys missing on either side and exits non-zero on drift. Defaults may be set under [config_drift] in .braingent/config.toml.

braingent reindex also generates indexes/epics.md and indexes/config-ledger.md, and fails validation when a record names an epic that does not exist.

Daily Log Commands

Record what every agent did today in daily/YYYY-MM-DD.md. See the Daily Log guide.

Command	Purpose
braingent daily-log started "<text>" --ref EX-1 --as agent--claude-code	Append an event. Kinds: todo, started, review, blocked, done, dropped, spawned, note.
braingent daily-log note "<text>" --as agent--codex-cli --date 2026-10-05	Log against another day.
braingent daily-log spawned "<text>" --ref app#202 --epic db-audit --as agent--claude-code	Tag an event with an epic. The status block adds a per-epic roll-up.
braingent daily-status	Regenerate the status block and print counts plus the sprawl flag.
braingent daily-status --json	Machine-readable summary for a PM agent.
braingent daily-status --path	Print the day file path.

The first write of a day creates the file and carries over the previous day’s unfinished items. Writes take a file lock, so concurrent agents are safe.

Weekly Plan Commands

Keep a human-written plan for the week in weekly/YYYY-Www.md. See the Weekly Plan guide.

Command	Purpose
braingent weekly	Create this week’s file if needed, regenerate its progress block, and print priorities, notes and not-this-week.
braingent weekly --json	Machine-readable plan and progress for an agent.
braingent weekly --path	Print the week file path.
braingent weekly-add "<text>" --section priorities	Append an item. Sections: priorities, notes (default), not-this-week.
braingent weekly --date 2026-10-14	Select the week that contains that day. Works on both commands.

A new week’s file carries over last week’s unticked priorities and notes.

MCP Server

Expose token-efficient retrieval tools to MCP-aware agents. Requires the braingent[mcp] extra.

braingent mcp serve --path ~/Documents/repos/braingent
# equivalent dedicated entrypoint:
braingent-mcp --path ~/Documents/repos/braingent

Tools:

• braingent_guide()
• braingent_find(query, limit)
• braingent_get(path, depth)

Point your agent’s MCP config at braingent mcp serve --path <memory-repo>.