Skip to content

Configuration reference

Every setting Logic-Loom reads, in the order the code declares them. Set them in ~/.config/logic-loom/config.toml (or the file named by LOGIC_LOOM_CONFIG), or override one with its LOGIC_LOOM_* environment variable. Precedence and examples are in Configuration.

Key Type Default Env var Description
logic_loom_root Path \| None unset LOGIC_LOOM_LOGIC_LOOM_ROOT Optional Logic-Loom source checkout (display only). None = unset.
akms_repo Path \| None unset LOGIC_LOOM_AKMS_REPO Optional, development-only AKMS source checkout. None = unset; nothing requires it, in packaged builds or otherwise. When present it adds the legacy batch plan, Packages/Nodes_Vault, local graph nodes and the /api/nlm developer scripts.
akms_workspace Path computed LOGIC_LOOM_AKMS_WORKSPACE Logic-Loom-owned AKMS workspace root. Holds runtime state (prompts, workflows, batches, runs, generated nodes, NLM inputs/outputs). Bootstrapped on first sidecar startup; safe in packaged builds. Default is under Application Support / XDG data (not Documents) so macOS TCC does not block the sidecar.
akms_global_vault Path \| None unset LOGIC_LOOM_AKMS_GLOBAL_VAULT Source vault for AKMS graph compilation. None = resolve via <akms_repo>/Packages/Nodes_Vault when that optional checkout is present, then AKMS_GLOBAL_VAULT, then the AKMS default.
learn_domain_packs_path Path \| None unset LOGIC_LOOM_LEARN_DOMAIN_PACKS_PATH Root directory scanned (recursively) for AKMS Learn domain-pack descriptor YAMLs (files named 'domain_pack.yaml'). Read as DATA via akms_learn's descriptor loader to drive the Learn tab's domain-pack status UI. None = resolve via learn_domain_packs_search_root() under akms_repo. An empty or missing directory yields domain_packs: [].
zsum_repo Path \| None unset LOGIC_LOOM_ZSUM_REPO Optional, development-only zotero-summarizer checkout. None = unset; zsum runs from the installed package.
vault_path Path \| None unset LOGIC_LOOM_VAULT_PATH Published Obsidian vault root. None = unset → first-run UX.
cache_path Path computed LOGIC_LOOM_CACHE_PATH LogicLoom-owned cache (run history, port file, etc.).
nlm_mcp_url str \| None unset LOGIC_LOOM_NLM_MCP_URL NotebookLM MCP server URL for document-grounded node generation (e.g. http://localhost:3000/sse).
nodes_folders list[Path] computed LOGIC_LOOM_NODES_FOLDERS Staging directories scanned for AKMS node .md files in the Nodes Review tab.
nodes_editor str \| None unset LOGIC_LOOM_NODES_EDITOR Editor command for opening nodes (e.g. 'code'). None = system default (macOS: open). The Settings page accepts known editors with plain flags only; set any other program here in config.toml.
port int \| None unset LOGIC_LOOM_PORT Fixed port, or None for --auto-port.
search_backend Literal['ripgrep', 'qmd'] "ripgrep" LOGIC_LOOM_SEARCH_BACKEND Default backend for /api/vault/search.
vault_qmd_collection str \| None unset LOGIC_LOOM_VAULT_QMD_COLLECTION QMD collection name registered for the vault. Required when search_backend=qmd.
zsum_config_path Path \| None unset LOGIC_LOOM_ZSUM_CONFIG_PATH Absolute path to zsum.config.yaml. None → defaults to <zsum_repo>/zsum.config.yaml at use time.
zsum_python_cmd str computed LOGIC_LOOM_ZSUM_PYTHON_CMD Command used to invoke the zsum pipeline. Defaults to running the bundled launcher through the sidecar's own Python interpreter, which works in both dev and packaged builds. Override (e.g. 'uv run zsum') only if you want to point at a different zsum install.
zsum_cost_per_mtoken_in float 3.0 LOGIC_LOOM_ZSUM_COST_PER_MTOKEN_IN USD cost per million input tokens (for cost estimation only).
zsum_cost_per_mtoken_out float 15.0 LOGIC_LOOM_ZSUM_COST_PER_MTOKEN_OUT USD cost per million output tokens (for cost estimation only).
zsum_tokens_per_card_in int 4000 LOGIC_LOOM_ZSUM_TOKENS_PER_CARD_IN Estimated input tokens per card.
zsum_tokens_per_card_out int 500 LOGIC_LOOM_ZSUM_TOKENS_PER_CARD_OUT Estimated output tokens per card.
local_models_custom list[str] computed LOGIC_LOOM_LOCAL_MODELS_CUSTOM User-added local model names shown in Home → Models.
local_model_last_installed str \| None unset LOGIC_LOOM_LOCAL_MODEL_LAST_INSTALLED Most recent local model successfully installed/configured from LogicLoom.
anthropic_api_key str \| None unset LOGIC_LOOM_ANTHROPIC_API_KEY Anthropic API key (Claude). Enables the API route for Learn LLM expansion.
openai_api_key str \| None unset LOGIC_LOOM_OPENAI_API_KEY OpenAI API key (Codex/GPT). Enables the API route for Learn LLM expansion.
google_api_key str \| None unset LOGIC_LOOM_GOOGLE_API_KEY Google API key (Gemini). Enables the API route for Learn LLM expansion.
llm_provider str \| None unset LOGIC_LOOM_LLM_PROVIDER Global host LLM provider used by every consumer (Learn/zsum/node-gen) unless a per-consumer override is set. Same vocabulary as the legacy learn_llm_provider: 'akms' (API/LiteLLM), 'claude-cli', 'codex-cli', 'nlm', or a custom label. None/'auto' = auto-resolve (nlm or API key only; CLI agents require an explicit choice). When unset, the legacy learn_llm_provider value is read as the back-compat alias.
learn_llm_provider str \| None unset LOGIC_LOOM_LEARN_LLM_PROVIDER Legacy/back-compat alias for the global llm_provider. Kept so existing config.toml files keep working untouched: when llm_provider is unset, learn_llm_provider is read as the effective global provider (effective = llm_provider or learn_llm_provider). Same vocabulary: 'akms' (API/LiteLLM), 'claude-cli', 'codex-cli', 'nlm', or a custom label. None/'auto' = auto-resolve.
zsum_llm_provider str \| None unset LOGIC_LOOM_ZSUM_LLM_PROVIDER Per-consumer override for the zsum (Zotero Summarizer) host LLM provider. None = fall back to the global llm_provider (then the learn_llm_provider alias). Same provider vocabulary as llm_provider.
nodegen_llm_provider str \| None unset LOGIC_LOOM_NODEGEN_LLM_PROVIDER Per-consumer override for the AKMS node-generation host LLM provider. None = fall back to the global llm_provider (then the learn_llm_provider alias). Same provider vocabulary as llm_provider.
learn_llm_custom_clis dict[str, str] computed LOGIC_LOOM_LEARN_LLM_CUSTOM_CLIS User-defined CLI providers: label → command template. '{prompt}' is argv-substituted (no shell); absent → prompt piped to stdin. Empty command = not registered.
openalex_user_email str \| None unset LOGIC_LOOM_OPENALEX_USER_EMAIL OpenAlex polite-pool email used as the User-Agent contact. Required for the OpenAlex client; optional only when the Assistant Discovery feature is disabled.
openalex_api_key str \| None unset LOGIC_LOOM_OPENALEX_API_KEY Optional OpenAlex API key (premium tier).
semantic_scholar_api_key str \| None unset LOGIC_LOOM_SEMANTIC_SCHOLAR_API_KEY Optional Semantic Scholar API key. The Assistant client uses the public endpoint when this is unset, with stricter rate limits.
assistant_workspace Path \| None unset LOGIC_LOOM_ASSISTANT_WORKSPACE Assistant data tree root. None = resolve via assistant_workspace_path() — either <akms_workspace>/../Assistant-Workspace, or <akms_workspace>/assistant/ when co-located with the AKMS workspace.
assistant_workspace_colocate bool False LOGIC_LOOM_ASSISTANT_WORKSPACE_COLOCATE When True and assistant_workspace is unset, the resolver returns <akms_workspace>/assistant/ instead of the sibling Assistant-Workspace directory. Lets users keep both trees under a single root.
failure_memory_mode Literal['disabled', 'read-only', 'operator'] "read-only" LOGIC_LOOM_FAILURE_MEMORY_MODE Permission mode for the Failure Memory workspace. 'read-only' (default) exposes inspection/preview/diagnostics only and cannot mutate any configured repository. 'operator' additionally unlocks record/refresh/compile and must be set deliberately in config.toml or LOGIC_LOOM_FAILURE_MEMORY_MODE. 'disabled' turns the surface off entirely.
failure_memory_projects list[FailureMemoryProject] computed LOGIC_LOOM_FAILURE_MEMORY_PROJECTS EXPLICITLY configured failure-memory projects, as [[failure_memory_projects]] array-of-tables entries with id + config (+ optional root). Logic-Loom never discovers .failure-memory directories by walking the filesystem — an unlisted project is invisible to the app, by design.
records_stores list[RecordsStore] computed LOGIC_LOOM_RECORDS_STORES EXPLICITLY configured akms-records stores, as [[records_stores]] array-of-tables entries with id + scope (+ repo for a project scope, optional home for agent/shared). Logic-Loom only reads them and never discovers stores by scanning.
seed_starter_batches bool True LOGIC_LOOM_SEED_STARTER_BATCHES Seed the AKMS batch store with shipped starter batches on first sidecar startup. Seeding runs only when the store is empty; existing batches (including any whose id collides with a seed id) are never overwritten. Set False to skip seeding entirely — useful for clean-room testing or users who want a blank workspace.