Braingent
Search
Before planning, the agent reads the memory repo — prior records, decisions, repo profiles, known risks.
A Manifesto for AI-Assisted Engineering
A Shared Memory for AI-Assisted Engineering.
Braingent is a Git-backed, Markdown-first memory repo. It gives Claude, Codex, ChatGPT, and Gemini CLI the same engineering context — what to read before planning, which decisions matter, and what work is already underway.
The Problem
Agents Forget. Engineers Repeat. Decisions Vanish.
Agents start every session from zero.
Even capable models have no idea what your repo looked like yesterday, what you decided last sprint, or which approach you already tried and rejected.
You re-explain the same context, again.
Architecture, conventions, constraints, that one weird quirk in the deployment script. Pasted into a fresh chat. Lost the moment it closes.
Decisions disappear into chat logs.
The reasoning behind a non-obvious choice — buried somewhere between message #47 and a tangent about TypeScript generics. Unsearchable, uncitable, gone.
Every tool wants its own walled garden.
Memory you can't read, can't diff, can't move. Tied to one vendor's roadmap and one vendor's outage.
The Loop
Search. Work. Capture. Better Next Session.
Work
You and the agent ship like normal. Evidence, commands, tradeoffs and links accrue along the way.
Capture
Say capture this or task done. The agent writes a durable Markdown record and commits it.
Inherit
Future sessions — and future agents — search that memory first instead of starting from zero.
Records
Markdown Is the Source of Truth.
Plain files. YAML frontmatter for search. Git for history. Nothing your editor can't open and your eyes can't read.
- Eight record kinds — tasks, decisions, reviews, learnings, profiles, versions, summaries, ticket stubs.
- Five memory surfaces — pinned context, durable records, derived retrieval, live
BGT-NNNNtasks, optional dashboard. - Indexes, search, and MCP retrieval all derive from the same Markdown.
- No server. No vendor lock-in. No hosted account.
memory/decisions/2026-04-12-jobs-runtime.md--- id: DEC-0218 title: Move job runtime from BullMQ to Temporal status: accepted date: 2026-04-12 authors: [jj, claude] tags: [runtime, jobs, reliability] supersedes: DEC-0091 --- # Move job runtime from BullMQ to Temporal ## Context We hit a third silent retry loop in two weeks. # incident link BullMQ's failure model doesn't survive process churn on Fly.io. ## Decision Adopt Temporal. Migrate `billing` first, `webhooks` second. ## Consequences + Durable workflows, deterministic replay - Operator must run a Temporal cluster (1 dev, 1 prod) - 2-week migration, freeze new BullMQ jobs starting 2026-04-15
memory/tasks/BGT-0142.md--- id: BGT-0142 title: Backfill repo profile for `acme/api` status: in_progress priority: P2 owner: claude depends_on: [BGT-0138] created: 2026-04-28T09:14Z --- ## Goal Generate `repos/acme-api/profile.md` from local docs, git history, and open PRs. ## Activity - 2026-04-28 09:14 claude — opened, scanned README + ADRs - 2026-04-28 09:31 claude — drafted profile, 14 sections - 2026-04-28 10:02 jj — flagged auth section as stale - 2026-04-28 10:18 claude — re-read `auth/*`, rewrote section
CLAUDE.md · agent entrypoint# Braingent entrypoint for Claude You are working inside a repo that is paired with a **Braingent** memory repo at ../braingent. ## Before you plan 1. Read ../braingent/preferences/*.md 2. Search ../braingent/decisions/ and ../braingent/learnings/ for this area 3. Check ../braingent/repos/<name>/profile.md ## When the user says "capture this" - Write to ../braingent/<type>/<slug>.md - Include YAML frontmatter (id, title, status, date, tags) - Commit with message: capture: <slug> ## Never store secrets, tokens, credentials, raw chat transcripts, or sensitive personal data. Ever.
Privacy & Portability
Yours. Local. In Files You Can Read, Diff, and Move.
What Braingent Stores
Durable, intentional, human-readable. Things worth keeping for next time.
- Decisions and their reasoning
- Reviews, learnings, and follow-ups
- Repo profiles and tool notes
- Standing preferences and workflows
- Active task files (optional)
What It Never Touches
If it shouldn't sit on disk in plain text, it doesn't belong here.
- Secrets, API keys, tokens
- Credentials of any kind
- Raw chat transcripts
- Sensitive personal data
- Anything you wouldn't commit to a repo
What It Isn't
A Clear-Eyed List of Things Braingent Is Not.
i.
Not a Hosted SaaS.
Your memory lives in your repo. No accounts, no dashboards behind a login.
ii.
Not a Git Replacement.
Braingent runs on top of Git. History, diffs, sync, review — Git already does that.
iii.
Not a Project Manager.
Live tasks are optional. Linear, Jira, GitHub Issues stay where they are.
iv.
Not a Chat Archive.
Records are the durable signal. Full transcripts don't belong on disk.
v.
Not Vendor-Bound.
Markdown reads in any editor. Any agent. Any future tool you'll use in five years.
vi.
Not a Hosted Index.
The filesystem is the index. Optional local search and dashboards stay local to your machine.
Get Started
Four Steps. Roughly Ten Minutes.
Copy the starter pack, point your agent at it, capture your first task. From there, your memory grows on its own.
i.
Clone the Manifesto
Public, open source. Markdown only — no install required to read it.
ii.
Copy the Starter Pack Into Your Private Memory Repo
Preferences, templates, workflows, and an empty records tree. Personalize the placeholders, then commit.
iii.
Wire Up Your Agents
Drop entrypoints into the memory repo root. Works with Claude, Codex, ChatGPT, and Gemini CLI.
iv.
Capture Your First Task
Finish a piece of work, then say it. The agent writes a durable record and commits it.
Features
A Small CLI Today. Durable QA From Your History Tomorrow.
Health Checks
Reports missing files, stale placeholders, malformed frontmatter, and generated-index drift before agents trip on them.
Structured Search
Filter records by topic, repo, project, ticket, kind, status, person, or tool. Frontmatter is the index.
Focused Context Packs
Build a small, citation-ready context pack for one task instead of rereading the whole memory repo.
Live Task Coordination
Create, claim, comment, status, list, and archive BGT-NNNN tasks across multi-agent work — all just Markdown.
Source-Indexed Synthesis
Generate synthesis pages from your records — every claim cited back to the Markdown it came from.
Optional Local Dashboard
Read-only Bun + Astro UI over tasks/active/ and indexes. Agents and humans see the same live queue.
Zero-Friction Setup
Copy the starter pack, replace placeholders, ask one-time setup questions. Markdown stays the source of truth.
Safe Starter-Pack Upgrades
Compare versions, show the patch plan, never overwrite your edits without an explicit diff.
Test Cases From Your Engineering History
Derive durable QA test-case records from prior decisions, learnings, and bug captures. Your agent's memory becomes a reusable test plan — Markdown in, Markdown out.
✦ ✦ ✦