auto-recall

name	auto-recall
description	Use when you need semantic retrieval from perpetual memory at query time. Parses query intent, searches vector store, ranks by relevance and recency, and injects context. Complements memory-search.cjs with the perpetual_memory LanceDB table.
version	1.0.0
source	builtin
trust_score	100
provenance_sha	3d65fa4f13109af6

Auto-Recall

Overview

Semantic retrieval from the perpetual memory vector store at query time. Parses query intent, searches the perpetual_memory LanceDB table, ranks results by relevance and recency, and returns structured context for injection into agent prompts.

Core principle: Every agent should be able to recall any past interaction instantly by meaning, not by filename or keyword. Auto-recall is the read side of the perpetual memory architecture.

When to Use

• At the start of any task to recall related past decisions and learnings
• When debugging to find previously encountered similar issues
• When an agent needs context about how a similar problem was solved before
• When building prompts that benefit from historical context
• When checking if a pattern or approach was tried previously

Do NOT use for:

• Searching code (use pnpm search:code instead)
• Searching markdown memory files (use memory-search.cjs for that)
• Real-time interaction monitoring (use perpetual-memory skill for writes)

Relationship to Existing Tools

Tool	Searches	Use For
pnpm search:code	Code files (BM25+semantic)	Finding code patterns
memory-search.cjs	Markdown memory files	Searching learnings/decisions/issues
auto-recall	perpetual_memory table	Recalling past interactions

Auto-recall is complementary -- it searches a different index (the perpetual memory vector store) that contains auto-captured interaction summaries rather than manually-written markdown entries.

Workflow

Step 1: Parse Query Intent

Before searching, classify the query intent:

Intent Type	Query Pattern	Search Strategy
Decision	"Why did we choose X", "What was decided"	Filter: category=decision
Issue	"Have we seen this error before"	Filter: category=issue
Pattern	"How do we usually handle X"	Filter: category=pattern
Learning	"What did we learn about X"	Filter: category=learning
General	Any other query	No category filter

Step 2: Search Vector Store

# Basic semantic search
node .claude/tools/cli/auto-embed.cjs --query "how does the routing guard handle Write operations" --limit 10

# Or via the skill script
node .claude/skills/auto-recall/scripts/main.cjs --query "JWT refresh token pattern" --limit 5

Step 3: Rank by Relevance + Recency

Results are ranked by cosine similarity from LanceDB. For time-sensitive queries, apply a recency boost:

final_score = similarity * 0.7 + recency_score * 0.3

where recency_score = max(0, 1 - (days_since_creation / 30))

This ensures recent interactions are slightly preferred when similarity is close.

Step 4: Inject Context

Format retrieved memories for agent prompt injection:

## Recalled Context (from perpetual memory)

1. [decision] (sim=0.87, 2d ago, agent=architect)
   Chose JWT RS256 over HS256 for key rotation support. ADR-045.

2. [learning] (sim=0.82, 5d ago, agent=developer)
   Token refresh requires httpOnly cookies to prevent XSS.

3. [issue] (sim=0.74, 1d ago, agent=qa)
   JWT expiry not propagated to frontend. Workaround in auth.middleware.ts:47.

CLI Reference

# Semantic query
node .claude/skills/auto-recall/scripts/main.cjs --query "routing guard behavior"

# Query with category filter
node .claude/skills/auto-recall/scripts/main.cjs --query "auth decision" --category decision

# Query with limit
node .claude/skills/auto-recall/scripts/main.cjs --query "memory system" --limit 5

# Query with recency boost
node .claude/skills/auto-recall/scripts/main.cjs --query "recent changes" --recency-boost

# Output as JSON
node .claude/skills/auto-recall/scripts/main.cjs --query "search" --json

Agent Integration Pattern

Agents should invoke auto-recall at the start of significant tasks:

// At task start, recall relevant context
Skill({ skill: 'auto-recall' });

// Then query for task-relevant history
// node .claude/skills/auto-recall/scripts/main.cjs --query "<task description>" --limit 5

This provides agents with historical context about similar past work, preventing repeated mistakes and leveraging prior decisions.

Iron Laws

1. NEVER use auto-recall as a replacement for memory-search.cjs -- they search different indexes and are complementary.
2. ALWAYS limit results to avoid context bloat -- default to 5-10 results, never more than 20.
3. NEVER inject recalled context without relevance filtering -- results below 0.5 similarity are noise.
4. ALWAYS include metadata (category, agent, timestamp) in recalled context for traceability.
5. NEVER block on auto-recall failure -- if the perpetual memory table is unavailable, proceed without it.

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Approach
Using auto-recall for code search	Wrong index; code is in BM25/semantic code index	Use pnpm search:code for code discovery
Injecting all results into context	Low-similarity results pollute the prompt	Filter to similarity > 0.5 before injecting
Blocking task on recall failure	Perpetual memory is a bonus, not a dependency	Gracefully degrade: proceed without recall
Recalling without specifying limit	Unbounded results consume too many tokens	Always set --limit (default: 10)
Trusting recall over fresh code analysis	Past context may be outdated	Use recall as starting context, verify current

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.