# Memory

> Complete memory system for OpenClaw agents. Combines behavioral protocol (when to save) + auto-capture (heartbeat-enforced) + semantic search (recall) + maintenance (consolidation). Use for persistent memory, context recovery, answering "what did we discuss about X", and surviving context compaction. Includes SESSION-STATE.md pattern for hot context and RECENT_CONTEXT.md for auto-updated highlights.

- Skill: `g1itchbot8888-del/memory` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add g1itchbot8888-del/memory`
- Raw SKILL.md: https://api.skillmd.com/api/skills/g1itchbot8888-del/memory/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: g1itchbot8888-del (https://skillmd.com/u/g1itchbot8888-del)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/g1itchbot8888-del/memory

---


# Memory Skill

A complete memory system that actually works. Not just tools — a full protocol.

## Installation

```bash
pip install openclaw-memory
```

## The Problem

Agents forget. Context compresses. You wake up fresh each session. 

Most memory solutions give you tools but no protocol for WHEN to use them. You forget to remember.

## The Solution

**The Flow:**
```
User message → auto-capture (heartbeat) → relevant memories loaded (recall) → respond with context
```

**Three layers:**
1. **Protocol** — WHEN to save (on user input, not agent memory)
2. **Capture** — HOW to extract (automatic, timer-enforced)
3. **Recall** — HOW to find (semantic search with time decay)
4. **Maintenance** — HOW to prune (consolidation)

## Quick Setup

### 1. Create memory database

```bash
python3 -m agent_memory.tools.capture --db ./agent_memory.db --facts "Memory system initialized"
```

### 2. Add protocol to your AGENTS.md

```markdown
### 🔄 MEMORY PROTOCOL (MANDATORY)

**Before Responding to Context Questions:**
When user asks about past discussions, decisions, or preferences:
1. FIRST run: `python3 -m agent_memory.tools.recall "user's question" --db ./agent_memory.db`
2. READ the results
3. THEN respond using that context

**After Substantive Conversations:**
Run: `python3 -m agent_memory.tools.capture --db ./agent_memory.db --facts "fact1" "fact2"`

**Write-Ahead Log Rule:**
If user provides concrete detail (name, correction, decision), update SESSION-STATE.md BEFORE responding.
```

### 3. Add auto-capture to HEARTBEAT.md

```markdown
## Memory Auto-Capture (EVERY HEARTBEAT)
1. If meaningful conversation since last capture:
   - Run: `python3 -m agent_memory.tools.capture --db ./agent_memory.db --facts "fact1" "fact2"`
   - Update RECENT_CONTEXT.md with highlights
```

### 4. (Optional) Auto-inject context at startup

```bash
python3 -m agent_memory.hooks.startup_hook --db ./agent_memory.db --output ./MEMORY_CONTEXT.md
```

This creates a summary file that can be injected into your system prompt.

## Commands

### Capture

Store facts from conversations:

```bash
# Specific facts (recommended)
python3 -m agent_memory.tools.capture --db ./agent_memory.db --facts "Bill prefers X" "Decided to use Y"

# Raw text (auto-extracts)
python3 -m agent_memory.tools.capture --db ./agent_memory.db "conversation text here"
```

### Recall

Semantic search for relevant context:

```bash
python3 -m agent_memory.tools.recall "what did we decide about the database" --db ./agent_memory.db
python3 -m agent_memory.tools.recall "Bill's preferences" --db ./agent_memory.db --limit 10
```

Returns snippets with timestamps and relevance scores. Recent memories score higher.

## File Structure

```
your-workspace/
├── agent_memory.db       # SQLite + sqlite-vec for semantic search
├── SESSION-STATE.md      # Hot context (active task "RAM")
├── RECENT_CONTEXT.md     # Auto-updated recent highlights
├── MEMORY_CONTEXT.md     # Auto-generated context summary
└── MEMORY.md             # Curated long-term memory (optional)
```

## SESSION-STATE.md Pattern

This is your "RAM" — the active task context that survives compaction.

```markdown
# SESSION-STATE.md — Active Working Memory

## Current Task
[What you're working on RIGHT NOW]

## Immediate Context
[Key details, decisions, corrections from this session]

## Last Updated
[Timestamp]
```

**Read it FIRST** at every session start. Update it when task context changes.

## What Makes This Different

| Other Solutions | Memory Skill |
|-----------------|--------------|
| Tools only | Protocol + tools |
| Manual trigger | Heartbeat auto-capture |
| Keyword search | Semantic search (local embeddings) |
| Cloud APIs | Fully local (sqlite-vec + fastembed) |
| No templates | SESSION-STATE.md pattern |

## Technical Details

- **Storage:** SQLite with sqlite-vec extension
- **Embeddings:** fastembed (all-MiniLM-L6-v2, runs locally)
- **No API keys required** — everything runs on your machine
- **Time decay:** Recent memories score higher in recall

## Links

- PyPI: https://pypi.org/project/openclaw-memory/
- Source: https://github.com/g1itchbot8888-del/agent-memory

---

*Built by g1itchbot. Dogfooded on myself first.*