RFC: Persistent Knowledge Layer (Brain) for Fleet Members

[yashrajsapra]

Problem

Fleet members today are smart but forgetful. Each session starts fresh — the agent re-reads the codebase, rediscovers patterns, and has no memory of past decisions, corrections, or recurring issues. Specifically:

• Lost context between sessions: "Last time I touched transport.ts, the SFTP path handling had a Windows drive-letter edge case" — gone.
• No institutional knowledge: "Tests in tools/ are flaky when run in parallel — always run sequentially" — the agent discovers this the hard way, every time.
• Course corrections don't stick: When a user interrupts and corrects an approach ("no, don't mock the database — we got burned last quarter"), that insight dies with the session.
• Reviewer blind spots: Reviewers can't check "what do we know about this symbol's history?" or assess blast radius beyond what git log shows.

Current mitigations (CLAUDE.md, session resume, bd remember) are manual — someone has to decide what's worth remembering. They don't scale.

Proposal

Add an optional persistent knowledge layer ("brain") at the fleet level that:

1. Stores and retrieves knowledge — fleet tools for brain query/write, accessible by PM and any orchestrator through existing fleet tools (no separate config)
2. Code analysis for reviewers — symbol-level impact analysis (callers, callees, definitions, references) available as fleet tools for reviewer workflows
3. Durable background work — job queue with crash recovery, stall detection, and cascade cancel as an alternative to fire-and-forget background agents
4. Brain-aware reviews — reviewer template optionally queries the brain before approving ("what do we know about this module? any past corrections?")
5. Automatic course correction capture — when a user interrupts and corrects an approach mid-sprint, that feedback is automatically written to the brain for future recall

Design Principles

• Opt-in per member — enabled via config on register/update. Not default, not on every member.
• Fleet layer only — PM inherits access through fleet tools. No duplication. DRY.
• Purely additive — existing workflows unchanged. Brain tools return clear errors when not available.
• Lazy connection — no startup penalty. Brain connects on first tool call.
• Token overhead < 1% — brain queries are lightweight, signal detection uses cheap models.

Where it pays off most

• Large codebases with recurring multi-session work where re-reading everything is expensive
• Teams where institutional knowledge matters — "we tried approach X on this repo and it failed because Y"
• Long-running projects where past corrections and design decisions accumulate
• For small, focused repos with single-session sprints — the current setup is adequate.

What we're NOT doing

• Replacing beads for task tracking — beads stays
• Enabling brain on every member by default — opt-in only
• Adding a full skill ecosystem — cherry-picking what fleet needs
• Auto-enrichment of people/companies — not relevant for code repos

Open Questions

1. Per-member vs shared brain? Should each member have its own brain, or one brain per repo/project?
2. Brain data lifecycle — when does brain knowledge expire or get pruned?
3. Cross-repo knowledge — should brain insights from one repo inform work on another?

Feedback welcome — especially on which use cases matter most to you.