App — Brain

The user’s second brain. Documents, memory, core knowledge. Sidekick reads from and writes to Brain.

Field	Value
Status	🟢 GA
Owner	@aphaiboon
Sidekick-accessible	✅ Read + write

What it is

Brain is the durable knowledge layer beneath the Sidekick. Three privacy tiers:

Tier	Visibility
Personal	Only the user
Team	Members of a selected team
Workspace	Everyone in the org

The BrainScopePicker (top of the Brain sidebar) toggles between these. The user’s selection composes with useTeamStore.selectedTeamId when in Team mode.

→ Privacy posture customers see: Privacy & Data Handling.

Document types

Type	Source
Uploaded files	PDF, DOCX, MD, TXT, images — fileUrl set, retrieved via presigned URL /api/brain/documents/:id/preview
Content-only (Sidekick-generated)	content stored in DB, no fileUrl. Fetched from /api/brain/documents/:id and rendered via TipTap (markdown → HTML via marked).

fileType may store just the extension (md) not full MIME — resolve via extension-to-MIME mapping.

Folders

A Brain Folder is a collection of Brain documents. Folders can be attached to Sidekick chats as durable context (brain-collection context tag). When attached, Sidekick injects up to 5 docs × 1500 chars from the folder.

Memory

Brain stores three kinds of memory:

1. Documents — explicit user-curated knowledge
2. Working memory — recent relevant snippets across chats (managed by MemoryConsolidator background job)
3. Core memory — long-term facts and preferences (the “this is who I am” layer)

Person memory (facts about specific people) is a separate but related system (lives in CRM).

Sidekick integration

Capability	How
Auto semantic search	Default. Embeds the user message, fetches top-K Brain results above similarity threshold. Skipped when explicit +brain-document or +brain-collection tags are present (pinned context wins).
Attach a Brain doc	+ menu → Brain Documents. Injects up to 8k chars (DB-stored) or summary + tool hint (file-backed).
Attach a Brain folder	+ menu → Brain Folders. Injects metadata + content from up to 5 docs.
Create a Brain doc	Tool: create_brain_doc
Update a Brain doc	Tool: update_brain_doc
Search Brain	Tool: search_brain

→ Sidekick Routing Pipeline for context envelope mechanics.

Data model (high level)

Table	Purpose
brain_documents	Doc rows — id, organizationId, title, content (nullable), fileUrl (nullable), fileType, privacyTier, ownerId, folderId
brain_folders	Folder rows — id, organizationId, name, privacyTier, ownerId
brain_memory_chunks	Embeddings + working memory snippets, indexed by pgvector
brain_core_memory	Long-term facts/preferences

All org-scoped per Repository Pattern (ADR-0002).

Editor

• TipTap (@tiptap/react) for .md and .txt editing
• Parse raw markdown to HTML via marked before setting as TipTap content
• Preview/Edit toggle via setEditable()
• Auto-save with 1.5s debounce

UI

• Brain sidebar with BrainScopePicker (Personal/Team/Workspace) at top, then BrainTabPicker (Documents/Memory/Core), then ScrollArea
• Privacy-layer scope is Brain-specific — never folded into universal team selector
• Other apps must not introduce their own privacy-tier pickers

Analytics events

• brain_document_created
• brain_document_viewed
• brain_document_updated
• brain_folder_created
• brain_search_query
• brain_context_tag_attached (from Sidekick + menu)

Related incidents

• FM-027 — Brain uploads invisible after refactor
• FM-028 — Org Drive never created
• FM-029 — Dual naming “Sidekick Files” vs “Chat Uploads”
• FM-031 — Account Drive backfill missed NULL collectionId
• FM-033 — Brain-first shortcut dumps raw content

Related

• App — Sidekick — primary consumer of Brain
• Sidekick Routing Pipeline — context envelope mechanics
• Data Access — Repository Pattern — DB access discipline
• Privacy & Data Handling — customer-facing privacy posture