brAIn

Persistent, layered memory for AI-assisted projects.

brAIn gives your AI tools memory that compounds over time — codebase facts, hard-won lessons, settled decisions, trust calibration, and your explicit corrections. Five memory layers plus a trust ladder. Stored as plain Markdown files in a .brain/ folder, git-backed, human-readable.

Not a vector database. Not a knowledge graph. Not an AI memory product. The lightweight memory substrate your coding tools actually need.

Status

Pre-alpha. The memory engine, CLI, MCP server, trust ladder, effectiveness tracking, configuration, and editor integration are implemented. The PostgreSQL adapter is coming in a future pitch.

Install

macOS and Linux (amd64 or arm64):

curl -fsSL https://raw.githubusercontent.com/luuuc/brain/main/install.sh | sh

The script detects your platform, downloads the matching binary from GitHub Releases, verifies its SHA256 checksum, and installs to /usr/local/bin/brain (or ~/.local/bin/brain if /usr/local/bin is not writable).

Or with Go:

go install github.com/luuuc/brain/cmd/brain@latest

Quick Start

cd your-project
brain init                    # scaffold .brain/ and a commented brain.yml
brain remember "The users table has 12M rows" --domain database --layer fact
brain recall --domain database
brain config                  # what's in effect, and where each value came from

Commit .brain/ to git so your memory travels with the project.

Editor Setup

Everything above is something you have to remember to run, which is the one thing memory should not depend on. To make the loop run by itself:

brain hooks                   # Claude Code: settings.json block, then CLAUDE.md rules
brain hooks --tool cursor     # Cursor: .cursor/rules/brain.mdc

brAIn prints; you paste. It never edits your settings, your CLAUDE.md, or anything else you own — merging into a file you have already customised is not a memory tool's job.

In Claude Code the hook loads your highest-authority memories into every new session, and again after a /clear or a compaction. Compaction is the one that matters most: it is where a correction gets summarised away and the model quietly loses the thing it was told not to do.

The rules cover what no hook can. A hook cannot know which domain you are touching, so per-domain recall, acting on the trust level, and restraint about what gets written down are all instructions to the model rather than automation.

Memories are committed, so they travel with the repository. The hook configuration is per-developer: everyone who clones runs brain hooks once on their own machine.

Configuration

Everything works with no configuration. To change a default, uncomment the relevant line in .brain/brain.yml — brain init generates it with every setting documented at its default value:

trust:
  promote_to_notify: 10       # clean outcomes to leave "ask"
facts:
  stale_after_days: 30
lessons:
  retire_after_streak: 20

Values resolve as built-in defaults, then brain.yml, then BRAIN_* environment variables. brain config shows which layer won for each setting.

How It Works

brAIn stores memories as Markdown files with YAML frontmatter in a .brain/ folder:

.brain/
  facts/
    users-table-12m-rows.md
  lessons/
    payments-race-conditions.md
  decisions/
    camelcase-api-responses.md
  effectiveness/
    persona-kent-beck.md
  corrections/
    2026-04-01-allow-nullable-email.md
  trust/
    trust.yml

Five Memory Layers

Layer	What	Lifetime
Facts	Codebase truths ("Users table has 12M rows")	Stale after 30 days
Lessons	Patterns from repeated events ("Migrations need a maintenance window")	Self-retire after 20 clean outcomes
Decisions	Settled choices ("camelCase for API responses")	Until explicitly revised
Effectiveness	Persona signal tracking (which reviews helped)	Rolling 90-day window
Corrections	Owner overrides ("stop flagging nullable email")	Permanent

Trust Ladder

Per-domain trust that governs AI autonomy:

Level	What happens	How it's earned
ask	Human must approve	Default
notify	Ships, human notified	10 clean outcomes
auto_ship	Ships silently	30 more at notify
full_auto	Full autonomy	100 more at auto_ship

Trust promotes gradually and demotes immediately on failure.

What brAIn Is Not

• Not a vector database. Markdown by default. pgvector is an optional upgrade.
• Not a knowledge graph. Flat files, no edges, no ontology.
• Not a permanent record. Facts go stale, lessons retire. Designed to forget what no longer matters.

Development

make build    # build the binary
make test     # run tests
make lint     # run linters
make ci       # all of the above

License

MIT