ADR-047: Multi-project brain: catalog-served today, resident daemon deferred

Date: 2026-07-07 Status: Accepted Author: Rômulo Febasi

Scopes the #288 epic (“always-on multi-project brain”). Seeds from #287 (SYN-300, the --workspace flag). Composes ADR-010 (federation) and ADR-011 (remote-as-witness).

Context

The desired product flow: “one brain, many projects, ambient access”, an agent in any repo can reach the user’s Synapse brain(s) elsewhere on the machine. The #288 epic sketched several phases; this ADR records what already exists and draws the line on what stays deferred.

What already ships (v1.2):

• User-level catalog. The federation registry (src/registry, workspaces.db at a platform-standard path) IS the per-user catalog: every syn init registers the workspace (id, name, root, git remote, cached SYNAPSE.md identity). syn ws list/show/include/exclude/refresh/forget/gc manage it.
• Serve any brain, from anywhere. syn mcp --workspace <path|name> resolves a brain by path or by its catalog name (SYN-300); syn mcp install --workspace bakes that into the client config (#287), so a client in any directory reaches the pinned brain with no cwd dependency.
• Attributed cross-workspace reads. list_workspaces, federated_search, get_entity_from, get_workspace_manifest return workspace-attributed results, gated by the opt-in federated flag (BR-12.4). Redaction is per-workspace.

So phases 1–3 of the epic (catalog, serve-from-catalog, attributed reads) are done. The remaining phase is the “always-on resident service”.

Decision

The multi-project brain is served through the catalog + --workspace + federation, which ship today. The always-on resident daemon (OS auto-start, persistent process, lifecycle) is DEFERRED and gated behind its own future ADR, it is not built in v1.x.

Rationale for deferring the daemon rather than building it now:

• It is large, OS-specific infra: launchd (macOS), systemd (Linux), a Windows service: plus crash-restart, upgrade handling, and a login hook. None of that exists today, and MCP clients already spawn the stdio server on demand, so the daemon is an optimization, not a capability gap.
• It needs a security/IPC model of its own: a resident server implies a transport beyond per-client stdio (an HTTP/SSE or socket gateway: SYN-235, already Commercial-scoped), an authorization story (today the user owns the machine and each client spawns its own process), and resource limits. Those are ADR-level decisions, not a code drop.
• MCP has no “enumerate sibling servers” primitive: catalog-driven auto- discovery would need either an MCP protocol extension (Anthropic’s call) or an external registry file kept in sync: a design question, not a bug.

Consequences

• Improves: the epic’s user-visible value (reach my brain from any project) is available now with zero new infra: syn mcp install --workspace <name>. The catalog + federation give attributed multi-brain reads today.
• Worsens / limits: there is no single always-on process; each MCP client starts its own stdio server (cheap, but not “resident”). Auto-start on login and catalog-driven discovery wait for the deferred daemon ADR.
• Follow-up: a future ADR (when demand is shown) decides the resident server transport + autostart + discovery, composing SYN-235 (HTTP/SSE gateway) and the multi-user roster (SYN-285 spike). Filed as SYN-317.

Alternatives considered

• Build the daemon now. Rejected: large cross-platform infra + a new security model for a convenience over the working on-demand spawn; premature without demand and its own ADR.
• Catalog-driven auto-discovery via a synced registry file. Deferred: needs a sync + staleness design; the manual --workspace install already covers the concrete workflow.