Memory System

Memory System

CortexPrism uses a 5-tier memory architecture with multi-strategy retrieval, time-decay scoring, and automatic injection into the agent's context window.

Architecture

retrieve(query, embedder)
  │
  ├── keywordSearch(query)   → FTS5 BM25 over episodic_memory + semantic_memory
  │
  ├── vectorSearch(embed)    → cosine similarity over stored embeddings
  │       embedding = embedder.embed(query) if embedder available
  │
  └── merge + decay-score
        score = raw_score × 2^(-age_days / half_life_days)
        sorted descending → top-K

Memory Tiers

Tier	Table	Contents	Retention
Episodic	episodic_memory	Turn summaries — user+agent exchanges	Auto-decay based on half-life
Semantic	semantic_memory	Injected facts / knowledge / entities	Indefinite unless pruned
Reflection	reflection_memory	LLM-extracted behavior patterns	Consolidated weekly
Graph	entity_graph	Knowledge graph nodes and edges	Built from semantic extraction
Skills	procedural_memory	Reusable procedural patterns (human-authored + LLM-learned)	Self-learning with auto-dedup

Skills System (v0.36.0+)

The procedural memory tier has been significantly enhanced. Skills now feature:

• 6-state lifecycle — candidate → verified → released → degraded → deprecated → archived
• Embedding-based retrieval — cosine similarity matching with lexical fallback
• Auto-deduplication — similar skills detected and merged automatically
• Quality signals — utility score, freshness, success rate, token cost
• Health system — composite scoring with auto-maintenance
• Trust tiering — 4 levels gate agent exposure
• Dependency tracking — declare depends_on / conflicts_with relationships
• 12 REST API endpoints — full CRUD + lifecycle management

See Skills System for the complete reference.

Retrieval Strategies

Keyword Search

Uses SQLite FTS5 (full-text search) with BM25 ranking across episodic_memory_fts and semantic_memory_fts virtual tables.

Vector Search

Computes cosine similarity between the query embedding and stored embeddings in episodic and semantic memory tables. Requires an embedding provider (Ollama, OpenAI, or Stub).

Graph Traversal

searchEntities() finds matching nodes in the knowledge graph, then traverseGraph() follows edges to discover related entities.

Time-Decay Scoring

After merging results from all strategies, each memory hit is scored:

score = raw_score × 2^(-age_days / half_life_days)

Memories with longer half-lives decay more slowly. Frequently accessed memories get their half-life automatically extended by the heuristics system.

Embedding Providers

Class	Backend	Model
OllamaEmbedder	Ollama /api/embeddings	Configurable
OpenAIEmbedder	OpenAI text-embedding-3-small	Fixed
StubEmbedder	Deterministic hash	No model needed

Memory Injection

Relevant memories are prepended to the system prompt on every turn:

--- Relevant Memory ---
[episodic] 2026-06-14: User: ... Assistant: ...
[semantic] CortexPrism uses SQLite WAL mode
---

Each hit includes: label, age, category, tags, topics, and entities for richer LLM context.

Consolidation

Daily Consolidation

runDailyConsolidation() applies decay scoring updates to all episodic memories and runs entity extraction on new turns.

Heuristic Learning

runHeuristicCycle() performs four passes:

1. Importance boosting — boosts importance for frequently accessed memories
2. Decay slowing — extends half-life for high-access memories (up to a ceiling)
3. Relation strengthening — reinforces graph edges for co-accessed entities
4. Auto-tagging — adds tags based on memory content analysis

Manual trigger: cortex memory heuristics

Memory CLI

cortex memory search "sqlite"              # Keyword + vector hybrid search
cortex memory search "sqlite" --semantic    # Vector only
cortex memory add "CortexPrism uses SQLite WAL mode"
cortex memory health                       # Per-tier stats with decay indicators
cortex memory heuristics                   # Trigger heuristic learning cycle

Privacy

The Privacy Manager (src/memory/privacy.ts) provides:

• PII detection and redaction in stored memories
• Configurable retention policies
• Per-user memory isolation

See Also

• Architecture — System overview
• Request Flow — Memory read/write paths in the agent lifecycle
• Configuration — Memory-related config options