SynapsesOS
Guides

Federation & Multi-Repo

Federation lets Synapses span multiple repositories or sub-projects, giving agents a unified view across service boundaries. This is essential for monorepos, microservice architectures, and any setup where related code lives in separate directories.

Configuration

Add federation settings to synapses.json:

{
  "federation": {
    "projects": [
      {
        "name": "api-gateway",
        "path": "../api-gateway",
        "type": "service"
      },
      {
        "name": "user-service",
        "path": "../user-service",
        "type": "service"
      },
      {
        "name": "shared-lib",
        "path": "../shared-lib",
        "type": "library"
      }
    ]
  }
}

Each federated project maintains its own graph. Synapses stitches them together for cross-project queries.

Monorepo Configuration

For monorepos with a shared root:

{
  "federation": {
    "mode": "monorepo",
    "projects": [
      { "name": "frontend", "path": "./packages/frontend" },
      { "name": "backend", "path": "./packages/backend" },
      { "name": "common", "path": "./packages/common" }
    ]
  }
}

NPM Workspace Support

Synapses auto-detects NPM/Yarn/PNPM workspaces. If your package.json has a workspaces field, federated projects are inferred automatically:

package.json
{
  "workspaces": ["packages/*"]
}

No additional federation config needed — Synapses discovers packages/frontend, packages/backend, etc.

Cross-Project Queries

get_context Across Projects

{
  "tool": "get_context",
  "arguments": {
    "query": "user authentication flow",
    "projects": ["api-gateway", "user-service"]
  }
}

The projects parameter limits the search to specific federated projects. Omit it to search all.

memory(action=“search”) Across Projects

{
  "tool": "memory",
  "arguments": {
    "action": "search",
    "query": "rate limiting decisions",
    "projects": ["api-gateway", "shared-lib"]
  }
}

Memory episodes are scoped to their originating project but searchable across the federation.

Agents coordinate across projects via the Work Ledger — session_init automatically surfaces active agents and their claimed work across federated projects.

Cross-Project Edges

When Synapses indexes federated projects, it detects cross-project relationships:

  • IMPORTS — one project importing packages from another
  • CONSUMES — API calls between services (detected via HTTP client patterns)
  • DEPENDS_ON — package.json/go.mod dependency references

These edges appear in get_context and get_impact results, showing how changes in one project affect another.

Drift Detection

Federation includes drift detection: Synapses tracks when federated projects change independently and flags potential inconsistencies.

{
  "tool": "validate",
  "arguments": {
    "phase": "list",
    "scope": "federation"
  }
}

Common drift scenarios:

  • Shared library updates a function signature, but consumers have not updated
  • API contract changes in one service without corresponding client updates
  • Version skew between federated dependencies

Indexing Federated Projects

Each federated project is indexed independently. The first session_init triggers indexing for the current project. To index all federated projects:

{
  "tool": "session_init",
  "arguments": {
    "agent_id": "agent-42",
    "index_federation": true
  }
}

Subsequent sessions use cached indexes unless files have changed.

Example: Microservice Architecture

Given three services:

/repos/
  api-gateway/    → routes requests, auth
  user-service/   → user CRUD, profiles
  billing-service/ → payments, invoices

Configure in api-gateway/synapses.json:

{
  "federation": {
    "projects": [
      { "name": "user-service", "path": "../user-service" },
      { "name": "billing-service", "path": "../billing-service" }
    ]
  }
}

Now an agent working in api-gateway can:

// Understand the full auth flow across services
{ "tool": "get_context", "arguments": {
  "query": "user authentication",
  "projects": ["api-gateway", "user-service"]
}}


// Check impact of changing a shared type
{ "tool": "get_impact", "arguments": {
  "entity": "user-service:internal/models/user.go:User"
}}
// Shows impact in user-service AND api-gateway (which consumes the User type)


// Search for all JWT usage across the federation
{ "tool": "search", "arguments": {
  "query": "jwt.Parse",
  "projects": ["api-gateway", "user-service", "billing-service"]
}}