Memory Search

Memory Search Skill

Search through saved memories to retrieve relevant information.

Usage

Two-step flow — the search query MUST NOT appear on the command line.

1. Write the query text to a payload file under the session staging directory using your edit/write tool:

   $TMPDIR/$SESSION_ID/query.md
   

   The $TMPDIR / $SESSION_ID tokens in that path are expanded by the ACP path boundary, so the write is approved and the text bytes are preserved verbatim (no shell expansion). $TMPDIR/$SESSION_ID/ is the per-spawn form of the staging directory; in shared-process deployments the staging directory is shown in your system prompt and the script resolves it automatically.

2. Invoke the script with the payload file path:

   ${HOME}/.agents/skills/memory-search/scripts/memory-search.ts \
     --session-id "$SESSION_ID" \
     --query-file "$TMPDIR/$SESSION_ID/query.md" \
     --limit 10
   
   # Filter by category and scope
   ${HOME}/.agents/skills/memory-search/scripts/memory-search.ts \
     --session-id "$SESSION_ID" \
     --query-file "$TMPDIR/$SESSION_ID/query.md" \
     --category preference \
     --scope user
   

WARNING: Never put the query on the command line. The legacy --query "..." / --query=... flag is REMOVED: the shell expands $VAR in it, which corrupts the search and can leak environment variables.

Parameters

• --query-file: (Required) Path of the payload file containing the search keywords
• --limit: (Optional) Maximum number of results (default: 10)
• --category: (Optional) Filter results by category: fact, preference, episode, summary, or relationship
• --scope: (Optional) user, channel, or omit to search both user and channel memories

Error Codes

If the script fails, read the JSON error on stderr. It contains the fix. Common codes: SKILL_LEGACY_FLAG (you used the removed --query flag — stage the text in $TMPDIR/$SESSION_ID/query.md and use --query-file), SKILL_MISSING_PAYLOAD (no --query-file given), SKILL_PAYLOAD_OUT_OF_BOUNDS (payload path outside $TMPDIR/$SESSION_ID/), SKILL_PAYLOAD_NOT_FOUND (payload file not written yet — write it first with the edit/write tool).

Response Format

Results include tier, category, scope, and decay fields for each memory entry. Results are sorted by decay-weighted relevance (higher decay × relevance score = higher ranking).

Critical Rules

1. Timeout: The script won't run for more than 30 seconds. If it hangs, do stop_bash and do not retry, return an error message in JSON format.