inkentry config reference

inkentry reads configuration from two TOML files, layered with environment variable overrides.

Config files

The two files are not interchangeable: most fields are only read from the personal config, and the project file accepts a deliberately narrow set (see Project config fields below).

Load order (later overrides earlier):

1. Defaults
2. ~/.config/inkentry/config.toml (global personal). server_url is discarded even if present here: a team server is a project-wide choice, never a single developer's.
3. .inkentry/config.toml, discovered by walking up from the current directory (project-level, team-wide). Only server_url, project_id, server_ca, and [index] are read from this file.
4. Environment variables: INKENTRY_SERVER_URL, INKENTRY_SERVER_KEY, INKENTRY_PROJECT_ID, INKENTRY_SERVER_CA, INKENTRY_LLM_URL, INKENTRY_LLM_MODEL, INKENTRY_MODE.

A variable that is set but empty still overrides the file: INKENTRY_LLM_URL="" blanks a configured llm_url.

Override the global config file path with -c, --config <path> on any command, or relocate the whole ~/.config/inkentry/ directory with INKENTRY_CONFIG_DIR.

Fields (personal config)

These fields are read from ~/.config/inkentry/config.toml. Unless noted otherwise, setting them in .inkentry/config.toml has no effect: the project file only accepts the fields listed under Project config fields.

db_path

• Type: path
• Default: ~/.config/inkentry/index.db

Path to the SQLite index database file. At runtime inkentry prefers the project's .inkentry/index.db; the memory database (memory.db) lives alongside it.

llm_url

• Type: string, optional
• Default: unset
• Env override: INKENTRY_LLM_URL

Base URL of an OpenAI-compatible chat-completions endpoint. When set, the local inkentry-server that inkentry auto-starts is pointed at this endpoint, which enables the LLM-backed features (inkentry harvest, index summaries). Read from the personal config only.

llm_model

• Type: string, optional
• Default: unset
• Env override: INKENTRY_LLM_MODEL

Model name the auto-spawned daemon sends to its llm_url (as --llm-model). Ignored when llm_url is unset. It is not a request parameter you tune per call, and inkentry harvest does not consult it directly.

llm_context_length

• Type: integer
• Default: 8192

Context-window size (tokens) of the configured LLM. inkentry uses this to split inkentry harvest batches that would overflow the model's window. Set it to match the context length of the model you have loaded.

store_in_git_notes

• Type: boolean
• Default: true

When true, inkentry memory add also appends the new entry as a line of JSON to refs/notes/inkentry on HEAD. This keeps memory close to commits, so it travels with the code. Failure to write the git note is non-fatal: a warning is logged and the primary SQLite write is unaffected. Set store_in_git_notes = false to opt out.

server_url

• Type: string, optional
• Default: unset
• Env override: INKENTRY_SERVER_URL

URL of a team inkentry-server instance. When set, memory commands read and write against that shared server: this is the only configuration that moves memory off the local machine. A value in the personal config is always discarded on load; set it in .inkentry/config.toml (project-level) or via INKENTRY_SERVER_URL instead, since a team server is a shared, project-wide choice.

server_url must be https:// unless it points at loopback (127.0.0.1, ::1, or localhost). A non-loopback http:// URL is rejected at startup, with no opt-out, because the CLI attaches your bearer token to these requests.

An auto-discovered loopback inkentry-server is used for inference only and is never a memory store; it does not require this field to be set. See the server setup guide for putting TLS in front of a deployed team server.

mode

• Type: string, optional (offline / local_first / cloud_first)
• Default: unset (derived from server_url; see below)
• Env override: INKENTRY_MODE

Controls where memory reads and writes go, and whether the CLI ever contacts a configured server_url.

When unset, the effective mode is derived: no server_url means offline; a configured server_url means local_first. INKENTRY_NO_SERVER=1 forces offline regardless of this setting, as a hard kill-switch. mode also governs which server answers LLM calls, and whether a configured llm_url keeps LLM inference off a remote server. mode is only read from the personal config, not from .inkentry/config.toml.

server_key

• Type: string, optional
• Default: unset
• Env override: INKENTRY_SERVER_KEY

Despite the name, this field only resolves the inkentry cloud bearer token, the one attached to hosted requests (INKENTRY_SERVER_KEY if set, otherwise the [auth].access_token written by inkentry login). It is not the credential for a self-hosted team inkentry-server: that bearer is resolved separately and keyed by the server's origin, so keys for two different self-hosted servers never collide or leak into one another.

A bare server_key left in your personal ~/.config/inkentry/config.toml is migrated into your OS keychain (macOS Keychain, Linux Secret Service, Windows Credential Manager) and stripped from the file the next time it loads. It is then migrated a second time, into the per-origin key store, the first time it is needed to authenticate a specific server.

To manage self-hosted server credentials, prefer the inkentry auth commands over hand-editing this field:

• inkentry auth set-key --server <url> stores a per-server key directly in the secret store (the key is read from stdin or an interactive prompt, never a flag, so it never lands in shell history or ps output).
• inkentry auth list-servers shows which server origins have a stored key; it never prints key material.
• INKENTRY_SERVER_KEY works everywhere, including CI, and always takes precedence over both the per-origin store and the inkentry login tokens.

Do not commit a server_key to .inkentry/config.toml: the project file does not accept this field at all (see Project config fields), so a line present there anyway is silently dropped and never resolves to a credential.

project_id

• Type: string, optional
• Default: unset (derived at runtime if absent)
• Env override: INKENTRY_PROJECT_ID

Human-readable project slug (or a raw UUID) used to route memory on a team inkentry-server. The value is sent to the server exactly as configured: there is no slug-to-UUID lookup and nothing is cached. Required when server_url points at a non-loopback address. If server_url is a loopback address, project_id may be omitted: inkentry derives a stable id from the project's git remote, or from a hash of the local path if there is no remote. Normally set in .inkentry/config.toml alongside server_url.

server_ca

• Type: path, optional
• Default: unset
• Env override: INKENTRY_SERVER_CA

Path to a PEM CA bundle to trust in addition to the built-in roots, for a team server_url presenting a certificate signed by a self-signed or internal CA. Verification stays on: this only adds a trust anchor, it does not disable checks. Valid in either config file. See trusting the server's certificate for the full walkthrough.

[auth]

• Type: table, optional
• Default: absent
• Managed by: inkentry login, inkentry org switch - do not hand-edit

WorkOS device-flow tokens for inkentry cloud, written by inkentry login under the global config's [auth] table:

[auth]
access_token = "..."
refresh_token = "..."
expires_at = 1234567890
org_id = "org_..."

While access_token is unexpired, it is the source of the Authorization: Bearer token every inkentry cloud request sends; it does not apply to a self-hosted server_url, which resolves its own credential separately (see server_key above). refresh_token rotates an expired access token and backs organization switching. A partial table is tolerated: a missing access_token reads as not-logged-in, a missing expires_at as expired, a missing org_id as no scoping. The file is written with 0600 permissions. This table is not read from .inkentry/config.toml.

[index]

• Type: table
• Default: use_default_excludes = true, detect_generated = true, exclude = []

Controls the built-in index-time file filter that skips generated, vendored, and machine-data files. Distinct from the unconditional sensitive-file exclusion (.env, key files), which is not configurable.

[index]
exclude = ["vendor/**", "!vendor/README.md"]
use_default_excludes = true
detect_generated = true

• exclude - extra gitignore-syntax lines layered on top of the built-in defaults. A !pattern line re-includes a path the defaults would otherwise drop (last match wins). Cannot re-include a sensitive file.
• use_default_excludes - whether to apply the built-in default exclude set at all.
• detect_generated - whether to skip files whose header self-declares as generated (@generated, or // Code generated ... DO NOT EDIT.).

Also valid in .inkentry/config.toml, where it overrides the personal value per field: an absent key in the project table leaves the personal (or default) value in place.

Configuring the LLM endpoint

LLM-backed features (inkentry harvest, index summaries) run through the local inkentry-server, which the CLI starts against an OpenAI-compatible chat endpoint. Three values configure that endpoint, split between the config file and the environment:

The credential is deliberately not a config.toml field and is never read by config load: the CLI resolves it (env first, then the OS secret store written by inkentry auth set-key --llm) and hands it to the detached daemon out-of-band, so the daemon never opens the keychain itself. Two server-side tuning knobs also exist for the endpoint: INKENTRY_LLM_REASONING_EFFORT (default none) and INKENTRY_MAX_TOKENS (default 8192); both are read by inkentry-server, not by the CLI.

.inkentry/config.toml (project-level)

Safe to commit; contains no secrets by design. Only four keys are read from this file - server_url, project_id, server_ca, and [index] - anything else (including any personal field documented above) is silently ignored.

# .inkentry/config.toml
server_url = "https://inkentry.internal.example.com"
project_id = "my-awesome-app"
server_ca = "/etc/inkentry/internal-ca.pem"

[index]
exclude = ["fixtures/**"]

server_key is deliberately not accepted here. A credential in a committed file stays in the repo's history forever and is readable by anyone with repo access, so the project config has no field for it at all: a stray server_key line is silently dropped, and the file's other keys still load normally. Use inkentry auth set-key --server <url> (or INKENTRY_SERVER_KEY in CI) to set a shared team credential per developer instead.

~/.config/inkentry/config.toml (personal)

# ~/.config/inkentry/config.toml

# Enable inkentry harvest / index summaries (set the credential with
# `inkentry auth set-key --llm`, not here)
llm_url = "http://127.0.0.1:1234"
llm_model = "google/gemma-3n-e4b"
llm_context_length = 8192

# Keep memory close to commits (default)
store_in_git_notes = true

Written for you by inkentry login (the [auth] table) and by the one-time server_key migration; you don't normally hand-edit either.

Removed fields

These keys were removed pre-1.0. If your config still has them, they parse without error but do nothing:

inference_url is not a config key at all: it is populated at runtime only, when inkentry auto-discovers a loopback server, and is never read from either TOML file.

Environment variable overrides

What's next

• Server setup - server_url / server_key in a team deployment
• Memory guide - store_in_git_notes and memory backends
• CLI reference - -c, --config and per-command overrides