Synedrix OS
The governed operating layer for agentic business systems.
Synedrix OS is a reusable multi-agent operating system that enables specialized agents to coordinate across workflows, tools, and data while preserving human control, policy enforcement, and operational trust. It is not a vertical application with AI features bolted on, it is a shared operating substrate on which domain packs run.
Documentation map: This file is the executive overview. For the authoritative topic map (every category and topic with a canonical path or an explicit TBD), use docs/DOCS.md. For a single-file synthesis of OS specs, use docs/os/synedrix-os-canonical-master-v3.9.md.
1. What Problem It Solves
A modern enterprise faces a coordination problem more than a software problem. People spend significant time acting as middleware: chasing status, reformatting data, routing approvals, and translating context between disconnected systems. Single-agent assistants and narrow automations improve local productivity but do not solve end-to-end coordination.
Synedrix OS replaces that manual coordination layer with an orchestrated workforce of specialized agents governed by policy and shared context. It standardizes:
- How goals and events enter the system
- How work is decomposed and orchestrated across agents
- How specialized agents are defined, scoped, and run
- How tools and external systems are accessed safely
- How memory and business state are stored and shared
- How policy, approvals, and risk limits are enforced centrally
- How everything is traced, audited, and observed end-to-end
The platform makes the business programmable, domain-agnostic goals, constraints, workflows, decisions, tools, and feedback loops become explicit, inspectable, and executable. Humans move up the stack to strategy, policy, and exception management. Agents absorb the repetitive coordination and execution work inside those boundaries.
2. Core Principles
Synedrix OS has 12 core principles, summarised below and unpacked one by one after the table.
| # | Principle | What it means |
|---|---|---|
| 1 | Bounded autonomy | Every agent has explicit authority boundaries - no blank cheques |
| 2 | Orchestration is the center of gravity | Coordination quality, not model power, is the durable value |
| 3 | Specialised agents over mega-agents | Narrow, testable, governable roles beat one “do everything” agent |
| 4 | Governance before execution | Policies, approvals, and audit controls are built into the runtime |
| 5 | Shared context with scoped access | Agents share context; access remains least-privilege by default |
| 6 | Humans stay above the automation layer | Human oversight, not human exclusion |
| 7 | Explainability and audit by design | What happened, why it happened, under whose authority |
| 8 | Event-driven execution | Events are first-class triggers - no polling, no manual scheduling |
| 9 | One substrate, many domains | Domain-agnostic at the core; domain packs provide vertical logic |
| 10 | Trust is the real product | The ultimate output of the system is operational trust |
| 11 | Open by default, sovereign by design | Open source and self-hostable; three deployment modes; sovereignty by design |
| 12 | Deterministic idempotency, explicit state | Every side effect is idempotent or explicitly reconciled; all state is declared and recoverable |
Each principle unpacked:
Bounded autonomy - Agents operate within defined boundaries: what they may recommend, what they may execute, which systems they may access, and when they must escalate. Low-risk reversible actions can be automated; high-impact or irreversible actions must pass through policy checks and, where configured, human approval.
Orchestration as the center of gravity - The orchestrator decomposes goals into tasks, selects workflows, routes work to specialised agents, manages retries and sequencing, and coordinates approvals. Models, tools, and agents may change over time; stable coordination patterns are the durable value.
Specialised agents - Each agent has a clear mission, input/output contracts, allowed tools and systems, memory scope, execution scope, approval requirements, and an escalation path. Specialisation improves modularity, fault isolation, and the ability to evolve the system independently.
Governance before execution - Governance is load-bearing infrastructure, not a wrapper bolted on after deployment. Policies, permissions, approval thresholds, and audit controls are enforced centrally so agents can propose actions without being allowed to bypass trust, compliance, or safety requirements.
Shared context with scoped access - Agents are connected to a shared context fabric: systems of record, operational memory, event histories, and telemetry. Access is always bounded by role, policy, and mission.
Humans above the automation layer - Humans define goals, constraints, policies, escalation thresholds, and exception handling rules. Both human-in-the-loop (a person approves before the action proceeds) and human-on-the-loop (a person watches and can step in) patterns are supported based on risk and reversibility.
Explainability and audit - The system must always answer three questions: what happened, why it happened, and under whose authority it happened. Logs, traces, decision evidence, and policy lineage are core features, not optional compliance add-ons.
Event-driven execution - Signals, approvals, product changes, failures, anomalies, and callbacks trigger workflows the moment they happen. Agent coordination reflects the actual movement of the business rather than waiting for humans to poll systems manually.
One substrate, many domains - Trading, Commerce, Support, Ops, Finance, and future verticals all inherit the same orchestration, governance, memory, and observability foundations, while contributing their own domain-specific entities, tools, agents, and policies.
Trust is the real product - Performance and efficiency matter, but they are meaningful only when the system is reliable, governable, observable, and aligned with human accountability.
Open by default, sovereign by design - Synedrix OS is open source and self-hostable. Every component can run inside the customer’s own infrastructure, including local model inference. Three canonical deployment modes (cloud-connected, self-hosted-hybrid, air-gapped) are governed by this principle, so an organisation can match the system to its data sovereignty requirements without losing capability.
Deterministic idempotency, explicit state - State is explicit, execution is idempotent. Every side-effecting step carries an idempotency key, so where the target system honours it a retry, a redelivered event or a replay never duplicates the effect. A step whose tool cannot honour a key is declared non-idempotent, is never retried or replayed automatically, and is reconciled against the target system’s record or escalated to a human. All state an agent or workflow depends on is declared, versioned and recoverable, never held only in prompt context or a hidden cache. The determinism is of effects and state, not of model reasoning.
Full specification: Synedrix OS Core Principles
3. Architecture Overview
The architectural thesis: the durable value is not any individual model, but the operating substrate that coordinates agents, shared context, policies, and external systems into reliable business execution.
3.1 Canonical Layers
Synedrix OS is organized into 12 canonical layers:
| Layer | Primary purpose |
|---|---|
| Human Interface | Capture intent, approvals, and operational review via UIs, APIs, and messaging |
| Goal & Intent | Translate business objectives into structured intents, playbooks, and constraints |
| Orchestration | Decompose goals, route workflows, sequence tasks, manage retries and approvals (platform: n8n) |
| Agent Runtime | Execute agents with bounded lifecycle, scope, and communication patterns (platform: LangGraph, for stateful/cyclic/multi-agent reasoning) |
| Agent Registry | Discoverable agent capabilities, contracts, permissions, and lifecycle status |
| Tool Abstraction | Normalized, typed, observable, permissioned access to external systems |
| Memory & Data | Transactional, hot-state, semantic, graph, and audit memory — and the memory control plane that governs how it is formed, recalled and forgotten |
| Event | Standard event envelope, routing metadata, and correlation IDs |
| Governance & Controls | Policy enforcement, approvals, compliance checks, and immutable audit trails |
| Observability | Logs, traces, metrics, state transitions, decision lineage, and health signals |
| Domain Pack | Domain-specific entities, agents, workflows, tools, and policies |
| Business Instance | Tenant config, credentials, thresholds, and environment settings |
Rule of ownership: if reusable across domains → OS; if domain-specific → domain pack; if threshold/credential/env → business instance.
Full layer definitions: Synedrix OS Layer Taxonomy Table · Naming conventions: Synedrix OS Naming Convention Spec
3.2 OS-Owned Agents
Twelve agents are owned and shipped by Synedrix OS across three families. They are cross-domain, they operate identically regardless of which domain pack is active.
| Agent | Family | Role |
|---|---|---|
| Orchestrator Agent | Control | Decomposes goals into task graphs, routes to specialists, manages retries and approvals |
| Policy Guard Agent | Control | Evaluates proposed actions against policy rules, emits allow / block / escalate |
| Registry & Capability Agent | Control | Resolves which agents and workflows are available for a given goal |
| HITL Gateway Agent | Control | Routes approval requests to human reviewers, captures decisions, enforces timeouts |
| Memory Curator Agent | Control | Commits every durable memory record on behalf of the agents that propose them, so no agent writes durable memory directly and every record carries its provenance |
| Memory Access Broker Agent | Control | Mediates every memory recall and write proposal, resolving the requester’s declared scope against its memory profile before any store is queried; never sees memory content |
| Analytics Agent | Intelligence | Aggregates cross-domain metrics and surfaces performance signals |
| Forecasting Agent | Intelligence | Generates forward projections from time-series data |
| Anomaly Detection Agent | Intelligence | Monitors operational signals and emits anomaly events for triage |
| General Chat Agent | Intelligence | Answers natural-language questions about Synedrix OS from a semantic knowledge base, with cited sources, for standalone chat surfaces outside any domain pack |
| Consolidation & Reflection Agent | Intelligence | Analyses accumulated memory to propose consolidations, reflections, distilled skills, tier promotions and conflict resolutions; recommendations only, never writes |
| Audit & Lineage Agent | Observability | Reconstructs what happened, why, and under whose authority, read-only |
Domain packs contribute their own specialist agents using the same registry schema. Full definitions: Synedrix OS - Agent Registry
3.3 Target System Properties
| Property | Description |
|---|---|
| Reusability | Same core stack supports multiple business domains via domain packs |
| Modularity | Agents, tools, models, and workflows are independently replaceable |
| Governability | Policies, approvals, permissions, and auditability enforced centrally |
| Observability | Runs, decisions, transitions, and failures are traceable end-to-end |
| Interoperability | Agents communicate through contracts; tools communicate through adapters |
| Human override | High-impact decisions remain reviewable and interruptible at any time |
| Event responsiveness | The system reacts to business events rather than relying on static schedules |
4. Domain Packs and Business Instances
Synedrix OS separates platform primitives from domain logic into two distinct extension points.
4.1 Domain Packs
A domain pack is a modular capability package that implements a specific business domain on top of Synedrix OS. All domain packs are peers, no domain is privileged above others. Each pack contributes:
- Domain entity model
- Domain event catalog (conforming to the shared event envelope)
- Specialized agents for that domain
- Tool adapters for domain-specific external systems
- Domain policies and approval thresholds
- Domain workflow library and playbooks
- Analytics vocabulary, KPIs, and metrics
Each pack must declare: domain_id, domain_name, entity model, event catalog, agent registry entries, workflow library, tool adapters, policy modules, analytics model, and approval matrix.
Example packs: Synedrix Trading, Synedrix Commerce, Synedrix Ops, Synedrix Finance, Synedrix Support, all equivalent in status.
4.2 Business Instances
A business instance is a concrete deployed runtime: Synedrix OS + one or more domain packs + tenant configuration. It owns:
- Configuration, secrets, and credentials
- Policy thresholds and risk limits
- Approver roles and escalation rules
- Tenant data and environment-specific settings
This separation lets the same OS and pack architecture run across many tenants while keeping controls and configuration per-instance.
Full packaging model: Synedrix OS Taxonomy Spec · Responsibility split: Synedrix OS Responsibility Matrix
5. Events, Workflows, and Contracts
Synedrix OS is event-driven and contract-first.
5.1 Event Taxonomy
All events share a common envelope:
| Field | Purpose |
|---|---|
event_id | Unique event identifier |
event_type | Stable dotted name, e.g. order.created |
domain | Domain pack name or core |
entity_type / entity_id | Primary business entity |
source_type / source_id | Emitting agent, workflow, tool, or system |
timestamp | ISO 8601 event time |
correlation_id | End-to-end trace ID |
causation_id | Prior event or step that caused this one |
payload | Event-specific data |
policy_context | Optional governance metadata |
severity | Optional classification for alerting |
version | Event schema version |
Core OS events cover workflow lifecycle, approvals, agent invocation, policy enforcement, and incidents - emitted by the platform always. Domain events are defined by each domain pack and required to conform to the shared envelope.
5.2 Workflow Contracts
Every workflow must declare a formal contract covering:
workflow_id · name · domain · purpose · trigger_type · trigger_source · input_contract · validation_rules · agent_roles · tool_dependencies · side_effects · approval_requirements · output_contract · idempotency_strategy · retry_policy · error_policy · observability_signals · security_scope · version
Four non-negotiable rules:
- No implicit side effects - undeclared writes make a workflow non-compliant.
- No free-form production outputs - workflows feeding downstream automation must output structured payloads.
- High-impact workflows must be policy-aware - financial transactions, price changes, refunds, and regulated messaging must declare explicit policy and approval sections.
- Contracts are versioned artifacts - changes must be tracked and backward-compatible where possible.
Full specifications: Synedrix OS Event Taxonomy Standard · Synedrix OS Workflow Contract Spec
6. Tech Stack
Synedrix OS is built on purpose-selected infrastructure platforms, each with a non-overlapping responsibility. The stack deliberately separates different kinds of truth so each can evolve independently without breaking the others.
| Platform | Layer | Role |
|---|---|---|
| n8n | Orchestration | Workflow kernel, sequencing, agent handoffs, approvals, retries (orchestration only) |
| LangGraph | Agent runtime | Stateful/cyclic/multi-agent reasoning (with LangChain); invoked by n8n as a governed step |
| Hookdeck | Ingress gateway | Inbound event validation, buffering, and replay |
| Hookdeck Outpost | Egress gateway | Durable outbound notification delivery |
| Redis | Coordination bus | Hot state, pub/sub, idempotency keys, sub-10ms |
| Supabase PG17 | Transactional state | Canonical relational truth, entities, workflow state, audit trails |
| QuestDB | Temporal data | High-volume time-series, metrics, events, trends |
| Neo4j | Context graph | Workflow and outcome lineage, entity relationship graphs |
| Qdrant | Semantic memory | Vector retrieval, context recall, RAG, pattern matching |
| Langfuse | LLM engineering | Prompt versioning, LLM traces, token/cost, evaluations |
| PostHog | Behavioral analytics | Workflow analytics, feature flags, A/B experiments |
| Grafana LGTM Stack (Grafana · Alloy · Mimir · Loki · Tempo) | Operational monitoring | Service health, dashboards, alerts, SLOs, logs, traces |
Per-platform reference — what each platform is, what it is normally used for, and how and why Synedrix OS uses it: docs/platforms/
Full platform specifications: Synedrix OS Tech Stack · Orchestration vs runtime split: Orchestration & Runtime Strategy
7. Interoperability (MCP & A2A)
Synedrix OS is standards-aware at the interoperability boundary:
- MCP (Model Context Protocol) - preferred protocol for agent-to-tool and agent-to-context integration at the tool abstraction boundary. Used to expose selected internal services, resources, and read-only capabilities to LLM-backed agents and copilots.
- A2A (Agent2Agent) - preferred protocol for cross-system agent interoperability at the platform edge. Used for delegating work to external agent systems, federated workflows, and partner-agent collaboration.
Both protocols are governed the same as native tools and workflows. Neither replaces internal orchestration, governance, or observability. All MCP tool calls and A2A task exchanges remain policy-aware, auditable, and traceable.
Full strategy: Synedrix OS Interoperability Protocol Strategy
8. What Synedrix OS Is Not
Synedrix OS is explicitly not:
- A single mega-agent trying to do everything
- A model-specific framework tied to one LLM provider
- A collection of disconnected scripts or automations
- An autonomy-first system with weak oversight
- A domain-specific vertical application (trading platform, e-commerce stack, etc.)
- A system where governance is optional or bolted on after the fact
It is a reusable, governed, multi-agent operating system, a stable substrate on which many domain-specific capabilities can be built, run, and evolved independently.
9. Invariants
These rules hold unconditionally across all domain packs and business instances:
- Synedrix OS remains domain-agnostic at its core.
- Domain packs cannot bypass OS governance or observability.
- No agent writes to production systems without policy-aware orchestration visibility.
- Every workflow is observable end-to-end.
- Every agent has explicit authority boundaries.
- Every domain pack conforms to shared registry and contract standards.
- No MCP or A2A protocol interaction bypasses governance.
- Human override, review, and escalation always remain possible.
10. Who Is This For?
Synedrix OS targets teams that need to build serious, governable agentic systems:
- AI / platform engineering teams - building multi-agent workflows that span tools, services, and data stores
- Architecture and governance stakeholders - needing a principled, inspectable coordination substrate
- Ops, risk, and compliance teams - requiring policy enforcement, audit trails, and human override
- Product teams - building domain packs for specific business verticals on a shared foundation
If you need end-to-end business workflows powered by specialized agents with strong governance, full observability, and cross-domain reuse, Synedrix OS is the operating system you build on.
11. Canonical document map
Full checklist-style coverage (including gaps marked TBD) lives in docs/DOCS.md. The table below is a compact subset for quick access.
| Document | Version | Purpose |
|---|---|---|
| Synedrix OS Agentic Enterprise Manifesto Outline | v0.3 | Vision and strategic rationale |
| Synedrix OS Technical Platform Thesis | v0.2 | Architectural thesis |
| Synedrix OS Core Principles | v0.8 | Core principles - merged canonical source of truth |
| Synedrix OS Taxonomy Spec | v1.0 | Canonical taxonomy and packaging model |
| Synedrix OS Layer Taxonomy Table | v0.8 | Layer definitions and ownership rules; Layer 4 = LangGraph |
| Synedrix OS Responsibility Matrix | v0.7 | Capability-by-capability OS / pack / instance split |
| Synedrix OS Workflow Contract Spec | v0.4 | Workflow contract standard |
| Synedrix OS Event Taxonomy Standard | v1.0 | Event envelope and naming rules |
| Synedrix OS Tech Stack | v1.9 | Infrastructure platform specifications; adds LangGraph |
| Synedrix OS Orchestration & Runtime Strategy | v0.1 | n8n (L3) vs LangGraph (L4); governance bridge |
| Synedrix OS ADR-OS-001 — Agent Runtime Split | v0.1 | Decision: adopt LangGraph; reject LangSmith |
| Synedrix OS Interoperability Protocol Strategy | v0.3 | MCP and A2A; n8n↔LangGraph boundary |
| Synedrix OS - Agent Registry | v0.8 | OS-owned agent definitions - control, intelligence, observability families |
| Synedrix OS Canonical Master | v3.8 | Consolidated canonical reference (all docs in one) |
12. Versioning Policy
- Canonical documents carry their own
vX.Yversion number. - Breaking changes to taxonomy, event envelopes, invariants, or layer boundaries → major version bump.
- Additive changes (new events, new fields, new rules, new platform entries) → minor version bump.
- The consolidated master (
synedrix-os-canonical-master-vX.Y) is re-issued whenever two or more canonical documents change concurrently.
Related Documents
Canonical Reference
- Synedrix OS - Consolidated Canonical Reference — Consolidated single-file synthesis of all canonical specs; the authoritative executive view.
Core Principles and Vision
- Synedrix OS - Core Principles — All governing principles including Principle 11 (Open by default, sovereign by design).
- Synedrix OS - Agentic Enterprise Manifesto Outline — Platform vision and strategic rationale.
- Synedrix OS - Technical Platform Thesis — Architectural thesis and design rationale.
Architecture and Taxonomy
- Synedrix OS - Taxonomy & Platform Spec — Canonical taxonomy, naming model, architectural boundaries, and packaging structure.
- Synedrix OS - Layer Taxonomy Table — Authoritative layer definitions; Layer 4 platform = LangGraph.
- Synedrix OS — Naming Convention Spec — Single authoritative reference for all machine identifiers; runtime-engine vocabulary.
- Synedrix OS - Responsibility Matrix — Capability-by-capability OS/domain pack/business instance ownership split.
Agent Specifications
- Synedrix OS - Agent Registry — Full registry entries for the twelve OS-owned agents.
- Synedrix OS - Agent Spec — Full agent anatomy and normative field schema; adds
runtime_engine. - Synedrix OS - Agent Registry Spec — Registry schema, lifecycle states, and capability tag vocabulary.
Workflow and Event Standards
- Synedrix OS - Workflow Contract Spec — 19 canonical workflow contract fields and four cardinal contract rules.
- Synedrix OS - Event Taxonomy Standard — 15-field common event envelope and naming rules.
Tech Stack and Deployment
- Synedrix OS - Platform Architecture & Tech Stack — Platform stack including LangGraph (Layer 4), Ollama/vLLM, deployment modes, and Grafana LGTM Stack.
- Synedrix OS - Deployment Model Spec — Three canonical deployment modes: cloud-connected, self-hosted-hybrid, air-gapped.
- Synedrix OS - Interoperability & Protocol Strategy — MCP and A2A; n8n↔LangGraph boundary.
Vocabulary
- Synedrix OS — Vocabulary — Canonical glossary including deployment sovereignty and active development terms.
Synedrix OS · May 2026