Configuration

Config file locations

Docmancer uses YAML config files. It checks in this order:

1. --config <path> on any command (explicit path).
2. ./docmancer.yaml in the current directory (project-local).
3. ~/.docmancer/docmancer.yaml (global, auto-created on first use).

Global config

Created automatically when you first run docmancer setup or docmancer docs add. Located at ~/.docmancer/docmancer.yaml.

The default stack uses the vendored potion-base-8M model, sqlite-vec, and hybrid retrieval. It requires no API key, daemon, or model download.

Minimal docs-index override:

index:
  db_path: ~/.docmancer/docmancer.db
  extracted_dir: ~/.docmancer/extracted/

Project-local config

Create a project-specific config by writing a docmancer.yaml in the project directory. When present, it takes precedence over the global config for any command run from that directory. Relative index.db_path values resolve against the config file's directory, not the shell's current directory.

index

Controls the SQLite FTS5 index.

vector_store

Controls the vector backend. sqlite-vec is the default local path. Qdrant is an optional heavy compatibility backend.

embeddings

Selects the dense embeddings provider. Sparse retrieval is available only on the optional heavy Qdrant path.

Content-hash-keyed cache at ~/.docmancer/embeddings-cache/ skips re-embedding unchanged chunks. Cloud providers retry on 429/5xx with bounded exponential backoff; when a configured cloud provider has no API key in env, ingest falls back to FTS5-only with a warning rather than aborting.

retrieval

Controls the retrieval dispatcher: hybrid fusion, hierarchical two-stage retrieval, query routing, and neighbor expansion.

query

Defaults for docmancer docs query.

discovery, capture, and providers

These three sections describe the memory harness rather than docs retrieval, and are normally written by docmancer setup, docmancer agent install, and docmancer providers rather than by hand.

Provider API keys are never stored here. They live in the operating-system keyring.

web_fetch

Defaults for URL-based docmancer docs add.

Environment variables

Any field above can be overridden via its prefixed environment variable.

Example: full hybrid config

index:
  provider: sqlite
  db_path: ~/.docmancer/docmancer.db
  extracted_dir: ~/.docmancer/extracted

vector_store:
  provider: sqlite-vec
  collection: docmancer
  options:
    db_path: ~/.docmancer/sqlite-vec.db

embeddings:
  provider: model2vec
  model: minishlab/potion-base-8M
  dimensions: 256

retrieval:
  default_mode: hybrid
  hierarchical:
    auto: true
    auto_min_documents: 10
  fusion:
    method: rrf
    rrf_k: 60

query:
  default_budget: 2400
  default_limit: 8
  default_expand: adjacent

Deprecated and removed keys

• registry: and packs: are retired hosted API-pack configuration and should be removed.
• bench: was removed in 0.5.0 along with the docmancer bench command. YAML that still contains it loads with a deprecation warning.
• eval: was removed in 0.5.0. Same warning behaviour as bench:.

Data locations

DOCMANCER_HOME moves everything under ~/.docmancer to another root.

Resetting

To clear the docs index but keep everything else:

docmancer docs remove --all

To remove all machine-wide Docmancer state, including config, indexes, the memory tree, caches, and vendored models:

docmancer clear

clear prints an itemised size table and waits for confirmation. It does not touch project-local .docmancer/ directories or Cloud credentials in the OS keyring. Rebuild afterwards with docmancer setup.