DEV Community: Statewave

Statewave Guide — Day 4: We passed the safety test. Then failed the product test

Statewave — Thu, 15 Oct 2026 20:53:57 +0000

Built 27 Aug 2026 · written up 14 Oct 2026

Yesterday I asked:

Can technically safe product knowledge survive contact with an actual user?

Not particularly. 😅

One model, one fixture, same as yesterday: every number below comes from anthropic-opus-5 against a single application we wrote ourselves, with patterns we knew to look for.

Wrong-feature claims accepted     0
Unsupported claims accepted       0
Model restraint                   30/30
Verified claim yield              95%

Nice.

Then we asked:

Would any of this actually help a human?

The usefulness scores below were not produced by people. A separate model, OpenAI GPT-5.6 Sol, scored the twenty-one features against a fixed rubric. It is not the model under test, so this is not self-scoring, but it is not a human review either, and no amount of it becomes one.

1 / 3   median usefulness
24%     rated genuinely useful

Nothing was dangerously wrong.

Nothing was completely useless either.

It was worse in a much more software-engineering kind of way:

almost everything was mediocre.

We assumed the remaining problem would be missing capabilities.

The data disagreed.

1.43   features with a verified capability
1.14   features without one

Barely a difference.

That was how we read it at the time. A later round, with the language problem below fixed, put the same split at 2.00 against 1.07. The capability signal was real; we were reading it through bad presentation.

Meanwhile:

14 / 21 outputs were too technical.

Thirteen of twenty-one were flagged as missing a capability.

Then we found the smoking gun.

Ten features exposed this sentence directly to the user:

"No capability, route or permission has been verified for this feature."

Every single one was rated too technical.

10/10.

Fair enough. 😂

That's not product copy.

That's a debugger having an existential crisis in front of the customer.

Another feature had excellent evidence:

✓ POST endpoint        ✓ Create permission
✓ Submit path          ✓ Button

And our deterministic renderer proudly produced:

"You can create a new invoices create form and submit the invoices create form form…"

Technically grounded.

Linguistically deceased.

That exposed another boundary.

We had already separated:

what the application does   from   what the model thinks it does

Now we needed to separate:

what we know   from   what a human actually needs to hear

So the architecture gained another layer:

Product Model        →  what do we know?
Guidance Compiler    →  what is worth telling the user?   ← new
Renderer             →  how should we say it?

No verification rules loosened.

No extra authority for the model.

We were finally admitting something painfully obvious:

Technically correct data structures do not automatically know how to talk to humans.

Shocking discovery for software developers, I know.

Statewave Guide — Day 4.

Next question:

Can we turn verified product truth into human guidance without inventing anything new?

This day in the repo: PR #4 · Previous: Day 3 — True is not the same as relevant

Statewave Guide is built on Statewave — an open-source, self-hosted memory runtime for AI agents. Governance and provenance, not just retrieval. Apache 2.0.

→ statewave.ai · github.com/smaramwbc/statewave

Every post in this series: The Statewave Guide Journey Index

Statewave Guide — Day 3: True is not the same as relevant

Statewave — Tue, 13 Oct 2026 14:55:32 +0000

Built 26 Aug 2026 · written up 12 Oct 2026

Yesterday I asked:

Can a model add product meaning to this graph without being allowed to invent product truth?

The answer is:

Yes.

But apparently factual truth still isn't enough. 😅

Today we finally put a real model behind Statewave Guide.

One model, one fixture: every number below comes from anthropic-opus-5 against a single application we wrote ourselves, with patterns we knew to look for. Read it as a measurement of a design change, not of what a model will do on your code.

The good news first.

Across hundreds of factual claims under deliberately hostile conditions:

Invented routes reaching the Product Model     0
Invented permissions                           0
Unknown subjects                               0
Forbidden capabilities refused                 27/27
Unsupported actions refused                    23/23

The verifier did its job.

Then came the less exciting number.

The model found the right evidence about 89% of the time…

…but only turned it into a verifiable product claim about 20% of the time.

89%   found the right evidence
20%   became a verifiable claim
71%   features with no verified capability

workflow recovery: 18%

So technically:

Very safe.

Practically:

A beautifully verified empty room. 😂

Then we found the interesting bug.

One claim passed verification that should never have been attached to the feature being analyzed.

The model said, roughly:

Settings changes are saved by submitting the settings form.

Structurally?

Correct.

The form exists.

It submits.

The relationship exists.

Every verification rule passed.

There was only one problem:

It was true about the application, but not about the feature we were asking about.

The verifier answered:

Is this statement supported by real evidence?

Yes.

What it didn't answer was:

Does this evidence actually belong to THIS feature?

That's a very different class of error.

And it gave us today's rule:

Truth is not enough. Context owns truth.

An application graph is a neighborhood.

Related components, sibling elements, routes and services naturally sit next to each other.

If an assistant can grab any true fact from that neighborhood, it can produce answers that are technically correct and completely irrelevant.

So the next layer became Feature Scope.

A claim now has to prove:

the subject exists
the evidence exists
the evidence supports the claim
the claim belongs to the feature being explained

We also learned that we were asking the model to do too much.

Find the evidence.
Choose the claim.
Choose the action.
Choose the subject.
Choose the relationships.
Then explain it.

The source graph already knows most of that.

So we changed direction:

Instead of:

Model → invent claim → Verifier

we moved toward:

Graph → deterministic claim opportunities → Model adds meaning → Verifier

Same safety boundary.

Less guessing.

And it worked.

Verified claim yield went from roughly 20% → 95%.

Wrong-feature claims went to 0.

Model restraint reached 30/30.

What did not move: 45 of 63 features still end with no verified capability. Safer, not fuller.

At that point we had something very safe.

So naturally we asked the question we should probably have asked earlier:

Does any of this actually help a human?

Statewave Guide — Day 3.

Next question:

Can technically safe product knowledge survive contact with an actual user?

This day in the repo: PR #3 · Previous: Day 2 — Unknown is better than wrong

Statewave Guide is built on Statewave — an open-source, self-hosted memory runtime for AI agents. Governance and provenance, not just retrieval. Apache 2.0.

→ statewave.ai · github.com/smaramwbc/statewave

Every post in this series: The Statewave Guide Journey Index

Statewave Guide — Day 2: Unknown is better than wrong

Statewave — Mon, 05 Oct 2026 19:24:05 +0000

Built 26 Aug 2026 · written up 5 Oct 2026

Yesterday's question was:

Can we follow one real user action all the way from a button to the backend — without guessing?

Yes.

But getting there was a useful reminder that even your benchmark can lie to you.

The target looked simple:

New Client
    ↓
openCreateClient()
    ↓
NewClientDialog
    ↓
submitClient()
    ↓
clientService.create()
    ↓
POST /api/clients

Frontend to backend.

One connected application graph.

No docs.

No manually maintained knowledge base.

Easy, right? 😅

Our first quality run had other ideas.

invokes precision: 39%

API detection: 19%

calls_api: 0%

Beautiful.

At least the tests were honest. 😂

Then something more interesting happened.

We found what looked like an indexer bug.

The benchmark expected:

GET /clients

The indexer produced:

GET /api/clients

My first instinct was to normalize them.

Turns out that would have been wrong.

One adversarial fixture had another router with /clients whose mount point could not be determined.

Strip /api from the known endpoint and suddenly two different routes become the same thing.

Congratulations.

We've manufactured product knowledge.

So instead of fixing the indexer…

we fixed the benchmark.

That became another rule:

A benchmark isn't truth.
It's an executable statement of what we currently believe truth is.

If the evidence proves the benchmark wrong, the benchmark loses.

We also introduced partial identities:

api:GET:?/clients

Meaning:

"I know this route exists. I do not know where it is mounted."

No guessing.

No helpful little inference quietly connecting it to the wrong backend handler.

After reconciliation:

API precision: 100%
invokes: 100% / 100%
uses_hook: 100% precision
uses_service: 100% precision
submits_to: 100%
renders: 100%
validates_with: 100%
calls_api: 83% precision / 100% recall

Across the graph:

0 relationships without evidence.
0 invalid confidence values.
0 unsupported inferences pretending to be facts.
0 / 37 adversarial trap violations.

437 tests green.

We also discovered our previous "deterministic output" wasn't actually deterministic.

Same repository.

Different working directory.

Different graph.

😬

Eight working directories later:

one hash.

Fixed.

One of the most important files we added might actually be refusals.md.

A catalogue of things the system intentionally refuses to infer.

One real-world pattern would have generated dozens of fake API endpoints if we'd taken the obvious shortcut.

So we didn't.

That's increasingly becoming the philosophy behind Statewave Guide:

Missing knowledge is fixable.
Wrong knowledge destroys trust.

So yes:

We can follow a real user action all the way to the backend without guessing.

Now comes the next problem.

We know increasingly well what happened.

But not necessarily what those facts mean to the user.

Statewave Guide — Day 2.

Next question:

Can a model add product meaning to this graph without being allowed to invent product truth?

This day in the repo: PR #2 · Previous: Day 1 — The DOM is not the product

Statewave Guide is built on Statewave — an open-source, self-hosted memory runtime for AI agents. Governance and provenance, not just retrieval. Apache 2.0.

→ statewave.ai · github.com/smaramwbc/statewave

Every post in this series: The Statewave Guide Journey Index

Statewave Guide — Day 1: The DOM is not the product

Statewave — Wed, 30 Sep 2026 20:40:00 +0000

Built 26 Aug 2026 · written up 30 Sep 2026

Yesterday I ended with:

Can source code become reliable product knowledge without developers maintaining another knowledge base beside it?

The answer looks like yes.

But definitely not by just reading the DOM.

Day 0 ended with:

141 files
~17k lines added
257 tests passing

and our first closed loop:

source code
    ↓
application graph
    ↓
running UI
    ↓
navigate
    ↓
highlight

So naturally I thought:

"Nice. This is going surprisingly well."

That feeling lasted about five minutes. 😅

Then we ran the implementation through adversarial review.

Everything was green.

And we still found:

a project path containing ( silently producing an empty graph
a React render loop happily heading past 300 renders
a selector injection edge case that could escape toward something like input[type="password"]
React 19 ref-cleanup behavior we weren't handling correctly
graph output changing depending on path capitalization
and a beautiful JavaScript classic where constructor inherited from Object.prototype and quietly disappeared from our graph

257 tests.

Still broken.

I love software. 😂

But the interesting part wasn't really the bugs.

It was what they forced us to clarify architecturally.

Eventually we want someone to ask:

"Where do I create a client?"

…and the application doesn't respond with six paragraphs of documentation.

It takes you there.

Highlights the control.

Explains it.

Eventually, it should even understand whether you've already done this twenty times and stop giving you the kindergarten tour.

But first we need to answer a harder question:

What does the application actually know about itself?

A browser DOM can tell us:

There's a button here.

That's nowhere near enough.

We need:

clients.create
      ↓
ClientsPage
      ↓
openCreateClient()
      ↓
NewClientDialog
      ↓
ClientForm
      ↓
submitClient()
      ↓
clientService.create()
      ↓
POST /api/clients

That is the difference between knowing the interface and understanding the product.

So we made an important decision:

The DOM is runtime evidence.
It is not the product model.

The product model starts with the source.

Routes.
Components.
Functions.
Forms.
Services.
APIs.
Permissions.
Schemas.
Tests.

Connected into an evidence-backed application graph.

And the running UI connects back to that graph through stable semantic IDs like:

data-guide="clients.create"

No arbitrary CSS selectors.

No hoping the third button inside the fourth <div> is still the third button after Friday's redesign.

We also adopted a rule that I suspect is going to survive this whole project:

Unknown is better than wrong.

If we can prove:

clients.create
    → invokes
    → openCreateClient

we store it.

With the file, symbol and line that prove it.

If we think something probably opens a dialog because the names look suspiciously similar?

We store nothing.

Missing knowledge can be improved later.

Confidently wrong product knowledge is how you build an assistant that confidently takes users to the wrong screen.

And once that happens twice, nobody trusts it again.

That rule isn't new, by the way. It's borrowed from one layer down.

In Statewave — the memory runtime underneath all of this — you don't write a memory directly. You record what happened, and memories are compiled from those events. Each one keeps the ids of the events it came from.

We're holding the product's own source code to the same standard.

So Day 1 isn't about chat.

It's about reconstructing the real application:

React UI
   ↓
handlers
   ↓
services
   ↓
HTTP
   ↓
Node API
   ↓
controllers
   ↓
business logic

If this works, developers may not need to maintain a separate product knowledge base at all.

Because the product already contains one.

We just normally call it source code.

Statewave Guide — Day 1.

Next question:

Can we follow one real user action all the way from a button to the backend — without guessing?

This day in the repo: PR #1 · Previous: Day 0 — The Beginning

Statewave Guide is built on Statewave — an open-source, self-hosted memory runtime for AI agents. Governance and provenance, not just retrieval. Apache 2.0.

→ statewave.ai · github.com/smaramwbc/statewave

Every post in this series: The Statewave Guide Journey Index

Statewave Guide — Day 0: The Beginning

Statewave — Mon, 28 Sep 2026 22:42:00 +0000

Built 25 Aug 2026 · written up 28 Sep 2026

The code is ahead of this story.

Statewave Guide has been built in public for a few weeks now — one commit per build day, all of it on GitHub.

What hasn't been public is the why: nearly every day ended with something we got wrong, and a rule we took away from it.

This series tells those days, in order, one or two a week. If you want the ending now, it's in the repo. The posts are about how we got there.

Here's where it started.

I wanted to add something fairly simple to an application:

A help chat that actually knows how the product works.

Not another little bubble in the bottom-right corner that politely links you to a 200-page documentation site nobody has opened since 2023.

Something that can answer:

"Where do I change this?"

…and instead of writing five paragraphs, it just takes you there.

Highlights the right element.
Explains what it does.
Walks with you through the workflow.

And eventually remembers that you already learned it last week, so it doesn't treat you like a new employee every Monday morning.

Sounds simple.

Obviously it isn't. 😅

So I started looking around.

There are great chat frameworks.
Great product-tour libraries.
Code documentation generators.
RAG systems.
Agent/UI protocols.

Lots of very good pieces.

But I couldn't find the thing I actually wanted:

Source code
    ↓
Product understanding
    ↓
Memory
    ↓
Interactive guidance
inside the real application

And one requirement became clear pretty quickly:

I don't want developers maintaining a second version of their application in Confluence just so the assistant understands the first one.

The code should be the source of truth.

Routes.
Components.
Forms.
API endpoints.
Schemas.
Permissions.
Tests.
Translations.
Git history.

There is already a ridiculous amount of product knowledge sitting inside a modern codebase.

We just don't normally call it documentation.

So this is where the experiment starts.

We're building our own guidance engine around Statewave.

No dependency on an existing tour engine.

We'll probably make some questionable architectural decisions.

We'll definitely delete a few of them later.

And I'll share the reasoning as we go — architecture, dead ends, trade-offs, weird bugs, and the occasional:

"This was a much better idea yesterday."

The repository starts now.

Statewave Guide — Day 0.

First question:

Can source code become reliable product knowledge without developers maintaining another knowledge base beside it?

This day in the repo: commit 5cb3c8a

Statewave Guide is built on Statewave — an open-source, self-hosted memory runtime for AI agents. Governance and provenance, not just retrieval. Apache 2.0.

→ statewave.ai · github.com/smaramwbc/statewave

Four of six open-source AI memory tools hold features back from the free build

Statewave — Mon, 28 Sep 2026 14:26:09 +0000

An Apache-2.0 badge does not tell you whether the feature you are switching for is in the free build. I counted 14 capabilities on Mem0's own Platform vs Open Source page that self-hosted users do not get, then went through five alternatives that come up in the same conversation, one vendor page at a time. Four of the six hold something back.

We build Statewave, one of the six, so weigh that entry accordingly. Every claim below links to the vendor's own page, our benchmark fork is public, and the section on our own tool ends with the things it does badly.

Mem0 is the default for good reasons

Worth saying before the criticism, because most posts in this genre skip it. Mem0 takes three lines of code to add, ships Python and JavaScript SDKs, and offers a hosted API. It raised $24M in October 2025 and reported API calls going from 35 million in Q1 to 186 million in Q3 2025. CrewAI, Flowise and Langflow use it natively, AWS picked it as the exclusive memory provider for its Agent SDK, and the repo is past 65,000 stars. For personalizing a chat assistant, that is hard to beat.

Trouble starts when you self-host, need an audit trail, or run several agents against one memory.

Where the self-hosted build stops

The OSS build is a different product. Mem0's own comparison page lists graph memory, memory decay, temporal reasoning, Dream background consolidation, webhooks, memory export, batch updates and deletes, feedback signals, summaries, custom categories, app-level scoping, orgs and projects, the project-wide event log and the web dashboard as Platform-only. Counted up, that is 14 capabilities, as of September 2026. Mem0's page also notes that the OSS SDK returns a not-supported error if you pass it the decay or temporal parameters.

Graph memory is the clearest case. Moving the open-source SDK to the v3 pipeline deleted roughly 4,000 lines of external graph store drivers covering Neo4j, Memgraph, Kuzu, Apache AGE and Neptune. Its migration guide tells OSS users who need graph memory to move to the Platform. Mem0's README carries its own caveat: benchmark scores reflect the managed platform, "which includes proprietary optimizations not available in the open-source SDK."

Graph memory and real retrieval volume start at $249 a month. Mem0's plans as of September 2026: Hobby free at 1,000 retrievals a month, Starter $19 at 5,000, Pro $249 at 50,000. Graph memory and Dream consolidation begin at Pro. Retrieval limits bite well before storage limits do. A support agent handling 300 conversations a day with three lookups per conversation is around 27,000 retrievals a month, more than five times the Starter allowance.

Audit logs, on-prem and SSO are Enterprise-only. Self-hosting does not fill that gap. Its OSS edition keeps a history for each individual memory and no project-wide log of adds, searches and deletes. It scopes memory by user_id, agent_id and run_id, with no app_id for separating tenants.

You cannot reproduce what the agent saw. Search returns whichever memories rank highest at the moment you query, and the OSS build does not store the exact set a given response was built from. When a customer asks why the agent told them their refund was approved, you are reading logs instead of looking up a record.

The edition line, across six tools

Here is what each vendor's own documentation says, as of September 2026.

Mem0: 14 Platform-only capabilities by our count, graph memory removed from OSS.
Zep: stopped maintaining Community Edition and moved its open-source work to Graphiti, which is a library rather than a memory service.
Cognee: running the whole memory layer on Postgres ships as a demo feature. The production-ready version is a licensed product.
Supermemory: the local build runs as one process on one machine with a single API key. Proprietary extraction models, multi-member orgs and connectors are Enterprise.
Letta and LangMem ship their memory engines in full.
Statewave has no paid edition. One question settles most of this: is the feature I am leaving Mem0 for included in the free build today, under the same license? Check the vendor's own edition or pricing page rather than a listicle. This one included.

Tool	Memory model	You run	Audit in the free build
Mem0 OSS (Apache-2.0)	Extracted facts + vector search	Vector store, LLM, embedder	Per-memory history only
Statewave (Apache-2.0)	Typed memories compiled from events	Postgres + pgvector	Source links, signed receipts, policies
Graphiti (Apache-2.0)	Temporal knowledge graph	Neo4j, FalkorDB or Neptune	Historical graph edges
Letta (Apache-2.0)	Agent-edited memory blocks	Letta App Server	Git-tracked memory
Cognee (Apache-2.0)	Graph + vector over docs and code	Pluggable stores	Inspectable evidence
LangMem (MIT)	Memory tools + background manager	LangGraph store	None built in
Supermemory local (MIT)	Memory + RAG engine	One local process	Server logs

The five alternatives, and the trade-off each one carries

Graphiti builds a knowledge graph that records when each relationship was true, so an agent can answer how a fact changed. In the Zep paper it beat MemGPT on DMR, 94.8% to 93.4%, and improved LongMemEval accuracy by up to 18.5% over baseline implementations. You pay for that in operations. Neo4j, FalkorDB or Neptune to run, Kuzu support deprecated, Zep's full memory service cloud-only now, and no receipts or access policies. Good fit for compliance and clinical agents, where "who owned this account before March?" is a real question.

Letta has the agent edit its own memory blocks, with context tracked in git and scheduled consolidation in the background. Its original repo is a landing page now, with active source in letta-code. One honest data point they published themselves: Letta agents on gpt-4o-mini scored 74.0% on LoCoMo just by storing conversation history in files, which Letta read as a sign that current memory benchmarks may not mean much. It is a framework you adopt rather than a layer you drop into an existing agent.

Cognee turns text into entities and relationships and code into a graph of symbols, behind four operations: remember, recall, improve, forget. Plugins for Claude Code and Codex. Watch the edition line here, since running the whole memory layer on a single Postgres database is a demo feature in the open-source build.

LangMem is MIT and gives agents tools to save and search memory mid-conversation, plus a background manager that consolidates what they learn, natively against LangGraph's store. Two cautions: the default in-memory store loses everything on restart, so production needs a Postgres-backed store, and the last PyPI release was 0.0.30 in October 2025.

Supermemory local puts memory and RAG behind the same API as the hosted platform, reports first place on LongMemEval and LoCoMo, and publishes MemoryBench so others can compare. Its local build is one process, one machine, one API key. Best for personal assistants and air-gapped experiments on a single box.

Our own entry, including where it loses

Statewave is a memory runtime rather than a vector store. Raw agent events are saved as immutable episodes, a compiler turns them into typed memories carrying a confidence score, a validity window and the IDs of the episodes they came from, and at answer time it builds a ranked context bundle that fits a token budget you set. Given the same subject, task and budget over the same memory state, it returns the same bytes.

We forked Mem0's own benchmark suite and changed only the memory backend, keeping Mem0's judge unchanged with gpt-4o as answerer and judge:

Benchmark	Statewave	Mem0 cloud	Mem0 OSS
LoCoMo (n=1,540)	0.905	0.899	0.866
LongMemEval (n=30)	0.967	0.933	0.833

Read those carefully, because I do.

Each is a single run rather than an average. Our LoCoMo margin over Mem0 cloud is 0.006, and a rerun can land either side of it, so nobody should treat it as a win. LongMemEval ran 30 questions, which makes it directional at best.

Two things cut against us specifically. We applied three fixes to Mem0's client code and every one of them raised Mem0's scores. And Mem0 OSS retrieves at most 20 memories per query by default, against roughly 200 for Statewave and Mem0 cloud, so part of that gap is retrieval budget rather than ranking quality. Which makes the cloud column the fairer comparison of the two.

Mem0 also publishes higher figures for its newer algorithm, 92.5 on LoCoMo and 94.4 on LongMemEval, from a different model stack than our fork runs. The full methodology is public and the fork diffs against upstream.

Where it loses:

Self-hosted only, with no managed cloud.
No first-class entity graph. If your questions are graph questions, Graphiti is the better tool.
One Postgres database. Multiple API replicas are verified, cross-region clustering is not available.
Tenant isolation is enforced in the application, without Postgres row-level security.
Bundles are denser than a plain fact store, so each answer costs more tokens. Best for teams whose memory has to stay in their own infrastructure and be explainable to an auditor or a customer.

Four questions that settle most of these evaluations

Is the feature you are switching for in the free build today, under the same license? Edition pages get revised, and features move across the line in both directions. Check the date on whatever you are reading.
Can you prove what the agent saw? If an auditor or a customer might ask, you need links back to source events and a per-call record, and you need them on the retrieval path.
How many systems do you want to patch? A graph database, a vector database and an LLM is three.
Can you clone and rerun the benchmark? One you can rerun beats a chart you cannot. Pick by requirement rather than star count. Fastest real test is to replay a week of your own conversations through two backends and diff the context bundles side by side. Whatever the leaderboards say, that diff is the thing you will actually be shipping.

Statewave's core runtime is on GitHub under Apache-2.0 if you want to read the compiler and the ranking code rather than take the table's word for it.

Why our support health score drops 25 points on a quiet week

Statewave — Mon, 28 Sep 2026 14:18:53 +0000

I scored one support account once a day for eleven days and added nothing to it. No new tickets, no messages, no resolutions. It went from 80 to 55 and crossed a band boundary on the way down. Two of the eight signals in the score read the clock, and that is the whole explanation.

We build Statewave, an open-source memory runtime for AI support agents, so treat the framing as ours and the numbers as checkable. The scoring rules are plain arithmetic in the Apache-2.0 core, which is what makes this post possible: every number below can be re-derived from the published constants.

What this score measures, and what it leaves to your CSM tool

Worth separating before anything else, because the two answer different questions.

Customer success platforms score the whole relationship. Gainsight's Staircase AI health score combines sentiment, engagement, open items and response time, with weights set by a statistical model and lifecycle modifiers layered on top.

HubSpot's customer success workspace takes a different route: an admin builds a points-based score from event and property groups, with a point cap per group and optional decay.

Ours reads only the support record: open and resolved sessions, urgency in the conversation, idle tickets, response and resolution times. Narrower on purpose, because it matches the question the next agent has at escalation: how are this customer's tickets going right now? Predicting renewal is a different job and this number will not do it.

How the eight rules compute the number

Every customer starts at 100. Eight rules move the number, the result is clamped between 0 and 100, and a band is assigned: 70 and above is healthy, 40 to 69 is watch, under 40 is at_risk.

Signal	Points	Cap	Fires when
Unresolved issues	-15 per open session	-45	A session's resolution status is open
Repeated issue	-20	Once	An open session shares at least 30% of its keywords with a resolved session
Escalations	-10 per episode	-20	A message contains an urgency marker such as outage, p0, sev1, or escalat
Idle open issue	-15	Once	An open session has had no activity for 7 days
Resolution breach	-10 per session	-20	A resolved session took more than 24 hours from the first customer message
Slow first response	-5	Once	Average first response across sessions is above 10 minutes
Recent resolution	+10	Once	A session was resolved in the last 7 days
High resolution rate	+10	Once	At least 80% of two or more sessions are resolved

No model call, no stored score, nothing cached in the scoring path. The same history at the same moment always returns the same number and the same factor list.

The factor list matters more than the number

Take a constructed mid-market account with three tickets. An SSO login loop fixed in two hours, three weeks ago. A duplicate-invoice export problem that took 36 hours to close last week. A warehouse sync to Snowflake failing since a schema change, untouched for seven days.

{
  "subject_id": "acct_ridgeline",
  "score": 65,
  "state": "watch",
  "factors": [
    { "signal": "unresolved_issues", "impact": -15, "detail": "1 open session(s)" },
    { "signal": "idle_open_issue", "impact": -15, "detail": "Session t-102 idle for 7 days" },
    { "signal": "recent_resolution", "impact": 10, "detail": "1 session(s) resolved in last 7 days" },
    { "signal": "sla_resolution_breaches", "impact": -10, "detail": "1 session(s) exceeded 24h resolution SLA" },
    { "signal": "slow_first_response", "impact": -5, "detail": "Avg first response 10.7 min (threshold: 10 min)" }
  ]
}

A receiving agent does not have to trust 65. They can see that 30 of the 45 penalty points come from one stale ticket, and go straight to t-102.

Fixed rules beat learned weights for a number that lands in an escalation brief, for one reason. Nobody can argue with a learned weight at 2am. A -15 labeled Session t-102 idle for 7 days gets checked in ten seconds.

Why it drifts when nothing happens

Two signals read elapsed time. An idle penalty fires once an open ticket passes seven days without activity, and the recent-resolution bonus expires seven days after a ticket closes. Neither needs a new event to change the score.

Scored daily across eleven days with no new episodes and no new resolutions, that same account walks down on its own:

Day 0: 80, healthy
Day 3: the Snowflake ticket crosses seven idle days, 65
Day 7: last week's invoice fix ages out of the bonus window, 55 Urgency markers behave the opposite way. Nothing ages them out, because the escalation check counts matching episodes regardless of when they were written.

So an "outage" message from a ticket that closed months ago keeps costing points forever. Only the 20-point cap bounds how much.

Alerts fire only when something asks for the score

The subject.health_degraded and subject.health_improved webhooks compare the current band against the last band cached. That comparison runs only when the score is computed, which happens on GET /v1/subjects/{subject_id}/health and on POST /v1/handoff.

In the walkthrough above, the drop to watch on day 3 sends nothing at all until one of those calls runs. If you want band-change alerts on the day they happen, run a scheduled job that requests health for every subject with an open session.

One more detail worth knowing: a subject scored for the first time is compared against a default of healthy. A new subject whose first score lands in watch therefore fires health_degraded immediately.

What can actually reach at_risk

I enumerated every combination of signal values the rules allow, respecting dependencies such as a repeated issue requiring at least one open session, and scored each one against the published constants. Doing so produced 936 feasible combinations.

No single signal can do it. Largest penalty any one signal applies is 45, from three or more open sessions, which leaves a score of 55. Still watch. Every at_risk customer has at least two separate things going wrong.

Zero open tickets means a floor of 55. With no open sessions the unresolved, repeated-issue and idle signals cannot fire at all. Everything left adds up to 45 at most, and 66 of the 72 no-open-ticket combinations come out healthy.

The fastest route is three open tickets plus one full-strength signal. Three open sessions (-45) plus a repeated issue (-20), two urgency episodes (-20), or two resolution breaches (-20) lands on exactly 35. With only one open ticket, reaching at_risk takes at least three other signals firing together.

Read an at_risk alert as "this customer's queue needs a person today." Risks that live outside the queue, like a champion leaving or a renewal slipping, have to reach your team some other way.

Four ingest mistakes that move the score with no error

Each of these is a mismatch between how your ingest path records support data and the fields the rules actually read. None of them raise an error. I reproduced all four against the scoring rules before writing them down.

What you see	Why it happens	What to do
An outage ticket scores like a routine one	The escalation and repeated-issue checks read `payload.messages[].content`. Text sent as `payload.text` is skipped. An open ticket reading "Full outage, P0" scored 85 as text and 75 as messages.	Record support turns in the messages shape
A 48-hour resolution costs no points	Timing checks recognize `user`, `chat` and `support-chat` as customer sources, and `assistant`, `agent`, `system`, `tool` as responders. The same history scored 100 with `customer`/`staff` and 95 with `user`/`agent`.	Normalize source names at ingest
Billing questions count as escalations	Urgency markers are substring matches, so "download" contains "down"	Never alert on the escalations factor alone. The 20-point cap limits the damage
Scores run high right after a bulk import	Idle and timing checks read `created_at`, which is ingest time. Backfilled tickets look answered in seconds and resolved today	Backfill before go-live, or hold health alerts for seven days after an import

One failure we see more often than any of those is not in the table at all: tickets that never get closed. Open-session penalties stack toward 45 and the resolution bonuses never fire, so long-standing customers drift into watch for no reason other than bookkeeping.

What the handoff pack drops first

A score is one line in a larger brief. POST /v1/handoff assembles nine sections from stored memory, with no model call, then trims to a token budget: 4,000 by default, up to 16,000.

Trimming cuts from the end. Customer and health come first so they survive, and recent context from the customer's other sessions is the first thing lost. If your briefs are getting cut, raise max_tokens before you change anything else.

Three quirks worth knowing before you wire this into an escalation path:

The health line keeps the first three factors rather than the biggest three. Factors are added in the fixed order the rules run, so for the account above that means the open session, the idle ticket and the recent resolution. Its resolution breach and slow first response reach the next agent through the SLA section instead.
Active Issue is the first message in the session, cut to 200 characters. If the session opens with "hi", so does the brief. Record the problem statement, or a ticket-created event carrying the subject line, as the first episode.
What Has Been Tried keeps five entries, oldest first. On a long-running ticket the most recent attempts are the ones left out, so a specialist picking one up should pull the full session timeline for anything past step five. Because nothing is generated, the brief cannot invent a detail that was never recorded. Which cuts both ways. A model-written summary reads more smoothly, and it can also tell you something that never happened.

If you are building your own

Five things that transfer, whatever you build this on:

Make every point traceable to a reason string. A score that goes into an escalation brief has to survive a skeptical human during a live incident.
Decide deliberately which signals age. Two of ours do, and both surprised us once we watched them over a week: bonuses that expire, and urgency markers that never expire at all.
Compute on demand and schedule the computation. If your alerts compare against a cached band, they fire when something asks, not when the state changes.
Your ingest shape is what the score actually reads. Field names and payload shapes change the number silently, whatever you meant them to record. Normalize at ingest, and write a resolution when a ticket closes.
Cap anything matched by substring. "download" contains "down", and a cap is what stops that from becoming an alert. Start with one account that has an open ticket. Call the health endpoint and check each factor against the ticket history. It takes about ten minutes and it tells you whether your ingest path records what the rules actually read.

Scoring rules, handoff assembly and the eval suite all live in the Apache-2.0 core runtime.

Read the constants there rather than taking our word for any of this.

Your dedup marker expires. The fact it created does not.

Statewave — Mon, 14 Sep 2026 12:04:13 +0000

Here is a bug that raises no error anywhere and shows up as a memory store slowly filling with the same fact twice.

You process an event, write a dedup marker, and set a 24-hour TTL on it so the marker table does not grow forever. Every guide tells you to do this, and for delivery-level idempotency it is correct advice. Then a backfill re-reads a ticket from last year. The marker expired months ago, so the ingest layer has no memory of it. But the fact derived from that event is still in the store, because derived facts do not expire on a schedule.

Now you have it twice. Nothing failed.

I went through the papers, talks and practitioner write-ups we had collected on this, and the word "idempotent" carried four incompatible meanings across them. Every source recommending a dedup marker also recommended a TTL on it. None discussed the interaction between an expiring marker and a non-expiring derived fact.

Four definitions sharing one word

Request-level. Repeating the same request leaves state unchanged after the first. The HTTP version is familiar, and RFC 9110 defines it in section 9.2.2: GET and DELETE are naturally idempotent, POST is not, and PATCH depends entirely on what it does. A PATCH setting a name to "DJ" is idempotent. A PATCH incrementing a counter is not. Same verb, opposite guarantee.

Delivery-level. The same event arriving twice gets acted on once. Most event-driven systems mean this, and enforce it with a marker.

Merge-level. The merge function is itself idempotent, plus associative and commutative, so replicas converge regardless of arrival order or repetition. This is the CRDT property.

Derivation-level. Re-running a derivation over the same inputs produces no new derived records. This is the one that matters for agent memory, and the one almost nobody names.

Satisfying any of those tells you nothing about the other three. A system can be fully delivery-idempotent and still accumulate duplicate facts, by exactly the mechanism above.

Why memory pipelines re-read on purpose

Retries are the obvious source. Even a broker promising exactly-once delivery cannot stop an upstream service publishing the same logical event twice under two different event IDs, which is why ID checks usually get paired with a business-key check on something like an order number.

What is specific to memory systems is that re-syncs are not failures. A connector pulling GitHub issues, Slack threads or support tickets runs on a schedule and re-reads overlapping windows every time, by design. A backfill re-reads everything. Neither is an error condition, so treating duplicate suppression as error handling puts the check in the wrong place.

Derive the key, never expire it

Stop generating keys and start deriving them from the event's logical identity. A derived key costs nothing to keep forever, because it is a property of the record rather than a row in a growing side table.

github:acme:api-server:issue:4471:opened

Source, org, repo, record type, issue number, event kind. Re-sync that issue a thousand times and you get one episode. No UUID, no timestamp, no TTL.

One file over in the same connector suite, the IDE companion uses the opposite rule: idempotency is content-addressable, so re-running an unchanged workspace scan maps to the same key and a changed workspace yields a new memory.

Two opposite policies in one codebase, and both are right. A GitHub issue has a stable identity independent of its text, so keying on identity is correct and an edited title should not create a second episode. A workspace scan has no identity apart from its contents, so keying on a content hash is correct and a changed workspace should produce a new one.

Your key encodes a definition of "the same event," and that definition is a per-source decision. Wrong in one direction floods the store. Wrong in the other silently drops real updates.

Compilation has to set, not append

Ingest dedup only covers ingest. The compile step needs its own guarantee, and it comes from one design choice: a compile pass that derives current state from the full episode log behaves like a set. A pass that appends whatever it found this run behaves like an increment, and increments are never idempotent.

That single property is what makes a compile endpoint safe to call from a retry loop, a cron job and a webhook handler at the same time. It is also what lets you batch compilation off the request path instead of running it inline after every turn.

Test for it in one line:

def test_recompile_is_a_noop(client, subject_id):
    first = client.post("/v1/memories/compile", json={"subject_id": subject_id})
    assert first.json()["memories_created"] > 0

    second = client.post("/v1/memories/compile", json={"subject_id": subject_id})
    assert second.json()["memories_created"] == 0

That whole test is the second number. If it is not zero, you have an append where you need a derivation, and no amount of ingest deduplication will save you.

Duplicates and conflicts are different problems

A duplicate is two records saying the same thing, and the fix is to keep one. A conflict is two records saying different things, both legitimately written, and there is no version of "keep one" that is obviously right.

Idempotency does nothing for the second case. Martin Kleppmann's taxonomy of conflict handling is still the cleanest: let a human resolve it, pick a winner automatically, or merge automatically. On the middle option he is precise about the cost, noting that some systems choose one version as the winner and throw away the others.

Throwing away the loser is the default in most agent memory stacks, and it is where the damage lands. You do not just lose the old value. You lose the evidence that a disagreement existed at all.

Recency-wins is near-universal as the automatic rule, and it is fine for state that genuinely changes, like which database a team runs. It is wrong for a stable attribute that a bad extraction re-asserts incorrectly. And it is wrong for facts that only look contradictory: "I am in Berlin this week" does not contradict "this user lives in Lisbon," and a system that supersedes the second with the first has made the memory worse.

Supersede, because the loser is evidence

Mark the older fact superseded, filter it out at read time, keep it in the record with provenance links to both sides. Three states cover it: active, superseded, tombstoned.

A worked example I can point at: three agents read three source documents concurrently and write to one shared subject. One commits Stripe's pre-reversal processing rate, another commits the corrected rate. Where the two memories carry a registered single-valued claim key, the compiler compares claims directly. Otherwise it falls back to Jaccard word overlap between the compiled memories, and at 0.6 or above it marks the older one superseded and records the decision with links to both source episodes.

Downstream, the synthesis agent's bundle contains only the winner. The audit trail contains both, plus the similarity score that triggered the call, 0.72 in the shipped run.

Treat 0.6 as a dial rather than a constant. Set it lower and unrelated facts collide, producing false-positive supersession that deletes true information from the read path. Set it higher and genuine contradictions both survive into the bundle, so you pay tokens to hand the model two incompatible answers.

Where this still fails

Word overlap is a fallback, not the mechanism. Jaccard catches "Stripe charges 3.5% + 35c" against "Stripe charges 2.9% + 30c." It will occasionally fire on unrelated facts sharing common words, and it misses contradictions expressed in entirely different vocabulary.

Idempotent is not deterministic. Run an LLM compiler and the extraction step can produce different facts from the same episodes on different runs. Idempotent compilation means a second pass over already-processed episodes adds nothing. It does not mean the first pass is reproducible. A regex-based heuristic compiler is.

Some conflicts should not be resolved. Two high-confidence claims that contradict each other may mean the boundary conditions differ. If being wrong is expensive in your domain, flag them and abstain instead of auto-resolving.

None of this fixes bad extraction. Deduplicating, superseding and auditing low-quality facts gives you a clean, well-audited store of low-quality facts.

The ten-minute check

Run your compile step twice in a row and look at the second number. If it created anything, that is the bug to fix before any of the rest.

If you would rather not build the key derivation, compile markers and supersession logic, the runtime behind the examples here is Apache-2.0 on GitHub and runs on your own Postgres. The full version of this post covers the per-kind conflict policy table and the replay boundary I skipped.

Quadrupling my agent's context budget bought 3x the facts, not 4x

Statewave — Mon, 14 Sep 2026 11:57:56 +0000

I ran one subject through a context assembler at three different token budgets and wrote down what came back. 200 tokens returned 2 memories. 500 returned 4. 800 returned 6.

That is a 4x spend for 3x the facts. It is the most useful number I have for sizing an agent's memory budget, and I almost never see it published.

Budget requested	Tokens returned	Utilization	Memories returned	Marginal cost per new memory
200	178	89.0%	2	89 tokens
500	443	88.6%	4	133 tokens
800	761	95.1%	6	159 tokens

Method, so you can repeat it: these are the published outputs of the budget command in the statewave-personal-assistant reference app, which calls the context API three times at three budgets against the same subject. I read them on 3 August 2026 and derived the marginal column myself.

The cheap facts get spent first

Marginal cost per fact rose 79% across that range, from 89 tokens to 159.

The assembler is not distributing effort evenly. It sorts by score and fills from the top, so the first two items are the densest, highest-priority things it holds. By the fifth and sixth it has worked down into longer, lower-scoring material.

So if you are choosing between 400 and 800 tokens, you are not choosing between four and eight facts. You are deciding whether to pay roughly double for two more items that already scored worse than everything in the bundle.

Utilization is the other column worth reading. It landed at 89.0%, 88.6% and 95.1%, and it never crossed 100%, because items are admitted whole. A memory that would overshoot the ceiling by one token gets dropped rather than truncated mid-sentence. Headroom across those runs was 11.0%, 11.4% and 4.9%. Plan for 5 to 11% of slack instead of assuming you get the number you asked for.

The stop rule is three lines, and that is the point

selected, used = [], 0
for memory in sorted(candidates, key=score, reverse=True):
    if used + memory.token_count > budget:
        break
    selected.append(memory)
    used += memory.token_count

A greedy knapsack fill. RCR-Router, a multi-agent routing paper, publishes essentially this as its Algorithm 1: sort by importance, accumulate, break on overflow. Nothing in it is stochastic, which is the property everything below depends on.

Compare it against the two patterns it replaces. Full history replay re-sends everything each turn, so cost grows with session lifetime and a throwaway comment carries the same weight as a production incident. Top-K vector retrieval returns the K nearest chunks, but K is a count and not a token budget, so your actual prompt size drifts with chunk length.

And no, a bigger window does not make this go away. Liu et al. tested position directly in Lost in the Middle and found accuracy follows a U-shaped curve against where the relevant passage sits: best at the start and end, worst in the middle, and that held even for models built for long context. Padding a 128K window with 100K tokens of history hands the model a large middle.

Scoring is where your opinions live

The fill is trivial. Ranking is where the design decisions sit. Four signals carry most of the ordering in the implementation those numbers came from:

Signal	Range	What it encodes
Kind priority	3 to 10	`profile_fact` 10, `procedure` 8, `episode_summary` 5, `raw_episode` 3
Recency	0 to 5	Linear, the newest memory takes the maximum
Task relevance	0 to 8	Word overlap contributes up to 5, cosine similarity up to 8
Temporal validity	-4 to +3	Currently valid adds 3, expired subtracts 4

Read that as a set of opinions rather than a spec. A stable profile fact outranks a raw conversation turn by 7 points on kind alone, before any other signal applies, which is why identity survives budget pressure and chatter does not. An expired fact carries a 7-point swing against it. Cosine similarity is in there, but as one input among four rather than the whole ranking.

What makes small budgets viable at all is compilation: a pass over raw episodes producing typed facts with confidence scores and provenance back to the source events. Two hundred conversation turns become one profile_fact. Rank raw turns instead and you are sorting a bad unit, low density and high token count with no confidence signal attached.

Determinism matters more than the compression

A 73% token reduction is the headline here, from roughly 2,800 tokens of raw history down to 761. I care more that it is the same 761 tokens every time.

Researchers at Penn State measured the alternative. Their work on parallel context compaction reports that as context grows, both the volume a model produces and the information it retains vary run to run. Prompt instructions asking for a specific summary length get largely ignored.

Which means: if your compaction step is an LLM call, your retrieval layer is non-deterministic, and every eval you run afterwards measures two things at once.

Deterministic assembly means same subject, same task string, same budget, same point in time, same bytes. When an answer changes, you know the change came from the model or the prompt, because the context did not move.

There is a real cost attached. Compile-then-use bundles are denser per answer than a plain fact-store lookup. If your queries are mostly single-hop and cost-sensitive, a lighter store may be the better call.

Six steps for setting your own number

Instrument before you tune. Log the returned token estimate and memory count on every context call. You want the utilization ratio. Running consistently below 85% means the budget is not your constraint and raising it will change nothing.
Start at 800. Aim for 5 to 8 compiled facts, which for typical fact and procedure sizes lands between 600 and 1,200 tokens.
Add the fixed costs before deciding it is too small. System prompt and tool schemas run 2,000 to 4,000 tokens on their own and get billed every call. Memory is usually the smallest line item in a well-built agent.
Watch the marginal curve, not the total. Run your own version of the three-budget test above and find where the next 200 tokens stop changing answers.
Set per-role budgets for multi-agent runs. A base budget plus a role offset. A planner needs structured plans; an executor needs less.
Keep compaction off the hot path. Compile on a schedule, every N episodes or nightly, using an async mode that hands you a job ID to poll. Raise the budget only when a named eval fails at the current one.

Two ways this still goes wrong

Bad extraction upstream. Ranking garbage precisely and fitting it exactly into 800 tokens gives you 800 tokens of well-organized garbage. The compiler sits upstream of everything here.

Prefix cache invalidation downstream. TokenPilot's authors found that mutating the prompt sequence to save tokens invalidates the KV prefix cache, and the misses can cost more than the tokens saved. Assemble a stable prefix and vary the tail.

One related trap: this is not token-level compression. The AGORA authors tested extractive token-level compressors across 17 agent configurations and reported that all 17 collapsed despite achieving real compression, because the compression broke action grammar. Dropping tokens inside a well-formed fact is a different operation from dropping a whole low-ranking fact.

Where to start

Log the token estimate and memory count on the context calls you already make. Then run one subject at three budgets and find where the answers stop changing. If your curve flattens where mine did, you have your number in an afternoon.

If you would rather not build the compilation and ranking layer, the runtime those numbers came from is Apache-2.0 and on GitHub. It boots against your own Postgres with one command. The longer version of this post carries the full signal list and the receipt model I skipped.

AI agent memory vs RAG — what's the difference?

Statewave — Fri, 11 Sep 2026 15:28:28 +0000

Most teams building on LLMs end up with two patterns in the same codebase: RAG for looking things up in a corpus, and some hand-rolled memory for remembering what the agent has done or what the user has said. The two are often confused, and the confusion costs real engineering time when one is used in place of the other.

RAG retrieves content the agent doesn't already know. Memory retrieves context the agent has already participated in.

They share a vector store but they answer different questions, store different shapes of data, and have different correctness requirements.

The shared substrate

Both patterns sit on top of an embedding store — usually pgvector or a dedicated vector database — and both use approximate-nearest-neighbour search at retrieval time. That's where the overlap ends.

RAG stores chunks of source documents (markdown pages, PDFs, support articles). Retrieval returns the most semantically similar chunks to the user's question, which are spliced into the prompt as grounding.
Memory stores typed records of what happened: episodes (raw conversation turns, tool calls, decisions) and compiled memories (typed facts derived from episodes, with provenance back to the source). Retrieval returns the most relevant prior context for this subject, ranked by recency, kind, validity, and similarity.

If you only need to ground answers in static documentation, you need RAG. If you need the agent to remember the user across sessions, you need memory.

Where RAG breaks down

RAG was designed to answer "what does our documentation say about X?" — not "what did this user tell us last month?" When teams stretch RAG to cover memory, three failure modes show up:

Embedding-nearest is not decision-relevant. A user message "I'm allergic to peanuts" and a later question "What should I order for lunch?" don't have close embeddings. Cosine similarity will surface every restaurant chunk before the allergy note. Memory ranking needs more than similarity — it needs kind priority, temporal validity, and explicit provenance.
There's no compaction. RAG indexes the corpus as-is. Memory has to summarize — turning 200 conversation turns into "user is a senior engineer at a fintech, prefers terse responses" — because the prompt budget is finite. RAG doesn't do that.
No invalidation model. If the user's job changes, the old "works at a fintech" record needs to be marked superseded, not retrieved alongside the new one. RAG's append-only chunk store has no concept of validity windows or supersession.

You can paper over each of these in your application code. Teams that do end up with a memory runtime in everything but name.

Where memory goes beyond retrieval

A memory runtime adds three things on top of the vector store:

Compilation — a pass over raw episodes that produces typed memories — profile facts, preferences, procedures, episode summaries — with confidence scores and validity windows. This is what shrinks 200 turns into one fact.
Deterministic ranking — scoring that mixes similarity with kind priority (a procedure beats a casual mention), recency, temporal validity, and an explicit token budget. Same query → same bundle. No silent re-ordering.
Provenance — every compiled memory carries the IDs of the episodes it was derived from. When an agent answers from memory, the answer is auditable back to the raw event that produced it.

None of those are properties of "RAG" in the literature sense. They're what makes memory infrastructure rather than retrieval over chat logs.

When to reach for which

	RAG	Memory
Question shape	"What does our content say about X?"	"What does this user / agent / project need to know right now?"
Data shape	Document chunks	Episodes → compiled memories with provenance
Ranking signal	Cosine similarity	Similarity + kind priority + recency + validity + token budget
Mutability	Append-only chunks; reindex on doc update	Episodes append-only; memories supersede; compaction is idempotent
Output	Top-K chunks	Token-bounded bundle ready to drop into a prompt

Most production agents need both. The grounding corpus (docs, knowledge base) lives in RAG. The user / account / project context lives in memory.

Trying to make either pattern do the other's job is the common architecture mistake — and it's the one we built Statewave to stop people from making.

What Statewave is in this picture

Statewave is the memory layer — episodes in, ranked context bundles out, with deterministic ranking and provenance. It uses pgvector under the hood (no separate vector DB to operate) but it's not a RAG framework: there's no document loader, no chunker, no retriever interface for grounding-over-corpora. If you want RAG, plug Statewave alongside your existing RAG stack — Statewave handles the who you're talking to layer, your RAG framework handles the what does the knowledge base say layer.

The architecture page on the docs site goes deeper on the ranking signals and the compile-vs-retrieve split. The getting-started guide is a five-minute Docker Compose path if you want to try it side-by-side with your current RAG setup.

FAQ

1. What's the difference between RAG and AI agent memory?

RAG retrieves content the agent doesn't already know — document chunks ranked by cosine similarity. Memory retrieves context the agent has already participated in — episodes and compiled facts ranked by recency, kind, validity, and similarity.

2. Can I use RAG in place of a memory layer for agent memory?

You can stretch it, but three failure modes show up: embedding-nearest isn't decision-relevant (an allergy note won't be the closest embedding to a lunch question), there's no compaction of history into durable facts, and there's no invalidation model for facts that get superseded.

3. Do I need both RAG and a memory runtime?

Most production agents do. The grounding corpus — docs, knowledge base — lives in RAG. The user, account, or project context lives in memory. Trying to make either pattern do the other's job is the common architecture mistake.

4. What does a memory runtime add that a vector store alone doesn't?

Three things: compilation (turning raw episodes into typed facts with confidence and validity), deterministic ranking (the same query always returns the same bundle), and provenance (every compiled memory carries the IDs of the episodes it came from).

5. Is Statewave a RAG framework?

No. It uses pgvector under the hood but ships no document loader, chunker, or retriever for grounding over a corpus. It's the who-you're-talking-to layer, meant to run alongside your existing RAG stack rather than replace it.

6. How do I decide which one to reach for?

Look at the shape of the question. "What does our content say about X?" is RAG. "What does this user, agent, or project need to know right now?" is memory.

Originally published on the Statewave blog. Statewave is an open-source, self-hosted memory runtime for AI agents — GitHub.

8 Open Source Tools for Building AI Agents with Memory

Statewave — Thu, 03 Sep 2026 14:09:06 +0000

An agent that remembers needs four things: somewhere to put raw events, something that turns them into facts, a way to retrieve those facts under a token budget, and a framework to run the loop. No single tool does all four well, which is why this list is eight tools and not one.

We build Statewave, an open-source memory runtime, so treat the entry about us accordingly. Everything below is Apache-2.0, MIT, or the PostgreSQL License, verified from the LICENSE file rather than the badge, checked on 1 September 2026. MCP is mid-transition from MIT to Apache-2.0.

Grouping below is by what each tool owns, because the most common mistake in this category is picking two tools that own the same layer and none that own the missing one.

The memory layer

1. Statewave

A memory runtime that sits behind your agents over HTTP. You send raw events as episodes; it compiles them into typed memories with confidence scores and validity windows, and you request a ranked, token-bounded bundle when you need context.

from statewave import StatewaveClient

with StatewaveClient("http://localhost:8100") as sw: sw.create_episode(subject_id="user-42", source="chat", type="message", payload={"text": "Alice asked about pricing tiers"}) sw.compile_memories("user-42") print(sw.get_context("user-42", task="answer pricing", max_tokens=1000).assembled_context)

What it owns: storage, consolidation, ranked retrieval, conflict resolution, provenance. What it deliberately does not own: your agent loop. Storage is Postgres with pgvector and no separate vector service. npx @statewavedev/statewave boots the API, admin console, and Postgres locally. The server defaults to demo mode with stub hash-based embeddings and the heuristic compiler, which means no real semantic search but a working loop.

Determinism is the property we care most about. The same subject, task, and token budget return the same bytes, which is what makes retrieval regression-testable.

Where it costs you: cross-subject retrieval is two calls, and the default compiler is heuristic regex. Switch to STATEWAVE_COMPILER_TYPE=llm for better extraction from messy conversation, or keep the heuristic compiler deliberately if no customer text may leave your network.

2. Mem0

Mem0 is the shortest path from nothing to an assistant that remembers a user. Its API is four calls wide: add, search, update, delete. Apache-2.0 for the library, with a managed platform sold separately.

Pick it when time to first working result matters more than being able to explain a specific retrieval later. Composition of its vector store, graph layer, and reranker is not broken down in public docs, so auditability means reading source.

3. Graphiti

Graphiti is a temporal knowledge graph that tracks when a fact became valid and when it stopped being true. That is a real answer to stale memory, which most fact stores handle by overwriting and hoping.

A note that saves evaluation time: many lists point to getzep/zep for this project. That repo’s README describes itself as examples for the managed Zep Cloud rather than the product, checked 1 September 2026. Graphiti is the self-hostable piece.

4. Cognee

Cognee builds a self-hosted knowledge graph with ontology grounding, combining embeddings with graph reasoning. Apache-2.0.

Reach for it when the relationships between entities carry the meaning, not just the facts about each one. It is more machinery than a preference store needs.

The orchestration layer

5. LangGraph

LangGraph models agents as state machines with explicit nodes and edges, which makes multi-step flows debuggable in a way that a while-loop over tool calls is not. MIT.

Its checkpointer handles per-thread state well. Worth being precise about the boundary: thread-level persistence is not the same as cross-session, cross-agent memory, and conflating them is how teams end up with an agent that remembers a conversation but not a customer.

6. Letta

Letta carries the MemGPT lineage and is a stateful agent runtime rather than a memory layer. It owns the reasoning loop, tool calls, and context management. Apache-2.0.

Check what you are adopting before you commit to it. letta-ai/letta now describes itself as a landing page for the project, with the retired Letta V1 server preserved on an archive branch and marked unsupported and not for production use. The current path is the hosted platform and the Letta Agent SDK, so Letta is no longer the self-hostable “one decision instead of four” it used to be.

The protocol and storage layers

7. Model Context Protocol

MCP is the piece people skip, then rebuild badly. It is an open protocol for exposing tools and data to LLM clients, built on JSON-RPC.

Why it belongs on a memory list: if four agents in three frameworks need the same memory, a protocol endpoint is what stops you writing three adapters. We expose Statewave over MCP for exactly this, so a Claude custom connector and a Python agent hit one memory service without either knowing about the other.

8. pgvector

pgvector adds vector types and distance operators to Postgres. Not glamorous, and it removes an entire moving part from your architecture.

One detail worth knowing: use an HNSW index rather than IVFFlat for anything that grows. IVFFlat recall depends on lists and probes matching your row count, so a corpus that outgrows its tuning quietly returns worse neighbors. We migrated for that reason and wrote up the details in the Postgres post.

How to assemble these

Stacks that work: pair one tool per layer:

● Fast prototype: LangGraph plus Mem0. Two decisions, working today.

● Self-hosted with audit requirements: your framework plus Statewave on Postgres and pgvector, exposed over MCP.

● Relationship-heavy domains: Graphiti or Cognee for memory, LangGraph for orchestration.

A common anti-pattern is picking Letta and Mem0 together, or LangGraph checkpointers and expecting cross-session memory. Both are two tools fighting over one layer while a different layer stays empty.

If you want the working code rather than the list, we keep three runnable demos: multi-agent memory with conflicting sources and automatic supersession, multi-agent shared context where a planner and coder stop contradicting each other, and a personal assistant that boots in five minutes without an LLM key.

No neutral, third-party benchmark compares these on the same task with the same corpus. Ours covers a subset and we ran it, which is exactly why it is not the one to settle your decision. Run the eval on your own data before committing to any of them.

7 Postgres Tools Every AI Engineer Should Know

Statewave — Thu, 03 Sep 2026 13:59:42 +0000

Most AI stacks add a vector database on day one and a second datastore to keep in sync forever after. A short list of Postgres extensions removes that decision for a large class of workloads.

We build Statewave, an open-source memory runtime for AI agents that runs on Postgres and nothing else. No separate vector service. That constraint forced us to learn which extensions genuinely carry AI workloads and which are resume padding. Below are seven, ordered by how often they earn their install.

Our own dependency list is one extension long, which is the first useful signal in this post: vector is the only one we require. Two entries below are not extensions at all, full-text search ships in Postgres core, and PgBouncer is a connection pooler, but both earn their place on an AI workload, so they are here.

1. pgvector

pgvector is what makes the rest of the argument possible. It adds a vector column type plus distance operators for cosine, L2, and inner product.

CREATE EXTENSION IF NOT EXISTS vector; ALTER TABLE memories ALTER COLUMN embedding TYPE vector(1536);

Index choice is the part worth internalizing, because we shipped the wrong one first. Our initial migration built an IVFFlat index:

CREATE INDEX ON memories USING ivfflat (embedding vector_cosine_ops);

IVFFlat partitions vectors into lists and probes a subset at query time. It builds fast and uses little memory. Recall, though, depends on lists and probes being tuned against your actual row count, and a corpus that grows past what you tuned for silently returns worse neighbors. Nothing errors. Results just get quietly less relevant.

We moved to HNSW:

CREATE INDEX ix_memories_embedding ON memories USING hnsw (embedding vector_cosine_ops);

HNSW builds a navigable graph. Better recall at the same latency, stable as the corpus grows, and no list-count tuning. Cost is real: build time and memory. On a small corpus the migration finishes in under a second, but HNSW build is the slow step at scale, so our migration sets statement_timeout = '20min' to survive large tables.

Use IVFFlat when your corpus is static and you need a fast build. Use HNSW for anything that grows. If you inherited an IVFFlat index and nobody has retuned lists since the table doubled, that is worth checking today.

2. Built-in tsvector and GIN (no extension required)

Semantic search alone fails on exact tokens. A user asking for error code SW-4021 needs lexical matching, and embeddings will happily return five semantically adjacent errors instead.

Postgres ships full-text search in core. A generated column plus a GIN index gives you lexical retrieval with zero dependencies:

ALTER TABLE memories ADD COLUMN content_tsvector tsvector GENERATED ALWAYS AS (to_tsvector('english', content)) STORED; CREATE INDEX ix_memories_content_tsvector ON memories USING gin (content_tsvector);

GENERATED ALWAYS AS ... STORED means Postgres maintains the column on every write. No trigger to forget, no backfill job to schedule.

We run this alongside vector search and fuse the two, which is what "hybrid retrieval" means in practice. Including it here because half the teams that install a vector database do so to solve a problem that lexical search solves better.

3. pgcrypto

Small but load-bearing. pgcrypto supplies gen_random_uuid() for primary keys generated server-side, so you are not round-tripping to the application for an ID.

CREATE EXTENSION IF NOT EXISTS pgcrypto;

On Postgres 13 and newer, gen_random_uuid() is in core and you may not need the extension at all. Check your version before adding it. Its digest and encryption functions matter separately if you are storing anything sensitive in a memory layer, which for agent memory you usually are.

4. pg_trgm

pg_trgm does trigram matching for fuzzy string comparison. Entity resolution is the AI-specific use: deciding that "Acme Corp", "ACME Corporation", and "acme corp." are the same subject before you write three separate memory rows about them.

CREATE EXTENSION IF NOT EXISTS pg_trgm; CREATE INDEX ON subjects USING gin (name gin_trgm_ops); SELECT name, similarity(name, 'acme corp') AS score FROM subjects WHERE name % 'acme corp' ORDER BY score DESC;

Embeddings are the wrong tool here. Two spellings of the same company name are lexically close and semantically identical, so cosine similarity gives you no separation between the right match and every other company in your table.

5. pg_stat_statements

pg_stat_statements tells you why your agent feels slow.

CREATE EXTENSION IF NOT EXISTS pg_stat_statements; SELECT query, calls, mean_exec_time, total_exec_time FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 10;

AI workloads have a specific failure shape: one vector query looks fine at 40ms, then you discover the agent issues it eleven times per turn. Mean latency stays healthy while total time balloons. total_exec_time catches that; a p99 dashboard does not.

6. pg_cron

pg_cron covers the background work agent memory needs. Compiling raw events into typed facts, expiring memories past their validity window, and recomputing scores are all jobs that should not run on the request path.

CREATE EXTENSION IF NOT EXISTS pg_cron; SELECT cron.schedule('expire-memories', '0 * * * *', $$UPDATE memories SET status='expired' WHERE valid_until < now() AND status='active'$$);

We run compilation as durable jobs in the application layer rather than in pg_cron, because our jobs call an LLM and need retry semantics Postgres should not own. Honest rule: pg_cron is right for deterministic SQL maintenance and wrong for anything that makes a network call.

7. PgBouncer (a pooler, not an extension)

Included deliberately, because the thing that breaks first when you scale an AI service is not the vector index. It is connection count.

Each API replica holds a pool. Ten replicas at fifteen connections each is 150 logical connections crowding max_connections, and Postgres connection overhead is not free. Raising max_connections postpones the problem and makes it worse.

PgBouncer in transaction mode decouples logical client connections from physical backends: a pool of 30 to 60 backend connections comfortably serves 5 to 15 replicas. Transaction mode is the right setting when sessions are short. If you use prepared statements, PgBouncer 1.21 and later support them in transaction mode via max_prepared_statements; on older versions, avoid holding them across transactions.

One thing to know before you switch: pg_stat_activity then shows PgBouncer's identity rather than your replicas. Use SHOW POOLS and SHOW CLIENTS for the per-replica picture.

What we would actually install

For a new AI service on Postgres, in order:

vector with an HNSW index. Non-negotiable.
Built-in tsvector plus GIN. Free, and it fixes the exact-token failures embeddings cannot.
pg_stat_statements. Install before you need it, because the query pattern you need to diagnose is one you have to catch in the act.
pg_trgm once you have real user-entered entity names.
PgBouncer at the point where replica count times pool size approaches max_connections.

pgcrypto and pg_cron are situational. Check your Postgres version for the first and your job semantics for the second.

Broader point: a memory layer for AI agents can run on Postgres with one extension and no separate vector service. We wrote up the storage decisions in more detail, and the IVFFlat-to-HNSW migration is readable in the repo linked at the top if you would rather check it than take our word for it.

What did we miss? If you are running something in production that earned its place on an AI workload, name it below.