Configuration Reference

All four primitives (taskprim, stateprim, knowledgeprim, and queueprim) read the same YAML configuration format. Copy config.example.yaml to config.yaml and edit to suit your environment. knowledgeprim adds additional fields for embedding and auto-connect.

Resolution Order

Configuration is resolved differently depending on whether you pass --config.

With `--config` (recommended for multi-agent deployments)

Highest precedence wins:

--db / --port CLI flags — explicit per-invocation overrides
YAML file — values from your config file, with ${ENV_VAR} interpolation for secrets
Hardcoded defaults — e.g., port 8090

Environment variable overrides (TASKPRIM_DB, etc.) are not applied when a config file is present. This prevents a global env var from silently overriding per-agent configuration in multi-agent deployments. Use ${VAR} interpolation inside the YAML when you need to inject a dynamic value.

Without `--config` (env-only / container deployments)

Highest precedence wins:

--db / --port CLI flags
Environment overrides — prefix-based env vars (TASKPRIM_*, STATEPRIM_*, KNOWLEDGEPRIM_*, QUEUEPRIM_*)
Hardcoded defaults

Full YAML Spec

storage:
  db: ~/.taskprim/default.db
  replicate:
    enabled: false
    provider: r2
    bucket: ${R2_BUCKET}
    path: taskprim.db
    endpoint: ${R2_ENDPOINT}
    access_key_id: ${R2_ACCESS_KEY_ID}
    secret_access_key: ${R2_SECRET_ACCESS_KEY}

auth:
  keys:
    - key: "tp_sk_your_api_key_here"
      name: "johanna"

server:
  port: 8090

taskprim:
  default_list: ""              # reserved — use TASKPRIM_LIST env var instead

# knowledgeprim-only settings (ignored by taskprim and stateprim)
embedding:
  provider: ""              # gemini | openai | custom (empty = disabled)
  model: ""                 # e.g., text-embedding-004 (Gemini), text-embedding-3-small (OpenAI)
  dimensions: 768           # expected output dimensions
  api_key: ${EMBEDDING_API_KEY}
  endpoint: ""              # custom endpoint for local models or proxies

auto_connect:
  enabled: true             # auto-link new entities to similar ones on capture
  threshold: 0.35           # cosine distance threshold (lower = more similar)
  max_connections: 10       # max auto-connections per capture

Fields

`storage`

Field	Type	Default	Description
`db`	string	`~/.taskprim/default.db`	Path to the SQLite database file. Created automatically if it doesn't exist. Parent directories are created as needed.

`storage.replicate`

Litestream replication configuration. When enabled, WAL frames are continuously streamed to object storage for durability. Replication runs for all commands (CLI, serve, MCP).

Field	Type	Default	Description
`enabled`	bool	`false`	Enable WAL replication to object storage.
`provider`	string	—	Object storage provider: `r2`, `s3`, `b2`, or `gcs`.
`bucket`	string	—	Bucket name in the object storage provider.
`path`	string	—	Object path within the bucket (e.g., `taskprim.db`).
`endpoint`	string	—	Custom S3-compatible endpoint. Required for R2 and B2. Not needed for AWS S3.
`access_key_id`	string	—	Access key for the object storage provider. Use `${ENV_VAR}` interpolation.
`secret_access_key`	string	—	Secret key for the object storage provider. Use `${ENV_VAR}` interpolation.

`auth`

Authentication is only used in serve and MCP SSE modes. CLI mode relies on filesystem permissions.

Field	Type	Default	Description
`keys`	list	`[]`	List of API keys and their human-readable names. When empty, authentication is disabled (open mode).

Each key entry:

Field	Type	Description
`key`	string	The API key value. Passed as `Authorization: Bearer <key>`.
`name`	string	Human-readable name mapped to this key. Used as the `source` field when creating tasks or records via the API, so you can tell who created what.

`server`

Field	Type	Default	Description
`port`	int	`8090`	HTTP server port for `serve` and MCP SSE transport.

`taskprim`

taskprim-specific settings (ignored by stateprim). Note: the default_list field shown in the YAML spec is reserved for future use. Currently, the default list is set via the TASKPRIM_LIST environment variable only.

Field	Type	Default	Description
`default_list`	string	`""`	Reserved. Use the `TASKPRIM_LIST` environment variable to set the default list for new tasks when `--list` is omitted.

`embedding` (knowledgeprim only)

Vector embedding configuration. When a provider is configured, knowledgeprim generates embeddings on capture and enables vector and hybrid search modes.

Field	Type	Default	Description
`provider`	string	`""`	Embedding provider: `gemini`, `openai`, or `custom`. Empty string disables embedding.
`model`	string	`""`	Provider-specific model name (e.g., `text-embedding-004` for Gemini, `text-embedding-3-small` for OpenAI).
`dimensions`	int	`768`	Expected output vector dimensions. Must match the model's output.
`api_key`	string	—	API key for the embedding provider. Use `${ENV_VAR}` interpolation.
`endpoint`	string	`""`	Custom endpoint URL. Required for `custom` provider. Optional for `openai` (overrides default). Unused for `gemini`.

Supported providers:

Provider	Model	Dimensions	Notes
`gemini`	`text-embedding-004`	768	Google Gemini (default model; supports Matryoshka dimensions)
`openai`	`text-embedding-3-small`	1536	OpenAI
`openai`	`text-embedding-3-large`	3072	OpenAI (highest quality)
`custom`	Any	Configurable	Any OpenAI-compatible endpoint (local models, proxies)

`auto_connect` (knowledgeprim only)

Auto-connect configuration. When embedding is enabled, new entities are automatically linked to semantically similar existing entities on capture.

Field	Type	Default	Description
`enabled`	bool	`true`	Enable auto-connect when capturing with embeddings.
`threshold`	float	`0.35`	Cosine distance threshold. Lower = more similar. Entities below this threshold get automatic `similar_to` edges.
`max_connections`	int	`10`	Maximum number of auto-connections created per capture.

Environment Variable Interpolation

Any value in the YAML file can reference environment variables using ${VAR_NAME} syntax. Variables are interpolated at startup. Missing variables resolve to an empty string.

storage:
  replicate:
    access_key_id: ${R2_ACCESS_KEY_ID}
    secret_access_key: ${R2_SECRET_ACCESS_KEY}

This lets you keep secrets out of the config file while still having a single file for all other settings.

Environment Variable Overrides

Environment variables with the appropriate prefix are used when no --config file is provided. They are the primary configuration mechanism for container and CI deployments where mounting a config file is impractical.

Multi-agent note: If you run multiple primitive instances each with its own --config file (e.g. taskprim --config /configs/agent-a.yaml serve), env var overrides are skipped and each instance uses its own file exclusively. Use ${VAR} interpolation inside the YAML to inject secrets while keeping the file authoritative.

taskprim prefix: `TASKPRIM_`

Env Var	Overrides
`TASKPRIM_DB`	`storage.db`
`TASKPRIM_SERVER_PORT`	`server.port`
`TASKPRIM_REPLICATE_ENABLED`	`storage.replicate.enabled`
`TASKPRIM_REPLICATE_PROVIDER`	`storage.replicate.provider`
`TASKPRIM_REPLICATE_BUCKET`	`storage.replicate.bucket`
`TASKPRIM_REPLICATE_PATH`	`storage.replicate.path`
`TASKPRIM_REPLICATE_ENDPOINT`	`storage.replicate.endpoint`
`TASKPRIM_REPLICATE_ACCESS_KEY_ID`	`storage.replicate.access_key_id`
`TASKPRIM_REPLICATE_SECRET_ACCESS_KEY`	`storage.replicate.secret_access_key`

stateprim prefix: `STATEPRIM_`

Same mapping as taskprim, with STATEPRIM_ prefix:

Env Var	Overrides
`STATEPRIM_DB`	`storage.db`
`STATEPRIM_SERVER_PORT`	`server.port`
`STATEPRIM_REPLICATE_ENABLED`	`storage.replicate.enabled`
`STATEPRIM_REPLICATE_PROVIDER`	`storage.replicate.provider`
`STATEPRIM_REPLICATE_BUCKET`	`storage.replicate.bucket`
`STATEPRIM_REPLICATE_PATH`	`storage.replicate.path`
`STATEPRIM_REPLICATE_ENDPOINT`	`storage.replicate.endpoint`
`STATEPRIM_REPLICATE_ACCESS_KEY_ID`	`storage.replicate.access_key_id`
`STATEPRIM_REPLICATE_SECRET_ACCESS_KEY`	`storage.replicate.secret_access_key`

knowledgeprim prefix: `KNOWLEDGEPRIM_`

Same storage/server mapping as above, plus embedding-specific overrides:

Env Var	Overrides
`KNOWLEDGEPRIM_DB`	`storage.db`
`KNOWLEDGEPRIM_SERVER_PORT`	`server.port`
`KNOWLEDGEPRIM_REPLICATE_ENABLED`	`storage.replicate.enabled`
`KNOWLEDGEPRIM_REPLICATE_PROVIDER`	`storage.replicate.provider`
`KNOWLEDGEPRIM_REPLICATE_BUCKET`	`storage.replicate.bucket`
`KNOWLEDGEPRIM_REPLICATE_PATH`	`storage.replicate.path`
`KNOWLEDGEPRIM_REPLICATE_ENDPOINT`	`storage.replicate.endpoint`
`KNOWLEDGEPRIM_REPLICATE_ACCESS_KEY_ID`	`storage.replicate.access_key_id`
`KNOWLEDGEPRIM_REPLICATE_SECRET_ACCESS_KEY`	`storage.replicate.secret_access_key`
`KNOWLEDGEPRIM_EMBEDDING_PROVIDER`	`embedding.provider`
`KNOWLEDGEPRIM_EMBEDDING_MODEL`	`embedding.model`
`KNOWLEDGEPRIM_EMBEDDING_DIMENSIONS`	`embedding.dimensions`
`KNOWLEDGEPRIM_EMBEDDING_API_KEY`	`embedding.api_key`
`KNOWLEDGEPRIM_EMBEDDING_ENDPOINT`	`embedding.endpoint`

queueprim prefix: `QUEUEPRIM_`

Same storage/server mapping as taskprim and stateprim. No primitive-specific fields beyond the shared base.

Env Var	Overrides
`QUEUEPRIM_DB`	`storage.db`
`QUEUEPRIM_SERVER_PORT`	`server.port`
`QUEUEPRIM_REPLICATE_ENABLED`	`storage.replicate.enabled`
`QUEUEPRIM_REPLICATE_PROVIDER`	`storage.replicate.provider`
`QUEUEPRIM_REPLICATE_BUCKET`	`storage.replicate.bucket`
`QUEUEPRIM_REPLICATE_PATH`	`storage.replicate.path`
`QUEUEPRIM_REPLICATE_ENDPOINT`	`storage.replicate.endpoint`
`QUEUEPRIM_REPLICATE_ACCESS_KEY_ID`	`storage.replicate.access_key_id`
`QUEUEPRIM_REPLICATE_SECRET_ACCESS_KEY`	`storage.replicate.secret_access_key`

Examples

Minimal (local development)

storage:
  db: ~/.taskprim/default.db

Everything else uses defaults. No auth, no replication.

With Cloudflare R2 replication

storage:
  db: /data/taskprim.db
  replicate:
    enabled: true
    provider: r2
    bucket: primkit-backups
    path: taskprim.db
    endpoint: https://abc123.r2.cloudflarestorage.com
    access_key_id: ${R2_ACCESS_KEY_ID}
    secret_access_key: ${R2_SECRET_ACCESS_KEY}

auth:
  keys:
    - key: "tp_sk_prod_key_1"
      name: "api-server"
    - key: "tp_sk_prod_key_2"
      name: "agent-01"

server:
  port: 8090

Environment-only (no config file)

export TASKPRIM_DB=/data/taskprim.db
export TASKPRIM_SERVER_PORT=9090
export TASKPRIM_REPLICATE_ENABLED=true
export TASKPRIM_REPLICATE_PROVIDER=s3
export TASKPRIM_REPLICATE_BUCKET=my-bucket
export TASKPRIM_REPLICATE_ACCESS_KEY_ID=AKIA...
export TASKPRIM_REPLICATE_SECRET_ACCESS_KEY=secret...

taskprim serve

When no --config flag is provided, defaults are used and env overrides are applied as the primary configuration mechanism.

knowledgeprim with Gemini embedding

storage:
  db: ~/.knowledgeprim/default.db

embedding:
  provider: gemini
  model: text-embedding-004
  dimensions: 768
  api_key: ${GEMINI_API_KEY}

auto_connect:
  enabled: true
  threshold: 0.35
  max_connections: 10

server:
  port: 8092

knowledgeprim without embedding (FTS-only)

storage:
  db: ~/.knowledgeprim/default.db

Works immediately. Full-text search, manual edges, graph traversal, and discovery all work without embedding.

Database Path Resolution

The database path is resolved in priority order. The rules differ based on whether --config is provided:

With --config /path/to/config.yaml (per-agent configuration):

Priority	Source
1	`--db` flag
2	`storage.db` in the config file
3	Home directory default (`~/.taskprim/default.db`, etc.)

Without --config (env-only / container deployments):

Priority	Source
1	`--db` flag
2	`TASKPRIM_DB` / `STATEPRIM_DB` / `KNOWLEDGEPRIM_DB` env var
3	Home directory default (`~/.taskprim/default.db`, etc.)

The database file and its parent directory are created automatically if they do not exist.

SQLite Pragmas

The following SQLite pragmas are applied automatically when the database is opened:

Pragma	Value	Purpose
`journal_mode`	`WAL`	Allows concurrent reads during writes. Required for Litestream replication and HTTP serve mode.
`foreign_keys`	`ON`	Enforces referential integrity (e.g., task labels reference tasks).
`busy_timeout`	`5000`	Waits up to 5 seconds for locks instead of failing immediately, preventing "database is locked" errors.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Configuration Reference

Resolution Order

With `--config` (recommended for multi-agent deployments)

Without `--config` (env-only / container deployments)

Full YAML Spec

Fields

`storage`

`storage.replicate`

`auth`

`server`

`taskprim`

`embedding` (knowledgeprim only)

`auto_connect` (knowledgeprim only)

Environment Variable Interpolation

Environment Variable Overrides

taskprim prefix: `TASKPRIM_`

stateprim prefix: `STATEPRIM_`

knowledgeprim prefix: `KNOWLEDGEPRIM_`

queueprim prefix: `QUEUEPRIM_`

Examples

Minimal (local development)

With Cloudflare R2 replication

Environment-only (no config file)

knowledgeprim with Gemini embedding

knowledgeprim without embedding (FTS-only)

Database Path Resolution

SQLite Pragmas

FilesExpand file tree

configuration.md

Latest commit

History

configuration.md

File metadata and controls

Configuration Reference

Resolution Order

With --config (recommended for multi-agent deployments)

Without --config (env-only / container deployments)

Full YAML Spec

Fields

storage

storage.replicate

auth

server

taskprim

embedding (knowledgeprim only)

auto_connect (knowledgeprim only)

Environment Variable Interpolation

Environment Variable Overrides

taskprim prefix: TASKPRIM_

stateprim prefix: STATEPRIM_

knowledgeprim prefix: KNOWLEDGEPRIM_

queueprim prefix: QUEUEPRIM_

Examples

Minimal (local development)

With Cloudflare R2 replication

Environment-only (no config file)

knowledgeprim with Gemini embedding

knowledgeprim without embedding (FTS-only)

Database Path Resolution

SQLite Pragmas

With `--config` (recommended for multi-agent deployments)

Without `--config` (env-only / container deployments)

`storage`

`storage.replicate`

`auth`

`server`

`taskprim`

`embedding` (knowledgeprim only)

`auto_connect` (knowledgeprim only)

taskprim prefix: `TASKPRIM_`

stateprim prefix: `STATEPRIM_`

knowledgeprim prefix: `KNOWLEDGEPRIM_`

queueprim prefix: `QUEUEPRIM_`