Overkill Memory System

# Ultimate Unified Memory System (Overkill Memory System)
## VERSION 1.9.3 (SPEED-FIRST)

A comprehensive 6-tier memory architecture with neuroscience integration, WAL protocol, and full automation for OpenClaw agents.

## Overview

The Ultimate Unified Memory System implements a **biologically-inspired, speed-first** memory hierarchy. It provides persistent, contextual memory across agent sessions with automatic importance weighting, emotional tagging, and value-based retention.

### What It Does

- **Brain-Full Architecture**: 6 brain regions (Hippocampus, Amygdala, VTA, Basal Ganglia, Insula, ACC)
- **Speed-First Architecture**: Optimized for ~5ms average query time
- **Fast File Search**: Uses `fd` + `rg` for 10x faster file tier searching
- **Knowledge Graph**: Structured atomic facts with versioning
- **Self-Improving**: Continuous learning from errors and corrections
- **Self-Reflection**: Periodic self-assessment and performance review
- **Multi-Agent Support**: Shared + private ChromaDB areas per agent
- **6-Tier Memory Architecture**: From instant recall (HOT) to archival (COLD/GIT-NOTES)
- **Hybrid Neuroscience**: Filter + Ranker approach for precision + speed
- **WAL (Write-Ahead Log) Protocol**: Ensures no memory is ever lost
- **Neuroscience Integration**: Hippocampus (importance), Amygdala (emotions), VTA (rewards/motivation)
- **Error Learning**: Tracks and learns from user corrections
- **Spaced Repetition**: FSRS-6 via Vestige for natural memory decay
- **Semantic Search**: ChromaDB-powered vector storage for contextual retrieval
- **Cloud Backup**: Supermemory integration for cross-device backup (NOT in query path)
- **Full Automation**: Cron jobs for cross-session messages, platform posts, diary entries, and proactive memory maintenance

### Speed Targets

| Scenario | Time |
|----------|------|
| Compiled query match | ~0ms |
| Ultra-hot hit | ~0.1ms |
| Hot cache hit | ~1ms |
| Mem0 hit | ~22ms |
| Full search | ~55ms |
| **Average** | **~5ms**...

# Overkill Memory System - Quick Start

A neuroscience-inspired 6-tier memory architecture for OpenClaw agents.

## Quick Start

### 1. Initialize

```bash
cd ~/.openclaw/workspace-cody/skills/overkill-memory-system
python3 cli.py init
```

### 2. Add Your First Memory

```bash
python3 cli.py add "Starting my memory system journey!"
```

### 3. Search Memories

```bash
python3 cli.py search "memory system"
```

## Common Commands

| Command | Description |
|---------|-------------|
| `python3 cli.py init` | Initialize memory system |
| `python3 cli.py add "text"` | Add a memory |
| `python3 cli.py search "query"` | Search memories |
| `python3 cli.py session new` | Start new session |
| `python3 cli.py session end` | End session (flush WAL) |
| `python3 cli.py brain state` | View emotional state |
| `python3 cli.py daily "note"` | Add daily note |
| `python3 cli.py diary "entry"` | Add diary entry |
| `python3 cli.py stats` | Show memory statistics |

## The 6 Tiers

1. **HOT** - Session state (current context)
2. **WARM** - Daily notes (24-48h)
3. **TEMP** - Cache (minutes-hours)
4. **COLD** - Core memory (weeks-months)
5. **ARCHIVE** - Diary (months-years)
6. **COLD-STORAGE** - Git-Notes (indefinite)

## Environment Setup

```bash
cp .env.example .env
# Edit .env with your ChromaDB/Ollama settings (optional)
```

## Need Help?

See `SKILL.md` for complete documentation.