# Shelbymcp > Knowledge-graph memory server for AI tools via MCP - **Type:** MCP server - **Install:** `agentstack add mcp-studio-moser-shelbymcp` - **Verified:** Pending review - **Seller:** [Studio-Moser](https://agentstack.voostack.com/s/studio-moser) - **Installs:** 0 - **Latest version:** 0.2.4 - **License:** MIT - **Upstream author:** [Studio-Moser](https://github.com/Studio-Moser) - **Source:** https://github.com/Studio-Moser/Shelby-MCP ## Install ```sh agentstack add mcp-studio-moser-shelbymcp ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About The memory backbone for Shelby — and a standalone knowledge-graph memory server for any MCP-compatible AI tool. Mem0-grade intelligence. Engram-grade simplicity. Quick Start · Architecture · Agent Setup · Contributing --- ## What is ShelbyMCP? Every AI memory server is a bag of embeddings. **ShelbyMCP connects your thoughts.** ShelbyMCP is the open-source memory backbone of [Shelby](https://shelbybot.com) — your AI coworker on Mac — and a zero-dependency MCP memory server you can run standalone with any MCP-compatible AI tool. It gives Claude Code, Cursor, Codex, Windsurf, Gemini, Antigravity, and others persistent memory that understands how your thoughts are related — not just what they contain. Ship it with the **Forage skill**, a scheduled task you run in your own Claude Code (or Codex / Gemini CLI) session to continuously enrich, consolidate, and connect your memories. Forage uses *your* subscription — the same way you'd use Claude Code yourself — so ShelbyMCP itself stays zero-cost and zero-cloud. No Docker. No Python. No cloud accounts. Just a binary and a database file. > **Where this fits in Shelby**: Shelby is an AI coworker built on three layers — companion (the experience), harness (the runtime that carries context, enforces governance, holds history), and memory (this server). If you want the full coworker experience, install Shelby for Mac. If you only want the memory backbone for your existing AI tools, ShelbyMCP standalone is what you want. ### Why ShelbyMCP? | Problem | ShelbyMCP's answer | |---|---| | Every conversation starts from zero | Persistent memory across sessions | | Memories are a flat pile of text | Knowledge graph with typed relationships (refines, cites, refuted_by, tags) | | Search results blow up your context window | Pre-computed summaries — search returns one-liners, fetch full content on demand | | No memory maintenance | Forage skill auto-consolidates, deduplicates, and connects | | Vector search requires heavy infra | Forage skill backfills embeddings via the AI tool you already run yourself (Claude Code, Codex, Gemini CLI) — Shelby never touches your subscription auth | | Requires Docker/Python/Cloud | `npx shelbymcp`, single SQLite file | --- ## Quick Start ### 1. Install ```bash # npx (no install needed) npx shelbymcp # Or install globally npm install -g shelbymcp # Or build from source git clone https://github.com/Studio-Moser/shelbymcp.git cd shelbymcp && npm install && npm run build ``` ### 2. Set Up Your Agent The CLI auto-configures everything — MCP server registration, Memory Protocol, and optional Forage skill: ```bash shelbymcp setup claude-code --forage # Claude Code CLI shelbymcp setup claude-desktop --forage # Claude Desktop app shelbymcp setup cursor --forage # Cursor IDE shelbymcp setup codex --forage # OpenAI Codex shelbymcp setup windsurf --forage # Windsurf (Codeium) shelbymcp setup gemini --forage # Gemini CLI shelbymcp setup antigravity --forage # Antigravity (Google) ``` Drop `--forage` if you just want the MCP server without the scheduled enrichment skill. That's it. The CLI registers the MCP server, adds the Memory Protocol to the right place, and installs the Forage skill. See [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md) for manual config and platform-specific details. ### 3. Add the Memory Protocol Most agents get the Memory Protocol added automatically during setup. For agents that require manual steps, the CLI will tell you exactly what to do. Here's where it goes: ```bash shelbymcp protocol >> ~/.claude/CLAUDE.md # Claude Code (auto) shelbymcp protocol >> ~/.codex/AGENTS.md # Codex (auto) shelbymcp protocol >> ~/.codeium/windsurf/memories/global_rules.md # Windsurf (auto) shelbymcp protocol >> ~/.gemini/GEMINI.md # Gemini CLI / Antigravity (auto) ``` For Cursor, paste into **Settings > Rules > User Rules**. For Claude Desktop, paste into **Settings > General > "What personal preferences should Claude consider in responses?"**. The Memory Protocol tells your agent *when* to save and search — without it, the tools are available but won't be used proactively. ### 4. Seed Your Memory Your database is empty after install. There are three ways to make it useful immediately: ```bash # Option A: Run the onboarding interview (recommended) # Paste this into a conversation — it asks a few questions and saves 15-30 memories shelbymcp onboard # Option B: Import from another AI tool # Paste this prompt into ChatGPT/Claude/Gemini, copy the response back shelbymcp migrate # Option C: Just start working — memories accumulate naturally over time ``` The **onboard** skill runs a conversational interview covering who you are, what you're building, your team, preferences, and anti-patterns. Takes about 5 minutes. The **migrate** prompt tells your other AI tools to export everything they know about you in a structured format that ShelbyMCP can import. ### 5. Verify Ask your agent: *"What memory tools do you have available?"* It should list 9 tools. Then test: *"Remember that I prefer dark mode in all my apps."* — and in a new session: *"What do you know about my preferences?"* --- ## How It Works ``` You (in Claude Code): "We decided to use CloudKit for sync instead of Firebase" Claude Code → capture_thought tool → ShelbyMCP: 1. Stores thought in SQLite 2. Agent provides metadata (type: decision, topics: [sync, cloud]) 3. Agent suggests relationships to existing thoughts 4. FTS5 indexes content for keyword search Later: You: "What did we decide about our sync strategy?" Claude Code → search_thoughts tool → ShelbyMCP: 1. FTS5 keyword search for "sync strategy" 2. Returns thought + all connected thoughts via knowledge graph 3. Agent has full context of decisions, alternatives considered, and related work ``` ### With the Forage Skill (scheduled, daily): ``` Forage runs on Claude Code's scheduler: 1. Backfills embeddings for thoughts that don't have them 2. Re-classifies poorly tagged thoughts 3. Finds duplicate thoughts and merges them 4. Detects contradictions ("we said PostgreSQL last month but SQLite this week") 5. Discovers connections between thoughts across projects 6. Sweeps for stale action items that fell through the cracks 7. Generates a weekly digest of your thinking ``` --- ## MCP Tools 9 focused tools — research shows 5-8 tools per server is the sweet spot for agent accuracy. | Tool | Description | |---|---| | `capture_thought` | Store a thought with summary, metadata, topics, and relationships. Accepts an array for bulk capture. | | `search_thoughts` | Full-text search with knowledge graph expansion. Auto-detects FTS5 vs. vector mode. Returns summaries, not full content. | | `list_thoughts` | Browse/filter by type, topic, person, project, date range | | `get_thought` | Retrieve a specific thought by ID (full content) | | `update_thought` | Update content or metadata. Accepts `ids` array for bulk updates. | | `delete_thought` | Remove a thought | | `manage_edges` | Create or remove typed relationships between thoughts (link, unlink) | | `explore_graph` | Traverse the knowledge graph from a starting thought. Depth 1 = direct connections, 2+ = full traversal. | | `thought_stats` | Aggregate statistics about your memory | --- ## Knowledge Graph What makes ShelbyMCP different from every other memory server is the knowledge graph. Thoughts aren't isolated — they're connected. ### Edge Types | Edge Type | Meaning | Example | |---|---|---| | `refines` | A thought that adds detail to another | "Use CloudKit" → "Configure change tokens for sync" | | `cites` | A thought that references another as evidence | "Decision doc" → "Performance benchmark results" | | `refuted_by` | A thought that contradicts another | "Use Firebase" ← "Switch to CloudKit" | | `tags` | A thought that categorizes another | "Architecture" → "CloudKit sync design" | | `related` | General association | "Auth system" ↔ "User migration plan" | | `follows` | Sequential relationship | "Phase 1 plan" → "Phase 2 plan" | Agents create edges at capture time ("this decision relates to thought X") and the Forage skill discovers additional connections over time. --- ## The Forage Skill ShelbyMCP ships with `shelby-forage`, a scheduled skill *you* run in your own AI tool of choice (Claude Code, Codex, Gemini CLI) to continuously improve your memory. The skill executes inside your session, on your subscription — ShelbyMCP itself never authenticates the call. The server stays zero-dependency, your subscription terms apply normally, and the intelligence comes from tools you're already paying for. | Task | Frequency | What it does | |---|---|---| | **Summary backfill** | Daily | Generate one-liners for thoughts missing summaries | | **Auto-classify** | Daily | Improve type/topics/people on poorly tagged thoughts | | **Consolidation** | Daily | Find and merge duplicate thoughts | | **Contradiction detection** | Daily | Flag conflicting memories (tagged `needs-attention`) | | **Connection discovery** | Daily | Create edges between related thoughts | | **Stale sweep** | Weekly (Mon) | Flag forgotten action items (tagged `needs-attention`) | | **Digest** | Weekly (Mon) | Summary of the week's thinking by project/topic | | **Forage log** | Every run | Audit trail for continuity between runs | ### Setup See [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md#3-forage-skill-optional) for full setup instructions, platform compatibility table, and gotchas for each agent. ### Without the Forage Skill ShelbyMCP works fine without it — you get persistent storage, FTS5 search, and knowledge graph. The Forage skill adds the intelligence layer that makes memories smarter over time. Think of it as optional but recommended. --- ## Getting Started: Onboard & Migrate An empty memory database is a cold start problem — your AI tools can't personalize until they know something about you. ShelbyMCP ships with two tools to solve this: ### The Onboard Skill (recommended) A one-time conversational interview that seeds 15-30 foundational memories. Paste the prompt into a conversation with your primary AI tool: ```bash shelbymcp onboard ``` It covers: - **Who you are** — name, role, expertise - **What you're building** — projects, goals, tech stack - **Who you work with** — team, roles, stakeholders - **How you like to work** — communication style, coding preferences, AI interaction style - **What to avoid** — anti-patterns, pet peeves, past frustrations Takes about 5 minutes. The skill adapts its questions based on your answers — if you're a solo founder, it won't ask about team structure. Memories are saved after each round so you can see them accumulate in real time. ### The Migrate Prompt Already have context stored in ChatGPT, Claude, Gemini, or another AI? Export it: ```bash shelbymcp migrate ``` This prints a prompt you paste into your other AI tool. That tool dumps everything it knows about you in a structured format. Copy the response back into your ShelbyMCP-connected agent — the onboard skill will parse and import it, or you can just paste it into any conversation and ask the agent to import it. Works with any AI that has memory or conversation history about you. Run it once per tool you're migrating from. --- ## CLI Reference ``` shelbymcp Start the MCP server (stdio) shelbymcp --transport http Start as HTTP server (Streamable HTTP) shelbymcp setup Set up ShelbyMCP for an agent shelbymcp setup --forage ...and install the Forage skill shelbymcp uninstall Remove ShelbyMCP from an agent shelbymcp protocol Print the Memory Protocol shelbymcp forage Print the Forage skill prompt shelbymcp onboard Print the onboarding interview prompt shelbymcp migrate Print the migration prompt for other AI tools shelbymcp help Show help shelbymcp --version Print version ``` **Supported agents:** `claude-code`, `claude-desktop`, `cursor`, `codex`, `windsurf`, `gemini`, `antigravity` **Server flags:** | Flag | Default | Description | |---|---|---| | `--db ` | `~/.shelbymcp/memory.db` | Custom database path | | `--verbose` | off | Debug logging | | `--transport ` | `stdio` | Transport mode | | `--port ` | `3100` | HTTP port (only with `--transport http`) | | `--host ` | `127.0.0.1` | HTTP bind address (only with `--transport http`) | **Remote server example (Streamable HTTP):** ```bash # Start ShelbyMCP as an HTTP server shelbymcp --transport http --port 3100 # Connect from Claude Code claude mcp add --transport http shelby http://localhost:3100/mcp ``` See [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md) for manual config, platform-specific details, and setup for other MCP-compatible clients. --- ## Cloud Deployment ShelbyMCP can run as a remote HTTP server, letting you share one memory database across multiple machines. All configuration is via environment variables: | Variable | Default | Description | |---|---|---| | `SHELBY_TRANSPORT` | `stdio` | Set to `http` for remote server mode | | `PORT` | `3100` | HTTP port (most cloud platforms inject this) | | `HOST` | `0.0.0.0` (http) / `127.0.0.1` (stdio) | Bind address | | `SHELBY_DB_PATH` | `~/.shelbymcp/memory.db` | SQLite database path (use a persistent volume) | | `SHELBY_API_KEY` | *(none)* | Bearer token for auth — **set this for any internet-facing deployment** | CLI flags (`--transport`, `--port`, `--host`, `--db`) override env vars when both are set. ### Docker ```bash docker build -t shelbymcp . docker run -d \ -e SHELBY_TRANSPORT=http \ -e SHELBY_API_KEY=your-secret-key \ -v shelby-data:/data \ -e SHELBY_DB_PATH=/data/memory.db \ -p 3100:3100 \ shelbymcp ``` ### Connect from Claude Code ```bash claude mcp add --transport http shelby-cloud https://your-server.example.com/mcp \ --header "Authorization: Bearer your-secret-key" ``` ### Health Check `GET /health` returns `200 {"status": "ok"}` (unauthenticated). Configure this as your platform's health check endpoint. ### Auth When `SHELBY_API_KEY` is set, all requests to `/mcp` require an `Authorization: Bearer ` header. Without the key, requests return `401`. If `SHELBY_API_KEY` is not set, auth is disabled (suitable for local-only use). --- ## Architecture ShelbyMCP is a single binary that communicates via MCP and stores everything in a single SQLite file. Supports both **stdio** (local, default) and **Streamable HTTP** (remote/multi-client) transports. ``` AI Tool (Claude Code, Cursor, etc.) │ │ MCP (stdio or Streamable HTTP) │ ▼ ┌──────────────────────┐ │ ShelbyMCP │ │ │ │ ┌──────────────────┐ │ │ │ MCP Protocol │ │ ← JSON-RPC request/response │ │ (stdio or HTTP) │ │ │ └────────┬─────────┘ │ │ │ │ │ ┌────────▼─────────┐ │ │ │ Tool Router │ │ ← Routes to capture/search/link/etc. │ └────────┬─────────┘ │ │ │ │ │ ┌────────▼─────────┐ │ │ │ SQLite DB │ │ │ │ ┌─────────────┐ │ │ │ │ │ thoughts │ │ │ ← Content, metadata, embeddings │ │ │ thought_fts │ │ │ ← FTS5 full-text index │ │ │ edges │ │ │ ← Knowledge graph relationships │ │ └─────────────┘ │ │ │ └──────────────────┘ │ └──────────────────────┘ │ ▼ ~/.shelbymcp/memory.db (single file) ``` See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full technical design. --- ## Comparison | | ShelbyMCP | Engram | Mem0 | Basic Memory | Cipher | |---|---|---|---|---|---| | **Dependencies** | Zero | Zero | Docker+Qdrant+Neo4j | Python+pip | Node.js | | **Storage** | SQLite | SQLite | Qdrant+Neo4j+SQLite | Markdown+SQLite | Files | | **Knowledge graph** | Native (typed edges) | No | Ne … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [Studio-Moser](https://github.com/Studio-Moser) - **Source:** [Studio-Moser/Shelby-MCP](https://github.com/Studio-Moser/Shelby-MCP) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Versions - **0.2.4** — security scan: pending review — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-studio-moser-shelbymcp - Seller: https://agentstack.voostack.com/s/studio-moser - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.