Build your own Brainkeeper project memory system

brainkeeper.md

Build Your Own Brainkeeper

A Brainkeeper is a lightweight operating system for project memory. It gives humans and coding agents one reliable place to put raw context, distill it into current truth, and keep decisions from disappearing into chat history.

This pattern works well for product teams, solo builders, open-source maintainers, research projects, internal tools, and any repo where future contributors need more context than the code can provide.

What the Brainkeeper Maintains

Create a brain/ directory in your repo:

brain/
├── README.md
├── BRAINKEEPER.md
├── RESOLVER.md
├── sources/
├── synthesized/
│   ├── active-principles.md
│   ├── current-strategy.md
│   ├── roadmap.md
│   ├── decision-log.md
│   └── open-questions.md
├── workflows/
│   ├── session-wrap-up.md
│   ├── synthesis-update.md
│   └── daily-reflection.md
└── admin/
    ├── activity-log.md
    ├── pending-proposals.md
    └── reflections/

The exact files can change, but keep the separation between:

• sources/: raw inputs, append-only.
• synthesized/: current best understanding.
• workflows/: repeatable procedures for agents and humans.
• admin/: maintenance history, proposals, and reflections.

Core Principle

Do not treat the brain as a notes dump. Treat it as a small knowledge system:

1. Capture raw material.
2. Route it to the right place.
3. Synthesize only what changes current understanding.
4. Preserve the old state when meaningfully changing the new state.
5. Cite sources for important claims.
6. Log maintenance work so future readers know what changed.

brain/README.md

Use this as the front door:

# Project Brain

This folder is the shared memory for the project. It preserves raw source material, current decisions, strategy, operating principles, roadmap, and open questions.

## How to read this brain cold

1. Start with `synthesized/active-principles.md`.
2. Read `synthesized/current-strategy.md` for current direction.
3. Check `synthesized/roadmap.md` for sequencing.
4. Check `synthesized/open-questions.md` before making major decisions.
5. Check `synthesized/decision-log.md` for prior choices and rationale.
6. If you are maintaining the brain, read `BRAINKEEPER.md`, `RESOLVER.md`, and the relevant workflow in `workflows/`.

## Operating rules

- Sources are append-only.
- Synthesized docs may change, but significant changes should preserve prior state in a Timeline or Change Log section.
- Important claims should link back to source files when practical.
- Ambiguous filing decisions should be previewed before writing.
- Large synthesis passes should be intentional, not automatic.

brain/BRAINKEEPER.md

This is the reusable agent spec. Any human or coding agent can follow it.

# Brainkeeper

## Role

You are the Brainkeeper for this project. Your job is to keep `brain/` useful, current, legible, and source-grounded for future humans and future agents.

## Responsibilities

1. Intake: accept notes, session summaries, transcripts, links, research, screenshots, and strategy fragments; file them in the right place.
2. Synthesis: maintain derived artifacts such as active principles, current strategy, roadmap, decisions, open questions, and plans.
3. Maintenance: reconcile contradictions, retire stale claims, preserve history, and keep links useful.
4. Visibility: log meaningful actions in `admin/activity-log.md` and proposals in `admin/pending-proposals.md`.
5. Self-improvement: write short reflections in `admin/reflections/` when asked or on a schedule.
6. Downstream sync: when a brain update changes engineering truth, check package-local docs, runbooks, README files, or agent entrypoints and either update them or log why no change was needed.

## Non-negotiables

- Never silently overwrite important synthesized truth. Preserve the old state in a Timeline or Change Log section.
- Cite source files for important claims.
- Do not let the brain become accurate while package-local docs stay misleading.
- Prefer a diff or preview before structural rewrites.
- Keep the brain scannable: a new contributor should understand the project in under 15 minutes.
- Be cheap by default: do not run large synthesis unless asked or approval-gated.

## Output style

When reporting back:

- Use short bullets.
- State exactly which files changed or are proposed to change.
- Separate facts, decisions, open questions, and proposals.
- Ask only when ambiguity changes the write or action.

brain/RESOLVER.md

This file prevents context from getting filed randomly.

# Brain Resolver

Use this when deciding where new information belongs.

## Scope check

Before filing anything, ask: does this belong in this project brain?

Examples that may belong elsewhere:

- Company/legal/finance material.
- Personal notes unrelated to the project.
- Implementation details that belong in package-local docs.
- Secrets, credentials, private customer data, or sensitive records.

If it does not belong here, do not file it in `brain/`.

## Filing decision tree

1. Is it raw source material?
   - Examples: transcript, pasted note, meeting notes, article dump, screenshot text, unedited brainstorm.
   - File under `brain/sources/YYYY-MM-DD-short-description.md`.
   - Do not rewrite existing source files.

2. Is it a current principle future contributors should follow?
   - Update `synthesized/active-principles.md`.
   - Preserve significant prior wording in that file's Timeline or Change Log.

3. Is it current product, project, or business strategy?
   - Update `synthesized/current-strategy.md`.

4. Is it sequencing, milestones, timing, or delivery order?
   - Update `synthesized/roadmap.md`.

5. Is it a choice already made?
   - Add to `synthesized/decision-log.md` with date, decision, rationale, and sources.

6. Is it unresolved or needs validation?
   - Add to `synthesized/open-questions.md`.

7. Is it about Brainkeeper maintenance?
   - Use `admin/activity-log.md`, `admin/pending-proposals.md`, or `admin/reflections/`.

## Ambiguity rules

- If one item plausibly belongs in multiple places, prefer a source capture plus links from synthesized docs.
- If a write would restructure multiple files, produce a proposed map or diff first.
- If the content changes strategy, log it as both a decision or open question and an update to the relevant synthesis doc.

Starter Synthesized Files

Keep these short and current.

synthesized/active-principles.md

# Active Principles

Current operating principles future contributors should follow.

## Principles

- Principle: ...
  - Why it matters: ...
  - Sources: ...

## Timeline

- YYYY-MM-DD: Added or changed principle ...

synthesized/current-strategy.md

# Current Strategy

The current best understanding of what the project is trying to do and why.

## Current Direction

...

## What Changed Recently

...

## Source Notes

- `../sources/YYYY-MM-DD-example.md`

synthesized/roadmap.md

# Roadmap

## Now

- ...

## Next

- ...

## Later

- ...

## Timeline

- YYYY-MM-DD: ...

synthesized/decision-log.md

# Decision Log

## YYYY-MM-DD: Decision title

- Decision: ...
- Rationale: ...
- Alternatives considered: ...
- Sources: ...

synthesized/open-questions.md

# Open Questions

## Question

- Status: open
- Why it matters: ...
- Needed to resolve: ...
- Sources: ...

Workflows

workflows/session-wrap-up.md

# Workflow: Session Wrap-Up

Use this at the end of a work session.

## Inputs

- Session transcript or summary.
- Optional list of changed files.
- Optional user notes about what mattered.

## Steps

1. Extract decisions made, facts learned, open questions, action items, and new concepts.
2. File raw transcript or summary under `brain/sources/` if it is source material.
3. Use `RESOLVER.md` to propose synthesized updates.
4. Produce a diff preview before writing if more than one synthesized doc changes.
5. If engineering truth changed, check local docs and agent entrypoints before finishing.
6. After approval, write changes and add an entry to `admin/activity-log.md`.

## Output

Report:

- source file created or used
- synthesized files changed or proposed
- downstream docs checked or changed
- decisions logged
- open questions added
- follow-up proposals

workflows/synthesis-update.md

# Workflow: Synthesis Update

Use when sources or decisions make a synthesized artifact stale.

## Steps

1. Identify the target artifact.
2. Read relevant sources and the current artifact.
3. Preserve important previous wording in a Timeline or Change Log section.
4. Update the current top section to reflect the best current truth.
5. If the update changes engineering behavior or runbooks, check downstream docs before finishing.
6. Cite sources inline using relative links where practical.
7. Log the update in `admin/activity-log.md`.

## Approval rule

If the update changes strategy, roadmap, scope, or project direction materially, show a diff preview before writing unless explicitly asked to write directly.

workflows/daily-reflection.md

# Workflow: Daily Reflection

Use on a schedule or when asked to improve the brain.

## Steps

1. Review recent activity log entries, pending proposals, and changed synthesized docs.
2. Identify stale claims, duplicated ideas, unresolved contradictions, and missing citations.
3. Write a short reflection in `admin/reflections/YYYY-MM-DD-reflection.md`.
4. Add concrete proposals to `admin/pending-proposals.md`.
5. Do not rewrite major synthesized docs unless asked.

Agent Entry Point

Add a root AGENTS.md or equivalent tool-specific entrypoint:

# Project Agent Guide

Before product, strategy, planning, or documentation work, read:

1. `brain/README.md`
2. `brain/BRAINKEEPER.md`
3. `brain/RESOLVER.md`
4. The relevant file in `brain/workflows/`

For brain updates:

- Preserve raw sources under `brain/sources/`.
- Update synthesized docs only with source-grounded changes.
- Preserve prior synthesized truth in a Timeline or Change Log.
- Preview multi-file or strategic changes before writing.
- Log meaningful completed changes in `brain/admin/activity-log.md`.

For Claude Code, you can add .claude/agents/brain-keeper.md:

---
name: brain-keeper
description: Maintain the project brain; use for session wrap-ups, strategy synthesis, decision logging, and brain maintenance.
model: sonnet
tools: [Read, Edit, Write, Bash]
---

You are the Brainkeeper for this project.

The canonical spec is in the brain itself. Before doing brain work, read:

1. `brain/README.md`
2. `brain/BRAINKEEPER.md`
3. `brain/RESOLVER.md`
4. The relevant workflow in `brain/workflows/`

Follow those files over this shim.

Suggested Activity Log Format

admin/activity-log.md:

# Brain Activity Log

## YYYY-MM-DD

- Action: ...
- Files changed: ...
- Sources used: ...
- Downstream docs checked: ...
- Notes: ...

Suggested Pending Proposal Format

admin/pending-proposals.md:

# Pending Brain Proposals

## Proposal title

- Date: YYYY-MM-DD
- Proposal: ...
- Why: ...
- Files affected: ...
- Status: pending

Practical Rules

• Keep source files boring and faithful. Raw inputs should not be polished into hindsight.
• Keep synthesized files opinionated and current. They are the answer to "what do we believe now?"
• Prefer links over duplication.
• Do not cite chat memory. File the relevant summary as a source first, then cite that.
• Do not store secrets or sensitive personal data in the brain.
• Do not let every conversation become a brain update. Capture material only when it changes future behavior, strategy, decisions, or context.
• Keep it small enough that a future agent can read the important parts before doing real work.

Minimal First Commit

If you want the smallest useful version, create:

brain/
├── README.md
├── BRAINKEEPER.md
├── RESOLVER.md
├── sources/
├── synthesized/
│   ├── current-strategy.md
│   ├── decision-log.md
│   └── open-questions.md
└── admin/
    └── activity-log.md

Then add this rule to your agent entrypoint:

Before making project-level decisions, read brain/README.md. When new context changes future decisions, capture the raw source under brain/sources/, update the relevant synthesized doc, cite the source, and log the maintenance action.