# Waggle Mcp

> Persistent graph-backed conversational memory for AI agents.

- **Type:** MCP server
- **Install:** `agentstack add mcp-abhigyan-shekhar-waggle-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Abhigyan-Shekhar](https://agentstack.voostack.com/s/abhigyan-shekhar)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.8
- **License:** Apache-2.0
- **Upstream author:** [Abhigyan-Shekhar](https://github.com/Abhigyan-Shekhar)
- **Source:** https://github.com/Abhigyan-Shekhar/Waggle-mcp
- **Website:** https://pypi.org/project/waggle-mcp/

## Install

```sh
agentstack add mcp-abhigyan-shekhar-waggle-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

waggle-mcp

  Persistent memory that remembers decisions, reasons, and contradictions across sessions.
  Your AI forgets everything when the context window closes. Waggle gives it a graph-backed brain that persists.

  Not a code indexer. A conversational memory engine — it stores what you decided, why you decided it, and what changed, so the next session picks up where the last one left off.

  
  
  
  
  
  

---

## Core

This repository is the public Waggle product repo: Apache-2.0 licensed, available on GitHub and PyPI, and focused on the local-first memory engine.

## Tech Stack

- Python 3.11+ package built with `pyproject.toml`
- MCP server exposed through `waggle-mcp`
- SQLite graph storage by default, with an optional Neo4j backend
- Local sentence-transformers embeddings with a deterministic offline fallback
- Ruff, mypy, and pytest for linting, type checks, formatting, and tests
- GitHub Actions for pull request CI/CD checks
- Vite/React assets for the bundled Graph Studio UI under `apps/mcp/graph-ui/`

---

## Quick Start

```bash
# Install globally (no venv needed)
pipx install waggle-mcp

# One-line setup — detects your MCP clients and writes config
waggle-mcp setup --yes

# Verify everything is healthy
waggle-mcp doctor
```

*(No `pipx`? Run `brew install pipx && pipx ensurepath` first.)*

`setup --yes` detects Claude Code, Codex, Cursor, Gemini CLI, and Antigravity, writes the MCP config, and installs automatic memory hooks where supported. Restart your client and you're live.

> **Windows users:** Run all commands with `python -X utf8` or set `PYTHONUTF8=1` to avoid `UnicodeEncodeError` from emoji in log output.

## Local Development Setup

These steps are intended to work on a clean macOS, Linux, or Windows checkout with Python 3.11+ and Git installed:

For a complete list of supported environment variables and configuration options, see [docs/environment-variables.md](docs/environment-variables.md).

```bash
git clone https://github.com/Abhigyan-Shekhar/Waggle-mcp.git
cd Waggle-mcp
python -m venv .venv
source .venv/bin/activate      # macOS/Linux
# .venv\Scripts\activate       # Windows PowerShell
python -m pip install --upgrade pip
pip install -e ".[dev]"
WAGGLE_MODEL=deterministic pytest -q
ruff check src/ tests/
ruff format --check src/ tests/
```

Use `WAGGLE_MODEL=deterministic` for local verification so setup does not require downloading the embedding model.

## Install Waggle

Waggle is a local MCP server that gives coding agents persistent graph memory.

Recommended:

- VS Code: install the live `Waggle: Local Memory for AI Agents` extension from the Marketplace for one-click setup
- MCP clients: use [docs/install](./docs/install/README.md) and Smithery metadata in `smithery.yaml`
- Claude: use [docs/install/claude-code.md](./docs/install/claude-code.md) or [docs/install/claude-desktop.md](./docs/install/claude-desktop.md)
- Developers: `pipx install waggle-mcp`

Benchmark:

- LongMemEval 500-case retrieval-only: `97.4% R@5`, `89.0% Exact@5` for `graph_raw` retrieval

VS Code extension features:

- one-click `Enable for this Workspace` onboarding
- installs `waggle-mcp` with consent if it is missing
- safely creates or updates `.vscode/mcp.json`
- preserves existing non-Waggle MCP servers
- runs `waggle-mcp doctor`
- opens Graph Studio
- exports Waggle memory from the editor

Claude distribution:

- Claude Code does not use an `.mcpb` bundle. Users add Waggle directly as an MCP server:

```bash
pipx install waggle-mcp
claude mcp add --transport stdio waggle -- waggle-mcp serve --transport stdio
```

- Claude Desktop uses the `claude-desktop-extension.mcpb` bundle, which can be distributed through GitHub Releases.

Manual MCP config:

```json
{
  "mcpServers": {
    "waggle": {
      "command": "waggle-mcp",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}
```

## Enterprise Evaluation

For self-hosted production review and security posture:

- [Production deployment guide](docs/deployment/production.md)
- [Security model](docs/security/security-model.md)
- [Hardening checklist](docs/security/hardening-checklist.md)
- [Reference](docs/reference.md)

## Contributing & Community

- [Contributing guide](./CONTRIBUTING.md)
- [Repository map](./docs/repository-map.md)
- [Starter issues](./docs/good-first-issues.md)
- [Label catalog](./.github/labels.yml)
- Contact channel: open a GitHub issue for bugs, feature proposals, and contributor assignment requests. Use `SECURITY.md` for vulnerability reports.

Contributor layout note:
- The repo root is reserved for packaging, deployment entrypoints, and external registry manifests. Contributor-facing docs, examples, and utilities should live under `docs/`, `examples/`, `scripts/`, or `deploy/`.

### Maintainer Tip

Repository labels are synced from [`.github/labels.yml`](./.github/labels.yml). To preview changes locally:

```bash
python3 scripts/sync_github_labels.py --repository Abhigyan-Shekhar/Waggle-mcp --dry-run
```

---

## 60-Second Demo

No MCP client needed. Run this from a fresh install:

```bash
waggle-mcp demo
```

This imports a pre-loaded example graph and runs 4 scripted queries locally — no API key, no network, no client required. Add `--with-embeddings` to use the real sentence-transformers model for higher-fidelity retrieval (requires ~420 MB download on first run).

---

## Why Waggle

`waggle-mcp` is a local-first memory layer for MCP-compatible AI clients, built on a persistent knowledge graph.

The core difference from flat note storage or chunked RAG is the graph structure. Waggle doesn't just store facts — it stores the relationships between them: this decision depends on that constraint, this preference contradicts that earlier one, this requirement was updated three sessions ago. When you query, you get a subgraph with the reasoning chain attached, not just the matching text.

| Without Waggle | With Waggle |
|---|---|
| Paste context into every session | Compact subgraph retrieved at query time |
| Session-local memory only | Persistent memory across all sessions |
| Flat notes, no structure | Typed nodes and edges: decisions, reasons, contradictions |
| "What changed?" requires replaying logs | Temporal queries, diffs, and conflict resolution are first-class |
| Contradictions silently overwrite history | Both positions preserved, contradiction edge explicit |

### What Is In Core Today

Waggle Core is the open-source local memory foundation:

- SQLite-backed graph memory
- MCP server integration
- CLI setup and doctor flows
- local embeddings or deterministic fallback
- graph querying, observation, and context priming
- import/export and graph inspection utilities

## Product Scope

This public repo is the product-facing Waggle surface:

- MCP server and tool surface
- local-first graph memory
- automatic memory hooks and orchestration
- `.abhi` export, import, diff, merge, and checkpoint handoff
- Graph Studio and admin tooling

Research artifacts, benchmark harnesses, evaluation reports, and paper material now live in the private `waggle-pro` repo.

---

## Architecture

```mermaid
flowchart TD
    U["User / Developer"] --> C["MCP ClientClaude, Codex, Cursor, Gemini CLI, Antigravity, ChatGPT"]
    C --> S["waggle.serverMCP tool surface"]

    S --> P["Automatic memory policyprime_context before sessionsquery_graph before contextual answersobserve_conversation after durable turns"]

    P --> R["RecursiveContextControllertoken-budgeted context assembly"]
    R --> HR["Hybrid retrievalgraph + verbatim transcript + recency"]
    HR --> GE["Graph engine"]

    GE --> SQ["MemoryGraphSQLite local-first store"]
    GE --> N4J["Neo4jMemoryGraphremote / HTTPS deployment option"]

    SQ --> DM["Graph data modeltyped nodes + typed edges"]
    N4J --> DM

    DM --> NT["Nodesfact, entity, concept,preference, decision, question, note"]
    DM --> ET["Edgesupdates, contradicts, depends_on,derived_from, relates_to, similar_to"]

    P --> ING["Ingestion pipeline"]
    ING --> VT["Verbatim transcript stored first"]
    VT --> EX["Memory extraction"]
    EX --> INF["Edge inference + evidence records"]
    INF --> DM

    R --> PACK["Compact context packranked subgraph + provenanceconflicts + update chains"]

    DM --> CW["Context windowssession-level memory containers"]
    CW --> XW["Cross-window edgeshandoff, overlap, temporal continuity"]

    DM --> ABHI[".abhi portable memory artifact"]
    ABHI --> OPS["commit / pull / diff / merge / fsck / show"]
    ABHI --> HANDOFF["checkpoint handoffbetween sessions or machines"]

    S --> GS["Graph Studio / debug toolsretrieval debugger, graph viz,conflict review, provenance inspection"]
```

---

## Recursive Context Assembly

Waggle stores memory outside the model context window. Instead of pasting long context into every prompt, agents call `build_context` to get a compact, high-signal context pack assembled from the graph.

Inspired by [Recursive Language Models](https://github.com/alexzhang13/rlm) — the idea of externalising long context into an environment and interacting with it through decomposition and targeted retrieval.

**How it works:**

1. **Decompose** — the query is split into targeted subqueries (decisions, constraints, implementation details, unfinished work, conflicts)
2. **Retrieve** — each subquery runs against graph, hybrid, and verbatim transcript retrieval
3. **Expand** — the graph is traversed around top nodes via typed edges (`updates`, `contradicts`, `depends_on`, `derived_from`)
4. **Resolve** — update chains and contradictions are detected; superseded nodes are flagged
5. **Deduplicate & rank** — overlapping hits are merged; high-signal node types (decisions, preferences) are boosted
6. **Compress** — everything is packed into a structured context brief under a configurable token budget

**Example MCP call:**

```json
{
  "tool": "build_context",
  "arguments": {
    "query": "Continue implementing Waggle from where we left off",
    "project": "waggle-mcp",
    "token_budget": 1000,
    "depth": 2
  }
}
```

**Example output:**

```
### Waggle Recursive Context Pack
Task: Continue implementing Waggle from where we left off

Current relevant decisions:
- [decision] Use SQLite for local storage: We chose SQLite with WAL mode for local-first deployments.
- [decision] Hybrid retrieval default: Hybrid (vector + BM25 + graph) is the default retrieval mode.

Active constraints:
- [preference] No external LLM APIs required: All retrieval must work fully local.

Important implementation context:
- [fact] RecursiveContextController added: New module waggle/recursive_context.py implements build_context.

Conflicts or superseded context:
- Possible conflict: 'Use Flask' contradicts 'Use FastAPI'
```

**Config env vars:**

| Variable | Default | Description |
|---|---|---|
| `WAGGLE_RECURSIVE_CONTEXT_ENABLED` | `true` | Enable/disable the feature |
| `WAGGLE_RECURSIVE_CONTEXT_DEFAULT_BUDGET` | `1200` | Default token budget |
| `WAGGLE_RECURSIVE_CONTEXT_MAX_SUBQUERIES` | `6` | Max decomposed subqueries |
| `WAGGLE_RECURSIVE_CONTEXT_DEFAULT_DEPTH` | `2` | Graph expansion depth |
| `WAGGLE_RECURSIVE_CONTEXT_INCLUDE_EVIDENCE` | `true` | Include transcript evidence |

**Tool aliases:** `recursive_context`, `assemble_context`, `rlm_context` all resolve to `build_context`.

---

## How It Works

```
User  → Agent → observe_conversation(...)  → Graph stores typed nodes + edges
User  → Agent → query_graph("database")   → Subgraph returned → Agent answers with linked rationale
```

**Session 1**
```
User:  Let's use PostgreSQL. MySQL replication has been painful.
Agent: [calls observe_conversation()]
       → stores decision node: "Chose PostgreSQL over MySQL"
       → stores reason node:   "MySQL replication painful"
       → links them with a depends_on edge
```

**Session 2** (fresh context window, no history)
```
User:  What did we decide about the database?
Agent: [calls query_graph("database decision")]
       → retrieves the decision node + linked reason from Session 1
       "You decided on PostgreSQL. The reason recorded was that MySQL replication had been painful."
```

**Session 3**
```
User:  Actually, let's reconsider — the team is more familiar with MySQL.
Agent: [calls store_node() + store_edge(new_node → old_node, "contradicts")]
       → both positions are preserved, and the contradiction is explicit
```

---

## Setting Up as an MCP Server

> **One-time install:** `pipx install waggle-mcp` — no API key, no cloud account, no Docker required for local use.

Shared JSON config for clients that accept `mcpServers` JSON:

```json
{
  "mcpServers": {
    "waggle": {
      "command": "waggle-mcp",
      "args": ["serve"],
      "env": {
        "WAGGLE_TRANSPORT": "stdio",
        "WAGGLE_BACKEND": "sqlite",
        "WAGGLE_DB_PATH": "~/.waggle/waggle.db",
        "WAGGLE_DEFAULT_TENANT_ID": "local-default",
        "WAGGLE_MODEL": "all-MiniLM-L6-v2",
        "WAGGLE_STARTUP_MODE": "normal"
      }
    }
  }
}
```

> First run takes ~30 s — `all-MiniLM-L6-v2` (~420 MB) downloads on first use.
> To skip the download: set `"WAGGLE_MODEL": "deterministic"` (offline-safe, instant start, slightly lower retrieval quality).

### Claude Desktop

Config file location:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Add the `mcpServers` block above.

### Claude Code

```bash
claude mcp add waggle \
  --env WAGGLE_TRANSPORT=stdio \
  --env WAGGLE_BACKEND=sqlite \
  --env WAGGLE_DB_PATH=~/.waggle/waggle.db \
  --env WAGGLE_DEFAULT_TENANT_ID=local-default \
  --env WAGGLE_MODEL=all-MiniLM-L6-v2 \
  -- waggle-mcp serve
```

Claude Code also supports **automatic memory hooks** — see the [Hooks](#automatic-memory-hooks-claude-code) section below.

### Codex

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.waggle]
command = "waggle-mcp"
args    = ["serve"]
env     = {
  WAGGLE_TRANSPORT         = "stdio",
  WAGGLE_BACKEND           = "sqlite",
  WAGGLE_DB_PATH           = "~/.waggle/waggle.db",
  WAGGLE_DEFAULT_TENANT_ID = "local-default",
  WAGGLE_MODEL             = "all-MiniLM-L6-v2"
}
```

`waggle-mcp setup --yes` also writes a managed memory block into `AGENTS.md` in the current workspace so automatic memory is enabled by default for that repo.

### Gemini CLI

```bash
gemini mcp add waggle \
  -e WAGGLE_TRANSPORT=stdio \
  -e WAGGLE_BACKEND=sqlite \
  -e WAGGLE_DB_PATH=~/.waggle/waggle.db \
  -e WAGGLE_DEFAULT_TENANT_ID=local-default \
  -e WAGGLE_MODEL=all-MiniLM-L6-v2 \
  waggle-mcp serve
```

After restarting, run `/mcp` to confirm Waggle is connected.

### Cursor

`Cursor Settings → Features → MCP Servers → + Add`
- Command: `waggle-mcp`
- Args: `serve`
- Env vars: same keys as the JSON block above.

### Antigravity

The AI agent reads `~/.gemini/antigravity/mcp_config.json` (macOS/Linux) or `%USERPROFILE%\.gemini\antigravity\mcp_config.json` (Windows). Add the `waggle` block there. The VS Code extension panel reads a different file — adding waggle there will NOT make it available to the AI agent.

Run `waggle-mcp doctor` to see exactly which config files exist and which ones have a waggle entry.

### ChatGPT

ChatGPT custom MCP connectors require a remote HTTPS server. Deploy Waggle in HTTP mode with the Neo4j backend, expose `/mcp` over HTTPS, then add that URL as a custom connector in ChatGPT (`Settings → Connectors → Advanced → Developer mode`).

```bash
WAGGLE_TRANSPORT=http \
WAGGLE_BACKEND=neo4j \
WAGGLE_DEFAULT_TENANT_ID=workspace-default \
WAGGLE_NEO4J_URI=bolt://localhost:7687 \
WAGGLE_NEO4J_USERNAME=neo4j \
WAGGLE_NEO4J_PASSWORD=change-me \
waggle-mcp serve
```

Do not expose Waggle publicly without authentication.

### `waggle-mcp` not on PATH?

```bash
pipx ensurepath   # then restart your terminal
```

---

## Automatic Memory — Prompt Rules

Registering Waggle as an MCP server only makes the tools available. For the agent to call them autom

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Abhigyan-Shekhar](https://github.com/Abhigyan-Shekhar)
- **Source:** [Abhigyan-Shekhar/Waggle-mcp](https://github.com/Abhigyan-Shekhar/Waggle-mcp)
- **License:** Apache-2.0
- **Homepage:** https://pypi.org/project/waggle-mcp/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Versions

- **0.1.8** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-abhigyan-shekhar-waggle-mcp
- Seller: https://agentstack.voostack.com/s/abhigyan-shekhar
- 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%.