# OSHUN V1 In-Memory Runtime State Audit

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
