From f154e32145a05b4919828478b197ea6026c81c71 Mon Sep 17 00:00:00 2001 From: Alex Newman Date: Fri, 12 Dec 2025 00:09:25 -0500 Subject: [PATCH] feat: add mem-search skill and Claude Desktop integration documentation --- README.md | 11 +- desktop-skill/Skill.md | 44 +++++++ desktop-skill/mem-search.zip | Bin 0 -> 1124 bytes docs/public/docs.json | 1 + docs/public/usage/claude-desktop.mdx | 169 +++++++++++++++++++++++++++ 5 files changed, 220 insertions(+), 5 deletions(-) create mode 100644 desktop-skill/Skill.md create mode 100644 desktop-skill/mem-search.zip create mode 100644 docs/public/usage/claude-desktop.mdx diff --git a/README.md b/README.md index 9e68ded3..349852db 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,7 @@ Restart Claude Code. Context from previous sessions will automatically appear in - 📊 **Progressive Disclosure** - Layered memory retrieval with token cost visibility - 🔍 **Skill-Based Search** - Query your project history with mem-search skill (~2,250 token savings) - 🖥️ **Web Viewer UI** - Real-time memory stream at http://localhost:37777 +- 💻 **Claude Desktop Skill** - Search memory from Claude Desktop conversations - 🔒 **Privacy Control** - Use `` tags to exclude sensitive content from storage - ⚙️ **Context Configuration** - Fine-grained control over what context gets injected - 🤖 **Automatic Operation** - No manual intervention required @@ -108,7 +109,7 @@ npx mintlify dev - **[Architecture Evolution](https://docs.claude-mem.ai/architecture-evolution)** - The journey from v3 to v5 - **[Hooks Architecture](https://docs.claude-mem.ai/hooks-architecture)** - How Claude-Mem uses lifecycle hooks - **[Hooks Reference](https://docs.claude-mem.ai/architecture/hooks)** - 7 hook scripts explained -- **[Worker Service](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API & Bun process management +- **[Worker Service](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API & PM2 management - **[Database](https://docs.claude-mem.ai/architecture/database)** - SQLite schema & FTS5 search - **[Search Architecture](https://docs.claude-mem.ai/architecture/search-architecture)** - Hybrid search with Chroma vector database @@ -148,7 +149,7 @@ npx mintlify dev 1. **5 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook scripts) 2. **Smart Install** - Cached dependency checker (pre-hook script, not a lifecycle hook) -3. **Worker Service** - HTTP API on port 37777 with web viewer UI and 10 search endpoints, managed by Bun +3. **Worker Service** - HTTP API on port 37777 with web viewer UI and 10 search endpoints, managed by PM2 4. **SQLite Database** - Stores sessions, observations, summaries with FTS5 full-text search 5. **mem-search Skill** - Natural language queries with progressive disclosure (~2,250 token savings vs MCP) 6. **Chroma Vector Database** - Hybrid semantic + keyword search for intelligent context retrieval @@ -260,10 +261,10 @@ See [CHANGELOG.md](CHANGELOG.md) for complete version history. ## System Requirements -- **Bun**: 1.0 or higher (auto-installed on first run if missing) -- **Node.js**: 18.0.0 or higher (for build tools) +- **Node.js**: 18.0.0 or higher - **Claude Code**: Latest version with plugin support -- **SQLite 3**: For persistent storage (via bun:sqlite - zero native dependencies) +- **PM2**: Process manager (bundled - no global install required) +- **SQLite 3**: For persistent storage (bundled) --- diff --git a/desktop-skill/Skill.md b/desktop-skill/Skill.md new file mode 100644 index 00000000..40c8a098 --- /dev/null +++ b/desktop-skill/Skill.md @@ -0,0 +1,44 @@ +--- +name: mem-search +description: Search your persistent memory database from previous coding sessions. Use when asked about past work, decisions, bugs fixed, or development history. +--- + +## Overview + +Search your local memory database for past sessions, decisions, code changes, and development history. This skill uses the `mem-search` MCP server tools. + +## Available MCP tools + +Use these tools from the `mem-search` MCP server: + +| Tool | Description | +|------|-------------| +| `search` | Unified search across all memory types | +| `decisions` | Find architectural/design decisions | +| `changes` | Find code changes and refactorings | +| `timeline` | Get observations around a specific point in time | +| `find_by_file` | Find observations for specific files | +| `find_by_type` | Filter by type (decision, bugfix, feature, refactor, discovery, change) | +| `find_by_concept` | Find by concept tags | +| `how_it_works` | Understand system architecture and design patterns | + +## Common parameters + +- `query` - Natural language search query +- `limit` - Max results (1-100, default 20) +- `format` - `index` for titles only (recommended), `full` for complete content +- `type` - Filter: observations, sessions, or prompts +- `obs_type` - Filter observation type: decision, bugfix, feature, refactor, discovery, change + +## When to use + +- "Did we already solve this?" +- "How did we do X last time?" +- "Find the bug fix for..." +- "What decisions did we make about..." +- "Show me changes to [file]" +- "What work did we do on [project]?" + +## Setup requirement + +The `mem-search` MCP server must be configured in Claude Desktop settings. See MCP configuration docs. diff --git a/desktop-skill/mem-search.zip b/desktop-skill/mem-search.zip new file mode 100644 index 0000000000000000000000000000000000000000..89573028f7696b73d3ce8803de54827f249ac756 GIT binary patch literal 1124 zcmWIWW@h1H00FDo?r1OrN^mpCFyyA@>K3Oa7A0rshlX%6F!$?NXHEg)(h6<{MwYLP z3=AwHK;;2ILqIeK*pPiXQ~iXP85j!L7#M_64GGT9%*oNqO@SLW5!0}_A-?{%9R&9N z4)1xuG-<9=|IQH66>nR&2`OkPPRV&wxasVz?6T{e(>^`^o%YtEGpaCykMqpA=hdIp zPH$QgChEWPk=ExmG5fr@zU{p1dtuwWOSM}9)1%#at=HE+uKxB^XFfZ59ckeoUL*^S8BHQ=kj(BG3|G|tyXsR&HOZV z)%2eKA+dip8`wV3|CF7}v-N~?;!zWO2lM5-XV2Goa6z0kyLbK(JNx`8W?6|A`;ND( z2>J-<-%om>Sfl>X#Ix)RL-?(WZyS|vsqWUPYn%U&+4$`D$g(dHuY;I>-E-0^zg8WT z#-dfi%hnaBtS9utm6@mWV&mrvR;hLgj$by}9k}k!`=ZzI_yji>+38yBeG$EiDlfWv z*F`4nD^l1!AuzPVbL!@`Q`GJ+2v}L1wT4Y{ms;m*<0&glqDwXhNy}-^Um|$#IM1VJ z{>rKE>@Klv*!E)Lg6_X1g~}WIHK(pIuwVXI;fBK7V(z?MB{RN!GO5gaJ!iH-S=*cD z&Zb+7H*C5+lg~J?>HSJAg)Isbe)1Kq?tAz=(NdYYm+OV4kV1A@^6FDvR~;`^9GH}9 zQlESA{v4xU>y&C!E@Z5pw&#B93x#=Z;Z_~b=T;q_u+Q}1<)fu#wWX>_nxZ^kKE4X7 zVa#5-=(9}o$J;hcvLylyxw%%m3g#?UJeFNJQ)!XuvhPhh4Ko5ZOvqOHStYfpvF#;i z`^$-Gu15vDg!i}{%r29vl#!S@=hA;eNx|Alvqjf*#BQ+JeU&xWv9WMXSKl5}X~B)( z=AV1=bM{@Oz!FWJzf6~Qm~UG1w>X9|(BjtwVf6$bwaGueZ3%kl5$HV4Ywgbc)2jDZ z=Wwf7b8(-wJsq}RX445J*{zH+^B8aDuQ|{CYr@8NmRoq+>T|ay?=0~A^x>T9>ZqQL z9VJt%I3I8cKI{$D73mA!!ndt4pJUM*&Q0IT^WNVp4!j|A{R4l1HzSiAGp<}J0nM)h z3 +**Availability:** The mem-search skill works with Claude Desktop on macOS and Windows. + + +## Overview + +Claude Desktop can access your claude-mem memory database through the **mem-search** skill. This allows you to search past sessions, decisions, and observations directly from Claude Desktop conversations. + +## Prerequisites + +Before installing the skill, ensure: + +1. **claude-mem is installed** and the worker service is running +2. **MCP server is configured** in Claude Desktop (the skill uses the `mem-search` MCP server) + +### Verify Worker is Running + +```bash +curl http://localhost:37777/api/health +# Should return: {"status":"ok"} +``` + +## Installation + +### Step 1: Download the Skill + +Download the skill package from the repository: + + + Download the mem-search skill for Claude Desktop + + +Or build from source: + +```bash +cd desktop-skill +zip -r mem-search.zip Skill.md +``` + +### Step 2: Install in Claude Desktop + +1. Open **Claude Desktop** +2. Go to **Settings** (gear icon) +3. Navigate to **Skills** +4. Click **Install Skill** or drag the `mem-search.zip` file +5. Confirm installation + +### Step 3: Configure MCP Server + +The skill requires the `mem-search` MCP server. Add this to your Claude Desktop configuration: + + + + Edit `~/Library/Application Support/Claude/claude_desktop_config.json`: + + ```json + { + "mcpServers": { + "mem-search": { + "command": "node", + "args": [ + "/Users/YOUR_USERNAME/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs" + ] + } + } + } + ``` + + + Edit `%APPDATA%\Claude\claude_desktop_config.json`: + + ```json + { + "mcpServers": { + "mem-search": { + "command": "node", + "args": [ + "C:\\Users\\YOUR_USERNAME\\.claude\\plugins\\marketplaces\\thedotmack\\plugin\\scripts\\mcp-server.cjs" + ] + } + } + } + ``` + + + + +Replace `YOUR_USERNAME` with your actual username. Restart Claude Desktop after editing the configuration. + + +### Step 4: Restart Claude Desktop + +Close and reopen Claude Desktop for the MCP server configuration to take effect. + +## Usage + +Once installed, the skill auto-activates when you ask about past work: + +``` +"What did we do last session?" +"Did we fix this bug before?" +"How did we implement authentication?" +"What decisions did we make about the API?" +"Show me changes to worker-service.ts" +``` + +## Available Search Tools + +The skill provides access to these MCP tools: + +| Tool | Description | +|------|-------------| +| `search` | Unified search across all memory types | +| `decisions` | Find architectural/design decisions | +| `changes` | Find code changes and refactorings | +| `timeline` | Get observations around a specific point in time | +| `find_by_file` | Find observations for specific files | +| `find_by_type` | Filter by type (decision, bugfix, feature, refactor, discovery, change) | +| `find_by_concept` | Find by concept tags | +| `how_it_works` | Understand system architecture and design patterns | + +## Troubleshooting + +### Skill Not Appearing + +1. Verify the zip file was properly installed +2. Check Claude Desktop's skill installation logs +3. Restart Claude Desktop + +### MCP Server Connection Failed + +1. Verify the worker is running: `curl http://localhost:37777/api/health` +2. Check the MCP server path in configuration +3. Look for errors in Claude Desktop logs + + + + ```bash + # View Claude Desktop logs + tail -f ~/Library/Logs/Claude/claude.log + ``` + + + Check `%APPDATA%\Claude\logs\` + + + +### Search Returns No Results + +1. Ensure claude-mem has recorded sessions (check http://localhost:37777) +2. Verify the database exists: `ls ~/.claude-mem/claude-mem.db` +3. Test the API directly: `curl "http://localhost:37777/api/search?query=test"` + +## Related + + + + Complete search API reference + + + Build custom integrations + +