All projects

pi-brain

Makes agents read your decisions before they edit, and keeps a person in charge of what they learn.

Set this up in your teamSource on GitHubnpm

Role

Author and maintainer

What

A package for pi: a knowledge base per project or client, in its own clone

Releases

9 on npm, July to September 2026; 0.5.1 is the latest

License

MIT

$ git log --follow -- wiki/muhamed.github.io/adrs/project-profile-pages.md

a831a16 projects: profile pages for enola, enola-guides and Usput.ba
41eceaa wiki: project profile ADR draft takes the owner's answers on repositories
d1293af wiki: revise project profile ADR draft (projects URLs, video, brain, enola-guides)
01b5101 wiki: draft ADR for project profile pages

The decision behind the project pages on this site: drafted by the agent as a suggestion, revised with my answers, approved by me, and built in the same commit that moved it to the approved shelf.

Agents implement first. For some decisions, that is wrong.

Ask a coding agent to change the layout of a repository and it starts moving files. Nobody wrote down why, nobody agreed to it, and the next agent cannot tell a decision from an accident.

pi-brain keeps a project’s decisions, architecture and product reasoning next to the code, as a clone of its own, and makes the agent ask before the changes that matter. Raw drafts never become truth without human approval.

What it does.

1. Stop and shape.

   A structural change waits for an approved decision record. The agent drafts it, says “this looks structural”, and stops. Only after a person approves it does the agent move the record to the approved shelf, build, and write a record of what shipped.

   wiki/muhamed.github.io/constraints/adr-before-structural-changes.md

   ---
   kind: constraint
   status: active
   severity: must
   ---
   
   # Constraint — ADR before structural changes
   
   Any structural change to this pi-brain home or the maintained project
   repository MUST have an approved ADR before implementation begins.

2. Checked, every commit.

   brain_sync validates every page and rebuilds the index, before each commit. Links are graphed for orphans and dead ends. Nothing runs a model on a schedule.

   $ node tools/brain-sync.mjs && node tools/brain-links.mjs (on a copy of this site)

   Regenerated wiki/index.md with 70 pages across 16 kinds.
   Link graph: 70 nodes, 389 edges
   Orphans: 0, Hubs: 63, Dead links: 3, Suggestions: 21

• Agents draft. People promote.

  Knowledge moves from the inbox to a suggestion, a draft, an accepted decision, its implementation and a record. Agents may only write suggestions. What an agent writes starts at confidence: low and cannot promote itself to high in the same change.

• Forty-four commands, enola built in.

  /brain:shape, /brain:continue, /brain:investigate, /brain:tend and forty more, plus nineteen tools for the agent. With enola switched on, fifteen /brain:enola-* commands check changes, keep receipts, and record verdicts on findings; since 0.5.0 the first write into a repository is held once to show the decisions that govern it.

• This site runs on it.

  muhamed.at is a pi-brain clone: twelve decision records, records of what shipped, a must-constraint on structural changes, and a log line for every change. The wiki is public, so you can read how every page on this site was decided.

What it shows about how I work.

I let agents do the work and keep people in charge of what is true. pi-brain is that rule made into a tool: it slows the agent down exactly where a decision is being made, and nowhere else.

How I work with knowledge bases

• Source on GitHubmisabegovic/pi-brain, MIT
• npmpi install @misabegovic/pi-brain
• This site's wikia pi-brain clone, in the open
• How I work with knowledge basesthe practice it belongs to