Store a piece of knowledge as a node in the persistent memory graph. Call this whenever you learn something important from the user: facts, preferences, decisions, entities, concepts, or questions. Prefer atomic facts.

Create a relationship between two stored nodes. Use this immediately after storing related nodes so the memory graph preserves structure, updates, and conflicts.

Manually merge multiple nodes into a single canonical node. All aliases from the merged nodes flow into the canonical node's aliases. All edges pointing to/from merged nodes are re-pointed to the canonical node. Merged nodes are deleted. Idempotent: merging an already-merged node is a no-op. Use this after reviewing dedup_candidates to resolve ambiguous duplicates.

Return pairs of nodes whose embeddings are above a threshold but below the auto-merge threshold. Intended for human review before calling canonicalize_node. Returns pairs sorted by descending similarity so the most likely duplicates appear first.

Retrieve a broad set of nodes bypassing standard semantic limits, optimized for global aggregation and map-reduce tasks. Supports filtering by node_type and tags.

Automatically search the memory graph before answering questions that may depend on prior context, user preferences, project decisions, constraints, or earlier conversation state. Returns a serialized subgraph with matching nodes and their connected neighborhood. Uses hybrid retrieval (transcript + graph) by default for robust fallback. Understands temporal references such as 'recently', 'latest', 'originally', and 'last week'. Benchmark modes: use retrieval_mode='graph' for graph-only (no verbatim fallback), 'verbatim' for transcript-only.

Diagnose memory retrieval ranking for a query. Returns query embedding preview, context-window routing scores, selected windows, flat top nodes, and tiered top nodes for comparison.

Fetch the neighborhood around a specific memory node. Use when you already have a node ID and need its connected context. Returns matching nodes and edges as a serialized subgraph.

Inspect one memory node's evidence, validity window, and connected context. Use when auditing why a memory exists or how it changed. Returns the node, evidence records, related nodes, and edges.

List known agent, project, and session scope values stored in the current tenant graph. Use before filtering memory by scope. Returns arrays of scope identifiers.

List context windows for a project. Use to inspect chat/session-level memory containers, their status, node counts, and update times.

Inspect one context window, including its nodes and links to other context windows. Use when auditing what a conversation/session contributed to memory.

Close a context window, recompute its final graph embedding, refresh node counts, and derive cross-window edges. Use when a chat/session is complete.

Build a chronological view of memory changes for a node, a query result, or the whole tenant. Use when order and evidence matter. Returns timestamped timeline items.

List contradiction and update edges, with unresolved conflicts shown by default. Use to review memory disagreements before resolving them. Returns conflict entries with source and target nodes.

Mark a contradiction or update edge as resolved without deleting the underlying history. Use after deciding how competing memories should be interpreted. Returns the resolved conflict entry. When winner is provided and the edge is CONTRADICTS or UPDATES, the losing node's valid_to is set to now, excluding it from future default queries.

Update an existing memory node's content, label, or tags. Use when a stored memory needs correction without deleting its identity. Returns the updated node.

Delete a node and all connected edges from persistent memory.

Delete all memory data for one session/context window stream, including nodes, transcripts, context windows, and connected edges. Requires confirm=true.

Delete all memory data for one project/repository, including nodes, transcripts, repos, context windows, and connected edges. Requires confirm=true.

Delete all graph memory data for the current tenant. Requires confirm=true. This does not remove API keys or tenant metadata.

Break long or complex content into atomic memory nodes, store them automatically, and create inferred edges. Use for notes, summaries, or multi-fact passages. Returns the stored subgraph.

Automatically observe a completed user-assistant turn. ALWAYS persists the verbatim turn first. Then runs extraction (graph inference) as optional enrichment. If extraction fails, the verbatim turn is still stored. Use after turns containing preferences, decisions, constraints, requirements, corrections, project facts, or meaningful task outcomes. Do not ask the user to trigger this. Returns: turn_id, verbatim_stored (bool), nodes_extracted (count), edges_inferred (count), extraction_errors (non-fatal). Required fields: 'user_message' (the user's text) and 'assistant_response' (the assistant's reply). Do NOT use 'user_text' or 'assistant_text' — those field names are not accepted.

Show what changed in the memory graph recently, including added nodes, updated nodes, created edges, and contradiction edges. Use for review or handoff. Returns a serialized graph diff.

Automatically build a compact context brief at the start of a scoped conversation or before work that needs continuity. Use to hydrate an assistant with the most relevant scoped memories. Returns summary text plus nodes and edges.

Detect topic clusters in the graph using community detection. Use to understand the main themes in memory. Returns labeled clusters with representative nodes and tags. Note: scope filtering (project, agent_id, session_id) is optional and silently ignored — topic detection always runs across the full tenant graph.

Return high-level statistics about the current memory graph. Use for health checks or quick summaries. Returns node and edge counts, node type breakdowns, and recent or highly connected nodes.

Export the current memory graph as an interactive HTML visualization. Use when a human needs to inspect the graph visually. Returns the output path and graph counts.

Export the context-window graph as an interactive HTML visualization. Each node is a chat/session window and edges show overlap, supersession, temporal order, or shared scope.

Snapshot the current memory graph to a portable file (waggle commit). Exports a JSON backup for migration, restore drills, or offline archive. Use commit_format='abhi' (default) for a full .abhi export, or 'backup' for a raw JSON backup. Returns the output path, schema version, and object counts.

Load a memory file into the current graph (waggle pull). Accepts a .abhi file (default) or a raw JSON backup. Runs integrity verification, schema validation, and constraint checks before merging. Returns counts for created and updated nodes and edges.

Compare two .abhi memory files (waggle diff). Reports structural graph changes — added/removed/updated nodes and edges — plus lightweight semantic changes. The output is the screenshot that goes on the homepage.

Three-way merge branching .abhi memory files (waggle merge). Merges left and right branches against a common base into one output file. Conflicts surface as CONTRADICTS edges — nobody else can do this. Use --merge-strategy to control winner selection when both sides changed the same object.

Execute a saved or ad hoc query against an .abhi file (waggle grep). Triggers the file's on_query event actions and returns matching nodes.

Load only selected or query-relevant chunks from an .abhi file for partial graph inspection.

Validate an .abhi memory file without importing it (waggle fsck). Verifies integrity hash, schema compliance, and constraint satisfaction. Like git fsck — run this before trusting a file you received.

Inspect an .abhi memory file without loading it into the graph (waggle show). Returns summary stats, node/edge type breakdowns, and metadata counts. Like git show — quick read-only inspection of a commit object.

Export the current graph as an Obsidian-compatible Markdown vault. Use when a human wants browsable note files with graph links. Returns written files and graph counts.

Import an Obsidian-compatible Markdown vault into the current graph non-destructively. Use to sync edited vault notes back into memory. Returns created, updated, deleted-edge, and conflict counts.

Audit the quality of relationship edges in the memory graph. Returns counts per edge type, average edge_confidence per type, and the top-10 highest- and lowest-confidence edges for each type. Useful for diagnosing graph health and identifying noisy RELATES_TO edges.

Recursively retrieves and compresses relevant Waggle memory for the current task, using graph, hybrid, transcript, update, and conflict-aware retrieval. Decomposes the query into targeted subqueries, expands the graph around key nodes, resolves contradictions and superseded memories, and returns a compact context pack under a configurable token budget. Aliases: recursive_context, assemble_context, rlm_context.