memsearch + Codex memory recall (on-demand)

Generated by: Codex Supercharge maintenance automation.

This skill is for manual recall using the memsearch CLI. It does not install hooks or run upstream installers.

Reference notes: references/memsearch-codex-memory.md.

Preconditions

• Prefer .memsearch/memory/ if it exists.
• If there is no .memsearch/memory/, fall back to $agent-memory-ledger and rg across .codex-memory/.
• If memsearch is not installed, stop and ask the user whether they want to install it. Do not run curl | sh installers.

Workflow

1. Confirm the memory store location:

   • PROJECT_ROOT/.memsearch/memory/ (preferred)
   • otherwise .codex-memory/ + rg fallback

2. Derive a stable project collection, then index memory when needed:

PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
COLLECTION="$(plugins/codex-supercharge/scripts/derive_memsearch_collection.sh "$PROJECT_ROOT")"
memsearch index "$PROJECT_ROOT/.memsearch/memory" --collection "$COLLECTION"

If indexing fails because the ONNX embedding model needs a first-run download, either:

• temporarily allow network access, or
• switch to a provider you already have configured (high-trust only).

3. Search for relevant chunks and expand the best hit:

memsearch search "<query>" --top-k 5 --json-output --collection "$COLLECTION"
memsearch expand <chunk_hash> --collection "$COLLECTION"

4. If expand fails, read the source file directly using the source and line-range fields from JSON output:

sed -n '<start_line>,<end_line>p' "<source>"

5. Return a curated summary:
   • focus on decisions, constraints, prior fixes, and “why”
   • cite the memory file/date (and heading if present)
   • if nothing relevant: say so, and propose a tighter query

Skip when

• The task is purely about the current repo state (prefer Read/Grep/tests).
• The user asked to ignore memory or avoid semantic tools.
• There is no .memsearch/memory/ and the user does not want to create one.

Validation

• If memsearch exists: memsearch --version and a dry run search against a small collection.
• Otherwise: ensure the fallback path uses $agent-memory-ledger + rg.
• Validate the helper with plugins/codex-supercharge/scripts/derive_memsearch_collection.sh "$PWD".