Synapsee

Parsing

Two stages: decode the wire format, then let the right parser claim the event.

Stage one picks a decoder by topic, turns the protobuf into a generic event, and writes it to a raw topic that ClickHouse reads. Stage two tries event parsers until one succeeds: one named for the topic first, then one named for its prefix, then the rest. Each parser checks for the shape it expects — Claude Code exports logs, LangGraph and ADK export spans — so a parser that can't read an event fails and the next one tries. The winner's agents, traces, compositions and communications go back to Kafka for the ingestor. A new runtime is a new parser.

Graph

What happened, as relationships, not as a log.

The API writes what the parsers found into FalkorDB. Agents take part in sessions; traces belong to a session and nest under their parents; a tool call is made by an agent and uses a tool; a message starts at one agent, targets another and belongs to a trace. Agents that work together form compositions. The dashboard draws this graph as its network view, and Heart queries it through the same API, so both see the same data. The raw events stay in ClickHouse for the trace view.

Analysis

Turn an OS agent run into a diagnosis and a concrete next step.

Open a trace or a whole session in Synapsee. The server reconstructs the goal, decisions, tools, outcomes and delegation patterns. A separate performance record examines eight areas: missing tools, hallucination, unused relevant tools, error recovery, context loss, prompt redundancy, delegation and promises the agent's capabilities cannot support.

The analysis combines labeled spans with measured context-token trends and a breakdown of the prompt. Each finding describes what happened, why it matters, its evidence and a recommended fix. A deterministic pass filters noise, resolves span citations and computes scores from the surviving findings. When configured, a TypeSafe judgement adds an impact and evidence assessment. A clean run can have no findings.

Investigation

Follow a finding back to the run that produced it.

The record carries session and runtime provenance, the OS build, the analysis prompt version and API links. Span citations resolve to stable trace and span IDs. Alongside the record, Synapsee saves an evidence bundle: spans for each trace, measured context tokens, the prompt breakdown and session activity when available. The records API exposes the bundle and resolves cited spans, checking saved evidence before the live span store.

This gives a developer something to inspect after the run: which tool failed, what context grew, or where the agent offered an action it could not perform. The record survives a failed bundle write; the evidence manifest reports missing or truncated data. Correlated application logs are still a later addition.

Self-improvement

Use the agent's own runs to decide what to change.

A performance finding is the starting point for improving the OS agent. A developer or coding agent reads the record, follows its evidence and changes the relevant prompt, tool or capability registration. Another run produces a fresh record to review alongside the original, checking the outcome, remaining findings and measured token usage.

For example, a prompt-redundancy finding must identify a prompt section and cite measured token counts. Its recommendation can propose a specific trim and estimate the saving. The next run provides new measurements to check whether that change helped while preserving the agent's ability to complete the task.

Analysis, recommendations and evidence retrieval are implemented in Zion OS. Applying changes and comparing runs is developer-driven today; automatic remediation, record lifecycle tracking and cross-run trend APIs are future extensions.