brain

# Local Brain Local Brain is the user's durable local memory. It stores typed records, evidence, AI notes, extracted facts, curated memories, tags, assets, and universal search chunks in SQLite. Use the `brain` CLI; do not write SQLite directly. ## Golden Rules 1. **Query before you write.** Run `brain --json import-context` and targeted `brain --json search` calls before creating or linking records. 2. **Discover the contract.** Run `brain --json contract` when command shapes, link syntax, exit codes, or source rules are unclear. 3. **Verify the target brain.** Pass the intended `--brain <dir>` or verify `$BRAIN_ROOT` with `brain --json doctor` and `brain path` before writes. 4. **stdout is data, stderr is diagnostics.** Use global `--json`; parse success data from stdout and JSON errors from stderr. 5. **Import source-led.** Enumerate source records first. Keyword search is a filter, not a coverage plan. 6. **Store evidence before intelligence.** Raw text/transcripts come first; AI notes, facts, tasks, tags, and memories complete the import. 7. **Cite, do not invent.** Use chunk evidence for derived tasks, facts, AI notes, and memories. 8. **Create agreed projects, suggest uncertain structure.** Add a project only after the user has signed off on that project boundary. Link existing projects/orgs; use suggestions for unapproved project candidates or high-impact inferred organizations. 9. **Use entity external IDs only for entities.** For people/orgs, `--external-id` must identify that person/org itself, not an email thread, message, meeting, event, document, or other source record. 10. **Finish participant normalization.** Backfills are not complete until unresolved participant handles are audited and recurring real people are promoted or ledgered. ## Brain selection When this skill is installed by Local Brain, the app writes a generated `brains.json` file next to this `SKILL.md`. Read it before running `brain`: - Use the entry with `isActive: true` by default. - Pass `--brain <rootPath>` on CLI calls, or set `BRAIN_ROOT=<rootPath>` for a sequence of calls. - If there is no active brain or the user names a different brain, choose the matching `name` / `rootPath` from `brains.json`. - If `brains.json` is missing or ambiguous, ask the user which brain folder to use instead of guessing. ## Nouns - **person** - someone the user knows. Use `brain add person`, `brain add person-from-email`, or `brain enrich person`. - **organization** - company, team, vendor, school, club, or institution. It has a `headline`; use `brain add organization` or `brain enrich organization`. - **project** - user-agreed workstream or life area. Use `brain add project` only after explicit user sign-off; otherwise link existing projects or propose candidates with `brain suggest project`. - **task** - commitment, waiting item, reminder, or follow-up. Cite source chunks when derived from an import. - **interaction** - meeting, call, email, message, event, or note that happened at a time. - **interaction_transcript** - raw transcript text for an interaction. - **document** - durable reference material such as a note, file, webpage, plan, memo, receipt, or imported text artifact. - **ai_note** - narrative AI artifact: summary, action items, decisions, risks, highlights, coaching, or other. - **extracted_fact** - append-only structured claim. Promote selected facts to hidden memories with `brain promote fact`. - **memory** - curated hidden atomic claim with evidence and links. - **asset** - managed binary file plus optional searchable text. ## Read First ```bash brain --json doctor brain path brain --json contract brain --json import-context --limit 200 brain --json search "northwind kickoff" brain --json retrieve "northwind kickoff" brain --json retrieve --record-type interaction --kind email --sort recency --after 2026-06-01 brain --json get-records interaction:<id> --chunk <chunk-id> brain --json show person <id> brain --json suggest list brain --json import audit --limit 100 brain --json today brain --json report daily brain --json tasks plan-day --limit 25 brain --json graph --center self ``` For answer generation, use `brain retrieve` to find grounded chunks, then `brain get-records <recordRef> --chunk <chunkId>` to load the record title, date, and bounded chunk text. Use `brain search` for quick lookup/navigation, not as the full grounding path. The CLI does not synthesize answers for you. For a daily brief, use `brain --json report daily` as the complete context payload. It includes the self display name, task buckets, waiting items, recent interactions with excerpts and participants, recent changes, relationship context, active projects, counts, and generated date metadata. Generate the narrative outside Local Brain from that JSON; do not scrape the Tauri Today surface. ## Staged Import Preferred import flow: ```bash brain --json import interaction ... brain --json import document --source <slug> --external-kind <kind> --external-id <id> ... brain --json import transcript --interaction <id> --text-file transcript.txt ... brain --json add ai-note --interaction <id> --text-file summary.md brain --json add fact --subject interaction:<id> --key decision --value-text "..." \ --source-record interaction:<id> --evidence interaction:<id>~"short quote" brain --json promote fact <fact-id> --memory-kind decision brain --json tag ensure --name "Picardo" brain --json tag attach --tag picardo --record interaction:<id> brain --json import participants audit --min-count 2 brain --json import participants promote --handle maya@example.com --full-name "Maya Chen" brain --json import finalize --record interaction:<id> ``` Task maintenance during imports: ```bash brain --json add task --title "Reply to Scott Shreeve about his Picardo feedback" \ --link person:<id> --link interaction:<id> \ --evidence interaction:<id>~"Scott signed up for Founder Mode" brain --json tasks update <task-id> \ --title "Confirm Asset in Motion luggage quote and transfer plan with Janine" \ --description "Waiting for Janine to confirm the quote after Alex sent luggage details." \ --status waiting \ --link interaction:<id> \ --evidence interaction:<id>~"four metal RIMOWA cases" brain --json tasks complete <task-id> \ --evidence interaction:<id>~"transfer was handled" ``` Create a new task when a human source clearly introduces a missing follow-up. Use `brain --json tasks update` when a newer source clearly advances an existing task, such as changing a logistics task to `waiting` after the user asked someone else to proceed. Use suggestions/prose review for uncertain edits, splits, priority changes, or completion without explicit evidence. During recurring imports, reconcile the entire active backlog after fresh sources are stored, including undated and waiting tasks. Match new actions against both active and terminal tasks by the underlying obligation and source context. Reuse existing tasks for repeated reminders; do not recreate completed work. Complete resolved tasks, cancel source-backed obsolete tasks, and consolidate confirmed duplicates into one canonical task while preserving evidence. Age alone does not justify closure. Record per-task outcomes and explicit source gaps, then audit coverage before regenerating the daily brief. `tasks plan-day --limit 25` is a prioritized view, not proof that every task was reviewed. The bundled `brain-task-review` skill provides a full snapshot and readback audit for this pass. Older direct writes still work: ```bash brain --json add document --title "Pricing model v2" --text-file note.md brain --json add interaction --kind email --title "Intro" --text-file body.txt ``` Use `brain --json import finalize --record kind:id` after an import. Complete imports have source identity, entities/participants, complete readable source text when the source has text, AI note, extracted facts, project/task links when relevant, evidence-backed tasks or memories, tags, and chunks. Do not redact imported source bodies; skip and ledger the whole source record if it should not be stored locally. If a good import intentionally lacks a stage, finalize with the narrow waiver that explains it: `--raw-text-unavailable`, `--no-entities`, `--no-project-or-task-link`, `--no-derived-actions`, or `--no-extracted-facts`. Record-level finalize does not replace global normalization. Before a backfill final report, run `brain --json import participants audit --fail-on-promote-candidates` after promoting recurring real people or ledgering unresolved cases. For backfills, keep each bounded source pass auditable outside the brain DB. Use local pass artifacts such as `manifest.jsonl`, `review-queue.jsonl`, `decisions.jsonl`, `decisions.tsv`, `import-ledger.tsv`, raw provider JSON, readable text files, and `report.md`. Record provider estimates, explicit caps, fetched/imported/skipped/duplicate counts, and the unreviewed remainder. Dedupe new source records against all prior pass ledgers and source identities before writing. ## People And Organizations Create person/org records when evidence shows repeated meaningful contact, a known relationship, or durable future relevance. Do not create a person for every imported handle or a company for every domain. Preserve weak or one-off entities as participants, suggestions, or tags until more evidence appears. Before large imports, register the user's known handles with `brain self set` so self participants normalize automatically. Use `--self-participant` for a source-specific user handle that is not registered yet. Keep headlines and affiliations conservative. Prefer "works on", "contact for", or "appears affiliated with" over exact titles unless the source states the title. Mark affiliations current only when current evidence supports it. Skip machine/shared mailboxes and low-signal domains as entities: - no-reply, notifications, support, billing, receipts, calendar, mailer-daemon - personal or email-provider domains such as gmail.com, icloud.com, outlook.com Creating people/orgs improves future participant normalization. Existing imported participant rows can be audited and normalized with: ```bash brain --json import participants audit --source gmail --min-count 2 --limit 100 brain --json import participants promote --handle maya@example.com \ --full-name "Maya Chen" --headline "Picardo vendor contact" \ --org "Example Labs" --org-domain example.com --title "Operations lead" --current brain --json repair participants relink --handle maya@example.com --person <person-id> brain --json repair person-email move --email maya@example.com \ --from <wrong-person-id> --to <right-person-id> --relink-participants brain --json repair person-phone move --phone "+1 555 0100" \ --from <wrong-person-id> --to <right-person-id> --relink-participants ``` Use read-only SQL only for audits and candidate discovery; all creates, enrichments, affiliations, promotions, and repairs go through `brain`. If `brain --json add person`, `brain --json add person-from-email`, or `brain --json add organization` returns `external_identity_conflict`, stop and fix the import identity. Do not retry by forcing enrichment onto the matched record. Trusted contact: ```bash brain --json add person --full-name "Maya Chen" \ --email maya@example.com --phone "+1 555 0100" \ --headline "Picardo vendor contact for lab logistics" \ --org "Example Labs" --org-domain example.com --title "Operations lead" --current ``` Untrusted email sender: ```bash brain --json add person-from-email --full-name "Maya Chen" \ --email maya@example.com --source gmail ``` Only pass `--external-id` here when the upstream id is a stable contact/person id for Maya herself. Do not use the Gmail message or thread id; that belongs on the imported interaction. Enrichment: ```bash brain --json enrich person <id> --headline "House design contact" \ --current-title "Designer" --role-family design --seniority lead brain --json add organization --name "Example Labs" --domain example.com \ --headline "Clinical lab partner" brain --json enrich organization <id> \ --one-line-description "Clinical testing provider for launch workflows." \ --why-it-matters "Relevant to credentialing and ordering paths." \ --source-urls-json '["https://example.com"]' ``` Use `brain suggest organization` when an org is weakly inferred from one email signature or ambiguous domain. Use `brain affiliate --person <id> --org <id> --title <title> --department <dept> --role-family <family> --seniority <level> --current --primary` for existing records. ### Cleanup And Dedupe Use CLI cleanup primitives instead of direct SQLite updates: ```bash brain --json merge person --from <duplicate-person-id> --to <canonical-person-id> --dry-run brain --json merge person --from <duplicate-person-id> --to <canonical-person-id> \ --reason "duplicate contact shell" brain --json unlink person:<person-id> organization:<org-id> \ --reason "org field was a location, not an employer" brain --json archive organization <org-id> --reason "mistaken organization import" brain --json person rename <person-id> --full-name "Correct Name" brain --json person email add <person-id> --email correct@example.com brain --json person phone add <person-id> --phone "+1 555 0100" brain --json repair participants relink --handle wrong@example.com \ --person <right-person-id> --from-person <wrong-person-id> ``` Add `--force` only when the target is already linked in the same interaction and the wrong-person participant row should be merged away. Always dry-run `merge person` before applying it in a large backfill. It moves handles, affiliations, participant rows, typed links, tags, source identities, and fact/memory references to the target, then archives the source. Source provenance stays attached to the archived source, and the target gets an explicit merge provenance event. It refuses to merge away the self person; merge duplicates into self instead. Archive bad shells after unlinking active relationships that should not survive. Organization archive blocks while active current affiliations remain; use `unlink` first when the affiliation itself was wrong. ## Projects Create projects only when the user has agreed to the project boundary: ```bash brain --json add project --name "House" \ --summary "Renovation and property work for 701 W Elizabeth St and 700 Jewell St" \ --link person:<id> --link interaction:<id> ``` When a source strongly hints at a project but the user has not signed off, do not create the project. Use `brain suggest project` with evidence instead. ## Email, Calendar, And Meetings Gmail thread: ```bash brain --json import interaction --kind email \ --title "Gmail: Everlywell Integration" \ --summary "Production credential setup and go-live readiness." \ --text-file full-thread.md \ --source gmail --external-kind thread --external-id <thread-id> \ --participant "from:Maya Chen <maya@example.com>" \ --link project:<id> ``` For historical Gmail backfills, prefer `from:me` as the first bounded pass. It usually surfaces high-signal relationship and project threads because it captures what the user replied to, approved, introduced, or coordinated. Follow with `is:important`, recurring correspondent/domain, attachment-heavy, and explicit project passes as needed. Skip commodity confirmations, self-authored daily digests, shared mailbox noise, and sensitive personal/family/medical material unless explicitly approved or clearly part of an accepted project. Calendar event: ```bash brain --json import interaction --kind event \ --title "Calendar: Stay at Louma" \ --occurred-at 2026-07-09 --ended-at 2026-07-12 \ --location "Louma Country Shepherd's Hut" \ --text-file full-calendar-event.txt \ --metadata-json-file raw-google-calendar-event.json \ --event-json-file event-details.json \ --source google_calendar --external-id event-123 \ --original-url "https://www.google.com/calendar/event?eid=..." \ --participant "organizer:Alice Wyatt <alice@example.com>" \ --self-participant "attendee:You <alex@example.com>" \ --link project:<id> ``` Use `event` for travel, lodging, reservations, reminders, all-day blocks, and non-meeting schedule context even if attendees exist. Use `meeting` for people-centered appointments. Calendar events that only say "see Gmail for details" are incomplete unless the importer fetches the linked Gmail source or records `--raw-text-unavailable`.