Environment Setup Scripts

Environment Setup Scripts

Platform-specific snippets for setting SymForge environment variables. See the README environment section and Runtime-Model for the current variable reference.

When to use these

Most users do not need to set anything. Use these only when you want explicit defaults in a shell profile, need to pin local-vs-daemon behavior, or want to enable optional persistent stores.

Recommended Baseline

The baseline keeps normal auto-indexing, default local bind hosts, session frecency, lazy co-change preparation, and no forced ranking diagnostics.

PowerShell

Current terminal:

$env:SYMFORGE_HOME = "$HOME\.symforge"
$env:SYMFORGE_AUTO_INDEX = "true"
$env:SYMFORGE_RECONCILE_INTERVAL = "30"
$env:SYMFORGE_SIDECAR_BIND = "127.0.0.1"
$env:SYMFORGE_DAEMON_BIND = "127.0.0.1"
Remove-Item Env:SYMFORGE_NO_DAEMON -ErrorAction SilentlyContinue
Remove-Item Env:SYMFORGE_DEBUG_RANKING -ErrorAction SilentlyContinue

Persist for the current Windows user:

[Environment]::SetEnvironmentVariable("SYMFORGE_HOME", "$HOME\.symforge", "User")
[Environment]::SetEnvironmentVariable("SYMFORGE_AUTO_INDEX", "true", "User")
[Environment]::SetEnvironmentVariable("SYMFORGE_RECONCILE_INTERVAL", "30", "User")
[Environment]::SetEnvironmentVariable("SYMFORGE_SIDECAR_BIND", "127.0.0.1", "User")
[Environment]::SetEnvironmentVariable("SYMFORGE_DAEMON_BIND", "127.0.0.1", "User")
[Environment]::SetEnvironmentVariable("SYMFORGE_NO_DAEMON", $null, "User")
[Environment]::SetEnvironmentVariable("SYMFORGE_DEBUG_RANKING", $null, "User")

CMD

Current terminal:

set SYMFORGE_HOME=%USERPROFILE%\.symforge
set SYMFORGE_AUTO_INDEX=true
set SYMFORGE_RECONCILE_INTERVAL=30
set SYMFORGE_SIDECAR_BIND=127.0.0.1
set SYMFORGE_DAEMON_BIND=127.0.0.1
set SYMFORGE_NO_DAEMON=
set SYMFORGE_DEBUG_RANKING=

Persist for the current Windows user:

setx SYMFORGE_HOME "%USERPROFILE%\.symforge"
setx SYMFORGE_AUTO_INDEX "true"
setx SYMFORGE_RECONCILE_INTERVAL "30"
setx SYMFORGE_SIDECAR_BIND "127.0.0.1"
setx SYMFORGE_DAEMON_BIND "127.0.0.1"

Open a new terminal after setx.

Linux Bash

Current shell:

export SYMFORGE_HOME="$HOME/.symforge"
export SYMFORGE_AUTO_INDEX=true
export SYMFORGE_RECONCILE_INTERVAL=30
export SYMFORGE_SIDECAR_BIND=127.0.0.1
export SYMFORGE_DAEMON_BIND=127.0.0.1
unset SYMFORGE_NO_DAEMON
unset SYMFORGE_DEBUG_RANKING

Persist in ~/.bashrc:

python3 - <<'PY'
from pathlib import Path
import re

path = Path.home() / ".bashrc"
start = "# >>> SymForge env >>>"
end = "# <<< SymForge env <<<"
block = """# >>> SymForge env >>>
export SYMFORGE_HOME="$HOME/.symforge"
export SYMFORGE_AUTO_INDEX=true
export SYMFORGE_RECONCILE_INTERVAL=30
export SYMFORGE_SIDECAR_BIND=127.0.0.1
export SYMFORGE_DAEMON_BIND=127.0.0.1
# <<< SymForge env <<<"""

text = path.read_text() if path.exists() else ""
pattern = re.compile(re.escape(start) + r".*?" + re.escape(end), re.S)
if pattern.search(text):
    text = pattern.sub(block, text)
else:
    if text and not text.endswith("\n"):
        text += "\n"
    text += block + "\n"
path.write_text(text)
PY

macOS Zsh

Current shell:

export SYMFORGE_HOME="$HOME/.symforge"
export SYMFORGE_AUTO_INDEX=true
export SYMFORGE_RECONCILE_INTERVAL=30
export SYMFORGE_SIDECAR_BIND=127.0.0.1
export SYMFORGE_DAEMON_BIND=127.0.0.1
unset SYMFORGE_NO_DAEMON
unset SYMFORGE_DEBUG_RANKING

Persist in ~/.zshrc:

python3 - <<'PY'
from pathlib import Path
import re

path = Path.home() / ".zshrc"
start = "# >>> SymForge env >>>"
end = "# <<< SymForge env <<<"
block = """# >>> SymForge env >>>
export SYMFORGE_HOME="$HOME/.symforge"
export SYMFORGE_AUTO_INDEX=true
export SYMFORGE_RECONCILE_INTERVAL=30
export SYMFORGE_SIDECAR_BIND=127.0.0.1
export SYMFORGE_DAEMON_BIND=127.0.0.1
# <<< SymForge env <<<"""

text = path.read_text() if path.exists() else ""
pattern = re.compile(re.escape(start) + r".*?" + re.escape(end), re.S)
if pattern.search(text):
    text = pattern.sub(block, text)
else:
    if text and not text.endswith("\n"):
        text += "\n"
    text += block + "\n"
path.write_text(text)
PY

Optional Policies

Force local in-process mode

export SYMFORGE_NO_DAEMON=1

PowerShell:

$env:SYMFORGE_NO_DAEMON = "1"

Enable persistent frecency

export SYMFORGE_FRECENCY=1

Warm co-change on startup

export SYMFORGE_COUPLING=1

Unset SYMFORGE_COUPLING for lazy prepare-on-request behavior.

Enable default ranking diagnostics

export SYMFORGE_DEBUG_RANKING=1

Most users should leave this unset and request debug_ranking=true per query.

Override local database paths

export SYMFORGE_ANALYTICS_DB_PATH="$HOME/.symforge/analytics.db"
export SYMFORGE_FRECENCY_DB_PATH="$HOME/.symforge/frecency.db"
export SYMFORGE_COUPLING_DB_PATH="$HOME/.symforge/coupling.db"

Verify

After changing environment values:

symforge --version
symforge analytics status

Then call health from your MCP client and confirm the expected runtime, capability, and local-store state.