{ "markdown": "\n\n

\n \"Waggle\"\n

\n\n

\n Project memory for humans and AI agents.
\n Keep decisions, context, and the reasons behind them across conversations.\n

\n\n

\n \"PyPI\"/\n \"Python\n \"MCP\n \"Apache-2.0\"/\n

\n\n

\n Install Waggle ·\n Try the browser workspace ·\n Documentation\n

\n\n---\n\n## Keep the context, not just the conversation\n\nWaggle is an open-source, local-first memory layer for AI agents. It stores\nproject knowledge as a graph: what you decided, why it matters, what it depends\non, and what has changed. Your next conversation can pick up from that context\ninstead of starting over.\n\nUse Waggle with your MCP client, inspect and edit memory in Graph Studio, or\nbring a portable memory graph into the browser workspace.\n\n- **Continue across sessions.** Recall project decisions, requirements, preferences,\n and open questions without repeatedly pasting context.\n- **Understand the reasoning.** Explore relationships, supporting evidence,\n contradictions, and the history behind a decision.\n- **Keep control of corrections.** In the WebMCP workspace, agents propose changes;\n humans approve the exact content before it becomes authoritative.\n- **Take memory with you.** Export and import `.abhi` files across supported\n workflows without tying your graph to one client.\n- **Start locally.** The default SQLite store lives on your machine. Local use\n does not require a Waggle account or an external database.\n\n## Quick Start\n\nThe Python package requires Python 3.11+ and `pipx`. On macOS, you can install\n`pipx` with `brew install pipx`; see the [installation guide](docs/install/README.md)\nfor client-specific options.\n\n```bash\npipx install waggle-mcp\npipx ensurepath\n```\n\nRestart your terminal after the first `pipx ensurepath`, then run:\n\n```bash\nwaggle-mcp setup --yes\nwaggle-mcp doctor\n```\n\nRestart your MCP client to load Waggle. Setup detects supported clients and\nwrites their configuration; automatic memory behavior uses the client's\ninstalled hooks, skills, or project instructions.\n\nTo check continuity, ask your agent to remember a project decision, then open\na fresh session in the same project and ask what was decided. Keep the same\nproject identifier across sessions.\n\n### Choose your client\n\n| Client | Setup guide |\n|---|---|\n| Codex | [Install the Waggle plugin or configure the MCP server](docs/install/codex.md) |\n| Claude Code | [MCP server and automatic memory hooks](docs/install/claude-code.md) |\n| Claude Desktop | [Desktop extension and manual configuration](docs/install/claude-desktop.md) |\n| VS Code | [Waggle extension and workspace setup](docs/install/vscode.md) |\n| Cursor | [Connect the local MCP server](docs/install/cursor.md) |\n| Antigravity | [Client configuration](docs/install/antigravity.md) |\n| Other MCP clients | [Standard MCP configuration](docs/install/generic-mcp.md) |\n| ChatGPT with Site tools | [Use the browser workspace](#webmcp--memory-in-your-browser) |\n\nFor clients that accept an `mcpServers` configuration:\n\n```json\n{\n \"mcpServers\": {\n \"waggle\": {\n \"command\": \"waggle-mcp\",\n \"args\": [\"serve\", \"--transport\", \"stdio\"]\n }\n }\n}\n```\n\nIf the command is not found, run `pipx ensurepath` and reopen your terminal.\nUse the [troubleshooting guide](docs/install/troubleshooting.md) for installation,\nstartup, and client connection issues.\n\n## How memory works\n\nWaggle separates durable project knowledge from the model's context window.\nAn agent retrieves relevant memory when needed and records meaningful outcomes\nfor later conversations.\n\n1. **Capture:** record decisions, constraints, preferences, and supporting context.\n2. **Connect:** link related memories and preserve contradictions and updates.\n3. **Recall:** retrieve scoped context with evidence and provenance.\n4. **Continue:** use that context in another session or supported client.\n\nThe core MCP workflow uses `prime_context` to load project context,\n`query_graph` to retrieve relevant history, and `observe_conversation` to\nrecord durable outcomes. `build_context` assembles a compact context pack for\na specific task. Tool availability alone does not make an agent use memory\nautomatically; its hooks, skills, or instructions must call these tools.\n\nSee the [tool reference](docs/reference.md) and\n[configuration reference](docs/environment-variables.md) for the full API and\nretrieval settings.\n\n## Graph Studio\n\nGraph Studio makes project memory inspectable and editable. Browse nodes and\nrelationships, add or remove graph content, inspect source evidence, and review\nhow a memory changed over time.\n\nThe browser workspace provides focused views for project context, memories,\nproposals, and activity. Graph Studio provides the graph-level view of that\nserver-backed memory; private browser imports remain in the workspace tab.\n\n**[Open Graph Studio](https://waggle-webmcp.onrender.com/graph)**\n\n## WebMCP — memory in your browser\n\nThe [Waggle workspace](https://waggle-webmcp.onrender.com/) lets a human and a\ncompatible browser agent work with the same project memory. Its WebMCP adapter\nregisters page-level Site tools through `document.modelContext.registerTool`.\nThis is separate from installing Waggle's MCP server or configuring a remote\nMCP connector.\n\n### Connect and use the workspace\n\n1. Open the workspace in ChatGPT's built-in browser using a model and account\n configuration that supports Site tools.\n2. In the address bar, check **Site tools → Available site tools** and confirm\n the five Waggle tools are available. Keep this workspace tab open while\n working with its memory.\n3. Explore the sample project or select **Load private .abhi** to work with your\n own graph.\n4. Ask for a project brief or recall a specific decision. On the hosted workspace,\n use `project_id: waggle-webmcp`, including after importing your own graph.\n5. To correct a memory, ask the agent to propose a replacement. Review it in\n **Proposals**, edit it if needed, and approve the exact value.\n6. Ask the agent to apply the approved proposal using only its actual proposal\n ID. Recall the decision again to confirm the result and inspect its history.\n\nFor example:\n\n```text\nCall Waggle's get_project_brief with project_id \"waggle-webmcp\".\nUse the returned memories to catch me up on this project.\n```\n\nIf Site tools are unavailable, check the browser's permissions and configuration.\nIf the browser blocks an apply call, you can use **Apply approved change** on\nthe approved proposal and confirm the action yourself. This uses the same\napproval and freshness checks; it does not bypass browser safeguards.\n\n### Browser tools\n\n| Tool | What it does |\n|---|---|\n| `get_project_brief` | Returns the project's goal, current decisions, constraints, state, and open questions. |\n| `recall_memory` | Finds current authoritative memories for a query, with supersession provenance when available. |\n| `propose_memory_change` | Creates a pending correction for human review without changing authoritative memory. |\n| `apply_approved_memory_change` | Applies the exact approved value using only a proposal ID. |\n| `load_abhi_for_session` | Loads a portable graph into this browser tab and returns a brief. |\n\n### Corrections you can review\n\n```mermaid\nflowchart LR\n A[Agent proposes a correction] --> B[Human reviews and approves]\n B --> C[Waggle checks approval and target version]\n C --> D[Approved value becomes authoritative]\n D --> E[Previous memory stays in history]\n```\n\nApproved content cannot be changed by the applying agent. If the target memory\nhas changed since the proposal was created, the proposal is marked stale\ninstead of overwriting newer information. Application preserves the previous\nmemory and links it to the replacement with an `updates` edge.\n\nThese approval rules govern the WebMCP correction workflow. They are not a\nclaim that every direct graph-editing or local MCP operation requires approval.\n\n## Bring your own memory\n\nA `.abhi` file is Waggle's portable memory graph. The browser importer reads\nexisting memories; it does not ingest a source repository to invent a project\nbrief.\n\n1. Select **Load private .abhi** in the workspace.\n2. Choose an unencrypted schema 2.x file, up to 700 KiB compressed and 4 MiB\n expanded.\n3. Confirm the **Private session graph** indicator appears. Briefs, recall,\n proposals, and approvals now use that imported copy.\n\nThe import replaces this tab's active workspace; it does not merge with the\nsample graph, modify your original file, or affect another visitor.\n\nYou can also attach the file to a compatible chat and ask:\n\n```text\nUse Waggle's load_abhi_for_session tool to load this .abhi file into\nproject \"waggle-webmcp\" for this session. Then call get_project_brief.\n```\n\nThe agent must be able to read the attachment and provide its bytes as base64.\nThe tool does not accept a local file path or download URL. Use the page's file\npicker if the chat cannot access the attachment.\n\nSee the [portable memory format](docs/abhi-format-v2.md) for archive structure\nand supported operations.\n\n## Your data and deployment options\n\n| Where you use Waggle | Where memory lives |\n|---|---|\n| Local MCP server | SQLite on your machine, at `~/.waggle/waggle.db` by default. |\n| Private browser import | This tab's `sessionStorage`; the importer does not upload the graph to Waggle's backend. |\n| Hosted sample workspace | An isolated, temporary server-side sample project; not an account-based cloud backup. |\n| Self-hosted remote MCP server | Your configured Neo4j backend and infrastructure. |\n\n**Browser lifetime.** Private imports survive page reloads, and browser session\nrestoration can preserve them. Use the workspace's **Reset Demo** control to\nexplicitly clear the private copy and return to the sample project. Closing a\nchat conversation alone is not a guaranteed deletion signal. Browser storage\nis not encrypted by the importer.\n\n**AI services.** Attaching a file in chat shares it with that chat provider.\nMemory returned through tool calls is also shared with the requesting AI\nservice. Local storage does not mean that model inputs stay on your device.\n\n**Hosted preview.** The public workspace is for trying the browser experience,\nnot durable production storage. Its free hosting can pause when idle, take time\nto wake, and lose sample state on restart or redeployment. Opening it does not\nconnect to your local Waggle database. The included SQLite preview configuration\nstores disposable state under `/tmp`, caps admission at 128 sessions per database,\nand rejects new sessions at capacity without evicting existing ones.\n\n**Self-hosting.** The browser preview's governance backend currently requires\nSQLite. Remote MCP hosting with Neo4j is a separate configuration, not a drop-in\nreplacement for that browser workflow. For remote deployment, configure HTTPS,\nauthentication, persistent storage, and backups. Read the\n[production deployment guide](docs/deployment/production.md),\n[security model](docs/security/security-model.md), and\n[hardening checklist](docs/security/hardening-checklist.md) before exposing a\nserver publicly.\n\n## Development\n\nWaggle uses Python for the memory engine and MCP server, and React/Vite for\nGraph Studio and the browser workspace.\n\n```bash\ngit clone https://github.com/Abhigyan-Shekhar/Waggle-mcp.git\ncd Waggle-mcp\npython -m venv .venv\nsource .venv/bin/activate\n# Windows PowerShell: .venv\\Scripts\\Activate.ps1\npython -m pip install -e \".[dev]\"\n\nWAGGLE_MODEL=deterministic pytest -q\nruff check src/ tests/\nruff format --check src/ tests/\n```\n\nOn PowerShell, set `$env:WAGGLE_MODEL=\"deterministic\"` before running `pytest -q`.\nDeterministic embeddings keep tests offline; use the normal embedding model\nwhen evaluating semantic retrieval.\n\nFor frontend changes:\n\n```bash\nnpm ci --prefix apps/mcp/graph-ui\nnpm run test:unit --prefix apps/mcp/graph-ui\nnpm run build --prefix apps/mcp/graph-ui\n```\n\n## Documentation and contributing\n\n- [Installation guides](docs/install/README.md)\n- [Tool reference](docs/reference.md)\n- [Configuration](docs/environment-variables.md)\n- [Portable memory format](docs/abhi-format-v2.md)\n- [Deployment and security](docs/deployment/production.md)\n- [Contributing](CONTRIBUTING.md)\n- [Repository map](docs/repository-map.md)\n- [Report an issue](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues)\n\n## License\n\nWaggle is open source under the [Apache License 2.0](LICENSE).\n", "bytes": 13047, "sha": "d0584a4008f9eaa25ba80b67977d5074fbb57f99d8b6ff73bbedbb9300371f00", "repo_slug": "abhigyan-shekhar/waggle-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_abhigyan_shekhar_waggle_mcp_e30d51f3/readme" }