Operations

Bootstrap

Build produces ai-memory.svc; run it with -f .ai-memory.yaml. Ports and TLS are chassis-managed. The entity schema (sessions, messages, episodes, facts, events, exclusions) is embedded and applied per tenant through the data layer.

ai-memory.svc -f .ai-memory.yaml

The datastore selects its backend from the DSN — sqlite:// for development, postgres:// for production. With no DSN, an in-memory store is used (dev only).

Configuration

The memory service config controls retention, consolidation, recall ranking, governance, and which models it uses. Every key is per-tenant overridable.

retention:
  raw_ttl: 30d              # raw messages of closed sessions, once episodes exist
  episode_ttl: 365d
  fact_history_ttl: 730d    # superseded (historical) facts
  decay: importance_weighted
consolidation:
  t0_embed: micro_batch     # near-real-time embedding/indexing
  t1_on_session_close: true # summarize + extract episodes/facts on close
  t2_schedule: "0 2 * * *"  # nightly deep pass (merge facts, decay importance)
  supersession_auto_threshold: 0.8   # below this, a contradiction is flagged, not auto-applied
recall:
  default_budget_tokens: 2048
  weights: { relevance: 0.5, recency: 0.3, importance: 0.2 }
governance:
  deletion: cascade
  sensitive_default: suppressed
  sensitive_keywords: [ssn, salary]
models:
  embed: gateway:embed-default        # via the AI gateway
  consolidate: gateway:slm-default
scope:
  claim_secret: ${SCOPE_CLAIM_SECRET} # HMAC secret the edge signs scope claims with

Model references of the form gateway:<model> resolve through the AI gateway. Leave scope.claim_secret empty to disable scope-claim enforcement in development.

Consolidation

Consolidation runs in the background off the write path. Trigger it on demand for a session or scope:

# extract episodes/facts from a just-closed session
POST /admin/v1/consolidate   {"tier":"t1","session_id":"…"}
# run importance decay for a scope
POST /admin/v1/consolidate   {"tier":"t2","scope":"user:u-42"}

POST /admin/v1/maintenance runs one full decay + retention cycle across all active scopes; the background scheduler runs the same cycle on the t2_schedule/interval.

Retention and forgetting

Two independent paths:

• Retention ages out raw messages of closed sessions past raw_ttl — but only once their episodes have been durably extracted, so nothing salient is lost. Historical (superseded) facts are reaped past fact_history_ttl.
• Right-to-forget (POST /v1/forget) cascade-deletes by session, subject, or fact, propagates through provenance, deindexes, audits, and returns a deletion receipt. If propagation can’t complete, it returns 500 with a partial receipt rather than reporting a false success.

Health and observability

• GET /admin/v1/health — liveness/readiness.
• GET /admin/v1/stats — the persistence backend and whether semantic recall, consolidation, and scope-claim enforcement are enabled.

Dependencies

data (durable storage; the source of truth), the AI gateway (embedding + consolidation models), config and meta (config + schema), IAM (JWT/CPET), and the audit service for governance actions. RAG is a peer, not a dependency — it owns document knowledge; Memory owns interaction memory.