Shared medium

The shared medium

Everything in this library is a fold over one thing: an ordered, attributed, append-only transcript that several agents read and write. This page is about that transcript as a medium — what it is made of, what its physical properties buy and cost, and what it deliberately does not carry.

The mechanics built on top are on Hive episodes and Trace grammar. The reading behind them is on Further reading, with the equations in docs/research/.

What a record is

pub struct LogMessage {                       // the host's row
    pub sequence: Sequence,
    pub chat_id: Option<String>,
    pub parent: Option<Sequence>,
    pub author: SessionAuthor,
    pub content: String,
}

pub struct SessionMessage {                   // what a participant reads
    pub sequence: Sequence,
    pub author: SessionAuthor,
    pub content: String,
}

Three facts about this shape are load-bearing.

One address space. Sequence(u64) is the host's monotonic log position, and everything hangs off it: thread membership is parent, a conversation is (desk, thread_root), a citation is ^N, a read cursor is a watermark, an episode boundary is a sequence, and a dispatch idempotency key is a trigger_sequence. There is no second identifier and no second journal, so there is nothing to keep consistent with anything.

Attribution never collapses. SessionAuthor distinguishes an operator, a person, an agent, and a system notice, and it survives projection. This is the first defect the library exists to fix: the host it came from produced a (role, content) pair, so on a shared desk agent B read agent A's replies as B's own prior turns.

A record is immutable. Nothing edits a message. That is a deliberate refusal rather than a missing feature — see Revisability below.

What the medium buys, in Clark and Brennan's terms

Clark & Brennan (1991) list eight properties a communication medium either has or lacks, and each one changes which kind of grounding is cheap. A persistent shared transcript sits at a specific point on that list, and it is worth being explicit about where.

property	here	what follows
Reviewability	yes	The whole point. Any participant can re-read any earlier turn, and a decision can be audited back to the messages that carried it.
Sequentiality	yes	Sequence is a total order the host assigns, so "the next turn" is a reliable signal. Most multi-writer systems have to buy this with vector clocks; a coordinator gives it away.
Simultaneity	no	One message, one turn. Nobody writes while anybody else writes.
Revisability	no, deliberately	A message that changed after it was read would make every ^N a citation of something that no longer says what it said. Corrections are new records, not edits.
Cotemporality	no	There is no clock. Salience decays by sequence rank, not by elapsed time.
Copresence, visibility, audibility	no	Every cheap back-channel signal of understanding — a nod, an "uh huh", a puzzled look — is unavailable. Acknowledgement has to be written, and writing it costs a turn.

The last row is the one with consequences. repetition_cap counts how many distinct peers have acknowledged a point, but acknowledgement is inferred from a trace citing it rather than stated. A room cannot distinguish silence from assent, and that is a known gap rather than a solved problem.

One log, many projections

The medium is a single full-fidelity log. What each participant sees is a pure function of it:

• project_session — bounded, chronological, conversation-scoped. A thread reader sees the root and its direct replies; a channel reader sees every root plus each root's first reply, and never the interior of a thread it is not in.
• prepare_delta — the same walk from a watermark, so a bound agent keeps up with peers without re-reading.
• project_for — the episode's visibility filter. Under Visibility::Blind a participant sees the task, its own work, and everything below the episode watermark, but not a peer's position taken since the room opened.

This is the shape that resolves an argument the multi-agent literature has not. Cognition's position is share full traces, because a summarized message loses the reasoning and parallel writers then make conflicting implicit decisions. Anthropic's is that repeated condensation plays telephone with citations and that token usage explains most of the performance variance. Both are right, and they only conflict if narrowing what a reader sees also narrows what is available. Here it does not: the log is complete and the projections are cheap, deterministic, and rebuildable.

What the medium does not carry

Stated plainly, because each of these is a decision and several are on the roadmap.

• parent, after projection. SessionMessage drops it, so the channel-level narrowing has to happen inside the paging walk and cannot be a fold a caller applies. (P11.)
• A structured payload. Traces are re-parsed from prose on every read. trace::resolve already accepts an authoritative supplied list and revalidates it against the body — the right shape, with nowhere to put the result. (P11.)
• Per-conversation read state. SharingState is one scalar watermark. That is only correct on a single timeline, and the goal of the thread work is an agent holding two conversations in one desk at once. Matrix had to retrofit exactly this. (P12.)
• Compaction that keeps citations resolvable. Truncation is silent, and a ^N below the window resolves to nothing — indistinguishable from a fabricated citation. (P13.)
• Supersession. Two contradictory !evidence traces both stand forever. (P13.)
• A who-knows-what directory. The roster answers who is here, not who knows what. This is Wegner's transactive memory, and its absence is exactly why a room can hold the fact that settles a question and never route the floor to the member holding it. (P10.)
• Feedthrough. An agent's tool calls and file edits are invisible unless it narrates them, so the only awareness channel is the expensive one.
• A second journal. Not missing — refused. The host owns storage, and a second append-only log could not be made consistent with the first.

Where this sits in the landscape

what	who does it	what this library takes
Immutable log plus a per-reader cursor	Kafka	The whole architecture, including that compaction must never renumber.
Mandatory, total conversation scope	Zulip	Every record is in a conversation; scope is never optional. Slack's optional threading is the counterexample.
Content hash as a citable address	Matrix	Not taken — a coordinator-assigned sequence is simpler and gives total order for free.
Two tiers over one stream	AutoGen	Not yet taken; it needs the sidecar.
Structured payload beside prose	MetaGPT, Semantic Kernel, A2A	Not yet taken. (P11.)
Bi-temporal supersession	Zep/Graphiti	Not yet taken. (P13.)
Deterministic merge	event sourcing	Taken, absolutely. Mem0's LLM-arbitrated writes are the thing to avoid.

Full notes, with citations, are in docs/research/shared-context.md.