skilld
All skills
obra avatar

/remembering-conversations

@bb6346c
by Jesse Vincentobra/clank41 stars
27

Search previous Claude Code conversations for facts, patterns, decisions, and context using semantic or text search

Ask your Agent

Use this Skill: https://skilld.dev/gh/obra/clank/remembering-conversations

This session only. Nothing lands on disk.

INDEXING.md

≈887 tokens on demand. Your agent reads this file only when SKILL.md points to it.

Managing Conversation Index

Index, archive, and maintain conversations for search.

Quick Start

Install auto-indexing hook:

~/.claude/skills/collaboration/remembering-conversations/tool/install-hook

Index all conversations:

~/.claude/skills/collaboration/remembering-conversations/tool/index-conversations

Process unindexed only:

~/.claude/skills/collaboration/remembering-conversations/tool/index-conversations --cleanup

Features

  • Automatic indexing via sessionEnd hook (install once, forget)
  • Semantic search across all past conversations
  • AI summaries (Claude Haiku with Sonnet fallback)
  • Recovery modes (verify, repair, rebuild)
  • Permanent archive at ~/.clank/conversation-archive/

Setup

1. Install Hook (One-Time)

cd ~/.claude/skills/collaboration/remembering-conversations/tool
./install-hook

Handles existing hooks gracefully (merge or replace). Runs in background after each session.

2. Index Existing Conversations

# Index everything
./index-conversations

# Or just unindexed (faster, cheaper)
./index-conversations --cleanup

Index Modes

# Index all (first run or full rebuild)
./index-conversations

# Index specific session (used by hook)
./index-conversations --session <uuid>

# Process only unindexed (missing summaries)
./index-conversations --cleanup

# Check index health
./index-conversations --verify

# Fix detected issues
./index-conversations --repair

# Nuclear option (deletes DB, re-indexes everything)
./index-conversations --rebuild

Recovery Scenarios

Situation Command
Missed conversations --cleanup
Hook didn't run --cleanup
Updated conversation --verify then --repair
Corrupted database --rebuild
Index health check --verify

Troubleshooting

Hook not running:

  • Check: ls -l ~/.claude/hooks/sessionEnd (should be executable)
  • Test: SESSION_ID=test-$(date +%s) ~/.claude/hooks/sessionEnd
  • Re-install: ./install-hook

Summaries failing:

  • Check API key: echo $ANTHROPIC_API_KEY
  • Check logs in ~/.clank/conversation-index/
  • Try manual: ./index-conversations --session <uuid>

Search not finding results:

  • Verify indexed: ./index-conversations --verify
  • Try text search: ./search-conversations --text "exact phrase"
  • Rebuild if needed: ./index-conversations --rebuild

Excluding Projects

To exclude specific projects from indexing (e.g., meta-conversations), create:

~/.clank/conversation-index/exclude.txt

# One project name per line
# Lines starting with # are comments
-Users-yourname-Documents-some-project

Or set env variable:

export CONVERSATION_SEARCH_EXCLUDE_PROJECTS="project1,project2"

Storage

  • Archive: ~/.clank/conversation-archive/<project>/<uuid>.jsonl
  • Summaries: ~/.clank/conversation-archive/<project>/<uuid>-summary.txt
  • Database: ~/.clank/conversation-index/db.sqlite
  • Exclusions: ~/.clank/conversation-index/exclude.txt (optional)

Technical Details

  • Embeddings: @xenova/transformers (all-MiniLM-L6-v2, 384 dimensions, local/free)
  • Vector search: sqlite-vec (local/free)
  • Summaries: Claude Haiku with Sonnet fallback (~$0.01-0.02/conversation)
  • Parser: Handles multi-message exchanges and sidechains

See Also

  • Searching: See SKILL.md for search modes (vector, text, time filtering)
  • Deployment: See DEPLOYMENT.md for production runbook

Source: SKILL.md on GitHub

Third-party checks

1 warning4mo3 checks · Risk MEDIUM
  • Gen Agent Trust Hub4mo

    This skill provides a comprehensive system for indexing and searching past Claude conversations using semantic search and AI-generated summaries. It implements a persistence mechanism via a platform hook to automatically update its index, which is its primary functional feature. The skill uses local models for embeddings to maintain privacy while sending data to Anthropic for summarization via the official platform SDK.

  • Socket4mo

    No alerts

  • Snyk4mo

    Risk: LOW · No issues

Provenance

Signed by skilld at bb6346c. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 months ago.

Dormantupdated last year

Capability

version
1.0.0
Other metadata
when_to_use
When your human partner mentions "we discussed this before". When debugging similar issues. When looking for architectural decisions or code patterns from past work. Before reinventing solutions. When you need to find a specific git SHA or error message.

Topics

  • Debugging
  • conversation-search
  • semantic-search
  • context-retrieval
  • claude-code
  • decision-tracking
  • architecture

README badge

README badge for obra/clank

What it does

Searches archived Claude Code conversations by semantic similarity or exact text match to recover facts, architectural decisions, code patterns, and debugging context from past sessions. Use it when your human mentions "we discussed this before" or when debugging recurring issues to avoid reinventing solutions.

Generated from the current SKILL.md.

Frequently asked

How do I search conversations outside of Claude Code?
Use the CLI tool at ~/.claude/skills/collaboration/remembering-conversations/tool/search-conversations with a query string. Supports vector similarity (default), exact text match (--text flag), or both modes.
What's the difference between semantic and text search?
Semantic search finds conceptually similar conversations; text search matches exact strings like git SHAs or error messages. Use --text for precise matches and the default mode for topic-based lookups.
Can I filter search results by date?
Yes. Use --after YYYY-MM-DD and --before YYYY-MM-DD flags to narrow results to a specific time range.
When should I use this skill instead of searching the current conversation or codebase?
Search previous conversations when looking for architectural decisions, past code patterns, or context from earlier sessions. Use Grep/Read for info already in the current conversation or codebase.
Does this skill require setup?
Yes. Refer to INDEXING.md in the skill directory for initial setup instructions before using the search tool.

Generated from the current SKILL.md. These answers refresh after source changes.