Waggle Mcp

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

# 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).

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:

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:

{
  "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:

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:

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

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 — 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:

{
  "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:

{
  "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

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:

[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

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).

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?

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
• Source: 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.