Guide

How Indexing Works

Semfora uses sharded indexing to handle codebases of any size. Index once, query instantly with cached semantic data.

Overview

The indexing process analyzes your codebase and creates a queryable cache containing:

Repository overview - Framework detection, module structure, entry points
Module shards - Symbols grouped by directory/module
Symbol details - Full semantic data for each function, class, etc.
Call graph - Function call relationships across the codebase

Basic Indexing

Create a semantic index for your project:

semfora-engine index generate

Or use the MCP tool:

// In your AI assistant
index({
  path: "/path/to/project"
})

Index Location

By default, the index is stored in a cache directory:

# Linux/macOS
~/.cache/semfora-engine/<project-hash>/

# Windows
%LOCALAPPDATA%\semfora-engine\<project-hash>\

The project hash is derived from the absolute path, ensuring each project has its own cache.

Incremental Updates

Semfora automatically detects file changes and only re-indexes what's needed. This makes updates 3.5x to 25x faster than full rebuilds.

# Check index freshness
semfora-engine index check

# Auto-refresh if stale (MCP tool)
index({
  path: ".",
  force: false  // smart refresh - only if stale
})

Git-Aware Updates

When you switch branches, Semfora detects the change and refreshes affected files automatically.

Sharding Strategy

Module Shards

Symbols are grouped by their containing directory/module. This allows efficient querying without loading the entire index.

Symbol Shards

Individual symbols can be fetched by hash without loading module data. Ideal for targeted lookups.

Call Graph Shard

Function relationships stored separately for efficient call graph queries and impact analysis.

Overview Shard

Lightweight summary of the entire repository. Loads instantly for quick context.

Performance Tips

For Large Monorepos

Semfora automatically uses parallel processing for initial indexing.

semfora-engine index generate --progress

Exclude Test Files

The overview excludes test directories by default for token efficiency:

get_overview({
  exclude_test_dirs: true,  // default
  max_modules: 30           // limit for token efficiency
})

Filter by Extension

Index only specific file types to reduce size:

index({
  path: ".",
  extensions: ["ts", "tsx", "js", "jsx"]
})

Troubleshooting

Index appears stale

Run semfora-engine index check or use the index MCP tool to automatically regenerate if the index is outdated.

Missing symbols

Ensure the file extension is supported. Check get_languages for supported extensions. Force regeneration with force: true.

Slow initial indexing

Use --progress to see indexing status. Consider excluding generated files, node_modules, and vendored dependencies.