Skip to content
claude-mem

claude-memSkill

by thedotmack
Released
v13.24.1
Apache-2.0
Repository Docs
Featured markdown Development

Summary

Persistent cross-session memory for coding agents: hooks capture each session, a local SQLite + vector store compresses it, and a mem-search skill reads it back.

Features

  • Five lifecycle hooks capture sessions automatically — nothing to remember to save
  • Local SQLite store with vector search; observations typed as bugfix, feature, decision, discovery or change
  • Layered search → timeline → fetch workflow documented as ~10x token savings
  • Hybrid full-text and semantic retrieval via a Chroma vector database
  • <private> tags exclude sensitive content from capture
  • Web viewer for the live memory stream, plus citations by observation ID
  • Optional cloud sync; Node.js 20+ required

Install This Skill

Add this skill to your favorite AI agent in a few steps.

Any AI agent

This skill is plain instructions — it works with any assistant that accepts custom instructions or system prompts.

  1. Copy the skill content with the button below.
  2. Paste it into your agent's instruction file or system prompt (for example AGENTS.md, .cursorrules, or a custom instructions field).
  3. Ask the agent to apply the skill whenever the task matches.

Skill Content

Markdown Content

Copy this content and use it with your preferred AI agent

---
name: mem-search
description: Search claude-mem's persistent cross-session memory database. Use when user asks "did we already solve this?", "how did we do X last time?", or needs work from previous sessions.
---

# Memory Search

Search past work across all sessions. Simple workflow: search -> filter -> fetch -> (rarely) disclose raw tool I/O.

## 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. 10x token savings.**

### 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) - "date_desc" (default), "date_asc", "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:** `depth_before + 1 + depth_after` 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 `get_observations` for 2+ observations - single request vs N requests.**

**Parameters:**

- `ids` (array of numbers, required) - Observation IDs to fetch
- `orderBy` (string, optional) - "date_desc" (default), "date_asc"
- `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)

### Step 4: Disclose 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 `get_tool_uses` 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 `tool_uses` ids OR opaque `tool_use_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 `tool_input` / `tool_response` 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")
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
- **10x token savings** by filtering before fetching

## 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.

Usage Instructions

Learn how to use this skill with different AI agents.

Generic Instructions

Run npx claude-mem install and pick your agent when prompted. The hooks then record every session with no further action. To read memory back, just ask about previous sessions — the mem-search skill triggers on questions like "did we already solve this?" or "what happened last week?". Search accepts query, limit (max 100), project, type, obs_type, dateStart/dateEnd, offset and orderBy. Wrap anything you do not want stored in <private> tags.

Example Usage

npx claude-mem install

Then, in a later session:

"Did we already fix the token expiration bug?"

"How did we handle auth last time?"

mem-search runs: search(query="authentication", limit=20) -> timeline(anchor=11131) -> fetch

Description

claude-mem gives a coding agent memory that outlives the session. Close the terminal, come back tomorrow, and the decisions you made, the bug you fixed and what you meant to do next are still retrievable — instead of re-explaining the project from scratch every morning.

It works in three phases. Capture: five lifecycle hooks (SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd) observe the session as it happens, so nothing depends on you remembering to save. Compress: observations and summaries are written to a local SQLite database with vector search, classified by type — bugfix, feature, decision, discovery, change. Inject: relevant context comes back into later sessions, and the bundled mem-search skill lets the agent query the archive on demand when you ask "did we already solve this?" or "how did we do X last time?".

The retrieval design is the interesting part, because naive memory search wrecks a context window. mem-search enforces a layered workflow: search first for an index of IDs, timestamps and titles at roughly 50-100 tokens per result; then use timeline to pull context around the few results worth expanding; only then fetch full detail. The skill documents this as roughly 10x token savings over fetching everything up front, and the result table even prints an estimated read cost per row so the agent can budget before it commits.

Search is hybrid — full-text plus semantic queries through a Chroma vector store — and filters cover project, observation type, date range and ordering. Content wrapped in <private> tags is excluded from capture, which matters when secrets pass through a session. There is a web viewer for browsing the memory stream in real time, citations that reference past observations by ID, and optional cloud sync for backup.

Install with npx claude-mem install. It requires Node.js 20 or newer, keeps its database local by default, and works across Claude Code and a range of other agent harnesses. Apache-2.0 licensed, currently at version 13.24.1.

Related Skills

Skill: PlanetScale Safe Orchestrator

by PlanetScale

New

The master skill in PlanetScale's official pack: runs a full read-only best-practices assessment of a database or org, then produces one evidence-backed report.

Development
2 views

Skill: Inngest Agents

by Inngest

New

Build crash-safe AI agents on AgentKit and step.ai — durable tool calls, human-in-the-loop approval, realtime progress, and when not to reach for an agent loop at all.

Development
3 views

Skill: Inngest Durable Functions

by Inngest

New

Inngest's durable-execution playbook as an agent skill — steps and memoisation, event and cron triggers, idempotency, cancellation, retries and non-retriable errors.

Development
2 views

Skill: Temporal Developer

by Temporal

New

Temporal's official skill for building durable workflows — SDK patterns across seven languages, plus the determinism rules that decide whether a workflow survives a replay.

Development
7 views
Browse all skills →