Memory System Architecture

Overview

The memory system provides 7 distinct memory types inspired by MIRIX (arXiv:2507.07957):

1. Core - Agent identity and constraints
2. Episodic - Task experiences
3. Semantic - Domain knowledge
4. Procedural - Skills and workflows
5. Resource - External references
6. Vault - Cross-session persistence
7. Belief - Hindsight belief memory for reasoning agents (arXiv:2512.12818)

This architecture is inspired by MIRIX (arXiv:2507.07957), which reports +35% accuracy vs baseline RAG and 99.9% storage reduction in paper benchmarks. These are research metrics from the paper, not measured on this system.

Core Interface: IContextMemoryBackend

Hybrid persistence layer with SQLite + Markdown export.

interface IContextMemoryBackend {
  set<T>(key: string, value: T, metadata?: MemoryMetadata): Promise<void>;
  get<T>(key: string): Promise<T | undefined>;
  has(key: string): Promise<boolean>;
  delete(key: string): Promise<boolean>;
  clear(): Promise<void>;
  keys(): AsyncIterable<string>;
  entries<T>(): AsyncIterable<[string, T]>;
  size(): Promise<number>;
}

type MemoryImportance = 'critical' | 'high' | 'medium' | 'low';
// High-importance memories are also written to Markdown files

Importance-Based Persistence

Typed Memory System (ITypedMemory)

MIRIX-style 7-type memory with specialized sub-interfaces.

interface ITypedMemory {
  readonly core: ICoreMemory; // Agent identity, constraints
  readonly episodic: IEpisodicMemory; // Task experiences
  readonly semantic: ISemanticMemory; // Domain knowledge
  readonly procedural: IProceduralMemory; // Skills, workflows
  readonly resource: IResourceMemory; // External references
  readonly vault: IKnowledgeVault; // Persistent cross-session storage

  queryByType(type: MemoryType, query: string): Promise<Result<TypedMemoryEntry[], MemoryError>>;
  filterByRelevance(role: AgentRole): Promise<Result<TypedMemoryEntry[], MemoryError>>;
  getStats(): Promise<Result<TypedMemoryStats, MemoryError>>;
  pruneExpired(): Promise<Result<TypedMemoryPruneResult, MemoryError>>;
}

type MemoryType = 'core' | 'episodic' | 'semantic' | 'procedural' | 'resource' | 'vault';

Memory Type Details

Routing Memory (IRoutingMemory)

Bridges MobiMem and routing systems for learning-based model selection. The supported contract is the synchronous IRoutingMemory in context/routing-memory.ts, implemented by RoutingMemory and re-exported through the CLI adapters entry. The asynchronous Result-returning contract from #238 was never implemented by shipped code and is removed in 10.0 (#5715).

import type { IRoutingMemory } from 'nexus-agents';

function recordModelPerformance(memory: IRoutingMemory): void {
  memory.storePreference('claude', 'code', {
    avgQuality: 0.9,
    successRate: 1,
    avgLatencyMs: 1000,
    avgTokens: 500,
    observations: 1,
  });
}

Integration Points

• Model preferences: Store performance and retrieve preferences by task type
• MobiMem Evolution: Record workflow experience and cache action results
• CompositeRouter: Consult routing memory for model selection and record outcomes

Graph Memory

Entity relationships extracted from context.

interface IGraphMemory {
  addNode(entity: Entity): Promise<void>;
  addEdge(from: string, to: string, relation: string): Promise<void>;
  query(pattern: GraphPattern): Promise<Entity[]>;
  getRelated(entityId: string, depth?: number): Promise<Entity[]>;
  visualize(): string; // Mermaid diagram
}

Entity Extraction

Automatically extracts:

• Named entities: Functions, classes, files, concepts
• Relationships: Uses, extends, imports, references
• Attributes: Types, visibility, documentation

Use Cases

Adaptive Memory

Priority-based retrieval combining recency, importance, and relevance.

interface IAdaptiveMemory {
  store(item: MemoryItem): Promise<void>;
  retrieve(query: string, limit: number): Promise<MemoryItem[]>;
  setDecayRate(rate: number): void;
  getRelevanceScore(item: MemoryItem, context: string): number;
}

interface MemoryItem {
  content: string;
  timestamp: number;
  importance: number; // 0-1
  accessCount: number;
  lastAccessed: number;
}

Retrieval Algorithm

Priority score = (importance × 0.4) + (recency × 0.3) + (relevance × 0.3)

Where:

• Importance: User-assigned or learned from feedback
• Recency: Exponential decay from creation time
• Relevance: Semantic similarity to current query

Session Memory

Cross-session persistence for learning retention (Reflexion pattern).

interface ISessionMemory {
  startSession(sessionId: string): void;
  endSession(): Promise<void>;
  recordLearning(learning: Learning): void;
  recordTask(task: TaskRecord): void;
  recordResolvedError(error: ResolvedError): void;
  loadRelevantLearnings(context: string, minConfidence?: number): Promise<Learning[]>;
  searchLearnings(query: string): Promise<Learning[]>;
  getErrorSolution(errorPattern: string): Promise<ResolvedError | undefined>;
}

Learning Persistence

{
  "id": "learn_001",
  "content": "Always validate user input before database queries",
  "context": "SQL injection prevention",
  "confidence": 0.95,
  "createdAt": "2026-01-15T10:00:00Z",
  "source": "security_review_task"
}

Memory Lifecycle

sequenceDiagram
    participant A as Agent
    participant TM as TypedMemory
    participant AM as AdaptiveMemory
    participant V as Vault

    A->>TM: Query by task type
    TM->>AM: Get relevant items
    AM-->>TM: Priority-sorted results
    TM-->>A: Typed memory entries

    A->>A: Execute task
    A->>TM: Store experience
    TM->>AM: Update priorities

    alt High importance
        TM->>V: Persist to vault
    end

Configuration

memory:
  backend: hybrid # sqlite | markdown | hybrid
  maxSize: 100MB
  pruneThreshold: 80%

  typed:
    enabled: true
    types: [core, episodic, semantic, procedural, resource, vault]

  graph:
    enabled: true
    maxNodes: 10000

  adaptive:
    decayRate: 0.95 # Per-hour decay
    relevanceThreshold: 0.3

Source Files

Research Sources

Related Documents

• Agent System: AGENT_SYSTEM.md
• Routing System: ROUTING_SYSTEM.md
• Full Architecture: ARCHITECTURE.md