​

watercooler_memory_sync

​

Overview

• T2 (Graphiti): Temporal knowledge graph with entities and relationships
• T3 (LeanRAG): Hierarchical clustering with multi-hop reasoning

• Semantic search across all threads
• Entity and relationship queries
• Temporal “what changed when?” queries
• Multi-hop “why did we X given Y?” reasoning

​

Automatic vs Manual Sync

​

Automatic Sync

• After every say/ack/handoff: Entry is queued for indexing
• Fire-and-forget: Indexing happens in background, doesn’t block tools
• Retry logic: Failed indexing is retried automatically

​

Manual Sync

• Bulk index: Index many threads at once
• Force refresh: Re-index threads with updated config
• Recovery: Index threads that failed automatic sync

​

Parameters

​

Return Value

​

Usage Examples

​

Sync All Threads

await use_mcp_tool(
    "watercooler_memory_sync",
    code_path="."
)

​

Sync Specific Threads

await use_mcp_tool(
    "watercooler_memory_sync",
    topics=["feature-auth", "bug-fix-123"],
    code_path="."
)

​

Force Re-Index

await use_mcp_tool(
    "watercooler_memory_sync",
    topics=["feature-auth"],
    force=True,
    code_path="."
)

​

Sync to Specific Backend

# Graphiti only (T2)
await use_mcp_tool(
    "watercooler_memory_sync",
    backend="graphiti",
    code_path="."
)

# LeanRAG only (T3)
await use_mcp_tool(
    "watercooler_memory_sync",
    backend="leanrag",
    code_path="."
)

​

Example Output

​

Queued Execution

{
  "success": true,
  "queued": true,
  "task_ids": [
    "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "01ARZ3NDEKTSV4RRFFQ69G5FAW"
  ],
  "message": "Queued 2 threads for async indexing. Poll with watercooler_memory_task_status."
}

​

Direct Execution

{
  "success": true,
  "queued": false,
  "indexed_count": 15,
  "execution_time_ms": 8450,
  "message": "Indexed 15 entries across 2 threads"
}

​

Sync Process

​

T2 (Graphiti) Indexing

1. Entry chunking: Split entries into semantic chunks
2. Entity extraction: LLM extracts entities and relationships
3. Embedding generation: Chunks embedded with configured model
4. Graph storage: Nodes and edges written to FalkorDB
5. Provenance tracking: Entry-to-episode mapping stored

​

T3 (LeanRAG) Indexing

1. Episode extraction: Load episodes from Graphiti (T2)
2. Clustering: Hierarchical clustering by semantic similarity
3. Summarization: LLM generates cluster summaries
4. Graph storage: Cluster hierarchy written to FalkorDB
5. Incremental update: Only new episodes processed (if enabled)

​

Queue vs Direct Execution

​

Queued Execution (Default)

• Tasks are queued for background processing
• Tool returns immediately
• Progress tracked via watercooler_memory_task_status
• Retry logic handles failures

​

Direct Execution (Fallback)

• Indexing runs synchronously
• Tool blocks until complete
• Useful for debugging
• May timeout on large threads (>50 entries)

​

Monitoring Progress

# Get task status
await use_mcp_tool(
    "watercooler_memory_task_status",
    task_id="01ARZ3NDEKTSV4RRFFQ69G5FAV"
)

# Get queue health
await use_mcp_tool(
    "watercooler_memory_task_status",
    action="health"
)

​

Prerequisites

​

T2 (Graphiti)

# Enable Graphiti
export WATERCOOLER_GRAPHITI_ENABLED=1

# Configure API keys
export LLM_API_KEY="sk-..."
export EMBEDDING_API_KEY="sk-..."

# Start FalkorDB
docker run -d -p 6379:6379 -p 3000:3000 \
  --name falkordb \
  -v falkordb_data:/var/lib/falkordb/data \
  falkordb/falkordb:latest

​

T3 (LeanRAG)

# Enable LeanRAG
export WATERCOOLER_LEANRAG_ENABLED=1
export LEANRAG_PATH="/path/to/leanrag"

# Same FalkorDB and API keys as T2

​

Best Practices

​

Initial Setup

1. Enable backends: Set environment variables
2. Start services: Launch FalkorDB
3. Bulk index: Sync all existing threads

# Index everything
await use_mcp_tool(
    "watercooler_memory_sync",
    code_path="."
)

​

Ongoing Use

​

Recovery

# Check failed tasks
await use_mcp_tool(
    "watercooler_memory_task_status",
    action="recover"
)

# Re-sync specific threads
await use_mcp_tool(
    "watercooler_memory_sync",
    topics=["failed-thread-1", "failed-thread-2"],
    force=True,
    code_path="."
)

​

Config Changes

# Force re-index with new config
await use_mcp_tool(
    "watercooler_memory_sync",
    force=True,
    code_path="."
)

​

Troubleshooting

​

Indexing Fails

# Verify API keys
echo $LLM_API_KEY
echo $EMBEDDING_API_KEY

# Check diagnostics
await use_mcp_tool("watercooler_diagnose_memory")

​

FalkorDB Connection Error

docker ps | grep falkordb
# If not running:
docker start falkordb

​

Timeout on Large Threads

• Ensure queue is enabled (automatic)
• Split large threads into smaller chunks
• Use CLI: watercooler memory index

​

Related Tools

• watercooler_memory_task_status - Monitor indexing progress
• watercooler_smart_query - Query indexed memory
• watercooler_find_similar - Find similar entries
• watercooler_diagnose_memory - Check backend health