No Turn Order in Parallel
Message-passing tutorials assume agents take turns. Parallel agents don't wait for a message that hasn't been sent yet.
Multi-Agent Shared Context
Multiple Agents.
One Source of Truth.
Give every agent access to the same durable context. Decisions, discoveries and updates become instantly available across your entire workflow—without prompt sharing or duplicated work.
status: ok▸ sw-run-8841switch mode
--mode statewaveAgent log
Planner
Deprecating legacy-session-token, replaced by JWT.
Coder
Reading shared context before starting implementation… Skipping legacy-session-token because it is deprecated. Building jwt-auth instead.
context used2 memories
Reviewer
No conflicts found. The Coder read the Planner's deprecation before acting.
$ python main.py --mode statewaveRun
Shared context
subject: sw-run-8841architectural_decisionscore 0.92
Deprecation: legacy-session-token
implementation_notescore 0.85
Built: jwt-auth, rbac, login, logout
review_findingscore 0.79
STATUS: CLEAN
Conflict avoided: read before write
Problems
The Cost of Message-Passing Only
Without shared context, agents repeat work, lose decisions and rely on fragile handoffs to stay aligned.
Conflicts Caught Too Late
The Reviewer catches the conflict only after both agents have finished. The wasted compute can't be recovered.
"Did Someone Decide This?" Is a Guess
Without a shared authoritative layer, every agent is reconstructing state from whatever messages happened to reach it.
Features
One Subject. Every Agent Reads It.
Every role operates from the same durable context while preserving its own actions, decisions and provenance.
01
PlannerT+0.0s
architectural_decision
Content
Deprecate legacy-session-token and replace it with JWT.
02
CoderT+4m 0s
implementation_note
Built jwt-auth, RBAC, login and logout.
03
ReviewerT+4m 45s
review_finding
STATUS: CLEAN
3 episodes persistedappend-only
Every decision is an episode
create_episode() records one raw fact per agent action. Cheap, append-only, no interpretation yet.
01
create_episode()
Planner records its architectural decision.
02
compile_memories_wait()
compileThe decision becomes active and readable by every agent.
03
get_context()
Coder reads the decision before writing any code.
collision prevented before execution
Read before write, always
The Coder's context read happens before it decides what to build, not after. That ordering is what prevents the collision instead of just detecting it.
LangGraphClaude Agent SDKCrewAI
agent.py
bundle = shared.before_acting(
caller_id, task
)
result = agent.run(task, context=bundle)
shared.decide(caller_id, result.decision)
SharedContext unchangedonly the harness changes
Portable Across Frameworks
SharedContext isn't tied to this repo's agents. Wrap the same before_acting()/decide() pair around any CrewAI tool or Claude Agent SDK loop.
Shared subjectactive
subject_id = "sw-run-8841"
p
planner
c
coder
r
reviewer
caller_id attributes every read and write
All three roles read and write the same subject. “Did someone already decide this?” becomes a lookup, not a guess.
Same Subject, Every Role
One run, one subject_id. Every agent in the fleet reads and writes that same shared context, automatically.
Reference Builds
One Repository.
Three Ways To See It.
Compare the same workflow before and after Statewave, then inspect the complete execution history behind every decision.
PythonLiteLLM
The Collision, Before Statewave
python main.py --mode naive runs the same task with message-passing only. The Coder never sees the Planner's deprecation and rebuilds the dead module from scratch.
python main.py --mode naivemessage passing
PlannerDeprecates legacy-session-token and replaces it with JWT.
CoderNo shared context found. Building from task description only.
CoderImplements legacy-session-token and jwt-auth simultaneously.
✕Collision detected
Reviewer detects duplicated work only after both agents have finished. Compute has already been wasted.
PythonStatewave SDK
No Collision, After Statewave
python main.py --mode statewave runs the identical task on a shared subject. The Coder reads the deprecation before writing any code and skips the dead module entirely.
python main.py --mode statewaveshared context
PlannerDeprecates legacy-session-token and replaces it with JWT.
PlannerCompiles the episode so the decision is immediately readable.
CoderReads architectural_decision with 0.92 relevance before acting.
CoderSkips legacy-session-token and builds jwt-auth instead.
Conflict avoided
The Coder read the Planner's deprecation before acting, so the obsolete module was never rebuilt.
PythonRich
The Full Audit Trail, on Demand
timeline_inspector.py --run <id> prints the chronological chain for any run: what each agent knew when it acted, what it wrote and the final memory state.
timeline_inspector.pyaudit trail
TimeRelAgentEvent
14:01:00ZT+0.0sPlannerArchitectural decision → Deprecate legacy-session-token
14:01:12ZT+12.1sPlannerEpisodes compiled into shared memories
14:01:15ZT+15.3sCoderRetrieved 2 memories before implementation
14:05:00ZT+4m0sCoderBuilt jwt-auth, RBAC, login and logout
14:05:45ZT+4m45sReviewerReview completed · STATUS: CLEAN
Prevention
Prevented,
Not Just Detected.
Traditional pipelines review conflicts after the work is done. Statewave gives the Coder the right context before it decides what to build.
- Every write is compiled before the next agent reads.
- Runs on Postgres with no extra coordination infrastructure.
Pipeline comparison
Context available before execution
Naive pipeline
Message-passing only
Coder's context before actingtask string only
The Reviewer detects the conflict only after both agents finish.
Statewave pipeline
Shared subject
Coder's context before acting2 ranked memories
The deprecation is known before the first line of code is written.
PythonCLI
from statewave_agents.context import
SharedContext
bundle = shared.before_acting(...)
result = agent.run(...)
shared.decide(...)
PythonCLI
python timeline_inspector.py \
--run sw-abc12345
✓ chronological replay generated
Integration
Two Calls.
That's The Primitive.
Call before_acting() before an agent decides, and decide() after it produces output. Wrap those two calls around any existing agent loop in minutes.
- Same two calls in CrewAI, Claude Agent SDK or a custom agent loop.
- LiteLLM-backed, so providers can be swapped without changing your workflow.
Why Statewave
Memory Built
For Real Agents.
Everything agents need to remember, retrieve and explain, without turning raw conversation history into your architecture.
Typed, Ranked Memory
Every fact is classified and scored, so agents surface the most relevant context instead of searching through raw history.
Multi-User by Default
Memories stay isolated by user and agent, making personalized sessions safe to run at scale.
Token Budget Control
Set a hard ceiling and Statewave fills it with the highest-signal memories without exceeding the limit.
Durable Across Sessions
Memory survives restarts and redeployments, so agents continue with context from the first message onward.
Full Audit Trail
Every recalled fact links back to its source episode, showing exactly what an agent knew and when.
Sub-150ms Recall
Retrieval stays fast enough for real-time conversations without adding noticeable delay to agent responses.
FAQ
Frequently asked questions
How is shared context different from message passing?
Message passing assumes an ordering parallel agents do not have — an agent cannot wait for a message nobody has sent yet. Shared context inverts it: before_acting() reads the authoritative bundle for the run’s subject before an agent decides, and decide() writes the outcome back as an episode. "Did someone already decide this?" becomes a lookup against one store rather than a guess about which messages happened to arrive.
What actually stops two agents from duplicating work?
Ordering. The Coder’s context read happens before it chooses what to build, not after — so the Planner’s deprecation is known before the first line of code exists, and the obsolete module is never rebuilt. A reviewer-style check catches the same conflict only once both agents have finished, and that compute is unrecoverable. Prevention is a read-before-write discipline, not a smarter conflict detector.
How do I audit what an agent knew when it acted?
Every read and write carries a caller_id and the run is one subject_id, so timeline_inspector.py --run <id> prints the chronological chain: what each agent read, what it wrote, and the final memory state. For compliance-grade runs, context assembly can also emit a state-assembly receipt with a SHA-256 hash of the exact bytes delivered and the content hash of the policy bundle applied.
Do I have to rewrite my agents to use it?
No. SharedContext wraps whatever loop you already run — the same before_acting() and decide() pair goes around a CrewAI tool or a Claude Agent SDK loop, and each agent keeps its own prompt and model. Coordination runs on Postgres with no extra infrastructure: no message broker, no scheduler, and no graph database to operate alongside it.
Answers last checked against the Statewave docs and repositories on .
START BUILDING
Give every agent
the same truth
Shared memory that keeps every agent aligned before work begins, preventing duplicated decisions and conflicting implementations.