Agent-Skills.md

Agent Skills: 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.

UncategorizedID: nicosuave/memex/memex-search

Repository

nicosuave/memex
nicosuaveLicense: MIT
7

Skill Files

Browse the full folder contents for memex-search.

Download Skill

Loading file tree…

skills/memex-search/SKILL.md

Skill Metadata

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.

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.

Recommended LLM Flow

  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>