Skip to main content

Memory System

The memory system gives agents persistent context across workflow steps and across runs. It supports four memory types — working, episodic, semantic, and procedural — each serving a different retrieval pattern. Memory entries are scored by salience to keep the agent's context window focused on relevant information.

Source: internal/memory/*

Memory Types​

  • Working: in-run transient context attached to workflow state.
  • Episodic: per-run event history (memory_episodes).
  • Semantic: cross-run facts with embeddings (memory_facts).
  • Procedural: reusable procedures/playbooks (memory_procedures).

Memory Flow​

Salience Scoring​

Salience reranks semantic facts before prompt assembly.

Inputs:

  • Relevance score from retrieval query similarity.
  • Recency decay from last update/retrieval timestamps.
  • Confidence metadata from extraction/verification.
  • Usage frequency (retrieval count).
  • Freshness (when temporal decay is enabled).

Config:

  • CRUVERO_SALIENCE_ENABLED
  • CRUVERO_MEMORY_SALIENCE_RELEVANCE
  • CRUVERO_MEMORY_SALIENCE_RECENCY
  • CRUVERO_MEMORY_SALIENCE_CONFIDENCE
  • CRUVERO_MEMORY_SALIENCE_USAGE
  • CRUVERO_MEMORY_SALIENCE_FRESHNESS
  • CRUVERO_MEMORY_SALIENCE_HALFLIFE

Operationally, QueryFacts retrieves candidates first, then applies weighted salience reranking.

Context Budget​

Context budget constrains how much memory/tool context is assembled per step.

Behavior:

  • Enabled by CRUVERO_CONTEXT_BUDGET_ENABLED.
  • Uses a global budget (CRUVERO_CONTEXT_BUDGET_TOKENS) and system allocation (CRUVERO_CONTEXT_SYSTEM_TOKENS).
  • Allocates budget across user prompt, memory sections, tool schemas, and safety/system instructions.
  • Drops or truncates lower-salience sections first when the budget is exceeded.

This keeps prompt size bounded while preserving high-signal context.

Interference Detection​

Interference detection flags conflicting memory facts during assembly.

Behavior:

  • Detects contradictory facts (e.g., negated facts with same key/topic).
  • Emits conflict warnings in context metadata and telemetry.
  • Allows the agent to reflect or request verification before acting.

Interference does not automatically delete facts; it surfaces uncertainty for safer decisions.

Temporal Decay​

Temporal decay models staleness for semantic facts.

Behavior:

  • Freshness decays over time based on per-fact/profile half-life.
  • Facts can be marked as stale/needs-refresh.
  • Verification updates (last_verified_at) restore freshness.
  • Decay influences salience and can trigger metacognitive reflection paths.

Config and schema hooks:

  • CRUVERO_TEMPORAL_REASONING_ENABLED (runtime coupling)
  • 0019_memory_decay columns (freshness_half_life, last_verified_at, fact_type)

Storage Backends​

  • Postgres: default store for episodic/semantic/procedural memory.
  • Redis/Dragonfly: optional episodic store (CRUVERO_MEMORY_EPISODIC_STORE=redis) with TTL.

Tools​

  • memory_write: persist facts/procedures.
  • memory_read: query memory.

Queries​

cmd/memory-query supports:

  • episodic lookups by run and type
  • semantic query by namespace + text
  • procedural retrieval by name