Memory System

Spectral’s agent draws on a hierarchical knowledgebase that is autonomously defined and managed. Knowledge flows upward through compounding — each tier boundary filters, generalizes, and optionally sanitizes observations before promotion.

This page covers the universal lifecycle vocabulary, the parameterization the World Agent applies, the records-vs-memory load-bearing invariant, and the workshop discipline at the tool → memory boundary.

Tier architecture

The universal lifecycle vocabulary is interaction / session / persistent per ADR-058 D1 — tiers carry durability, not domain. Each agent parameterizes the universal lifecycle with its own anchor entity and its own session-end rules; the agent-domain event scopes that accumulate observations within a session are not tiers.

See agent memory primitives for the agent-general template; the World Agent’s parameterization lives at World Agent — Memory architecture.

Tier	Durability	World Agent parameterization
Interaction	Per LLM-turn / per chat thread	Per-interaction scope.
Session	Per session boundary (chat session, operator session, customer session)	Per-session scope (operator or customer session per ADR-081 D3).
Persistent	Durable across sessions	Anchored to (org_id, domain_id); durable across world-model versions with world_model_version carried as contextual provenance.

Interaction tier

Scope: A single LLM interaction or chat thread. Carries in-flight task parameters, tool-call arguments, the user’s current intent.

Lifecycle: Created during the interaction. At interaction completion, a compounding step evaluates whether any observations warrant promotion to the session tier. All unpromoted observations are dropped.

Session tier

Scope: A coherent session — for the World Agent, an operator-mode or customer-mode chat session. The session is the agent-domain event scope; the memory tier is universal.

Lifecycle: Observations promoted from the interaction tier accumulate here for the duration of the session. At session completion, compounding evaluates promotion to the persistent tier. All unpromoted observations are dropped.

Persistent tier

Scope: Durable across sessions. World Agent persistent memory anchors to (org_id, domain_id).

Lifecycle: Observations promoted from the session tier persist here. Periodic compounding evaluates observations for retention. Persistent-tier rows are subject to time decay unless marked decay-exempt or load-bearing for an action.

The World Agent’s persistent-tier typology distribution is semantic + procedural about the world’s domain (exploration patterns, code-generation patterns, discovery observations). Persistent-episodic is not produced by current agent design (the schema retains episodic in the typology enum so the cell exists; doctrine + repository wrapper enforce the distribution).

Records are not memory

A load-bearing invariant per ADR-058 D14 and the broader records-vs-memory boundary. Records hold what the system did; memory holds what the agent reasoned about it. Records are produced by system functions (decision-execution handlers and audit-chain writers). Agents reason over records and memorize the reasoning, not the records themselves.

The canonical record families are:

• Decision records and audit-chain entries (Primitives — Audit chain) — produced by the platform pillar per ADR-076 D3 on every /decide invocation. Audit-grade; agent memory does not duplicate.
• Override-pattern signals (Glossary — Override-pattern signal) — produced by the platform pillar from customer-flagged decisions on the Customer Dashboard. Aggregated and surfaced to operators; the World Agent memorizes reasoning about the aggregations, not the raw signal rows.
• Operator-action audit rows — WorldAuthoringAudit, ApprovalDecision — produced by the operator’s mutate-API surface on the Operations app. Records, not memory.

The bridge between records and memory is provenance, not duplication. When an agent forms value-added conclusions about a record, the resulting observation may be written to memory tiers via the agent’s memory gateway; the gateway stores a cross-reference back to the source record via (source_type, source_ref) in <agent>_agent_memory_corroborations. The gateway rejects records-verbatim memory writes at the write boundary: memory rows whose body fields equal the source record’s fields with no value-added observation are not accepted.

This is a specific instance of the workshop discipline at the tool → memory boundary (per agent-memory-primitives primitive 13: reference-only invariants).

For the records side:

• Entity schemas: domain-model for the record families.
• Retention: retention registry catalogues the platform-side decision-execution records and the worlds-side operator-action audit families.

Compounding and decay

Compounding is the evaluation process that runs at each tier boundary. It performs two functions:

1. Filtering — is this observation valuable enough to keep at the broader scope?
2. Generalizing — can it be stated in a way that’s useful beyond the immediate context?

Unpromoted observations at the interaction and session tiers are dropped after compounding. This prevents memory accumulation from unbounded growth while ensuring that valuable learnings are preserved at the appropriate scope. Deduplication runs against existing memories at the target tier to prevent redundant observations from accumulating.

Persistent-tier observations are subject to time decay. Decay is not simply a relevance weighting mechanism — it is a forcing function for disposition. Every persistent-tier observation is on a clock that demands: confirm this or let it go.

Two mechanisms operate:

• Continuous evaluation on retrieval: When the retrieval system queries memories, time decay is a factor in relevance scoring. Older, undisposed observations carry progressively less weight in retrieval results.
• Periodic cleanup: A separate periodic process identifies observations that have fully decayed — reached the end of their decay window without disposition. These observations are archived, not deleted — they remain available for auditability but are no longer returned by the retrieval system.

Concurrent compounding isolation

Two compounding evaluations may target the same persistent-tier slot when concurrent flows reach the same tier boundary in overlapping windows. The invariant is that the resulting memory state is deterministic under concurrent races — never a torn write, never a duplicated promotion, never a lost decay-exemption flag. Memory write paths run under serializable (SERIALIZABLE) transaction isolation, backstopped by a partial unique index on the target slot, so the second writer either observes the first writer’s commit (and short-circuits the duplicate) or fails the unique constraint and retries against the post-commit state.

Decay exemption

Individual observations can be marked as decay-exempt by the compounding engine (autonomously, when confidence is high) or by an operator. Decay-exempt status means the observation has indefinite lifespan at the persistent tier without needing further confirmation. Action-linked memory at any tier is retained regardless — the audit posture is action-linkage-based per ADR-058 D6, not blanket-tier-based.

Memory format

Each observation uses a structured envelope around a natural language body:

Structured envelope (enables retrieval and deduplication):

• Agent type tags
• Problem category
• Tier metadata (origin tier, promotion history)
• Provenance cross-references (records the observation reasons about)

Natural language body (carries the actual insight):

• The observation itself
• Context that informed it
• Conditions under which it applies

The structure enables efficient, relevance-based retrieval. The natural language carries insights that are difficult to formalize into rigid schemas.

Retrieval

At the start of each interaction, an agent retrieves relevant memories from all applicable tiers — interaction (currently empty), session (the current session’s accumulated observations), and persistent (this anchor entity’s persistent memory).

Retrieval uses three parallel signals merged via Reciprocal Rank Fusion (RRF):

• Structured envelope matching — filter by agent type, problem category, provenance reference. Fast, precise, catches exact pattern matches.
• Semantic search via pgvector — embed query against memory embeddings. Catches relevant memories with different envelope tags but similar patterns.
• Time decay scoring — exponential decay with confirmation/frequency boost.

RRF normalizes all signals to a common scale (k=60) without requiring tuned weights. More specific tiers weighted higher. Supabase pgvector extension enabled natively.

Either signal alone misses relevant results — structured matching misses analogous patterns, semantic search misses exact matches. RRF combines both naturally.

Workshop discipline at the tool → memory boundary

A cross-agent invariant captured in agent memory primitives: agent memory is a workshop, not a canonical-content cache. Tool-output paths that contain canonical content (rule body, audit-chain entry, customer PII) do not round-trip into memory rows verbatim. Sanitization happens at the memory-write boundary; the repository gateway enforces typology-driven classification; the trigram trigger backstops doctrine drift. Tool calls that fetch canonical content for reasoning are fresh-read each time, not cached in memory.

Rule interpretation lives with the rule corpus and its tools. The World Agent’s memory has no promotion path to rule storage; rule candidates are proposed through the Evolution Loop per Evolution Loop.

What’s next

• Agent Architecture — the World Agent topology and how it uses the memory tiers this page describes.
• Agent Memory Primitives — the canonical schema and gateway behavior backing the tiered memory.
• World Agent — Memory architecture — World Agent’s parameterization of the universal lifecycle.
• Decision Execution — the audit-chain records that the World Agent reasons over via provenance, never duplicates into memory.