What It Is & Why It Exists
Modern productivity tools have backed knowledge workers into a corner: your thoughts, journals, plans, and confidential projects are stored in remote cloud databases, monetized through subscriptions, held hostage behind proprietary sync protocols, and ingested to train third-party AI models. When the server goes down, your network drops, or a SaaS vendor pivots, your second brain vanishes.
Synapse OS is the antidote.
Synapse OS is an open, private, local-first personal knowledge operating system designed to manage your notes, tasks, projects, meetings, and ideas with uncompromising performance and complete autonomy.
Core Philosophy
- 🔒 100% Data Ownership: Every piece of your data lives on your physical disk. Notes are standard Markdown (
.md) files that remain readable in any text editor for the next 50 years. Metadata and relationships are indexed in an open SQLite database you can inspect with standard SQL tools.
- 🛡️ Privacy by Design: Zero tracking, zero analytics beacons, zero cloud telemetry, and zero remote API calls required. Ollama runs on
127.0.0.1, keeping your thoughts, questions, and embeddings strictly confined to your hardware.
- ⚡ Offline First, Always Fast: Everything loads in milliseconds. With no round-trip network hops, search queries and database updates execute with the raw speed of native C/C++ SQLite bindings.
- 🧩 Extensibility Without Lock-in: You are never trapped in a walled garden. Point your Synapse vault to an existing Obsidian or VS Code directory, synchronize changes via Git, and own your digital workspace end-to-end.
Core Features
🧠 Private AI Chat (On-Device Intelligence)
Engage in deep, contextual conversations with your knowledge base without transmitting a single byte over the Internet.
- Powered by Ollama: Seamless native integration with local LLMs (such as Llama 3, Qwen 2.5/3, Mistral, and Phi 3) running directly on your machine.
- Knowledge Retrieval & Grounding: Ask Synapse questions across your entire library—it queries your notes, tasks, and meetings, synthesizes coherent answers, and provides direct source citations.
- No Leaks, No Subscriptions: Get state-of-the-art conversational AI without recurring monthly API bills or privacy compromises.
📝 Markdown Vaults (Future-Proof Plain Text)
Your ideas should outlive any application.
- File System Source of Truth: Every note is saved as a discrete Markdown file inside your chosen vault folder.
- Bi-Directional Sync & Reindexing: Edit notes inside Synapse, in Obsidian, or via Neovim/VS Code. Synapse detects file changes, extracts frontmatter and tags, recalculates content hashes, and reconciles the SQLite index seamlessly.
- Wikilinks & Knowledge Graph: Connect thoughts using
[[Note Title]] syntax and explore your interconnected web of ideas through an interactive force-directed graph.
🔍 Instant Full-Text Search (FTS5 & SQLite Power)
Instantaneous recall across your entire repository.
- Lightning Performance: Powered by local SQLite (
better-sqlite3) with WAL (Write-Ahead Logging) enabled.
- Comprehensive Filtering: Perform sub-millisecond, accent-insensitive searches across titles, descriptions, markdown bodies, projects, and tags.
- Unified Results: Access both active notes and tasks from a single, keyboard-driven interface.
🛠️ More Operating System Capabilities
- Task & Project Management: Organize work with dependencies, due-date urgency badges, status states, and project hierarchies.
- Visual Workflow & Timeline: Interactive Gantt-style timeline grouped by deadlines and urgency—no external services needed.
- Capture Inbox: Frictionless quick-capture for raw thoughts, links, and snippets with quick triage into permanent notes or actionable tasks.
- Calendar & Meeting Sync: Parse ICS calendar feeds, manage meeting notes, track attendees, and automatically surface upcoming agendas.
- Security & Authentication: Optional single-user login with scrypt password hashing, session tokens, and local secret management.
Architecture & Tech Stack
Synapse OS is architected for extreme responsiveness, simplicity, and rock-solid reliability. We deliberately favor plain SQL, explicit data flows, and minimal abstractions over heavy ORMs.
┌────────────────────────────────────────────────────────┐
│ Next.js UI │
│ (React 19, Server Components, Tailwind CSS) │
└───────────────┬────────────────────────┬───────────────┘
│ │
Server Actions / APIs Local REST / Chat
│ │
▼ ▼
┌──────────────────────────────┐ ┌──────────────┐
│ Core Lib Engine │ │ Ollama LLM │
│ (TypeScript + Zod) │ │ (127.0.0.1) │
└───────┬──────────────┬───────┘ └──────────────┘
│ │
▼ ▼
┌───────────────┐ ┌───────────────┐
│ SQLite (WAL) │ │ Markdown │
│ better-sqlite3│ │ Vault Folder │
└───────────────┘ └───────────────┘
| Layer | Technology | Rationale |
|---|
| Framework | Next.js (App Router, React 19) | Modern server components, instantaneous Server Actions, and strict zero-bundle-overhead rendering. |
| Language | TypeScript | End-to-end type safety across domain logic, database records, and UI components. |
| Styling | Tailwind CSS | Cohesive dark-neutral design system crafted for deep focus and long reading sessions. |
| Database | SQLite via better-sqlite3 | Synchronous, ultra-low-latency embedded database in WAL mode with plain SQL queries—no ORM overhead. |
| Schema Migrations | Plain SQL Migrations (migrations/*.sql) | Numbered, transactional, append-only migration pipeline executed safely on boot. |
| Local AI | Ollama | Standardized REST API for on-device, GPU-accelerated open-weights model inference. |
| Validation | Zod | Strict runtime validation for forms, API endpoints, and configuration schemas. |
| Testing | |
Getting Started (Local Development)
Synapse is one Next.js app for synapse-os.ca: the public website (src/app/(public)), login (src/app/(auth)) and the app (src/app/(app)). In production the app and login run on app.synapse-os.ca (set by NEXT_PUBLIC_APP_URL); src/proxy.ts maps app.synapse-os.ca/notes to the /app/notes route. Without that variable (local development, previews) the app stays under /app. To try the subdomain locally, set NEXT_PUBLIC_APP_URL=http://app.localhost:3000 and NEXT_PUBLIC_SITE_URL=http://localhost:3000, then open http://app.localhost:3000. Data lives in Supabase; the AI runs in each user's own Ollama, called from the browser.
1. Prerequisites
- Node.js 24 and npm
- Docker Desktop (runs the local Supabase stack)
- Ollama for the local AI (ollama.com), with a model:
ollama pull qwen3:8b
2. Install and start the local database
git clone https://github.com/SamuelRosengarten/Synapse-OS.git
cd Synapse-OS
npm install
npm run db:start # local Supabase in Docker (first run downloads a few GB)
npx supabase status -o env
Copy .env.example to .env.local and fill in NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY and SUPABASE_SECRET_KEY from the API_URL, PUBLISHABLE_KEY and SECRET_KEY lines of supabase status.
Public sign-up is off. npm run db:reset loads two local test users from supabase/seed.sql: [email protected] and [email protected], both with the password dev-password. They exist only in the local database. Emails sent by the local stack (password resets) appear at http://127.0.0.1:54324.
SYNAPSE_LEGACY=1 keeps the not-yet-ported SQLite pages (meetings, ...) under /app on your machine. Leave it out to see exactly what Vercel serves.
Try a branch before merging it
Docker Desktop must be running, and .env.local must point at the local stack (http://127.0.0.1:54321; the script refuses anything else).
git switch S2-8-notes-ui # the branch to try
npm run db:start # once per boot
npm run dev:fresh # resets the LOCAL database (applies the branch's migrations), then starts the app
Open http://127.0.0.1:3000/login and sign in as [email protected] / dev-password. Use a private window with [email protected] to check that two users do not see each other's data.
npm run dev:app starts the app without resetting the database. Both show the Supabase pages only, like the live site. Add -- --legacy to also see the old SQLite pages. npm run dev:fresh erases the local data each time, never the cloud project's.
3. Run and test
npm run dev # http://127.0.0.1:3000
npm test # unit tests (no database needed)
npm run test:int # integration tests against the local Supabase (db:start first)
npm run db:test # pgTAP tests: row-level security, triggers, beta requests
npm run typecheck
npm run build
Deploying to Vercel
Environment variables (Vercel > Project Settings > Environment Variables)
| Variable | Production | Preview | Notes |
|---|
NEXT_PUBLIC_SUPABASE_URL | https://<project-ref>.supabase.co | same | Supabase > Project Settings > API Keys |
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY | sb_publishable_... | same | Safe in the browser; RLS applies |
SUPABASE_SECRET_KEY | sb_secret_... | same | Server only. Never add a NEXT_PUBLIC_ prefix. Mark it "Sensitive" |
NEXT_PUBLIC_SITE_URL | https://synapse-os.ca | (leave unset) | Previews use their own VERCEL_URL |
NEXT_PUBLIC_APP_URL | https://app.synapse-os.ca | (leave unset) | The app's own host; previews keep the app under /app. Add the domain in Vercel > Project Settings > Domains |
BETA_IP_SALT | a long random string | same | Hashes visitor IPs for the beta form rate limit |
Do not set SYNAPSE_LEGACY on Vercel: SQLite cannot run there, and without it the unported pages answer 404.
Supabase settings for the cloud project
- Authentication > URL Configuration
- Site URL:
https://synapse-os.ca
- Redirect URLs:
https://app.synapse-os.ca/** (production: login and email links run on the app's host)https://synapse-os.ca/**https://*-<your-vercel-team>.vercel.app/** (preview deployments)
- Authentication > Sign In / Providers: turn off "Allow new users to sign up". Keep the Email provider on; it is also what lets users log in.
- Authentication > Email Templates: paste the bodies of
supabase/templates/invite.html ("Invite user") and supabase/templates/recovery.html ("Reset password"). Their links go to /auth/confirm, which the app needs to start the session on the server.
- Authentication > SMTP Settings: add your own email provider before real users. The built-in sender is limited to a few emails per hour.
- Database: apply the migrations with
npx supabase login, npx supabase link --project-ref <project-ref>, then npx supabase db push.
- Beta users: Authentication > Users > "Invite user" (they choose a password from the email) or "Add user" with a password. Read beta requests in Table Editor >
beta_requests.
Local AI on the live site
Each user's Ollama must allow the site. Set the environment variable OLLAMA_ORIGINS=https://app.synapse-os.ca and restart Ollama. Chrome and Edge then ask once to let the site reach apps on this device. Safari does not allow it. The Local AI page (app.synapse-os.ca/ai) checks all of this and explains what to fix.
How to Use It (Quick-Start Guide)
Synapse OS is designed to fit naturally into your daily thinking and working routine. Here is the recommended workflow to get the most out of it:
Step 1: Linking Your Markdown Vault
- Your notes reside in
{SYNAPSE_DATA_DIR}/notes as plain .md files.
- You can create notes directly within the Synapse web interface, or you can drop in existing Markdown files and folders from Obsidian, Logseq, or your personal archive.
- Subfolders are automatically supported.
Step 2: Syncing Files to the Database (Reindex)
- Whenever you add, rename, or modify markdown files externally, navigate to Notes in Synapse and click Reindex Vault (or hit the sync trigger).
- Synapse rapidly scans your folder, parses frontmatter and headings, re-hashes content, and updates the SQLite search index without altering your raw markdown files.
Step 3: Querying the Local AI (Ask / Copilot)
- Go to Ask in the sidebar.
- In Settings, ensure your local Ollama instance is recognized and select an installed model from the dropdown.
- Ask questions in natural language:
- "What were the key takeaways from my project architecture notes?"
- "Summarize the tasks due this week across the infrastructure project."
- Synapse retrieves relevant notes, tasks, and meetings locally, provides a detailed response, and includes interactive source links directly back to your files.
Step 4: Using Instant Search
- Press the global search bar or navigate to Search.
- Search is accent-insensitive and scans titles and markdown content simultaneously.
- Find notes, project dependencies, and pending tasks in sub-milliseconds without waiting on remote network calls.
Project Structure
Synapse-OS/
├── migrations/ # Append-only, numbered SQL migrations
├── public/ # Static branding and assets
├── src/
│ ├── app/ # Next.js App Router (pages, layouts, and server actions)
│ │ ├── ask/ # Local AI Chat interface
│ │ ├── notes/ # Markdown notes & vault view
│ │ ├── tasks/ # Task manager & dependency graph
│ │ ├── projects/ # Project dashboards
│ │ ├── search/ # Full-text SQLite search
│ │ └── settings/ # Local AI & user preferences
│ └── lib/ # Core business logic (plain SQL, pure functions)
│ ├── ai/ # Ollama client and prompt routines
│ ├── db.ts # SQLite database connection & WAL management
│ ├── migrate.ts # Transactional migration runner
│ ├── notes.ts # Note CRUD & frontmatter extraction
│ ├── reindex.ts # File-system vault scanner & reconciler
│ └── search.ts # Keyword & full-text search matching
└── tasks/ # Structured project milestones and roadmap
Security & Privacy Manifesto
- Localhost Bound: By default, Synapse binds strictly to
127.0.0.1. It does not listen on public interfaces unless explicitly configured behind a trusted reverse proxy (such as Tailscale).
- Zero Remote Analytics: No Google Analytics, no PostHog, no Sentry, no third-party tracking scripts.
- Encrypted Backups: Built-in backup utilities support AES-256-GCM encryption for safe archival to external storage.
- Open Formats: Even if you stop using Synapse, your data remains yours. Your notes are plain text; your database is an open SQLite file that can be queried with any standard SQLite viewer.
License & Community
Synapse OS is open-source software built for those who value privacy, control, and craft.
