Config

smem install / sm install / statefulmemory install writes ~/.statefulmemory/config.toml with hybrid search, the conflict judge, extract, and Laya System-1 enabled. Code defaults also enable conflict.enabled and search.mode = "hybrid". Extract and Laya stay opt-in in code defaults (no LLM / sidecar on unit tests) but install turns them on. Skip Laya setup with --no-laya.

Hybrid retrieval is local (BM25 + BGE-small + RRF + optional local CE). Extract, conflict, optional LLM --rerank, resolve, and Decide call whichever agent CLI is on PATH — or Laya when [laya] enabled (silent Claude fallback on decide/conflict; heuristic-only fallback on the query router). They use that agent’s current/default model unless you pin one (STATEFULMEMORY_LLM_MODEL=qwen, --rerank opencode/glm-5.3, or a concrete Zen id). Roles in config (fast / capable / haiku / sonnet) mean inherit, not a vendor slug. Host env such as CURSOR_MODEL / OPENCODE_MODEL is used when set.

Disable the judge if you want heuristic supersession only:

statefulmemory config set conflict.enabled false
statefulmemory config set extract.enabled false    # skip fact triples on save
statefulmemory config set search.mode bm25         # lexical-only retrieval
statefulmemory config set embed.quantize true      # int8 vectors (~75% smaller)
statefulmemory config set verify.serve_stale true  # keep stale claims in context
statefulmemory config set search.decay_lambda 0.005
statefulmemory config set search.evidence_window 2
statefulmemory config set search.max_per_type 2
statefulmemory config set laya.enabled false       # disable System-1 sidecar
statefulmemory obs reindex                         # backfill embeddings

Config files

• Global: ~/.statefulmemory/config.toml
• Per-project overlay: ~/.statefulmemory/projects/<name>.config.toml

Merge order (highest wins): env vars → project overlay → global → code defaults.

Common env overrides

STATEFULMEMORY_EXTRACT_ENABLED, STATEFULMEMORY_EXTRACT_MODEL, STATEFULMEMORY_EXTRACT_TIMEOUT_SECS, STATEFULMEMORY_EXTRACT_WORKERS, STATEFULMEMORY_RERANK_MODEL, STATEFULMEMORY_RERANK_TIMEOUT_SECS, STATEFULMEMORY_EMBED_WORKERS, STATEFULMEMORY_EMBED_QUANTIZE, STATEFULMEMORY_CONFLICT_ENABLED, STATEFULMEMORY_CONFLICT_MODEL, STATEFULMEMORY_CONFLICT_TIMEOUT_SECS, STATEFULMEMORY_VERIFY_SERVE_STALE, STATEFULMEMORY_SEARCH_MODE, STATEFULMEMORY_SEARCH_DECAY_LAMBDA, STATEFULMEMORY_SEARCH_EVIDENCE_WINDOW, STATEFULMEMORY_SEARCH_MAX_PER_TYPE, STATEFULMEMORY_LAYA_ENABLED, STATEFULMEMORY_LAYA_URL, STATEFULMEMORY_LAYA_TIMEOUT_MS, STATEFULMEMORY_LAYA_ROUTER, STATEFULMEMORY_LAYA_DECIDE, STATEFULMEMORY_LAYA_CONFLICT, STATEFULMEMORY_LAYA_BACKEND (auto | mlx | torch), STATEFULMEMORY_LLM_BIN, STATEFULMEMORY_LLM_PROVIDER, STATEFULMEMORY_LLM_MODEL (legacy STATEFULMEMORY_CLAUDE_MODEL is the same as STATEFULMEMORY_LLM_MODEL).

Laya sidecar backend

Full walkthrough: Laya System-1. Backend selection:

[laya] backend picks the sidecar inference runtime:

• auto (default): laya-mlx on Apple Silicon (macOS 14+, Python ≥ 3.11), PyTorch laya everywhere else
• mlx: force the native MLX runtime (published P50 on an M3 Max: 13.4 ms for the 421M checkpoint, 7.4 ms multilingual; no PyTorch dependency)
• torch: force the PyTorch / Transformers laya package (CUDA / Linux servers)

Default timeout_ms = 80 fits the single-question router/conflict calls but drops decide / resolve on MLX (~100–200 ms for 2–3 question batches) — use timeout_ms = 250 for those call sites.

smem doctor and GET /health report the active backend. All three run the same Laya checkpoints with identical typed output schemas; the choice is purely about hardware.

See the repository AGENTS.md (OpenCode / Codex / local LLMs) and CLAUDE.md for the full knob list and architecture notes.