Abhigyan-Shekhar/Waggle-mcp

Keep decisions, context, and the reasons behind them across conversations.
Install Waggle ·
Try the browser workspace ·
Documentation
---
Keep the context, not just the conversation
Waggle is an open-source, local-first memory layer for AI agents. It stores
project knowledge as a graph: what you decided, why it matters, what it depends
on, and what has changed. Your next conversation can pick up from that context
instead of starting over.
Use Waggle with your MCP client, inspect and edit memory in Graph Studio, or
bring a portable memory graph into the browser workspace.
- **Continue across sessions.** Recall project decisions, requirements, preferences,
and open questions without repeatedly pasting context.
- **Understand the reasoning.** Explore relationships, supporting evidence,
contradictions, and the history behind a decision.
- **Keep control of corrections.** In the WebMCP workspace, agents propose changes;
humans approve the exact content before it becomes authoritative.
- **Take memory with you.** Export and import .abhi files across supported
workflows without tying your graph to one client.
- **Start locally.** The default SQLite store lives on your machine. Local use
does not require a Waggle account or an external database.
Quick Start
The Python package requires Python 3.11+ and pipx. On macOS, you can install
pipx with brew install pipx; see the installation guide
for client-specific options.
Restart your terminal after the first pipx ensurepath, then run:
Restart your MCP client to load Waggle. Setup detects supported clients and
writes their configuration; automatic memory behavior uses the client's
installed hooks, skills, or project instructions.
To check continuity, ask your agent to remember a project decision, then open
a fresh session in the same project and ask what was decided. Keep the same
project identifier across sessions.
Choose your client
| Client | Setup guide |
|---|---|
| Codex | Install the Waggle plugin or configure the MCP server |
| Claude Code | MCP server and automatic memory hooks |
| Claude Desktop | Desktop extension and manual configuration |
| VS Code | Waggle extension and workspace setup |
| Cursor | Connect the local MCP server |
| Antigravity | Client configuration |
| Other MCP clients | Standard MCP configuration |
| ChatGPT with Site tools | Use the browser workspace |
For clients that accept an mcpServers configuration:
If the command is not found, run pipx ensurepath and reopen your terminal.
Use the troubleshooting guide for installation,
startup, and client connection issues.
How memory works
Waggle separates durable project knowledge from the model's context window.
An agent retrieves relevant memory when needed and records meaningful outcomes
for later conversations.
1. **Capture:** record decisions, constraints, preferences, and supporting context.
2. **Connect:** link related memories and preserve contradictions and updates.
3. **Recall:** retrieve scoped context with evidence and provenance.
4. **Continue:** use that context in another session or supported client.
The core MCP workflow uses prime_context to load project context,
query_graph to retrieve relevant history, and observe_conversation to
record durable outcomes. build_context assembles a compact context pack for
a specific task. Tool availability alone does not make an agent use memory
automatically; its hooks, skills, or instructions must call these tools.
See the tool reference and
configuration reference for the full API and
retrieval settings.
Graph Studio
Graph Studio makes project memory inspectable and editable. Browse nodes and
relationships, add or remove graph content, inspect source evidence, and review
how a memory changed over time.
The browser workspace provides focused views for project context, memories,