Synapse

Synapse

Automatically elaborate, transcribe, enrich, summarize, organize, and connect your notes with AI in Obsidian.

Overview

Synapse is an Obsidian plugin that uses AI to help you build, maintain, and connect your knowledge base. It detects incomplete or stub notes and proposes content expansions, transcribes audio and video media into searchable text, enriches notes with tags, internal links, and references, summarizes content, corrects formatting, organizes your vault directory structure, and recursively explores topics into interlinked knowledge trees.

Every AI-generated change goes through a proposal review system. You see what the plugin wants to do, accept or reject each suggestion, and undo any change with built-in checkpoint support. Nothing is written to your vault without your approval.

Supported AI providers: OpenAI, Anthropic, Google Gemini, and Ollama (local).

Features

Elaboration

Scans your vault for stub notes (short content, TODO markers, empty sections) and generates AI-powered content proposals. Proposals appear in a sidebar where you can edit and accept them.

Audio Transcription

Transcribes audio files embedded in your notes using OpenAI Whisper API, Deepgram, or a local Whisper installation. Includes AI post-processing to remove filler words, add structure, and extract key points.

Video Transcription (desktop only)

Downloads and transcribes YouTube and TikTok videos using yt-dlp and ffmpeg. Extracts the audio track and feeds it through the audio transcription pipeline. Not available on mobile.

Enrichment

Analyzes note content to suggest metadata tags (from a configurable vocabulary), internal links to related notes, topic links, and external references. Uses proximity-weighted scoring to find the most relevant connections in your vault. Runs automatically after elaboration, transcription, or summarization when configured.

Summarize

Summarizes URLs, transcriptions, and audio embeds found in notes. Supports bullet points, paragraph, and key-points styles. Can also create standalone summary notes from enrichment links.

Tidy

Corrects spelling and formatting errors via AI without changing content meaning. Creates a snapshot before each change so you can undo instantly.

Organize

AI-powered semantic directory structuring. Analyzes note content and suggests where each note should live in your vault. Proposes new directories when existing ones do not fit, with configurable confidence thresholds.

Deep Dive

Recursively explores a note's topics into a tree of interlinked child notes. Uses breadth-first generation with local quality scoring to decide when to stop branching. Configurable depth, quality threshold, and output folder structure (nested, flat, or AI-organized).

Shared Infrastructure

• Unified Proposal View -- a sidebar panel where you review and accept/reject proposals from all modules in one place.
• Checkpoint/Undo System -- every vault-wide operation creates checkpoints so you can resume interrupted operations or roll back changes.
• Notification Manager -- centralized notifications with status bar integration on desktop.

How it all fits together

Synapse has many commands, and several of them quietly trigger other steps once they finish. This master diagram is the canonical birds-eye view of every chain: what cascades after a single-note command, what runs standalone, what Fire Synapse runs over a folder, and how the intake folder auto-routes new notes.

How to read it

• Solid labeled edge = a follow-on step that is on by default.
• Dotted labeled edge = a follow-on step that is off by default.
• Every conditional edge names the exact setting that gates it and its default, so you can answer "does this also fire X?" at a glance.
• Diamonds are routing decisions.

flowchart TD
    subgraph perNote["a · Per-note commands — cascade after accept / complete"]
        EL["Elaborate<br/>(on accept)"]
        TR["Transcribe<br/>audio · video · image"]
        SU["Summarize"]
        DD["Deep Dive<br/>(on accept)"]
    end

    EL --> OP
    TR --> OP
    SU --> OP
    DD -->|"deepDive.autoEnrichOnAccept · default ON"| OP
    OP(["Operation completes / proposal accepted"])

    OP -->|"enrichment.autoEnrich · default ON"| ENp["Enrichment proposals<br/>tags · links · references"]
    OP -->|"title.checkAfterOperations · default ON"| TTp["Title → rename proposal"]

    SU -.->|"summarize.autoOrganizeOnSummarize · default OFF"| ORGp["Organize proposal<br/>(single note)"]
    DD -.->|"deepDive.autoOrganizeOnAccept · default OFF"| ORGp

    subgraph standalone["b · Standalone commands — no cascade"]
        SA1["Enrich"]
        SA2["Tidy"]
        SA3["REM — wikilink discovery"]
        SA4["Organize"]
        SA5["Title (manual check)"]
    end
    standalone --> SAp["Proposal only — nothing else fires"]

    subgraph fire["c · Fire Synapse — run all on a folder/note, fixed order, serial"]
        F1["1 · Elaboration"] --> F2["2 · Summarize"] --> F3["3 · Enrichment"] --> F4["4 · REM"] --> F5["5 · Tidy"] --> F6["6 · Organize"]
    end

    subgraph intake["d · Intake folder — auto-routes new notes"]
        IN["New note in intake folder"] --> IG["Debounce + idempotency guard"]
        IG --> IU{"Body is essentially<br/>one bare URL?"}
        IU -->|"no — general / mixed / text"| FT["Fire pipeline on note"]
        IU -->|yes| IC{"Classify URL"}
        IC -->|article| FA["Fetch article + Fire pipeline"]
        IC -->|"video / audio"| VS["Transcribe — stub, no-op today"]
        IC -->|unknown| FT
    end

    FA -.->|fireOnFile| fire
    FT -.->|fireOnFile| fire

Per-note cascade defaults at a glance

Standalone commands — Enrich, Tidy, REM, Organize, and a manual Title check — produce their own proposals and trigger nothing else.

This overview is the single source of truth for the command flow. For module-level detail — the exact callback wiring, the fallback path when enrichment is disabled but title checks stay on, and intake internals — see ARCHITECTURE.md, whose Fire Synapse Pipeline, Intake and Cross-Module Communication diagrams expand the subgraphs above.

Privacy and network use

Synapse runs inside your vault. It contacts a remote service only when you configure one and then trigger a feature that needs it. Every request goes through Obsidian's requestUrl API, and every request is one you set up (your provider and API key) or started yourself (running a command).

Synapse ships with no telemetry, no analytics, and no auto-update or update-check traffic of its own -- it never contacts a server on its own, and nothing about how you use it is collected or sent anywhere. If you never set an API key and never enable a cloud provider, Synapse sends nothing out.

Remote services

These are the only services Synapse contacts, what each one is used for, and what is sent:

What this means for you

• Cloud AI and transcription require an account. OpenAI, Anthropic, Google Gemini, and Deepgram each need an API key you supply in Settings > Synapse. The note content or audio you act on is sent to the one provider you selected so it can do the work, and to no one else.
• Two paths stay offline. Selected as your AI provider, Ollama sends note content only to the local endpoint you set (default http://localhost:11434) -- no account, no key, nothing leaving your machine. For transcription, the local Whisper option is designed to run entirely on-device for the same reason. Use these if you want Synapse to work without sending anything out.
• Content you link is fetched from third-party sites. When a note references a tweet or a web page and you run elaboration, enrichment, or summarize, Synapse requests that URL to read its content -- from Twitter/X (falling back to the fxtwitter and vxtwitter mirrors) or from the site itself. To avoid this, don't run those features on notes whose links you would rather not request, or turn the feature off in settings.
• Video transcription downloads the video. On desktop, video transcription invokes yt-dlp to download the source from YouTube, TikTok, or another platform, then extracts and transcribes the audio locally.
• Audio and video transcription use privileged desktop access. To work with yt-dlp, ffmpeg, and ffprobe, the desktop build reaches outside the vault in two ways, both gated to desktop only (mobile never runs this code):
  • Direct filesystem access. Synapse writes scratch files -- downloaded media, extracted audio, clipped or concatenated segments -- to your operating system's temp directory (os.tmpdir()), never inside your vault. These temp files are removed when the operation finishes, on both success and failure. The finished video, if you opt to keep it, is the only artifact saved into the vault (in your configured download folder).
  • Local shell execution. Synapse runs the external tools as child processes with execFile and an explicit argument array -- never a shell command string -- so there is no shell interpolation of URLs, paths, or titles. URLs and file paths are sanitized first (sanitizeUrl / sanitizePath), the subprocess inherits a narrowed environment (essentially just an augmented PATH plus HOME), and the binaries that run are exactly the yt-dlp path and ffmpeg path you set in settings.

Synapse proposes, you decide -- and that holds for the network too: nothing is requested until you ask for it.

Installation

Synapse is not yet published to the Obsidian Community Plugin directory. To install manually:

1. Clone the repository:

   git clone https://github.com/dustinkeeton/obsidian-synapse.git
   cd obsidian-synapse
   

2. Install dependencies and build:

   npm install
   npm run build
   

3. Copy the built plugin into your vault:

   mkdir -p /path/to/your/vault/.obsidian/plugins/synapse
   cp main.js manifest.json styles.css /path/to/your/vault/.obsidian/plugins/synapse/
   

4. Open Obsidian, go to Settings > Community plugins, and enable Synapse.

Install via BRAT (Beta Reviewers Auto-update Tester)

If you prefer automatic updates during the beta period:

1. Install the BRAT plugin from the Obsidian Community Plugin directory.
2. In BRAT settings, click Add Beta Plugin.
3. Enter dustinkeeton/obsidian-synapse and click Add Plugin.
4. Enable Synapse in Settings > Community plugins.

BRAT will automatically check for updates and notify you when new versions are available.

External tools (optional)

For video transcription, you need these tools installed and available on your PATH:

• yt-dlp -- downloads video from YouTube, TikTok, and other platforms
• ffmpeg -- extracts audio from video files

Use the command Synapse: Check dependencies to verify these are available.

Verifying releases

Release assets are signed with GitHub artifact attestations, letting you cryptographically confirm they were built from this repository. After downloading a release, verify an asset with the GitHub CLI:

gh attestation verify main.js --repo dustinkeeton/obsidian-synapse

Repeat for manifest.json and styles.css as needed.

Configuration

Open Settings > Synapse to configure the plugin. All features can be individually enabled or disabled.

AI Configuration

Each API-key field carries a Get an API key → link to the right provider's console and a Test button that makes a minimal authenticated request and reports ✓ Connected or ✗ Invalid key inline -- so you can confirm a key works before running a feature, instead of discovering a typo later. The same helpers appear on the per-provider transcription key fields, and Ollama's endpoint gets a reachability Test. Keys are still entered manually: a one-click OAuth "connect" flow isn't offered because the major providers don't support third-party API access that way (see DECISIONS.md).

Elaboration

Audio Transcription

Video Transcription (desktop only)

Enrichment

Summarize

Tidy

Organize

Deep Dive

Exclusions

A single, cross-cutting list controls which vault paths Synapse may touch. Each rule names a path pattern and the features it blocks, so you can hide a folder from everything or from just a few flows. Path exclusions live here for every feature; tag exclusions (Excluded tags) stay per-feature.

By default, .synapse/** (the plugin's own data folder) and templates/** are excluded from all features — including audio/video transcription, OCR, the intake watcher, and title checks, none of which had folder exclusions before. Existing vaults are migrated automatically on upgrade: folders you had excluded from every module broaden to all features, while a folder you scoped to a single feature stays scoped to it.

Patterns are vault-relative and case-sensitive, and metacharacters such as . are matched literally (so .synapse/** never matches Xsynapse/...). Add a folder with the picker (saved in canonical folder/** form) or type an exact path / folder/* pattern directly, choosing the scope up front. Each rule shows the features it blocks as a row of chips: pick All features, or add individual flows from the "+ Add feature" dropdown. Remove a chip (✕) to narrow the rule; a rule with no chips is inactive and blocks nothing.

When a batch or vault-wide scan hits an excluded note it skips silently; an explicitly invoked single-note command refuses with a notice naming the rule that matched.

Development

Prerequisites

• Node.js
• npm

Setup

git clone https://github.com/dustinkeeton/obsidian-synapse.git
cd obsidian-synapse
npm install

Scripts

Project Structure

The plugin is organized into 8 feature modules plus a shared utilities layer. Each module follows a consistent contract with onload() and onunload() lifecycle methods.

src/
  main.ts              Plugin entry point and module orchestration
  settings.ts          Settings interfaces and defaults
  settings-tab.ts      Settings UI
  elaboration/         Stub note detection and proposal generation
  audio/               Audio transcription
  video/               Video download and transcription (desktop only)
  transcription/       Unified transcription UI modals
  summarize/           Note summarization
  enrichment/          Tags, links, and references
  deep-dive/           Recursive topic exploration
  organize/            Semantic directory structuring
  tidy/                Spelling and formatting cleanup
  shared/              AI client, file utils, notifications, checkpoints
  views/               Unified proposal review sidebar

Build output is a single main.js bundle produced by esbuild.

Testing in Obsidian

For development, symlink or copy the built plugin into your vault:

# From your vault's plugin directory:
ln -s /path/to/obsidian-synapse .obsidian/plugins/synapse

Then run npm run dev to rebuild automatically on changes. Reload Obsidian (Cmd+R / Ctrl+R) to pick up changes.

Support

Synapse is free and open source. If it has earned a place in your workflow, you can support continued development:

License

AGPL-3.0