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