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 via AGENTS.md config (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} is not configured in AGENTS.md, 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

Before starting any mode workflow, resolve {brain_dir} — the directory where brain documents are stored.

1. Read {cwd}/AGENTS.md → scan for <!-- synapsync-skills:start --> block → find ## Configuration table → parse brain_dir row
2. If brain_dir found → use it, done
3. If not found → ask the user:
   • Option A: Use default (.agents/staging/project-brain/)
   • Or select “Other” to write a custom path
4. Persist the chosen value to AGENTS.md Configuration table

Full resolution algorithm: see assets/helpers/brain-config.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} from AGENTS.md, 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. MCP for Obsidian only in LOAD: SAVE always writes to filesystem (Obsidian syncs via the obsidian skill if needed)
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