Restormel State (agent memory)

@restormel/state models append-only agent memory, deterministic projections, and correlation with context packs and observability. It publishes on platform-v* (not graph-v*): suite-wide platform, often used together with graph-aware retrieval and @restormel/context-packs.

Restormel Graph docs focus on the canvas (graph-v*) and optional reasoning extensions (platform-v*). Restormel State is also on the platform-v* train—it is not part of Contract v0 or @restormel/graph-core. We document it here because many integrators (for example SOPHIA) combine retrieval → context packs → multi-pass LLM → graph UI; State closes the loop on what the agent remembers and how that lines up with each run.

What it is

@restormel/state provides:

  • An append-only StateEvent stream (upsert / remove / pin / summarize-compact / scope clear).
  • projectWorkingMemory(events, policy) — pure fold plus per-scope caps (cells and approximate tokens); unpinned cells drop before pinned when over budget.
  • Correlation helpers — attach restormel_correlation onto ContextPackRetrievalInput (from @restormel/context-packs) and emit small structs for logs or traces next to run_id (alongside @restormel/observability).
  • SOPHIA / Stoa: dialogue-specific event builders are not in the npm package — copy the reference module from state-sophia-integration.md into SOPHIA.

What it is not

  • Not a vector database, embedding store, or RAG product.
  • Not a workflow or checkpoint engine (for example LangGraph-style execution state).
  • Not a hosted memory service: you persist events (Firestore, Postgres, append-only log); this package only projects them.

How it fits next to context packs

Reasoning extensions already points at @restormel/context-packs, which turns a retrieval-shaped payload into pass-specific LLM blocks. State answers a different question: over time, what memory cells were added, summarized, or removed—and which events explain the prompt you built for this run_id? Use attachCorrelationToRetrievalInput so support and operators can jump from a bad answer to both retrieval correlation and memory tail ids.

Canonical documentation (repo)

Maintainer-facing source of truth and SOPHIA hook checklist (Stoa +server.ts, escalation) live in the monorepo:

Publish train

State publishes with other platform packages when maintainers push platform-v*. Order on the train: @restormel/contracts → @restormel/context-packs → @restormel/state (depends on context-packs for correlation types) → @restormel/observability → @restormel/graph-reasoning-extensions. Workflow: publish-restormel-platform.yml.

← Docs home · Reasoning extensions & contracts · How it fits together