Operator guide

This page is for operators running Fuse as an MCP server, a host, or in CI: where the index lives, how to reset it, and which environment variables affect behavior. For the store layout, see Caching internals.

fuse.db lifecycle

All persistent index data for a workspace lives in one SQLite file named fuse.db. Placement depends on whether the workspace is inside a git repository:

The database is created and populated on the first index build. The read commands and MCP read tools build the index on first use; fuse index builds it explicitly. The MCP server and the host keep the store open across calls, so a multi-call task pays the indexing cost once and reads a warm graph afterward.

Resetting the index

The index is entirely derived data: deleting it loses nothing that cannot be rebuilt from the source.

Freshness after an edit

The read tools do not serve an index frozen at first call. When the store is already warm, opening it for a read runs a bounded freshness reconcile: it compares the current on-disk content hash of every known file against the stored hash, re-indexes files that were edited, and removes files that were deleted, before answering. So a symbol added by an edit is found on the next read, and a symbol in a deleted file is gone, with no explicit fuse index call.

The reconcile refreshes a file's own rows (symbols, chunks, full-text, routes); cross-file semantic graph edges (DI, routes, MediatR, EF) are recomputed by a full fuse index, not by the per-file reconcile. A bulk change (a branch switch or a large pull that dirties many files at once) is not reconciled one file at a time: above a storm threshold the reconcile records a stale-as-of stamp (the dirty-file count in the index metadata) instead, so the answer is reported as stale rather than paying a reconcile storm on every read, and running fuse index clears it. New files added on disk since the last full index are picked up by fuse index, not by the reconcile, which only tracks files it already knows.

Version control

Add .fuse/ to your repository .gitignore. The directory holds derived index data (like bin/ or obj/): it can grow, varies by machine, and is rebuilt on the next run. The Fuse repository ignores .fuse/ itself; your project should too. Running fuse init inside a git repo appends .fuse/ to .gitignore when the entry is missing.

Schema migration and corrupt recovery

The store carries a schema version. When Fuse opens a database older than the current schema (for example a cache from an earlier major version), it drops the Fuse-owned tables and rebuilds at the current version rather than attempting an in-place migration, so an older index is replaced cleanly on the next run.

If SQLite reports a malformed database on open, Fuse recreates an empty database rather than failing, and the next run repopulates it. If corruption persists, check filesystem permissions on .fuse/ and that no other process holds a stale lock on the WAL files (a leaked fuse mcp serve child, for example).

Environment variables

When driving an agent against the Fuse MCP server (for example in the agent evaluation suite), the Claude CLI variables MCP_TOOL_TIMEOUT and MCP_TIMEOUT bound per-tool-call and startup time; these are read by the agent client, not by Fuse.

Session-delta state (sessionId on fuse_context and fuse_review) is held in memory inside the running server only; it is not stored in .fuse/fuse.db and is lost when the process exits.

Next

See Caching internals for the store layout, or Connect your AI for MCP client setup.