Every Session Starts Cold
Users repeat their background, preferences, and history every time, even when the conversation is clearly ongoing.
One Assistant. Every
Session Remembered
Agents work better when they actually know who they're helping, every session, every time.
●statewaveon▸ dev_aliceswitch user
token budget: 800Chat
Hey, picking back up. Where did we leave off?
What was the bug I was debugging last session?
You were hitting 429s on batch embedding jobs, an undocumented per-IP burst limit (~500 req/10s). Did the tenacity backoff fix land?
memory usedep_0012 · 761 tok
What was I building?Any open issues?
Type a message…Send
Memory state
/v1/contextprofile_factscore 1.00
RAG code assistant. Python only.
procedurescore 0.94
429 workaround: tenacity backoff
episode_summaryscore 0.87
Session covered streaming + function calling setup
artifact_refscore 0.71
chunking_strategy.py · v2 draft
✓4 memories compiled · 761 tokens
Problems
The cost of stateless chat apps
Without durable memory, every session starts from scratch and every prompt carries more history than it needs.
Context Runs Out Fast
After 8–10 turns the context window is full. Earlier facts are silently dropped to make room for recent ones.
No Ranking Signal
Stuffing raw history into every prompt means a throwaway comment gets the same weight as a critical bug report.
Features
The memory does the merging
Statewave keeps every episode intact, compiles what matters, and returns the right memory without losing the history behind it.
Current Session
Session 7 · Jul 8, 4:12 PM
User ·Let's try streaming instead of polling for the dashboard updates.
Session 3 · Jun 4, 9:50 AM
User ·Poll every 5s for now, it's fine.
Session 1 · May 22, 8:03 AM
User ·Kicking off the RAG code assistant project.
●3 episodes · content-hashed · immutable
Every finding is an episode
Every turn is recorded as an episode: one user message, one reply. Episodes are appended, never merged, so the full history stays in the log.
1
POST /v1/episodes
Record one user turn + assistant reply
2
POST /v1/memories/compile
Idempotent. Same subject in, same bytes out.
3
POST /v1/context
Ranked, budget-bound context bundle
Ingest. Compile. Use.
Three endpoints handle the whole loop. Compile is idempotent. Run it again and again on the same subject, same query, same bytes back.
OpenAIClaudeCrewAI
context = await _get_context(uid, msg)
system = base + f"\n{context}"
assistant = Agent(backstory=system)
● memory layer unchangedonly the model call changes
Portable Across Frameworks
The same two calls work with OpenAI, Claude, or CrewAI. Swap the model layer freely; the memory layer never changes.
What update approach am I using for the dashboard?
supersededjaccard 0.81
Session 3: poll every 5s
You switched to streaming with exponential backoff in session 7. That's the active approach now.
Personalizes at Scale
Every subject_id compiles its own memory. dev_alice and dev_bob never see each other's context, automatically.
Reference builds
Three quickstart examples. One live comparison.
Start with the smallest possible integration, add a visible memory panel, or wire the same pattern into an agent framework.
The two-call pattern, nothing else.
minimal-quickstart is a single Python file: no framework, no UI. Just get_context before the model call and create_episode after it, the fastest way to see the integration surface.
PythonNo framework
context = await get_context(user_id, message)
reply = call_llm(context, message)
await create_episode(user_id, message, reply)
● three lines, one file
A chat panel and a memory panel, side by side.
chat-react-standalone pairs a React frontend with the same two-call pattern. Every compiled fact appears grouped by kind, scored, and sourced to its episode, refreshed after every reply.
ReactFastAPI
Chat
Hey, picking back up. Where'd we leave off?
What was the bug I was debugging?
429s on batch embeds: undocumented burst limit. Did the tenacity backoff land?
memory usedep_0012
Type a message…Send
Memory
profile_fact 1.00
RAG code assistant
procedure 0.94
tenacity backoff fix
episode_summary 0.87
streaming + fn calling
artifact_ref 0.71
chunking_strategy.py
Memory wired into an agent framework.
support-agent shows the same two calls injected into a CrewAI-style support bot. Context goes into the agent's backstory at construction time, and the episode is recorded from the final output.
CrewAIPython
context = await get_context(user_id, message)
backstory = base + f"\n{context}"
agent = Agent(role="Support", backstory=backstory)
result = Crew(agents=[agent], tasks=[task]).kickoff()
await create_episode(user_id, message, str(result))
● memory layer unchanged
Context retrieval
Only the highest-confidence facts reach the prompt
get_context() ranks compiled memories and returns only what fits the configured token budget, ready to inject into your agent.
STATEWAVE_MAX_TOKENS enforced on every call
Confidence-ranked memories before throwaway conversation
Raw conversation history
Tokens to LLM~2,800 / session
6 sessions of raw history. No ranking signal.
Statewave context bundle
Tokens used, average761 / session
Only the highest-confidence facts, within budget.
●Context compiled
Developer API
Three endpoints. That's the whole API.
Wrap your LLM with two calls—retrieve context before inference and record the episode afterwards. The client drops into any FastAPI app in minutes.
Same two calls in FastAPI, Flask, or a bare script
OpenAI-compatible: swap the model, keep the memory
Why Statewave
Purpose-built memory for AI agents
A focused memory layer designed for production agents, with durable context, predictable token usage, and infrastructure you control.
Self-Hosted, No Cloud Account
Runs on your own Postgres with pgvector. No SaaS plan, no sign-up, no vendor API key.
Multi-User by Default
Memories are scoped per subject_id. Any string becomes a user, created on first episode write.
Token Budget Control
Set STATEWAVE_DEFAULT_MAX_CONTEXT_TOKENS and Statewave always fits within it, highest-confidence facts first.
Durable Across Sessions
Episodes are appended, not merged. Compiled memory survives restarts and redeploys.
Full Audit Trail
Any context call can produce an HMAC-signed receipt tracing facts back to their source episode.
Fails Open, Never Blocks
If Statewave is down, context comes back empty and the episode write fires and forgets. Chat never errors.
FAQ
Frequently asked questions
How much code does it take to give an assistant memory?
Two calls. get_context(user_id, message) before the model call, create_episode(user_id, message, reply) after it — the minimal-quickstart example is a single Python file with no framework and no UI. Everything else is optional: compilation runs as a background pass, and the React reference build adds a panel rendering each compiled fact grouped by kind, with its confidence score and source episode.
How is this different from replaying chat history into the prompt?
Raw history carries no ranking signal — a throwaway aside weighs the same as a critical bug report, and after eight to ten turns the window is full and early facts are silently dropped. Statewave keeps every turn as an immutable episode, compiles the durable parts into typed memories with confidence scores and provenance, and returns only what the current question needs, ranked and packed to a token budget you set.
Can one user’s memory leak into another’s?
Not by construction. Every episode and memory is scoped to a subject and retrieval is per-subject, so dev_alice and dev_bob compile and read separate memory with no shared candidate set on a single instance. Multi-tenant deployments add per-memory sensitivity labels (pii, financial, secret) and a declarative policy engine that filters on caller identity, with require_caller_identity available to make anonymous calls fail closed.
Does it lock me into one model or framework?
No. The same two calls sit in front of OpenAI, Claude, or CrewAI, because Statewave returns text a prompt can carry rather than a model-specific structure. Compilation routes through LiteLLM (100+ providers, including self-hosted Ollama and vLLM), retrieval is provider-agnostic, and the runtime is an HTTP service with two thin SDKs — swap the model layer and the memory layer does not change.
Answers last checked against the Statewave docs and repositories on .
START BUILDING
Give your assistant memory
Start building with Statewave in about 5 minutes. Self-hosted, open source, and ready for production.