memory-pipeline

What this skill does

# Memory Pipeline + Performance Routine

A complete memory and performance system for AI agents. Two subsystems, one package:

- **Memory Pipeline** (Python scripts) — Extracts facts, builds knowledge graphs, generates daily briefings
- **Performance Routine** (TypeScript hooks) — Pre-game briefing injection, tool discipline, output compression, after-action review

## What This Does

### Memory Pipeline (Between Sessions)

A three-stage system that helps AI agents maintain long-term memory:

1. **Extract** — Pulls structured facts (decisions, preferences, learnings, commitments) from daily notes and session transcripts using LLM extraction
2. **Link** — Builds a knowledge graph with embeddings and bidirectional links between related facts, identifies contradictions
3. **Briefing** — Generates a compact BRIEFING.md file loaded at session start with personality reminders, active projects, recent decisions, and key context

### Performance Routine (Within Sessions)

Four lifecycle hooks that enforce consistency during agent runs:

1. **Pre-Game Routine** (`before_agent_start`) — Assembles a bounded briefing packet from memory files + checklist, injects into system prompt
2. **Tool Discipline** (`before_tool_call`) — Enforces deny lists, normalizes params, prevents unsafe tool calls
3. **Output Compression** (`tool_result_persist`) — Head+tail compression of large tool results to prevent context bloat
4. **After-Action Review** (`agent_end`) — Writes durable notes about what happened, tools used, and outcomes

## Quick Start

### Installation

The skill includes three Python scripts in `scripts/`:
- `memory-extract.py` — Fact extraction
- `memory-link.py` — Knowledge graph building
- `memory-briefing.py` — Daily briefing generation

All scripts auto-detect your workspace from:
1. `CLAWDBOT_WORKSPACE` environment variable
2. Current working directory (if contains SOUL.md or AGENTS.md)
3. `~/.clawdbot/workspace` (default fallback)

### Requirements

**At least one LLM API key** is required:
- OpenAI API key (for GPT-4o-mini + embeddings)
- Anthropic API key (for Claude Haiku)
- Gemini API key (for Gemini Flash)

Set via environment variable or config file:
```bash
# Environment variable
export OPENAI_API_KEY="sk-..."

# OR config file
echo "sk-..." > ~/.config/openai/api_key
```

The scripts will auto-detect and use whichever API key is available.

### Basic Usage

Run the full pipeline:
```bash
python3 scripts/memory-extract.py
python3 scripts/memory-link.py
python3 scripts/memory-briefing.py
```

Or run individual steps as needed.

## Pipeline Stages

### Stage 1: Extract Facts

**Script:** `memory-extract.py`

Reads from (in priority order):
1. Daily memory files (`{workspace}/memory/YYYY-MM-DD.md`) — today or yesterday
2. Session transcripts (`~/.clawdbot/agents/main/sessions/*.jsonl`)

Extracts structured facts:
- **Type**: decision, preference, learning, commitment, fact
- **Content**: The actual information
- **Subject**: What it's about (auto-detected from context)
- **Confidence**: 0.0-1.0 reliability score

**Output:** `{workspace}/memory/extracted.jsonl` — One JSON fact per line, deduplicated

### Stage 2: Build Knowledge Graph

**Script:** `memory-link.py`

Takes extracted facts and:
- Generates embeddings (if OpenAI key available, else uses keyword similarity)
- Creates bidirectional links between related facts
- Detects contradictions and marks superseded facts
- Auto-generates domain tags from content

**Output:**
- `{workspace}/memory/knowledge-graph.json` — Full graph with nodes and links
- `{workspace}/memory/knowledge-summary.md` — Human-readable summary

### Stage 3: Generate Briefing

**Script:** `memory-briefing.py`

Creates a compact daily briefing loaded at session start.

Combines:
- Personality traits (from SOUL.md if exists)
- User context (from USER.md if exists)
- Active projects (top subjects from recent facts)
- Recent decisions and preferences
- Active todos (from any todos*.md files)

**Output:** `{workspace}/BRIEFING.md` — Under 2000 chars, LLM-generated or template-based

## Wiring Into HEARTBEAT.md

To run automatically, add to your workspace's `HEARTBEAT.md`:

```markdown
# Heartbeat Tasks

## Daily (once per day, morning)
- Run memory extraction: `cd {workspace} && python3 skills/memory-pipeline/scripts/memory-extract.py`
- Build knowledge graph: `cd {workspace} && python3 skills/memory-pipeline/scripts/memory-link.py`
- Generate briefing: `cd {workspace} && python3 skills/memory-pipeline/scripts/memory-briefing.py`

## Weekly (Sunday evening)
- Review `memory/knowledge-summary.md` for insights
- Clean up old daily notes (optional)
```

## Loading BRIEFING.md

**Important:** BRIEFING.md needs to be loaded as workspace context at session start. This requires the OpenClaw context loading feature (currently in development).

Once available, configure your agent to load BRIEFING.md along with SOUL.md, USER.md, and AGENTS.md at the start of each session.

## Output Files

All files are created in `{workspace}/memory/`:

- **extracted.jsonl** — All extracted facts (append-only)
- **knowledge-graph.json** — Full knowledge graph with embeddings and links
- **knowledge-summary.md** — Human-readable summary of the graph
- **BRIEFING.md** (in workspace root) — Daily context cheat sheet

## Customization

### Changing Models

Edit the model names in each script:
- `memory-extract.py`: Lines with `"model": "gpt-4o-mini"` (or claude/gemini equivalents)
- `memory-link.py`: Line with `"model": "text-embedding-3-small"`
- `memory-briefing.py`: Lines with `"model": "gpt-4o-mini"`

### Adjusting Extraction

In `memory-extract.py`, modify the extraction prompt (lines ~75-85) to focus on different types of information or change the output format.

### Link Threshold

In `memory-link.py`, change the similarity threshold for creating links (currently 0.3 at line ~195).

## Troubleshooting

**No facts extracted:**
- Check that daily notes or transcripts exist
- Verify API key is set correctly
- Check script output for LLM errors

**Low-quality links:**
- Add OpenAI API key for embedding-based similarity (more accurate than keyword matching)
- Adjust similarity threshold in `memory-link.py`

**Briefing too long:**
- Reduce number of facts included in template (edit `generate_fallback_briefing`)
- LLM-generated briefings are automatically constrained to 2000 chars

## Performance Routine (Hook System)

The performance routine is implemented as OpenClaw lifecycle hooks in `src/`. It applies a core principle from performance psychology: **separate thinking from doing**. Athletes don't redesign their technique mid-game — they prepare (purposeful thinking), then execute trained sequences (reactive execution). The only exception is genuine error handling.

For agents, this means: front-load all context, constraints, and memory retrieval into a briefing packet *before* inference starts. Keep execution clean. Write the after-action review *after*. Never inject corrections mid-run.

### Architecture

```
User Message → Gateway → Agent Loop
  ├── before_agent_start → Briefing Packet (checklist + memory + constraints)
  ├── LLM Inference (clean context, no mid-run corrections)
  ├── before_tool_call → Policy enforcement (deny list)
  ├── Tool Execution → Result
  ├── tool_result_persist → Compression (head+tail, bounded)
  └── agent_end → After-Action Review → durable memory for next run
```

### The Core Idea: No Mid-Swing Coaching

Constant correction during execution degrades output. Mid-run prompt patches create instruction collision — two competing directives the agent must reconcile instead of executing. The alternative:

1. **Capture corrections** — don't inject them into the current run
2. **Condense into deltas** — merge all corrections into a clean update
3. **Inject next run** — the next briefing packet includes the corrected instructions

The after-action review (`agent_end`) feeds back into the next briefing (`before_agent_start`). The l