memex

Search, browse, and revisit your local agent history. Memex indexes conversations from coding tools so you and your agents can find previous work, read the original transcripts, and resume sessions in their original tool where supported.

Keyword search uses BM25. Optional local embeddings add semantic and hybrid search. You can also search saved Claude and Codex memories, query history across machines over SSH, and track token usage from local logs.

Install

brew install memex

Or use the installer:

curl -fsSL https://raw.githubusercontent.com/nicosuave/memex/main/scripts/setup.sh | sh

See installation and updates for Arch Linux, Nix, Cargo, source builds, and upgrade behavior.

Quickstart

memex index                              # Index local agent history
memex                                    # Browse sessions in the terminal
memex search "deployment rollback" --format text
memex session SESSION_ID                 # Read a transcript page

In the TUI, select a session to read it or use its resume action to continue in the original agent. Resume requires that agent to be installed and its session data to remain available. See the engine support table for exceptions.

Indexing discovers supported sources automatically. To select specific engines:

memex index --only-source claude --only-source codex
memex search "deployment rollback" --source codex --project my-project

Search defaults to conversations and JSONL output. Embeddings, plaintext reasoning, and token tracking are off by default. Searches refresh stale indexes automatically; for background indexing, run memex daemon enable --continuous.

Engine support

Support varies by capability. History means indexing, searching, and reading locally available conversations. Resume opens an existing session in its original tool. Import into creates a conversation in another tool using the experimental transfer feature.

• History coverage depends on the local records a tool saves. Cursor history comes from agent transcripts; its usage data comes from local databases. Antigravity reads available transcript, SQLite, and overview projections; it does not decrypt encrypted trajectories. Its token counters are not yet supported. ZCode reads ~/.zcode/cli/db/db.sqlite, which its SSH-attached runtimes also write on remote hosts; ZCODE_HOME (comma-separated) indexes extra stores. Kiro reads ~/.kiro/sessions; set KIRO_SESSIONS_DIR for copied sessions. KiloCode CLI reads ~/.local/share/kilo/kilo.db ($XDG_DATA_HOME/kilo/kilo.db); set KILO_DATA_DIR (comma-separated) to index extra stores. Kimi Code reads ~/.kimi-code/sessions (KIMI_CODE_HOME relocates it); every agent journal, subagents included, is indexed as its own session with the parent recorded. goose keeps every session in one SQLite store under its data directory (~/.local/share/goose/sessions/sessions.db), relocatable with GOOSE_PATH_ROOT; per-turn context messages and hidden CLI sessions are skipped.
• Token usage is opt-in and depends on recorded counters. Cost estimates are not subscription charges or quota balances. Hermes history and usage are read from its local state.db; plaintext reasoning is indexed only with --include-reasoning. Copilot usage requires local OpenTelemetry export files; session transcripts alone do not supply its usage data. Kiro reports credits separately because its records do not contain token counts or costs.
• Resume uses per-engine commands, configurable in Memex. Cursor uses cursor-agent; Antigravity uses agy or antigravity. A supported command does not guarantee every historical session remains resumable in newer tool versions.
• Saved memories are separate from transcripts. Only Claude project memories and Codex memory files are discovered. Search them with --content memories, or combine them with conversations using --content all.
• Dreaming is opt-in and model-driven. memex dream sends redacted excerpts of recent sessions and saved memories to the claude or codex CLI and stores what it concludes, as cited dreams, under ~/.memex/dreams/. Nothing runs and search returns no dreams until you set [dream] enabled = true.

See source discovery and memory retrieval and usage details for formats, paths, and limitations.

Ways to use Memex

The interfaces share Memex's data, but expose different workflows. The native app READMEs describe their capabilities and platform requirements.

For the macOS app:

brew install nicosuave/tap/memex-app

The native macOS app:

The Qt companion:

For the browser:

memex web serve

To keep indexing and the browser running in the background:

memex daemon enable --web-ui
memex web open

See background indexing and Web UI authentication.

Search and read

memex search "migration failure" --format text
memex search "migration failure" --source claude --limit 10
memex search "deployment decision" --content all
memex search "project conventions" --content memories
memex sessions --cwd . --limit 5
memex session SESSION_ID
memex show --record-id RECORD_ID --machine local

Search results identify the session, source, and machine so you can retrieve the original records. Transcript reads are bounded by default and return continuation information for longer content.

Assign sessions to projects or tag them; both survive reindexing and rebuilds:

memex session set-project SESSION_ID ProjectA
memex session tag add SESSION_ID tooling
memex sessions --tag tooling

See projects and tags.

For semantic or hybrid search, first generate local embeddings:

memex index --embeddings
memex search "how we handled retries" --mode hybrid --format text

Dream

Consolidate recent history across agents into a small set of dreams: single statements, each citing the transcript records it rests on, such as corrections you keep giving, recurring mistakes, and saved memories that recent work contradicts. Opt in first with [dream] enabled = true in config.toml.

memex dream --dry-run
memex dream
memex dream show
memex search "package manager" --content all

Dreams come back from --content all beside the conversations and memories they were drawn from, so an agent recalling prior decisions gets them without a separate query. Each run publishes a new generation with a diff, and Claude and Codex memory files are never written. See dreaming.

See search and reading for filters, output formats, pagination, reasoning inclusion, and memory retrieval; see embeddings and configuration for models and CPU, CoreML, or CUDA execution. Embeddings can also come from an OpenAI-compatible API such as OpenAI or Ollama; see remote embeddings. Remote embeddings send transcript text and memory documents to that API.

Agent integration

Install the shared search skill for Codex, OpenCode, Pi, and Oh My Pi:

memex skill install --target shared

For Claude Code:

memex skill install --target claude

Restart the agent after installing or updating its skill. The skill guides it to search progressively and verify relevant source records.

For MCP clients that launch a local process:

{
  "mcpServers": {
    "memex": { "command": "memex", "args": ["mcp", "--transport", "stdio"] }
  }
}

Memex also serves authenticated Streamable HTTP with memex mcp, or alongside background indexing with `mem