waggle-mcp 0.1.5

MCP server that gives LLMs persistent graph-structured memory

Persistent, structured memory for AI agents — up to 4× fewer tokens than chunk-based retrieval.
Your LLM remembers facts, decisions, and context across every conversation, backed by a real knowledge graph.

---

Why waggle-mcp?

waggle-mcp is a local-first memory layer for MCP-compatible AI clients, built on a persistent knowledge graph. It gives your AI a persistent knowledge graph it can read and write through any MCP-compatible client (Claude Desktop, Cursor, Codex, Antigravity, etc.).

Stuffed context	Structured retrieval
Huge prompts every session	Compact subgraph retrieved at query time
Session-local memory	Persistent multi-session memory
Flat notes and chunks	Typed nodes and edges: decisions, reasons, contradictions
"What changed?" requires replaying logs	Temporal queries and diffs are first-class

Waggle yields up to ~4× fewer tokens than naive chunked retrieval on factual queries. Graph-traversal queries spend more tokens to include necessary reasoning context such as updates, contradictions, and dependencies.

---

Quick start

pip install waggle-mcp
waggle-mcp init
# Restart your MCP client. Done.

init detects your MCP client, writes its config, and creates the local database directory. Default mode is local SQLite with on-device embeddings. Antigravity and manual configuration details are in docs/reference.md.

---

See it in action

Session 1 — April 10

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 — April 12 (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 April 10

       "You decided on PostgreSQL on April 10. The reason recorded was
        that MySQL replication had been painful."

Session 3 — April 14

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

---

Key Features

• Automatic Extraction: observe_conversation ingests facts into the graph without manual schema work.
• Portable Context: export_context_bundle generates Markdown/JSON context packs for another AI.
• Vault Round-trip: export_markdown_vault / import_markdown_vault for Obsidian-style node editing.
• Conflict Resolution: list_conflicts / resolve_conflict to manage contradictions without losing history.
• Deterministic Fallback: Stable SHA-256 hashing for reliable, reproducible offline operation when transformer models are unavailable.

---

Benchmarks & Verification

Waggle performance is verified against checked-in fixtures and automated regression tests.

Project Fixtures

Area	Corpus	Result
Extraction	25-case deterministic fixture	100.0%
Retrieval	18-query retrieval fixture	83.3% Hit@k
Comparative eval	27-scenario / 69-query corpus	88.4% Hit@k, 76.8% exact support, 58.5 tokens/query
Query stress	40 adversarial retrieval-only cases	97.5% Hit@k, 97.5% exact support
Deduplication	22 cases (semi-semantic)	77.3% (17/22), zero false merges
Unit Tests	Infrastructure & Logic	90+ passing tests

External Benchmarks

Benchmark	Coverage	Metric	Status
LongMemEval	500 questions	97.4% R@5	Verified (Held-out split: 81.6% deterministic)
LoCoMo	1,986 items	Pending	Adapter implemented
ConvoMem	250 items	Pending	Adapter implemented
MemBench	8,500 items	Pending	Adapter implemented

• Token efficiency: Waggle averages 58.5 tokens per retrieval vs 150.9 for naive chunked RAG.
• Retrieval split: The flat slice (factual_recall, temporal_*) measures 85% / 85%; the graph slice (change, delta, synthesis, paraphrase) measures 93% / 70%.
• Deduplication: Zero false-positive merges across the threshold sweep. Accuracy limited by conservative similarity bounds.

Detailed benchmark artifacts and the new Benchmark Methodology guide provide full traceability.

---

Reference & Docs

Detailed reference material lives in external documentation:

• docs/reference.md: Environment variables, admin commands, Docker setup, and full tool surface.
• deploy/kubernetes/README.md: Production deployment.
• docs/runbooks/: Operations and troubleshooting.
• tests/artifacts/README.md: Benchmark artifacts and traceability.

---

License

MIT — see LICENSE.