# raggy-mcp

MCP server that gives every AI agent a universal brain -- centralized memory and knowledge via [Raggy](https://raggyai.com). One brain, all agents.

## 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](./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 (recommended)

Add to your Claude Code configuration:

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

### Manual installation

```bash
npm install -g raggy-mcp
```

Then add to your Claude Code configuration:

```json
{
  "mcpServers": {
    "raggy": {
      "command": "raggy-mcp"
    }
  }
}
```

## Configuration

### API Key (optional)

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

```bash
# Via environment variable
export RAGGY_API_KEY=rgy_live_xxxxx

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

Free tier (20 searches/day) works without an API key.

## Tools

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

### Memory writing

- **`raggy_capture`** -- Structured auto-capture with rich metadata. Use for
  decisions, errors, preferences (tag as `["preference"]`), insights,
  snippets, and research. Requires `content_type` and `importance`.
- **`raggy_remember`** -- Simple unstructured note. Prefer `raggy_capture`
  when you have a clear type.
- **`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 (requires API key)

- **`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.

## Pricing

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

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start
```

## License

MIT