Token-Budget Extraction

AI agents have limited context windows. Dumping entire files into a prompt wastes tokens on imports, boilerplate, and irrelevant code — leaving less room for the symbols that actually matter to the task. NestWeaver solves this by letting callers specify a token budget, then filling that budget with the highest-ranked, most task-relevant code from the graph.

How token budgets work

brain_context defaults token_budget to 2000. project_context defaults to a concise orientation of about 1000 tokens; response_format: "detailed" is about 3000. nestweaver context has no default budget until you pass --token-budget. NestWeaver ranks results and fills the budget from the top of that list.

# Get context for a symbol within 2000 tokens
nestweaver context "UserService" --token-budget 2000

# Code context around a symbol. A question belongs on `nestweaver investigate`.
nestweaver context processPayment --token-budget 2000

The budget controls the output size, not the computation. NestWeaver still ranks the entire relevant subgraph — it just truncates the response to fit your window.

Three retrieval signals

Ranking is not based on a single metric. NestWeaver fuses three independent retrieval signals via convex combination to produce a final relevance score for each symbol:

Signal	Default weight	What it captures
Personalized PageRank	0.40	Structural importance relative to the query seeds — follows call chains, imports, and type relationships through the graph
BM25	0.25	Text match — keyword relevance using the Tantivy full-text index with pseudo-relevance feedback expansion
Semantic similarity	0.35	Embedding-based similarity — natural language queries matched against symbol and note embeddings (local BERT model, Metal-accelerated on Apple Silicon)

The three signals in a context score

Personalized PageRank 0.40

Structure around the seed.

Semantic similarity 0.35

Only after embeddings exist.

BM25 0.25

Text match in the search index.

Semantic similarity is omitted until embeddings exist. The token budget then keeps the top of this ranking and drops the rest.

The combined score for each symbol is:

score = 0.40 * ppr + 0.25 * bm25 + 0.35 * semantic

Weights are configurable in your instance.toml:

[embedding]
weight_ppr = 0.40
weight_bm25 = 0.25
weight_semantic = 0.35

Token efficiency

nestweaver context and brain_context resolve names, tags, titles, and UIDs. A question such as “how does authentication work” belongs on nestweaver investigate. File paths belong on nestweaver context / code_context, not on brain_context.

Response formats

NestWeaver supports two response formats that trade detail for token efficiency:

• "detailed" (default) — includes full symbol bodies, file paths, line numbers, edge lists, and metadata
• "concise" — strips bodies to signatures and key lines, omits verbose metadata, typically ~60% fewer tokens than detailed

# Concise project orientation
nestweaver project-context payments

# Detailed project orientation
nestweaver project-context payments --detailed

When using NestWeaver via MCP tools, set response_format: "concise" in the tool arguments. The concise format is strongly recommended for subagent and batch queries where token cost matters.

Filtering

On brain_context, repos and vaults filter after the PageRank walk. A tags filter drops symbol nodes, because symbols carry no tags. These flags are on nestweaver brain context, not nestweaver context.

Filter	Effect
repos	Restrict to symbols from specific repositories
tags	Include only symbols/notes with matching tags (e.g., project/payments)
exclude_tags	Remove symbols/notes with specific tags
path_prefix	Restrict to files under a directory (e.g., src/api/)
kinds	Filter by symbol kind (e.g., function, class, interface)

nestweaver brain context checkout --repos payments-api --path-prefix src/api/

Filters are combinative — specifying multiple filters intersects them. This lets you efficiently target the exact subset of the graph relevant to your task.

Example

A typical context query for an agent working on a payment processing feature:

nestweaver context UserService --token-budget 2000

Representative output:

UserService (class) — src/services/user-service.ts:15
  Relevance: 0.92 | PPR: 0.88 | BM25: 0.95 | Semantic: 0.94

  class UserService {
    constructor(private db: DatabasePool, private cache: RedisClient)
    async getUser(id: string): Promise<User>
    async updateProfile(id: string, data: ProfileUpdate): Promise<User>
    async deleteUser(id: string): Promise<void>
  }

  Called by: PaymentController.processPayment, AuthMiddleware.validateSession
  Calls: DatabasePool.query, RedisClient.get, RedisClient.set
  Imported by: payment-controller.ts, auth-middleware.ts, user-router.ts

UserRepository (class) — src/repositories/user-repository.ts:8
  Relevance: 0.71 | PPR: 0.65 | BM25: 0.70 | Semantic: 0.78

  class UserRepository {
    async findById(id: string): Promise<User | null>
    async update(id: string, data: Partial<User>): Promise<User>
  }

(2 symbols, ~480 tokens)

The output fits within the 2000-token budget and contains only the symbols most relevant to UserService — ranked by a combination of graph proximity, text match, and semantic similarity.