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 nicosuave/tap/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.
• Token usage is opt-in and depends on recorded counters. Cost estimates are not subscription charges or quota balances. Hermes support reads usage counters and metadata only, not message content. Copilot usage requires local OpenTelemetry export files; session transcripts alone do not supply its usage data.
• 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.

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.

For semantic or hybrid search, first generate local embeddings:

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

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.

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 memex daemon enable --mcp. See the MCP guide for client setup, OAuth, remote access, and the retrieval tool contracts.

Multiple machines over SSH

Each machine keeps its own index. Memex queries configured machines over SSH and returns results with their originating machine attached. Unavailable machines produce partial results with a warning.

memex search "deployment rollback" --machine mini
memex session SESSION_ID --machine mini

Install Memex on each machine and add its SSH configuration to ~/.memex/config.toml. See multiple-machine setup for a complete example and remote reading and resume behavior.

Token usage

Enable local usage tracking in ~/.memex/config.toml:

token_usage = true

memex usage
memex usage --source codex --since 2026-09-01

Usage is reconstructed from each engine's local records. Costs prefer recorded request prices and otherwise use a built-in price catalog; calculated values are API-equivalent estimates, not subscription charges. Missing prices remain visibly unpriced. See usage and cost estimates for details.

Experimental session transfers

memex transfer imports an indexed conversation into Codex, Claude Code, Copilot CLI, Cursor, OpenCode, or Pi. This is experimental, and compatibility depends on the destination tool's version and storage format.

Transfers reconstruct conversation content; they do not migrate the complete agent runtime, workspace files, permissions, or executable tool state. Use native resume when you want to continue the original session in the same tool.

# Generate an intermediate transcript without importing into the destination
memex transfer SESSION_ID --source claude --to codex --dry-run

# Import the conversation into the destination tool
memex transfer SESSION_ID --source claude --to codex

• --mode compact (default) imports cleaned user and assistant text.
• --mode strict also includes tool activity as text notes. It does not provide a lossless native-session migration.
• --turns N limits the history included. Pi defaults to the last 60 user turns and caps imports at 400.
• --source disambiguates session IDs present in more than one engine.

The command reads the local Memex index. A dry run still writes a generated transcript file, but does not import it into the target. A successful import prints the destination information and a resume command; it does not validate that the destination can reproduce the original session's behavior.

Reference