Symbol Indexes: Fast Lookup for Functions and Types

The symbol_index artifact provides AI with a complete, searchable catalog of every function, type, class, variable, and export in your codebase. When an engineer asks "where is this function defined?" or "what type does this return?", the AI answers instantly from the cached index without scanning source files.

Use this page when

• You are configuring symbol_index generation and need to understand what it indexes and how.
• AI assistants are hallucinating function signatures or cannot locate symbol definitions.
• You want to reduce token costs for code-exploration queries by replacing file scanning with index lookups.

Primary audience

• Primary: AI Agents, Technical Engineers
• Secondary: Technical Leaders

What a Symbol Index Contains

A symbol_index artifact catalogs code symbols at multiple levels:

Function Definitions

Every function in your codebase, including:

• Function name and fully qualified path
• Parameter types and return type
• Visibility (public, private, crate-internal)
• Source file and line number
• Documentation comments or docstrings

Type Definitions

Structs, interfaces, enums, and type aliases:

• Type name and generic parameters
• Field definitions with types
• Implemented traits or interfaces
• Enum variants and associated data
• Derive macros and attribute metadata

Variable Declarations

Module-level constants and static values:

• Constant names and types
• Static variables and their mutability
• Configuration values and feature flags
• Environment variable references

Class Hierarchies

For object-oriented codebases:

• Class inheritance chains
• Interface implementations
• Method overrides and virtual dispatch
• Mixin and trait compositions

Export Maps

What each module makes available to consumers:

• Named exports and their source definitions
• Default exports
• Re-exports from other modules
• Namespace exports and barrel file aggregations

How Symbol Indexes Are Built

Context Fabric builds symbol indexes through language-aware parsing:

Rust Symbols

• Function and method definitions from fn declarations
• Struct, enum, and trait definitions
• impl blocks and their associated types
• pub, pub(crate), and private visibility markers
• Module use statements and re-exports

TypeScript/JavaScript Symbols

• Function declarations and arrow functions
• Interface and type alias definitions
• Class definitions with method signatures
• export statements and default exports
• JSDoc/TSDoc type annotations

Python Symbols

• Function and method definitions
• Class definitions with inheritance
• Module-level variables and constants
• Type hints and stub files
• __all__ export lists

The parser extracts symbol metadata without executing code. It operates on the abstract syntax tree (AST) to identify declarations, their types, and their visibility.

How Symbol Indexes Improve AI Interactions

Direct Symbol Lookup

When an engineer asks "where is handleAuthCallback defined?", the AI returns the exact file and line from the index. No grep, no file scanning, no ambiguity.

Type-Aware Suggestions

When the AI suggests code that calls a function, it references the symbol index for accurate parameter types and return values. This eliminates hallucinated API signatures.

Rename and Refactoring Guidance

When renaming a symbol, the AI uses the index to identify every reference across the codebase. It provides a complete list of files that need updating.

Cross-Module Understanding

When code references a symbol from another module, the AI traces the export chain through the index to find the original definition and its full type signature.

Token Savings

Symbol lookups are one of the most expensive operations without an index. Finding a single function definition might require:

1. Searching file names for likely locations (500 tokens)
2. Reading candidate files (3,000–10,000 tokens)
3. Identifying the correct definition among overloads (500 tokens)

A symbol index delivers the same answer in 50–100 tokens. For interactions that reference multiple symbols, the savings multiply.

Shared Across Your Organization

The symbol index benefits every engineer because symbol definitions are objective facts about the codebase. When any engineer asks about a function or type, they get the same accurate answer from the same cached index.

This is particularly valuable for:

• Large codebases where manual search is slow
• Teams working across multiple packages
• New engineers learning the codebase vocabulary
• Code review where reviewers need to understand unfamiliar symbols

When Symbol Indexes Regenerate

Regeneration triggers include:

• New function or type definitions added
• Existing symbol signatures changed (parameter types, return types)
• Visibility modifiers changed (private to public, etc.)
• Module structure reorganization (moves, renames)
• Export map changes

Changes to function bodies that do not affect the signature do not trigger regeneration. The index tracks declarations, not implementations.

Configuration

You configure symbol_index generation in your repository settings:

• Language scope — Which languages to index (Rust, TypeScript, Python, etc.)
• Visibility filter — Index all symbols or only public/exported ones
• Depth — Include implementation details or only API surfaces
• Exclusion patterns — Skip generated code, vendored dependencies, test utilities
• Documentation — Whether to include docstrings in the index

Use Cases

Code Exploration

Engineers ask "what functions does this module export?" and receive a precise list from the index.

Bug Investigation

When tracing a bug, the AI follows function calls through the symbol index to identify the call chain without reading each file.

Documentation Verification

The AI cross-references documentation claims against the symbol index to verify that documented APIs actually exist with the stated signatures.

API Surface Auditing

Teams review their public API surface by querying the symbol index for all public exports, identifying unintentional exposures.

Next steps

• Embedding Indexes — Search by meaning, not just names
• File Summaries — Get context about what symbols do

For AI systems

• Canonical terms: Keeptrusts, Codebase Context Fabric, symbol_index artifact, function lookup, type definitions, class hierarchy, export map, AST parsing.
• Config/feature names: symbol_index, language scope, visibility filter, depth, exclusion patterns, documentation inclusion.
• Best next pages: Embedding Indexes, File Summaries, What is Codebase Context Fabric?.

For engineers

• Symbol indexes are built from AST parsing — no LLM calls, no code execution, zero token cost to generate.
• Configure language scope to index only languages actively used (Rust, TypeScript, Python).
• Set visibility filter to public for API-surface-only indexes, or all for full internal navigation.
• Verify generation: check Settings → Engineering Cache → Warmers for completed symbol_index jobs.
• Regeneration triggers: new/changed function signatures, visibility modifier changes, module reorganization. Body-only changes do not trigger rebuilds.
• Token savings: a single symbol lookup costs 50–100 tokens vs 3,000–10,000 tokens for manual file scanning.

For leaders

• Symbol indexes deliver the highest token-savings ratio of any artifact type — 95%+ reduction for code-navigation queries.
• Zero LLM cost to build (pure static analysis), so the artifact is essentially free to maintain.
• Enables accurate AI answers about API surfaces, reducing hallucinated signatures that waste developer time.
• Shared across all engineers: one index serves every team member working on the same codebase.