tiered-memory

# Tiered Memory System v2.2.0

> *A mind that remembers everything is as useless as one that remembers nothing. The art is knowing what to keep.* 🧠

EvoClaw-compatible three-tier memory system inspired by human cognition and PageIndex tree retrieval.

## What's New in v2.2.0

🔄 **Automatic Daily Note Ingestion**
- Consolidation (`daily`/`monthly`/`full` modes) now auto-runs `ingest-daily`
- Bridges `memory/YYYY-MM-DD.md` files → tiered memory system
- No more manual ingestion required — facts flow automatically
- Fixes the "two disconnected data paths" problem

## What's New in v2.1.0

🎯 **Structured Metadata Extraction**
- Automatic extraction of URLs, shell commands, and file paths from facts
- Preserved during distillation and consolidation
- Searchable by URL fragment

✅ **Memory Completeness Validation**
- Check daily notes for missing URLs, commands, and next steps
- Proactive warnings for incomplete information
- Actionable suggestions for improvement

🔍 **Enhanced Search**
- Search facts by URL fragment
- Get all stored URLs from warm memory
- Metadata-aware fact storage

🛡️ **URL Preservation**
- URLs explicitly preserved during LLM distillation
- Fallback metadata extraction if LLM misses them
- Command-line support for adding metadata manually

## Architecture

```
┌─────────────────────────────────────────────────────┐
│              AGENT CONTEXT (~8-15KB)                │
│                                                     │
│  ┌──────────┐  ┌────────────────────────────────┐  │
│  │  Tree    │  │  Retrieved Memory Nodes         │  │
│  │  Index   │  │  (on-demand, 1-3KB)            │  │
│  │  (~2KB)  │  │                                │  │
│  │          │  │  Fetched per conversation      │  │
│  │  Always  │  │  based on tree reasoning       │  │
│  │  loaded  │  │                                │  │
│  └────┬─────┘  └────────────────────────────────┘  │
│       │                                             │
└───────┼────────────────────────...

# Tiered Memory v2.0

> *A mind that remembers everything is as useless as one that remembers nothing.  
> The art is knowing what to keep.* 🧠

Three-tier memory system for OpenClaw agents implementing the EvoClaw Tiered Memory Architecture. Inspired by human cognition and PageIndex tree-based retrieval.

**Version:** 2.0.0  
**License:** MIT  
**Python:** 3.8+ (zero external dependencies)

---

## What's New in v2.0

🆕 **LLM-Powered Tree Search** — Reasoning-based retrieval instead of keyword matching  
🆕 **Distillation Engine** — 3-stage compression (500B → 80B → 20B)  
🆕 **Hot Memory Structure** — Identity, owner profile, active context, lessons (auto-pruning)  
🆕 **Score-Based Tiers** — >=0.7 Hot, >=0.3 Warm, >=0.05 Cold, <0.05 Frozen  
🆕 **Multi-Agent Support** — Agent ID scoping for all operations  
🆕 **Consolidation Modes** — Quick/daily/monthly/full with tree pruning  
🆕 **Critical Sync** — Cloud-first hot+tree sync after every conversation  
🆕 **Metrics & Observability** — Comprehensive memory system metrics  

---

## Architecture

```
┌─────────────────────────────────────────────────────┐
│                 AGENT CONTEXT                        │
│                                                     │
│  ┌──────────────┐  ┌──────────────────────────┐    │
│  │ Memory Tree  │  │  Retrieved Memory Nodes  │    │
│  │ Index (~2KB) │  │  (on-demand, ~1-3KB)     │    │
│  │              │  │                          │    │
│  │ Always in    │  │  Fetched per conversation│    │
│  │ context      │  │  based on tree reasoning │    │
│  └──────┬───────┘  └──────────────────────────┘    │
│         │                                           │
└─────────┼───────────────────────────────────────────┘
          │
          │ Tree Search (LLM reasoning)
          │
┌─────────┼───────────────────────────────────────────┐
│         ▼              MEMORY TIERS                  │
│                                                     │
│  ┌─────────────┐  ┌─────────...