Brain (entities & episodes)

Memory and the knowledge base are the two surfaces you see in the chat. Underneath sits the brain: a structured graph of entities, edges, and immutable episodes that grows every time you (or a connector) feeds it a new signal. This page explains the layer you don't see directly but that powers every assistant turn.

From signal to structure

Everything the workspace hears becomes an immutable episode. One extractor turns episodes into structure, trying the strongest shape first. Chat retrieves over the result.

Signals
  • Chat
  • Calendar
  • Meetings
  • GitHub
  • Files & voice
Episode log
Append-only, immutable

Extractor

One pass emits structure

Precedence ladder
  1. Task
  2. Entity + edge
  3. CRM
  4. Memory
  5. Ephemeral

Chat retrieves

Search, rollups, provenance

searchBraingetEntityprovenance

The primitives

Five operational primitives, three cognitive ones. The operational primitives are what you query directly in chat: CRM (people + companies + deals), Tasks, KB, Memory, and Files. The cognitive substrate (entities, edges, episodes) threads them together.

Entities

Canonical nouns: people, companies, projects, deals, products. Every brain primitive resolves to or links from an entity.

Edges

Typed graph relationships between entities (works_at, engagement_of, mentioned_in). Bi-temporal: a closed relationship keeps its history.

Episodes

The append-only observation log. Every memory, entity, and edge points back to the episode that observed it. Episodes are immutable; consolidation reads, never writes.

How signals become structure

Pipeline B is the unified extraction surface. Given any episode (a chat checkpoint, a Calendar invite that matched a rule, a Fathom transcript, a Slack mention), it runs a single LLM call that emits entities, edges, tasks, memories, and ephemeral items, with every observation evaluated against a precedence ladder (Task → Entity/Edge → CRM → Memory → Ephemeral). Memory is the last resort; emissions carry why_not_entity / why_not_task justifications so the model confronts the alternative.

Three pipelines, one extractor

  1. A

    Pipeline A: chat

    Live chat turns hit a compaction checkpoint; the compacted window becomes a web_chat episode and runs Pipeline B fire-and-forget.

  2. B

    Pipeline B: episode to derived rows

    The shared extractor. Called by A, C, and active capture (file upload, voice memo, manual save).

  3. C

    Pipeline C: external event ingest

    Connector events (GitHub, Calendar, Fathom, Slack) flow through the rules engine; matched events become episodes and run Pipeline B.

Rules engine

Per-connector-instance rules decide how each event is routed: realtime (straight to Pipeline B), scheduled (queued and drained on a cron), or drop (truly discarded). Filters are first-match-wins, with default templates per source: ":crm_contacts → realtime" for Calendar, "is_dm → realtime" for Slack, "pull_request.merged → realtime+alert" for GitHub. Edit them under Studio → Ingestion.

Self-healing classifier

The v2 classifier doesn't just decide once. Pipeline B's emissions are scored against the original episode; low-confidence rows go back through a reclassifier pass that can re-tier, merge near-duplicates, or downgrade a Memory to Ephemeral. Existing memories that drift from their evidence are surfaced for retraction in the corrections queue.

How chat reads the brain

Chat reads the brain through seven tools: one hybrid search (full-text + vector + graph + recency), entity rollups, recent episodes, provenance walks, usefulness feedback, typed aggregation, and row history. External agents reach the same brain through the MCP server.

searchgetEntityrecentEpisodesprovenanceaggregatemarkUsefulgetRowHistory

Brain vs memory

Memory is one primitive in the brain: the layer that holds inferred behavioral facts about people. Entities, edges, tasks, deals, and files are the rest. The acid test for the boundary: "if the source disappeared, does this row stay?" Yes for memory, typically no for KB chunks (which are re-importable from the source repo or docs). See Memory & knowledge for the user-facing controls.

Other surfaces worth knowing

Explicit links

Every brain-write tool (saveMemory, saveContact, saveDeal, createTask, fileWrite, …) accepts a universal links parameter so the model can connect new rows back to existing entities in the same call. Bi-temporal: closed relationships keep their history. Capped at 20 links per call.

Graph view

Obsidian-style force-directed visualization, via the Graph toggle on the Brain page. The workspace-wide entity↔entity graph, server-side degree, kind-coloured nodes, click-through to the brain detail drawer. Capped at 500 nodes.

Trust signals

Every row carries a source (user, model, connector, episode-graduation) and an optional verified_by_user_id. Retraction marks a belief as wrong without deleting the audit trail. Retrieval ranks rows via SOURCE_WEIGHTS × VERIFIED_BOOST: provenance, not a numeric confidence score.