# Waggle-mcp

Project memory kept as a graph, so decisions and their reasons survive into the next session. Useful when re-pasting context has become a chore.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 44
- Author: Abhigyan-Shekhar
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Abhigyan-Shekhar/Waggle-mcp
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/mcp/waggle-mcp

## What it does

Waggle keeps project knowledge in a graph rather than in the chat: what was decided, why it matters, what depends on it, what changed. An agent pulls the relevant slice when it needs one and writes down outcomes for later conversations. The core loop runs through `prime_context` to load project context, `query_graph` to fetch history, `observe_conversation` to record durable results, and `build_context` to assemble a compact pack for one task.

The default store is SQLite on your own machine, and local use needs no Waggle account or external database. Graph Studio lets you browse nodes and relationships, edit them and follow how a memory changed over time; `.abhi` files move a graph between clients. In the browser workspace the agent only proposes edits — a human approves the exact wording before it becomes authoritative.

Python 3.11+ and `pipx` are required. Connecting the server is not enough on its own: the client's hooks, skills or project instructions have to call these tools, or the agent will not touch memory by itself. Run `pipx ensurepath` and reopen the terminal first, otherwise the `waggle-mcp` command stays out of reach.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `WAGGLE_TRANSPORT`, `WAGGLE_BACKEND`, `WAGGLE_DB_PATH`, `WAGGLE_DEFAULT_TENANT_ID`, `WAGGLE_MODEL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env WAGGLE_TRANSPORT=<WAGGLE_TRANSPORT> --env WAGGLE_BACKEND=<WAGGLE_BACKEND> --env WAGGLE_DB_PATH=<WAGGLE_DB_PATH> --env WAGGLE_DEFAULT_TENANT_ID=<WAGGLE_DEFAULT_TENANT_ID> --env WAGGLE_MODEL=<WAGGLE_MODEL> --transport stdio waggle-mcp -- uvx waggle-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from waggle-mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add waggle-mcp --env WAGGLE_TRANSPORT=<WAGGLE_TRANSPORT> --env WAGGLE_BACKEND=<WAGGLE_BACKEND> --env WAGGLE_DB_PATH=<WAGGLE_DB_PATH> --env WAGGLE_DEFAULT_TENANT_ID=<WAGGLE_DEFAULT_TENANT_ID> --env WAGGLE_MODEL=<WAGGLE_MODEL> -- uvx waggle-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from waggle-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "waggle-mcp": {
            "command": "uvx",
            "args": [
                "waggle-mcp"
            ],
            "env": {
                "WAGGLE_TRANSPORT": "<WAGGLE_TRANSPORT>",
                "WAGGLE_BACKEND": "<WAGGLE_BACKEND>",
                "WAGGLE_DB_PATH": "<WAGGLE_DB_PATH>",
                "WAGGLE_DEFAULT_TENANT_ID": "<WAGGLE_DEFAULT_TENANT_ID>",
                "WAGGLE_MODEL": "<WAGGLE_MODEL>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from waggle-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "waggle-mcp": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "waggle-mcp"
            ],
            "env": {
                "WAGGLE_TRANSPORT": "<WAGGLE_TRANSPORT>",
                "WAGGLE_BACKEND": "<WAGGLE_BACKEND>",
                "WAGGLE_DB_PATH": "<WAGGLE_DB_PATH>",
                "WAGGLE_DEFAULT_TENANT_ID": "<WAGGLE_DEFAULT_TENANT_ID>",
                "WAGGLE_MODEL": "<WAGGLE_MODEL>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from waggle-mcp <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e WAGGLE_TRANSPORT=<WAGGLE_TRANSPORT> -e WAGGLE_BACKEND=<WAGGLE_BACKEND> -e WAGGLE_DB_PATH=<WAGGLE_DB_PATH> -e WAGGLE_DEFAULT_TENANT_ID=<WAGGLE_DEFAULT_TENANT_ID> -e WAGGLE_MODEL=<WAGGLE_MODEL> waggle-mcp uvx waggle-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from waggle-mcp <command>

## When to use it
- pick up a project in a fresh session without pasting old chat
- record a decision together with the reasoning behind it
- trace what a requirement depends on and what it affects
- spot contradictions between older and newer agreements
- move a memory graph to another MCP client

## Example prompts
- Load the project context with `prime_context` and summarise where we left off
- Search the graph for everything tied to the database choice and show its history
- Record with `observe_conversation` that we settled on PostgreSQL

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md