Related Pages

Related topics: System Architecture, Getting Started

Overview - What is Statewave?

Statewave is a self-hosted memory infrastructure for AI agents. It enables AI systems to store, retrieve, compile, and reason over long-term contextual information across conversations and sessions.

Core Concept

Statewave solves the memory problem for AI agents by providing:

• Episode Ingestion — Capture events, conversations, and real-world signals as structured memory units
• Memory Compilation — Transform raw episodes into refined, actionable memories using LLM or heuristic approaches
• Context Assembly — Retrieve and rank relevant memories within token budgets for inference
• Temporal Reasoning — Track state changes and resolution status over time

The system operates as a REST API service that agents and applications query to build persistent, evolving memory without hand-writing custom storage and retrieval logic for each use case.

Architecture Overview

graph TD
    subgraph "Sources"
        MCP[MCP Server]
        GH[GitHub]
        MD[Markdown Docs]
        SL[Slack]
        APP[Application]
    end

    subgraph "Statewave Core"
        INGEST[Ingestion API]
        COMPILE[Memory Compiler]
        SEARCH[Search API]
        CONTEXT[Context Assembly]
    end

    subgraph "Storage"
        PG[(PostgreSQL<br/>+ pgvector)]
    end

    MCP --> INGEST
    GH --> INGEST
    MD --> INGEST
    SL --> INGEST
    APP --> INGEST

    INGEST --> PG
    COMPILE --> PG
    SEARCH --> PG
    CONTEXT --> PG

    APP --> SEARCH
    APP --> CONTEXT

Key Components

Data Flow

graph LR
    A[Source Event] --> B[POST /v1/episodes]
    B --> C[(Episode Store)]
    C --> D[POST /v1/memories/compile]
    D --> E[(Memory Store)]
    E --> F[GET /v1/memories/search]
    F --> G[POST /v1/context]
    G --> H[Ranked Context Bundle]

API Reference

Core Endpoints

Subject Management

Resolution Tracking

Additional Endpoints

Sources: README.md:26-49

Connectors

Statewave is not limited to live chat transcripts. Connectors feed real-world events into Statewave as episodes, enabling agents to build memory from diverse sources.

Sources: README.md:53-60

Deployment

Docker Deployment

Statewave is deployed as a containerized service using Docker Compose:

services:
  app:
    image: statewavedev/statewave:latest
    ports: ["8100:8100"]
    environment:
      STATEWAVE_DATABASE_URL: postgresql+asyncpg://statewave:statewave@db:5432/statewave
      STATEWAVE_LITELLM_API_KEY: sk-...
    depends_on:
      db:
        condition: service_healthy

docker compose up -d
curl http://localhost:8100/healthz

Sources: DOCKER.md

Environment Configuration

Sources: README.md:93-107

Multi-Tenant Support

Statewave supports multi-tenant deployments through application-layer isolation:

• Tenant Header: X-Tenant-ID header identifies the tenant (configurable via STATEWAVE_TENANT_HEADER)
• Query-Scoped Isolation: Data isolation is enforced at the query layer
• Per-Tenant Configuration: Policy bundles and receipts support tenant-specific settings

Sources: README.md:100-107

Documentation System

Statewave includes a documentation-grounded memory system:

• Curated documentation sections are chunked at heading boundaries
• Each section becomes an episode with source="statewave-docs", type="doc_section"
• Episodes carry a deterministic content hash for change detection
• A bundled starter pack provides 276 episodes and 364 compiled memories out of the box

Sources: scripts/docs_loader.py Sources: server/starter_packs/statewave-support-agent/manifest.json

Evaluation Framework

The repository includes an evaluation framework for testing docs-grounded retrieval:

@dataclass
class Question:
    task: str
    expected_doc_paths: list[str]
    expected_terms: list[str]

Sample evaluation questions verify that the system correctly surfaces documentation for queries about deployment, compilation modes, hardware requirements, and API contracts.

Sources: scripts/eval/eval_docs_support.py

Starter Packs

Statewave ships with pre-built starter packs:

Sources: server/starter_packs/statewave-support-agent/manifest.json Sources: scripts/build_demo_packs.py

Health Monitoring

Statewave provides subject-level health monitoring:

• Health Score: Aggregated customer health with explainable factors
• SLA Metrics: Response time, resolution time, and breach tracking
• Snapshot Restore: Restore subject state from snapshots with timestamp shifting

Sources: README.md:46-47 Sources: server/services/snapshots.py

Getting Started

``bash docker compose up db -d python -m venv .venv && source .venv/bin/activate pip install -e ".[dev,llm]" alembic upgrade head uvicorn server.main:app --host 0.0.0.0 --port 8100 ``

1. Quick Start:

```bash # Unit tests (no DB required) pytest tests/test_*.py -v

1. Run Tests:

# Integration tests (requires Postgres) PGPASSWORD=statewave createdb -h localhost -U statewave statewave_test pytest tests/integration/ -v ```

Sources: CONTRIBUTING.md Sources: README.md:11-19

Current Limitations

Sources: README.md:117-122

Repository Structure

Sources: SUPPORT.md:73-83

Related Pages

Related topics: Overview - What is Statewave?, API Endpoints Reference

Getting Started

Overview

The Getting Started guide provides developers and operators with the essential knowledge to install, configure, and run Statewave — an agent memory system that captures, compiles, and retrieves episodic and semantic memory for AI agents. The guide covers three primary deployment paths: Docker Compose for local development, Helm charts for Kubernetes production environments, and Python packages for programmatic integration.

Statewave operates as an append-only memory store where episodes represent raw events (chat messages, commits, support tickets) and memories are compiled, high-confidence knowledge units derived from episodes through LLM or heuristic processing. The system enables agents to assemble token-bounded context bundles for RAG (Retrieval-Augmented Generation) workflows.

Sources: README.md:1-50

System Architecture

graph TD
    subgraph "Ingestion Layer"
        E[Episodes] --> B[Batch Ingest]
        E --> S[Single Ingest]
    end
    
    subgraph "Compilation Layer"
        S --> COMP[Memory Compiler]
        B --> COMP
        COMP -->|LLM or Heuristic| M[Memories]
    end
    
    subgraph "Retrieval Layer"
        M --> CX[Context Assembler]
        Q[Query] --> CX
        CX --> CB[Token-Bounded Context]
    end
    
    subgraph "Storage Layer"
        M --> PG[(PostgreSQL)]
        E --> PG
    end
    
    subgraph "Connectors"
        MCP[MCP Server]
        GH[GitHub]
        MD[Markdown]
        SL[Slack]
        MCP --> E
        GH --> E
        MD --> E
        SL --> E
    end

Prerequisites

Before beginning the installation, ensure the following requirements are met:

Sources: DOCKER.md:1-30

Installation Methods

Quick Start with Docker Compose

The fastest path to a running Statewave instance uses Docker Compose:

# docker-compose.yml
services:
  api:
    image: statewavedev/statewave:latest
    ports: ["8100:8100"]
    environment:
      STATEWAVE_DATABASE_URL: postgresql+asyncpg://statewave:statewave@db:5432/statewave
      STATEWAVE_LITELLM_API_KEY: sk-...
    depends_on:
      db:
        condition: service_healthy

volumes:
  pgdata:

Sources: DOCKER.md:40-55

Execute the following commands to start Statewave:

# Start the stack
docker compose up -d

# Verify health
curl http://localhost:8100/healthz

Pinning a Specific Version

Production deployments should pin to a specific version:

STATEWAVE_VERSION=0.7.0 docker compose up -d

Available tagging conventions:

Sources: DOCKER.md:70-85

Verify Build Attestation

For supply chain security, verify the container image:

gh attestation verify \
  oci://docker.io/statewavedev/statewave:latest \
  --owner smaramwbc

Sources: DOCKER.md:90-95

Environment Configuration

Statewave uses environment variables for all configuration. The following table documents the complete set:

Sources: README.md:180-200

API Endpoints

Health and Readiness

Core Memory Operations

Advanced Operations

Sources: README.md:30-60

Connectors Ecosystem

Statewave supports external data sources through modular connectors:

# Install connectors individually
npm install @statewavedev/connectors-github
npm install @statewavedev/connectors-markdown
npm install @statewavedev/connectors-slack
npm install @statewavedev/connectors-n8n
npm install @statewavedev/connectors-zapier
npm install @statewavedev/mcp-server

# Meta-package for all connectors
npm install @statewavedev/connectors

Available connectors and their status:

Sources: README.md:250-280

Connector Usage Examples

# Sync GitHub data (dry-run first)
statewave-connectors sync github \
  --repo smaramwbc/statewave \
  --subject repo:smaramwbc/statewave \
  --dry-run

# Sync Markdown documentation
statewave-connectors sync markdown \
  --path ./docs \
  --subject repo:smaramwbc/statewave \
  --dry-run

# Start MCP server
statewave-connectors mcp start

Kubernetes Deployment

For production environments, use the Helm chart:

helm install statewave ./helm/statewave \
  --set database.url='postgresql+asyncpg://...' \
  --set llm.apiKey='sk-...' \
  --set auth.apiKey='replace-me'

The Helm chart runs a pre-install Job (alembic upgrade head) before any API pod admits traffic. Upgrades repeat migration as a pre-upgrade Job.

Sources: helm/statewave/README.md:1-40

Helm Configuration Reference

Sources: helm/statewave/README.md:50-70

Running Tests

Statewave includes unit tests (no database required) and integration tests (requires PostgreSQL):

# Unit tests
pytest tests/test_*.py -v

# Integration tests
PGPASSWORD=statewave createdb -h localhost -U statewave statewave_test
pytest tests/integration/ -v

# All tests
pytest tests/ -v

Sources: README.md:210-220

Bootstrap Documentation Pack

After initial deployment, bootstrap the documentation memory pack for a self-hosted support agent:

python -m scripts.bootstrap_docs_pack [--docs-path PATH] [--purge] [--dry-run]

Environment Variables for Bootstrap

Bootstrap Behavior

graph LR
    A[Read statewave-docs corpus] --> B[Ingest each section as Episode]
    B --> C[Compile Episodes to Memories]
    C --> D[Assemble docs-grounded Knowledge Base]
    D --> E[Support Agent queries via POST /v1/context]
    
    F[--purge] -.->|Wipe and rebuild| A
    G[--dry-run] -.->|No ingestion| A

The bootstrap process is idempotent. By default, it fails if the subject already has episodes. Re-run with --purge to wipe and rebuild from scratch.

Sources: scripts/bootstrap_docs_pack.py:1-50

Seed Demo Subjects

For development and testing, seed demo subjects with sample data:

python -m scripts.seed_demo_subjects [--dry-run]

This creates sample episodes and memories that reference each other, enabling verification of the compilation and retrieval pipeline.

Sources: scripts/seed_demo_subjects.py:1-60

Current Limitations

Statewave v0.8.0 has known limitations:

Sources: README.md:225-235

Next Steps

Related Pages

Related topics: Overview - What is Statewave?, Database Schema & Migrations, Compilation Services

System Architecture

Statewave is an AI agent memory system designed to ingest real-world events as episodes, compile them into structured memories, and retrieve ranked, token-bounded context for agentic workflows. The system follows a layered architecture with clear separation between API handling, business logic services, data persistence, and external connectors.

High-Level Architecture Overview

graph TD
    subgraph "External Clients"
        A[Agents / Applications]
        B[Connectors: GitHub, Slack, MCP]
        C[SDK Clients]
    end

    subgraph "API Layer"
        D[FastAPI Application]
        E[Endpoint Routes]
        F[Middleware / Auth]
    end

    subgraph "Service Layer"
        G[Episode Service]
        H[Memory Service]
        I[Compiler Service]
        J[Search Service]
        K[Snapshot Service]
    end

    subgraph "Data Layer"
        L[(PostgreSQL)]
        M[(Vector Embeddings)]
        N[Starter Packs]
    end

    A --> D
    B --> D
    C --> D
    D --> F
    F --> E
    E --> G
    E --> H
    E --> I
    E --> J
    E --> K
    G --> L
    H --> L
    H --> M
    I --> L
    J --> M
    K --> L
    K --> N

Core Data Models

Episode

An Episode represents a discrete unit of experience — a chat message, a support ticket update, a GitHub issue event, or a documentation section. Episodes are the atomic ingestion unit in Statewave.

Sources: server/db/tables.py

Memory

A Memory is a compiled, structured artifact extracted from one or more episodes. Memories have temporal validity windows, confidence scores, and lineage tracking.

Sources: server/api/timeline.py

Subject

A Subject is the central entity in Statewave — a persona, entity, or concept that accumulates memory over time.

Sources: server/db/tables.py

API Layer

REST API v1

The API is served by FastAPI on port 8100 by default and exposes OpenAPI documentation at /docs and ReDoc at /redoc.

graph LR
    A[Client] --> B["POST /v1/episodes"]
    A --> C["POST /v1/episodes/batch"]
    A --> D["POST /v1/memories/compile"]
    A --> E["GET /v1/memories/search"]
    A --> F["POST /v1/context"]
    A --> G["GET /v1/timeline"]
    A --> H["GET /v1/subjects"]
    A --> I["DELETE /v1/subjects/{id}"]
    A --> J["POST /v1/resolutions"]
    A --> K["POST /v1/handoff"]
    A --> L["GET /v1/subjects/{id}/health"]
    A --> M["GET /v1/subjects/{id}/sla"]

Core Endpoints

Sources: README.md

Health Endpoints

Sources: README.md

Service Layer

Compiler Service

The compiler extracts memories from episodes. Statewave supports two compilation modes:

#### Heuristic Compiler

The heuristic compiler extracts two memory kinds from episodes:

1. episode_summary: A 500-character truncation of the episode text with 0.8 confidence
2. profile_fact: Extracted profile facts with 0.6 confidence

MemoryRow(
    kind="episode_summary",
    content=text[:500],
    summary=text[:200],
    confidence=0.8,
    valid_from=ep_valid_from,
    valid_to=compute_valid_to("episode_summary", ep_valid_from, ttl),
    source_episode_ids=[ep.id],
    status="active",
)

Sources: server/services/compilers/heuristic.py

#### Temporal Anchoring

The compiler determines episode temporal anchors with the following priority:

1. payload.event_time — Explicit client override for historical data replay
2. payload.messages[0].timestamp — First message timestamp in chat-shaped payloads (used by LoCoMo, Slack, Zendesk connectors)
3. created_at — Fallback to ingestion timestamp

graph TD
    A[Episode Ingestion] --> B{event_time present?}
    B -->|Yes| C[Use event_time]
    B -->|No| D{messages timestamp present?}
    D -->|Yes| E[Use messages[0].timestamp]
    D -->|No| F[Use created_at]

Sources: server/services/compilers/heuristic.py

Snapshot Service

Snapshots enable point-in-time restoration of subject data, including episodes, memories, and resolutions.

snapshot = SubjectSnapshotRow(
    name=name,
    version=version,
    source_subject_id=snapshot_subject,
    episode_count=len(eps),
    memory_count=len(mems),
    metadata_=metadata or {},
)

Sources: server/services/snapshots.py

Timeline Service

The timeline service provides chronological event merging across episodes and resolutions within a session.

graph TD
    A[Session Request] --> B[Fetch Episodes]
    A --> C[Fetch Resolutions]
    B --> D[Merge Events Chronologically]
    C --> D
    D --> E[TimelineResponse]
    
    E --> F[TimelineEpisodeEvent]
    E --> G[TimelineResolutionEvent]
    
    F --> H[id]
    F --> I[source]
    F --> J[type]
    F --> K[payload]
    F --> L[created_at]
    F --> M[citing_memory_count]
    
    G --> N[resolved_at]
    G --> O[status]

#### Timeline Response Model

Sources: server/api/admin.py

Handoff Service

The handoff endpoint generates compact context packs for transferring conversation context between agents or sessions.

Sources: server/api/handoff.py

Data Layer

Database Schema

Statewave uses PostgreSQL with SQLAlchemy async for data persistence. Key tables:

Multi-Tenancy

Multi-tenant isolation is implemented at the application layer:

Sources: README.md

Current Limitation: Multi-tenant isolation is query-scoped (application-layer) with no PostgreSQL Row-Level Security (RLS) enforcement.

Connectors

Connectors feed external data sources into Statewave as episodes without requiring custom ingestion code.

graph LR
    A[GitHub] -->|Issues, PRs, Reviews| B[Connector]
    C[Slack] -->|Messages, Threads| B
    D[MCP Server] -->|Agent Memory| B
    E[Markdown] -->|Docs, RFCs| B
    F[n8n] -->|Workflow Events| B
    G[Zapier] -->|Automation Triggers| B
    
    B --> H[Episodes]
    H --> I[Statewave API]

Available Connectors

Sources: README.md

Configuration

Environment Variables

Sources: README.md

Deployment

Docker Deployment

Statewave is distributed as a Docker image and can be deployed using Docker Compose.

services:
  statewave:
    image: statewavedev/statewave:latest
    ports: ["8100:8100"]
    environment:
      STATEWAVE_DATABASE_URL: postgresql+asyncpg://statewave:statewave@db:5432/statewave
      STATEWAVE_LITELLM_API_KEY: sk-...
    depends_on:
      db:
        condition: service_healthy

#### Image Tags

Sources: DOCKER.md

Helm Chart

Kubernetes deployment is supported via Helm:

Sources: helm/statewave/README.md

Testing

Test Execution

# Unit tests (no DB required)
pytest tests/test_*.py -v

# Integration tests (requires Postgres)
PGPASSWORD=statewave createdb -h localhost -U statewave statewave_test
pytest tests/integration/ -v

# All tests
pytest tests/ -v

Sources: README.md

Related Pages

Related topics: System Architecture, Governance - Receipts & Policy Engine

Database Schema & Migrations

Overview

The Statewave application uses PostgreSQL as its primary data store, managed through SQLAlchemy ORM with Alembic for schema migrations. The database layer provides persistent storage for the core domain entities: Subjects, Episodes, Memories, Resolutions, and Snapshots.

All tables use UUID v4 as primary keys and include automatic timestamp tracking (created_at, updated_at) with timezone-aware DateTime(timezone=True) columns. The schema is designed to support multi-tenant isolation through a tenant_id column on relevant entities.

Sources: server/db/tables.py

Architecture

graph TD
    subgraph "Database Layer"
        T[PostgreSQL]
        ORM[SQLAlchemy ORM]
        MIG[Alembic Migrations]
    end
    
    subgraph "Core Tables"
        SUBJ[subjects]
        EP[episodes]
        MEM[memories]
        RES[resolutions]
        SNAP[snapshots]
        POL[policy_bundles]
        SES[sessions]
    end
    
    T --> ORM
    ORM --> SUBJ
    ORM --> EP
    ORM --> MEM
    ORM --> RES
    ORM --> SNAP
    ORM --> POL
    ORM --> SES
    
    MIG -.->|manage schema| T

Core Table Definitions

subjects

The central entity representing a user, entity, or concept that episodes and memories are associated with.

Sources: server/db/tables.py

episodes

Immutable event records representing interactions, activities, or data points fed into the system via connectors.

Sources: server/db/tables.py Sources: server/services/context.py

memories

Compiled, semantically indexed summaries derived from episodes. Memories have temporal validity windows and confidence scores.

Sources: server/db/tables.py

Status Values:

Sources: alembic/versions/0016_memory_status_tombstoned.py

resolutions

Tracks issue or conversation resolution state per session.

Sources: server/db/tables.py Sources: server/services/snapshots.py

subject_snapshots

Immutable snapshots capturing a point-in-time state of a subject for backup/restore purposes.

Sources: server/db/tables.py

policy_bundles

Immutable policy YAML bundles content-addressed by bundle_hash.

Sources: server/db/tables.py

Design Note: Composite unique index on (tenant_id, bundle_hash) NULLS NOT DISTINCT ensures one bundle per (scope, content) combination while allowing multiple tenants to install the same policy independently.

Migration System

Statewave uses Alembic for database schema versioning. Migrations are located in the alembic/versions/ directory and follow a sequential naming convention (e.g., 0016_memory_status_tombstoned.py).

Migration Workflow

graph LR
    A[Development] --> B[Create Migration]
    B --> C[Review SQL]
    C --> D[Apply: alembic upgrade head]
    D --> E[Production Deploy]
    E --> F[Rollback if needed: alembic downgrade]

Migration Naming Convention

Migrations use the format XXXX_<short_description>.py where XXXX is a zero-padded sequence number. This ensures deterministic ordering across distributed development.

Migration Example: Status Rename

The migration 0016_memory_status_tombstoned.py demonstrates the migration pattern:

"""memories.status — rename `deleted` to `tombstoned` (defensive)

Revision ID: 0016_memory_status_tombstoned
Revises: 0015_episode_occurred_at
Create Date: 2026-05-10

Purpose:

1. Normalize any existing deleted values to tombstoned
2. Align vocabulary with issue #49 (State-assembly receipts specify supersession_status: active | superseded | tombstoned)
3. Provide a visible breadcrumb for future developers tracing the change

Sources: alembic/versions/0016_memory_status_tombstoned.py

Key Migration Characteristics

Data Import/Export

The backup service (server/services/backup.py) provides import/export functionality that serializes and deserializes subjects, episodes, and memories.

Import Process

graph TD
    A[JSON Archive] --> B[Parse episodes_data]
    B --> C[Parse memories_data]
    C --> D[Resolve subject_id]
    D --> E[Insert Episodes]
    E --> F[Insert Memories]
    F --> G[Return Import Result]
    
    E -->|preserve_ids| E1[Use original UUIDs]
    E -->|new_ids| E2[Generate new UUIDs]

Import Flow:

1. Validate archive structure
2. Resolve target subject_id based on conflict_strategy
3. Insert episodes with optional ID preservation
4. Insert memories with source episode ID remapping
5. Commit transaction

Sources: server/services/backup.py

Snapshot Restore Process

Snapshots preserve the complete state of a subject including temporal offsets:

# Timestamp shifting during restore
time_shift = restore_time - snapshot.created_at
valid_from = mem_valid_from + time_shift
valid_to = (mem_valid_to + time_shift) if mem_valid_to else None

The metadata_ field receives "restored_from_snapshot": str(snapshot_id) for audit tracking.

Sources: server/services/snapshots.py

Schema Design Patterns

Temporal Modeling

Memories use valid_from and valid_to columns for temporal validity:

def compute_valid_to(kind: str, valid_from: datetime, ttl: dict) -> datetime | None:
    """Compute expiration based on memory kind TTL."""
    ttl_hours = ttl.get(kind, DEFAULT_TTL_HOURS)
    return valid_from + timedelta(hours=ttl_hours)

Sources: server/services/compilers/heuristic.py

Temporal Anchoring

The system extracts temporal anchors from episodes with priority:

1. payload.event_time — explicit client override
2. payload.messages[0].timestamp — first message timestamp in chat payloads
3. created_at — fallback to ingestion time

Sources: server/services/compilers/heuristic.py

JSONB Flexibility

Columns like payload, metadata_, and provenance use PostgreSQL's JSONB type for schema flexibility:

• payload: Raw event data varying by source connector
• metadata_: Extracted structured data
• provenance: Source attribution with content hashes

This allows the system to evolve connectors without schema migrations.

Composite Indexes

Key indexes for query performance:

See Also

• API v1 Contract — Database operations via REST API
• Deployment Guide — Database configuration
• Helm Chart Configuration — Migration job settings

Related Pages

Related topics: Context Assembly & Ranking

API Endpoints Reference

Overview

The Statewave API provides a comprehensive set of RESTful endpoints for managing agent memory, tracking session context, and enabling multi-tenant workspace isolation. The API is built on FastAPI and follows OpenAPI standards with automatic documentation at /docs (Swagger UI) and /redoc (ReDoc).

Base URL: http://localhost:8100

API Version: v1

All endpoints support multi-tenant isolation through the X-Tenant-ID header, configurable via the STATEWAVE_TENANT_HEADER environment variable. The API enforces query-scoped data isolation for multi-tenant deployments. Sources: README.md

Related Pages

Related topics: API Endpoints Reference, Embedding Services, Governance - Receipts & Policy Engine

Context Assembly & Ranking

Context Assembly & Ranking is the core mechanism that transforms raw episodic memory into a curated, token-bounded context bundle for LLM consumption. When an agent queries Statewave for context, the system retrieves relevant memories and episodes, scores them by relevance, and assembles them within a configurable token budget.

Architecture Overview

The context assembly system operates as a multi-stage pipeline:

1. Retrieval — Query memories and episodes by subject, kind, text, or semantic similarity
2. Scoring — Assign relevance scores to each item using configurable strategies
3. Ranking — Sort items by score and enforce token budget constraints
4. Assembly — Build the final context bundle with proper formatting and ordering

graph TD
    A[Client Request: POST /v1/context] --> B[ContextService.assemble]
    B --> C[Retrieve Memories by Query]
    B --> D[Retrieve Episodes by Query]
    C --> E[_ScoredItem Scoring Loop]
    D --> E
    E --> F[Apply Ranking Strategy]
    F --> G[Token Budget Enforcement]
    G --> H[Context Bundle Response]
    
    E -->|score, kind, text, section| E

Core Data Model

`_ScoredItem` Class

The fundamental unit used throughout the ranking pipeline is the _ScoredItem class, defined in server/services/context.py:

class _ScoredItem:
    """An item (memory or episode) with its computed relevance score."""

    __slots__ = ("score", "kind", "memory_row", "episode_row", "text", "section")

    def __init__(
        self,
        score: float,
        kind: str,
        text: str,
        section: str,
        memory_row: Any = None,
        episode_row: Any = None,
    ) -> None:
        self.score = score
        self.kind = kind
        self.memory_row = memory_row
        self.episode_row = episode_row
        self.text = text
        self.section = section

Sources: server/services/context.py:49-67

Memory Response Model

When context is assembled, memories are returned with full provenance:

MemoryResponse(
    id=m.id,
    subject_id=m.subject_id,
    kind=m.kind,
    content=m.content,
    summary=m.summary,
    confidence=m.confidence,
    valid_from=m.valid_from,
    valid_to=m.valid_to,
    source_episode_ids=m.source_episode_ids or [],
    metadata=m.metadata_,
    status=m.status,
    sensitivity_labels=list(m.sensitivity_labels or []),
    created_at=m.created_at,
    updated_at=m.updated_at,
)

Sources: server/api/timeline.py:1-20

Context Assembly Flow

Endpoint: `POST /v1/context`

Assembles a ranked, token-bounded context bundle from a subject's episodic memory.

sequenceDiagram
    participant Client
    participant API as /v1/context
    participant ContextService
    participant MemoryStore
    participant EpisodeStore

    Client->>API: POST /v1/context {subject_id, query, max_tokens}
    API->>ContextService: assemble(request)
    ContextService->>MemoryStore: search_memories(query)
    MemoryStore-->>ContextService: [MemoryRow...]
    ContextService->>EpisodeStore: search_episodes(query)
    EpisodeStore-->>ContextService: [EpisodeRow...]
    ContextService->>ContextService: score_and_rank(items)
    ContextService->>ContextService: enforce_token_budget(items, max_tokens)
    ContextService-->>API: ContextResponse
    API-->>Client: 200 OK

Token Budget Enforcement

The system enforces a configurable token budget via the STATEWAVE_DEFAULT_MAX_CONTEXT_TOKENS environment variable (default: 4000 tokens). This ensures that:

• Large subjects don't overwhelm LLM context windows
• The most relevant items are prioritized
• Lower-scored items are truncated when budget is exhausted

Sources: README.md:1-100

Ranking Strategies

The ranking system supports multiple strategies that can be applied in combination:

1. Semantic Similarity Ranking

For queries with semantic intent, memories are ranked by vector similarity against the query embedding. This is the default strategy when using kind="semantic" in search requests.

2. Confidence-Based Ranking

Memories include a confidence field (0.0–1.0) that reflects the compiler's certainty. Higher-confidence memories are ranked higher by default.

Sources: server/services/compilers/heuristic.py:1-100

3. Temporal Recency Ranking

For timeline-sensitive queries, items can be weighted by recency (valid_from, created_at). Recent memories receive higher ranking weights.

4. Composite Scoring

The _ScoredItem system enables composite scoring:

final_score = (
    semantic_weight * semantic_score +
    confidence_weight * confidence +
    recency_weight * recency_score
)

Memory Kinds and Their Role in Context

Statewave supports structured memory kinds that inform ranking behavior:

Sources: server/services/compilers/heuristic.py:50-100

Configuration Options

Environment Variables

Sources: README.md:100-150

Helm Chart Configuration

For Kubernetes deployments:

compiler:
  type: llm  # or 'heuristic' for no-LLM mode
embedding:
  provider: litellm  # or 'stub' for demo mode

Sources: helm/statewave/README.md:1-50

API Response Structure

Success Response: `200 OK`

{
  "subject_id": "uuid",
  "query": "user query string",
  "memories": [
    {
      "id": "uuid",
      "subject_id": "uuid",
      "kind": "episode_summary",
      "content": "...",
      "summary": "...",
      "confidence": 0.8,
      "valid_from": "2024-01-15T10:00:00Z",
      "valid_to": "2024-01-20T10:00:00Z",
      "source_episode_ids": ["uuid1", "uuid2"],
      "metadata": {},
      "status": "active",
      "sensitivity_labels": [],
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "episodes": [],
  "total_tokens": 3500,
  "truncated": false
}

Snapshot Integration

Context assembly respects snapshot-restored memories. When memories are restored from snapshots, they carry provenance:

metadata_={
    **mem.metadata_,
    "restored_from_snapshot": str(snapshot_id),
}

Sources: server/services/snapshots.py:1-50

Memory Evolution and Context

The memory evolution system tracks superseding relationships:

class MemoryEvolutionResponse(BaseModel):
    memory_id: str
    status: str
    created_at: str
    superseding_memory: Optional[MemoryRelation]
    superseded_memories: list[MemoryRelation]
    sibling_memories: list[MemoryRelation]
    source_episode_count: int

When assembling context, superseded memories may be excluded or marked, ensuring agents see the most current information.

Sources: server/api/admin.py:1-100

Evaluation and Testing

The scripts/eval/eval_docs_support.py module provides evaluation patterns for context quality:

Question(
    task="How does context ranking work?",
    expected_doc_paths=["architecture/ranking.md"],
    expected_terms=["ranking", "score"],
)

This validates that the ranking system correctly surfaces relevant memories for queries.

Sources: scripts/eval/eval_docs_support.py:1-50

Best Practices

1. Set Appropriate Token Budgets: Balance context richness against LLM limits. Start with 4000 and adjust based on model context window.

1. Use Semantic Search for Complex Queries: When users ask complex questions, semantic similarity ranking outperforms keyword matching.

1. Leverage Memory Kinds: Structure memories with appropriate kinds to enable kind-filtered context retrieval.

1. Monitor Confidence Scores: Low-confidence memories may indicate compilation issues or ambiguous data.

1. Snapshot Before Major Changes: Use snapshots to preserve context state before bulk operations.

Related Endpoints

Sources: README.md:50-80

Related Pages

Related topics: System Architecture

Compilation Services

Compilation Services transform raw episodes into structured memories within Statewave. This process extracts meaningful information from conversation events, resolves conflicts between overlapping facts, and produces durable knowledge representations that agents can retrieve during context assembly.

Overview

Statewave's compilation pipeline operates as a multi-stage process that converts incoming episode data into memory entities. The system supports two distinct compilation modes — heuristic and LLM — allowing deployments to choose between performance and intelligence based on infrastructure constraints.

graph TD
    A[Episode Ingest] --> B{Compilation Mode}
    B -->|Heuristic| C[Heuristic Compiler]
    B -->|LLM| D[LLM Compiler]
    C --> E[Memory Rows]
    D --> E
    E --> F[Conflict Resolution]
    F --> G[Finalized Memories]
    
    H[Context Assembly] --> I[Memory Retrieval]
    G --> I

Compilation Modes

Statewave ships with two compiler implementations, each suited to different operational contexts.

Heuristic Compiler

The heuristic compiler performs rule-based extraction without external AI dependencies. It analyzes episode text using pattern matching and natural language heuristics to identify structured facts.

Supported Memory Kinds:

The heuristic compiler processes each episode independently, extracting profile facts through pattern recognition and generating episode summaries through text truncation and normalization.

LLM Compiler

The LLM compiler leverages large language models to perform semantic understanding of episodes. This mode produces higher-quality memories with better contextual awareness but requires external LLM infrastructure.

Key Capabilities:

• Multi-episode summarization across conversation turns
• Inference of implicit facts not explicitly stated
• Better handling of ambiguous or complex dialogue
• Cross-episode fact consolidation

Temporal Anchoring

Every memory requires a temporal anchor to support time-bounded queries and historical reasoning. The compilation system determines validity windows using a priority cascade.

graph LR
    A[Temporal Anchor Priority] --> B[payload.event_time]
    B --> C[payload.messages[0].timestamp]
    C --> D[Episode created_at]
    
    E[compute_valid_to] --> F[Memory.valid_from]
    F --> G[Memory.valid_to]

Anchor Resolution Order:

1. Explicit event_time in episode payload (connector replay scenarios)
2. First message timestamp in chat-shaped payloads
3. Episode creation timestamp (fallback)

The valid_to date derives from the memory kind's configured TTL (time-to-live), ensuring automatic expiration of transient information.

Conflict Resolution

When multiple episodes produce overlapping memories, the conflict resolution service determines which information takes precedence.

graph TD
    A[New Memory] --> B{Same Subject?}
    B -->|No| C[Insert Directly]
    B -->|Yes| D{Overlapping Time Range?}
    D -->|No| E[Insert Directly]
    D -->|Yes| F{Conflicting Content?}
    F -->|No| G[Insert as Sibling]
    F -->|Yes| H[Apply Resolution Strategy]
    
    H --> I{Strategy: Supersede}
    H --> J{Strategy: Merge}
    H --> K{Strategy: Retain Both}
    
    I --> L[Mark Older as Superseded]
    J --> M[Combine Content]
    K --> N[Link as Alternatives]

Resolution Strategies:

Compilation Job Management

Long-running compilation tasks are managed through an asynchronous job system that prevents API timeouts and supports retry logic.

graph TD
    A[POST /v1/memories/compile] --> B{Currently Compiling?}
    B -->|Yes| C[Return 409 Conflict]
    B -->|No| D[Queue Job]
    D --> E[Job Created]
    E --> F[Background Processing]
    F --> G{Success?}
    G -->|Yes| H[Memories Created]
    G -->|No| I{Retryable?}
    I -->|Yes| J[Retry with Backoff]
    I -->|No| K[Mark Failed]
    J --> F

Job States:

• pending — Queued for processing
• running — Actively compiling
• completed — Successfully finished
• failed — Unrecoverable error
• cancelled — Manually aborted

Data Models

Episode to Memory Flow

EpisodeRow
├── id: UUID
├── subject_id: UUID
├── source: str (e.g., "mcp-server", "github", "statewave-docs")
├── type: str (e.g., "conversation", "doc_section", "issue")
├── payload: dict
│   ├── title: str
│   ├── text: str
│   ├── messages: list[dict]
│   └── ...
├── metadata_: dict
├── provenance: dict
│   └── content_hash: str
└── created_at: datetime

         ↓ Compilation

MemoryRow
├── id: UUID
├── subject_id: UUID
├── kind: str (e.g., "episode_summary", "profile_fact")
├── content: str
├── summary: str
├── confidence: float (0.0 - 1.0)
├── valid_from: datetime
├── valid_to: datetime
├── source_episode_ids: list[UUID]
├── metadata_: dict
├── status: str ("active", "superseded", "redacted")
├── sensitivity_labels: list[str]
├── embedding: vector (optional)
└── created_at, updated_at: datetime

Configuration

Environment Variables

Helm Chart Configuration

Idempotency

Compilation is designed to be idempotent. Re-running compilation on episodes that have already been compiled will not create duplicate memories. The system tracks source_episode_ids to prevent reprocessing and uses content hashing in provenance metadata to detect unchanged source material.

This design supports:

• Safe re-compilation after configuration changes
• Incremental updates from connector replay
• Bootstrap and refresh workflows

API Integration

Compilation is triggered through the REST API:

POST /v1/memories/compile

The endpoint accepts a subject_id and initiates asynchronous processing. Polling the job status or receiving webhooks (if configured) provides completion feedback.

Request Example:

{
  "subject_id": "550e8400-e29b-41d4-a716-446655440000",
  "force": false
}

Response:

{
  "status": "queued",
  "job_id": "660e8400-e29b-41d4-a716-446655440001"
}

Related Pages

Related topics: Context Assembly & Ranking

Embedding Services

Embedding Services provide semantic vector representations for memories and episodes in Statewave, enabling similarity-based search, context ranking, and retrieval-augmented generation workflows.

Overview

The embedding layer is a pluggable component that converts textual content into high-dimensional vector embeddings. These vectors power the semantic search capabilities of the /v1/memories/search endpoint and the relevance scoring in context assembly (POST /v1/context).

Statewave supports two embedding providers:

Sources: helm/statewave/README.md

Architecture

graph TD
    subgraph "Embedding Services Layer"
        LLM[LiteLLM Embeddings<br/>litellm.py]
        STUB[Stub Embeddings<br/>stub.py]
        CACHE[Query Cache<br/>query_cache.py]
    end
    
    subgraph "Backfill Operations"
        BF[Backfill Service<br/>backfill.py]
    end
    
    subgraph "Consumers"
        SEARCH[Memory Search<br/>/v1/memories/search]
        CONTEXT[Context Assembly<br/>/v1/context]
        COMPILER[Memory Compiler]
    end
    
    LLM --> CACHE
    STUB --> CACHE
    CACHE --> SEARCH
    CACHE --> CONTEXT
    CACHE --> COMPILER
    BF --> LLM
    BF --> STUB

Configuration

Embedding behavior is controlled via environment variables:

Sources: helm/statewave/README.md

Providers

LiteLLM Provider

The LiteLLM provider (server/services/embeddings/litellm.py) routes embedding requests through the LiteLLM proxy library, which standardizes access to multiple LLM backends including OpenAI, Azure, Cohere, and custom providers.

Key responsibilities:

• Accept text input and return normalized embedding vectors
• Handle API authentication via STATEWAVE_LITELLM_API_KEY
• Support custom base URLs via STATEWAVE_LITELLM_BASE_URL
• Model selection via STATEWAVE_EMBEDDING_MODEL
• Normalize embedding dimensions across providers

Stub Provider

The stub provider (server/services/embeddings/stub.py) returns zero vectors for all inputs. This is useful for:

• Development environments without API access
• Demo deployments where semantic search is not required
• Testing the rest of the system without embedding dependencies

Sources: server/services/embeddings/stub.py

Query Cache

The query cache (server/services/embeddings/query_cache.py) reduces redundant embedding computations by caching the results of previously generated embeddings.

Cache Strategy

graph LR
    A[Embedding Request] --> B{Hit in Cache?}
    B -->|Yes| C[Return Cached Vector]
    B -->|No| D[Compute Embedding]
    D --> E[Store in Cache]
    E --> F[Return Vector]
    C --> F

Cache Behavior

• Cache key is derived from the text content being embedded
• Cached vectors are returned directly on cache hit
• Reduces API calls and latency for repeated queries
• Particularly effective for search queries that repeat across requests

Sources: server/services/embeddings/query_cache.py

Backfill Operations

The backfill service (server/services/embeddings/backfill.py) handles bulk embedding regeneration for existing data.

Use Cases

• Model migration: When switching embedding models, regenerate all existing embeddings
• Corruption recovery: Rebuild embeddings for data with missing or corrupted vectors
• Schema changes: When embedding schema or normalization changes

Backfill Process

graph TD
    A[Start Backfill] --> B[Query Rows Missing Embeddings]
    B --> C{Process Batch}
    C -->|Has More| D[Fetch Batch]
    D --> E[Generate Embeddings]
    E --> F[Update Database]
    F --> C
    C -->|Complete| G[Backfill Complete]

Sources: server/services/embeddings/backfill.py

Integration with Memory System

Embeddings are stored alongside memory records and used for relevance scoring:

graph LR
    subgraph "Memory Row Schema"
        M1[id]
        M2[content]
        M3[embedding]
        M4[source_episode_ids]
    end
    
    subgraph "Usage Flow"
        S[Search Query] --> E[Generate Query Embedding]
        E --> SC[Compute Similarity Scores]
        M3 --> SC
        SC --> R[Ranked Results]
    end

The embedding field in MemoryRow stores the vector representation of memory content, enabling:

1. Semantic similarity search via cosine similarity
2. Context relevance scoring during context assembly
3. Deduplication by detecting high-similarity memory candidates

Sources: server/services/context.py

API Endpoints Using Embeddings

Deployment Considerations

Production Deployment

For production with semantic search enabled:

1. Set STATEWAVE_EMBEDDING_PROVIDER=litellm
2. Configure STATEWAVE_LITELLM_API_KEY with appropriate permissions
3. Optionally specify STATEWAVE_EMBEDDING_MODEL for a specific model
4. For proxy deployments, set STATEWAVE_LITELLM_BASE_URL

Demo Mode

For demos or development without API costs:

1. Set STATEWAVE_EMBEDDING_PROVIDER=stub
2. Full functionality except semantic search (returns zero similarity)

Sources: helm/statewave/README.md

Helm Configuration

embedding:
  provider: litellm  # or "stub" for demo mode
  model: ""          # optional: specify model

Related Services

• Compiler Services: Use embeddings during memory compilation
• Context Assembly: Uses embeddings for relevance scoring
• Memory Search: Primary consumer of embedding similarity
• Snapshots: Preserves embeddings when snapshotting subject state

Sources: server/services/snapshots.py

Related Pages

Related topics: Multi-tenancy & Security, Context Assembly & Ranking

Governance - Receipts & Policy Engine

Overview

The Governance layer in Statewave provides two interrelated mechanisms for operational accountability and data access control:

1. State Assembly Receipts — Immutable audit records that capture exactly which memories and episodes were included in a /v1/context or /v1/handoff response, enabling full traceability of AI-generated context.
2. Policy Engine — A content-addressed bundle system that enforces sensitivity-label-based filtering on memories before they appear in responses, with configurable enforcement modes.

These systems work together to ensure that when a context bundle is assembled for downstream AI consumption, there is a verifiable record of what was included, why it was included, and what policy rules were applied.

Sources: server/schemas/responses.py

Related Pages

Related topics: Governance - Receipts & Policy Engine

Multi-tenancy & Security

Overview

Statewave implements a multi-tenant architecture with comprehensive security controls for enterprise deployments. The system provides query-scoped data isolation, per-tenant policy enforcement, caller identity validation, and distributed rate limiting—all coordinated through a Postgres-backed shared infrastructure.

Architecture

graph TD
    subgraph "API Layer"
        A[Incoming Request] --> B[Tenant Resolution]
        B --> C[Auth Middleware]
        C --> D[Rate Limiter]
        D --> E[Policy Engine]
        E --> F[Business Logic]
    end
    
    subgraph "Security Components"
        C -->|API Key| Auth[Auth Service]
        D -->|Distributed| RL[Rate Limit Store]
        E -->|Bundle Hash| PB[Policy Bundles]
        E -->|caller_id/caller_type| CI[Caller Identity]
    end
    
    subgraph "Tenant Isolation"
        B -->|tenant_id| TI[Tenant Isolation Layer]
        TI -->|query scoping| DB[(Postgres)]
        PB -->|per-tenant| TI
    end

Tenant Resolution

Tenant Header Configuration

Statewave uses a configurable HTTP header for tenant identification. The header name defaults to X-Tenant-ID but can be customized via environment variables.

When STATEWAVE_REQUIRE_TENANT is set to true, any request missing the tenant header receives a 400 Bad Request response. When false, requests without a tenant header are processed with an anonymous tenant context.

Sources: README.md:env-vars (configuration documentation)

Tenant Resolution Flow

sequenceDiagram
    participant C as Client
    participant A as API Server
    participant T as Tenant Resolver
    participant DB as Postgres
    
    C->>A: Request + X-Tenant-ID header
    A->>T: Extract tenant_id
    T->>DB: Lookup tenant config
    DB-->>T: TenantConfigResponse
    T-->>A: Tenant context
    A->>A: Apply tenant-scoped logic

Tenant Configuration API

Configuration Schema

The TenantConfigResponse schema defines the tenant configuration structure:

Configuration Keys

Sources: server/schemas/responses.py:tenant-config-schema (response schema definition)

Admin Endpoints

#### PATCH Request Shape

The PATCH operation performs a merge update with optimistic concurrency control:

# Expected version must match current state
{
    "expected_version": 5,
    "config": {
        "policy_mode": "enforce",
        "receipt_retention_days": 90
    }
}

If expected_version does not match the current database version, the update fails with a 409 Conflict response.

Sources: server/api/admin.py:config-endpoints (admin API implementation)

Authentication & Authorization

API Key Authentication

Statewave supports API key authentication via the Authorization header:

Authorization: Bearer <api_key>

Or via query parameter for specific integration scenarios:

GET /v1/context?api_key=<api_key>

Caller Identity Validation

When require_caller_identity is enabled in tenant config, every context and handoff request must include:

Requests missing these fields receive a 401 Unauthorized response:

{
    "detail": "tenant config requires caller_id and caller_type on every context call"
}

Sources: server/api/handoff.py:identity-validation (identity enforcement)

Rate Limiting

Rate Limit Strategy

Statewave supports two rate limiting backends:

Configuration

Current Limitations

Note: Rate limiting is currently keyed by IP address only, not per-tenant or per-API-key. This is a known limitation in v0.8.0.

Sources: README.md:rate-limiting-limits (documentation of limitations)

Policy Engine

Policy Bundle Structure

Policy bundles are declarative YAML/JSON documents that define filtering rules. Each bundle is:

• Immutable: Once created, content cannot be modified
• Content-addressed: Identified by bundle_hash (SHA-256)
• Per-tenant: Same bundle content can exist independently per tenant

# Example policy bundle
version: 1
rules:
  - id: redact_sensitive
    predicates:
      - kind: label_match
        args:
          label: PII
      - kind: caller_type
        args:
          type: external_agent
    action: redact

Predicate Types

Actions

Policy Modes

Sources: server/db/tables.py:policy-bundle-row (database schema)

Receipts System

Receipt Emission Logic

Receipts record policy decisions for audit and compliance. The emission decision follows a priority cascade:

flowchart TD
    A[Receipt Request] --> B{Global Kill Switch?}
    B -->|Enabled| E[Emit = False]
    B -->|Disabled| C{Bundle Force Off?}
    C -->|Yes| E
    C -->|No| D{Tenant Mode?}
    D -->|always| F[Emit = True]
    D -->|never| E
    D -->|on_request| G{Request Flag?}
    G -->|True| F
    G -->|False| E

Kill Switch

Global environment variable disables all receipt emission:

STATEWAVE_RECEIPTS_DISABLED=true  # or "1", "yes"

Receipt Data Model

Sources: server/services/receipts.py:emission-decision (emission logic)

Multi-Tenant Data Isolation

Query-Scoped Isolation

All database queries include tenant_id in their WHERE clauses. This is enforced at the service layer:

# Example isolation pattern
query = select(MemoryRow).where(
    MemoryRow.tenant_id == tenant_id,
    MemoryRow.subject_id == subject_id
)

Composite Unique Index

Policy bundles use a composite unique index to enforce:

UNIQUE (tenant_id, bundle_hash) NULLS NOT DISTINCT

This allows multiple tenants to install identical policy content while maintaining row-level separation.

Sources: server/db/tables.py:composite-index (index definition)

Security Best Practices

Recommended Configuration

For production deployments:

# Kubernetes/Helm values
auth:
  apiKey: <use-external-secret>
  
database:
  url: <use-external-secret>
  existingSecret: statewave-db
  existingSecretKey: STATEWAVE_DATABASE_URL

# Tenant configuration
policy_mode: enforce
require_caller_identity: true
receipts: always
receipt_retention_days: 90

Secret Management

The Helm chart supports two patterns:

1. Inline secrets: Set via --set for development
2. External secrets: Reference existing secrets (recommended for production)

Sources: helm/statewave/README.md:secret-management (Helm documentation)

Current Limitations

Sources: README.md:current-limitations (version 0.8.0 status)

Doramagic Pitfall Log

Doramagic extracted 6 source-linked risk signals. Review them before installing or handing real data to the project.

1. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | github_repo:1219923941 | https://github.com/smaramwbc/statewave | README/documentation is current enough for a first validation pass.

2. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1219923941 | https://github.com/smaramwbc/statewave | last_activity_observed missing

3. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | github_repo:1219923941 | https://github.com/smaramwbc/statewave | no_demo; severity=medium

4. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | github_repo:1219923941 | https://github.com/smaramwbc/statewave | no_demo; severity=medium

5. Maintenance risk: issue_or_pr_quality=unknown

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1219923941 | https://github.com/smaramwbc/statewave | issue_or_pr_quality=unknown

6. Maintenance risk: release_recency=unknown

• Severity: low
• Finding: release_recency=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1219923941 | https://github.com/smaramwbc/statewave | release_recency=unknown

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using statewave with real data or production workflows.

• policy_bundles: support cross-tenant bundle reuse via composite (tenant_ - github / github_issue
• v0.8.0 - github / github_release
• v0.7.2 - github / github_release
• v0.7.0: Admin Dashboard API - github / github_release
• README/documentation is current enough for a first validation pass. - GitHub / issue