Welcome to Statewave Discussions

[smaramwbc]

👋 Welcome.

Statewave is a durable memory and state layer for AI agents. Memory lives outside the model — structured, inspectable, portable, self-hostable, vendor-neutral. The same memory layer works across model versions, providers, and frameworks.

This Discussions space exists so that the people building real agents — at startups, in infra teams, in research, on side projects — can compare notes, propose changes, and shape where Statewave goes next.

Who this space is for

• Developers and AI builders shipping agents, copilots, support systems, voice apps, research workflows
• Infrastructure teams evaluating where memory and state should live in the stack
• Startups building on top of Statewave or considering it
• Researchers working on long-term memory, temporal memory, agent state, evals

If you're building something that has to remember anything across sessions, you're welcome here.

Where to post what

You want to…	Go here
Ask a usage / "how do I…" question	Q&A
Suggest a feature, integration, or SDK improvement	Ideas & Feature Requests
Propose a design change worth real review	RFCs
Share what you've built	Show and Tell
Talk integrations (LangChain, LlamaIndex, CrewAI, AutoGen, OpenAI Agents SDK, MCP, …)	Integrations
Weigh in on what should ship next	Roadmap
Discuss long-term memory, temporal memory, retrieval, evals	Research
Get practical setup / deployment help	Support
Anything else	General
Report a reproducible bug	Open an issue
Report a security vulnerability	Email security@statewave.ai — never post publicly
Discuss commercial / private licensing terms	Email licensing@statewave.ai

The full community guide is in statewave-docs/community/discussions.md, with copy-paste prompts in discussion-templates.md.

Useful links

• README — what Statewave is and how to run it
• Getting started — clone, run, ingest your first episode
• Why Statewave — technical comparison vs history stuffing and plain RAG
• Architecture
• Roadmap
• CONTRIBUTING, SECURITY, LICENSING
• Live demo — statewave.ai (two identical agents answer the same question, one stateless, one backed by Statewave)

Licensing in one paragraph

Statewave Core is dual-licensed: AGPLv3 for open-source / community use, and a separate Statewave Commercial License for proprietary, SaaS, embedded, hosted, or enterprise use. The full breakdown is in LICENSING.md. General licensing questions — which license fits my use case? — are fine to discuss publicly. Specific commercial terms, contracts, and enterprise procurement go to licensing@statewave.ai.

Introduce yourself

Comment below and tell us:

• What you're building (or evaluating Statewave for)
• The memory or state problem you keep hitting
• Stack — agent framework, model provider, deployment style

We read every reply, and the patterns we see here directly shape what gets built next.

[musaabhasan]

For an external agent state layer, the feature I would evaluate first is not only recall quality, but state accountability.

A strong state layer should make it easy to answer:

• What did the agent know at the time of a decision?
• Which memory entries were current versus historical?
• Which entries came from user input, tool output, imported documents, or another agent?
• Which state changes were proposed by the model versus accepted by policy?
• Which state entries are allowed to influence tool use, spending, or external side effects?
• Can a reviewer reconstruct the decision context without exposing unnecessary sensitive content?

That suggests adding first-class support for provenance, validity intervals, sensitivity labels, promotion workflows, and state-diff review. Durable memory becomes much more valuable when it is not just persistent, but inspectable and governable across model versions and agent frameworks.

[smaramwbc]

Great framing — “state accountability” is exactly the right axis.

We agree that durable memory is not enough by itself. Recall that cannot be inspected, traced, replayed, or governed eventually becomes a liability, not a feature.

Mapping your points to where Statewave is today:

• What did the agent know at the time of a decision?
  Memories include temporal validity metadata, and context assembly supports as-of-date queries, so the system can reason about what was current at a given point in time instead of only showing the latest state.

• Which memory entries were current versus historical?
  This is a core part of the model. State changes are not meant to simply overwrite the past. Historical memory, superseded state, and memory lineage are important because agents need continuity, but reviewers also need to understand how state changed over time.

• Which entries came from user input, tool output, imported documents, or another agent?
  Tracked via source links. Each memory carries source_episode_ids back to the originating episodes, and episodes carry a provenance dict such as origin, connector, importer, etc. That gives the admin surface enough information to explain where state came from, not only what the current memory says.

• Which state changes were proposed by the model versus accepted by policy?
  This is only partial today. Statewave can compile memories from episodes, and conflict resolution can run automatically, but an explicit “proposed → reviewed / accepted / rejected” workflow is not yet a full first-class product surface. I agree this is important for higher-stakes deployments.

• Which state entries are allowed to influence tool use, spending, or external side effects?
  This is one of the biggest gaps relative to your list. We do not yet have a complete sensitivity-label / capability-policy layer where a memory can be read by one part of an agent but blocked from another, for example billing, payments, write tools, or external side effects.

• Can a reviewer reconstruct the decision context without exposing unnecessary sensitive content?
  The reconstruction primitives — provenance, time-aware state, and lineage — are already in. Memory evolution and source-episode links are exposed in the admin API. The missing piece is review-time redaction, which likely belongs on top of sensitivity labels.

So I think your summary is right: provenance, validity intervals, lineage, and state-diff review are the foundation. Promotion workflows, sensitivity labels, and policy bindings are the next layer that turns persistent memory into governable memory.

I’d be very interested in your view on the right abstraction here:

• capability tags on memories?
• trust tiers?
• namespace-level policy?
• Rego / OPA-style policy?
• per-tool memory access rules?
• human approval workflows for selected memory classes?

Happy to open separate issues for these two areas — memory promotion workflow and sensitivity / policy labels — if you’d like to help shape the design.

[musaabhasan]

Thanks for the detailed mapping. The next useful artifact may be a state-assembly receipt: not the full memory contents, but a compact record of which state entries influenced a given context window.

Fields I would want in that receipt:

• query/task id and as-of time
• memory entry ids and versions selected
• validity intervals and supersession status
• source/provenance hash for each promoted fact
• policy filters applied, such as sensitivity or tenant boundary
• conflict status where two facts share the same fact key
• output context hash delivered to the agent

The negative tests are important: stale fact selected for current query, sensitive tombstoned memory resurrected, conflicting entries merged without a conflict flag, and as-of-date query accidentally using latest-state recall. Those tests would make the accountability model easy to evaluate.

[smaramwbc]

This is exactly the artifact we should be building toward.

A “what did the agent see, and why was it that?” receipt is the missing piece between provenance metadata sitting in the database and accountability that is actually evaluable.

Mapping your fields against today:

Already derivable from the assembly path, but not yet surfaced as a single object:

• query / task id and as-of time
• memory entry ids and versions selected
• validity intervals and supersession status
• conflict status per fact key

Not yet shipped as receipt fields:

• Provenance hash per promoted fact.
  Provenance is tracked today, but content-addressing it is new. I would keep both a stable id and a content hash: the id is the lookup path, the hash is the tamper-evidence. Either one alone loses something.

• Policy filters applied.
  This depends on the sensitivity / policy layer that does not exist yet, and the receipt is actually a strong forcing function for getting that layer right. If the receipt must say which filters fired, the policy layer has to be explicit enough to fill that field.

• Output context hash.
  This should be straightforward and high-value. It is what makes the receipt independently verifiable even if the assembly code changes later.

Two small additions worth considering:

• Policy version, not just which filters applied.
  Otherwise the receipt becomes hard to verify once the policy itself changes.

• Receipt id.
  Receipts should be addressable and chainable: decision → receipt → context → memories → episodes. That makes audit walks tractable instead of relying on recursive joins.

On the negative tests: those are exactly the right shape — falsifiable, bounded, and each one isolates a specific failure mode.

One more worth adding:

• superseded memory still influenced ranking

That is distinct from “stale fact selected for current query.” A stale-fact bug means the retriever ignored valid_to / valid_from. A superseded-ranking bug means the retriever ignored supersession status. Different fields, different failure modes.

I’ll open an issue for the receipt schema and link it here.

One design question I would value your input on up front: should the receipt schema be a strict superset, where every field is always present and some are null, or a tagged union per assembly mode, where different assembly paths produce slightly different receipt shapes?

Both have real tradeoffs, and the choice affects how the negative tests should be written.

[smaramwbc]

@musaabhasan — update: both #49 (state-assembly receipts) and #50 (sensitivity labels + policy bundles) shipped in v0.8.0 today. Released across the workspace: server image statewavedev/statewave:0.8.0, GitHub release, Python SDK statewave 0.8.0 on PyPI, TypeScript SDK @statewavedev/sdk@0.8.0 on npm.

Receipt fields, mapped to your list

Your field	What shipped
query / task id and as-of time	query_id, task_id, as_of (top-level)
memory entry ids and versions selected	selected_entries[].memory_id + version
validity intervals and supersession status	selected_entries[].valid_from / valid_to / supersession_status (active | superseded | tombstoned)
source / provenance hash per promoted fact	selected_entries[].content_hash (per-fact) + output.context_hash (whole-bundle SHA-256)
policy filters applied	policy.filters_applied[] (per-memory denies) and policy.filters_skipped[] (per-rule non-fires)
conflict status per fact key	selected_entries[].fact_key + selected_entries[].conflict_status (none | merged | overridden | unresolved)
output context hash	output.context_hash — SHA-256 of the exact bytes delivered to the agent

Two of the extras from my earlier reply also landed:

• Receipt id + chaining. receipt_id is a ULID (sortable, addressable, tenant-scoped). parent_receipt_id links multi-step tasks so audit walks are tractable rather than recursive joins.
• Policy version. policy.policy_bundle_hash is recorded on every receipt — content-addressable so verification doesn't depend on the bundle still being the "active" one when the receipt is replayed later.

Design question — strict superset vs tagged union

We shipped the strict superset. Top-level shape is fixed; nested arrays default to empty (filters_applied: [], filters_skipped: [] when no policy bundle is active). One mode field ("retrieval" in v1) reserves the slot for the assembly-mode variants you alluded to — as_of_replay and eval_run modes are the next two to land, but they'll be additive nested fields, not different top-level shapes. The choice was driven by negative-test ergonomics: every assertion has a guaranteed path to evaluate against, even when a feature didn't fire.

Negative tests

All four of yours are pinned as acceptance tests on #49 / #50. Plus the additional one from the reply:

• stale-fact — retriever respects valid_from/valid_to
• tombstone resurrection — supersession_status: tombstoned cannot be selected
• conflict marker — two facts with the same fact_key get conflict_status: merged|unresolved, never silently combined
• as-of-date contamination — as_of query path is isolated from latest-state recall
• superseded-ranking — supersession_status: superseded cannot influence rank order even when valid intervals would otherwise permit it (different fix path from stale-fact)

Sensitivity & policy (#50)

Memories carry sensitivity_labels: TEXT[] (GIN-indexed). Policy bundles are YAML, evaluated first-match-wins, with six predicates (memory_has_any_label, memory_has_all_labels, caller_type, caller_type_in, caller_type_not_in, caller_id) and two actions (deny, redact). Per-tenant config controls policy_mode: log_only (default) vs enforce and require_caller_identity. log_only is deliberately the default so operators can see exactly what would be denied via receipts before flipping to enforce.

Full schemas: receipts.md, sensitivity-labels.md.

Still partial / next

• The proposed → reviewed → accepted/rejected memory promotion workflow you raised in the first comment is still not first-class — receipts make it auditable retroactively, but there's no explicit "pending → reviewed" lifecycle yet. Open question: should that live in the memory state machine, or as a separate workflow over labelled memories?
• as_of_replay receipt mode (replay an old assembly bit-for-bit from receipt + memory store) is on the v0.9 line.

Feedback welcome on any of this — especially if you can stress-test the receipts against a real audit scenario.

[smaramwbc]

Issue opened to track this: #49 — feat: state-assembly receipts for context-window accountability.

The body has the v1 schema sketch, the layered emission control surface (per-request → per-tenant → per-policy force-on → env kill-switch), the open design questions (including the strict-superset vs tagged-union shape question), and your negative tests as acceptance criteria. Happy to take input either there or here — whichever you prefer.