Runtime Model

Runtime Model

Use this page for

understanding startup, daemon mode, snapshots, sidecar state, local stores, analytics, and environment variables.

Startup

At startup, SymForge:

1. discovers a project root unless auto-indexing is disabled;
2. decides whether to use a local in-process index or a shared daemon session;
3. loads a snapshot when one is valid;
4. indexes the workspace when a fresh index is needed;
5. starts the watcher and serves MCP tools over stdio.

If no project root is found, SymForge can still start, but health will show an empty or unavailable project state and the recovery path is usually index_folder(path).

Local In-Process Mode

Local mode keeps the active LiveIndex inside the MCP server process. This is the simplest and most deterministic path. It is the right mental model for most single-client sessions.

Daemon Mode

Run:

symforge daemon

Daemon mode lets multiple local sessions share project/session state. Clients can fall back to local in-process mode if daemon routing is unavailable.

Set SYMFORGE_NO_DAEMON=1 when you want to force local mode.

Snapshots

Index snapshots persist at:

.symforge/index.bin

Snapshots are a startup accelerator, not the final authority. Current workspace bytes, file watcher events, analyze_file_impact, and index_folder keep the runtime honest.

Watcher And Reconciliation

The watcher keeps the index current as files change. Reconciliation handles drift, missed events, and repair sweeps. health reports watcher state, reconcile repairs, overflows, and stale-mutation rejections.

Sidecar State

Sidecar metadata is stored under .symforge/ and may include:

• .symforge/sidecar.port
• .symforge/sidecar.pid
• .symforge/sidecar.session

health reports sidecar PID, port, and liveness state when available. Missing or dead sidecar state should be visible, not silently hidden.

Local Stores

Path	Purpose
.symforge/index.bin	Warm-start index snapshot
.symforge/frecency.db	Optional persistent frecency ranking signal
.symforge/coupling.db	Optional co-change coupling store
.symforge/analytics.db	Optional local analytics records
.symforge/sidecar.*	Sidecar PID/port/session metadata

Analytics

Analytics are local, optional, bounded, and redacted. When enabled, tool-call metadata is queued to a background writer instead of written synchronously on the handler hot path.

CLI:

symforge analytics status
symforge analytics summary
symforge analytics export
symforge analytics reset

Disabled analytics should not create an analytics database.

Result And Capability State

Modern tool responses report stable outcome classes where the transport can carry metadata. Health and ranking responses also report optional capability state such as ready, preparing, unavailable, disabled-by-policy, stale, and fallback-used.

This matters because "no result", "invalid request", "ambiguous selector", and "internal failure" require different agent behavior.

Environment Variables

Variable	Effect
SYMFORGE_HOME	Home directory for installed binary and daemon metadata
SYMFORGE_AUTO_INDEX	Enables startup project discovery and indexing
SYMFORGE_NO_DAEMON	Forces local in-process mode
SYMFORGE_SIDECAR_BIND	Bind host for local sidecar state
SYMFORGE_DAEMON_BIND	Bind host for daemon state
SYMFORGE_RECONCILE_INTERVAL	Watcher reconciliation interval in seconds; 0 disables periodic sweeps
SYMFORGE_CB_THRESHOLD	Parse-failure circuit-breaker threshold
SYMFORGE_FRECENCY	Frecency policy: session default, persistent when truthy, disabled when false/off/disabled
SYMFORGE_COUPLING	Co-change policy: lazy default, warm on startup when truthy, disabled when false/off/disabled
SYMFORGE_DEBUG_RANKING	Ranking diagnostic policy
SYMFORGE_WORKTREE_AWARE	Worktree routing policy for edit calls
SYMFORGE_ANALYTICS_DB_PATH	Override analytics database location
SYMFORGE_FRECENCY_DB_PATH	Override frecency database location
SYMFORGE_COUPLING_DB_PATH	Override co-change database location
SYMFORGE_PROJECT_CONFIG_TRUST_MODE	Trust behavior for project-local SymForge configuration

Recovery Sequence

When SymForge looks wrong in a client:

1. call health;
2. inspect index/runtime/sidecar state;
3. call index_folder(path) if the workspace is empty, stale, or wrong;
4. call validate_file_syntax for malformed files;
5. call analyze_file_impact after targeted file edits;
6. retry the original query.