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",
  "response_verbosity": "compact",
  "database": {
    "folder": "memory-spaces",
    "default_memory_space": "default"
  },
  "embedding": {
    "provider": "builtin-fastembed",
    "model": "BAAI/bge-base-en-v1.5"
  },
  "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"
  },
  "retrieval": {
    "protected_minimum": 3,
    "match_threshold": "model_recommended_default"
  }
}

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.
response_verbosity	string	compact	compact, verbose	Response detail for CLI command payloads. Use compact for shorter summaries and verbose for fuller payloads. Global --compact and --verbose override this setting for one invocation.

| database.folder | string path | memory-spaces | relative or absolute path | Folder that holds the per-memory-space databases. Relative paths resolve under the data directory. Absolute paths are used as written. | | database.default_memory_space | string | default | memory-space key | Default memory-space key used when commands do not specify --memory-space. | | embedding.provider | string | builtin-fastembed | currently builtin-fastembed | Embedding provider. v1 supports the built-in local FastEmbed provider. | | embedding.model | string | BAAI/bge-base-en-v1.5 | BAAI/bge-base-en-v1.5, jinaai/jina-embeddings-v2-small-en | Embedding model name. The default BGE base profile has 768 dimensions, max tokens 512, chunk tokens 384, and overlap 64. The legacy Jina small profile has 512 dimensions, max tokens 8192, chunk tokens 6144, and overlap 512. Switching model or profile can require existing memories to be re-embedded. Recollectium runs stale-profile refreshes inline in the triggering command, API request, or MCP tool call, and exposes explicit refresh and job cleanup controls. | | 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 the normal memory-space database for Recollectium operations. Enable this for embedding/search/operation testing without touching your regular memory databases. | | 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. | | retrieval.protected_minimum | integer | 3 | integer >= 0 | Keeps this many top-ranked search results before threshold filtering applies. | | retrieval.match_threshold | string, null, or number | model_recommended_default | model_recommended_default, null, or 0.0 to 1.0 | Match threshold for search results after the protected minimum. model_recommended_default uses the recommendation shipped with the active built-in embedding model, null disables threshold filtering, and numeric values use that exact cutoff. For built-in models, BAAI/bge-base-en-v1.5 recommends 0.63 and jinaai/jina-embeddings-v2-small-en recommends 0.78. |

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

Legacy database.path is rejected. Use database.folder and database.default_memory_space instead.

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 memory-space databases 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 the normal memory-space database. 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 Weighted Precision@10, Thematic Weighted Recall@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. In a human-readable TTY, it may also show live phase and status updates on stderr, while the final summary stays on stdout and JSON output remains structured and automation-safe. It refuses to run if the seeded database path matches the selected regular database path.

Run the seeded threshold optimizer:

recollectium dev optimize-threshold --format png --output threshold-sweep.png

The optimizer uses checked-in thematic query-memory labels to sweep retrieval.match_threshold values. It writes a PNG graph by default, or CSV with --format csv, and marks a recommended threshold. The recommendation maximizes weighted F-beta. With no beta specified, the default is --beta 0.5 for F0.5, which biases toward precision and fewer noisy matches. --beta 1.0 is the balanced precision/recall option, and higher beta values favor recall. Human-readable output includes a progress bar with ETA during threshold scoring, plus the recommendation, weighted precision, weighted recall, F-beta score, confuser exposure, unrelated exposure, and average returned count. It is advisory by default; pass --write-config to persist the recommended threshold into retrieval.match_threshold.

recollectium dev optimize-threshold --beta 0.5 --format csv --output precision-sweep.csv
recollectium dev optimize-threshold --beta 2.0 --write-config

The optimizer refuses to run if the seeded database path matches the selected regular database path.

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 the normal memory-space database.

CLI overrides

Global CLI options override config values for one invocation only:

recollectium list --memory-space project-alpha
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, dev serve, and mcp-stdio keep their protocol output regardless of cli_output.