SynapseOS

SynapseOS is a persistent, event-driven organizational runtime built around a Redis Stream event bus, LangGraph agent workflows, MCP tool servers, PostgreSQL persistence, and a Streamlit operational console. The system models a small company-like process where strategic decisions become task DAGs, operational workers execute those tasks, and completed work is routed through QA before being reflected in the live dashboard.

This repository reflects the current v1 architecture and the changes made since the first draft of the project. The codebase now includes cycle-scoped task execution, current-batch reviewer routing, Redis stream based orchestration, a live working-process panel in the frontend, and a task dashboard that focuses on the most recent work instead of older backlog.

System Summary

SynapseOS is designed as a layered execution pipeline:

1. External events arrive through FastAPI.
2. Events are written to a Redis Stream and consumed by a single router process.
3. The router dispatches each event to the correct LangGraph agent.
4. Agents use MCP tools to interact with task, memory, economy, and governance services.
5. PostgreSQL persists the durable organizational state.
6. Streamlit provides an operator view for event injection, live process tracing, and task monitoring.

The runtime is intentionally decoupled. Agents do not call each other directly; they communicate by publishing and consuming structured events. That makes the system easier to trace, easier to extend, and much more suitable for a persistent autonomous workflow than a single synchronous loop.

Architecture

API and Event Router

backend/api/main.py hosts the FastAPI application and the Redis stream consumer. The API exposes a single event injection endpoint (/events/emit). The router reads from the synapse_events stream using a consumer group (synapse_workers) and fan-outs events based on type.

Agent Layer

The current agent hierarchy is split into distinct responsibilities:

• CEO Agent: converts macro events into strategic direction.
• Strategy Agent: translates directives into task DAGs and emits a tasks_ready event.
• Research Agent: performs analysis-style work on assigned tasks.
• Builder Agent: handles technical implementation and operational work.
• Reviewer Agent: performs QA on completed work and emits verification or rework events.

MCP Tool Layer

The agents access capabilities through MCP servers instead of talking to the database directly:

• Task MCP: create tasks, inspect DAGs, poll assigned work, update task status.
• Memory MCP: store and retrieve organizational memory with vector search.
• Economy MCP: enforce token budgets and control spend.
• Governance MCP: evaluate risk and escalate actions when needed.

Persistence Layer

PostgreSQL stores agents, tasks, memories, and audit records. The memory model uses pgvector for similarity search. Tasks are ordered by creation time and can be filtered to a current cycle so workers only act on the batch generated in the present run.

UI Layer

The Streamlit app is the operator console. It now provides:

• Raw macro-event input that is formatted into a macro_shift payload.
• A Redis event-bus process view.
• A task DAG table that uses the full page width.
• Task ordering by newest first.
• Timestamp display in IST.
• Auto-refresh support.

Redis Event Bus

Redis Streams is the main coordination mechanism. This is the current behavior in v1:

1. The API writes all incoming events to synapse_events using XADD.
2. The router reads with XREADGROUP from the synapse_workers consumer group.
3. macro_shift events wake the CEO agent.
4. directive_issued events wake the Strategy agent.
5. tasks_ready and task_rejected wake the operational workers.
6. task_completed wakes the Reviewer agent.
7. Agent output events are re-published back into the stream.
8. The router acknowledges processed messages with XACK.

This design gives the runtime a durable event log, replayable execution history, and a clean boundary between event production and agent execution. It also keeps the workflow extensible without rewriting the orchestration model.

Current Task Cycle Behavior

The task lifecycle was refined after the initial implementation so the system focuses on the current batch instead of the entire pending task table.

Strategy Output

The Strategy agent now emits tasks_ready payloads that include the current cycle task IDs.

Worker Polling

The Research and Builder agents only poll the task queue for the current cycle task IDs. The Task MCP poller defaults to the latest two pending tasks and can also be scoped to the current cycle task IDs.

Reviewer Routing

The router now emits task_completed events for the current cycle task IDs so QA stays scoped to the generated batch. This prevents older backlog from being mixed into the current execution run.

Data Model

The main database entities are:

• Agents: persistent organizational identities and roles.
• Tasks: DAG nodes with parent/child relationships, assignees, budgets, and status.
• Memories: vectorized knowledge entries with metadata.
• Audit Logs: governance and system event history.

The task table is surfaced in the frontend as the active DAG view. It is sorted by created_at and shows timestamps in dd/mm, HH:MM format using IST.

Screenshots

SynapseOs Dashboard

SynapseOS Architecture

Repository Layout

• backend/api/main.py - FastAPI entry point and Redis router.
• backend/agent/ - LangGraph workflows and node logic.
• backend/mcps/ - MCP servers for tasks, memory, economy, and governance.
• backend/services/ - Database models and service functions.
• frontend/app.py - Streamlit dashboard and event console.
• misc/seeds_n_test.py - Database bootstrap and memory test harness.
• docker-compose.yml - Local Redis and PostgreSQL services.

Getting Started

Prerequisites

• Python 3.13 or newer
• PostgreSQL with pgvector support
• Redis 7+
• A compatible OpenAI-style model endpoint configured for the LangChain client

Environment Variables

Create a .env file with the connection values for your environment. The codebase currently expects at least:

• DATABASE_URL - PostgreSQL connection string.
• OLLAMA_API_KEY - API key used by the language model client.

Local Services

Start the infrastructure:

docker compose up -d

Backend API

Run the FastAPI runtime:

fastapi dev backend/api/main.py

Frontend Dashboard

Run the Streamlit console:

streamlit run frontend/app.py

Seed and Test Utilities

The repository also includes a test/seeding harness for database bootstrapping and memory retrieval and agent population:

python -m misc.seeds_n_test.py
python -m misc,seed_workforce.py

Runtime Flow

1. A macro event is injected from the frontend or a direct API call.
2. The event is written to the Redis stream.
3. The router dispatches it to the CEO, Strategy, or operational workers.
4. The Strategy agent generates a task DAG for the current cycle.
5. The Research and Builder agents work only on the current cycle task IDs.
6. The Reviewer agent checks only the current cycle batch.
7. Task status updates are written back to PostgreSQL.
8. The frontend reflects the latest task DAG and working process.

Current Scope

This v1 build focuses on a functioning organizational execution loop rather than full production hardening. It currently includes:

• Redis-based event orchestration.
• Task DAG creation and cycle scoping.
• MCP-based worker tool access.
• Memory storage and retrieval.
• Governance and token budget hooks.
• A live dashboard for task and event observability.

Roadmap

The next version of the system would naturally extend in three directions:

• Real-world tooling: add a research MCP backed by live web browsing or crawling.
• Deployment: package and deploy the runtime to a cloud environment.
• External triggers: connect the event stream to Slack, email, or other external inputs.

Notes

• The architecture is intentionally event-driven so the workflow can be traced end to end.
• The current-cycle task IDs are now part of the control flow, which prevents older pending tasks from being mixed into a fresh run.