Braingent

Core Concepts

Record Kinds

The record kinds Braingent uses, what each one contains, and when to write each.

Braingent recognizes durable record kinds plus a live agent-task kind. Each has a directory, a template, a frontmatter shape, and a clear answer to when do I write one of these?

This page is the field guide.

At a glance

Records cluster by context (the project, repo, topic, or tool they belong to), not by kind. The record_kind: frontmatter field is what discriminates them. So a decision about acme/api lives in repositories/repo--acme--api/ next to that repo’s reviews and learnings — not in a separate top-level decisions/ directory.

Kind record_kind: Lives in Write when
Task (durable) task tasks/archive/ or context dir A piece of work is finished.
Live agent-task agent-task tasks/active/BGT-NNNN.md Multi-agent coordination is in flight.
Decision decision The relevant context dir (repo / project / topic) A non-obvious choice is made.
Review review The relevant context dir A PR or code review surfaces something durable.
Learning learning The relevant context dir A reusable lesson is identified.
Profile profile repositories/<repo-slug>/README.md or another entity README A repo, org, project, or topic needs current local context.
Version note version tools/<tool-slug>/records/ A tool upgrade has gotchas worth remembering.
Summary summary imports/summaries/ or a context records dir An import or batch needs a compact durable summary.
Ticket stub ticket-stub tickets/ticket--<source>--<id>/ An upstream ticket needs a home in memory.
Interaction interaction people/ or a context records dir A stakeholder exchange changes future work.
Note note inbox/ or a context records dir Temporary or mixed context does not fit yet.

I. Task records

Tasks capture the what was done: the goal, what changed, evidence, follow-ups.

---
id: BGT-0142
record_kind: agent-task
title: Backfill repo profile for acme/api
status: in-progress
status_category: active
priority: high
claimed_by: agent--claude-code
repositories: [repo--acme--api]
project: project--acme--platform
topics: [topic--repo-profiles]
created: 2026-04-28
closed: null
---

## Description
Generate `repos/acme-api/profile.md` from local docs, git history, open PRs.

## Activity
- Scanned README + ADRs (3 ADRs surfaced).
- Drafted profile, 14 sections.
- jj flagged auth section as stale; rewrote.

## Evidence
- PR #428: https://github.com/acme/api/pull/428
- Reindex output: `indexes/recent.md` updated.

## Follow-ups
- BGT-0145 — refresh `tools/sqlite-3.46.md` based on this work.

Write when: a piece of work is shippable, even small. PRs opened, fixes landed, refactors merged, decisions reached.

II. Decision records

Decision records capture the choice, the context, and the consequences. They live forever and supersede each other rather than getting deleted.

---
id: DEC-0218
record_kind: decision
title: Move job runtime from BullMQ to Temporal
status: accepted        # proposed | accepted | rejected | superseded
date: 2026-04-12
authors: [jj, claude]
tags: [runtime, jobs, reliability]
supersedes: DEC-0091
---

Write when: you choose between two or more reasonable options, and the choice is non-obvious enough that future-you might want to revisit it. Don’t write a decision record for “we used let instead of const here”; do write one for “we picked Temporal over BullMQ”.

III. Review records

Code review and PR review notes that surface durable signal.

---
id: REV-2026-04-28-jobs-runtime-pr
record_kind: review
title: PR #428 review — Temporal migration first slice
date: 2026-04-28
reviewer: jj
repositories: [repo--acme--api]
links: [decisions/2026-04-12-jobs-runtime.md, tasks/archive/BGT-0142.md]
tags: [temporal, jobs, pr-review]
---

Write when: the review surfaced a tradeoff, a missed case, or a pattern worth re-applying. Skip it for routine “looks good, ship it” reviews.

IV. Learning records

Reusable lessons not tied to a single repo. The shape that travels.

---
id: LRN-2026-04-bullmq-process-churn
record_kind: learning
title: BullMQ silent retries under process churn
date: 2026-04-12
topics: [topic--jobs, topic--reliability]
tools: [tool--bullmq, tool--fly-io]
repositories: [repo--acme--api]
---

Write when: the same lesson would apply if you encountered the problem in a different repo. Repo-specific gotchas go in the repo profile, not here.

V. Repository profiles

One file per repo: local conventions, build commands, gotchas, hot files, agent guidance.

---
id: repo-acme-api
record_kind: profile
title: acme/api
status: active
repo: repo--acme--api
organization: org--acme
project: project--acme--platform
last_reviewed: 2026-04-28
primary_languages: [typescript, sql]
topics: [topic--jobs]
tools: [tool--sqlite]
---

Write when: an agent will work in this repo more than once. The profile saves you re-explaining the layout next time.

VI. Project briefs

One file per project: goal, stakeholders, current phase, key decisions.

---
id: proj-acme-platform
record_kind: profile
title: acme-platform
status: active
organization: org--acme
project: project--acme--platform
repo: null
repositories: [repo--acme--api, repo--acme--web, repo--acme--jobs]
last_reviewed: 2026-04-28
---

Write when: a piece of work spans more than one repo, or has stakeholders beyond the immediate engineering team.

VII. Topic pages

Cross-cutting synthesis. Auth across all repos. The migration playbook. The “we always do X for Y” pattern.

---
id: topic-auth
record_kind: profile
title: Authentication across acme repos
status: active
topic: topic--auth
organization: null
project: null
repo: null
repositories: [repo--acme--api, repo--acme--web, repo--acme--jobs, repo--acme--admin]
last_reviewed: 2026-04-30
---

Write when: you find yourself explaining the same cross-cutting topic in two different sessions. Promote it.

VIII. Tool / version notes

Quirks tied to a specific tool version. Especially useful for upgrades.

---
id: tool-sqlite-3.46
record_kind: version
title: SQLite 3.46 upgrade notes
status: active
tool: tool--sqlite
version: '3.46'
date: 2026-04-15
scope: upgrade
source_of_truth: release notes
last_checked: 2026-04-15
repositories: [repo--acme--api]
---

Write when: a tool’s behavior changed in a way that broke (or unblocked) something. Save the next person the half-day of debugging.

How records reference each other

Two mechanisms:

  1. links: in frontmatter — for retrieval and graph queries.
  2. Markdown links in the body — for prose context.

A well-linked record has both. Frontmatter links are how braingent_find and braingent recall use for retrieval; Markdown links are how a human reading the page gets to the next thing.

Where to go next