---

name: mem user-invocable: false description: Search and retrieve context from past Claude sessions. Triggers on 'search memory', 'find past sessions', 'what did we learn about', 'have we done this before', 'what did we decide about', 'what did I work on yesterday', 'remind me what we did', or when disoriented about past work ("I'm lost", "where were we?"). (user)

Reference Files Quick Index

When you need...

• Full CLI reference → references/COMMANDS.md
• Search workflow patterns → references/WORKFLOWS.md
• Troubleshooting → references/TROUBLESHOOTING.md

Read SKILL.md first, then load specific references as needed.

---

Memory Primitives

Search and retrieve context from past Claude sessions.

When to Use

Automatic triggers:

• User asks about past work: "What did we decide...", "Have we done this before...", "When did we..."
• Daily recap requests: "What did I work on yesterday?", "Remind me what we did"
• User seems confused about context: "Didn't we already...", "I thought we..."
• Starting work on a topic with likely history

When NOT to Use

• Simple question-answering (no history needed)
• Work with clear handoff context already loaded
• Greenfield projects with no session history
• Single-session tasks with no prior context

---

Core Primitives

All commands require uv run from ~/Repos/claude-mem:

1. Search

Copyuv run mem search "query"              # FTS5 full-text search
uv run mem search "query" --type X     # Filter by source type
uv run mem search "query" --project .  # Current project only
uv run mem search "query" -n 20        # More results (default: 10)

Source types: claude_code, handoff, claude_ai, cloud_session

2. Drill (Progressive Disclosure)

Copyuv run mem drill <id>              # Extraction summary (default)
uv run mem drill <id> --outline    # Extraction + numbered turn index
uv run mem drill <id> --turn N     # Specific turn in full
uv run mem drill <id> --full       # All turns (truncated)

3. Recent

Copyuv run mem recent              # Current project's recent activity
uv run mem recent --all        # All sources
uv run mem recent --days 14    # Custom timeframe (default: 7)
uv run mem recent --all --by-project  # Group by project with session counts

Daily recap pattern: --all --by-project shows "infra-openwrt (8 sessions)" style summary — useful for "what did I work on yesterday?"

4. Status

Copyuv run mem status              # Database stats and coverage

---

Progressive Disclosure Pattern

The unfolding label: Don't load full conversations immediately.

CopySearch → Find relevant sources by keyword
   ↓
Triage → Read extraction summaries (arc, learnings, builds)
   ↓
Drill  → Only load full content if extraction isn't enough

Extraction summaries include:

• Arc: Started → Turns → Ended (conversation shape)
• Builds: What was created
• Learnings: Insights with "why it matters"
• Patterns: Reusable approaches discovered
• Open threads: Unfinished work

The extraction is decision support for whether to drill deeper—not a replacement for full context when details matter.

---

Feedback: Filing Issues

When encountering problems with memory search or quality, file a structured bead. This helps improve the system.

When to File (Without Asking User)

• Search returning wrong/no results for known content
• Extraction missing key learnings or builds
• CLI errors or crashes
• Skill not triggering on expected phrases

Structured Templates

Search issues:

Copybd create "memory: search not finding [topic]" \
  --type bug \
  --description "Query '[query]' should find [expected] but returns [actual]" \
  --design "$(cat <<'EOF'
## Query Details
- Query: [exact query string]
- Filters: [--type, --project if used]
- Source ID (if known): [where content exists]

## Expected
[What should be found]

## Actual
[What was returned]
EOF
)"

Extraction quality:

Copybd create "memory: extraction missing [type]" \
  --type bug \
  --description "Source [id] missing [learnings/builds/arc]" \
  --design "$(cat <<'EOF'
## Source
- ID: [source_id]
- Topic: [what the session was about]

## Missing
[What should have been extracted]

## Why It Matters
[Impact on search/discovery]
EOF
)"

CLI bugs:

Copybd create "memory: [brief error]" \
  --type bug \
  --description "[Error message]" \
  --design "$(cat <<'EOF'
## Command
[Exact command run]

## Expected
[What should happen]

## Actual
[Error or unexpected behavior]
EOF
)"

Skill discovery:

Copybd create "memory: skill not triggering on '[phrase]'" \
  --type enhancement \
  --description "Expected memory skill on '[phrase]' but didn't trigger" \
  --design "$(cat <<'EOF'
## Trigger Phrase
[What user said]

## Why It Should Trigger
[Reasoning]

## Suggested Addition
[Phrase to add to description]
EOF
)"

---

Anti-Patterns

---

Integration Points

Consumed by:

• /open command → can check recent activity

Depends on:

• mem CLI installed (via uv run mem from ~/Repos/claude-mem)
• Database populated (mem scan has been run)
• API key for extraction (~/.claude/memory/env)

---

Quick Reference

For detailed CLI reference: See references/COMMANDS.md