Memory System

Multi-layer episodic memory with consolidation, semantic ontology, and unified search.

Overview

Animus provides a multi-component memory system designed for agents that accumulate knowledge over time. Memory is not a single store — it's a structured architecture with different systems handling different kinds of information.

• Episodic Memory (MemoryStore) — layered observations with configurable time horizons and perspective tracking
• Semantic Ontology (OntologyStore) — structured entity/property memory with evidence linkage and mutation logging
• Raw Artifacts (MemoryFileStore) — verbatim documents, transcripts, and notes stored as-is
• Unified Search (MemorySearch) — cross-domain query over all memory components
• Agent Diary — encrypted private reflections (covered in its own section)

Episodic Memory Layers

Observations are stored in configurable layers, each covering a different time horizon. A typical setup uses working (immediate context), short-term (recent days), and long-term (accumulated knowledge), but layers are fully configurable.

Each observation carries:

• agent_id — first-class property, not derived from layer. Ensures continuity when layers are reorganized.
• lifecycle state — new, current, or deprecated. Observations age through these states via consolidation.
• next_review_at_ms — explicit per-observation review cadence. The scheduler checks this timestamp rather than computing intervals.
• weight — relative importance within the layer. Used for ranking and budget allocation.

Each layer maintains a perspective triad — three text summaries that evolve over time:

Retrospective

The past view — what the layer has accumulated and how understanding has changed.

Current perspective

The present view — active beliefs and working knowledge.

Future perspective

The forward view — expectations, plans, and open questions.

Perspectives are revised during consolidation runs. They give the agent a sense of temporal orientation — not just what it knows, but how its understanding has evolved.

Semantic Ontology

Separate from episodic observations, the ontology stores structured knowledge about entities and their properties. Root categories are predefined:

• persons, concepts, procedures, events, locations, organizations, projects

Properties are evidence-driven — each property value is linked to an observation that produced it. Mutation logging tracks every change, creating an audit trail of how the agent's understanding evolved.

The admin UI provides a browsable ontology explorer for inspecting entities, their properties, and the evidence chain behind each value.

Memory Files

Raw memory artifacts — documents, transcripts, notes — are stored verbatim via MemoryFileStore. Content mutability is policy-driven per file (controlled by content_mutable flag). These are standalone storage, not part of consolidation distillation.

Unified Search

A single search interface queries across all memory domains:

• Episodic observations
• Ontology entities and properties
• Memory files
• Diary entries

Backed by SQLite FTS5 for ranking. Domain toggles let you enable or disable specific sources in the admin UI and API. The architecture supports swapping in embedding-based search later without changing the API surface.

Active Memory

When an agent activates (receives a message or event), the ActiveMemoryProvider constructs a context block injected into the system prompt. This includes:

• Temporal grounding — current date, time, timezone, time since last session (always present)
• Episodic highlights — top-weighted observations per layer, with per-layer budgets
• Diary presence — last 3 entry titles (not content — diary is encrypted)
• Ontology context — tag-matched entities relevant to the current session