Skip to main content

​
watercooler_find_similar

Find semantically similar entries using the Graphiti temporal knowledge graph (T2). Uses embedding-based similarity search to find related discussions.
Safety: Read-only tool - does not modify any state

​
Overview

This tool searches the Graphiti backend (T2) to find entries semantically similar to a query. Unlike keyword search, it understands meaning and context. Use cases:
  • Find related discussions across threads
  • Discover prior art for current work
  • Locate relevant decisions and rationale
  • Identify duplicate or overlapping work

​
Prerequisites

  1. Graphiti backend enabled: WATERCOOLER_GRAPHITI_ENABLED=1
  2. FalkorDB running: docker run -d -p 6379:6379 falkordb/falkordb
  3. Threads indexed: watercooler memory index
  4. API keys configured: LLM_API_KEY, EMBEDDING_API_KEY

​
Parameters

​
query
string
required
Search query or example textExamples:
  • "JWT token signing with RS256"
  • "error handling in authentication"
  • "async task queue implementation"
​
limit
integer
default:"10"
Maximum results to return
​
code_path
string
default:""
Path to code repository directoryResolves threads directory and database name
​
group_id
string
default:"null"
Optional project group_id to filter resultsIn unified model, all threads share one group_id per project (e.g., “watercooler_cloud”)

​
Return Value

Returns JSON with similar entries:
​
query
string
Original search query
​
result_count
integer
Number of similar entries found
​
results
array
List of similar entries, each containing:
  • episode_uuid: Graphiti episode UUID
  • content: Entry content/summary
  • score: Similarity score (0-1)
  • timestamp: Entry timestamp
  • source_description: Source metadata (topic, agent)
  • provenance: Entry provenance (entry_id, topic)

​
Usage Examples

​
Find Similar Discussions

await use_mcp_tool(
    "watercooler_find_similar",
    query="JWT token signing with RS256",
    limit=5,
    code_path="."
)

await use_mcp_tool(
    "watercooler_find_similar",
    query="Why did we choose this authentication method?",
    limit=10,
    code_path="."
)

​
Find Prior Art

await use_mcp_tool(
    "watercooler_find_similar",
    query="async task queue with retry logic",
    code_path="."
)

​
Search Specific Project

await use_mcp_tool(
    "watercooler_find_similar",
    query="memory backend integration",
    group_id="watercooler_cloud",
    code_path="."
)

​
Example Output

{
  "query": "JWT token signing with RS256",
  "result_count": 3,
  "results": [
    {
      "episode_uuid": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "content": "Decided to use RS256 (RSA with SHA-256) for JWT signing due to wide library support and asymmetric key benefits.",
      "score": 0.94,
      "timestamp": "2025-01-15T10:30:00Z",
      "source_description": "thread:feature-auth | Agent: Claude",
      "provenance": {
        "entry_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "topic": "feature-auth"
      }
    },
    {
      "episode_uuid": "01ARZ3NDEKTSV4RRFFQ69G5FAW",
      "content": "Implemented RS256 key pair generation and token signing in src/auth/jwt.py",
      "score": 0.89,
      "timestamp": "2025-01-15T11:00:00Z",
      "source_description": "thread:feature-auth | Agent: Cursor",
      "provenance": {
        "entry_id": "01ARZ3NDEKTSV4RRFFQ69G5FAW",
        "topic": "feature-auth"
      }
    },
    {
      "episode_uuid": "01ARZ3NDEKTSV4RRFFQ69G5FAX",
      "content": "Added token refresh endpoint with RS256 verification",
      "score": 0.85,
      "timestamp": "2025-01-15T11:30:00Z",
      "source_description": "thread:feature-auth | Agent: Claude",
      "provenance": {
        "entry_id": "01ARZ3NDEKTSV4RRFFQ69G5FAX",
        "topic": "feature-auth"
      }
    }
  ]
}

​
How It Works

​
Embedding Generation

When threads are indexed to Graphiti (T2):
  1. Entry chunking: Each entry is split into semantic chunks
  2. Embedding generation: Chunks are embedded using configured embedding model
  3. Graph storage: Embeddings stored in FalkorDB alongside episode nodes
When you query:
  1. Query embedding: Your query is embedded with same model
  2. Vector search: FalkorDB finds nearest neighbors in embedding space
  3. Ranking: Results sorted by cosine similarity
  4. Provenance: Episode UUIDs linked back to entry_id/topic

​
Similarity Scores

Score interpretation:
  • 0.9 - 1.0: Near-duplicate or highly related
  • 0.8 - 0.9: Strongly related, same topic
  • 0.7 - 0.8: Related, overlapping concepts
  • 0.6 - 0.7: Loosely related
  • < 0.6: Weak relationship

​
Use Cases

​
Avoid Duplicate Work

Before starting new work: 
# Check if someone already implemented this
await use_mcp_tool(
    "watercooler_find_similar",
    query="OAuth2 token refresh endpoint",
    code_path="."
)

​
Find Architectural Decisions

When making similar decision: 
# See what we decided before
await use_mcp_tool(
    "watercooler_find_similar",
    query="database backend selection criteria",
    code_path="."
)

​
Discover Context

When joining ongoing work: 
# Find related discussions
await use_mcp_tool(
    "watercooler_find_similar",
    query="memory backend integration challenges",
    code_path="."
)
Find related work across threads: 
# Find all error handling discussions
await use_mcp_tool(
    "watercooler_find_similar",
    query="error handling patterns and best practices",
    limit=20,
    code_path="."
)

​
Performance Tips

​
Adjust Limit

For exploration, request more results: 
await use_mcp_tool(
    "watercooler_find_similar",
    query="async patterns",
    limit=20  # Get more context
)

​
Use Specific Queries

More specific queries yield better results: 
# ❌ Too vague
query="authentication"

# ✅ Specific
query="JWT token signing with RS256 algorithm"

​
Filter by Project

For multi-project repos: 
await use_mcp_tool(
    "watercooler_find_similar",
    query="auth implementation",
    group_id="watercooler_cloud"  # Focus on one project
)

​
Troubleshooting

​
No Results

Cause: Threads not indexed to Graphiti Solution: 
watercooler memory index

​
Low-Quality Results

Cause: Embedding model mismatch or poor query Solution:
  • Use same embedding model for indexing and search
  • Make query more specific
  • Increase limit to see more results

​
Backend Unavailable

Cause: Graphiti not enabled or FalkorDB not running Solution: 
# Enable Graphiti
export WATERCOOLER_GRAPHITI_ENABLED=1

# Start FalkorDB
docker run -d -p 6379:6379 falkordb/falkordb

Build docs developers (and LLMs) love

Get started for freeTalk to us