All notable changes to the Statewave workspace.
The first stable public developer release of the open-source memory runtime. The /v1/* API contract and the v0.9 governance surfaces (HMAC-signed receipts, receipt-driven replay, sensitivity labels with declarative policy, opt-in detector-suggested labels, per-region residency) are now stable for developer use under a self-hosted deployment model. Carried-forward limitations remain documented honestly in why-statewave.md; the full sign-off trail is release-notes/v1.0-launch.md and release-notes/v1.0-readiness-checklist.md.
Not "GA", not "production-ready", not "battle-tested", not "enterprise-ready" — first stable public developer release.
- Public version-discovery endpoint (statewave#178) — unauthenticated
GET /v1/version. - Webhook delivery stats + tenant scoping — optional tenant filter on event-status queries plus per-tenant delivery statistics; permanent 4xx deliveries dead-letter instead of retrying indefinitely.
- A lap of correctness fixes since v0.9.2: tenant-scoping on admin/receipts/conflicts/compile-jobs surfaces, constant-time API-key compare, backup memory-id conflict guard, embedding input-order preservation, snapshot
occurred_atpreservation, newest-first recent-context ranking, and per-(tenant, subject)health-cache isolation.
statewavePython SDK v1.0.0 — governance helperslist_suggested_labels()/promote_suggested_labels()(statewave#176) andsession_idoncreate_episode(statewave#174). Folds in the never-published 0.10.2 prep.@statewavedev/sdkTypeScript SDK v1.0.0 —sessionIdnow reaches the wire oncreateEpisode/createEpisodesBatch(statewave#174). Folds in the never-published 0.10.2 prep.
Both SDKs are semver-stable from 1.0.0 forward, with typed surfaces matching the /v1 REST contract.
The release-candidate lap before the 2026-06-16 v1.0 tag. Validation-led: an end-to-end smoke against the published image, one in-stream fix for the only material smoke finding, the approved SDK ergonomics patch (session_id on create_episode), a launch-doc-freeze audit, and the v1.0 readiness checklist that the maintainer signs off on for the tag.
Full close-out — every merged PR, every dropped item, every guardrail honoured — lives in release-notes/v0.9.4-launch-readiness.md. The v1.0 sign-off artifact is release-notes/v1.0-readiness-checklist.md.
Added — sensitivity_labels + suggested_labels on subject-scoped admin memory listing (statewave#177)
The only material finding from the v0.9.4 smoke: GET /admin/subjects/{id}/memories returned 10 fields per memory but omitted both label arrays, fragmenting the "open subject → view memories → see labels" admin flow. Two new fields on MemoryListItem, populated on every row. Purely additive — no migration, no breaking move, no behaviour change on any existing field. The policy evaluator reads only sensitivity_labels; surfacing the field on a read-only listing route cannot affect policy decisions. +2 integration tests proving the listing surfaces both arrays before and after promotion.
Added — session_id accepted on create_episode in both SDKs (statewave#174)
statewavePython SDK v0.10.2 (statewave-py#18):session_id: str | None = Nonekeyword-only argument on bothStatewaveClient.create_episodeandAsyncStatewaveClient.create_episode. Field omitted from the JSON body whenNone. +4 tests. Full suite: 77 passed (was 73).@statewavedev/sdkTypeScript SDK v0.10.2 (statewave-ts#19):sessionIdwas already inCreateEpisodeParamssince v0.10.0 but was being silently dropped before serialization on the wire — real bug for TypeScript users. Fix forwards it throughcreateEpisodeand per-item throughcreateEpisodesBatch. +3 tests. Full suite: 50 passed (was 47).
- statewave-docs#55 —
release-notes/v0.9.4-smoke.md: 11 of 11 scenarios PASS against the published:latest. Same shape as the v0.9.2 smoke. One in-stream finding (#177 above), one deferred (statewave#178 — publicGET /v1/versionendpoint, v0.10.x post-v1.0). - statewave-docs#56 — Reworded "Single-node only" framing across 5 surfaces (
product.md,why-statewave.md×2,comparisons/mem0.md, v0.9.3 close-out) to the precise truth: "Single-Postgres only — multi-replica API supported and verified since v0.8 (Fly multi-machine + Helm HPA); cross-region / multi-Postgres clustering not yet shipped." Also caught uparchitecture/repo-map.mdSDK cells post-v0.10.2 (Python0.10.1 → 0.10.2, TS0.10.1 → 0.10.2, test counts73 → 77and47 → 50). - statewave-web#106 — Re-anchored
Audit & governancesection's lead paragraph from "v0.8 ships the governance layer" to a v0.9-extended framing (HMAC-signed receipts, replay, detector-suggested labels opt-in viaSTATEWAVE_AUTO_LABELING_ENABLED, per-region residency pinning). One paragraph, +2 lines net, no new components.
- statewave-docs#57 —
release-notes/v1.0-readiness-checklist.md: the single artifact for v1.0 tag sign-off. Seven approved go/no-go questions, each backed by a source artefact. Explicit claim boundary ("first stable public developer release"; no GA / production-ready / production-hardened / battle-tested / enterprise-ready / hardened). Sign-off rubric at the foot.
- statewave#176 — Python SDK governance helpers (
list_suggested_labels,promote_suggested_labels, typedPolicyDecision). Deferred to v0.10.3 post-v1.0 fast-follow (target ~2026-07-15). Auto-labeling is opt-in; default v1.0 user does not hit this. - statewave#178 — Public
GET /v1/versionendpoint. Deferred to v0.10.x. Documented workaround (Docker tag / pip metadata).
Validation-led stabilization patch on top of v0.9.2. No new backend features, no SDK implementation, no admin identity changes. The goal was to verify that every documented onboarding path actually works against the published artifacts, and to catch up documentation drift before 2026-06-16. Full close-out — including dropped items and v1.0-carry risks — lives in release-notes/v0.9.3-launch-readiness.md.
Added — receipt_signing_key_id on TenantConfigPatch (statewave#173)
TenantConfigPatchnow exposesreceipt_signing_key_id(the same surface stored intenant_configs.config.receipt_signing_key_id) and rejects unknown fields viamodel_config = {"extra": "forbid"}. Closes the in-stream finding caught by the v0.9.2 smoke that left HMAC-signed-receipt enablement reachable only via raw SQL.- +6 integration tests including an end-to-end "PATCH then sign a receipt" path that uses no SQL — proves the surface is wired through to
services/receipts.py. regionwas rechecked and confirmed already-working: the PATCH surface existed with 4 passing integration tests, so no duplicate code was written.
Documentation — explicit prerequisites + correct framework pins (statewave-examples#15)
langchain-quickstart/README.mdnow pinslangchain>=0.3,<1andlangchain-openai<1. LangChain 1.x removedBaseMemory(and thelangchain.memorynamespace) which the adapter extends — unpinned, the README's install line resolves tolangchain==1.4.0and the example fails onimport.autogen-quickstart/README.mdnow pinspyautogen==0.2.*. Unpinnedpyautogenresolves to a 0.10.x package with a different (non-autogen.*) import surface.crewai-quickstart/README.mdkeepscrewaiunpinned (installs cleanly on 1.14.5).- All three framework quickstarts now explicitly say
docker compose up -dbrings up Postgres 16 + pgvector + the API together.
Documentation — connector skim (statewave-docs#53)
architecture/repo-map.mdconnector row no longer says "13 modular packages" (then listed 14); now lists 11 source connectors plus shared Core, CLI, Config, MCP-server, IDE-core, and Runner packages — matching the actual 18-package monorepo.- Connector test count
498 → 606(counted from source viafind packages -name '*.test.ts' | xargs grep -hcE '^\s*(it|test)\('). - Stale
independentversion cells in the same table refreshed: Server0.8.0 → 0.9.2, Python SDK0.9.0 → 0.10.1, TypeScript SDK0.9.0 → 0.10.1(these rows are deliberately hand-updated per the release checklist; v0.9.3 catches up two SDK waves of drift).
A single "advanced eval assertions" figure moved 55 → 56 across every mirror that quoted it. All counts recomputed from source; nothing moved up without evidence. Surfaces touched:
- statewave#175, statewave-examples#14, and
statewave-launch#23(private repo): one-line README / posts updates. - statewave-docs#51: per-repo test counts in
architecture/repo-map.md,dev/conventions.md, plus assertion-count mirrors inarchitecture/overview.md,roadmap.md,why-statewave.md. Also a factual fix to a historical CHANGELOG entry (v0.6.1 workflow-benchmark9/9→8/8to match the actually-published figure). - statewave-docs#50: "Returning user?"
docker compose pullcallout + stale-image troubleshooting row ingetting-started.md. - statewave-docs#52: MD028 lint fix on the two
getting-started.mdcallouts from #50 (merged into one blockquote with a>continuation).
- statewave#174 — Python SDK
create_episode(..., session_id=...)gap. Target v0.10.2. - statewave#176 — Python SDK governance helpers (
list_suggested_labels,promote_suggested_labels, typedPolicyDecisionon receipts). Blocked the optional governance-quickstart example. Target v0.10.2.
Small stabilization patch on top of the canonical v0.9 governance release (v0.9.1). No new backend features, no API changes, no schema migrations. This patch closes a small set of stabilization items uncovered during the post-v0.9.1 readiness audit; each item lands as its own focused PR.
Changed — server version metadata aligns with the published tag (statewave#171)
pyproject.tomlbumped from0.9.0to0.9.2sopip show statewavereports a version that matches the GitHub release. Previously, both thev0.9.0(stub, superseded) andv0.9.1(canonical) tags reported0.9.0from pip metadata. No code, behaviour, or API changes.
The remaining v0.9.2 items land as separate focused PRs against their respective repos. Final PR numbers will be filled in when each lands; the v0.9.2 GitHub release notes serve as the consolidated index.
statewave-pyv0.10.1 (closes #169) — addsverify_receipt(receipt_id)andreplay_receipt(receipt_id)to bothStatewaveClient(sync) andAsyncStatewaveClient(async), with typed Pydantic return models (ReceiptVerifyResult,ReceiptReplayResult) and a dedicatedStatewaveUnreplayableError(reason)for HTTP 422 refusal codes (missing_policy_snapshot/nested_replay/invalid_snapshot). README governance section refreshed from(v0.8)to(v0.8+). PyPIDevelopment Statusbumped from Alpha to Beta.statewave-tsv0.10.1 (closes #170) — addsverifyReceipt(receiptId)andreplayReceipt(receiptId)toStatewaveClient. TheReceiptinterface gains the v0.9 governance fields (policySnapshot,receiptSignatureAlgorithm, plusregionif missing) and a discriminatedStatewaveUnreplayableErrormirrors the Python error type. Version-aligned withstatewave-pyv0.10.1.- statewave-examples —
try-it.shreferencedpip install statewave-py(the GitHub repo name) instead of the published package namestatewave. Corrected. - statewave-web — three stale v0.9-era strings refreshed: ProductPage auto-labeling description (
"planned"→"shipped"),llms-full.txtGovernance version tag (v0.8→v0.8+), proof-figure counts where re-counted locally against current main. No broader proof-figure sweep in this patch.
Customers calling /v1/receipts/{id}/verify and /v1/receipts/{id}/replay from raw HTTP can now use the typed client surface; semantics and refusal codes are unchanged from the v0.9.1 server release.
The previous CHANGELOG entry was filed under "v0.9.0" but described work that actually shipped under tag v0.9.1 (v0.9.0 was a stub tag at pre-v0.9 code, now marked superseded). The heading below has been corrected to "v0.9.1" to match the canonical tag. No content changed; only the heading and the heading anchor are different.
Closes the Replay, Signing & Auto-Labeling milestone plus the cross-region residency surface, building on the v0.8 governance foundation. Each item shipped as its own focused PR; the breakdown lives in roadmap.md.
Added — scheduled retention-purge worker (statewave#156 · #162)
- Implements the worker for the surface v0.8 reserved (
tenant_configs.config.receipt_retention_days). The hourly_cleanup_loopwalks tenants with a positive integer retention and issues one tenant-scopedUPDATEper tenant transitioningstatus='active'receipts older thannow() - retention_daysintostatus='tombstoned'. - Soft delete: rows persist for forensic lookup; the partial index
ix_receipts_active_tenant_created ON (tenant_id, created_at) WHERE status='active'keeps the worker cheap on large tables. - Idempotent and tenant-isolated: re-running against the same DB state is a no-op; misconfiguring tenant A cannot tombstone tenant B's receipts.
- Migration 0020 adds
receipts.status(server default'active') andreceipts.tombstoned_at. Reversible.
Added — HMAC-signed receipts with tenant-scoped key ids (statewave#157 · #163)
- Algorithm
hmac-sha256-canonical-v1over the canonical v1 form of the receipt body. Algorithm + canonicalization version baked into a single string so future migrations (RFC 8785 JCS, asymmetric signing) land as new algorithm tags without a schema break. - Operator-provided keys via
STATEWAVE_RECEIPT_SIGNING_KEYS(JSON map ofkey_id -> base64-key, minimum 32 bytes each). Never persisted to the database; the field isField(repr=False)so a strayprint(settings)cannot leak it. - Per-tenant active key id via
tenant_configs.config.receipt_signing_key_id. Rotation: add a newkey_idalongside the old, update the tenant pointer; old receipts still verify until the operator removes the old key from config (then they returnvalid: null, reason: "key_unavailable", never a 500). GET /v1/receipts/{id}/verifyreturns{valid: true | false | null, key_id, algorithm, reason}with constant-time comparison (hmac.compare_digest). Pre-v0.9 unsigned receipts verify cleanly as{valid: null, reason: "no_signature"}— fully backwards-compatible.- Failure modes: invalid signing config at boot fails startup; runtime signing failures emit unsigned with a structured warning. Assembly is never blocked by audit infra. Tests include a caplog assertion that no key bytes ever appear in logs.
- Migration 0021 adds
receipts.receipt_signature_key_id+receipts.receipt_signature_algorithm(both nullable). Thereceipt_signaturecolumn from v0.8 lights up. Reversible.
Added — heuristic auto-labeling pipeline (statewave#158 · #164)
- New
memories.suggested_labels TEXT[]column (migration 0022, GIN-indexed) holds advisory detector hints, kept strictly separate from the authoritativesensitivity_labelsthe policy evaluator reads. A noisy detector cannot tighten policy on real traffic; promotion into the authoritative column is a deliberate, audited operator action. - v0.9 first-wave detectors:
pii.email(RFC-5322-ish),pii.phone(E.164 + grouped national),financial.card(Luhn-validated 13–19 digit run),secret.token(AWS / GitHub / OpenAI / Google / Slack prefixes + bearer JWT). Precision-first by design — false positives surface noisy admin rows; false promotions require an operator click. - Off by default. Opt-in via
STATEWAVE_AUTO_LABELING_ENABLED=true. Both compilers (heuristic, llm) run the pipeline after MemoryRow construction. Detector failures are isolated — a buggy detector cannot break ingest; others still fire and the failure logs with the memory id. - Review surface:
GET /admin/memories/with-suggested-labelsfilters via the GIN index, supports tenant / subject / specific-label filters, and returns the detector catalogue inline. Available regardless of the feature flag so an operator can flip it off and still triage legacy suggestions. - Reference:
docs/auto-labeling.md— schema, examples, what the pipeline explicitly does not do, how to add a detector.
Added — receipt replay with embedded policy snapshot (statewave#159 · #165, handoff symmetry follow-up locally)
- Every v0.9+ receipt embeds the active policy bundle's YAML (
policy_snapshot.bundle_yaml) and hash inside the signed body and into a denormalisedreceipts.policy_snapshotcolumn for fast indexing (migration 0023). A null inner pair records "no policy was active" (replayable, no-policy fallback). A NULL column records "pre-v0.9 receipt" (not replayable). POST /v1/receipts/{id}/replay(+POST /admin/receipts/{id}/replayshim for the admin proxy) re-runs the original retrieval against current memories using the original policy bundle from the snapshot. Emits a newmode="as_of_replay"receipt withparent_receipt_idset to the source. The original is never modified.- Returns a structural diff envelope:
context_hash.{original, replay, changed},selected_entries.{added, removed, common}(keyed by memory_id / episode_id so re-ranking iscommon, not add+remove),filters_applied.{added, removed}. - Refusal codes (HTTP 422, standard error envelope):
unreplayable.missing_policy_snapshot(pre-v0.9),unreplayable.nested_replay(replay-of-replay rejected; the audit trail is recoverable by walkingparent_receipt_id),unreplayable.invalid_snapshot(YAML failed to parse). - Semantic shipped: current code + original policy. Replay is not byte-for-byte reproduction; the diff envelope separates "the rules changed" from "the data changed" in incident reviews. Memory snapshots for true byte-for-byte replay are deferred — the data model leaves room without a schema break. Reference:
docs/replay.md. - Handoff symmetry:
/v1/handoffreceipts also carry the snapshot and are replayable through the same endpoint.
Added — operator promote endpoint + admin UI (statewave#160 · server #166, admin statewave-admin#89)
POST /admin/memories/{memory_id}/promote-labelsis the explicit commit action that moves a subset of a memory'ssuggested_labelsinto authoritativesensitivity_labels. Review-only: every label in the request body MUST currently be on the memory's suggested list — ad-hoc writes via this endpoint are refused with HTTP 422promote_labels.not_suggested.- Merge semantics: promoted labels are appended to
sensitivity_labels(deduped + sorted, pre-existing tenant-set labels preserved) and removed fromsuggested_labelsso the review queue never re-surfaces them. - Audit trail: each promotion appends an entry to
memory.metadata.label_promotions({labels, promoted_at, promoted_by: null}). Append-only, never overwritten.promoted_byisnullin v0.9 — admin identity is a separate work item; when it lands, the column populates without an audit-schema break. - Admin app surfaces: new
/suggested-labelsroute (sidebar entry) with the review queue + per-row promote action; receipt detail modal grows aReplay this receiptbutton that calls the new replay shim and renders the diff envelope inline. Pre-v0.9 receipts show an explanatory line instead of the button.
Added — per-tenant residency with hard application-layer enforcement (statewave#161 · #167)
- Model: per-region deployment + metadata-pinned tenants.
STATEWAVE_REGIONdeclares which region this server process is running in;tenant_configs.config.regionpins a tenant to a region. The application is the source of truth for "is this request allowed here?" — DNS, anycast, and load balancers can misroute requests; the application layer is the single point that knows definitively. ResidencyMiddlewareenforces on every tenant-scoped request (/v1/AND/admin/— total isolation per the v0.9 design decision). Mismatch returns HTTP 403 +error.code = residency.mismatch. The response carries the tenant's pinned region (operator-set, safe to surface) but never the local server's region (would leak topology to a caller probing the boundary).- Single-region deployments (
STATEWAVE_REGIONunset) pay zero cost — the middleware short-circuits before any DB work. DB blip during a residency check fails OPEN with a structured warning so a transient connection failure doesn't take down every tenant-scoped request. - Admin-patch safety: pinning a tenant to a region this server doesn't serve would immediately lock the tenant out. The PATCH endpoint refuses with HTTP 422
residency.invalid_pinunlessforce_region_pin: trueis supplied (for scripted bulk-config migrations run from a single-region orchestrator). - Receipts emitted in multi-region mode now stamp
settings.regionon thereceipts.regioncolumn the v0.8 schema reserved. Combined with HMAC (#157), the policy snapshot (#159), and replay (#159), residency closes the end-to-end audit story: where was this decision made, with what rules, was the body tampered with, would current code make the same call. - v0.9 ships code + config model + enforcement tests + ops runbook only — no actual second region is deployed by this PR. Reference:
docs/residency.md— full ops runbook for spinning up a second region (provision regional infra, smoke-test in single-region mode, migrate data, pin tenants in both regions, verify cutover).
- Visual policy editor — admin-app YAML-free form for building rule sets. Listed in the v0.9 roadmap; pushed to a later release to keep the v0.9 release focused on the audit + replay + residency story.
- Admin identity so promote / future operator-action endpoints can fill
promoted_by. - Bulk promotion across many memories. v0.9 is one-row-per-call; bulk lands when UI usage justifies it.
- Federated cross-region audit search — explicit follow-up to #161, never as implicit cross-region access.
- Memory snapshots for true byte-for-byte replay. The data model leaves room for it without a schema break.
Closes the Adoption half of the v0.8 milestone, on top of the Governance & Audit foundation shipped in v0.8.0. Each item shipped as its own focused PR; the full breakdown lives in roadmap.md under "Adoption — shipped".
Added — SDK convenience methods for support endpoints (statewave-py#15, statewave-ts#16)
get_health/getHealth,get_sla/getSLA,create_handoff/createHandoff,create_resolution/createResolution,list_resolutions/listResolutionson both the PythonStatewaveClient(sync + async) and the TypeScriptStatewaveClient.- Same auth, tenant-scoping, retry/backoff, and structured error handling as the rest of each client — these methods route through the existing shared request path.
- Wrap support-agent endpoints the server has exposed since v0.6, so callers no longer need raw HTTP alongside the SDK.
- Released as
statewave0.10.0 on PyPI and@statewavedev/sdk0.10.0 on npm (version-aligned across SDKs).
Added — webhook event-type filter (statewave#150 · docs statewave-docs#39)
STATEWAVE_WEBHOOK_EVENTS(comma-separated) — an event-type allowlist applied at the global webhook URL. Filtered-out events are dropped before they reach the delivery queue (zero storage, zero delivery attempts).- Unknown event types fail the server at startup, so a typo can't silently drop every webhook. Validation against the canonical event vocabulary in
server/core/webhook_events.py. - Fully backward-compatible: empty / unset filter delivers every event. No DB migration.
Added — memory templates for common patterns (statewave#152 · docs statewave-docs#41)
- Declarative, versioned scaffolds for recurring information patterns. Five bundled templates ship today:
customer-support-handoff,user-preference,project-decision,incident-summary,account-onboarding(serverserver/templates/*.yaml). - Read-only API exposes every template's full field schema for inspection:
GET /v1/memory-templates,GET /v1/memory-templates/{template_id}. POST /v1/memory-templates/{template_id}/applyvalidates caller-supplied field values against the template, deterministically renders the content, and ingests an ordinary episode withtemplate_id/template_versionrecorded in bothpayloadandmetadata.templatefor provenance.- Pure data — no code runs inside a template; rendering is plain string substitution. Adding a template is dropping a YAML file in
server/templates/. The compiler is unchanged. Reference:docs/memory-templates.md.
Added — framework integration examples (statewave-examples#12)
- Three runnable quickstarts under
statewave-examples:langchain-quickstart/,crewai-quickstart/,autogen-quickstart/. Each ships anadapter.py, a runnable demo, a mock-based smoke test (no LLM, no Statewave server needed), and a README. - Dependency strategy: zero framework deps in the core Statewave SDKs. Adapter code lives inside each example; framework versions pinned only in the example READMEs. SDK releases don't chase framework version churn.
- Adapter shapes:
StatewaveMemory(BaseMemory)for LangChain; pure-function helpers (build_task_description+record_crew_output,build_system_message+update_system_message+record_turn) for CrewAI and AutoGen — both dependency-free of their own framework so smoke tests run without those installs.
- First complete equal-budget sweep across the public LoCoMo dataset — four token tiers (512 / 1024 / 2048 / 4096) × 10 conversations × 1,986 questions/system, single consistent run.
- Publication-safety harness — refuses headline rankings without 100% scored coverage, the same question set across systems, no
judge_failedrows, and measured input tokens reported beside every score. - The benchmark suite is now maintained in statewave-memory-benchmarks — see it for current methodology and per-system results.
Added — design partner onboarding package (statewave-docs#42)
- New
design-partners.md: a single-page guide covering overview + 30/60/90-day relationship shape, who Statewave is for (strong + weak fit), a 30-minute setup path, recommended first use cases, data/privacy expectations, support and feedback loop, evaluation checklist (functional, performance, governance, operational), success criteria with benchmark reference numbers, and a 9-entry FAQ. Linked fromREADME.mdandSUPPORT.md.
Roadmap consistency (statewave-connectors#66 · statewave-docs#38 · statewave-docs#43)
- Connectors-repo roadmap brought into agreement with the canonical
statewave-docsroadmap: Tier 3 operator/cloud productization wave (v0.12.0–v0.17.0) recorded in the "State of the world" callout; the stale "Built-in OIDC verification for Gmail Pub/Sub" entry (shipped inconnectorsv0.15.0) removed from the Queued list in both copies. roadmap.mdticks every Adoption checkbox with PR citations, flips the← CURRENTmarker from v0.8 to v0.9, and renamesAdoption — in progresstoAdoption — shipped.
This release adds the governance layer that turns Statewave from "structured memory with provenance" into "structured memory with emitted, queryable, policy-governed accountability." Three components:
Added — state-assembly receipts (#49)
- Every
/v1/contextand/v1/handoffcall can emit an immutable, ULID-addressable receipt of which memories + episodes influenced the assembled bundle, plus a SHA-256 hash of the bytes delivered to the agent. Receipts are tenant-scoped, append-only, and queryable viaGET /v1/receipts/{id}andGET /v1/receipts?subject_id=&since=&until=&cursor=. - Strict-superset schema with a
modediscriminator (retrievalin v0.8;as_of_replayandeval_runreserved for v0.9) so future modes extend without breaking parsers. - Per-entry fields cover the supersession status (
active | superseded | tombstoned), source episodes, provenance hash, rank, and afact_key/conflict_statusslot for the conflict-resolution layer to fill in. - Reserved schema slots for v0.9 work:
parent_receipt_id(wired in v0.8 for chaining),region(for data residency),receipt_signature(for HMAC tamper-evidence). - Emission control is a single decision function consulting (env kill-switch → per-policy force-on → per-tenant config
receipts: always | on_request | never→ per-requestemit_receipt: bool). Fail-open: a receipt write error logs a structured warning and the assembly bundle still returns. - Six negative-test acceptance criteria from the design doc — stale fact selected, superseded memory ranked, tombstoned memory resurrected, unresolved conflict, as-of drift, byte tampering — each phrased as a deterministic assertion against the receipt body.
- Read API surface ships in both SDKs:
client.get_receipt(id),client.list_receipts(subject_id, ...). Receipts also exposed via the admin app's/receiptspage (read-only, cross-tenant) and the/admin/receiptscross-tenant operator endpoints. - Full reference in
receipts.md.
Added — sensitivity labels & per-memory policy bindings (#50)
- Per-memory capability tags stored as
memories.sensitivity_labels: TEXT[]with a GIN index for cheap overlap queries on the hot path. Operator-supplied viaPATCH /v1/memories/{id}/labels; server normalises (deduplicate + lowercase + trim) and caps at 32 entries per memory. - Declarative policy bundles in YAML or JSON, content-hashed and immutable in the new
policy_bundlestable. Six predicates (memory_has_any_label,memory_has_all_labels,caller_type,caller_type_in,caller_type_not_in,caller_id) AND-ed insidewhen:; first-match-wins across rules; default-allow on no match. Two actions:deny(drop memory) andredact(replace content with[REDACTED by policy]). - Caller identity in requests:
caller_idandcaller_typeon/v1/contextand/v1/handofffeed the evaluator. Tenant configrequire_caller_identity: true401s anonymous calls — the lever compliance customers flip to make policy enforcement non-bypassable. - Per-tenant policy_mode: log_only | enforce. Ships in
log_onlyby default — receipts record what would be denied without filtering the response, so operators can audit a policy for a few days before flipping toenforce. Without this lever the day a tenant enabled policy would silently lose memories for any under-tagged subject. - Receipts fill
policy.filters_applied(one entry per memory where a rule fired) andpolicy.filters_skipped(one entry per rule that ran but matched nothing — bounded bylen(bundle.rules), not memory count). - Admin endpoints:
POST /admin/policy/bundles(upload + optional activate),GET /admin/policy/bundles(list, optional tenant filter),GET /admin/policy/bundles/{hash}?tenant_id=(detail with disambiguation),POST /admin/policy/activate(flip active in a scope),POST /admin/policy/reload(bust in-process cache for direct DB fix-ups),GET /admin/policy/active?tenant_id=(returns200 + nullfor unconfigured scopes). - Admin app
/policypage: list, upload YAML, activate, detail viewer with parsed rules + when blocks + actions. - Full reference in
sensitivity-labels.md.
GET / PATCH /admin/tenants/{tenant_id}/configcovers the receipt emission policy, retention window (worker is v0.9), policy mode, and caller-identity gate. PATCH is partial-merge (only touches supplied keys, preserves the rest) so future per-tenant knobs land without each endpoint knowing the full key set.- Validation at the API boundary: enum values, integer bounds, and the documented key set are all checked by Pydantic before they reach the JSONB. A typo like
policy_mode: "enforced"returns 422 instead of silently leaving enforcement off — the failure mode the JSONB shape made too easy to introduce. - Optimistic concurrency via
expected_version: lost-update races between parallel admin edits surface as 409 with a clear message, not silent overwrites.expected_version=0is the create semantic for a tenant with no row yet. - Admin app: tenant-config form on the
/policypage (rendered when a tenant scope is selected), with an enforce-mode warning and 409-auto-reload on concurrent edits.
Added — cross-tenant policy bundle independence (#79)
policy_bundlesnow keyed on a synthetic UUIDidPK plus a composite unique index(tenant_id, bundle_hash) NULLS NOT DISTINCT(PG15+). Two tenants installing the identical YAML produce two independently-resolvable rows.GET /admin/policy/bundles/{hash}accepts?tenant_id=for disambiguation;POST /admin/policy/activaterequest body includestenant_idso the flip targets exactly(tenant, hash).- Pre-fix, the second tenant's upload silently re-bound the first's row and broke their policy resolution. Caught in the enforce-mode prod smoke; the temporary workaround was to add a tenant-identifying comment to the YAML.
- Multi-replica policy bundle cache staleness (#77) — dropped the in-process cache on
policy_bundles. The 60-second TTL caused replicas that hadn't handled the admin upload to keep serving the pre-uploadNonevalue until their TTL expired, which underenforcewould silently pass sensitive memories through for up to a minute after a tenant activated a policy. DB lookup is sub-millisecond with the existing index; correctness > caching savings. Caught in production smoke testing. /admin/policy/active404 → 200 + null when no bundle is active for the scope. "No bundle uploaded yet" is the default state on fresh install, not an error. 404 polluted every operator's browser console on first page load.- Stacked-PR rebase hygiene in the merged history — the closed-by-cascade PRs (server #73, py #8, ts #10) have explanatory comments pointing at their replacement PRs.
- The receipt body shape was chosen as a strict superset rather than a tagged union so v0.9's
as_of_replayandeval_runmodes can extend without forcing every receipt consumer to update its parser. Themodediscriminator carries the actual variant. policy_bundlesuses a synthetic UUID PK rather than a sentinel-tenant approach (tenant_id NOT NULL DEFAULT '') so wire shapes don't shift — global bundles still appear astenant_id: nullon the wire post-#79.- The policy evaluator is intentionally pure (no DB, no IO inside
evaluate_memory) so it can be tested directly with synthetic rules and memories. Bundle resolution is the only DB-touching part.
alembichead moved from0016_memory_status_tombstonedto0019_per_tenant_bundles. Three new migrations:0017_receipts_and_policy—receipts,tenant_configs,policy_bundlestables.0018_sensitivity_labels—memories.sensitivity_labels TEXT[]+ GIN index.0019_per_tenant_bundles— composite uniqueness onpolicy_bundles(synthetic UUID PK +(tenant_id, bundle_hash) NULLS NOT DISTINCT).
statewaveserver v0.8.0 — full surface above.statewave-py0.8.0 (PyPI) —Receipt,ReceiptList,set_memory_labels,get_receipt,list_receipts,caller_id/caller_typeonget_context().statewave-ts0.8.0 (npm@statewavedev/sdk) — same surface, first-class types.statewave-admin— Receipts viewer, Policy page (upload + activate + bundle detail), Tenant config form, sensitivity-labels editor onMemoryDetailModal.
- Per-kind memory TTL — operators configure global expiry windows per memory kind (
profile_fact,episode_summary,procedure,artifact_ref) viaSTATEWAVE_KIND_TTL_DAYS(JSON). Compilers stampvalid_to = valid_from + ttl_daysat insert;/v1/contextretrieval filters expired rows immediately; an hourly cleanup loop tombstones expired rows. Soft-delete only — rows are preserved for audit and future receipt lookup. (#59, full operator guide:deployment/memory-ttl.md) - MemoryStatus enum aligned to
active | superseded | tombstoned— the previously unuseddeletedvalue renamed totombstoned(alembic 0016) so the status surface composes cleanly with the receipts work in #49. - Helm chart at
helm/statewave— API-only chart with pre-install hook ordering, externalSecret support, optional HPA + Ingress + PDB, and migration Job. (#58) - Cross-machine query embedding cache (L2) — Postgres-backed
query_embedding_cachetable (alembic 0014) shared across all backend instances. Wraps the in-process LRU as L2: warm calls are sub-second regardless of which instance handles them. 24h TTL, composite (text, model) key. - In-process LRU + TTL query embedding cache (L1) — eliminates repeat provider calls on identical task text in
/v1/context. - CODE_OF_CONDUCT.md — adopt-by-reference Contributor Covenant 2.1.
- All LLM and embedding calls go through a single LiteLLM adapter (
server/services/llm.py). One env-var contract (STATEWAVE_LITELLM_*), 100+ provider compatibility, consistent retry + timeout + structured logging. - Cross-workspace positioning unified —
Open-source memory runtime for AI agentsis now the canonical tagline across homepage, READMEs, package descriptions, GitHub bios, and Docker Hub. - Docker Hub repo description sync now succeeds via the OAT-scoped
DOCKERHUB_TOKEN.
- New: deployment sizing guide, capacity-planning checklist.
- Session-aware context assembly — active session boosted, resolved sessions deprioritized
- Resolution tracking —
POST /v1/resolutions,GET /v1/resolutionsfor open/resolved/unresolved state per session - Handoff context packs —
POST /v1/handoffgenerates compact escalation briefs with customer summary, active issue, attempted steps, resolution history, health, and SLA context - Customer health scoring —
GET /v1/subjects/{id}/healthreturns deterministic 0–100 score with explainable factors (unresolved issues, repeats, escalations, idle open issues, SLA breaches, slow response) - Repeat-issue detection — surfaces prior resolutions when episode patterns recur
- Support-specific ranked retrieval — session awareness, resolution status, and health signals feed into context ranking
- Health-aware handoff — risk level, score, and top factors appear in handoff briefs
- Proactive health alerts —
subject.health_degradedandsubject.health_improvedwebhooks on state transitions - SLA tracking —
GET /v1/subjects/{id}/slacomputes first-response time, resolution time, and breach flags per session with configurable thresholds - SLA integration — breach signals feed into health scoring; SLA summary appears in handoff packs when relevant
- 3 eval suites: context quality (7 tests, 14 assertions), handoff (7 tests, 16 assertions), advanced (7 tests, 24 assertions)
- 2 benchmarks: context recall + workflow comparison (Statewave 8/8 vs Naive 2/8)
- 232 unit tests passing
- Health scoring now includes SLA breach penalty and slow first-response penalty
- Handoff packs now include conditional SLA section (absent when clean)
- Context ranking formula updated with session and resolution awareness
- True multi-tenant isolation — tenant_id persisted on all tables, all queries scoped by tenant
- Distributed rate limiting — Postgres-backed fixed-window, survives restarts, multi-worker
- Backup/restore tooling — subject-level export/import via admin API with SHA-256 checksum
- Tenant audit endpoint —
GET /admin/tenant-auditfor NULL-tenant row discovery - Admin export/import —
GET /admin/export/{subject_id},POST /admin/import - Operator upgrade guidance for pre-tenant data backfill
- Rate limiting now defaults to
distributedstrategy (Postgres-backed) - Tenant middleware no longer experimental — real data isolation enforced
- Background cleanup loop now also handles rate limit window pruning
0008_add_tenant_id_columns— tenant_id + indexes on episodes, memories, webhook_events, subject_snapshots0009_add_rate_limit_table— rate_limit_hits table for distributed rate limiting
- README rewrite across all repos — accurate product framing, docs navigation, current limitations
- Consistent tagline and cross-repo linking
- SDK READMEs updated with batch and subject listing examples
- CI workflows: added tests to TS CI, fixed lint errors
- Release workflows: tag-push trigger, CI gate, no accidental releases
- PUBLISHING.md rewritten for automated release process
- Cleaned up all failed GitHub Actions runs
- Batch episode ingestion —
POST /v1/episodes/batchaccepts up to 100 episodes per request - OpenTelemetry tracing — optional tracing spans on compile, search, and context assembly. Install with
pip install statewave[otel] - Comprehensive
.env.example— documents allSTATEWAVE_*configuration variables with comments
- Python SDK 0.4.0 —
create_episodes_batch()method,BatchCreateResultmodel,py.typedmarker, PyPI-ready metadata (classifiers, URLs, keywords) - TypeScript SDK 0.4.0 —
createEpisodesBatch()method,BatchCreateResulttype, npm-ready metadata (exports, files, engines, repository) - Publish checklists —
PUBLISHING.mdin both SDK repos
- Deployment guide — Docker Compose, bare metal, single container, Fly.io, Railway instructions with production checklist
- SDK changelogs —
CHANGELOG.mdin both SDK repos
- TTL/auto-expiry — deferred to v0.5.
valid_toon memories provides manual expiry semantics. Automatic sweep requires a background scheduler not yet justified.
- Middleware execution order — corrected Starlette reverse-ordering so auth runs before rate limiting and request ID is set outermost
- Compile + conflict resolution transaction — both now execute in a single commit, preventing data inconsistency on partial failure
- LLM compiler event loop blocking —
LLMCompilernow usesThreadPoolExecutorso synchronous OpenAI calls don't block async request handling - Episode route uses repository layer — previously bypassed
repo.insert_episode()and used raw session directly - Request validation — added
min_length/max_lengthon string fields, boundedmax_tokens(1–128,000) andlimit(1–100)
- Python SDK 0.3.5 — added
api_keyandtenant_idconstructor params,semanticparam onsearch_memories() - TypeScript SDK 0.3.5 — added
ClientOptionswithapiKey/tenantId,semanticparam onsearchMemories()
- All examples now accept
STATEWAVE_API_KEYandSTATEWAVE_URLenvironment variables - Coding agent example added to examples README
- API contract doc fully rewritten to match v0.3.5 server behavior (auth, semantic, webhooks, validation, config reference)
- Architecture overview updated with v0.3 component diagram, scoring model, middleware stack
- Repo map updated with current versions, test counts, and server structure
- Development conventions refreshed with current SDK features and test counts
- ADR-004 written documenting all v0.3 architectural decisions
- Multi-tenant demoted to "experimental" with clear documentation that data isolation is not implemented
- LLM-backed memory compiler (
LLMCompilerusing OpenAI chat completions) - Embedding generation during compilation (OpenAI + stub providers)
- Semantic search via pgvector cosine similarity with
semantic=truequery param - Temporal reasoning in context assembly (+3 bonus for valid, -4 penalty for expired memories)
- Memory conflict resolution (Jaccard similarity, auto-supersede older overlapping memories)
- Webhook event hooks (
episode.created,memories.compiled,subject.deleted) - API key authentication middleware (
X-API-Keyheader) - Rate limiting middleware (per-IP sliding window)
- Multi-tenant header extraction middleware (
X-Tenant-ID, experimental) - Coding agent example (
coding-agent-python/)
- Idempotent memory compilation (only uncompiled episodes processed)
- Pluggable
BaseCompilerprotocol withHeuristicCompiler - Token-bounded context assembly with configurable budget
- Ranked retrieval (kind priority × recency × task-keyword relevance)
- Structured error responses with consistent JSON shape
- Request ID middleware (
X-Request-IDheader) - CORS configuration
- Health endpoints (
/healthz,/readyz) - Structured logging via structlog (JSON in production, console in dev)
- Python SDK 0.2.0 — typed exceptions (
StatewaveAPIError,StatewaveConnectionError,StatewaveTimeoutError), async client - TypeScript SDK 0.2.0 — typed errors, full type exports
- Support agent example (2-session demo with ranked context)
- Core domain model (Episode, Memory, ContextBundle)
- FastAPI server with 6 endpoints
- Heuristic memory compiler (regex/pattern extraction)
- Context assembly with token estimation
- PostgreSQL + pgvector schema with Alembic migrations
- Docker Compose local deployment
- Python SDK 0.1.0
- TypeScript SDK 0.1.0
- Minimal quickstart example
- CI/CD pipeline (GitHub Actions)