---
title: "Memory System -- Cross-Session Learning and Recall"
description: "A two-tier memory architecture with TF-IDF scoring, 8 knowledge types, and time-decayed recall across every Claude Code session."
---

# Memory System -- Cross-Session Learning and Recall

A two-tier memory system with a continuously growing archive of learnings across sessions, using TF-IDF scoring with time decay to surface relevant knowledge at the right moment.

## Architecture

The memory system uses two tiers of storage working together:

- **MEMORY.md** (core memory): Always loaded at the start of every session. Kept concise at approximately 200 lines. Contains the most important distilled knowledge -- architectural decisions, critical lessons, and active project context.
- **memory_log.jsonl** (archive): Append-only log that grows continuously. Every learning, error resolution, and decision is recorded here with timestamps and tags. This is the searchable long-term memory.
- **core_universal.md** (always-relevant preferences): Core preferences and patterns that apply across all projects, always injected.
- **core_tagged.jsonl** (tagged entries): Tagged memory entries for targeted injection based on current context.
- **memory_graph.db** (graph database): A 227MB+ semantic graph database enabling relationship-based memory queries across sessions. Stores connections between concepts, files, and decisions for deeper context retrieval.

## 8 Knowledge Types

Every memory entry is tagged with one of 8 types:

| Type | What It Captures |
|------|-----------------|
| ARCHITECTURAL_DECISION | Design choices and system structure decisions |
| WORKING_SOLUTION | Fixes and solutions that worked |
| CODEBASE_PATTERN | Patterns discovered in code |
| FAILED_APPROACH | What did not work and why |
| error_resolution | How specific errors were resolved (auto-captured) |
| test_result | Test pass/fail context (auto-captured) |
| USER_PREFERENCE | User's preferred approaches and style |
| in_session | General session learnings |

## TF-IDF Scoring

Memory recall uses Term Frequency-Inverse Document Frequency matching. When you describe a task, the system scores every memory entry against your current context. Entries with rare, specific terms that match your task score highest. Common words are down-weighted automatically.

## Scoring Formula

The full scoring formula combines multiple signals:

```
score = (exact_matches + stem_matches x 0.7 + substring_matches x 0.5) / query_token_count
      x type_boost x tag_boost x recency_decay
```

- **Type boost** (1.5x): Applied to user corrections, repeated corrections, and preference entries
- **Tag boost** (2x): Applied when memory entry tags overlap with current query context
- **Recency decay**: e^(-0.03 x age_in_days) -- recent learnings score higher, old ones fade but never disappear

## Time Decay

Recent learnings score higher than older ones. A learning from yesterday outranks an identical learning from last month. This ensures the AI prioritizes fresh context. However, older learnings are not deleted -- they remain in the archive and can still surface if their content is highly relevant.

## 3 Recall Tiers

Memory matches are injected at different levels based on their relevance score:

| Tier | Score | Behavior |
|------|-------|----------|
| HOT | > 0.3 | Full content injected into context. Acknowledgment required before proceeding. |
| WARM | 0.1 - 0.3 | Preview shown for reference. AI can use or skip. |
| COLD | < 0.1 | Not shown. MEMORY.md core memory is still loaded regardless. |

## Auto-Learning

Three automatic capture mechanisms run without any user action:

1. **Error-resolution pairs**: When the AI encounters an error and resolves it, the pair is recorded automatically.
2. **Test results**: Pass/fail outcomes with context are captured after every test run.
3. **Session-end extraction**: When a session ends, a dedicated hook extracts decisions, fixes, and user preferences from the full transcript.

## Failed Approach Tracking

The FAILED_APPROACH type is specifically designed to prevent the AI from repeating mistakes. When a solution fails, the system records what was tried, why it failed, and what eventually worked. On future sessions, if the AI is about to try a known-failed approach, the memory system surfaces the warning.

## Context Compaction Resilience

State markers use TTL-based expiration for resilience against context compaction. Memory markers have 10-minute TTL, bug resolution markers have 1-hour TTL. If a marker is fresh enough, it is accepted regardless of any session changes.

## Distillation

Over time, the JSONL archive grows large. Periodic distillation consolidates the archive into MEMORY.md core memory. This process summarizes related learnings, removes redundancy, and keeps core memory concise while preserving details in the archive. Run manually or ask the AI to "distill my memories."

## Related

- [Safety Gates](https://erebora.org/mantis/docs/safety-gates) -- Gate 1.5 (Memory Recall) triggers this system
- [Skills & Agents](https://erebora.org/mantis/docs/skills-and-agents) -- Agents use memory for context
- [Getting Started](https://erebora.org/mantis/docs/getting-started) -- Memory initializes on first run
- [Live Documentation](https://erebora.org/mantis/) -- Full product page