Skip to main content

​
watercooler_search

Search the baseline JSONL knowledge graph for threads, entries, entities, and episodes. This is the T1 (Tier 1) baseline memory tier.
Safety: Read-only tool - does not modify any state

​
Overview

The baseline graph (T1) is a lightweight JSONL-based knowledge graph that indexes:
  • Threads: Thread metadata and summaries
  • Entries: Individual thread entries with summaries
  • Entities: Extracted named entities (files, concepts, agents)
  • Episodes: Episodic memory chunks (if memory backend enabled)
T1 provides:
  • Fast keyword search with regex patterns
  • Semantic search via embeddings (if enabled)
  • No LLM costs for basic queries
  • Instant availability - no backend setup required

​
Parameters

​
query
string
required
Search query (keyword or natural language)Examples:
  • "authentication error"
  • "What did we decide about JWT tokens?"
  • "file:src/auth/jwt.py"
​
mode
string
default:"auto"
Search modeOptions:
  • "auto" - Auto-detect (semantic if query is question, else keyword)
  • "keyword" - Regex-based keyword search
  • "semantic" - Embedding-based similarity search
  • "entities" - Search entity nodes only
  • "episodes" - Search episodic memory only
​
limit
integer
default:"10"
Maximum results to return
​
code_path
string
default:""
Path to code repository directoryResolves threads directory location
​
threads_dir
string
default:""
Explicit threads directory path (overrides code_path resolution)
​
group_ids
list[string]
default:"null"
Optional list of project group IDs to filter resultsIn unified model, all threads share one group_id per project (e.g., “watercooler_cloud”)

​
Return Value

Returns JSON with search results:
​
query
string
Original search query
​
mode
string
Search mode used (keyword/semantic/entities/episodes)
​
result_count
integer
Number of results found
​
results
array
List of matching nodes, each containing:
  • id: Node UUID
  • name: Node name/title
  • labels: Node types (Thread, Entry, Entity, Episode)
  • content: Node content/summary
  • score: Relevance score (0-1)
  • metadata: Additional properties (timestamp, agent, topic, etc.)

​
Usage Examples

await use_mcp_tool(
    "watercooler_search",
    query="authentication error",
    mode="keyword",
    code_path="."
)

​
Semantic Search (Natural Language)

await use_mcp_tool(
    "watercooler_search",
    query="What did we decide about JWT token signing?",
    mode="semantic",
    limit=5,
    code_path="."
)

​
Search Entities

await use_mcp_tool(
    "watercooler_search",
    query="src/auth/jwt.py",
    mode="entities",
    code_path="."
)

​
Search Episodes

await use_mcp_tool(
    "watercooler_search",
    query="OAuth2 implementation",
    mode="episodes",
    code_path="."
)

​
Auto Mode

# Question -> semantic search
await use_mcp_tool(
    "watercooler_search",
    query="Why did we choose RS256?",
    mode="auto",
    code_path="."
)

# Keywords -> keyword search  
await use_mcp_tool(
    "watercooler_search",
    query="jwt token refresh",
    mode="auto",
    code_path="."
)

​
Example Output

{
  "query": "JWT token signing",
  "mode": "semantic",
  "result_count": 3,
  "results": [
    {
      "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "name": "Decision: Use RS256 for JWT signing",
      "labels": ["Entry", "Decision"],
      "content": "Decided to use RS256 (RSA with SHA-256) for JWT signing due to wide library support and asymmetric key benefits.",
      "score": 0.92,
      "metadata": {
        "topic": "feature-auth",
        "timestamp": "2025-01-15T10:30:00Z",
        "agent": "Claude",
        "entry_type": "Decision"
      }
    },
    {
      "id": "01ARZ3NDEKTSV4RRFFQ69G5FAW",
      "name": "JWT token generation implemented",
      "labels": ["Entry", "Note"],
      "content": "Implemented RS256 key pair generation and token signing in src/auth/jwt.py",
      "score": 0.87,
      "metadata": {
        "topic": "feature-auth",
        "timestamp": "2025-01-15T11:00:00Z",
        "agent": "Cursor",
        "entry_type": "Note"
      }
    }
  ]
}

​
Search Patterns

​
Find File References

await use_mcp_tool(
    "watercooler_search",
    query="file:src/auth/",
    mode="keyword",
    code_path="."
)

​
Find Decisions

await use_mcp_tool(
    "watercooler_search",
    query="Decision:",
    mode="keyword",
    code_path="."
)

​
Find Agent Contributions

await use_mcp_tool(
    "watercooler_search",
    query="agent:Claude",
    mode="keyword",
    code_path="."
)

​
Semantic Questions

await use_mcp_tool(
    "watercooler_search",
    query="What authentication method did we implement?",
    mode="semantic",
    code_path="."
)

​
When to Use T1 vs T2/T3

Use T1 (watercooler_search):
  • Simple keyword lookups
  • File/entity searches
  • Fast retrieval, no LLM costs
  • Sufficient for most queries
Use T2 (watercooler_smart_query with force_tier=“T2”):
  • Complex temporal queries (“what changed after X?”)
  • Relationship queries (“who worked on Y?”)
  • More sophisticated semantic search
Use T3 (watercooler_smart_query with force_tier=“T3”):
  • Multi-hop reasoning
  • Hierarchical summarization
  • Expensive but most comprehensive

​
Graph Structure

The baseline graph stores nodes in .graph/nodes.jsonl: 
{"uuid":"...","labels":["Thread"],"name":"feature-auth","summary":"..."}
{"uuid":"...","labels":["Entry"],"name":"Initial proposal","content":"..."}
{"uuid":"...","labels":["Entity","File"],"name":"src/auth/jwt.py"}
Embeddings (if enabled) stored in .graph/embeddings.npy.

Build docs developers (and LLMs) love

Get started for freeTalk to us