Skip to content

README.md

Latest commit

 

History

History
130 lines (88 loc) · 4.3 KB

README.md

File metadata and controls

130 lines (88 loc) · 4.3 KB

memsearch — Codex CLI Plugin

Automatic persistent memory for Codex CLI. Every conversation turn is summarized and indexed — your next session picks up where you left off.

Prerequisites

Install

# 1. Install memsearch
uv tool install "memsearch[onnx]"

# 2. Clone the repo and run the installer
git clone https://github.com/zilliztech/memsearch.git
cd memsearch
bash plugins/codex/scripts/install.sh

The installer sets up everything automatically:

  • Copies the memory-recall skill to ~/.agents/skills/
  • Installs or updates memsearch hook entries in ~/.codex/hooks.json
  • Enables the hooks feature flag

Usage

Start Codex with a full-access mode so hooks can run and the ONNX model can download on first use:

codex --dangerously-bypass-approvals-and-sandbox

Why full access? The ONNX embedding model needs network on first run to download from HuggingFace (~100 MB). After that it's cached locally. Codex's default sandbox blocks network, which prevents model download and can interfere with hook-launched shell commands. On current Codex builds, --dangerously-bypass-approvals-and-sandbox is the explicit full-access flag. Some builds may also accept the older --yolo alias.

Pre-cache the model (optional) — run once so subsequent sessions work even if you later tighten sandboxing:

memsearch search "test" --collection test_warmup 2>/dev/null; memsearch reset --collection test_warmup --yes 2>/dev/null

What happens automatically

When What
Session starts Recent memory context is injected; you'll see [memsearch v...] in the status line
Each prompt A [memsearch] Memory available hint reminds Codex that memory-recall is available
Each turn ends The conversation is summarized and saved to a daily .md file

Search past memories

Use the $memory-recall skill:

$memory-recall what did we discuss about batch size limits?

Codex will search your memory, expand relevant results, and return a curated summary. The skill uses three-layer progressive disclosure:

  1. Search — memsearch search finds relevant chunks by semantic + keyword hybrid search
  2. Expand — memsearch expand retrieves the full markdown section around a match
  3. Deep drill — when rollout anchors are available, optionally parses the original Codex rollout transcript for exact conversation context

Configuration

Embedding provider

Default is onnx (bge-m3) — runs locally, no API key needed.

# Switch to OpenAI embeddings (requires OPENAI_API_KEY)
memsearch config set embedding.provider openai

# Switch back to local ONNX
memsearch config set embedding.provider onnx

Milvus backend

Default is Milvus Lite (local .db file). For larger memory stores or team sharing:

# Use a remote Milvus server
memsearch config set milvus.uri http://localhost:19530

Summarization routing

The Stop hook uses its built-in Codex summarize model by default. To override only this plugin's native capture model:

memsearch config set plugins.codex.summarize.model gpt-5.1-codex-mini

To use a memsearch-managed API provider instead:

memsearch config set llm.providers.openai.type openai
memsearch config set llm.providers.openai.model gpt-5-mini
memsearch config set llm.providers.openai.api_key env:OPENAI_API_KEY
memsearch config set plugins.codex.summarize.provider openai

Leave plugins.codex.summarize.provider empty or set it to native to keep the current default. This setting does not fall back to llm.model.

Memory files

Each project stores memory under <project>/.memsearch/memory/:

.memsearch/memory/
├── 2026-03-20.md
├── 2026-03-21.md
└── 2026-03-24.md

These are plain markdown files — human-readable, editable, and version-controllable. Milvus is a derived index that can be rebuilt anytime from these files.

Uninstall

Remove only memsearch's hook entries from ~/.codex/hooks.json so unrelated Codex hooks stay intact. The safe uninstall steps are documented in docs/platforms/codex/installation.md.

Updating

cd memsearch
git pull
bash plugins/codex/scripts/install.sh