/mem-search

name: mem-search
description: "Searches past coding sessions for observations, decisions, context. Triggers: mem-search, recall session, past work, prior decisions, session history."
effort: medium
argument-hint: "[search query]"
allowed-tools: Bash, Read
user-invocable: true

Search Session Memory

Search the persistent memory database for past coding observations, decisions, and context.

$ARGUMENTS

How It Works

This skill queries the SQLite FTS5 full-text search index at `~/.softspark/ai-toolkit/memory.db` to find relevant observations from past sessions.

Instructions

1. **Parse the search query** from `$ARGUMENTS`. If empty, prompt the user for a query.

2. **Initialize the database** if it does not exist:

   python3 "$HOME/.softspark/ai-toolkit/hooks/../plugins/memory-pack/scripts/init_db.py" 2>/dev/null || true

3. **Run the FTS5 search** against the observations table:

   sqlite3 ~/.softspark/ai-toolkit/memory.db "
     SELECT o.id, o.session_id, o.tool_name, o.content, o.created_at,
            s.project_dir, s.summary
     FROM observations_fts fts
     JOIN observations o ON o.id = fts.rowid
     LEFT JOIN sessions s ON s.session_id = o.session_id
     WHERE observations_fts MATCH '<query>'
     ORDER BY rank
     LIMIT 10;
   "

Replace `<query>` with the user's search terms. Escape single quotes by doubling them.

4. **Progressive disclosure** -- present results in two stages:

**Stage 1: Summary view** (show first)

   ## Memory Search: "<query>"

   Found N results across M sessions.

   | # | Session | Project | Tool | Time | Preview |
   |---|---------|---------|------|------|---------|
   | 1 | abc123  | /path   | Edit | 2025-01-15 | First 80 chars... |

**Stage 2: Detail view** (on request) Show the full observation content, session summary, and related observations from the same session.

5. **If no results found**, suggest:

• Trying broader search terms
• Checking if memory-pack hooks are installed
• Running `init-db.sh` if the database is missing

Query Tips

• Use simple keywords: `mem-search database migration`
• FTS5 supports prefix matching: `migrat*` matches "migration", "migrate"
• Boolean operators: `database AND NOT test`
• Column filters: `tool_name:Edit` to search only Edit tool observations

Example

/mem-search "postgres migration rollback"

Typical output:

## Memory Search: "postgres migration rollback"
Found 3 results across 2 sessions.

| # | Session | Project          | Tool | Time       | Preview                              |
|---|---------|------------------|------|------------|--------------------------------------|
| 1 | abc123  | magento2-os      | Edit | 2026-03-12 | Rolled back 0042_add_tax_col...      |
| 2 | def456  | magento2-b2b     | Bash | 2026-02-28 | pg_dump before schema migration...   |
| 3 | abc123  | magento2-os      | Read | 2026-03-12 | Reviewed migration safety checklist  |

Rules

• **MUST** escape single quotes in queries by doubling (`it''s`) — SQL injection into the FTS5 call will break the query
• **NEVER** return the raw database path — treat `~/.softspark/ai-toolkit/memory.db` as internal
• **CRITICAL**: if the database does not exist, initialize it silently and return zero results — do not fail the skill
• **MANDATORY**: present Stage 1 (summary table) first; only expand to Stage 2 on follow-up

Gotchas

• FTS5 `MATCH` is picky: hyphens, slashes, and dots are parsed as operator separators and will reject queries like `mem-search api/v1` with a cryptic `malformed MATCH expression`. Wrap multi-token phrases with double-quotes: `"api/v1"` or `"mem-search"`.
• Results are ordered by `rank` (FTS5 relevance), **not** by `created_at`. A stale but high-ranked match outranks a fresh but weak one — include the `created_at` column and consider `ORDER BY rank, created_at DESC` for time-sensitive queries.
• The database path is static at `~/.softspark/ai-toolkit/memory.db`. If the user runs from a container, `~` resolves to the container's home, not the host's — the observation list will look empty. Check the env var `SOFTSPARK_HOME` before assuming the DB is missing.
• `observations_fts` is a separate virtual table; when observations are deleted directly (not via the SDK) the FTS index can drift. If counts between `observations` and `observations_fts` differ, rebuild with `INSERT INTO observations_fts(observations_fts) VALUES('rebuild');`.

When NOT to Use

• To search the KB or documentation — use `/research-mastery` or `smart_query()`
• To find a specific commit — use `git log --grep` or `/git-mastery`
• To list agent tasks — use `TaskList` or `/plan`
• When memory-pack hooks are not installed — direct the user to install them first