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.

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.
• Privacy is in the code, not a policy. 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

However you open Second Brain Link — the Studio web app or the desktop app — the flow is the same. A short wizard walks you through it on first launch; here it is in full.

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.

Open the web app

• Go to the Studio web app — nothing to install. It opens your vault right in the browser.
• First run shows the 3-step wizard above. Drop in your export zips to seed the vault, then open the graph, notes, or chat.

Install the desktop app

• Download for your platform: macOS · Windows.
• The desktop app is the same Studio in a native window — better for working offline and keeping a vault open alongside Obsidian.

Where to go for what

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) — on the App Store and Google Play.
• Onboarding walks you through it: pick your sources → import the export zips on the phone → the brain builds locally in about a minute.

Where to go for what

Quick start

From zips to a working brain in about a minute of compute. You'll need Claude Code or OpenAI Codex, Python 3.8+, and (recommended) Obsidian. No other dependencies.

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.

Personal sources — a digital twin

Company sources — a Company Brain

That's 24 sources — 12 personal, 12 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 (sharper fuzzy matching lands in v1.2).

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.

How the AI answers — spreading activation

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 spreading activation, the textbook cognitive-science model of memory recall, 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. Built-ins: fundraising, bd, jobsearch, datamining, personalization.
• 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.

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

Each output dir must be new or empty — the builder never clobbers existing notes.

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.

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.