memex

/memex — Search Past Claude & Codex Sessions

Search all past Claude Code and Codex sessions using full-text search with BM25 ranking.

Usage

python3 <MEMEX_SKILL_DIR>/scripts/recall.py [QUERY] [--list] [--project PATH] [--days N] [--source claude|codex] [--limit N] [--offset N] [--summary-len N] [--no-summary] [--include-subagents] [--reindex] [--json] [--version] [--doctor] [--fix]

<MEMEX_SKILL_DIR> varies by installation. Common examples:

~/.claude/skills/memex
~/.agents/skills/memex

Examples

# Simple keyword search
python3 <MEMEX_SKILL_DIR>/scripts/recall.py "bufferStore"

Phrase search (exact match)

python3 <MEMEX_SKILL_DIR>/scripts/recall.py '"ACP protocol"'

Boolean query

python3 <MEMEX_SKILL_DIR>/scripts/recall.py "rust AND async"

Prefix search

python3 <MEMEX_SKILL_DIR>/scripts/recall.py "buffer*"

Filter by project and recency

python3 <MEMEX_SKILL_DIR>/scripts/recall.py "state machine" --project ~/my-project --days 7

Search only Claude Code sessions

python3 <MEMEX_SKILL_DIR>/scripts/recall.py "buffer" --source claude

Search only Codex sessions

python3 <MEMEX_SKILL_DIR>/scripts/recall.py "buffer" --source codex

Force reindex

python3 <MEMEX_SKILL_DIR>/scripts/recall.py --reindex "test"

List recent sessions

python3 <MEMEX_SKILL_DIR>/scripts/recall.py --list --limit 20

List mode with optional text filter

python3 <MEMEX_SKILL_DIR>/scripts/recall.py --list "state machine" --limit 20

Machine-readable JSON output

python3 <MEMEX_SKILL_DIR>/scripts/recall.py --json --source codex --list "auth api"

Paginate results

python3 <MEMEX_SKILL_DIR>/scripts/recall.py --list --limit 10 --offset 10

Include subagent sessions (hidden by default)

python3 <MEMEX_SKILL_DIR>/scripts/recall.py --list --include-subagents

Hide summary lines

python3 <MEMEX_SKILL_DIR>/scripts/recall.py --list --no-summary

Shorter summaries

python3 <MEMEX_SKILL_DIR>/scripts/recall.py --list --summary-len 80

Show installed version metadata

python3 <MEMEX_SKILL_DIR>/scripts/recall.py --version

Run local health checks

python3 <MEMEX_SKILL_DIR>/scripts/recall.py --doctor

Run doctor with safe auto-fixes

python3 <MEMEX_SKILL_DIR>/scripts/recall.py --doctor --fix


## Query Syntax (FTS5)

- **Words**: `bufferStore` — matches stemmed variants (e.g., "discussing" matches "discuss")
- **Phrases**: `"ACP protocol"` — exact phrase match
- **Boolean**: `rust AND async`, `tauri OR electron`, `NOT deprecated`
- **Prefix**: `buffer*` — matches bufferStore, bufferMap, etc.
- **Combined**: `"state machine" AND test`

## After Finding a Match

To resume a session, `cd` into the project directory and use the appropriate command:

```bash
# Claude Code sessions [claude]
cd /path/to/project
claude --resume SESSION_ID

# Codex sessions [codex]
cd /path/to/project
codex resume SESSION_ID

Each result includes a File: path. Use it to read the raw transcript (auto-detects format):

python3 <MEMEX_SKILL_DIR>/scripts/read_session.py <File-path-from-result>

If results are missing File: paths, run --reindex to backfill.

Notes

Index is stored at ~/.memex.db (SQLite FTS5, auto-migrated from legacy paths)
Indexes both ~/.claude/projects/ (Claude Code) and ~/.codex/sessions/ (Codex)
Each session shows a one-line summary (first meaningful user message)
Subagent sessions are hidden by default; use --include-subagents to show them
--project matches an exact project path or child paths only
Queries with special characters (e.g. dashes) are auto-quoted; on FTS error, falls back to LIKE search
--fix can be used with --doctor to apply safe automatic fixes (e.g. auto-index when DB is empty)
First run indexes all sessions (a few seconds); subsequent runs are incremental
Automatically prunes orphaned DB rows when indexed source files are removed
Only user and assistant messages are indexed; system noise (<local-command-caveat>, <system-reminder>, etc.) is filtered
Results show [claude] or [codex] tags to indicate the source
For simple CJK queries, adds substring fallback matching to improve recall

About this skill

Usage

Examples

Notes