search-memory

name	search-memory
description	Search past decisions, procedures, learnings, or context relevant to the current task. Trigger when work connects to prior decisions, a debugging pattern resembles a past issue, the user asks about rationale, or uses recall language like "that approach" or "like before".

Find what the user already knows. Search their memories and past conversations for decisions, procedures, and context that make the current task sharper.

For continuation-style engineering work, search near the start of the task. Do not wait for the user to literally say "search memory".

When to use

Strong signals (search when):

• The user references previous work, a prior fix, or an earlier decision
• The task resumes a named feature, bug, refactor, incident, or subsystem
• The task is a review, regression, release, docs-alignment, or integration-behavior question
• A debugging pattern resembles something solved earlier
• The user asks for rationale, preferences, procedures, or recurring workflow details
• The user uses implicit recall language: "that approach", "like before", "the pattern we used"

Contextual signals (consider searching when):

• Complex debugging where prior context would narrow the search space
• Architecture discussion that may intersect with past decisions
• Domain-specific conventions the user has established before
• The current result is ambiguous and past context would make the answer sharper

When NOT to search:

• Fundamentally new topic with no prior history
• Generic syntax or API questions answerable from documentation
• User explicitly asks for a fresh perspective without prior context

Retrieval routing

If this session already exposes the Nowledge Mem MCP server, prefer:

1. memory_search for durable knowledge (decisions, insights, procedures).
2. thread_search when the user is asking about a prior conversation or exact session history.
3. thread_fetch_messages for progressive inspection of the matching thread.

Otherwise:

1. Start with nmem --json m search "query" for durable knowledge (decisions, insights, procedures).
2. Use nmem --json t search "query" --limit 5 when the user is asking about a prior conversation or exact session history.
3. If a result includes source_thread, inspect it progressively with nmem --json t show <thread_id> --limit 8 --offset 0 --content-limit 1200.

Prefer the smallest retrieval that answers the question. Do not over-fetch.

If the runtime already knows the active project or agent lane, add --space "<space name>" to these commands.

Deep mode

If results are weak or the need is conceptual/historical, try deeper matching:

nmem --json m search "query" --mode deep

Knowledge tree routing

When the user needs to browse across multiple object types, inspect nearby context, or asks for a file/tree/vault-like view, use the Knowledge Filesystem instead of only flat search.

Prefer MCP mem_fs when available:

recall "session token strategy" --in /memories -k 5
find /memories --label decisions --since 2026-01-01
grep "JWT rotation" /memories
cat /memories/by-id/<id>.memory.md

Otherwise use:

nmem fs recall "session token strategy" --in /memories -k 5
nmem fs ls /wiki
nmem fs cat /wiki/topics/<topic>.topic.md

Use recall for fuzzy phrasing, find for metadata constraints, grep for exact strings, then stat or cat the returned paths. KFS paths are Mem identifiers, not local OS files; mount and SQL/Cypher are later phases.

Filters

Add filters only when the task clearly implies them:

• By label: -l "label-name"
• By importance: --importance 0.7
• By date range: --event-from 2026-01-01 / --event-to 2026-03-01
• By source: -s codex
• Limit results: -n 10

Summarize only the strongest matches and clearly say when nothing relevant was found.

Links

• Search