Brain

A local-first notebook system for capturing and connecting work knowledge.

Philosophy

Everything is Markdown stored in a Git repo. No databases, no cloud services, no proprietary formats. Your notes are plain text files you own and can read with any editor.

Note Types

Type	Directory	Purpose
Person	notes/people/	Contacts, roles, context about individuals
Org	notes/orgs/	Companies, teams, groups
Project	notes/projects/	Initiatives, workstreams, efforts
Meeting	notes/meetings/	Agendas, notes, action items
Memo	notes/memos/	Loom videos, voice memos, written memos
Decision	notes/decisions/	ADR-style records of choices made
Journal	notes/journal/	Daily log / journal entries
Event	notes/events/	Calendar events synced from Google Calendar

Note Identity

Every note has a stable ID stored in its YAML frontmatter:

---
id: person-alice-smith
type: person
created: 2026-02-11
tags: [engineering, platform-team]
---

IDs are human-readable slugs prefixed by type. They never change, even if the file is renamed or moved. Links between notes use these IDs.

Attachments

Binary files (PDFs, images, recordings) go in attachments/ organized by note type. Reference them from Markdown with relative paths.

Content Directory (BRAIN_ROOT)

By default, notes, attachments, and the index live at the repo root. Set the BRAIN_ROOT environment variable (or answer the prompt during brain init) to point at a different directory — useful when the notebook content lives outside the CLI repo.

Directory Layout

brain/                        # CLI repo root
  src/             # CLI source code (TypeScript)
  scripts/         # Helper scripts
  docs/            # Documentation
  .brain/          # Settings, credentials and sync state (git-ignored)

$BRAIN_ROOT/                  # content root (defaults to repo root)
  notes/
    people/        # Person notes
    orgs/          # Organization notes
    projects/      # Project notes
    meetings/      # Meeting notes
    memos/         # Memo notes
    decisions/     # Decision records
    journal/       # Daily log / journal entries
    events/        # Calendar event notes
  attachments/
    meetings/      # Meeting-related files
    memos/         # Memo-related files
  index/           # Generated index (git-ignored)

CLI

A CLI tool named brain provides:

brain init

Interactive setup for new users. Prompts for your name, role, and organization, then creates your person note (with self: true) and an optional org note.

brain init
# Name: Alice Smith
# Role (optional): Engineering Lead
# Organization (optional): Acme Corp
# Created notes/people/alice-smith.md
# Created notes/orgs/acme-corp.md

brain remember <type> <title> [flags]

Remember a person, meeting, memo, decision, or journal entry. Flags: --date YYYY-MM-DD, --force, --dry-run.

Meeting notes require --file <path>. Pass a .txt transcript file and the LLM extracts structured sections (recap, summary, decisions, action items, notes) and populates the note body.

Memo notes require --file <path>. Pass a .txt, audio, or video file. The LLM extracts sections (summary, key points, action items, notes). Use --author <name> to set the author; defaults to the owner (self: true person).

brain remember person "Alice Smith"
brain remember meeting "Sprint Planning" --file transcript.txt
brain remember memo "API Walkthrough" --file walkthrough.mp4
brain remember memo "Quick Thoughts" --file voice-memo.m4a --author "Alice Smith"
brain remember today

brain rename <entity-id> <new-name>

Rename an entity (person, org, or project). Updates the note's name, ID, and filename, then rewrites all references across the notebook.

For people, the old name is added to aliases so future transcript matching still works.

brain rename person-alice-smith "Alice Jones"
brain rename org-acme "Acme Inc"

brain merge <source-id> <target-id>

Merge one entity into another of the same type. Combines frontmatter fields, body sections, and aliases, then rewrites all references and deletes the source note.

brain merge person-alice-duplicate person-alice
brain merge org-acme-dup org-acme

brain mcp

Start an MCP (Model Context Protocol) server over stdio. Claude Code calls this automatically — see Claude Code Integration below.

brain index [--embed]

Build (or rebuild) the local SQLite index from all notes in the repo. Run this after adding or editing notes to keep the index current.

Pass --embed to generate vector embeddings (via OpenAI text-embedding-3-small) for each chunk. When embeddings are present, the MCP server automatically uses hybrid retrieval (FTS + vector similarity).

brain slack [--model <model>]

Start a Slack bot that listens for @brain remember this in threads and creates memo notes from thread content. Runs as a long-lived daemon using Socket Mode. See docs/integrations/slack-setup.md for setup instructions.

brain sync calendar [--from <date>] [--to <date>] [--calendar-id <id>] [--dry-run] [--model <model>]

Sync events from Google Calendar and create event notes. On first run, walks through OAuth setup. Subsequent runs sync incrementally from the last successful sync.

Editor Integration

The extensions/brain-links/ directory contains a VS Code / Cursor extension that makes note references Cmd+Clickable. It handles [[wiki-links]], entity IDs in frontmatter, and artifact paths. See its README for build and install instructions.

Claude Code Integration

Brain exposes its retrieval pipeline to Claude Code via an MCP server, letting Claude search your notebook when answering questions. See docs/integrations/claude-code-setup.md for setup instructions.