Eve library

OSHUN V1 In-Memory Runtime State Audit

Guide

Revision 1

On this page

Status: Active Owner: OSHUN Engineering Last Updated: March 23, 2026 Related: docs/releases/v1/specs/web-app-admin-v1-prd.md, docs/releases/v1/reports/subsystem-ownership-matrix.md, docs/releases/v1/specs/when-to-call-which-subsystem-guide.md, docs/releases/v1/reports/unified-product-gap-analysis-and-nisaba-integration-report-2026-03-22.md

1. Purpose#

This document is the authoritative V1 audit for V1-ARCH-047: identify quality-critical Oshun-facing services that still keep meaningful runtime state only in process memory.

The governing requirement is docs/releases/v1/specs/web-app-admin-v1-prd.md section 16.4 Durability Requirement, which states that quality-critical in-memory-only runtime state must be moved to durable storage, durable queues, or durable event logs before the platform is production-complete.

2. Scope#

This audit covers the Oshun shell plus the subsystem services that are directly in the V1 execution path for:

  • assistant identity, memory, and conversation continuity
  • real-time assistant session continuity and replay
  • grounding and research support
  • generation workflow control
  • review and approval workflows
  • user-visible notification and preference continuity

Audited services:

  • apps/oshun/bff
  • apps/iris/api
  • services/psyche/orchestrator
  • apps/sophia/search-api
  • apps/sophia/knowledge-graph
  • apps/isis/generation-api
  • apps/isis/workflow-registry
  • apps/isis/output-registry
  • apps/isis/gpu-worker
  • apps/lilith/bff
  • apps/lilith/svc-review
  • apps/lilith/svc-conversation
  • apps/lilith/svc-spiritual-guidance

Out of scope for this audit:

  • request-local algorithm helpers that do not survive the request
  • obviously test-only fixtures
  • frontend component local state
  • low-value counters and transient metrics unless they gate a quality-critical workflow

3. Method#

The audit was performed by inspecting the live service codepaths and excluding purely local algorithm structures. A finding appears here only when the code holds state across requests, sessions, jobs, or workflow steps inside process memory, or when a service exposes an explicit in-memory backend for a quality-critical runtime.

4. Summary#

Service Observed Persistence Posture Audit Summary
apps/oshun/bff Process-local in-memory stores present Notification preferences, read state, digest config, quiet hours, and device tokens are stored in memory.
apps/iris/api Process-local in-memory stores only Assistant memory, conversations, agents, tasks, and knowledge-base state are all held in Map/Set collections.
services/psyche/orchestrator Durable-capable, but memory defaults remain in core state manager Session state and checkpoints default to in-memory stores unless callers wire a durable store.
apps/sophia/search-api No long-lived process-local runtime store identified in audited paths The audited retrieval and citation logic uses request-local maps and sets, not cross-request service state.
apps/sophia/knowledge-graph Service boots with in-memory graph store The standalone service entrypoint uses MemoryGraphStore-backed runtime state for entities and relationships.
apps/isis/generation-api Durable-backed in audited job paths Job state is persisted through PostgreSQL plus BullMQ/Redis-backed queueing.
apps/isis/workflow-registry Dual mode; in-memory backend is still available Workflow and template registry state can be process-local when ISIS_WORKFLOW_REGISTRY_STORAGE=in-memory.
apps/isis/output-registry Durable-backed in audited paths No long-lived process-local registry state was identified in the audited service module.
apps/isis/gpu-worker Process-local operational state atop durable queue Worker-local model caches and callback registries exist, but the durable job source-of-truth lives outside the worker.
apps/lilith/bff Multiple process-local product stores present User memory, preferences, translation lifecycle, review lifecycle, research lifecycle, webhook delivery, and mock generation state are stored in memory.
apps/lilith/svc-review Process-local in-memory stores only Review queues, items, decisions, assignments, escalations, and metrics are all in memory.
apps/lilith/svc-conversation Durable option exists, but memory mode remains active and can be the default/fallback Session state and conversation reliability helpers still have in-memory modes and memory fallbacks.
apps/lilith/svc-spiritual-guidance Process-local in-memory stores only Session history, journey tracking, and conversation memory are stored in memory.

5. Detailed Inventory#

5.1 OSHUN BFF#

Observed process-local runtime state:

  • apps/oshun/bff/src/notifications/preferences-store.ts createNotificationPreferencesStore() keeps per-user notification preferences and revisions in in-memory Map collections.
  • apps/oshun/bff/src/notifications/read-state-store.ts createNotificationReadStateStore() keeps per-user read/unread notification state and revision counters in memory.
  • apps/oshun/bff/src/notifications/digest.ts userDigestConfigs and lastDigestDelivery store digest schedules and last delivery timestamps in memory.
  • apps/oshun/bff/src/notifications/quiet-hours.ts userQuietHours stores per-user quiet-hours configuration in memory.
  • apps/oshun/bff/src/routes/device-tokens.ts tokensByUser stores registered push device tokens in memory, with an inline comment noting that production should use persistent storage.

Audit note:

  • These are user-facing continuity settings. Process restarts currently lose notification state that users would reasonably expect to persist.

5.2 Iris API#

Observed process-local runtime state:

  • apps/iris/api/src/services/memory.service.ts MemoryService keeps assistant memory entries, core blocks, and user indexes in in-memory Map and Set structures.
  • apps/iris/api/src/services/conversation.service.ts ConversationService keeps conversation history and user conversation indexes entirely in memory.
  • apps/iris/api/src/services/agent.service.ts AgentService keeps agents, tasks, user agent indexes, and agent task indexes in memory.
  • apps/iris/api/src/services/knowledge.service.ts KnowledgeService keeps knowledge bases, documents, chunks, and indexes in memory.
  • apps/iris/api/src/routes/health.ts readiness checks still contain TODO placeholders for database and Redis connectivity, which matches the absence of a durable data path in the service layer.

Audit note:

  • Iris is supposed to be the canonical durable assistant memory and identity substrate. In the audited service code, that substrate is not durably backed.

5.3 Psyche Orchestrator#

Observed process-local runtime state:

  • services/psyche/orchestrator/src/orchestrator/session/state.py MemoryStateStore keeps serialized session state in a process-local dictionary.
  • services/psyche/orchestrator/src/orchestrator/session/state.py CheckpointManager defaults to MemoryStateStore() and also keeps checkpoints in a process-local dictionary.
  • services/psyche/orchestrator/src/orchestrator/session/state.py SessionStateManager defaults to MemoryStateStore() and keeps _local_states and checkpoint tasks in process memory.
  • services/psyche/orchestrator/src/orchestrator/caching/cache_config.py development factory helpers explicitly configure cache_backend="memory" and vector_backend="memory".
  • services/psyche/orchestrator/src/orchestrator/caching/semantic_cache.py the semantic cache supports both in-memory cache and in-memory vector-store modes.

Audit note:

  • Redis-backed state storage exists, but the audited session manager does not enforce a durable backend by default. Replay-sensitive session state can still end up process-local.

5.4 Sophia#

apps/sophia/search-api#

Observed posture:

  • The audited citation and retrieval modules use Map and Set structures as request-local algorithm helpers.
  • No long-lived, cross-request, process-local service store was identified in the audited search API paths.

Audit note:

  • Search API remains in scope for later research-job durability work, but this audit did not find the same class of restart-lost runtime state here that was present in Iris, Lilith, or Oshun BFF.

apps/sophia/knowledge-graph#

Observed process-local runtime state:

  • apps/sophia/knowledge-graph/src/entities/entity-service.ts MemoryGraphStore is an explicit in-memory graph store for nodes and relationships.
  • apps/sophia/knowledge-graph/src/main.ts KnowledgeGraphService boots the standalone service on top of a CombinedMemoryStore, which extends MemoryGraphStore.

Audit note:

  • The standalone knowledge-graph service currently uses an in-memory graph store in its primary runtime entrypoint, not only in tests.

5.5 Isis#

apps/isis/generation-api#

Observed posture:

  • apps/isis/generation-api/src/services/job.service.ts is explicitly described as job management with PostgreSQL persistence.
  • The same service integrates BullMQ and Redis-backed queueing for job dispatch and queue health.
  • The audited job service did not expose a long-lived in-memory job store.

Audit note:

  • This is a positive control in the audit. Generation job state already has a durable foundation in the audited primary path.

apps/isis/workflow-registry#

Observed process-local runtime state:

  • apps/isis/workflow-registry/src/services/workflow.service.ts defines StorageBackend = 'postgres' | 'in-memory'.
  • The service keeps workflow records, versions, deleted-version state, templates, and taxonomy backfill provenance in in-memory maps when the storage backend resolves to in-memory.
  • resolveStorageBackend() allows ISIS_WORKFLOW_REGISTRY_STORAGE=in-memory.

Audit note:

  • The registry has a durable path, but the in-memory backend still exists for a quality-critical control-plane service and remains selectable by runtime configuration.

apps/isis/output-registry#

Observed posture:

  • The audited service module did not expose a long-lived process-local output registry store.
  • The identified Map and Set structures were local graph-building and query helpers rather than cross-request service state.

apps/isis/gpu-worker#

Observed process-local runtime state:

  • apps/isis/gpu-worker/src/workers/gpu-worker.ts keeps event callback registries and loaded-model metadata in memory.

Audit note:

  • This is worker-local operational state on top of a durable BullMQ queue. The durable source-of-truth for job progression is not the worker process itself.

5.6 Lilith#

apps/lilith/svc-review#

Observed process-local runtime state:

  • apps/lilith/svc-review/src/app.ts keeps review queues, review items, reviewer profiles, decisions, SLAs, metrics, assignments, and escalations in process-local Map collections.

Audit note:

  • This service is directly in scope for review-state durability. The audited implementation is memory-only.

apps/lilith/svc-conversation#

Observed process-local runtime state:

  • apps/lilith/svc-conversation/src/session/memory-store.ts MemorySessionStore keeps websocket sessions, user-session indexes, server-session indexes, and subscribers in memory.
  • apps/lilith/svc-conversation/src/session/index.ts createSessionStoreFromEnv() still defaults to memory mode and falls back to memory when Redis configuration is missing.
  • apps/lilith/svc-conversation/src/app.ts the service also keeps conversations, threads, messages, connected clients, idempotency state, replay cache, and rate-limit buckets in memory.

Audit note:

  • Durable session storage exists conceptually, but memory mode remains active in the service's production-shaped runtime surface.

apps/lilith/svc-spiritual-guidance#

Observed process-local runtime state:

  • apps/lilith/svc-spiritual-guidance/src/conversation-memory.ts keeps conversation messages, session metadata, user journey state, and memory index entries in memory, with an inline note that production should replace these stores with an adapter.

Audit note:

  • This is assistant continuity and user-journey state, not a request-local cache.

apps/lilith/bff#

Observed process-local runtime state:

  • apps/lilith/bff/src/utils/long-term-memory.ts keeps user memory, conversation memory, and indexes in memory.
  • apps/lilith/bff/src/utils/user-preferences.ts keeps user preferences and preference history in memory.
  • apps/lilith/bff/src/utils/translation-service.ts keeps translation records, translation history, and indexes in memory.
  • apps/lilith/bff/src/utils/translation-review-workflow.ts keeps review records, workflow status history, and user review indexes in memory.
  • apps/lilith/bff/src/utils/translation-open-research.ts keeps research submissions, datasets, publication state, and researcher indexes in memory.
  • apps/lilith/bff/src/synthesis-engine.ts keeps queued generation jobs in pendingJobs.
  • apps/lilith/bff/src/api/webhooks/webhook-service.ts the default storage implementation is InMemoryWebhookStorage, and the service also keeps a process-local delivery queue.

Audit note:

  • The Lilith BFF still contains multiple product-state implementations that behave like prototypes rather than durable service adapters.

6. Cross-Cutting Patterns#

The audit found four recurring patterns:

  1. Canonical services implemented as in-memory prototypes. apps/iris/api, apps/lilith/svc-review, apps/lilith/svc-spiritual-guidance, and the Sophia knowledge-graph service are the clearest examples.
  2. Durable adapters exist, but memory remains the default or silent fallback. services/psyche/orchestrator, apps/lilith/svc-conversation, and apps/isis/workflow-registry fit this pattern.
  3. User-visible shell state is still restart-sensitive. Oshun notification settings and device tokens are stored in memory inside the shell BFF.
  4. Isis job execution is materially further along than the surrounding stack. The audited generation job path already uses durable persistence and queueing.

7. What This Audit Enables Next#

This audit intentionally stops at inventory. The next V1 tasks should use this document to:

  • classify each finding as acceptable cache, transitional prototype, or release blocker
  • define concrete replacement plans for the release-blocking findings
  • durably persist review, approval, assistant memory, generation, research, and persona-release state through the subsystem boundaries defined in the V1 ownership matrix