Cosmonapse/cosmonapse-core

Cosmonapse

A platform suite for event-driven AI systems - design them on a canvas, run them on an open protocol, watch them think. No orchestrator loop.

Quick Start • The Suite • Architecture • Why • Docs

pip install cosmonapse    # the cosmo CLI ships with it
cosmo genesis             # opens the designer at 127.0.0.1:7072

Cosmonapse models a multi-agent system on a nervous system rather than a supervisor. Components emit Signals and react to Signals on one bus; nobody holds the loop. You grow a system by adding a node, not by editing a god object - and because every interaction already crossed one bus in one envelope format, tracing costs nothing.

cosmonapse.com · PyPI · Envelope Spec · Examples · Roadmap · Changelog

Graph and loop frameworks ask you to declare control flow before you know what the system does: nodes, edges, branches, and a supervisor that turns the crank. That holds until something arrives you didn't draw - a tool returns late, a human answers halfway through, a second model disagrees with the first.

Real systems are concurrent and only partially ordered. Encoding one as a graph means encoding time as topology, and you end up maintaining a state machine larger than the problem. Cosmonapse takes the other side: concurrency, fan-out, retries and ordering are properties of the transport - the same properties that have run distributed systems for twenty years - rather than branches you drew in advance.

They share exactly one thing - the Signal envelope. That is what lets the designer, the runtime and the observability plane stay honest about the same system without any of them owning it. Genesis and Prism both ship inside the cosmonapse wheel; there is nothing extra to download and no runtime dependency on either.

Genesis writes onto the bus, Prism reads off it, and Core is the bus. None of the three owns the system, which is the only reason a designer and an observability plane can describe the same running program without either becoming a dependency of it.

Canvas - place a component and Genesis writes the module, wires it into brain.py, and lands the node on the ring around the Synapse. Each primitive keeps its silhouette: circle, diamond, triangle, cup.

Code - the declaration as a form and the handlers as code boxes. Edits are applied through the AST, so the file that comes back is your file with one node changed, comments and all.

Test - Run starts brain.py as a real process; Connect opens whatever that Receptor actually is - a terminal on its stdin and stdout, a request builder, or a chat panel.

pip install cosmonapse

cosmo init my-app -n demo
cd my-app
python brain.py

cosmo init writes a working brain, not a hello-world file:

my-app/
├── brain.py            # the entry point - attaches every node, serves every interface
├── config.py           # namespace + synapse URL
├── neurons/hello.py    # a Neuron: an async function behind an Axon
├── effector/tools.py   # an Effector: a tool family
├── engram/store.py     # an Engram: memory as a protocol citizen
└── receptors/terminal.py   # a Receptor: the edge a turn arrives at

python brain.py starts every node and drops you into a REPL on the terminal Receptor. It also takes one-shot forms, which map onto the three dispatch modes:

python brain.py greet --name Ada    # dispatch_and_wait
python brain.py --stream greet      # dispatch_and_subscribe
python brain.py --send greet        # dispatch_task, fire and forget

New Neuron modules go under neurons/, tool families under effector/, interfaces under receptors/; wiring stays in brain.py. The same code over a real broker:

cosmo synapse start memory --namespace=demo
SYNAPSE_URL=cosmo://127.0.0.1:7070 python brain.py

Or skip the terminal entirely and grow it on the canvas with cosmo genesis.

Nothing above is required. A brain is two objects and a function:

import asyncio
from cosmonapse import Axon, Dendrite, MemoryRegistryStore, connect_synapse

async def main():
    synapse = await connect_synapse("cosmo://127.0.0.1:7070")
    try:
        async def answerer(input, context):
            return {"answer": input["q"]}

        worker = Dendrite(synapse=synapse, namespace="demo")
        worker.attach_axon(Axon(neuron_id="answerer", neuron_fn=answerer))

        orch = Dendrite(synapse=synapse, registry_store=MemoryRegistryStore(),
                        namespace="demo")

        @orch.on_agent_output
        async def done(sig):
            await orch.emit_final(trace_id=sig.trace_id, parent_id=sig.id,
                                  result=sig.payload["output"])

        async with orch, worker:
            await orch.dispatch_task(neuron="answerer", input={"q": "hi"})
            await asyncio.sleep(0.5)
    finally:
        await synapse.close()

asyncio.run(main())

The Neuron is a plain async function. No base class, no inheritance, nothing to import into it.

A system, moving. A request arrives at a Receptor and crosses the bus into a Neuron; the memory read and the tool call that follow are Signals on that same bus, and so is the tool's answer coming back. There is no call stack in that picture and nobody is holding a loop - just four participants and one medium, which is why any of them could have been on another machine, and why a fifth could watch the whole thing without being wired to anyone.

Four kinds of participant hang off one Synapse, and the division of labour is the whole design: Neurons think, Engrams remember, Effectors act, Receptors listen. Each keeps one silhouette across the suite - you place that shape in Genesis and watch the same shape light up in Prism. This is the long version of the lexicon table above.

Every Signal carries its own id, the trace it belongs to, and the id of whatever caused it. That is not instrumentation you add - it is the envelope, filled in whether or not anyone intends to look. Which is why "why did this happen" is walking up a tree rather than grepping a log, and why you would have to work to not have a trace. See design/ENVELOPE_SPEC.md for the full wire format, or run cosmo schema for the machine-readable version.

A Neuron can pause and ask instead of returning. A __clarification__ or __permission__ marker becomes a CLARIFICATION / PERMISSION Signal that another Dendrite - or a person, through cosmo answer - resolves. Paired with an Engram, an answered question or a granted permission is recalled rather than re-asked. No custom plumbing, no separate approval service.

The transport is pluggable because Cosmonapse is a protocol, not a runtime. The same component code runs across every one of them.

Other extras: [postgres] for a Postgres-backed Engram, [receptor] for the FastAPI-served HTTP and chat Receptors. A CliReceptor needs nothing beyond the core install.

An ordinary consumer joins a queue group, so exactly one of them gets each message. A Doppler joins none: it competes for nothing, sees every Signal, and can never take work away from a participant. cosmo prism is that seat rendered in a browser; cosmo prism --tail is the same stream on stdout. Neither is privileged - anything willing to speak the envelope can take the same seat.

Brain View - the live graph. Each node is tinted by the last Signal type it emitted; a request and the reply it provokes are drawn as one journey through the Synapse rather than two unrelated blips.

Constellation - one run as its execution graph, edges typed by channel (task, tool, recall, imprint, output). Repeated runs of the same prompt carry a structural consistency score, so a refactor that changed the shape of the system shows up as a number.

Signal Tree - every Signal of one task arranged by parent_id. Each edge is causal parentage, so "why did this happen" is walking up ancestors rather than grepping a log.

Signal List - the chronological record. Tasks as collapsible rows, Signals indented by lineage, any row expandable from payload to the full envelope, and the whole trace exportable as text.

Metrics - health, latency, task time composition, human-in-the-loop, memory effectiveness and participants. Every number is derived from timestamps and parent links already in the envelope, so nothing had to be instrumented to be measured.

Python is the single first-party SDK. Nothing about the protocol is Python, though: the envelope spec plus cosmo schema is everything an implementation in another language builds against, and anything that emits and accepts valid Signals is a participant on the bus. See DECISIONS #19 for why there is one reference implementation rather than two.

Runnable end-to-end examples - routing, bidding, retries, RAG, MCP tools, memory, full agents - live in their own repository: Cosmonapse/cosmonapse-examples.

• Python SDK README - install, quick start, API, CLI
• ENVELOPE_SPEC.md - the Signal wire format
• SDK_DESIGN.md - design rationale
• ENGRAM_DESIGN.md - shared memory design
• RECEPTOR_DESIGN.md - interface layer design
• CONTRIBUTING.md - how to set up and contribute
• CHANGELOG.md - release notes

The diagrams above are generated from the same components that draw them on cosmonapse.com, so a figure here cannot drift from the one on the site. The screenshots and recordings are Genesis and Prism as they ship in the wheel, captured from a real run.

Apache 2.0 © 2026 Aqib Khan