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. 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

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.

Personal sources — a digital twin

Company sources — a Company Brain

New sources (X, GitHub, Strava — anything with a data export) are usually just a JSON mapping.

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.

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.

Goals & dashboards

A brain is only useful once pointed at a goal. After building, run the analyzer — 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

The engine is plain Python — every command 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.