v0.1 · MCP server · open source

Your AI agent can now remember.

Waggle is a local-first MCP memory layer. It stores the decisions, reasons, and contradictions your agents need to pick up where the last session ended.

Install

$pipx install waggle-mcp
$waggle-mcp setup --yes
$waggle-mcp doctor

Ready in ~60 seconds. No account, no API key, no Docker.

waggle-mcp · live

decision · 38 ms · 32 tokens

Nodes · 5

Graph

→Decision

Use Supabase Auth with PKCE flow.

Selected over NextAuth for built-in RLS and native social login.

stored · 2 days ago

Connected

↳becauseReason
↳extended byUpdated

Hover a node to explore · auto-cycles every 3.4s

Works with

Claude · Cursor · Codex · Gemini CLI · Antigravity

Runs locally

SQLite by default · no cloud account · no Docker required

01 — About Waggle

Five principles. One memory layer.

Scroll through what makes Waggle different from cloud-based memory tools. Each principle is a non-negotiable in how the system was built.

waggle://local-first01 / 05

Memory that lives on your machine.

SQLite by default. No cloud account, no API key, no Docker. Your decisions, code context, and reasoning never cross the network unless you explicitly export them.

Zero network roundtrips for recall
Works offline — plane, tunnel, restricted networks
Your IP and project history don't leave your machine

$ls -la ~/.waggle/

memory.sqlite 4.2 MB

index.idx 128 KB

config.toml 1.4 KB

$waggle-mcp status

● running locally

238 nodes · 412 edges

last write 4 min ago

waggle://typed-graph02 / 05

Not flat notes. A graph of typed relationships.

Decisions, reasons, dependencies, updates, and contradictions are first-class node types with typed edges between them. Agents follow reasoning chains, not just keyword matches.

Five built-in node types · extensible
Edges carry semantic labels, not just pointers
Recall walks the graph, not a vector blob

Node types

Decision

what was chosen

Reason

why it was chosen

Depends_on

what it requires

Updated

how it changed

Contradicts

what it replaced

Edge labels

because

Decision → Reason

requires

any → Depends_on

extends

Updated → Decision

superseded_by

Contradicts → Decision

related_to

any → any

waggle://preserves-change03 / 05

Old plans stay linked. They don't get erased.

When a decision changes, Waggle creates a new node connected to the old one with a typed edge. Both versions remain retrievable — no silent overwrites, no lost reasoning, no audit gaps.

Every change is an append, never a replace
Old positions queryable by edge or by date
The reason something was abandoned is part of the record

was

NextAuth + custom Postgres

archived · 1 week ago

↕

superseded_by

now

Supabase Auth with PKCE flow

active · today

Both queryable

$waggle-mcp recall "auth approach" → now

$waggle-mcp recall "what did we rule out?" → was

waggle://mcp-native04 / 05

Plugs into every MCP-compatible agent.

Implements the Model Context Protocol spec. Setup detects and configures Claude Code, Cursor, Codex, Gemini CLI, and Antigravity automatically. One install, every agent.

waggle-mcp setup detects installed clients
Writes the right config in the right place
Drops in alongside any other MCP server

Detected on setup

✓Claude Code~/.claude/config.json
✓Cursor~/.cursor/mcp.json
✓Codexcodex.toml
✓Gemini CLIgemini config
✓Antigravityantigravity.yaml

What gets written

{
  "mcpServers": {
    "waggle": {
      "command": "waggle-mcp",
      "args": ["serve"]
    }
  }
}

waggle://portable05 / 05

Your memory is a file you own.

Export the entire graph as a portable .abhi checkpoint. Version it in git, share it across machines, archive it as project history. No vendor lock-in, no proprietary store.

git-track project memory alongside code
Hand context off to a teammate as one file
Restore an archived project's state on a new machine

$waggle-mcp export project-2026.abhi

✓ exported 238 nodes, 412 edges

✓ wrote project-2026.abhi (2.4 MB)

$waggle-mcp import project-2026.abhi

✓ restored 238 nodes, 412 edges

memory now matches checkpoint

01 — About Waggle

Five principles. One memory layer.

Scroll through what makes Waggle different from cloud-based memory tools. Each principle is a non-negotiable in how the system was built.

waggle://local-first01 / 05

Memory that lives on your machine.

SQLite by default. No cloud account, no API key, no Docker. Your decisions, code context, and reasoning never cross the network unless you explicitly export them.

Zero network roundtrips for recall
Works offline — plane, tunnel, restricted networks
Your IP and project history don't leave your machine

$ls -la ~/.waggle/

memory.sqlite 4.2 MB

index.idx 128 KB

config.toml 1.4 KB

$waggle-mcp status

● running locally

238 nodes · 412 edges

last write 4 min ago

02 — In practice

The difference isn't a longer prompt.

It's an agent that actually understands the project it's working inside — across every session, on every machine.

Without Waggle

With Waggle

01
Paste project context into every new chat.
→
Agent retrieves the relevant memory automatically.
02
Chat history is trapped inside one session.
→
Memory persists across sessions and tools.
03
Flat notes and stale summary files.
→
Typed graph of decisions, reasons, and updates.
04
Changed requirements get lost.
→
Updates and contradictions stay explicit.
05
Context window bloats with every recap.
→
Compact, token-budgeted recall packs.
06
The agent knows what was said.
→
The agent understands what changed, and why.

03 — Local-first by design

Memory that lives where your code does.

Most AI memory tools route your project history through a cloud service. Waggle keeps it local — SQLite on disk, queryable in microseconds, portable as a file you own.

01 / 04

Local-first by default

Decisions, reasoning, and code context stay on the machine that wrote them. No data crosses the network unless you explicitly export it.

02 / 04

No account, no recurring bill

pipx install is the whole setup. SQLite ships with Python. Nothing to expense, no plan to upgrade, no usage cap.

03 / 04

Microsecond retrieval

Cloud memory layers add a 50–500 ms network round-trip to every recall. Waggle reads from a local file — recall completes before the agent notices.

04 / 04

Your memory is a file

Export the whole graph as a portable .abhi checkpoint. Hand it off, version it, archive it, move it between machines. No vendor lock-in by design.

How it compares

Cloud memory layers vs. Waggle.

The same six dimensions every team eventually ends up evaluating — in the order they typically come up.

Dimension

Cloud memory layers

Waggle

Where memory lives
CloudVendor servers
WaggleYour machine · SQLite on disk
Setup
CloudAccount · API key · billing
Wagglepipx install waggle-mcp
Pricing model
CloudRecurring · per-call or per-seat
WaggleFree · ships with Python
Works offline
CloudNetwork required
WaggleYes — on a plane, in a tunnel
Recall latency
Cloud50–500 ms over the network
WaggleMicroseconds · local file read
Portability
CloudLocked to vendor store
Waggle.abhi checkpoint you own and export

Cloud memory layers earn their keep when memory has to be shared across teams and machines at scale. Waggle is the opposite trade: built for the individual developer who wants the simplest possible answer to “where does my agent's memory live?”

04 — How it works

From conversation to durable context.

Waggle runs quietly behind your agent: observe what matters, preserve it as connected memory, and bring back the right context when a new session begins.

One PostgreSQL decision · carried across sessions

Stage01ObserveDatabase decision

Waggle notices what is worth remembering.

After a completed turn, Waggle stores the verbatim exchange first. It then extracts durable decisions, preferences, constraints, corrections, and outcomes into typed nodes, infers their relationships, and skips low-value chatter. Every memory stays scoped to the project, agent, and session.

What this means

The agent does the remembering in the background; the source conversation remains available as evidence.

Captures: decisions · preferences · constraints · corrections · outcomes
Scopes: project · agent_id · session_id

observe_conversation({
  project: "waggle-mcp",
  user_message: "Use PostgreSQL; MySQL replication hurt.",
  assistant_response: "PostgreSQL decision recorded."
})
 
✓ verbatim_stored    true
✓ nodes_extracted    2  decision · fact
✓ edges_inferred     1  derived_from

Stage02PersistDatabase decision

A local graph keeps the decision—and what changed.

Waggle keeps the resulting graph in ~/.waggle/waggle.db by default. A decision can link to the fact it came from; a later choice can update or contradict an earlier one. Temporal validity marks what is current without erasing why the old position existed.

What this means

The current answer stays clear, while previous decisions and their reasoning remain inspectable.

Nodes: fact · entity · concept · preference · decision · question · note
Relations: updates · contradicts · depends_on · derived_from · relates_to
Handoff: shared local DB · portable .abhi file between machines

~/.waggle/waggle.db
 
decision   Use PostgreSQL
fact       MySQL replication was painful
edge       decision --derived_from--> fact
history    new decision --updates--> prior decision
status     current / superseded via valid_to

Stage03RecallDatabase decision

A fresh session gets only the context it needs.

At session start, prime_context hydrates the agent with relevant scoped memory. Before a context-dependent answer, query_graph combines graph and verbatim retrieval, follows typed relationships, and separates current decisions from superseded ones. For broader tasks, build_context assembles a compact brief under a token budget.

What this means

No pasted recap and no full transcript replay—just the decision, its rationale, and the change history that matters now.

Routine: prime_context · query_graph
Retrieval: graph + verbatim + typed-edge expansion
Advanced: build_context · recursive · token-budgeted

prime_context({ project: "waggle-mcp" })
 
query_graph({
  query: "What database did we choose, and why?",
  retrieval_mode: "hybrid",
  max_nodes: 8, max_depth: 1
})
 
✓ PostgreSQL   current decision
✓ MySQL pain   supporting fact
↳ MySQL        superseded alternative

04 — How it works

From conversation to durable context.

Waggle runs quietly behind your agent: observe what matters, preserve it as connected memory, and bring back the right context when a new session begins.

One PostgreSQL decision · carried across sessions

Stage01ObserveDatabase decision

Waggle notices what is worth remembering.

What this means

The agent does the remembering in the background; the source conversation remains available as evidence.

Captures: decisions · preferences · constraints · corrections · outcomes
Scopes: project · agent_id · session_id

observe_conversation({
  project: "waggle-mcp",
  user_message: "Use PostgreSQL; MySQL replication hurt.",
  assistant_response: "PostgreSQL decision recorded."
})
 
✓ verbatim_stored    true
✓ nodes_extracted    2  decision · fact
✓ edges_inferred     1  derived_from

05 — Product demo

See Waggle carry context across sessions.

Watch an agent observe durable decisions, preserve them as a typed graph, and recall exactly what matters in the next conversation.

observe_conversation({

project: "waggle-mcp",

user_message: "Use PostgreSQL; MySQL replication hurt.",

assistant_response: "PostgreSQL decision recorded."

})

✓ verbatim_stored true

✓ nodes_extracted 2 decision · fact

✓ edges_inferred 1 derived_from

~/.waggle/waggle.db

decision Use PostgreSQL

fact MySQL replication was painful

edge decision --derived_from--> fact

history new decision --updates--> prior decision

status current / superseded via valid_to

prime_context({ project: "waggle-mcp" })

query_graph({

query: "What database did we choose, and why?",

retrieval_mode: "hybrid",

max_nodes: 8, max_depth: 1

})

✓ PostgreSQL current decision

✓ MySQL pain supporting fact

↳ MySQL superseded alternative

observe_conversation({

project: "waggle-mcp",

user_message: "Use PostgreSQL; MySQL replication hurt.",

assistant_response: "PostgreSQL decision recorded."

})

✓ verbatim_stored true

✓ nodes_extracted 2 decision · fact

✓ edges_inferred 1 derived_from