Memstem Search

MemStem Search

Search MemStem — the unified memory index that contains every AI agent's memories, skills, daily logs, and session captures (Ari + Claude Code today, more later). MemStem is the only place that sees cross-agent context; grep on a single workspace cannot.

When to use

Any retrieval-style question — past decisions, project status, skills lookup, prior work, fuzzy or conceptual recall. Examples:

• "what did we decide about X"
• "what's the status of Y"
• "do we have a skill for Z"
• "what did Claude Code work on yesterday"
• "find the decision about the embedder migration"

Do not grep on a single workspace before trying this. grep can't see other agents' memories or Claude Code session captures, and most of what you're looking for is already indexed in MemStem.

Procedure

This skill owns the full priority ladder. Try each rung in order; only fall through on hard failure.

1. MemStem MCP (preferred — shares process state)

If mcp__memstem__memstem_search is callable in the current session, use it:

mcp__memstem__memstem_search(query="", top_k=10)

Deferred-tool gotcha — the rule that gets missed. Claude Code does not pre-load MCP tool schemas. If a ` lists mcp__memstem__* as **deferred tools**, the names are advertised but the schemas are not loaded — calling them directly fails with InputValidationError`. Load the schemas first:

ToolSearch(query="select:mcp__memstem__memstem_search,mcp__memstem__memstem_get,mcp__memstem__memstem_list_skills,mcp__memstem__memstem_get_skill")

If a later system-reminder says the memstem MCP has disconnected, do not retry ToolSearch — fall through to step 2.

2. MemStem HTTP API (warm — same daemon, loopback only)

Check the daemon:

curl -s http://127.0.0.1:7821/health

If status: ok, search:

curl -s -X POST http://127.0.0.1:7821/search \
  -H 'Content-Type: application/json' \
  -d '{"query": "", "top_k": 10}'

This reuses the daemon's live Vault / Index / Embedder instances — same backend as the MCP, just over loopback HTTP. No subprocess cold-start.

3. MemStem CLI (cold-start, slower)

memstem search "" --top 10 --format json

Known issues — if either of these fires, report the error in one line and proceed to step 4. Do not silently swallow:

• IntegrityError: UNIQUE constraint failed: embed_state.memory_id — the index DB has duplicate rows that the connect-time backfill tries to re-insert.
• embedder unavailable: GEMINI_API_KEY — the CLI runs in a shell with no GEMINI_API_KEY exported. The MCP and the daemon have it baked into their env via the OS-level config; the CLI does not.

4. Fallback — grep + direct file reads

Only when steps 1–3 are all unavailable.

grep -rli "" ~/ari/memory/ ~/ari/MEMORY.md ~/ari/skills/*/SKILL.md

Or read known files directly: ~/ari/MEMORY.md, today's daily log ~/ari/memory/YYYY-MM-DD.md, a specific SKILL.md.

This rung sees only the local Ari workspace — not Claude Code session captures, not other agents' memories, not the semantic index. Note this gap when you report results so the caller knows the answer may be incomplete.

Result format

Return a concise summary, not a dump. For each top hit:

• one-line title or excerpt
• file path or memory id (so the caller can navigate)
• relevance signal (rank, score) when available

Do not paste full memory bodies unless the caller asks — assume they will follow the path.

Reporting failures

If the entire ladder fails (rare — would mean MemStem is fully down and the workspace has nothing relevant on disk), say so explicitly. Do not pretend a no-result fallback is the same as a successful empty search.

Do NOT

• Default to openclaw memory search, memory_search, memory_get — legacy paths, lower-quality recall, blind to Claude Code captures.
• Use Claude Code's built-in ~/.claude/projects/*/memory/ — disabled in this environment; MemStem is the single source of truth.
• Skip rungs because you "feel like" the answer is somewhere specific. The point of MemStem is that the index decides; the caller does not need to know where the fact lives.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Memstem
• Source: Memstem/memstem
• License: MIT

Install and usage instructions live in the source repository linked above.