raggy-mcp

Status (April 2026): This package is internal infrastructure for LaunchPod and is no longer maintained as a general-purpose product. New issues and feature requests are not being triaged. The source remains MIT-licensed for transparency.

MCP server that provides memory tools to AI agents via the Raggy backend. Used by LaunchPod-managed bots; not currently recommended for general use.

How agents use Raggy

Starting in 0.3.0, raggy-mcp ships with a built-in agent protocol that teaches any connected client how to use the memory tools correctly. The protocol is advertised through the MCP instructions field on initialization, so compatible clients (Claude Desktop, Cursor, Zed, Windsurf, Claude Code, and most modern MCP editors) pass it to the underlying LLM automatically.

You no longer need to paste memory rules into SOUL.md, AGENTS.md, or CLAUDE.md -- connect the server and every agent knows the rules:

• Recall at the start of every session (once), via raggy_context
• Auto-capture decisions, errors, preferences, insights as they happen
• Link related memories into a knowledge graph with raggy_link
• Use raggy_timeline for "what did we do today" and raggy_threads for "what was in my last session"
• Respect "forget that" / "don't save that" immediately

See PROTOCOL.md for the full text, and for manual install instructions if your client doesn't yet support MCP instructions.

Features

• Universal memory protocol: Auto-loaded agent rules via MCP instructions
• Capture & Recall: Store decisions, errors, insights, snippets, research, and bookmarks that persist across sessions and agents
• Context bootstrap: raggy_context loads relevant prior-session memories at the start of every conversation
• Timeline & Threads: Chronological memory and per-session grouping for temporal queries
• Knowledge graph: Explicit links between memories (caused_by, resolved_by, supersedes, refines, contradicts, related_to, follows_from, part_of)
• Private sources: Upload files, URLs, and long-form content as searchable private knowledge
• Forget: Remove outdated or redact-while-preserving memories when they are no longer needed

Installation

Using npx (for interactive clients)

For desktop apps and editors (Claude Desktop, Cursor, VS Code, etc.):

{
  "mcpServers": {
    "raggy": {
      "command": "npx",
      "args": ["-y", "raggy-mcp"]
    }
  }
}

Global install (for hosted / daemon clients)

If your MCP client runs as a system service, daemon, or from inside another agent runtime (e.g., OpenClaw on a Linux VM), use a global install instead of npx:

npm install -g raggy-mcp

{
  "mcpServers": {
    "raggy": {
      "command": "raggy-mcp",
      "args": [],
      "env": { "RAGGY_API_KEY": "rgy_live_..." }
    }
  }
}

Why? npx requires a writable HOME directory for its cache. When a gateway process spawns npx without a login shell (common for systemd services and daemon-managed agents), HOME may be unset or point to an inaccessible directory like /root. This causes a silent EACCES failure -- the subprocess dies immediately but the gateway waits for the full MCP handshake timeout (typically 30s), then retries indefinitely. A global install avoids this entirely.

Diagnostics

Run raggy-mcp doctor to validate your environment:

raggy-mcp doctor

This checks node version, HOME directory, cache permissions, API key format, API reachability, and prints a clear pass/fail report.

Configuration

Config location

raggy-mcp stores per-device state (your anonymous ID and optional API key config) under ~/.raggy/. Resolution order:

1. RAGGY_CONFIG_DIR env var, if set — useful for sandboxed / multi-user / non-standard-HOME environments.
2. ~/.raggy/ (default).

Legacy migration: raggy-mcp ≤ 1.3.0 used ~/.claude/raggy/. If that directory is found on first run of a newer version, it is atomically renamed to ~/.raggy/. No manual steps required. If the rename fails (cross-device mount, permissions), raggy-mcp keeps using the legacy path.

API Key (optional)

For Pro tier access (200 searches/day and delete operations), set your API key:

# Via environment variable
export RAGGY_API_KEY=rgy_live_xxxxx

# Or create config file
mkdir -p ~/.raggy
echo '{"apiKey": "rgy_live_xxxxx"}' > ~/.raggy/config.json

Free tier (20 saves/day and 20 searches/day) works without an API key — see Anonymous mode below.

Anonymous mode

Without an API key, raggy-mcp runs in anonymous mode out of the box:

• On first use, a per-device anonymous ID (anon_<26-char-ULID>) is generated and stored at ~/.raggy/anonymous.json with 0o600 permissions. This ID is sent as the X-Raggy-Anonymous-Id header so the server can scope your memories to this device.
• Storage is device-local: memories saved in anonymous mode are visible only to requests using the same device ID. If you move to another machine, you start fresh (or link to an account to sync).
• Daily limits: 20 saves and 20 searches per day per device.
• Delete operations (raggy_forget, raggy_delete_source) require an account — they cannot run anonymously. Everything else (save, recall, context, timeline, threads, link, upload, private_sources) works without signing up.

Note: Do not sync ~/.raggy/anonymous.json through dotfile managers (chezmoi, stow, a dotfiles repo, etc.). The file encodes a per-device identity — syncing it collapses device isolation across machines and merges their daily caps, so you'll hit the 20/day limit much faster than expected.

Ready to upgrade? Create a free account and get an API key at raggyai.com/signup for unlimited saves and searches, cross-device sync, and delete support.

Tools

All tools follow the agent protocol loaded automatically at connect time (see PROTOCOL.md).

Memory writing

• raggy_save -- Zero-friction save. Just pass raw content — content_type, importance, tags, and title are auto-classified. This is the default tool agents should reach for.
• raggy_capture -- Structured capture with explicit metadata control. Use when you need to override auto-classification.
• raggy_remember -- Simple unstructured note. No metadata.
• raggy_link -- Connect two memories in the knowledge graph using one of: caused_by, resolved_by, supersedes, refines, contradicts, related_to, follows_from, part_of.
• raggy_forget -- Delete or redact a memory. Call when the user says "forget that" or "don't save that".

Memory reading

• raggy_context -- Mandatory first action of every session. Loads relevant memories from prior sessions based on project/technologies/query.
• raggy_recall -- Targeted semantic search. Use only as a follow-up lookup mid-session; don't call twice per question.
• raggy_timeline -- Chronological browse. Use for "what did we do today/yesterday/last week" questions.
• raggy_threads -- Session-based browse. Use for "what was in my last session" questions.

Private sources

• raggy_upload -- Upload files, URLs, or long-form content as a searchable private source.
• raggy_private_sources -- List uploaded sources.
• raggy_delete_source -- Delete an uploaded source by ID. Requires API key (delete operations are unavailable in anonymous mode; use raggy_forget to remove individual memories, or sign up to enable).

Pricing

| Tier | Searches | Features | |------|----------|----------| | Free | 20/day | Detection, semantic search | | Pro | 200/day | Priority support | | Enterprise | Custom | Private docs, SSO, SLA |

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start

License

MIT