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.
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.
| name | memex-search |
|---|---|
| description | 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. |
| allowed-tools | Bash(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-agentsto include agent transcripts--codex/--no-codexto 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_pathtext(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-arrayfor a single JSON array--fields score,ts,doc_id,session_id,snippetto reduce output-v/--verbosefor human output
Background index service (macOS launchd)
memex index-service enable
memex index-service enable --continuous
memex index-service disable
Narrow first (fastest reducers)
- Global search with
--limit - Reduce with
--projectand--since/--until - Optionally
--top-n-per-sessionor--unique-session memex session <id>for full context
Practical narrowing tips
- Start with exact terms (quoted) before hybrid if results are noisy.
- Use
--unique-sessionto collapse PR-link spam fast. - Use
--min-scoreto prune low-signal hits. - Use
--sort tswhen you want a timeline view. - Use
--role assistantfor narrative outcomes;--role tool_resultfor command errors. - For a specific session, prefer
search "<term>" --session <id> --sort ts --limit 50to 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" -vmemex show <doc_id> -vmemex 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.
Recommended LLM Flow
memex search "query" --limit 20- Pick hits using
matchesorsnippet memex show <doc_id>ormemex session <session_id>- Refine with
--session,--role, or time filters - Share relevant sessions with
memex share <session_id>