Global Configuration

Synapses supports a global config file at ~/.synapses/config.json that provides defaults across all your projects. Project-level synapses.json always wins for any key it sets.

Merge Order

Built-in defaults → ~/.synapses/config.json → <project>/synapses.json

Setting Global Defaults

Use the CLI to set global values:

# Enable brain globally
synapses config --global brain.enabled true

# Set embedding mode
synapses config --global embeddings builtin

# Set rate limits
synapses config --global rate_limits.write_ops_per_minute 20

Viewing Config with Sources

# Show full merged config
synapses config --show

# Show a single key with where it comes from
synapses config --show brain.enabled
# brain.enabled = true (from: ~/.synapses/config.json)

Globalizable Fields

These fields can appear in the global config:

Field	Description
`brain`	AI enrichment (Ollama model, mode)
`pulse`	Analytics sidecar URL
`embeddings`	Embedding mode: “builtin”, “ollama”, “off”
`embedding_endpoint`	Custom embedding API endpoint
`embedding_model`	Ollama embedding model name
`embed_pool_size`	Parallel ONNX workers (1-8)
`session`	Auto-end thresholds, reconnect windows
`rate_limits`	Per-session call limits
`content_safety`	Injection scanner mode
`recall`	Retrieval fusion settings

Project-Only Fields

These are inherently per-project and should not be in the global config:

rules — architectural constraints specific to a codebase
edge_weights — tuned per project
context_carve — depends on project size
linked / federation — paths to sibling repos
constitution — project principles
api_entries — project-specific entry points

Example Global Config

{
  "version": "1",
  "brain": {
    "enabled": true,
    "ollama_url": "http://localhost:11434",
    "model": "qwen3.5:2b"
  },
  "embeddings": "builtin",
  "session": {
    "auto_end_threshold_calls": 80,
    "reconnect_window_secs": 300
  },
  "rate_limits": {
    "write_ops_per_minute": 30,
    "expensive_reads_per_minute": 20
  },
  "content_safety": {
    "enabled": true,
    "mode": "reject"
  }
}

Project Override Example

In a specific project’s synapses.json, override just what differs:

{
  "version": "1",
  "brain": {
    "enabled": false
  }
}

This project disables brain while all other projects inherit the global brain.enabled: true.