Retrieving Code Context

Synapses offers several tools for finding and retrieving code. Each is designed for a different situation. This guide helps you pick the right one.

Decision Tree

What do you need?
│
├─ "I know the entity name" → search(mode="exact")
│
├─ "I need to understand an area of code" → get_context
│
├─ "I need to search for patterns or text" → search
│
└─ "I need full context for a specific task" → get_context(mode="intent")

search(mode=“exact”)

Use when you know the exact (or approximate) name of a function, struct, interface, or file.

{
  "tool": "search",
  "arguments": {
    "query": "HandleWebhook",
    "mode": "exact",
    "kind": "function"
  }
}

Returns matching nodes with their metadata: file path, line range, package, visibility. Fast and precise.

When to use:

• You have a function/type name from an error message or stack trace
• You want to jump to a known symbol
• You need the file location of a specific entity

Filtering by kind:

// Only functions
{ "tool": "search", "arguments": { "query": "Parse", "mode": "exact", "kind": "function" } }

// Only structs/types
{ "tool": "search", "arguments": { "query": "Config", "mode": "exact", "kind": "struct" } }

// Only interfaces
{ "tool": "search", "arguments": { "query": "Store", "mode": "exact", "kind": "interface" } }

get_context

Use when you need to understand an area of code — not just a single entity but its relationships, callers, callees, and related types.

{
  "tool": "get_context",
  "arguments": {
    "query": "authentication middleware",
    "intent": "modify"
  }
}

Returns a BFS ego-graph slice centered on the most relevant nodes. The intent parameter adjusts which edges and relationships are prioritized.

Available intents:

With a file path:

{
  "tool": "get_context",
  "arguments": {
    "file": "internal/auth/middleware.go",
    "intent": "debug"
  }
}

When you pass file, Synapses returns context anchored to that specific file rather than doing a semantic search.

search

Use for text pattern matching, grep-style queries, or when you need to find all occurrences of something.

{
  "tool": "search",
  "arguments": {
    "query": "context.WithTimeout",
    "kind": "call"
  }
}

Returns matching entities with location info. Supports kind filtering (function, struct, interface, file, call).

When to use:

• You need to find all usages of an API
• You are searching for a string pattern across the codebase
• You want a list of results, not a context graph

get_context(mode=“intent”)

The canonical context tool for task execution. Combines semantic search, intent-based edge weighting, and graph traversal into a single optimized call.

{
  "tool": "get_context",
  "arguments": {
    "mode": "intent",
    "task": "Refactor the webhook handler to use a connection pool",
    "intent": "modify",
    "files": ["internal/webhook/handler.go"]
  }
}

Returns a context packet: the most relevant code, relationships, architectural rules, and related episodes — everything needed to execute the task.

When to use:

• You have a well-defined task to perform
• You want the most complete context in one call
• You want Synapses to figure out what is relevant

See the Intent-Based Context guide for a deep dive.

Combining Tools

Tools compose naturally. A common pattern:

1. search("validateToken") → find all validation functions
2. get_context(file="internal/auth/validate.go", intent="modify") → understand the area
3. get_context(mode="intent", task="Add rate limiting to token validation", intent="modify") → get full task context

Scaling Considerations

For large projects (500+ files), prefer get_context(mode="intent") and get_context over search. The graph-based tools prune irrelevant results automatically, while search may return too many matches.

For small projects (under 50 files), any tool works well. search(mode="exact") and search are the fastest options.