← Workstreams

Workstream: External Brain

Status: Planned · Component: Maximize developer productivity

Goal

A place to store the thoughts that can't be kept in your brain. Inspired by Obsidian, the External Brain is a personal knowledge system where content of various types — notes, links, files — is authored as markdown and hyperlinked together, so a user can explore related items and jump around the graph rather than hunt through folders. Markdown is the lingua franca: everything the brain holds or ingests is represented as markdown, which keeps the entire brain human-readable, portable, and printable.

The External Brain is the human-facing member of the knowledge family: where Agent Memory compounds what a fleet of agents learns, the External Brain compounds what a person knows. The two are distinct workstreams with distinct audiences, but they share substrates — notably SearchableBucket for query-by-content recall.

Current state

The vision already has an incredibly naive first attempt at implementation, split across two projects that share the "ExternalBrain" name (their Documentation Repository pages currently describe the name-sharing as an accidental collision; it is better read as two fragments of the same intent):

  • The ExternalBrain project — a first pass at the knowledge graph: ExternalBrainApi (thoughts with tags, notes, URLs, and weighted connections, persisted as plain text under ~/externalbrain/) plus the ExternalBrainGui Compose Desktop app. Local-only: no server, no markdown, no graph view.
  • The Markdown project — a first pass at the authoring surface: ExternalBrainWui, the rich in-browser hybrid markdown editor deployed at my.externalbrain.wasmserver.com, backed by the MutableMarkdown stack (url://markdown/ CRUD markdown storage with API and CLI). Documents exist but do not link to each other.

The plan builds the one real External Brain out of both. The same repositories are reused — the names are already the right names — while the implementations inside them can be largely or completely blown away: what survives is decided by the salvage review in the roadmap below, not by inertia. The hybrid editor is the strongest candidate to keep, and the thoughts data model (a thought = a note with tags, a URL, and links) folds into notes-plus-links regardless of how much of its code survives.

The shape

The decisions below are settled.

The brain links; it does not own. There are bespoke services that organize domain-specific information better than any one uber-app ever could — different tasks call for different domain-specific specializations. In the interest of disintegrated, decentralized development, information stays in the system that owns it, and the External Brain makes it easy to link between systems. The brain might ingest from the External Brain Markdown Wiki Editor itself, photo albums, a contact manager, a todo-list bug tracker, filesystems, a web archive, and AI datasets — each remains the source of truth for its own items, and the brain holds notes, links, and projections of those items, never a copy it must keep in sync.

One service in the standard layered architecture. The brain is a standard layered service over url://external-brain/, with the WUI as a stateless frontend. Notes and the link graph are the brain's authoritative state: the link graph is relationship-shaped data, and the File Relational Filesystem is its intended substrate — the External Brain is that workstream's headline human-facing consumer, with note identity, links, tags, and backlinks in the graph layer and content bytes in Blobstore. The MutableMarkdown store the editor saves through today is the seed this storage layer grows out of. The full-text and retrieval index lives in SearchableBucket, edits propagate to open views via Observables, and identity and access ride on W3Wallet like every other service.

The markdown wiki editor

The frontend incorporates the External Brain Markdown Wiki Editor — the evolution of the rich hybrid editor ExternalBrainWui already ships, which renders formatting in place while hiding syntax. The editor gains what makes a wiki a wiki: [[wiki-link]] syntax with autocomplete against everything the brain knows, first-class backlinks on every document, and embedded projection chunks (below) rendered inline. The editor is deliberately just one of the brain's data sources — the first-party authoring surface, holding no privileged position over the photo album or the bug tracker in the link graph.

Widgets: projection functions

A widget is a projection function: it converts an external data item — a contact, a photo album, a group, a todo-list bug, a dataset — into a chunk of markdown that can be embedded in the editor. Each chunk carries metadata identifying which projection function rendered it and which data item it renders, so the chunk can be re-rendered (re-projected) when the source changes, and so a reader can follow the chunk back to the item in the external system that owns it.

Each data type can have one or more projection functions, so a user embeds the same item at different resolutions of detail by choosing the most appropriate projection — a contact as a one-line mention or as a full card, an album as a cover thumbnail or a contact sheet. Because a projection is markdown, an embedded item costs nothing extra to search, to diff, or to print: a brain page with its embedded widgets prints as cleanly as a plain note.

Widgets are wired up, not built in: a user registers projection functions on the settings page of the brain's UI (the registry itself is brain state — the frontend stays stateless). From there, offering them is automatic: when a url:// link is found in a document, the brain probes the linked service to ask which data types it exposes and suggests matching chips — the way Google Docs turns a pasted link into a chip, except a brain chip can be a much bigger, full-featured widget: any registered projection of the linked item, at whichever resolution of detail the user picks.

Chat with your thoughts

An LLM that uses RAG over the data within the brain lets the user chat with their own thoughts. Everything the brain holds is retrievable — authored notes and projected chunks alike, via the SearchableBucket-backed index — and answers link back to the notes they drew from, so a chat response is itself a doorway into the graph rather than a dead end.

Graph view

The graph view is for browsing documents and their links to other documents. When exploring, users can click nodes to mark them as relevant, changing their color; the color flows through to connected nodes (a "red-tree / green-tree" pattern), letting the user eliminate patently irrelevant regions and highlight potentially relevant ones as the search narrows.

Some nodes are super-popular — hundreds, thousands, even millions of references. For these, the graph view shows only the most relevant connections explicitly, plus a single link to a cloud of nodes standing in for the rest. Clicking the cloud opens a scrollable list of all remaining linked edges, each with an "add to graph" button to pull it into the visible view.

Link suggestions

The brain helps increase the connectedness of the graph by suggesting links between items — candidates surfaced from the same retrieval index that powers chat (notes that talk about the same things) and from projection metadata (notes that embed items from the same external source). Suggestions appear in the editor and the graph view; an accepted suggestion becomes a real link, so the graph's connectivity compounds with use.

Plan / roadmap

Milestones in proposed order; each earns its own detailed design in its implementation repository as it starts — this plan owns the shape, not the internals.

  • [ ] Salvage review. Inventory the first attempt — the ExternalBrain and MutableMarkdown repositories — for what is worth keeping; the hybrid editor is the leading candidate, and everything else can be largely or completely blown away. The repositories themselves are reused: the build-out lands in place, under the names that already exist.
  • [ ] Brain contract and service. The Api layer over url://external-brain/: notes, typed links, tags, backlinks, and the projection-chunk metadata contract, growing out of the MutableMarkdown stack the editor already saves through.
  • [ ] Wiki editor. [[wiki-link]] syntax, autocomplete, and backlinks in the External Brain Markdown Wiki Editor.
  • [ ] Projection functions. The widget registry (registered from the settings page) and chunk metadata contract; the url:// probe that discovers a linked service's data types and suggests matching chips; and the first real projections (at least two resolutions of one external data type) rendering, re-projecting, and deep-linking back to their source.
  • [ ] Search and chat. The brain's contents indexed in SearchableBucket; RAG chat with answers linking back into the graph.
  • [ ] Graph view. Link-graph browsing with relevance coloring and cloud-of-nodes collapse for high-degree nodes.
  • [ ] Link suggestions. Index- and metadata-driven suggestions surfaced in the editor and graph view.
  • [ ] Data convergence. Anything the first attempt captured migrates into the brain — thoughts become notes and their weighted connections become links; documents behind url://markdown/ become brain pages — so nothing authored in the naive era is left behind.

Graduation

A naive first attempt exists (ExternalBrainWui and the MutableMarkdown stack; the local thoughts system), but the product — linked markdown, projections, chat, and the graph view over one hosted brain — does not. This remains a workstream until a user can author linked notes, embed at least one projected external item, and explore them through the graph view against url://external-brain/; at that point the Documentation Repository project pages are updated to describe the unified product and this document has done its job.