Project Brain

Per-project, append-only memory for AI coding agents (Cline, Claude Code, etc.)

Project Brain gives your AI agent a durable, searchable memory that persists across sessions and lives in your repo. The agent writes structured events as it works (decisions, milestones, gotchas, test results); you query them in future sessions to avoid repeating expensive reasoning.

.brain/
  events.jsonl      ← append-only narrative  (committed)
  decisions.md      ← rendered decision ledger (committed)
  brain.config.json ← per-project config      (committed)
  brain.sqlite      ← FTS index (rebuildable, gitignored)

What you get

Tool	What it does
query_context	FTS search over decisions + gotchas — pull relevant context before reading a large doc
log_decision	Record an architectural fork: options considered, choice, reason
record_event	Append any structured event (milestone, gotcha, note, test run)
get_timeline	Paginated reverse-chronological feed of everything the agent has recorded
brain view	Local web viewer — timeline, API surface, DB schema

Quick install (60 seconds)

See QUICKSTART.md for the full step-by-step.

git clone https://github.com/Visual-Hive/project-brain.git ~/tools/project-brain
~/tools/project-brain/brain/scripts/install-into-project.sh /path/to/your/project

Then add the printed MCP block to your Cline settings and enable hooks — done.

Requirements

• Node.js ≥ 18 (≥ 20 recommended — see ABI note)
• Cline v3.36+ (for hooks) or any MCP-compatible agent (Claude Code, etc.)
• macOS or Linux (hooks use shell scripts; Windows WSL works)

Repo layout

brain/          ← the Node.js package (TypeScript source, tests, CLI)
.clinerules/    ← Cline enforcement adapter (soft rules + lifecycle hooks)
QUICKSTART.md   ← step-by-step install guide for strangers

How agents use it

Agents talk exclusively through the MCP server (brain mcp). Two rules in .clinerules/10-brain.md shape behaviour:

1. Call query_context before re-reading a large doc — the brain may already have the answer.
2. Call log_decision at any architectural fork, before implementing — future sessions thank you.

The three lifecycle hooks (TaskStart, TaskComplete, PreToolUse) auto-record task events so the timeline stays current without the agent having to remember.

Updating

cd ~/tools/project-brain
git pull
# Then in your project:
cd /your/project/brain && npm install && npm run build

Contributing

PRs welcome. The package is deliberately framework-free and dependency-light. Run npm test in brain/ — 40 tests, should be green.

Licence

MIT