perpetual-memory

name	perpetual-memory
description	Use when you need to auto-log all tool interactions into a self-organizing vector DB with instant recall. Intercepts interactions, extracts key information, generates embeddings, stores in LanceDB, auto-categorizes, and builds a retrieval index. Inspired by OpenClaw SQLite LCM + summary DAG pattern.
version	1.0.0
source	builtin
trust_score	100
provenance_sha	68efb747a552dc90

Perpetual Memory

Overview

Auto-embed all tool interactions into a vector store without explicit "remember" commands. Every significant interaction is captured, categorized, and stored in LanceDB for instant semantic recall across sessions.

Core principle: If it happened and it mattered, it is in perpetual memory. No explicit "remember" commands needed. The system auto-captures decisions, learnings, patterns, gotchas, and issues from every agent interaction.

When to Use

• After completing any significant task (auto-triggered)
• When agents produce findings, decisions, or learnings
• When debugging reveals root causes or workarounds
• When architectural decisions are made
• When new patterns or anti-patterns are discovered
• At session boundaries to capture session summaries

Do NOT use for:

• Trivial read-only queries that produce no insights
• Ephemeral debugging output that has no lasting value
• Duplicate content already in the memory system

Integration with Existing Memory System

This skill extends (does NOT replace) the existing memory system:

System	Purpose	Perpetual Memory Role
learnings.md	Human-readable learning archive	Auto-populates from embeddings
decisions.md	ADR-style decisions	Indexes for semantic recall
issues.md	Known blockers and workarounds	Indexes for semantic recall
patterns.json	Structured patterns (MemoryRecord)	Deduplicates against
gotchas.json	Structured gotchas (MemoryRecord)	Deduplicates against
memory-search.cjs	Semantic search over markdown	Complementary (different index)
pnpm search:code	Code search (BM25 + semantic)	Does NOT interfere
perpetual_memory table	Vector store of all interactions	Primary perpetual store

Workflow

Step 1: Intercept Interaction

After a tool completes (PostToolUse), extract the significant content:

• TaskUpdate completions with metadata.summary
• Write/Edit operations with file paths and descriptions
• Bash command outputs with significant findings
• Skill invocation results

Step 2: Extract Key Information

From the raw interaction, extract:

• What happened: One-line summary of the action
• Why it matters: The significance or decision rationale
• Context: Agent name, task ID, affected files
• Category signal: Keywords that indicate decision/learning/pattern/gotcha/issue

Step 3: Generate Embeddings and Store

# Embed and store via the auto-embed CLI tool
node .claude/tools/cli/auto-embed.cjs \
  --text "Discovered that routing-guard.cjs blocks Write on creator paths. This is Gate 4 enforcement." \
  --agent developer \
  --task-id task-12 \
  --category learning

Step 4: Auto-Categorize

The tool auto-categorizes based on keyword matching:

Category	Trigger Keywords
decision	decided, chose, selected, tradeoff, rationale, ADR
learning	learned, discovered, found that, realized, insight
pattern	pattern, approach, technique, best practice, convention
gotcha	gotcha, pitfall, anti-pattern, risk, warning, sharp edge
issue	issue, bug, error, broken, failing, blocker, regression

Override with --category <name> when auto-detection is wrong.

Step 5: Deduplication

Before storing, the tool checks similarity against existing entries:

• Default threshold: 0.92 (92% cosine similarity)
• If a near-duplicate exists, the store is skipped
• Configurable via --dedup-threshold <float>

Step 6: Build Retrieval Index

The LanceDB perpetual_memory table automatically maintains a vector index. Queries use ANN (Approximate Nearest Neighbor) search for sub-second retrieval.

CLI Reference

# Store an interaction
node .claude/tools/cli/auto-embed.cjs --text "interaction text" --agent developer --task-id task-5

# Query perpetual memory
node .claude/tools/cli/auto-embed.cjs --query "how does routing work" --limit 10

# View statistics
node .claude/tools/cli/auto-embed.cjs --stats

# Pipe from stdin
echo "important finding" | node .claude/tools/cli/auto-embed.cjs --stdin --agent qa

Agent Integration

All agents should embed significant findings at task completion:

// In TaskUpdate(completed) metadata handler:
// Auto-embed the summary into perpetual memory
const summary = metadata.summary;
if (summary && summary.length > 20) {
  // The auto-embed tool handles categorization and dedup
  Bash({
    command: `node .claude/tools/cli/auto-embed.cjs --text "${summary.replace(/"/g, '\\"')}" --agent ${agentType} --task-id ${taskId}`,
  });
}

Iron Laws

1. NEVER store secrets, credentials, or PII in perpetual memory -- sanitize before embedding.
2. ALWAYS deduplicate before storing -- duplicate embeddings waste storage and pollute retrieval.
3. NEVER break existing memory-search.cjs -- perpetual memory is an additional layer, not a replacement.
4. ALWAYS include agent and task-id metadata -- unattributed memories cannot be traced or audited.
5. NEVER embed raw tool output verbatim -- extract the insight, not the noise.

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Approach
Embedding raw Bash output	Noise drowns signal; embeddings are low quality	Extract the finding or decision from the output
Skipping deduplication	Storage bloat; retrieval quality degrades	Always use dedup threshold (default 0.92)
Replacing markdown memory files	Breaks existing agent workflows that read .md	Perpetual memory supplements, never replaces
Storing without agent/task metadata	Cannot trace or audit memory provenance	Always pass --agent and --task-id
Embedding everything	Context pollution; irrelevant results in queries	Only embed significant findings and decisions

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

• New pattern -> .claude/context/memory/learnings.md
• Issue found -> .claude/context/memory/issues.md
• Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.