Operator guide
Managing the on-disk semantic index, resetting it, recovering from corruption, and the environment variables that affect Fuse.
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:
| Context | Path |
|---|---|
| Inside a git repo | {repoRoot}/.fuse/fuse.db at the repository root, so every call scoped anywhere in the repo shares one warm index |
| Outside a git repo | ~/.fuse/fuse.db (override the directory with FUSE_USER_DATA) |
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
| Action | Effect |
|---|---|
fuse index --force | Rebuilds the index from scratch for the workspace |
Delete the store file ({repoRoot}/.fuse/fuse.db or ~/.fuse/fuse.db) | Full reset; the next read tool rebuilds it |
The index is entirely derived data: deleting it loses nothing that cannot be rebuilt from the source.
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 pre-V3 cache), 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 first V3 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
| Variable | Effect |
|---|---|
FUSE_USER_DATA | Directory for machine-wide Fuse data when the workspace is outside a git repository (default ~/.fuse). The store file is {FUSE_USER_DATA}/fuse.db. Inside a git repo the store stays at {repoRoot}/.fuse/fuse.db regardless of this variable. |
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.