Configuration reference

simse uses separate JSON configuration files to control ACP provider connections, MCP tool servers, memory behavior, embeddings, and general preferences. Configuration files live in:

• Linux: ~/.config/simse/
• macOS: ~/Library/Application Support/simse/
• Windows: %APPDATA%\simse\

simse creates default configuration on first run. Every setting has a sensible default, so you only need to change what matters to your workflow.

Config directory layout

~/.config/simse/
  acp.json        # ACP (LLM provider) servers
  mcp.json        # MCP tool servers
  config.json     # General user preferences
  memory.json     # Library/memory settings
  embed.json      # Embedding provider (optional)

ACP servers — acp.json

Configure ACP backend connections. Each server entry defines an LLM provider that simse can route requests to:

{
  "servers": [
    {
      "name": "anthropic",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/claude-code"],
      "env": { "ANTHROPIC_API_KEY": "sk-..." },
      "defaultAgent": "claude-sonnet-4-6",
      "timeoutMs": 60000
    }
  ],
  "defaultServer": "anthropic",
  "defaultAgent": "claude-sonnet-4-6"
}

Field	Type	Default	Description
servers[].name	string	—	Unique name for this ACP server
servers[].command	string	—	Command to start the server process
servers[].args	string[]	[]	Arguments passed to the command
servers[].cwd	string	—	Working directory for the server process
servers[].env	object	{}	Environment variables passed to the server
servers[].defaultAgent	string	—	Default agent/model for this server
servers[].timeoutMs	integer	60000	Request timeout in milliseconds
defaultServer	string	—	Which server to use when none is specified
defaultAgent	string	—	Global default agent/model

MCP tool servers — mcp.json

Configure MCP tool servers that provide tools to the agent:

{
  "servers": [
    {
      "name": "filesystem",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"],
      "env": {},
      "requiredEnv": []
    }
  ]
}

Field	Type	Default	Description
servers[].name	string	—	Unique name for this tool server
servers[].transport	string	"stdio"	Transport type: "stdio" or "http"
servers[].command	string	—	Command to start the server (stdio transport)
servers[].args	string[]	[]	Arguments passed to the command
servers[].env	object	{}	Environment variables passed to the server
servers[].requiredEnv	string[]	[]	Environment variables that must be set for the server to start

General preferences — config.json

General user preferences:

{
  "defaultAgent": "claude-sonnet-4-6",
  "logLevel": "warn"
}

Field	Type	Default	Description
defaultAgent	string	—	Default agent/model, overridden by acp.json server-level defaults
logLevel	string	"warn"	Log verbosity: "error", "warn", "info", "debug", "trace"

Memory settings — memory.json

Configure the memory/library system:

{
  "enabled": true,
  "similarityThreshold": 0.7,
  "maxResults": 10
}

Field	Type	Default	Description
enabled	boolean	true	Enable or disable memory
similarityThreshold	float	0.7	Minimum similarity score for memory retrieval
maxResults	integer	10	Maximum number of results returned from memory queries

Workspace overrides

Per-project settings can override the global configuration. Place a settings.json file in the project's .simse/ directory:

my-project/
  .simse/
    settings.json
  SIMSE.md

.simse/settings.json overrides global defaults for that project:

{
  "defaultAgent": "claude-opus-4-7",
  "systemPrompt": "You are a Go expert.",
  "defaultServer": "local"
}

SIMSE.md in the project root serves as the workspace system prompt. It is plain text loaded automatically when simse starts in that directory.