# waggle-memory-mcp

Persistent memory MCP server for **Claude Code**, **Claude Desktop**, and any MCP-compatible AI system.

Give your AI assistant memory that persists across conversations — facts, decisions, preferences, project context, and a knowledge graph of entities and relationships.

Powered by the [Waggle OS](https://waggle-os.ai) memory engine.

## Features

- **Persistent Memory** — Save and recall facts, decisions, preferences across conversations
- **Semantic Search** — Hybrid FTS5 keyword + sqlite-vec vector search with RRF fusion
- **Knowledge Graph** — Entities (people, projects, concepts) and their relationships
- **Identity** — Persistent user profile (name, role, capabilities)
- **Awareness** — Short-lived context markers for active tasks and flags
- **Workspaces** — Isolated memory spaces for different projects
- **Harvest** — Import conversation history from ChatGPT, Claude, Gemini, and more
- **Zero Config Embeddings** — Offline vector search using a local ONNX model (23MB, auto-downloaded)
- **Shared Data** — Same `~/.waggle/` directory as Waggle OS desktop app

## Installation

### Claude Code

Add to `~/.claude/settings.json`:

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

### Claude Desktop

Add to `~/.claude/claude_desktop_config.json`:

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

### Custom Data Directory

```json
{
  "mcpServers": {
    "waggle-memory": {
      "command": "npx",
      "args": ["-y", "waggle-memory-mcp"],
      "env": {
        "WAGGLE_DATA_DIR": "/path/to/your/.waggle"
      }
    }
  }
}
```

## Tools

| Tool | Description |
|------|-------------|
| `save_memory` | Save a memory (fact, decision, preference) with importance level |
| `recall_memory` | Semantic search across memories with scoring profiles |
| `search_entities` | Search the knowledge graph for entities |
| `save_entity` | Create or update an entity in the knowledge graph |
| `create_relation` | Create a relationship between entities |
| `get_identity` | Get the user's persistent identity profile |
| `set_identity` | Create or update identity (name, role, etc.) |
| `get_awareness` | Get active tasks, pending items, context flags |
| `set_awareness` | Set a short-lived awareness item |
| `clear_awareness` | Remove awareness items by ID or category |
| `list_workspaces` | List all workspaces with memory stats |
| `create_workspace` | Create a new isolated workspace |
| `harvest_import` | Import conversations from ChatGPT, Claude, Gemini |
| `harvest_sources` | List registered harvest sources and sync status |

## Resources

| URI | Description |
|-----|-------------|
| `memory://personal/stats` | Frame count, entity count, embedding provider status |
| `memory://identity` | Current identity profile |
| `memory://awareness` | Active awareness items |
| `memory://workspace/{id}` | Workspace config and memory stats |

## Architecture

```
~/.waggle/
├── personal.mind          ← SQLite database (WAL mode + sqlite-vec)
├── models/                ← Cached ONNX embedding model
├── config.json            ← Settings
└── workspaces/
    └── {id}/
        ├── workspace.json ← Workspace config
        └── workspace.mind ← Workspace SQLite database
```

### Memory Model

- **I-Frame** (Identity): Base facts — "User prefers TypeScript"
- **P-Frame** (Procedural): Updates to I-Frames
- **B-Frame** (Bridging): Links between frames

### Search Pipeline

1. FTS5 keyword search (stop-word filtered, OR-based)
2. sqlite-vec k-NN vector search (1024-dim embeddings)
3. RRF fusion (K=60) combines both result sets
4. Relevance scoring with 4 profiles: balanced, recent, important, connected

### Embedding Provider Chain

Probed in order, first success wins:

1. **InProcess** — `all-MiniLM-L6-v2` ONNX model, zero config, ~23MB download
2. **Ollama** — `nomic-embed-text` (requires local Ollama)
3. **Voyage/OpenAI** — API-based (requires API keys)
4. **Mock** — Deterministic fallback (always works, no semantic quality)

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `WAGGLE_DATA_DIR` | Data directory path | `~/.waggle` |
| `WAGGLE_EMBEDDING_PROVIDER` | Force a specific provider | `auto` |
| `WAGGLE_OLLAMA_URL` | Ollama server URL | `http://localhost:11434` |
| `WAGGLE_OLLAMA_MODEL` | Ollama model name | `nomic-embed-text` |
| `WAGGLE_VOYAGE_API_KEY` | Voyage AI API key | — |
| `WAGGLE_OPENAI_API_KEY` | OpenAI API key | — |

## Shared with Waggle OS

If you also run [Waggle OS](https://waggle-os.ai) desktop, this MCP server shares the **same data directory**. Memories saved in Claude Code appear in Waggle OS and vice versa. SQLite WAL mode supports concurrent readers.

## Development

```bash
# From the waggle-os monorepo root
cd packages/memory-mcp
npm install
npm run build
npm start
```

## License

MIT - Egzakta Group