mem-search skill

Smart Search (Default)

Search past work across all sessions. Use the original three-step mem-search workflow by default: search → timeline → selected get_observations. Reason about the index and context before choosing details. Do not use auto or guided modes.

Runtime and Tool Names

The examples below use the local worker tools. Native Pi and DSH integrations name the same three steps memsearch, memtimeline, and memgetobservations. Native OpenCode uses claudememsearch, claudememtimeline, and claudememgetobservations. CMEM Pro uses memorysearch, timeline, and get_observations; use the parameter names advertised by that connection.

A self-hosted server runtime uses the same three steps: search, timeline, and getobservations, scoped to the configured server project. Server observation IDs are strings. Set projectId only when selecting another authorized server project. Dumb search is unavailable in server runtime. A direct self-hosted /v1/mcp connection instead requires projectId on each call and anchorId for its timeline. CMEM Pro also uses anchorId for timeline context, and uses getsummaries when the selected index rows are session summaries. Follow the active connection’s advertised schema.

When to Use

Use when users ask about PREVIOUS sessions (not current conversation):

• "Did we already fix this?"
• "How did we solve X last time?"
• "What happened last week?"

Layered Workflow (ALWAYS Follow)

NEVER fetch full details without filtering first: an index row is ~50-100 tokens, about a tenth of a ~500-1,000-token record, so filtering decides how many records you fetch, not how large each one is.

Step 1: Search - Get Index with IDs

Use the search MCP tool:

search(query="authentication", limit=20, project="my-project")

Returns: Table with IDs, timestamps, types, titles (~50-100 tokens/result)

| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #11131 | 3:48 PM | 🟣 | Added JWT authentication | ~75 |
| #10942 | 2:15 PM | 🔴 | Fixed auth token expiration | ~50 |

Parameters:

• query (string) - Search term
• limit (number) - Max results, default 20, max 100
• project (string) - Project name filter
• type (string, optional) - "observations", "sessions", or "prompts"
• obs_type (string, optional) - Comma-separated: bugfix, feature, decision, discovery, change
• dateStart (string, optional) - YYYY-MM-DD or epoch ms
• dateEnd (string, optional) - YYYY-MM-DD or epoch ms
• offset (number, optional) - Skip N results
• orderBy (string, optional) - "datedesc" (default), "dateasc", "relevance"

Step 2: Timeline - Get Context Around Interesting Results

Use the timeline MCP tool:

timeline(anchor=11131, depth_before=3, depth_after=3, project="my-project")

Or find anchor automatically from query:

timeline(query="authentication", depth_before=3, depth_after=3, project="my-project")

Returns: depthbefore + 1 + depthafter items in chronological order with observations, sessions, and prompts interleaved around the anchor.

Parameters:

• anchor (number, optional) - Observation ID to center around
• query (string, optional) - Find anchor automatically if anchor not provided
• depth_before (number, optional) - Items before anchor, default 5, max 20
• depth_after (number, optional) - Items after anchor, default 5, max 20
• project (string) - Project name filter

Step 3: Fetch - Get Full Details ONLY for Filtered IDs

Review titles from Step 1 and context from Step 2. Pick relevant IDs. Discard the rest.

Use the get_observations MCP tool:

get_observations(ids=[11131, 10942])

ALWAYS use getobservations for 2+ observations - single request vs N requests.**

Parameters:

• ids (array of numbers, required) - Observation IDs to fetch
• orderBy (string, optional) - "datedesc" (default), "dateasc"
• limit (number, optional) - Max observations to return
• project (string, optional) - Project name filter

Returns: Complete observation objects with title, subtitle, narrative, facts, concepts, files (~500-1000 tokens each)

Exceptional Follow-up: Raw Tool I/O - Only When Step 3 Was Not Enough

Observations are summaries. When the answer needs the literal bytes a tool returned — the exact diff, the exact command output, the exact API response — use the gettooluses MCP tool:

get_tool_uses(ids=["toolu_01ABC..."], project="my-project")

Do not start here. Raw tool bodies are unsummarized and can run to thousands of tokens each; that is the whole reason claude-mem compresses them into observations in the first place. Reach for this layer only after search / timeline / get_observations pointed you at specific tool calls.

Parameters:

• ids (array, required) - Numeric tooluses ids OR opaque tooluse_id strings
• limit (number, optional) - Max rows to return
• project (string, optional) - Project name filter
• contentSessionId (string, optional) - Restrict to one session

Returns: The stored toolinput / toolresponse for those calls, plus the tool name, session ids, and the observation each was folded into. Payloads over 64 KB were truncated on write and carry a …[truncated: N bytes] marker.

Examples

Find recent bug fixes:

search(query="bug", type="observations", obs_type="bugfix", limit=20, project="my-project")

Find what happened last week:

search(type="observations", dateStart="2025-11-11", limit=20, project="my-project")

Understand context around a discovery:

timeline(anchor=11131, depth_before=5, depth_after=5, project="my-project")

Batch fetch details:

get_observations(ids=[11131, 10942, 10855], orderBy="date_desc")

Recover the exact output of a command we ran last week:

search(query="migration failed", limit=20, project="my-project")
timeline(anchor=11131, project="my-project")
get_observations(ids=[11131])            # read the summary first
get_tool_uses(ids=["toolu_01ABC..."])    # only if the summary omitted the detail

Why This Workflow?

• Search index: ~50-100 tokens per result
• Full observation: ~500-1000 tokens each
• Raw tool body: up to 64 KB each — the layer you skip 95% of the time
• Batch fetch: 1 HTTP request vs N individual requests
• An index row is about a tenth the size of a full record: ~50-100 tokens vs ~500-1,000. Filtering decides how many records you fetch, not their size (a size ratio, not a measured saving).

Knowledge Agents

Want synthesized answers instead of raw records? Use /knowledge-agent to build a queryable corpus from your observation history. The knowledge agent reads all matching observations and answers questions conversationally.

Dumb Search (Optional)

Doesn’t reason about the results. Fast, but shallow. Use Smart for reliable recall.

dumb_search(query="authentication token expiry", project="my-project")

This one-call lookup picks records whose titles share the most query words, adds nearby context, and returns up to maxDetails (default 3, max 5) records. Matching words from unrelated projects can crowd out useful results, and conflicting records are not reconciled. Use only for a quick, direct lookup; use Smart search by default.

Durable Note Taking