Episode 7: Skill 1 — Memory Search — The Complete Claude-Mem Hands-On Guide

This episode's scenario: Your blog project has been in development for two weeks. You vaguely recall making an architecture decision about the "tagging system" but can't remember the details. You want Claude to dig up that record.

7.1 What Is Memory Search?

Memory Search is Claude-Mem's core Skill — enabling Claude to search your development history using natural language. It's the practical interface for the 3-layer retrieval we learned in Episode 6.

7.2 The Four MCP Tools

Tool 1: `search` — Index Search

search(
  query: "tagging system",         // Search terms (required)
  type: "decision",               // Filter by Observation type (optional)
  date_from: "2026-04-01",        // Start date filter (optional)
  date_to: "2026-04-21",          // End date filter (optional)
  project: "my-blog",             // Filter by project (optional)
  limit: 10                       // Result count (optional, default 10)
)

Tool 2: `timeline` — Chronological Context

timeline(
  observation_id: 23,  // Around which Observation (optional)
  query: "tags"        // Or keyword-based timeline (optional)
)

Tool 3: `get_observations` — Full Details

get_observations(
  ids: [22, 23]  // Observation ID array (required)
)

Tool 4: `list_projects` — List All Projects

list_projects()

7.3 Search Syntax & Advanced Tips

Filter by Type

search(query="database", type="decision")    # Architecture decisions only
search(query="API", type="bugfix")           # Bug fixes only
search(query="Prisma", type="discovery")     # Discoveries only

6 available types: decision, bugfix, feature, refactor, discovery, change

Filter by File

search(query="file:auth.ts")
search(query="file:schema.prisma", type="decision")

Filter by Date

search(query="Bug", date_from="2026-04-14")
search(query="deploy", date_from="2026-04-01", date_to="2026-04-10")

Combined Search

search(
  query="database schema",
  type="decision",
  date_from="2026-04-14",
  project="my-blog"
)

7.4 Natural Language Search

In practice, you don't need to memorize this syntax. Just ask Claude in plain language:

You: Why did we choose implicit many-to-many for tags?

Claude automatically translates your question into the right search call and synthesizes a precise answer from the retrieved Observations.

7.5 Observation ID Citations

Claude-Mem supports ID-based citations. When Claude answers based on memory, it tags the source:

Claude: According to Observation #23, we chose Prisma's implicit many-to-many...

You can view the full record in the Web UI:
http://localhost:37777/api/observation/23

This traceability lets you verify Claude's answers — it's not fabricating, it's citing real history.

Hands-On Exercise

Ensure the blog project has at least 2 sessions of Observations
In a new session, search with natural language:
- "What architecture decisions have we made?"
- "What bug did we fix last time?"
- "What database-related operations were there?"
Observe how Claude calls the search tools
Verify results via IDs in the Web UI

Coming Up Next

Memory Search handles "searching memories." But what if Claude needs to understand your code structure? Reading a 500-line file wastes tokens. Next: Smart Explore — AST-based precision code navigation, saving 20x on tokens.

➡️ Episode 8: Skill 2 — Smart Explore

Episode 7: Skill 1 — Memory Search