Security model

Trust boundary

Synapse is local-first, not a sandbox. It removes unnecessary network and file exposure from the memory-and-credential workflow, but it still runs as your macOS user. Any process already able to control your account, inspect your terminal, read your home directory, or access an unlocked Keychain may sit inside the same trust boundary.

The application requires no Synapse account or hosted service. MCP uses local stdio. Memory and metadata live in a local SQLite file. Synapse includes no telemetry, no remote synchronization, and no web server.

Memory

Memory bodies are plain text in SQLite and are available to connected MCP clients through recall. Global records are available in every project; project records are returned only with the matching normalized project root. Do not store credentials, private keys, access tokens, or material you would not want an authorized connected tool to read.

Import reads recognized durable-memory stores only. It does not inspect conversation logs, authentication files, settings, tasks, or global instructions. Credential-shaped entries are flagged, hidden in previews, and skipped by the app. Provider formats are schema-checked before use, original files remain untouched, and import batches can be undone.

Database files use owner-only permissions on Unix systems and are checked for page and foreign-key integrity before use. These controls protect against accidental broad access and corruption; they do not encrypt memory at rest.

Secret values

A secret value is never in brain.db, never in YAML, never in a log, never in an MCP response, and never at rest in plaintext. brain.db stores the vault, label, environment name, and account reference. The value goes to one of two stores.

The encrypted store is the default, and the only one available off macOS. Each value is sealed with XChaCha20-Poly1305 under a random 24-byte nonce, with its account reference authenticated as associated data, and written to vault.db in the data folder. The 32-byte key lives beside it in vault.key, created once with owner-only permissions and never overwritten. Deleted rows are zeroed rather than left on a free page.

Be clear about what that protects. It protects a vault that has been copied — a backup, a synced folder, a disk image, a laptop somebody else now has. It does not protect you from a process already running as your user, which can read vault.key exactly the way Synapse reads it. This is encryption at rest, not an access control.

macOS Keychain is the other store, and on a Mac it is the stronger of the two: it adds per-application access control that the operating system enforces, which a key file cannot. It is one setting away in either direction, and synapse vault migrate moves every value across without a gap.

secret set does not accept a value argument. Interactive input uses a hidden prompt; piped input remains available for automation. secret copy is the only way a stored value comes back out, and it goes to the clipboard rather than to a screen, handed to pbcopy over stdin rather than as an argument that would be readable in ps. Anything on the clipboard is readable by every program that can ask for it, and Synapse does not clear it for you.

Scope approval

An unapproved, edited, or invalid .synapse.yaml never contributes variables. Approval stores a SHA-256 digest of the exact file bytes and its canonical path. Any later edit invalidates that digest.

Resolution walks from broad ancestor folders toward the working folder. Narrower approved files can replace a mapping, but a name denied by a broader scope remains denied. Any scope warning prevents synapse run from launching and makes the shell hook unload its managed values, avoiding silent partial configuration.

Environment boundaries

synapse run -- <command> reads only the selected values out of the vault and places them in the environment of a new child process. That command and all of its descendants can read those values normally. Synapse cannot stop the child from logging, transmitting, or persisting them.

The optional zsh, bash, or fish hook asks the shell to evaluate quoted environment changes. It activates only inside a directory with at least one approved discovered scope. Leaving, revoking approval, or changing any discovered scope unloads managed variables and restores values that existed before activation.

Settings installs the hook inside a marked startup-file block using the absolute managed CLI path. It backs up and atomically replaces an existing file, refuses incomplete or duplicate Synapse blocks, and removes only the marked block when disabled.

• Inspect scripts before launching them with production credentials.
• Use folder scopes and deny to narrow access.
• Prefer separate least-privilege credentials for development and deployment.
• Use synapse status . immediately before a sensitive command.
• Use synapse deny when a directory should no longer activate automatically.

Operational limits

• Synapse does not isolate a malicious connected MCP client from recalled memory. Only connect tools you trust.
• Both stores protect a value at rest, but an authorized local child receives plaintext environment variables.
• On the encrypted store, the key sits beside the sealed values in the data folder. Anything running as you can open the vault; a copy of the folder taken without the key cannot.
• Database exports contain brain.db only — memory and credential metadata, never a value. vault.db is a separate file for exactly that reason, and it is not in the export.
• Deleting the data folder deletes vault.db and vault.key with it, which is every stored value. On the Keychain store the values survive it. synapse uninstall says so before it does anything.
• SOUL.md is ordinary local Markdown. Both connected tools can read it, so do not put secrets there.
• Configuration writes are validated, backed up, and atomic, but external programs can still change the same files afterward.
• A scope digest proves that you approved exact bytes at a path; it does not prove the commands launched from that folder are safe.
• There is no remote revocation system. Forget a secret in Synapse and rotate it at its issuer when exposure is possible.