---
name: loom
description: >
  pi-loom long-term memory system — store, recall, and discover patterns
  across coding sessions. Provides Dream Engine insight generation,
  5-signal hybrid search (FTS5 + vector + recency + entity graph + cross-session),
  auto-capture of tool results, and RecMem subconscious consolidation.
  Sub-skills: loom-status, loom-recall, loom-store, loom-dream, loom-insights,
  loom-extract, loom-consolidate, loom-stats. Triggers: "loom", "memory",
  "remember this", "recall from previous session", "find pattern", "dream engine".
---

# pi-loom — Long-Term Memory

## Session Protocol

Every session starts with these calls:

```
loom_status()     — Lightweight status check (~50 tokens)
loom_context()    — [PI_LOOM] symbolic index (~520 tokens). Inject into your system prompt or working memory.
loom_recall()     — Full memory browse (when context-rich decisions needed)
```

## Daily Workflow

```
loom_status()                             # Start: check what's in memory
loom_context()                            # Get [PI_LOOM] symbolic index
... do work ...
loom_store "key decision" importance:0.8  # Persist important findings
loom_extract                              # Make memories searchable
loom_dream                                # End of session: distill patterns
loom_consolidate                          # Merge recurring subconscious memories
```

## Available Commands

| Command | Purpose |
|---------|---------|
| `loom_context` | Build [PI_LOOM] symbolic context index for injection |
| `loom_status` | Lightweight session status check |
| `loom_recall` | Search / browse memories by entity or query |
| `/loom-store` | Explicitly save a memory |
| `/loom-dream` | Run Dream Engine for insight generation |
| `/loom-insights` | View generated patterns and discoveries |
| `/loom-extract` | Extract atomic facts from memories |
| `/loom-consolidate` | Merge recurring subconscious memories |
| `/loom-stats` | View memory database statistics |

## Architecture

```
[PI_LOOM] index (~520 tokens) injected at session start
    ↓ drill-down via loom_recall / loom_detail / loom_timeline
SQLite (WAL mode) — single file: .pi-loom/loom.db
    ├── memories (FTS5 + vector search)
    ├── insights (Dream Engine output)
    ├── entity_edges (BFS graph for multi-hop retrieval)
    ├── raw_events (30-day TTL, zero LLM cost)
    └── session_summaries (LLM-generated)
```

## Design Principles

- **Restrained by design** — expiration as core mechanism against unbounded growth
- **Independent but collaborative** — entity_id is opaque string, no cross-plugin schema knowledge
- **Dual intake** — explicit `loom_store` + implicit auto-capture, two layers no duplication
- **Format-stable context** — deterministic `[PI_LOOM]` block for LLM prefix-cache efficiency
- **No echo loops** — insights are output-only; Dream Engine only samples raw memories