# Mem Search

> Search persistent project memory across sessions — decisions, bugs, features, discoveries

- Skill: `djnsty23/mem-search` (Agent Skill)
- Install (CLI): `npx skillmds@latest add djnsty23/mem-search`
- Raw SKILL.md: https://api.skillmd.com/api/skills/djnsty23/mem-search/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: djnsty23 (https://skillmd.com/u/djnsty23)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/djnsty23/mem-search

---


# Memory Search

Search the project's persistent memory database. Observations are captured automatically during sessions.

## Commands

| Say | Does |
|-----|------|
| `mem search <query>` | Keyword search — auto-falls back to conceptual (semantic) search when exact matches are sparse |
| `mem why <query>` / `semantic` | Conceptual/fuzzy recall (TF-IDF token similarity + synonym expansion) |
| `mem recent` | Last 10 observations for this project |
| `mem decisions` | All architectural/design decisions |
| `mem bugs` | All bug fixes |
| `mem timeline <query>` | Session-level view with summaries |
| `mem sessions` | List all past sessions |
| `mem stats` | Memory database statistics |

## How It Works

Memory is stored in SQLite at `~/.claude/auto-dev-memory.db`. Observations are captured automatically by the PostToolUse hook and classified by type:

- **decision** — Architectural or design choices
- **bugfix** — Bug fixes and patches
- **feature** — New functionality added
- **refactor** — Code restructuring
- **discovery** — Investigations and findings
- **change** — General modifications

## Progressive Disclosure (Token-Efficient)

1. **Start with `mem search`** — returns titles + timestamps only (~50-100 tokens)
2. **Then `mem timeline`** — shows session context around matches (~500 tokens)
3. **Then drill into specifics** — full observation details only when needed

This 3-layer approach saves ~10x tokens vs dumping full context.

## Implementation

Run queries via the memory-db CLI:

```bash
# Search — exact FTS5 first, auto-falls back to conceptual search when <3 exact hits
node "${CLAUDE_PLUGIN_ROOT}/scripts/memory-db.js" search "$(pwd)" "auth middleware"

# Conceptual / fuzzy recall (lexical TF-IDF ranker, no embeddings, offline)
node "${CLAUDE_PLUGIN_ROOT}/scripts/memory-db.js" semantic "$(pwd)" "why did we choose X"

# Recent observations
node "${CLAUDE_PLUGIN_ROOT}/scripts/memory-db.js" recent "$(pwd)" 10

# Decisions only
node "${CLAUDE_PLUGIN_ROOT}/scripts/memory-db.js" decisions "$(pwd)"

# Bug fixes only
node "${CLAUDE_PLUGIN_ROOT}/scripts/memory-db.js" bugs "$(pwd)"

# Session history
node "${CLAUDE_PLUGIN_ROOT}/scripts/memory-db.js" sessions "$(pwd)"

# Timeline search
node "${CLAUDE_PLUGIN_ROOT}/scripts/memory-db.js" timeline "$(pwd)" "database"

# Stats
node "${CLAUDE_PLUGIN_ROOT}/scripts/memory-db.js" stats "$(pwd)"
```

## When to Use

- Starting a new session and want context from past work
- Remembering why a decision was made
- Finding when/where a bug was fixed
- Checking what was explored in previous sessions
- Reviewing what's left to do (next_steps from last session)

## Privacy

Content wrapped in `<private>...</private>` tags is automatically stripped before storage. Secrets, API keys, and sensitive data in private tags never reach the database.

## Proving the run

**Observable:** the number of records searched, printed alongside the results.

"No memories match" is indistinguishable from "the database did not open". Before
reporting an empty result, run a query you know should hit — a term from a
memory written this week — and confirm it returns. Then report the count
searched, so a zero is legible as a real absence rather than a silent failure.