synapsync/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

| Mode | EN Signals | ES Signals | What It Does | |------|-----------|-----------|-------------| | LOAD | "load brain", "restore context", "brief me", "pick up where we left off" | "carga el brain", "recupera el contexto", "ponme al dia" | Auto-discovers brain, reads it, delivers context briefing | | SAVE | "save brain", "save session", "update brain", "persist session" | "guarda el brain", "guarda la sesion", "actualiza el brain" | Gathers session data, creates or updates brain document |

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.

| Mode | Read These Assets | Do NOT Read | |------|-------------------|-------------| | LOAD | assets/modes/LOAD.md, assets/helpers/brain-resolve.md | SAVE.md, brain-config.md, incremental-merge.md, BRAIN-DOCUMENT.md | | SAVE INIT | assets/modes/SAVE.md, assets/helpers/brain-config.md, assets/templates/BRAIN-DOCUMENT.md | LOAD.md, brain-resolve.md, incremental-merge.md | | SAVE UPDATE | assets/modes/SAVE.md, assets/helpers/brain-config.md, assets/helpers/incremental-merge.md | LOAD.md, brain-resolve.md, BRAIN-DOCUMENT.md |

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

| Capability | LOAD | SAVE (INIT) | SAVE (UPDATE) | |-----------|:----:|:-----------:|:-------------:| | Resolve {brain_dir} | Yes | Yes | Yes | | Auto-discover brain documents | Yes | No | Yes | | Read brain from Obsidian vault | Yes | No | No | | Read brain from filesystem | Yes | No | No | | Parse v2.0, v1.0, free-form | Yes | No | Yes | | Deliver context briefing | Yes | No | No | | Create new brain document | No | Yes | No | | Incremental merge | No | No | Yes | | Gather session context | No | Yes | Yes | | Offer format migration | No | No | Yes |

---

Integration with Other Skills

| Skill | Integration | |-------|------------| | sprint-forge | LOAD reads sprint-forge re-entry prompts. SAVE captures sprint progress as session entries. | | obsidian | LOAD can read brain documents from vault via obsidian READ mode. Invoke via Skill("obsidian") or say "read from obsidian". Subagent fallback: read obsidian SKILL.md directly. | | universal-planner | LOAD reads planning documents. SAVE captures planning decisions. |

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