Second Brain Link Documentation

Introduction

Your life is scattered across platforms — connections on LinkedIn, friends on Facebook, follows on Instagram, contacts and calendar in Google, code on GitHub, taste on Spotify. Each gives you a data export, and each sits dead in a zip. Second Brain Link pulls them into one structured knowledge vault your AI can think with — and the same person across two networks becomes a single, richer note.

Why this matters more each quarter: the model you point at the vault is rented, interchangeable and getting cheaper, and every competitor rents the same one. The vault is the part nobody else has. A better model released next year reads the same graph and gets more out of it — you rebuild nothing to collect that. Models depreciate; your graph compounds.

1. You download your own data archive(s) — from one network or several. They're yours; each platform provides them on request.
2. Second Brain Link runs 100% locally, detects which source(s) you've given it, and transforms them into one clean Obsidian vault: people, companies, your voice, your career intent, your interests, and how the algorithms categorize you.
3. You point Claude (or Codex) at the vault. Now you have a digital twin that knows your whole history across platforms and can reason, plan, and draft from it.

Why it's different

• Local-first and private by construction. The transform makes zero network calls; your data never leaves your machine.
• Custody is the security model. Your history is already spread across a dozen services you can't search and don't control; this gathers it on a machine you do. Contacts' emails and phone numbers are stripped at parse time; message bodies are never imported — only a "how often / how recently" signal.
• You own the output. Plain Markdown, no lock-in.
• MIT licensed, free, no catch.

Using the app — 3 steps

The desktop app (Mac, Windows, Linux) sets itself up: on first launch its Setup installs everything this computer needs, one button per step. The full walk-through, per system, is on the download page.

Install with your AI, or in one line

In Claude Code, Codex or Claude Desktop, paste: “Install Second Brain Link on this computer by following https://secondbrainlink.com/install.md” — it follows the install guide for your system and asks before each step. Or run the installer yourself (no git; it installs the brain builder and the agents for every AI tool it finds, checksum-verified):

Second Brain Studio — web & desktop

Studio is the friendly front door to your brain: a live workspace where you browse the knowledge graph, read & edit notes, and chat with an AI that reasons over everything. It runs locally — your API keys and data stay on your machine. Since v1.2 it also has a Map view and Agents. The hosted web Studio at secondbrainlink.com explores a demo brain; building your own, reseeding and running agents need the desktop app (whose Setup installs everything for you — step by step) or the web Studio run locally.

Open the web app

• Go to the Studio web app — nothing to install. It opens a demo brain right in the browser.
• First run shows a short welcome and offers a guided tour: explore the graph, notes and chat. To build your own brain, use the desktop app below.

Install the desktop app

• Download for your platform: macOS · Apple silicon · macOS · Intel · Windows · Linux AppImage / .deb.
• The desktop app is the same Studio in a native window — better for working offline, keeping a vault open alongside Obsidian, and the only place agents run. It auto-updates from the public releases repo.
• First launch opens Setup: pick your AI, and it installs it, signs you in and adds the brain builder and the agents — Python is built in. Reopen it any time from Help ▸ Set Up Second Brain… Step by step.

Where to go for what

Agents

A section of the left dropdown (Work › Agents), beside Inbox, Goals, Routines and Activity. Pick an installed plugin agent and the chat is grounded in that plugin rather than the whole brain: its grounding note is read on your machine, the session is one long-lived Claude Code process (steerable mid-run, resumed after a reload), and the note the agent writes — a dashboard, an application, a funding plan — repaints beside the conversation the moment the write lands. When the agent needs a decision, the question arrives as option buttons plus a free-text field and is answered in the same turn. The gear opens per-agent settings — a CV, a deck, a facts file, your Maps key — all read from disk, nothing uploaded.

Map view

• Brain › Map in the left dropdown draws every geo-tagged note on a map: places, plus the people and organizations the offline geocoder could place. Filter by country and kind of place.
• The map tiles come from Google Maps — Studio's own key, or yours if you add one (AI settings → Advanced). The geocoding itself never calls the network — it uses a bundled gazetteer.
• A map agent (the Travel Agent, v0.2.0 developer preview) swaps the centre canvas for the Map, redraws it on every itinerary change, and turns a click on a pin into a turn in the chat. The Sales Agent (v0.2.0 developer preview) draws its pipeline the same way — in Runtime › Lines, from its pipeline.json; a click or a drag is a chat turn, and the canvas never writes a file.

AI providers

Studio talks to the AI you choose in Settings → AI. Cloud providers are called directly from your browser or the desktop app with your own key, which stays on your device — there is no server of ours in between. Those requests carry the notes needed to answer, so that provider sees them; pick alocal one (Ollama, LM Studio) if a brain should never leave your machine.

The agents (Jobs, Fundraising, Travel) run through Claude Code. Building the brain itself never needs an AI — it is deterministic and local.

Agents & plugins — the brain that acts

The engine builds a brain and makes zero network calls doing it. A plugin uses a brain to do one job: it reads the vault, acts in the world, and writes its results back as a normal vault layer. A plugin that ships a studio.json becomes an Agent in Studio. Four ship today; the full tour is on the Agents page.

Install a plugin

In the desktop app: Setup installs the agents with the brain builder, and each agent's card in Agents has its own Install button (Settings ▸ Setup also checks GitHub for newer versions). With Claude Code or Codex: the one-line installer or the per-agent files on the download page. From source (developers):

claude plugin list shows an installed plugin as <name>@skills-dir. Both Studios read the same install, so one command serves the CLI, the desktop app and a locally-run web Studio. A symlink in ~/.claude/skills is the developer install; --install refuses to overwrite it.

The four agents

Autonomy, gates and the tool ceiling

• level: lives in your own profile note. supervised is the shipped default; autonomous is a word you type yourself — never a default, never inferred from how you phrased a request. The Travel Agent (v0.2.0 developer preview) ships as research.
• Credentials are never typed. A password, passport or ID number, card, date of birth, CAPTCHA or account-creation step stops that one item at every level.
• A plugin may request tools; it cannot grant itself any. Studio's ceiling is skills, sub-agents and your own Chrome. Studio asks the CLI's questions through a control_request and renders them as buttons.
• Working files never live inside the plugin. In a brain they go to the hidden .plugins/<name>/; the visible layer is the notes you read. Plugins never hardcode a vault layer and ship nothing personal.
• Where they run: the desktop Studio, or the web Studio run locally, through your own Claude Code CLI and subscription. The hosted secondbrainlink.com Studio does not run agents. Codex gets the same plugins as flattened skills without browser tooling — no form-filling, no shopping.

Build your own: copy a shipped plugin, change the job, keep the three rules. The contract is plugins/README.md in the repo; the shape is on the Agents page. What runs an agent without you opening a chat — Goals, Routines, the Inbox and Activity — is a developer preview: it runs on your machine while it is awake, and every background option is off until you turn it on.

Memory — agents that remember and compound

Every Studio chat and every agent (Jobs, Fundraising, Travel) keeps a memory inside your own brain. It is plain Markdown you can read, edit and delete, recalled at the start of every run, and it grows from two things: what you tell it and what verifiably happened. Developer preview.

The loop every run follows

1. Recall — the run loads the memories that matter for this task and says in one line which ones changed what it did.
2. Act — the answer, the shortlist, the plan, the itinerary.
3. Capture — what you said (a preference, a rule, a correction) and what happened (a reply, a rejection, a rating) are saved the moment they happen.
4. Reflect — at the end, at most three lessons the agent learned, saved automatically and flagged as inferred.

What gets remembered

• You said it — used from the next run on; every save shows Remembered · Undo. Nothing needs your approval by default.
• It verifiably happened — used from the next run on, with the evidence attached.
• The agent learned it by itself — saved and used automatically too, flagged as inferred so you can see it, edit it or forget it. Prefer to approve first? Switch the brain to Ask me first in the Memory manager.

A new observation that means the same as an existing memory strengthens it instead of adding a duplicate, and recall is ranked and budgeted — so memory gets sharper, not longer. That is how the agents compound: every correction is taught once, every outcome adds evidence to the lesson it confirms, and facts about you reach every agent. There is no model training, no embeddings and no vector store, and nothing leaves your machine.

Where it lives

Manage it

• Memory manager — the brain icon in the chat header: a tab per brain, per agent and for shared facts; Active, Waiting for review and Retired; Save automatically (default) or Ask me first; edit, retire, restore, forget, or add a memory yourself.
• 👍 / 👎 on every answer — a thumbs-down asks what was wrong and remembers it as a correction.
• In any agent chat, just say it: forget that, reword m-… to …, what do you remember about me?
• Settings → Memory turns recall off for a brain.
• From a terminal: memory.py recall · observe · review · approve · reject · forget · sync — ships with Second Brain Link and every plugin; sync picks up edits you made to the notes by hand.

Second Brain Mobile — iOS & Android

The native mobile app is the whole pipeline in your pocket: it unpacks your exports and builds the brain entirely on-device — no account, no backend, nothing uploaded. Explore the knowledge graph, browse your sources, and talk to your twin wherever you are.

Get the app

• Download on the App Store (iPhone) · Get it on Google Play (Android) — free, no account; the brain is built on the phone.
• Onboarding walks you through it: pick your sources → import the export zips on the phone → the brain builds locally, on the phone.

Where to go for what

Quick start

The terminal route, from zips to a working brain on your own machine. You'll need Claude Code or OpenAI Codex, Python 3.8+, and (recommended) Obsidian. No other dependencies. Rather not use a terminal? The desktop app needs none of this — its Setup installs your AI and the skill, with Python built in.

Supported sources

Give it one source or a combined archive with several — it detects and merges them all. Unknown files are summarized, never dropped. For the full connector directory — what each source contributes, where it maps in the brain, and the roadmap — see the Sources page. Each source also has its own export guide with the questions a brain built from it can answer — for example LinkedIn, Google Takeout, Slack and Notion — and the generated vault opens as an Obsidian second brain.

Personal sources — a digital twin

Company sources — a Company Brain

That's 27 sources — 13 personal, 14 company — every one detected automatically. Anything else with a data export is usually just a JSON mapping away, and files no source claims are rescued by the universal harvester, summarized in _COVERAGE.md — never dropped.

How it works

Every network changes its export format over time and across regions. A hardcoded converter breaks the moment that drifts — so Second Brain Link detects, adapts, builds, then verifies it left nothing behind:

1. Detect + profile. Identifies the source(s) in your archive, reads every file and column, and writes a schema_map.md — each file classified, each column typed, with privacy-safe samples. It also draws a mindmap and designs the brain structure.
2. Adapt. Each source is a declarative JSON mapping (engine/mappings/sources/<name>.json). Files no mapping claims are rescued by a universal harvester and flagged in _COVERAGE.md under "Needs a mapping". Only genuine unknowns need your AI — it reads the schema map (never your raw data) and proposes a mapping.
3. Build. A deterministic, dependency-free Python engine writes the entire unified vault in seconds with zero AI cost, merging people who appear in more than one source.
4. Verify (+ correlate). _COVERAGE.md reports how much of your export was used; _SUMMARY.md gives seed counts. Anything unrecognized lands in 99-uncategorized/ — nothing is silently dropped. Multiple entities get a _correlations/ brain linking them. Once built, asking the brain runs graph-grounded retrieval — see How the AI answers.

Self-adapting: the skill fixes itself

Platform exports drift — new files, renamed columns, regional variants, format changes between the export you took last year and the one you took today. The skill is built to absorb that drift on your machine, using the AI only on the residual:

1. Schema map first. The profiler reads every file and column in your archive and writes schema_map.md (PII-safe — column names only). Known shapes route to sources; unknowns are flagged, never guessed at.
2. Declarative mappings, not hardcoded parsers. Most sources are JSON mappings under mappings/sources/. When your export has an extra field or a renamed file, the AI extends the mapping — or drops a mapping_overrides.json beside your data — instead of waiting for a code release. A mapping override wins over the built-in adapter.
3. The harvester rescues the rest. Files no source claims go through a universal shape recognizer (people / places / posts / interests / message signal), so data lands in the brain even before a proper mapping exists. They're listed in _COVERAGE.md under "Needs a mapping" — the self-improvement backlog.
4. Self-heal on failure. If a build errors, the engine writes a structured _ERROR.md naming the script, the file and the line. The AI applies the smallest fix, mirrors it, and re-runs — no human debugging session required.
5. The ratchet. Every adjustment is durable: the extended mapping keeps working on your next export, and _DATA_POINTS.md's field-by-source matrix shows exactly which new cells lit up.

This is why the honest pitch is deterministic core, AI on the residual: the build itself costs zero tokens, and intelligence is spent only where your export genuinely differs from the known world.

Identity resolution

If "Sam Patel" is a LinkedIn connection, a Facebook friend, and a Google contact, you don't get three notes — you get one, tagged sources: [linkedin, facebook, google], with company and role filled in from whichever source knew it.

People who appear across multiple networks are surfaced as your strongest multi-context relationships. Matching is conservative by design — a wrong merge is worse than a miss (broader matching lands in v1.2).

The ontology

A built brain is more than a folder of notes: it carries an ontology — the object types in it and how they relate — derived deterministically from each note’s type, category and kind. No AI decides what an object is. The rules live in the engine (engine/mappings/brain/ontology.json), so every company brain uses the same words.

Object types and relations

Company objects: Organization (the company itself), Person, Account (a customer company), Team, Channel, Project, Wiki space, Deal, Campaign, Post, Meeting, Document, Place, Market view. A personal brain uses its own twins (Me, Person, Company, Application, Event, Purchase…). Ticket volume stays a number on an Account — there is no Ticket object, on purpose.

Relations are the typed edges between notes, read with a fixed verb and direction: works at, contact at (a person at an account), member of (team, channel, project), deal for, posted by, attended, authored by, mentions, filed under. The same verb appears in Studio’s Ontology view, in the Inspector, in Relationships and in the data catalog, so an edge never reads two ways.

Resolved (matched by name), and where each field came from

Resolved means found in two or more exports and matched by name, so one person seen in Slack, Workspace and LinkedIn is one note (sources: [slack, google_workspace, linkedin_company]). Matching is name-only and precision-biased — a wrong match is worse than a miss — and no AI decides a match. (It is not the “unresolved” of _HEALTH.md, which counts wikilinks with no note behind them.) On a resolved person or organization, field_sources: records which export supplied each field (company: hubspot), which Studio reads as “Company · from HubSpot”.

Where it lives

graph.json carries an ontology block — objects (label, meaning, count, sources, resolved count), relations (edge type, from, to, label, inverse, count), questions (the starters Home and the chat offer), metrics and merged_nodes — computed by counting real triples, nothing guessed. The edges themselves are unchanged, so retrieval is untouched. Before a build, brain_structure.md shows Before you build — the ontology these exports will make: the objects and relations the detected exports will produce, as a diagram and a table, so you can read it before anything is written. Build when it reads right; when it does not, exclude a source or adapt a mapping first.

Exact, counted answers

scripts/query.py answers from the built brain by read-only SQL over its notes: --ask objects (every object type with count and resolved count), --ask relations (every relation with its count), --ask accounts-by-deals (accounts by deal count and total value), --ask orgs-by-people (organizations by how many people in the brain are linked to them) and --ask top-by; add --json for machine output. These are the numbers a chart is allowed to use: in Studio’s chat a chart card is drawn only when its spec says what it was counted from (how many notes, which sources) — otherwise it stays plain text.

In Studio, the Ontology tab has three views. Architecture (How this brain is built, also a fold on the Dashboard) draws the brain as an isometric stack: the exports and the model at the base, the ontology in the middle as a molecule — one atom per kind of note, sized by how many there are, bonded by the typed relations between them — and answers, agents and the tools it opens in on top; the model is the current that runs through it. Data model (What this brain is made of) is the card diagram of object types, their fields and the relations between them. Relationships centres one note (Show relationships in the Inspector) and lights every note it is linked to, grouped by typed edge. The How it works page draws all three with the same renderers, fed the Acme and John demo brains.

The vault it builds

A layered, Obsidian-native vault. _STRUCTURE.md is the map — it documents what every folder and file is, so you (or an agent) always know where things live.

Obsidian-native by construction

• The graph is real. Filenames equal titles, so [[Acme Cloud]] resolves to the actual note — open Graph view and you literally see your network.
• Properties work. Valid YAML frontmatter with native Properties: type, strength, ISO dates; wikilinks in properties are quoted so backlinks resolve.
• Tags & filters. Every note carries source/<name> + type tags so the graph and search filter cleanly by where each fact came from.
• One brain per entity. Multiple identities/companies each get their own vault, plus a _correlations/ brain with works_at edges between them.

Update your brain from a newer archive (--refresh)

An export is a snapshot. When you download a newer one, run the same build with --refresh (or choose Update in Studio's reseed dialog) and the brain is updated in place rather than rebuilt:

• _GENERATED.json is the manifest — stable note IDs, so a person or place keeps its file and its backlinks across refreshes.
• Your edits win. A note you changed is kept; the fresh version is written beside it as <name>.new.md for you to merge or discard.
• _notes/ and the agent layers (45-jobs, 46-fundraising, 47-travel) are never touched — they keep their own manifests.
• _UPDATE_REPORT.md summarizes the run honestly: added, updated, pruned, kept-because-edited. Running it twice on the same archive changes nothing.

How the AI answers — Brain recall

When you ask your brain a question, the query flows through the graph, not just over its text. Retrieval is deterministic, client-side, and makes zero network calls — the brain fires before the model speaks.

1. Seed. Your words, matched directly against note titles, aliases and body keywords. The notes that match become the input activations — nothing hidden, nothing inferred.
2. Spread. Activation propagates along your real links — the typed, weighted edges the engine built from your exports. That's why an old note two hops away from your question still surfaces: the graph carries it there. This is Brain recall — modelled on the textbook cognitive-science account of how memory recall spreads along links — computed as Personalized PageRank.
3. Pack. The top-activated notes, plus the typed relationships among them, become a plain-text context pack — something you could open and read yourself.
4. Answer. The model must answer from the pack, and the answer cites the notes it used. No pack, no claim.

Why you can trust the animation

The Neural view — the layered view, your vault's layers as columns — animates the wave, and every number in it is real: seed pulses, arrival order and brightness all come from the retrieval run. An edge only lights if it genuinely connects two activated notes. No fake cascades, no fake ML.

The anatomy it fires through

Studio renders every vault as tissue, at every scale — the same anatomy the wave travels:

• Cells — real sub-clusters computed from the link graph: each cell is a genuine hub note plus the notes that actually link to it. Deterministic — same vault, same anatomy.
• Membranes & tissue — soft outlines around cells and smooth blobs around regions delimit the structure without hiding anything.
• The halo — notes with no links yet hold a seat on the rim, visible until the graph grows around them.
• Cells that open — hover names a cell, click opens it in place, “only this” isolates it. Counts are always honest: showing N of M.

At 25,000 notes

Big vaults stream metadata first: the full anatomy renders and searches instantly, and note bodies load on demand the moment you open one. 100% of notes stay visible and discoverable — nothing is sampled away.

Goals & dashboards

A brain is only useful once pointed at a goal. After building, just tell your agent what you want the brain for:

The skill runs the analyzer for you — deterministic and re-runnable in seconds (it reads frontmatter, no rebuild):

It writes:

• 95-goals/<goal>.md — ranked tables answering the goal, each ending in a ready-to-run AI prompt. Seven built-ins: fundraising, bd, jobsearch, datamining, personalization, and for a company brain onboarding (who to meet, which teams exist, where conversations happen) and whoknows (the expertise and ownership map). Default run: fundraising, bd, jobsearch.
• Dashboard.md — live Dataview tables: warm/dormant ties, network-by-company, a by-source breakdown.
• _DATA_POINTS.md — every node type + relation + a field-enrichment-by-source matrix + a "mineable questions" catalog.
• _GRAPH.md + --graph-config — colors the global graph by source and type (merges into .obsidian/graph.json, preserving your settings).
• copilot-prompts/ — one-click /commands for Obsidian Copilot: /warm-intro, /investor-paths, /reconnect, /job-fit, /mine, /for-me, /ask-my-network.

Obsidian integration

Two ways to put an AI directly in your vault — both install from Settings → Community plugins:

The answer can be an artifact, not just a chat reply. Because the agent can write into the vault, ask for the output as a file: a .canvas board of your warmest investor paths, a live Dataview dashboard of dormant contacts, a note comparing 50-mirror/ to how you describe yourself. Whatever it generates follows the builder's conventions, so it's instantly first-class in the graph.

CLI reference — under the hood

You normally never type these — you prompt the skill and it runs the engine for you (and adapts the commands to your export). They're documented for transparency, for self-hosters, and for the AI itself: the engine is plain Python and every command also runs without the Agent Skill installed.

Flags

A fresh build wants a new or empty output dir — it never clobbers notes it did not write. --refresh is the only way it touches an existing brain, and then only through the manifest.

analyze.py & profile_export.py

• analyze.py <brain> --goals fundraising,bd,jobsearch,datamining,personalization,onboarding,whoknows — plus --icp / --thesis to steer bd and fundraising, --copilot-dir for the Obsidian Copilot prompts, --graph-config / --graph-data for the graph colouring.
• profile_export.py <source> --out <dir> — the PII-safe schema map and mindmap; --no-mindmap, --no-structure, --doctor.
• packaging/build_skill.py [claude|openai|all] [--install] and packaging/build_plugin.py [<name>|all] [--provider claude|openai|all] [--install].

Adding a source

Anything with a data export can become part of the brain. In order of preference:

1. A declarative JSON mapping — engine/mappings/sources/<name>.json: a detect block plus records[] that locate arrays and pluck fields via a tiny selector language into canonical col.add_* verbs. No Python, no engine edit. A mapping wins over a same-named Python adapter and can ship via --mappings <dir>.
2. A Python adapter — only for bespoke cross-file logic: one file in engine/scripts/sources/personal/ or …/company/ (set SUBJECT="company" for company sources). Auto-discovered, no registry edit.
3. An output target — one emitter file in engine/scripts/emitters/.

Either way the builder, privacy rules, Obsidian/GBrain output, and cross-source merging all work unchanged. Files no mapping claims are caught by the universal harvester and listed in _COVERAGE.md under "Needs a mapping" — your cue to add a rule for precision.

Project layout

One provider-neutral engine does the work; thin per-provider manifests ship it as a cross-model Agent Skill (the Agent Skills open standard).

Privacy model

• Zero network calls in the core transform — verifiable in engine/scripts/.
• Third-party PII stripped at parse time — across every source, contacts' emails and phones never become notes.
• Message bodies never written — only a per-person count + last-contact date, which grades relationship strength.
• Sensitive files never imported — Logins, Receipts, Security Challenges, ImportedContacts and friends stay in your original archive, listed in _quarantine/.
• The schema map redacts sensitive columns and masks any email/phone in samples.
• Three network tiers, never blurred. The transform makes zero network calls. Model turns go through your own Claude Code or Codex CLI, on your subscription. Acting on the web is a plugin's job: each declares its endpoints in its manifest and reads them in your own browser, behind approval gates and a tool ceiling it cannot raise (see agents).

Never commit your vault to a public repo — the generated .gitignore guards against accidents. Full write-up: the privacy model.

Roadmap

Contributing

The most valuable contribution right now: run it on your real export and open an issue if any file or column didn't map cleanly — the schema_map.md it generates is exactly what we need to see. Parser robustness across the long tail of real accounts is how this gets great.

Created and maintained by Adrian Vicovan. Questions? Use our contact form.