Skip to content
cynapsecynapsecynapse

How cynapse fits together

Each fact has one home. Subjects live in the stores that own them, the conversation about them lives in cynapse, and the runtime that launches agents decides when to wake them.

How cynapse fits with stores, consumers and the runtimeConsumers (agents, people, UIs) fetch from and write back to the external stores directly, and append to, read and compose through cynapse. The runtime launches and wakes consumers, registers participants with cynapse and polls it for changes. cynapse refers to subjects in the stores by reference and never calls them. Its channels live in stock SQLite outside any repository; a hub is planned for more than one machine. Only distilled results reach a repository.CONSUMERSAgents · people · UIs such as Cortexeach with its own credentials for the storesSTORESGitHub · Asana · Linearhold the subjects:issues, PRs, tasks,repositoriesrelations as metadataon both endsCYNAPSEchannels of entrieskeyed by subjectseq order, threadscursors, tags, stateparticipants, addressesguides and composesRUNTIMEcyberlegionwakes sessionsobserves livenessclaims: which sessionacts as a roleresolves native IDsREPOSITORYdistilled results only:an ADR, a summarySTORAGEstock SQLite, WAL$CYNAPSE_HOME, no daemonHUB (PLANNED)owns seq beyondone machinefetch · write backappend · read · composelaunches · wakesregisterpollrefersby refsyncdistil
Solid arrows are calls; a dashed arrow is a reference or a planned path. Nothing points from cynapse to a store or to the runtime: cynapse holds no credentials, calls no store, and wakes no one. Channels keyed by subject, participant registration and the change poll are designed, not built (see Status).

What each part owns

Section titled “What each part owns”

The stores

Section titled “The stores”

GitHub, Asana, Linear and beads hold the subjects: issues, PRs, tasks, repositories. A subject’s metadata and its relations to other subjects (“#15 closes #12”) live there too, written on both ends. Consumers read and write these stores directly, with their own credentials. See Subjects across stores.

cynapse

Section titled “cynapse”

cynapse holds what none of those stores can: channels of immutable entries in seq order, with threads, per-reader cursors, tags and state records. It owns participant addressing and identity. For facts it doesn’t hold, it guides a consumer to the one call that fetches them, and composes what the consumer passes back. See What cynapse stores.

Consumers

Section titled “Consumers”

Agents, people, and UIs such as Cortex do the work. Each brings its own namespaced types: SDD writes sdd.decision entries, cyber-truss opens truss.arbitration channels. cynapse doesn’t know what a mission or an arbitration is.

The runtime

Section titled “The runtime”

A runtime such as cyberlegion launches agent sessions. It registers their participants with cynapse, polls cynapse for changes, and decides whom to wake. It also observes whether a session is alive, decides which session acts as a role, and resolves native IDs from the stores. See cynapse and the runtime.

Storage

Section titled “Storage”

One stock SQLite file per machine, outside any repository, shared by every process with no daemon. Past one machine, a hub will own seq. Only distilled results, such as an ADR or a reconciled channel’s summary, reach a repository. See Storage.

The rules

Section titled “The rules”
  1. cynapse stores only what no other store can. Everything else stays where it lives, and cynapse refers to it as gh:cyberuni/cynapse#12 (ADR-0011).
  2. cynapse holds no credentials and never calls a store. Auth, rate limits and APIs stay with the consumer (ADR-0011).
  3. Entries never change. An edit, a retraction or a later tag is a new entry. Every metadata change is written as an entry too (ADR-0003).
  4. Each channel has one order owner. seq is arrival order with no gaps: SQLite’s write transaction on one machine, the hub beyond it (ADR-0007).
  5. A channel is keyed by its subject, with no type in the key. Everyone working on #12 meets in #12’s one channel (ADR-0012).
  6. Hierarchy is a view, not identity. Relations live on the subjects, never in channel structure (ADR-0010).
  7. A message goes on the channel of what it is about. Work traffic on the work channel, direct traffic on the addressee’s address channel. cynapse never wakes anyone; the dependency runs one way, from the runtime to cynapse (ADR-0013).
  8. Raw conversation stays out of repositories. Agents reach it through narrow CLI reads, never by searching files (ADR-0007).

Expensive to unwind

Section titled “Expensive to unwind”

Most choices can be revisited cheaply. These can’t, because their values are written into every entry or relied on by every consumer:

  • the entry id shape (UUIDv7) and per-channel seq;
  • channel identity as a UUID, derived from an anchor or a key;
  • the channel key: a subject’s native ID, with no type;
  • the key format cynapse builds from a store and a native ID;
  • participant IDs derived from registration keys;
  • where traffic goes: work traffic on the work channel, direct traffic on the address channel;
  • cynapse holding no credentials and never calling another store;
  • cynapse never waking anyone and never measuring session liveness.

Cheap to revisit: relation names, the write-back triggers, how a reference shorthand renders, the storage engine and the hub technology behind the Store interface.

Read on

Section titled “Read on”