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 (14-day default)
Semantic	semantic_memory	Injected facts / knowledge / entities	Indefinite unless pruned (30-day half-life)
Reflection	reflection_memory	LLM-extracted behavior patterns	Consolidated weekly, duplicate patterns weighted
Graph	graph_entities + graph_relations	Knowledge graph nodes and edges	Built from semantic extraction + co-occurrence
Skills	procedural_memory	Procedural knowledge from sessions	See Skills System

Retrieval Strategies

Keyword Search

Uses SQLite FTS5 (full-text search) with BM25 ranking across episodic_memory_fts and semantic_memory_fts virtual tables. Sanitizes FTS5 special characters to prevent query errors.

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 up to configurable depth 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)

Tier	Default Half-Life	Max Extended
Episodic	14 days	90 days
Semantic	30 days	180 days

Frequently accessed memories get their half-life automatically extended by the heuristics system.

Heuristic Learning

runHeuristicCycle() performs four self-improvement passes daily:

1. Importance Boosting

Memories with high access counts receive importance bumps:

• 10+ accesses → +0.15 importance
• 5+ accesses → +0.05 importance
• Access count reset after each boost cycle

2. Decay Slowing

Frequently accessed memories get 1.3× half-life extension (e.g., episodic 14→18.2 days), capped at max values. Uses < max guard so frequently-accessed memories keep extending toward the ceiling on each cycle.

3. Relation Strengthening

Analyzes entity pairs across episodic memories. Creates or strengthens related_to graph relations when entities co-occur 3+ times.

4. Auto-Categorization

12 pattern-based rules auto-tag untagged semantic memories: api, database, frontend, debugging, security, devops, testing, documentation, configuration, performance, design, infrastructure.

Access Tracking

Every memory retrieval records to access_count and last_accessed, enabling usage-based reinforcement across all heuristics.

Memory Injection

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

--- Relevant Memory ---
[episodic·api·tag1,tag2] 2026-06-14: User: ... Assistant: ...
[semantic·database] CortexPrism uses SQLite WAL mode
---

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

Embedding Providers

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

Consolidation

Daily Consolidation

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

Hourly Consolidation

Aggregates turn-level episodic notes into session summaries.

Weekly Reflection

Consolidates reflection patterns, merging duplicates and updating confidence scores.

Memory CLI

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

Memory Health Dashboard

getMemoryHealth() returns aggregated metrics (60s in-memory cache):

• Per-tier: total, active, stale counts
• Average decay, importance, access frequency
• Graph entity and relation counts
• Reflection confidence distribution

Privacy

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

• PII detection and redaction (email, IP, SSN, card, API key patterns)
• Configurable retention policies per memory tier
• Per-agent privacy policy configuration
• Automatic enforcement via enforceMemoryRetention()

Web UI

The Memory page has 4 tabbed panes:

• Search — unified search with keyword/vector/hybrid mode
• Graph — entity browser with type badges, click-through traversal, breadcrumb navigation
• Reflections — confidence-ranked pattern list with category badges
• Health — per-tier cards with decay distribution bars and metrics

Plus 3 extension tabs:

• Privacy — PII redaction config, retention periods
• Heuristics — 12 auto-categorization rule toggles, manual cycle trigger
• Embeddings — provider/model/dimensions configuration

API Endpoints

Method	Path	Description
GET	/api/memory/search?q=&mode=hybrid	Search memory
GET	/api/memory/stats	Memory statistics
GET	/api/memory/health	Per-tier health metrics
POST	/api/memory/add	Add memory entry
GET	/api/memory/reflections	List reflection patterns
GET	/api/memory/graph/entities?q=	Search graph entities
GET	/api/memory/graph?entity=&depth=	Graph traversal
GET	/api/memory/privacy	Privacy configuration
PUT	/api/memory/privacy	Update privacy config
GET	/api/memory/heuristics	Heuristics configuration
PUT	/api/memory/heuristics	Update heuristics config
GET	/api/memory/embeddings	Embedding configuration
PUT	/api/memory/embeddings	Update embedding config

See Also

• Architecture — System overview
• Skills System — Procedural memory tier
• Memory Search Tool — memory_search and memory_note tools
• Security Supervisor — Sensitive memory access gating

Memory Health Monitor (#70)

src/memory/heuristics.ts computes a 0-100 health score with categorized warnings:

Warning Category	Trigger	Severity
All stale	100% of memories with decay < 0.1	Critical
Majority stale	>50% stale	Warning
Low decay	Avg decay < 0.3 with >10 entries	Warning
Low access	Avg < 0.5 access count with >20 entries	Info
No relations	Entities with zero graph relations	Warning
Large graph	>100 entities	Info
Low reflection confidence	Avg confidence < 0.5	Warning

Health score and warnings are visible on the Memory page with a color-coded bar (green ≥80, amber ≥50, red <50).

Entity Resolution (#66)

findDuplicateEntities() in src/memory/graph.ts detects fuzzy-matched entity duplicates by:

• Normalizing names (lowercase, strip non-alphanumeric)
• Matching exact or substring overlap (>3 char minimum)
• mergeEntities() relinks relations and removes the source entity

API: GET /api/memory/duplicates, POST /api/memory/merge

Multi-Modal Vault (#69)

The vault now supports content storage beyond credentials:

• POST /api/vault/content accepts files, embeddings, images, text (1MB limit)
• Content entries stored with credentialType: 'content'
• Entries logged as memory_write events in lens_events

Glossary (#73)

In-memory term registry with aliases and categories:

• GET /api/glossary?category= lists terms
• POST /api/glossary defines new terms with optional aliases