Waggle-mcp — MCP server for Claude Code and Codex memory
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.
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-mcpWhat Waggle-mcp 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.
What it helps with
- 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 for the agent
- Load the project context with
prime_contextand summarise where we left off - Search the graph for everything tied to the database choice and show its history
- Record with
observe_conversationthat we settled on PostgreSQL
How to install Waggle-mcp
Platform CLI
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-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from waggle-mcp <command>
Platform CLI
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-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from waggle-mcp <command>
Config file
{
"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>
Config file
{
"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>
Platform CLI
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-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from waggle-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Waggle-mcp
How do I install Waggle-mcp in Claude Code?
Install the package with pipx install waggle-mcp, then run pipx ensurepath and reopen your terminal. Add the server with claude mcp add waggle-mcp -- uvx waggle-mcp and restart the client.
What does Waggle-mcp do?
It is an MCP server that stores project knowledge as a graph and hands the relevant part to your agent on request. Decisions, constraints and preferences stay available in later sessions.
Does memory work automatically once the server is connected?
No. The tools need to be invoked by hooks, skills or project instructions — a connected server alone does not make an agent use memory.
