memex-search

Search, filter, and retrieve Claude/Codex history indexed by the memex CLI. Use when the user wants to index history, run lexical/semantic/hybrid search, fetch full transcripts, or produce LLM-friendly JSON output for RAG.

⭐2stars🔀0forks📁View on GitHub🕐Updated Jan 4, 2026⬇️1downloads

When & Why to Use This Skill

Memex Search is a high-performance Claude skill designed to index, filter, and retrieve local Claude and Codex interaction history. It enables users to perform advanced lexical, semantic, and hybrid searches across past sessions, providing structured, LLM-friendly JSON output. By serving as a long-term memory layer, it allows AI agents to leverage historical context for Retrieval-Augmented Generation (RAG), ensuring continuity and data-driven insights across multiple coding or research sessions.

Use Cases

  • RAG Context Enhancement: Automatically retrieving relevant past conversation snippets to provide deep context for current tasks, significantly improving the accuracy of AI-generated code and solutions.
  • Technical Troubleshooting: Searching through historical 'tool_result' logs to identify when and why a specific command failed in previous sessions, facilitating faster debugging.
  • Knowledge Retrieval: Using semantic search to find specific concepts or logic discussed in past Claude/Codex transcripts without needing to remember exact keywords.
  • Session Auditing and Sharing: Exporting encrypted, structured transcripts of complex agentic workflows to share with team members for collaborative review or documentation.
namememex-search
descriptionSearch, filter, and retrieve Claude/Codex history indexed by the memex CLI. Use when the user wants to index history, run lexical/semantic/hybrid search, fetch full transcripts, or produce LLM-friendly JSON output for RAG.
allowed-toolsBash(memex:*)

Memex Search

Use this skill to index local history and retrieve results in a structured, LLM-friendly way.

Indexing

  • Build or update the index (incremental):
    • memex index
  • Continuous index:
    • memex index-service enable --continuous
  • Full rebuild (clears index):
    • memex reindex
  • Embeddings are on by default.
  • Disable embeddings:
    • memex index --no-embeddings
  • Backfill embeddings only:
    • memex embed
  • Common flags:
    • --source <path> for Claude logs
    • --include-agents to include agent transcripts
    • --codex/--no-codex to include or skip Codex logs
    • --model <minilm|bge|nomic|gemma|potion> to select embedding model
    • --root <path> to change data root (default: ~/.memex)

Search (LLM default JSON)

Run a search; output is JSON lines by default.

memex search "query" --limit 20

Each JSON line includes:

  • doc_id, ts (ISO), session_id, project, role, source_path
  • text (full record text)
  • snippet (trimmed single-line summary)
  • matches (offsets + before/after context)
  • score (ranked score)

Mode decision table

Need Command
Exact terms search "exact term"
Fuzzy concepts search "concept" --semantic
Mixed search "term concept" --hybrid

Filters

  • --project <name>
  • --role <user|assistant|tool_use|tool_result>
  • --tool <tool_name>
  • --session <session_id> (search inside a transcript)
  • --source claude|codex
  • --since <iso|unix> / --until <iso|unix>
  • --limit <n>
  • --min-score <float>

Grouping / dedupe

  • --top-n-per-session <n> (top n per session)
  • --unique-session (same as top-k per session = 1)
  • --sort score|ts (default score)

Output shape

  • JSONL default (one JSON per line)
  • --json-array for a single JSON array
  • --fields score,ts,doc_id,session_id,snippet to reduce output
  • -v/--verbose for human output

Background index service (macOS launchd)

memex index-service enable
memex index-service enable --continuous
memex index-service disable

Narrow first (fastest reducers)

  1. Global search with --limit
  2. Reduce with --project and --since/--until
  3. Optionally --top-n-per-session or --unique-session
  4. memex session <id> for full context

Practical narrowing tips

  • Start with exact terms (quoted) before hybrid if results are noisy.
  • Use --unique-session to collapse PR-link spam fast.
  • Use --min-score to prune low-signal hits.
  • Use --sort ts when you want a timeline view.
  • Use --role assistant for narrative outcomes; --role tool_result for command errors.
  • For a specific session, prefer search "<term>" --session <id> --sort ts --limit 50 to jump to outcomes.

Config

Create ~/.memex/config.toml (or <root>/config.toml if you use --root):

embeddings = true
auto_index_on_search = true
model = "potion"  # minilm, bge, nomic, gemma, potion
scan_cache_ttl = 3600  # seconds (default 1 hour)
index_service_mode = "interval"  # interval or continuous
index_service_interval = 3600  # seconds (ignored when mode = "continuous")
index_service_poll_interval = 30  # seconds

auto_index_on_search runs an incremental index update before each search. scan_cache_ttl sets the maximum scan staleness for auto-indexing. index-service reads config defaults (mode, interval, log paths). Flags override. Service logs and the plist live under ~/.memex by default.

Recommended when embeddings are on (especially non-potion models): run the background index service or index --watch, and consider setting auto_index_on_search = false to keep searches fast.

Semantic and Hybrid

  • Semantic: --semantic
  • Hybrid (BM25 + vectors, RRF): --hybrid
  • Recency tuning:
    • --recency-weight <float>
    • --recency-half-life-days <float>

Fetch Full Context

  • One record:
    • memex show <doc_id>
  • Full transcript:
    • memex session <session_id>

Both commands return JSON by default.

Human Output

Use -v/--verbose for human-readable output:

  • memex search "query" -v
  • memex show <doc_id> -v
  • memex session <session_id> -v

Sharing Sessions

Share a session transcript via agentexport (requires brew install nicosuave/tap/agentexport):

memex share <session_id>
memex share <session_id> --title "Bug fix session"

Returns an encrypted share URL like https://agentexports.com/v/abc123#key.

In the TUI (memex tui), press S to share the selected session.

  1. memex search "query" --limit 20
  2. Pick hits using matches or snippet
  3. memex show <doc_id> or memex session <session_id>
  4. Refine with --session, --role, or time filters
  5. Share relevant sessions with memex share <session_id>