Configuration

Configuration

Recollectium uses a JSON config file plus XDG-style directories for data, cache, logs, and runtime files. Most users can install and run Recollectium without editing config manually. Use this page when you want to inspect paths, change the service port, move the database, or understand every setting.

Config location

Default config path:

~/.config/recollectium/config.json

On systems that set XDG_CONFIG_HOME, the config lives at:

$XDG_CONFIG_HOME/recollectium/config.json

Print the resolved path without creating a file:

recollectium config --path

Print built-in defaults without creating a file:

recollectium config --defaults

Print effective config:

recollectium config

The effective config is the built-in defaults merged with any values in your config file.

Defaults

{
  "version": 1,
  "cli_output": "human_readable",
  "database": {
    "path": "recollectium.db"
  },
  "embedding": {
    "provider": "builtin-fastembed",
    "model": "jinaai/jina-embeddings-v2-small-en"
  },
  "service": {
    "host": "127.0.0.1",
    "port": 8765
  },
  "logging": {
    "level": "info",
    "format": "json",
    "max_bytes": 10485760,
    "backup_count": 5
  },
  "directories": {
    "data": null,
    "cache": null,
    "logs": null,
    "runtime": null
  },
  "development": {
    "use_seeded_database": false,
    "seeded_database_path": "dev-seeded-memory.db"
  },
  "workspace": {
    "uid_normalization": "normalize"
  }
}

Settings

Setting	Type	Default	Options	What it does
version	integer	1	1	Config schema version. Recollectium uses this to validate the config format. Do not change it unless a future migration says to.
cli_output	string	human_readable	human_readable, json	Output format for CLI command results and non-argparse failures. Use human_readable for terminal-friendly summaries and errors. Human-readable output uses Rich-backed ANSI color only when the target stream is a TTY; pipes and captured output remain plain text. Use json for scripts and adapters.
database.path	string path	recollectium.db	relative or absolute path	SQLite database file. Relative paths resolve under the data directory. Absolute paths are used as written.
embedding.provider	string	builtin-fastembed	currently builtin-fastembed	Embedding provider. v1 supports the built-in local FastEmbed provider.
embedding.model	string	jinaai/jina-embeddings-v2-small-en	currently the built-in model	Embedding model name. Other models are planned for future releases, but v1 validates the built-in profile.
service.host	string	127.0.0.1	host or IP address	Bind host for API or managed MCP service. Keep this on localhost unless you have private networking and external access controls.
service.port	integer	8765	TCP port	Port used by the API or managed MCP service. Change this if the default port is already in use.
logging.level	string	info	debug, info, warning, error	Minimum log level. Use debug when troubleshooting.
logging.format	string	json	json	Log output format. v1 uses structured JSON logs.
logging.max_bytes	integer	10485760	positive integer	Maximum size of the active log file before rotation. Default is 10 MiB.
logging.backup_count	integer	5	non-negative integer	Number of rotated log files to keep.
directories.data	string path or null	null	path or null	Data directory override. Stores the default SQLite database and other durable data. Null means use XDG defaults.
directories.cache	string path or null	null	path or null	Cache directory override. Used for cached runtime assets. Null means use XDG defaults.
directories.logs	string path or null	null	path or null	Logs directory override. Null means use XDG state defaults.
directories.runtime	string path or null	null	path or null	Runtime directory override for PID and discovery files. Null means use XDG_RUNTIME_DIR when available, otherwise a fallback under data.
development.use_seeded_database	boolean	false	true, false	Uses a separate seeded development database instead of database.path for normal Recollectium operations. Enable this for embedding/search/operation testing without touching your regular memory database.
development.seeded_database_path	string path	dev-seeded-memory.db	relative or absolute path	SQLite path for the seeded development database. Relative paths resolve under the data directory. recollectium dev reset replaces this database with the canonical fixture.
workspace.uid_normalization	string	normalize	normalize, exact	Controls workspace UID cleanup. normalize lowercases and slugifies workspace candidates. exact keeps caller-provided UIDs as-is after validation.

XDG paths

When directories.* is null, Recollectium uses XDG-style paths:

• Config: $XDG_CONFIG_HOME/recollectium/, fallback ~/.config/recollectium/
• Data: $XDG_DATA_HOME/recollectium/, fallback ~/.local/share/recollectium/
• Cache: $XDG_CACHE_HOME/recollectium/, fallback ~/.cache/recollectium/
• Logs: $XDG_STATE_HOME/recollectium/logs/, fallback ~/.local/state/recollectium/logs/
• Runtime: $XDG_RUNTIME_DIR/recollectium/, fallback inside the data directory

Config commands

recollectium config
recollectium config --path
recollectium config --defaults
recollectium config --validate
recollectium config get service.port
recollectium config set service.port 9090
recollectium config unset service.port
recollectium config init --force
recollectium config edit
recollectium config reset
recollectium config doctor

recollectium config

Prints the effective config as human-readable text by default. Pass --json when you need formatted JSON. This is the best first command when you want to know which values Recollectium is actually using.

recollectium config --path

Prints the config file path that Recollectium would use. It does not create the file.

recollectium config --defaults

Prints the built-in defaults. It does not read or create your config file.

recollectium config --validate

Validates the active config and exits:

• 0 when valid.
• 1 when an explicit config file is missing.
• 2 when the config exists but is invalid.

recollectium config get KEY

Prints one effective value. Keys use dot notation.

Example:

recollectium config get service.port

recollectium config set KEY VALUE

Writes one config value. The value is parsed as JSON when possible, so numbers, booleans, null, and quoted strings work as expected.

Examples:

recollectium config set service.port 9090
recollectium config set logging.level '"debug"'
recollectium config set cli_output json
recollectium config set directories.data '"/data/recollectium"'
recollectium dev true

recollectium config unset KEY

Removes an explicit key from your config file. The built-in default then applies again.

Example:

recollectium config unset service.port

recollectium config init [--force]

Creates a starter config file with all defaults. If the file already exists, use --force to overwrite it.

recollectium config edit

Opens the config file in $EDITOR. If the file does not exist, Recollectium creates it first with defaults.

recollectium config reset

Replaces the config file with a fresh copy of defaults. Use this when you want to discard local config edits.

recollectium config doctor

Checks that the config is valid and that resolved data, cache, logs, runtime, and database parent directories exist, are directories, and are writable.

Seeded development database

Recollectium can switch normal operations to a pre-seeded development database for repeatable embedding and memory-operation tests. The seeded database is separate from your regular database.path and contains:

• 100 user memories across 10 topic buckets.
• Each topic has a balanced mix of 1-, 2-, and 3-sentence memories.
• 3 workspaces.
• 30 memories per workspace, for 90 workspace memories total.
• Each workspace has 3 internal themes with 10 memories each for retrieval evaluation.
• Each workspace has a balanced mix of 1-, 2-, and 3-sentence memories.

The user topics are normal fictional preferences and notes for travel, transportation, videogames, books, cooking, fitness, music, pets, learning, and home style.

The fictional workspaces are software-style demo projects:

Project	Workspace UID	Summary	Themes
CedarLedger	proj-fic-cedarledger-01	Bookkeeping app for independent workshops.	permissions, exports, reconciliation
Northstar Forms	proj-fic-northstar-forms-01	Offline-friendly form builder for structured field notes.	form-builder, offline-sync, review
HarborPilot	proj-fic-harborpilot-01	Scheduling and task board for repair crews.	scheduling, equipment, handoff

Enable it with the dev switch:

recollectium dev true

Optionally choose a custom path:

recollectium config set development.seeded_database_path '"/tmp/recollectium-dev-seed.db"'

When development.use_seeded_database is true, commands and core operations use development.seeded_database_path instead of database.path. If the seeded database is missing or incomplete, Recollectium recreates it before opening the store.

recollectium dev true, recollectium dev false, and recollectium dev reset refuse to run while a managed Recollectium service is already running. Stop or restart the service around the switch so API and MCP traffic cannot keep writing to the previously opened database.

Reset the development fixture back to its canonical seeded state:

recollectium dev reset

Run the seeded retrieval-quality evaluator:

recollectium dev eval

The eval reports Exact MRR, Semantic MRR, Thematic Precision@10, and Ranked-set NDCG@5 as separate metrics. It is a development regression check for the seeded fixture, not a benchmark leaderboard or a user-facing quality guarantee. It refuses to run if the seeded database path matches the selected regular database path, including global --db overrides.

Return to your regular memory database with one config change:

recollectium dev false

You can also remove the explicit setting and fall back to the default:

recollectium config unset development.use_seeded_database

dev reset only targets development.seeded_database_path. It does not touch database.path.

CLI overrides

Global CLI options override config values for one invocation only:

recollectium --db /tmp/recollectium.db list
recollectium --config /tmp/config.json config
recollectium --log-level debug search-user "preferences about wording"
recollectium --json list
recollectium --json service discover

Use config for durable settings. Use CLI overrides for tests, temporary databases, debugging, output-format changes, or one-off operations. --json and --human-readable are mutually exclusive and can appear before or after the command. They override cli_output for one invocation only, including non-argparse failure output. If a command needs the literal value --json or --human-readable, put it after -- so it is treated as a value instead of an output flag. completion --source, completion candidate generation, serve, and mcp-stdio keep their protocol output regardless of cli_output.