v1.4.0 — Global reach, instant handovers, frictionless day-one and capture you can trust

Synaptic v1.4.0

Turn your daily work into a brain your agent can actually use. Plain files. Zero runtime. Any agent.

The biggest Synaptic release yet. If you're on a bare v1.0, it all arrives in one clean /synaptic-upgrade
— additive, no schema change, nothing breaks — and your brain gets a lot more capable.

---

🌐 One brain, wherever you work

• Keep your brain scoped to a single project, or let it follow you across every folder — you choose, just by where it's wired.
• Move a project brain to global (or back) — guided, crash-safe, byte-for-byte, with automatic rollback if anything looks off.
• Every init / upgrade now detects how your brain is wired and fixes it — no more "works in this folder, invisible in the next."

⚡ Value in 10 minutes

• Day-1 walkthrough: empty brain → first note → first retrieval → your first "if I vanished tomorrow, here's everything" handover. Ten minutes, no jargon.
• /synaptic-handover: a new-joiner or vacation brief straight from the brain, on demand — what it is, the key decisions, the open threads, where to look. The knowledge tax, handled.
• Commands now show up in your agent's / menu, with descriptions.
• A path for non-developers — managers and POs get the value without touching a terminal.

🎯 Capture you can trust

• A structured session protocol — Goal · Discoveries · Done · Next · Files. Signal, not a wall of text.
• A "did capture actually fire?" audit that catches silently-dead hooks — so you never open your brain to an empty journal.

🧭 Know what's alive — and what to trust

• lifecycle (project · area · resource · dormant) + status (active · stale · archived): two dials, one grep, instant answers to "what's live right now?" and "can I trust this?" Archive, don't delete.

🕸️ See your brain

• A real interactive, force-directed graph — zoom, filter, search, expand. Not a static blob.
• God-node & surprising-edge audits — the over-connected hubs, and the links that shouldn't exist.

🛡️ Governance, in the box

• A crisp local-vs-remote data boundary (code stays 100% local; prose goes to your host LLM) — drop-in text for regulated environments.

---

The one thing that never changes

It's just files. Zero runtime. Any agent. Git-diffable. Portable. Yours.
No daemon, no lock-in, no gigabyte download — works offline, works air-gapped, works with whatever agent you use next year.

What's next

Retrieval is getting a turbo — faster search now, semantic when you want it. Opt-in, local, and your files
stay the source of truth. Alongside it, we're building toward a brain that gets better with use, not just
bigger. It'll always be just files underneath — and the hints are already in the repo if you want to dig.

---

Get it

• New: /synaptic-init
• On v1.x: /synaptic-upgrade — additive, no schema change, nothing breaks
• On v0.3 (pre-v1): a guided migration walks you through it — see UPGRADE-v0.3-to-v1.md

v1.3.0 — Safer, Cleaner, guided upgrades, dormant nodes and a modern visualization

Synaptic Core — Release Notes v1.3.0

Date: 2026-07-02 · Engine: 1.2.0 → 1.3.0 · Brain schema: unchanged (still 1.0)

One combined release. This single MINOR folds the migration-&-upgrade-hardening work
(originally scoped as a standalone PATCH v1.2.1) together with the additive structural
improvements. v1.2.1 is not released standalone — its entries ship inside 1.3.0.
The brain schema is unchanged; no /synaptic-upgrade is required to adopt this release.
Reinstall the skill for the new engine behavior.

This document has two parts. Part A is for a brain owner or user — plain language, no
jargon. Part B is the change-level technical detail.

---

TL;DR — which path are you on?

• Already on Synaptic v1 (v1.0.0+)? → This is an UPGRADE, not a migration. No schema change,
  nothing to migrate. Update/reinstall the skill so the engine is 1.3.0; optionally start tagging
  lifecycle: on nodes. The new interactive graph, god-node audit and hardened checks come for free.
  → Follow docs/UPGRADE-v1.x-to-v1.3.0.md. (Invoking
  /synaptic-upgrade on an already-1.0 brain just refreshes the engine + offers PARA — it does not
  run a full migration.)
• Still on v0.3 (pre-1.0)? → This is a MIGRATION and it lands you on v1.3.0. Back up first,
  run it guided, one commit per phase, and pass the retrieval drill before cutover (git fast-forward).
  → Follow docs/UPGRADE-v0.3-to-v1.md (paste-to-agent runbook:
  docs/UPGRADE-v0.3-to-v1.AGENT.md). Needs Node for the tools (else the
  documented manual fallbacks).
• Brand new? → /synaptic-init.

---

Part A — What v1.3.0 gives you

• Safer, more honest migrations. A brain can be structurally clean and still be hard to
  retrieve from — well-formed files, but too few links between them. Before, the checker said
  "all good" and stopped there. Now it prints a plain retrieval-readiness summary and, when your
  brain looks structurally fine but poorly connected, it tells you so with an advisory caveat.
  A brain that "passes" is no longer silently allowed to be retrieval-poor — you're told.

• A "dormant" shelf for finished or idle knowledge. You can now mark a note as dormant so
  it stops cluttering your everyday working context, while staying fully searchable and one flip
  away from active again. Nothing is deleted; the note, its index entry, and its links all stay
  intact. It's an archive-don't-delete cooling shelf — reversible with a single field change.

• A real interactive graph you can actually explore. The old graph produced a static picture
  that was unreadable once a brain grew. v1.3.0 ships a single self-contained HTML file you open
  in a browser and use: search for a note, filter by cluster or link type, zoom and pan, and
  expand or collapse busy hubs. No internet connection, no external downloads — one local file.

• Cleaner, guided upgrades. Bringing an older brain up to date is now walked through step by
  step, with a clear checklist you tick off per phase and a short "does retrieval actually work?"
  test at the end. The default mode keeps things quiet and safe; the safety checks run the same
  either way. You end up with a short before/after record of what moved and why.

• Nothing new to install, and your data stays where it is. The upgrade is files in, files
  out — no server, no database. Migrations run on a copy and only switch over once you're happy,
  and a new short document spells out plainly what stays 100% on your machine.

---

Part B — Technical detail

No schema bump — the brain schema stays 1.0; a v1.2.0 or skill-less agent simply ignores
the one new optional frontmatter key. Engine moves 1.2.0 → 1.3.0. Two paths are served:
the v0.3 → v1.3 migration (for late adopters bringing an old brain forward) and the
v1.2 → v1.3 upgrade (an existing v1 brain has nothing to migrate — reinstall the skill).

Migration & upgrade hardening

(Originally scoped as v1.2.1. Ships inside 1.3.0.)

• Retrieval-readiness report + structural-green ≠ retrieval-green. tools/check.js now
  prints a retrieval-readiness summary (nodes, edges, clusters, orphans, edges/node,
  MOC-reachable) computed over one canonical knowledge-scoped, MOC-excluded, undirected-deduped
  edge/degree universe (new shared tools/lib/brain-graph.js, used verbatim by tools/graph.js
  and the audit heuristics so the tools can never disagree on topology). When the brain is
  structurally clean (0 errors) yet a connectivity heuristic trips (orphan ratio > 20% or
  edges/node < 0.5), it prints an advisory CAVEAT — structural-green ≠ retrieval-green —
  that never changes the exit code.

• Non-live-artifact check in knowledge/ + audits/ exclusion. tools/check.js gains a
  fence-aware check: an ERROR only for exact-name / path-segment leaks (MIGRATION_DONE.md
  inside knowledge/, a _migration-staging/ path segment inside knowledge/), and WARN-only
  fuzzy heuristics (surviving prose carrying a {{...}} placeholder; a filename matching a
  closed-audit-report pattern). audits/ is wired into both the exclusion set and the link index;
  playgrounds/ and _migration-staging/ are treated as brain-root siblings of knowledge/,
  never children.

• lint: allow-large suppresses the soft-budget WARN. A node may carry lint: allow-large
  (scalar or list form) to opt out of the soft size-budget WARN, decoupling the budget policy from
  the node type (type: reference continues to suppress it as well).

• MIGRATION_DONE gate + mandatory retrieval drill + one-commit-per-phase. The v0.3 → v1
  migration now closes each phase against a binary checklist artifact — a new
  templates/MIGRATION_DONE.md (Phase M / C / V boxes, added to MANIFEST.txt) that lives at the
  brain root or _migration-staging/, never in knowledge/ (a MIGRATION_DONE.md under
  knowledge/ is a check.js ERROR). A phase is DONE only when every box under it is checked.
  Phase V adds a mandatory retrieval drill with a deterministic question-selection recipe
  (3 most-linked nodes + 2 registry lookups + 1 cross-cluster synthesis, answered by MOC
  navigation only) and a binary pass bar (all 5 fact-lookups via navigation, 0 grep-fallbacks; the
  synthesis question may miss as a /synaptic-weave gap) — because check.js green is necessary
  but NOT sufficient. The runbook prescribes ≥3 distinct, named, independently-revertible
  commits on the upgrade branch (migrate: Phase M … → refactor: Phase C … → `chore: cleanup

  • cutover …), each passing check.jsbefore the next begins, with the commit hash recorded per phase in the ledger. The AGENT runbook andreferences/upgrade-to-v1.md` mirror the drill and the
    gate.

• Git fast-forward cutover (Windows/OneDrive-safe) + guided-default mode + owner orientation.
  The cutover now leads with git switch main && git merge --ff-only <upgrade-branch> — files
  rewritten in place, no live-folder rename — with the folder rename/swap demoted to a non-git
  fallback and an explicit Windows/OneDrive lock/half-move/conflict-copy warning; if --ff-only
  refuses, that surfaces concurrent writers and routes to the shared-brain freeze path. A git
  worktree is noted as the safe way to build the v1 copy. ROLLBACK is reconciled to match (a git
  brain rolls back via git — reset to / forward-revert the pre-v1 tag; the rename is the non-git
  path only). A "Mode: guided (default) vs interactive" callout enumerates the ONLY questions
  guided mode may ask (topology intake, any deletion, private-vs-shared, cutover ack) and states
  that guided vs interactive changes verbosity, NOT the safety gates (conservation gate,
  no-silent-deletion ledger, and the Phase V drill run identically in every mode). Step 9 gains an
  owner-facing "how to use your new brain" orientation plus a soak/cleanup checklist.
  references/upgrade-to-v1.md mirrors the FF cutover, the mode definition, and the worktree note.

• Tooling / environment notes + deletion ledger as a standing rule. The AGENT runbook gains a
  "Tooling / environment notes" appendix framing four host quirks as ENV diagnostics, not
  Synaptic rules: Git Bash has no rg (use grep -rn / git grep / the agent's search — every
  grep-style instruction stays portable); apply_patch / VS Code fs-write failures fall back to
  direct writes; OneDrive/Dropbox locks → move to a local path (cross-links the Step 2 SYNC GUARD
  and the FF-cutover rationale); and PowerShell Get-Content / WriteAllText round-trips
  corrupt non-ASCII (em-dash, arrows, curly quotes) → prefer UTF-8-aware writes and keep tool
  source ASCII-safe. The deletion/move/archive ledger is promoted to a STANDING rule (not
  migration-only): a one-line note (what, why, loser → winner or destination, recoverable-via-git;
  git is the archive) is added to references/consolidate.md, references/maintain.md, and
  references/weave.md, matching the discipline references/upgrade-to-v1.md already uses.

• CORE breadcrumb as an instruction, robust when hooks are absent (issue #2). The per-turn
  journal breadcrumb is now stated as an instruction the agent follows, not only a hook — the
  floor underneath the automation, so a session that reaches compaction is never
  breadcrumb-empty (the issue #2 failure mode: a session neared recompact with no breadcrumbs
  written). templates/BRAIN.md Capture Contract names the failure mode and instructs the agent to
  append the breadcrumb per meaningful turn itself; the Stop hook automates it where wired, but
  it is written even w...

v1.2.0 — Upgrade path + seat brains

Bring your v0.3 brain to v1, and run one brain per workspace. Additive release — the brain
schema is unchanged (1.0), so an existing v1 brain has nothing to migrate; only a v0.3 brain runs an upgrade.

Highlights

• v0.3 → v1 upgrade path. A paste-to-agent runbook (docs/UPGRADE-v0.3-to-v1.AGENT.md) + a hardened
  skill-side procedure: works on a copy, verified backup as a hard gate, content-conservation check
  (not a naive node count), no silent deletions, staging kept until after verification, working rollback.
• Seat / global brain (one brain, a whole workspace of repos). Detect-on-Load now resolves the brain
  via the <!-- BEGIN:SYNAPTIC --> bridge pointer (not only a CWD-relative .synaptic/) and stays
  silent when a bridge is present — so a sibling-repo working dir never offers to create a competing
  nested brain. Model: one brain per workspace; the workspace's breadth is up to you.
• Harness: detect-then-deploy, prefer one user-level pointer (keeps work repos clean of brain
  refs), one source → many host targets; optional command-discovery stubs; a harness/setup/<host>.md
  record (your re-deploy recipe across machines).
• Operating rules (conventions, guardrails) live in harness/ as the source and are deployed to
  the host's instruction context — no Top Guardrails block in BRAIN.md (removed from the template).
• Three-tier zero-tooling install (agent self-install / npx degit / manual copy).

How to upgrade

• New (no brain yet): point your agent at the skill — npx degit diego-alfadev/synaptic-core/standalone/synaptic .claude/skills/synaptic, or the agent self-installs from SKILL.md + MANIFEST.txt, or copy the folder. Then /synaptic-init.
• Already on a v1 brain (older skill): just reinstall the skill to get v1.2.0 behavior — no brain migration (schema is unchanged). Re-run /synaptic-init on a wired brain to refresh the harness wiring.
• On a v0.3 brain: run the upgrade — paste docs/UPGRADE-v0.3-to-v1.AGENT.md to your agent (or run /synaptic-upgrade once the v1 skill is installed). It bootstraps the skill, backs up, restructures to v1 on a copy, rewires your harness, verifies, and swaps only when green.

Not in this release (roadmap)

Generic version-aware /synaptic-upgrade dispatcher + migrations/ library (future schema bumps);
deploy.js --brain/--repos to automate seat-brain wiring; content-routing for nested global+project brains.

v0.3.1 - Intelligent Upgrade Sync

Redesigned the /upgrade skill to be infinitely scalable. It now auto-fetches the latest release direct from GitHub and uses an Intelligent Seed Sync merge strategy to safely upgrade brains from any version to any version without intermediate steps.

Changes:

• Removed hardcoded version logic from /upgrade.
• Agent now performs a structural diff and explicitly overwrites protocols, adds new directories, and additively merges user data (Identity, Knowledge, Journal) without deletion.

v0.3.0 - Cortex Edition

v0.3.0 - Cortex Edition

This release introduces major improvements to agent autonomy, project direction, and session maintenance.

Key Features:

• Worklines: A lightweight task management system to give your brain direction and priorities without the overhead of external tools.
• Planning Mode: Intelligent mode detection in BOOTSTRAP.md that prompts the agent to follow a structured plan for complex tasks.
• Anti-Drift 2.0: Mandatory heartbeat every 3-5 interactions and a suite of self-detection signals to prevent identity loss in long sessions.
• Aggressive Detection: Support for 12 agent platforms including Cursor, Windsurf, Claude Code, Antigravity, and many more. Directories are created automatically if missing.
• Modular Bridges: Expanded ~500-token system prompt bridge for better agent initialization.
• Upgrade Skill: New /upgrade command to safely migrate brains from v0.0.1/v0.0.2 to v0.3.0 while preserving all knowledge.
• Relative Linking: Bridges now use relative Markdown links for maximum portability.

Acknowledgments:

Special thanks to the methodologies and patterns from Arscontexta, GSD, ClawVault, and Roam-Code.

v0.0.2 — Anti-Drift & /audit Support

🧠 SYNAPTIC-CORE v0.0.2

This release focuses on brain resilience and proactive discovery. Addressing the "Persona Drift" observed in long sessions, we introduce mechanisms to keep the agent grounded and its memory accurate.

🚨 Major Change: Anti-Drift Protocol

Long sessions often lead to agents losing their persona. We fixed this with:

• HEARTBEAT.md: A condensed identity checkpoint (~20 lines) the agent re-reads after each major task.
• Forced Journaling: The session rhythm now mandates writing the plan FIRST and results LAST.
• System Prompt Hook: /init now detects your platform (.agent, .claude, .cursor) and automatically writes a bridge file in its rules directory to ensure permanent connection to the brain.

🔍 New Skill: /audit

A proactive gap-filling tool. While /consolidate routes current session data, /audit reviews the entire brain cross-session to find:

• Missing info (empty templates, TBD contacts).
• Promotion opportunities (data in references/ that should be in inventory/).
• Workspace changes (new folders/files not yet ingested).

🌐 English-First Seed

The core standard (BOOTSTRAP.md, skills, templates) is now in English.

• Reason: LLMs follow English instructions with higher attention weight.
• Impact: Better alignment and performance across all models.
• User Content: Your actual data (overviews, journal, contacts) remains in your own language.

🧹 Other Improvements

• Improved /consolidate: Now automatically promotes data from references to inventory.
• Standalone Skill v3: Fully updated with all v0.0.2 features.

---

How to Upgrade

1. Download synaptic-seed-v0.2.0.zip
2. Replace .synaptic/BOOTSTRAP.md and the .synaptic/skills/ folder in your project.
3. Add .synaptic/identity/HEARTBEAT.md (or let /init create it).
4. Update your MANIFEST.md version to 0.2.0.
   (Manual for now—automated /upgrade skill coming in v0.0.3)

v0.0.1-beta — First public beta

🧠 SYNAPTIC-CORE v0.0.1-beta

The first public beta of the SYNAPTIC-CORE standard.

What is included

• Seed brain (\synaptic-seed.zip): Drop .synaptic/\ into any project and start working
• 5 core skills: /init, /consolidate, /ingest, /discover, /help- Standalone installer: A single .md\ file that generates a complete brain via dialogue
• BOOTSTRAP.md: Agent initialization protocol with session rhythm, memory routing, and quality gates

Quick start

1. Download \synaptic-seed.zip\ below
2. Extract .synaptic/\ into your project root
3. Open with any AI agent (Claude Code, Antigravity, Cursor, Copilot...)
4. Run /init\ to personalize

Or install just the standalone skill — see the README for details.

---

📊 Benchmark: Real-world brain (multi-project workspace)

Tested with a real workspace containing 4 projects (web CRM, SaaS product, WordPress sites), 4 git repos, deployment docs, and credentials files.

Brain after /init:

Metric	Value
Files	25
Total lines	1,101
Bootstrap read (session start)	~3,100 tokens
Full brain read	~9,300 tokens

What does that cost?

Operation	Tokens	Gemini 2.5 Pro	Claude Sonnet 4	GPT-4o
Session start (bootstrap)	~3,100	.004	.009	.008
Full brain read	~9,300	.012	.028	.023

Prices based on current API input rates: Gemini .25/Mtok, Claude /Mtok, GPT-4o .50/Mtok.

How much of your context window does it use?

Provider	Context window	Bootstrap %	Full brain %
🟢 Gemini 2.5 Pro	1,000,000	0.3%	0.9%
🟡 Claude Sonnet 4	200,000	1.5%	4.6%
🟡 GPT-4o	128,000	2.4%	7.3%

In perspective: A Synaptic bootstrap costs less than reading a single medium-length source file. Your agent barely notices it is there — but it never forgets who you are, what you know, or how you work.

Free tier impact: On the free Gemini API tier (1M context), running Synaptic adds roughly 0.3% to your context usage per session. On Claude Pro (/mo) or ChatGPT Plus (/mo) with their generous token budgets, the cost of having structured memory is effectively invisible.

---

Status

This is a beta. The standard is functional and tested, but we expect the structure and skill protocols to evolve with community feedback. Please open issues!