Project Brain

Project Brain

Assets

This skill uses a modular assets architecture. Detailed workflows, helpers, and templates are in the assets/ directory:

• assets/modes/ — LOAD and SAVE mode workflows
• assets/helpers/ — Brain directory config resolution, incremental merge algorithm
• assets/templates/ — Standard brain document format

See assets/README.md for full directory documentation.

Purpose

Project Brain is session memory for AI agents. It bridges the gap between sessions so any agent can pick up exactly where the last one left off — and save what it learned before shutting down.

Design principle: Agents behave like professionals with a notebook. Open the notebook before work (LOAD), write a summary when done (SAVE), and the notebook persists between sessions. Memory is a natural part of the workflow, not an extra step.

What it does:

• LOAD: Reads a brain document, parses structured context, delivers a concise briefing
• SAVE: Captures session context, creates or incrementally updates a brain document

What a brain document is: A markdown file that captures project state, session history, architecture decisions, and next steps. The standard format (v2.0) has defined sections, but the skill also reads v1.0 and free-form documents.

Critical Rules

RULE 1 — NO FABRICATION

Only report information that exists in the brain document (LOAD) or was explicitly discussed in the session (SAVE). Never infer, guess, or complete missing data.

RULE 2 — USER CONFIRMS BEFORE WRITE

In SAVE mode, always present the gathered session data to the user for review before writing. Never write without confirmation.

RULE 3 — INCREMENTAL NOT DESTRUCTIVE

SAVE UPDATE merges new data into existing sections. It never overwrites the full document. Accumulated Context is append-only. Session Log is prepend-only.

RULE 4 — FORMAT BACKWARD-COMPATIBLE

LOAD parses three formats: v2.0 standard, v1.0 sections, and free-form markdown. SAVE UPDATE detects the format and offers migration if the document isn't v2.0.

RULE 5 — PATH RESOLUTION ONCE

Resolve {brain_dir} once per session (see Configuration Resolution). The resolved path is used for all operations. Don't re-ask unless the user wants to change the path.

RULE 6 — LANGUAGE SEPARATION

Conversation (briefings, confirmations, questions) → respond in the same language the user used. Brain document content (what gets written to file) → always in English, regardless of conversation language. Technical artifacts must be consistent across sessions.

RULE 7 — NO SILENT DEFAULTS

When {brain_dir} has not been resolved, you MUST ask the user via AskUserQuestion before proceeding. Never silently choose the default staging path. The user must actively confirm their preferred directory.

Configuration Resolution

{brain_dir} is the directory where project-brain stores brain documents. Resolve it once per session:

1. User message context — If the user's message contains file paths, extract {brain_dir} from those paths
2. Auto-discover — Scan for .agents/project-brain/ in {cwd}, or look for existing brain documents
3. Ask the user — If nothing found, ask where to store brain documents via AskUserQuestion. Default suggestion: .agents/project-brain/{scope}/

No AGENTS.md. No branded blocks. The brain directory is resolved at runtime.

Full resolution algorithm: see assets/helpers/brain-resolve.md

Mode Detection

Disambiguation: If the user's intent is unclear, ask:

"Do you want me to load a brain document (restore context) or save the current session (capture what we did)?"

Asset Loading (Mode-Gated)

After detecting the mode, read ONLY the assets listed for that mode. Do NOT read assets for other modes — they waste context tokens.

Read the mode asset first, then follow its internal references to helpers/templates as needed.

Quick Start

LOAD Mode

Use at the start of a session to restore context:

Load the project brain.

This will: resolve {brain_dir}, scan for existing documents, read the brain, parse sections, and deliver a context briefing.

Assets to read now: assets/modes/LOAD.md + brain-resolve.md

SAVE Mode

Use at the end of a session to persist what happened:

Save the session to the brain.

This will: detect if a brain exists (UPDATE) or not (INIT), gather session data, confirm with you, and write or merge the brain document.

Assets to read now: assets/modes/SAVE.md + brain-config.md (SAVE.md references additional helpers per sub-mode)

Capabilities Matrix

Integration with Other Skills

Composition patterns:

session start  → project-brain LOAD  → agent is briefed → work happens
session end    → project-brain SAVE  → session persisted → next agent can LOAD

sprint-forge INIT  → generates findings + roadmap
project-brain SAVE → captures sprint-forge session → brain document created
new session        → project-brain LOAD → full context restored

Limitations

1. Markdown only: Handles .md files; does not parse .yaml, .json, or other formats
2. Single file: One brain document per project — not a recursive folder reader
3. No synthesis: If the brain document is outdated, the briefing reflects that
4. Obsidian integration in LOAD only: SAVE always writes to filesystem. To sync to Obsidian, use the obsidian skill after SAVE.
5. Session Log size: Compacted at 15+ entries — older sessions are archived to {brain_dir}/archive/ and replaced with a summary paragraph
6. No auto-save: SAVE must be explicitly invoked — the agent doesn't auto-save on exit