memex

Fast local history search for Claude, Codex CLI, Cursor, OpenCode, Pi, Oh My Pi, OpenClaw, GitHub Copilot CLI, Grok, Jcode, and Muse. Also supports Hermes usage records. Uses BM-25 and optionally embeds your transcripts locally for hybrid search.

Agents can use Memex through its MCP server or CLI skill. Ask about a previous session, then narrow the search and retrieve source records as needed.

Includes a TUI for browsing, finding and resuming agent CLI sessions, with optional token usage tracking.

A native macOS companion is available in apps/macos, with a three-column browser and collapsed tool activity. Build and launch it with apps/macos/scripts/launch.sh; no Xcode GUI is required.

Install

brew install nicosuave/tap/memex

Or

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

Or (from the AUR on Arch Linux):

paru -S memex

Or (with Nix):

nix run github:nicosuave/memex

Development shell:

nix develop

Note: No binary cache is configured, so first builds compile from source.

NixOS service:

Enable background indexing with the provided module:

{
  inputs.memex.url = "github:nicosuave/memex";

  outputs = { nixpkgs, memex, ... }: {
    nixosConfigurations.default = nixpkgs.lib.nixosSystem {
      modules = [
        memex.nixosModules.default
        {
          services.memex = {
            enable = true;
            continuous = true; # Run as a daemon (optional)
          };
        }
      ];
    };
  };
}

Home Manager:

Configure memex declaratively (generates ~/.memex/config.toml):

{
  inputs.memex.url = "github:nicosuave/memex";

  outputs = { memex, ... }: {
    # Inside your Home Manager configuration
    modules = [
      memex.homeManagerModules.default
      {
        programs.memex = {
          enable = true;
          settings = {
            embeddings = true;
            include_reasoning = false;
            model = "minilm";
            execution_provider = "auto"; # coreml on macOS, cpu elsewhere
            cuda_device_id = 0; # optional when execution_provider = "cuda"
            cuda_library_paths = ["/usr/local/cuda/lib64"]; # optional override
            cudnn_library_paths = ["/usr/lib/x86_64-linux-gnu"]; # optional override
            compute_units = "ane"; # CoreML only: ane, gpu, cpu, all
            auto_index_on_search = true;
            token_usage = false; # opt in to local token and cost tracking
            index_service_interval = 3600;
          };
        };
      }
    ];
  };
}

Then install the shared skill used by Codex, OpenCode, Pi, and Oh My Pi:

memex skill install --target shared

The shared memex-search skill is installed once at ~/.agents/skills/memex-search/SKILL.md for Codex, OpenCode, Pi, and Oh My Pi. For Claude Code, use memex skill install --target claude; its copy lives at ~/.claude/skills/memex-search/SKILL.md.

Launching memex in a human terminal offers an update when a newer release is available. Press Enter to update Memex and refresh its installed skill copies, or choose no to continue into the TUI. Homebrew installs run brew update followed by brew upgrade nicosuave/tap/memex; skills are refreshed by the newly installed binary. After updating, run memex again to start that version.

Agents and scripts still receive update notices but never a startup prompt. Memex recognizes CI, Codex, and Claude Code environment markers; use --non-interactive explicitly for other agents, including those using a PTY. Bare noninteractive memex prints help, while search and other data commands run normally. To update:

memex update --yes

Without --yes, explicit memex update requires a human terminal and confirmation. Both update paths replace existing shared/Claude skill copies, including local edits; they do not install missing copies. Restart your agent after its skill is updated.

Searches warn on stderr when an installed skill differs from the running binary (outdated or locally modified). memex skill status shows which copies differ; memex skill update refreshes skills without upgrading Memex. Searches never update anything or prompt, and JSONL/TOON output on stdout stays clean. Use memex skill cleanup to explicitly remove obsolete paths from older releases.

Release checks have a two-second network timeout and are cached for six hours (failed checks retry after five minutes). --no-update-check skips release checks without hiding stale-skill warnings. Install never overwrites a differing skill file.

Quickstart

Index (incremental):

memex index

The main search, indexing, and maintenance commands are organized as follows:

Index all supported sources by default. Use repeatable --only-source <source> or --exclude-source <source> options to select providers, and --claude-path <path> to use a non-default Claude projects directory. Index sources are claude, codex, cursor, opencode, pi, omp, openclaw, copilot, grok, jcode, and muse.

Agent memories

Indexing also discovers Claude project memories (projects/*/memory/**/*.md) and Codex's memories/MEMORY.md, memory_summary.md, and rollout_summaries/*.md. Discovery follows the existing Claude roots, --claude-path, Codex homes, provider selection, and path exclusions. Raw memory intermediates, generated skills, and unrelated project storage are not memory sources. Memex never edits these files.

Memories are documents, not sessions. They have a stable document ID, a content version, and sections for retrieval. A changed file replaces all its indexed sections atomically; deleted sections and files disappear on the next scan. Renames are treated as removal and addition. If a source cannot be read, Memex keeps the last good copy and marks its freshness instead of treating an error as a deletion. Memory snapshots are stored under the Memex data root's memory/ directory, separately from conversation records and session analytics.

For recall of prior decisions, preferences, project conventions, or previous work, use --content all to search memories and conversations together. Use --content memories to inspect saved notes specifically. Search without --content remains conversation-only. Provider selection remains independent: --source claude selects the provider, not the content type. Memory results carry document/section references, source paths, scope, freshness, and content versions. For scoped memories, --project uses the repository name across Git worktrees; --cwd selects the exact checkout. Each memory keeps its own source path and ID. Their timestamp filters use file modification time; dates explicitly recorded inside a note are separate metadata and do not imply that its claims are current.

Memory retrieval uses the existing search and show interfaces. Session listing, session reads, session batch, and conversation context keep their established meaning. A memory read uses a returned document ID rather than an arbitrary file path. If the version changed since search, the read identifies that change and returns bounded current document content rather than applying an obsolete section position to the new file.

The existing daemon handles updates; there is no second memory service. MCP uses the same search/read implementation, with structured provenance and bounded content. Retrieved notes are historical evidence, not instructions for the consuming agent. Explicit links can provide supporting documents or conversations; conflicting notes remain separately attributable rather than being silently merged.

memex search "deployment decision" --content all
memex search "deployment decision" --content memories --source codex
memex show --memory-id <memory_id> --section <section_ref> --content-version <content_version> --machine <machine>

search, sessions, session, session batch, show, context, and usage support --format jsonl|json|text; search also supports toon. Search, session listings, transcript pages, and batch reads keep JSONL as their default. show and context default to one JSON object, while usage defaults to text.

Modern OpenCode sessions stored in opencode*.db under ~/.local/share/opencode are discovered automatically, alongside OpenCode's legacy JSON storage. To use one or more alternate data roots, set OPENCODE_DATA_DIR to a comma-separated list of directories before running the installed memex binary.

The default scan indexes Pi sessions from ~/.pi/agent/sessions and Oh My Pi sessions separately from ~/.omp/agent/sessions plus named profile session directories.

Plaintext reasoning is excluded by default because it is usually low-value search noise. Opt in with memex index --include-reasoning; reasoning records remain BM25-only. Encrypted and redacted payloads, along with reasoning signature fields, are always excluded.

Search (JSONL default):

memex search "your query" --limit 20

Search output is compact by default. Each hit conta