# Memory Search

> Search through saved memories and your personal workspace notes by keywords. Use when you need to recall previous conversations, information about the user, or your own knowledge notes.

- Skill: `jim60105/memory-search` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add jim60105/memory-search`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jim60105/memory-search/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jim60105 (https://skillmd.com/u/jim60105)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jim60105/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:

   ```bash
   ${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.