Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs(config): map every toml key into template and properties doc

Igor Sant'Ana6276898ad211
diff --git a/AGENTS.md b/AGENTS.md
index d504af9f..6c12ba45 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -788,11 +788,14 @@ Additional boundary rules:
dormant. A PR's base branch follows its semver bucket: fixes → `main`,
features → `release/X.Y`.
- Keep `CLAUDE.md` as a pointer to this file.
+- **A new config key is documented in the same change, in two places.** Any key ai-memory accepts from `config.toml` (a `Config` field or a settings struct, whichever crate owns it) lands with (1) a commented entry in `crates/ai-memory-cli/templates/config.default.toml`, following the template's grammar (top-level keys above the first table, indented examples for credential or Option-typed keys, `[auth]` last; the two `the_shipped_default_config*` tests must pass), and (2) a row in `docs/config-properties.md`: key, default, env equivalent, one-line purpose. Env-only settings stay out of both; the `[auth]` keys `ai-memory init` appends itself stay out of the template and appear in `docs/config-properties.md` marked as init-managed. A config change that skips either file is incomplete.
## Documentation map
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — operational map: data
flow, crate breakdown, schema, invariants, config reference.
+- [`docs/config-properties.md`](docs/config-properties.md) — every TOML key
+ with its default, env equivalent, and a one-line purpose.
- [`docs/design-decisions.md`](docs/design-decisions.md) — full v1 spec
and milestone plan.
- [`docs/install.md`](docs/install.md) — installation cookbook for every
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e65cba04..f1b570ab 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,24 @@ version in [`docs/changelog/`](docs/changelog/):
## [Unreleased]
+### Changed
+
+- Documented the settings that `config.default.toml` had left out, and added
+ `docs/config-properties.md`, a reference table of every key `config.toml`
+ accepts with its default, environment variable and purpose. The template now
+ describes the `llm_*` keys (including `llm_compat_strict` and
+ `[[llm_fallbacks]]`), the embedding endpoint and prefix keys,
+ `tcp_keepalive_secs`, `base_path`, `release_base_url`, `cors_allow_origins`,
+ `consolidate_on_session_end`, `backfill_on_start`, `run_autowire`,
+ `claude_true_yolo`, the `contradiction_band_*` keys, and the `[run]`,
+ `[hook_spool]`, `[handoff]`, `[maintenance]`, `[dream]`, `[retrieval]`,
+ `[search.fts]`, `[profile]` and `[[admission_webhooks]]` sections. It also
+ lists the remaining keys of `[decay]` (including `[decay.half_life_days]`),
+ `[consolidation]`, `[auto_improve]`, `[auto_scope]` and `[auth]`, and the
+ `[auto_improve.scheduler.experience_entropy_filter]` table. The new entries
+ are all commented examples, and keys with a built-in default show that
+ default. `AGENTS.md` now requires a new config key to land in both files.
+
### Fixed
- Refused empty and whitespace-only `--workspace` and `--project` flags at the
@@ -29,6 +47,7 @@ version in [`docs/changelog/`](docs/changelog/):
`agent_id`, which the router treats like an OpenCode child session.
`drop_subagent_captures` now covers OMP subagents too, and an advisor's tool
calls stay with the session they advise (#1779).
+ a492ec23 (docs(config): map every toml key into template and properties doc)
## [3.2.9] - 2026-10-27
diff --git a/crates/ai-memory-cli/templates/config.default.toml b/crates/ai-memory-cli/templates/config.default.toml
index f684a6f2..5832dec2 100644
--- a/crates/ai-memory-cli/templates/config.default.toml
+++ b/crates/ai-memory-cli/templates/config.default.toml
@@ -28,9 +28,35 @@ bind = "127.0.0.1:49374"
# `AI_MEMORY_ALLOWED_HOSTS=homelab,192.168.0.90,localhost,127.0.0.1`.
allowed_hosts = ["localhost", "127.0.0.1", "::1"]
+# Origins allowed to make cross-origin requests to `/api/v1`. Empty (the
+# default) means same-origin only; serving a SPA through `--web-ui-dir` avoids
+# needing CORS at all. When non-empty, the CORS layer is attached to `/api/v1`
+# only, never to `/mcp`, `/hook`, `/admin` or `/web`. Each entry needs a scheme
+# and `*` is rejected. Env equivalent: `AI_MEMORY_CORS_ALLOW_ORIGINS=a,b,c`.
+# cors_allow_origins = []
+
# Default tracing filter (overridable by RUST_LOG).
log_level = "info"
+# Seconds an accepted `serve` connection sits idle before the OS starts TCP
+# keepalive probes. A hook client's peer can die without sending FIN (laptop
+# sleep, a VPN flap, a killed process); without keepalive that socket stays open
+# and leaks one file descriptor until `accept()` fails. 0 disables keepalive.
+# Env equivalent: `AI_MEMORY_TCP_KEEPALIVE_SECS`.
+# tcp_keepalive_secs = 60
+
+# URL subpath the server is mounted under when a reverse proxy serves it below
+# the root (for example `/wiki`). Thin-client commands prepend it to every
+# `/admin/*` request. Empty for a root-mounted server. `serve` reads the same
+# value from `AI_MEMORY_BASE_PATH` to nest its router.
+# base_path = ""
+
+# Releases URL that `ai-memory upgrade` downloads the archive and its `.sha256`
+# from. Unset uses https://github.com/akitaonrails/ai-memory/releases. Set it
+# for a mirror or a hermetic test. Env equivalent:
+# `AI_MEMORY_RELEASE_BASE_URL`.
+# release_base_url = "https://mirror.example/ai-memory/releases"
+
# Optional server-side hook ingest limiter for shared/remote installs. The rate
# is tokens per second per actor/session source; 0 or unset disables it. Burst
# defaults to the rate (minimum one token when enabled). Env equivalents:
@@ -76,6 +102,108 @@ log_level = "info"
# queries keep local order. Env equivalent: `AI_MEMORY_RERANKER=llm`.
# reranker = "llm"
+# --- LLM provider (consolidation, auto-improve, reranker) -----------------
+# Unset = zero-LLM: session pages are written heuristically and search needs no
+# provider. Setting a provider turns on the LLM features that need one. Each key
+# has an `AI_MEMORY_` environment equivalent (`AI_MEMORY_LLM_PROVIDER`, ...).
+# llm_provider = "anthropic" # or openai | gemini | openai-compat |
+# # openai-oauth | anthropic-oauth | codex |
+# # copilot | opencode | cursor
+# llm_model = "..." # provider-specific model override
+# llm_base_url = "..." # endpoint override; required for openai-compat
+
+# Send `response_format=json_schema` (strict) to the `openai-compat` provider.
+# On by default because every structured call supplies its own schema. Turn it
+# off for an endpoint that rejects the field. Env equivalent:
+# `AI_MEMORY_LLM_COMPAT_STRICT=false`.
+# llm_compat_strict = true
+
+# openai-compat only: send `chat_template_kwargs: {"enable_thinking": false}`
+# with every chat request. Thinking-capable local engines (vLLM or SGLang
+# serving a Qwen3-class model) otherwise spend the output budget on a reasoning
+# pass and can truncate the structured payload mid-JSON. Other providers ignore
+# it. Off by default. Env equivalent: `AI_MEMORY_LLM_COMPAT_DISABLE_THINKING`.
+# llm_compat_disable_thinking = false
+
+# Per-request timeout in seconds for every chat completion and for the Copilot
+# token exchange. The openai-oauth token refresh keeps its own built-in ceiling.
+# The default tolerates a local engine cold-loading a large model. Raise it for
+# a hosted gateway whose long completions run past it (seen on free aggregator
+# tiers). Env equivalent: `AI_MEMORY_LLM_TIMEOUT_SECS`.
+# llm_timeout_secs = 300
+
+# Reasoning effort sent to the provider. Unset leaves the model default. Values:
+# none, minimal, low, medium, high, xhigh, max, ultra, persistent. Each provider
+# maps the value to its own request field. Env equivalent:
+# `AI_MEMORY_LLM_REASONING_EFFORT`.
+# llm_reasoning_effort = "medium"
+
+# Extra HTTP headers attached to every LLM chat request, as `Name: Value` or
+# `Name=Value` entries. Empty by default. Use it for a gateway that wants a
+# caller-identifying header; OpenCode asks for `x-opencode-session` and a
+# specific `User-Agent`. Headers ai-memory sets itself (`authorization`,
+# `content-type`, `x-api-key`, ...) are refused at startup. Values are never
+# logged. Env equivalent: `AI_MEMORY_LLM_HEADERS`, set as an array such as
+# `["name=value","name2=value2"]`. A plain comma separated string is rejected.
+# llm_headers = []
+
+# Ordered fallback chain, tried after the primary provider only when a call
+# fails transiently. Empty by default. Each entry needs `provider` and `model`;
+# `base_url` is required for openai-compat. `api_key_env` names the environment
+# variable holding that entry's key. Every provider without a native credential
+# source (OpenAI OAuth, Copilot) must set it, and it is never inherited from the
+# primary provider. A missing provider or model, or an unknown provider, fails
+# config load. A named variable that is unset fails when the server builds the
+# LLM chain. There is no environment shorthand. See docs/llm-provider-fallback.md.
+# [[llm_fallbacks]]
+# provider = "openai-compat"
+# model = "poolside/laguna-s-2.1-free"
+# base_url = "http://127.0.0.1:49375/v1"
+# api_key_env = "AI_MEMORY_LOCAL_ROUTER_TOKEN"
+
+# Run LLM consolidation on SessionEnd as well as writing the heuristic session
+# page, when an LLM provider is configured. Off by default. The provider call is
+# queued after the session page and handoff are written, then handled outside
+# the hook response by one bounded retrying worker. Without this key the LLM
+# checkpoint runs on PreCompact and through manual `memory_consolidate`. Env
+# equivalent: `AI_MEMORY_CONSOLIDATE_ON_SESSION_END=true`.
+# consolidate_on_session_end = false
+
+# When a project's store is empty, the SessionStart hook imports that project's
+# existing local harness session history once, so installing hooks mid-project
+# does not start from nothing. The import is read-only on the local side,
+# sanitized like live capture, and only ever runs against an empty project.
+# On by default; `ai-memory backfill` runs it by hand. Env equivalent:
+# `AI_MEMORY_BACKFILL_ON_START=false`.
+# backfill_on_start = true
+
+# The first `ai-memory run <harness>` launch per harness, binary version and
+# config home installs that harness's lifecycle hooks and MCP server when they
+# are missing. On by default. Turn it off here, with
+# `AI_MEMORY_RUN_AUTOWIRE=false`, or for one launch with
+# `ai-memory run --no-autowire`.
+# run_autowire = true
+
+# When true, `ai-memory run --yolo` on Claude also injects `--settings` that
+# force `bypassPermissions` over any `defaultMode` in the user's settings. A
+# launch without `--yolo` never bypasses permissions, and Claude Code still
+# enforces the user's own `ask` rules. No effect on other harnesses. Off by
+# default; best paired with ai-jail (docs/design-yolo-safety-ai-jail.md). Env
+# equivalent: `AI_MEMORY_CLAUDE_TRUE_YOLO=true`. `ai-memory run --true-yolo`
+# requests it for one launch.
+# claude_true_yolo = false
+
+# Cosine-similarity band `memory_lint` uses to flag two cold pages as a likely
+# contradiction: same topic without being a near-duplicate. Pages at or above
+# the min and below the max are flagged; at or above the max they count as
+# duplicates (cold-cluster dedup handles those). Unrelated pages in a
+# single-language or single-domain store can already sit above the default min,
+# which makes the band measure topic proximity; raise the min for such a store.
+# Must satisfy 0 <= min < max <= 1. Env equivalents:
+# `AI_MEMORY_CONTRADICTION_BAND_MIN` and `AI_MEMORY_CONTRADICTION_BAND_MAX`.
+# contradiction_band_min = 0.4
+# contradiction_band_max = 0.75
+
# M8 retention-sweep parameters.
#
# Formula:
@@ -129,10 +257,30 @@ log_level = "info"
# enables on the next start), and existing pages are backfilled
# automatically at startup. See docs/local-embeddings.md.
# embedding_provider = "none" # opt out (FTS + entity + graph only)
-# embedding_provider = "openai" # or voyage | google | openai-compat
+# embedding_provider = "openai" # or voyage | google | gemini |
+# # openai-compat | local | copilot | none
# embedding_model = "..." # provider-specific override
# embedding_dim = 384 # must match the model
+# Embedding endpoint and text prefixes (`openai` and `openai-compat`
+# providers). `embedding_base_url` overrides the endpoint and is required for
+# `openai-compat`, which fails without it. `embedding_query_prefix` is
+# prepended to every query before it is embedded and
+# `embedding_document_prefix` to every page. Asymmetric models need
+# the pair their publisher specifies; base E5 models and
+# nvidia/Nemotron-3-Embed-1B-BF16 use "query: " and "passage: ". Instruction-
+# tuned E5 variants and Qwen3-Embedding want a task instruction on the query
+# side only, with exact spacing that differs per model (see
+# docs/llm-providers.md); leave the document prefix unset for them. Prefixes are
+# not trimmed, so a trailing space or newline is kept. Changing the query prefix
+# never needs a re-embed. The document prefix is part of the stored embedding
+# identity, so changing it is treated like a model change and stale rows are
+# picked up without `--force`. Env equivalents: `AI_MEMORY_EMBEDDING_BASE_URL`,
+# `AI_MEMORY_EMBEDDING_QUERY_PREFIX` and `AI_MEMORY_EMBEDDING_DOCUMENT_PREFIX`.
+# embedding_base_url = "..."
+# embedding_query_prefix = "query: "
+# embedding_document_prefix = "passage: "
+
# --- Session lifecycle (server-side) --------------------------------------
# [sessions] idle_end_after_hours = N (default 0 = off): the maintenance
# tick ends open sessions whose last activity is older than N hours
@@ -156,6 +304,30 @@ observation_retention_days = 0 # 0 = never prune raw observations
observation_prune_batch = 5000 # rows per prune transaction
ledger_retention_months = 0 # 0 = never delete hook event ledgers
+# Compact a cold episodic page instead of evicting it: keep its L0 abstract, an
+# L1 summary and the L2 keep-token set, and drop the prose. The full body stays
+# in git and in the supersession chain, so the change is reversible. Off by
+# default.
+# compact_cold_episodic = false
+#
+# Collapse near-duplicate cold episodic pages. The forget sweep clusters them by
+# embedding (cosine DBSCAN with an adaptive eps) and keeps one survivor per
+# cluster through supersession plus a merge note. Merged-away members stay
+# reachable and no generative LLM is called. Needs an embedder; without one it
+# does nothing. Off by default.
+# dedup_cold_clusters = false
+# dedup_min_pts = 0 # DBSCAN density floor; 0 uses 2
+# dedup_max_eps = 0.0 # ceiling on eps (cosine distance); 0.0 uses 0.15
+# # (similarity 0.85). Lower merges less.
+#
+# Per-tier half-lives in days. A tier that sets one decays at
+# lambda = ln(2) / days; a tier that leaves it unset keeps the scalar `lambda`,
+# so with none set every score matches the single-lambda behaviour. Each value
+# must be a finite number above zero. Tiers: working, episodic, semantic,
+# procedural.
+# [decay.half_life_days]
+# episodic = 180.0
+
# NOTE: commented example tables stay below the first real table, where the
# top-level keys have ended. A `[table]` header owns every key after it, so an
# example table uncommented above a top-level key would silently capture it.
@@ -267,6 +439,18 @@ per_user = false
[consolidation]
max_input_tokens = 100000
max_output_tokens = 32000
+#
+# Also send bounded literal excerpts of observations the normal projection
+# omitted or truncated. Off by default because it widens the captured text that
+# reaches the provider.
+# verbatim_residue = false
+#
+# Multiplier on the max_input_tokens budget, above 0 and at most 1.
+# max_input_tokens is a flat chars-per-token estimate, so it under-budgets denser
+# corpora: pt-BR text and source code tokenize at fewer characters per token
+# than English and can overshoot a provider's real input limit by about 40%.
+# Lower the margin for a corpus that is mostly non-English or code (#884).
+# input_token_safety_margin = 0.8
# Auto-improvement reviewer.
#
@@ -290,6 +474,35 @@ max_proposals_per_run = 5
include_raw_fallback = false
proposal_actor = "auto_improve"
pending_path = "_pending/auto-improve"
+#
+# Also schedule a reviewer run on SessionEnd. Off by default so hooks stay
+# cheap and fire-and-forget.
+# on_session_end = false
+#
+# Wiki folder prefixes whose page bodies the reviewer may read. A project that
+# keeps durable knowledge elsewhere (`decisions/`, `gotchas/`) can add those
+# folders so the reviewer stops proposing what is already written there (#834).
+# max_patchable_pages caps how many existing pages are included as context for
+# patch proposals, and max_patchable_body_chars caps the body rendered per page.
+# patchable_page_prefixes = ["_rules/", "procedures/"]
+# max_patchable_pages = 8
+# max_patchable_body_chars = 8000
+#
+# Size limits on patch proposals. Raise them only when validated proposals are
+# being rejected for size. max_final_body_chars is also capped at 32000 in
+# code, so a higher value has no effect; lower it to tighten the limit.
+# max_edits_per_proposal = 5
+# max_edit_content_chars = 4000
+# max_changed_chars_per_proposal = 12000
+# max_patch_edits_per_run = 8
+# max_final_body_chars = 32000
+# max_rule_page_tokens = 2000
+# max_procedure_page_tokens = 2000
+#
+# Recent rejection-buffer entries rendered into the review prompt, and how old
+# an entry may be, in days, to still be rendered.
+# max_rejection_context = 50
+# rejection_context_days = 180
# Optional executable evaluation gate for selected proposal targets. Disabled by
# default; operators supply the command and scoring policy. The command is run
@@ -317,6 +530,22 @@ interval_secs = 3600
max_sessions_per_tick = 1 # per project
min_session_age_secs = 600
+# Pre-filter for the experience pass (A4): skip session pages that carry little
+# information instead of sending them to consolidation. A skipped page is left
+# alone and never deleted. Off by default. A page is skipped as near-empty
+# below min_chars non-whitespace characters, as low entropy below
+# min_entropy_bits_per_char (Shannon entropy per character, finite and at least
+# 0), and as repetitive when 1 - distinct_tokens / total_tokens exceeds
+# max_repetition_ratio (0.0 to 1.0). The repetition check starts once a body
+# has repetition_min_tokens tokens, so a short terse note is never judged
+# repetitive.
+# [auto_improve.scheduler.experience_entropy_filter]
+# enabled = false
+# min_chars = 16
+# min_entropy_bits_per_char = 2.0
+# max_repetition_ratio = 0.7
+# repetition_min_tokens = 6
+
# How a mid-session event is attributed when the agent's cwd has moved since
# the session started. Session-CREATING events always resolve from their own
# cwd, and a `.ai-memory.toml` marker naming a project always wins in both
@@ -348,6 +577,181 @@ mid_session = "follow-cwd"
#
# [auto_scope]
# mode = "per_actor"
+#
+# Lifetime in seconds of an entry in the per_session and per_actor maps. 0 uses
+# the default of one hour. max_entries is a hard cap on the map size, evicting
+# the oldest insertions first; lower it on a very small install and raise it on
+# a shared server with many concurrent agents. Env equivalents:
+# `AI_MEMORY_AUTO_SCOPE__SESSION_TTL_SECS` and
+# `AI_MEMORY_AUTO_SCOPE__MAX_ENTRIES`.
+# session_ttl_secs = 3600
+# max_entries = 4096
+
+# Managed `ai-memory run` launches. require_server makes a launch fail when the
+# server is unreachable instead of continuing without one
+# (docs/managed-workstreams.md). Off by default. The `--require-server` flag
+# requests it for one launch, and `AI_MEMORY_RUN_REQUIRE_SERVER=true` for an
+# environment; the variable can only turn it on.
+# [run]
+# require_server = false
+
+# Client-side hook spool retry policy. max_attempts is the number of failed
+# drain passes before a spooled hook event is dropped. 0 disables the limit.
+# Env equivalent: `AI_MEMORY_HOOK_SPOOL_MAX_ATTEMPTS`.
+# [hook_spool]
+# max_attempts = 8
+
+# Session handoff delivery and creation. Both keys apply to every operator on
+# the server.
+#
+# claim_on_session_start true (the default) makes a SessionStart that finds a
+# pending handoff claim it automatically. False makes it render a notice with
+# the handoff id, `from_agent` and age, never the stored summary, and the agent
+# claims it with `memory_handoff_accept`. Set false so an unrelated next
+# session or a non-interactive launch cannot consume a handoff meant for
+# another session (#959).
+#
+# create_on_session_end true (the default) makes ending an unmanaged session
+# create an automatic open handoff. False still writes the session summary page
+# and queues consolidation but creates no handoff (#1043). Handoffs from
+# `memory_handoff_begin` and managed runs are unaffected.
+# [handoff]
+# claim_on_session_start = true
+# create_on_session_end = true
+
+# Scheduled server jobs. `enabled` is the master switch. The interval keys are
+# in seconds and 0 disables that job. The forget sweep and lint persist their
+# cadence across restarts, and overdue work starts after a bounded startup
+# delay. Embedding backfill is off by default because it may call a paid
+# provider.
+#
+# reconcile_tombstones_deleted_pages (#929, docs/okf.md) lets the watcher's 30s
+# reconcile pass tombstone an OKF-imported content page whose file was missing
+# on two consecutive passes. Session summary pages are excluded. A circuit
+# breaker skips a scope where more than max(3, 50%) of the candidate pages look
+# missing at once, or where a non-partial walk finds nothing, because that
+# points to an unmounted volume or a git checkout mid-walk. A tombstone stays
+# subject to the `hard_delete_after_days` sweep, but is never destroyed while
+# its chain has no successor, and a returning file re-links to the chain. Off by
+# default: deletions still need `ai-memory delete-page`.
+# [maintenance]
+# enabled = true
+# forget_sweep_interval_secs = 86400
+# lint_interval_secs = 86400
+# embedding_backfill_interval_secs = 0
+# reconcile_tombstones_deleted_pages = false
+
+# Opt-in LLM "dream" pass: rewrite and merge clusters of cold pages with the
+# configured provider. It runs only when `enabled` is true and both an LLM
+# provider and an embedder are configured. It starts after the operator has been
+# idle for idle_window_secs, cancels when activity returns, and never deletes a
+# source page. Off by default. In the numeric keys below, 0 selects the
+# built-in default named in the comment. Env equivalents:
+# `AI_MEMORY_DREAM__ENABLED=true` and `AI_MEMORY_DREAM__IDLE_WINDOW_SECS=600`.
+# [dream]
+# enabled = false
+# interval_secs = 3600 # how often the scheduler considers a run; 0 uses 3600
+# idle_window_secs = 0 # quiet seconds before a run starts; 0 uses 300
+# min_pts = 0 # DBSCAN density floor; 0 uses 2
+# max_eps = 0.0 # eps ceiling (cosine distance); 0.0 uses 0.15
+# max_clusters_per_run = 0 # clusters rewritten per run; 0 uses 8
+# min_cold_pages = 0 # cold pages needed before a run works; 0 uses 2
+
+# Ranking signals layered on the RRF fusion in `memory_query`. Only
+# observation_stream is on by default. With observation_stream off, the other
+# defaults leave ranking identical to a store that never had this section. Env
+# equivalents: `AI_MEMORY_RETRIEVAL__QUERY_INTENT=true`,
+# `AI_MEMORY_RETRIEVAL__ABSTRACT_VECTORS=true` and
+# `AI_MEMORY_RETRIEVAL__OBSERVATION_STREAM=false`.
+#
+# query_intent routes queries phrased as a search for a past session ("last
+# time", "yesterday", and the Chinese equivalents). Session pages normally pay a
+# kind and tier authority penalty in ranking, and while the routing fires they
+# do not. session_recall_bonus adds authority on top of that cancellation.
+#
+# abstract_vectors adds the L0 abstract-embedding stream to the fusion. A page
+# gets an abstract vector when its frontmatter carries `abstract:` and the
+# embedding backfill runs.
+#
+# belief_authority_weight folds a page's evidence-derived confidence into its
+# authority factor. 0.0 is inert and negative values are clamped to 0.
+#
+# observation_stream lets matching observation bodies vote, once per session,
+# for that session's latest `sessions/<id>.md` page in the same project. It
+# reads observations and writes nothing. False restores the previous ranking.
+# [retrieval]
+# query_intent = false
+# session_recall_bonus = 0.25
+# abstract_vectors = false
+# belief_authority_weight = 0.0
+# observation_stream = true
+
+# Words dropped from a bare natural-language FTS query before the terms are
+# OR-joined. Unset uses the built-in English list. `[]` turns the filter off. A
+# non-empty list replaces the built-in one. A wiki in another language should
+# list that language's function words: with only the English list, words such
+# as `de`, `que` and `em` reach BM25 scoring and skew it (#953). Matching folds
+# case but keeps diacritics, and it sees the characters as typed, so list every
+# spelling someone might type (Portuguese `e` and `é`). Entries are single words
+# of at most 64 characters, and the list holds at most 2000 entries. Env
+# equivalent: `AI_MEMORY_SEARCH_FTS_STOPWORDS=a,b,c`; a blank value is ignored.
+# [search.fts]
+# stopwords = ["e", "é", "de", "que", "em", "uma"]
+
+# Cross-project profile: how you usually work, delivered to every project as
+# defaults below the repository's rules file (docs/cross-project-profile.md).
+# Env equivalents have the form `AI_MEMORY_PROFILE__<KEY>`, for example
+# `AI_MEMORY_PROFILE__SHARE`.
+#
+# enabled is "auto" (the default), true or false. Auto turns the profile on for
+# a single-operator server and leaves it off for a multi-user one.
+#
+# share picks where the profile lives: "global" (one profile for the server, in
+# `default/_global`), "workspace" (one per workspace, in its `_profile`
+# project), "user" (one private profile per operator) or "off". The default,
+# "auto", means global on a single-operator server and user on a multi-user one.
+#
+# min_projects is the number of distinct projects a choice must appear in to
+# become an entry. inject_on_session_start delivers the digest at SessionStart.
+# digest_max_bytes caps that digest (clamped to 1500 through 12000) and
+# baseline_max_bytes caps it for a project with no pages yet (clamped to 2000
+# through 20000). apply_max_lines is the most lines `ai-memory profile apply`
+# writes into a rules file. llm lets the profile use the configured LLM
+# provider when there is one.
+# [profile]
+# enabled = "auto"
+# share = "auto"
+# min_projects = 2
+# inject_on_session_start = true
+# digest_max_bytes = 3000
+# baseline_max_bytes = 6000
+# apply_max_lines = 40
+# llm = true
+
+# Admission webhooks: synchronous HTTP hooks the server calls just before it
+# persists a page (docs/admission-webhooks.md). Empty by default, so no chain is
+# attached. name is a stable identifier used in loop-prevention skip lists and
+# log fields. url is the endpoint the payload is POSTed to. timeout_ms is the
+# per-request timeout (default 2000). failure_policy is what happens when the
+# webhook answers 4xx or 5xx or does not respond: "ignore" (the default) logs a
+# warning and continues with the unmodified page, "reject" aborts the write.
+# events is required and lists the operations the webhook subscribes to; an
+# empty list means it never fires. Values: write_page, consolidate, delete,
+# delete_event_ledger, purge_project, purge_session, purge_workspace,
+# move_project, move_session, handoff_begin, handoff_accept, handoff_cancel,
+# message_send, message_pop, message_cancel. blocking (default true) runs the
+# webhook inside the write path, where it can change the page and a rejection
+# aborts the write. With blocking = false the webhook is called after the page
+# lands, its response is ignored, and a slow or down mirror adds no latency to
+# writes. `AI_MEMORY_ADMISSION_WEBHOOKS_JSON` takes a JSON array of the same
+# fields and replaces the list from this file.
+# [[admission_webhooks]]
+# name = "contributors"
+# url = "http://contributors-webhook.memory.svc.cluster.local/enrich"
+# timeout_ms = 2000
+# failure_policy = "ignore"
+# blocking = true
+# events = ["write_page", "consolidate"]
# NOTE: `[auth]` must remain the LAST section in this template.
# `ai-memory init` appends further `[auth]` keys (token_pepper, root_username,
@@ -366,3 +770,15 @@ mid_session = "follow-cwd"
# resets the configured root_username via POST /auth/recovery.
[auth]
secure_cookie = false
+
+# Create new projects as `restricted`. The default is `open`, which admits every
+# authenticated user. A restricted project admits only its creator (granted
+# `write`) and root until someone grants others access. Existing projects keep
+# their access; restrict one with `ai-memory project access`. The reserved
+# `scratch` and global-preferences projects always stay open (#708).
+# new_projects_restricted = false
+
+# CIDRs allowed to supply `X-Forwarded-For` for login rate limiting. A bare
+# address counts as /32 or /128. The environment variable above takes a comma
+# separated list.
+# trusted_proxy_cidrs = ["10.0.0.0/8"]
diff --git a/docs/config-properties.md b/docs/config-properties.md
new file mode 100644
index 00000000..d8ff6576
--- /dev/null
+++ b/docs/config-properties.md
@@ -0,0 +1,319 @@
+# Configuration properties
+
+Every key ai-memory accepts in `config.toml`, one table per section. Each row gives the default as shipped in code, the environment variable that sets the same key, and a one-line purpose. For commented examples and longer explanations, read `crates/ai-memory-cli/templates/config.default.toml`, which `ai-memory init` writes into a new data directory.
+
+Environment variables use the prefix `AI_MEMORY_`. A top-level key `bind` is `AI_MEMORY_BIND`, and a key inside a section uses a double underscore, so `decay.lambda` is `AI_MEMORY_DECAY__LAMBDA`. A list is set from the environment as an array, for example `["a","b"]`. The keys `allowed_hosts`, `cors_allow_origins`, `ingest.drop_events` and `auth.trusted_proxy_cidrs` also accept a comma separated string. Where a key reads a different variable, the Env column names it. A dash in the Env column means the key has no environment form. Order of precedence: built-in defaults, then `config.toml`, then the environment, then command-line flags.
+
+Defaults that come from a named constant or from another crate say so in the Default cell. Settings that exist only as environment variables are not keys, so they are not listed.
+
+## Top-level keys
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `data_dir` | `<platform local data dir>/ai-memory` (`dirs::data_local_dir()`) | `AI_MEMORY_DATA_DIR`, or `--data-dir` | Root data directory holding `wiki/`, `raw/`, `db/`, `models/` and `logs/`. The config file lives inside it, so the flag or variable normally chooses it. |
+| `bind` | `127.0.0.1:49374` (`DEFAULT_BIND`) | `AI_MEMORY_BIND` | HTTP bind address used by `ai-memory serve`. |
+| `tcp_keepalive_secs` | `60` (`DEFAULT_TCP_KEEPALIVE_SECS`) | `AI_MEMORY_TCP_KEEPALIVE_SECS` | Idle seconds before TCP keepalive probes start on an accepted connection. 0 disables keepalive. |
+| `server_url` | Derived from `bind`; `http://127.0.0.1:49374` for the default bind (`DEFAULT_SERVER_URL`) | `AI_MEMORY_SERVER_URL` | Base URL thin-client commands use to reach the server. |
+| `release_base_url` | unset (the GitHub Releases page of `akitaonrails/ai-memory`) | `AI_MEMORY_RELEASE_BASE_URL` | Releases URL `ai-memory upgrade` downloads from, for mirrors and hermetic tests. |
+| `base_path` | empty | `AI_MEMORY_BASE_PATH` | URL subpath the server is mounted under, prepended by thin-client commands to `/admin/*` requests. |
+| `log_level` | `info` | `AI_MEMORY_LOG_LEVEL` | Default tracing filter. `RUST_LOG` overrides it. |
+| `allowed_hosts` | `["localhost", "127.0.0.1", "::1"]` | `AI_MEMORY_ALLOWED_HOSTS` | Host header allowlist for the HTTP server (DNS-rebinding defence). |
+| `cors_allow_origins` | `[]` | `AI_MEMORY_CORS_ALLOW_ORIGINS` | Origins allowed to make cross-origin requests to `/api/v1`. Empty means same-origin only. |
+| `hook_rate_per_sec` | `0.0` | `AI_MEMORY_HOOK_RATE_PER_SEC` | Hook ingest tokens per second per actor and session source. 0 disables the limiter. |
+| `hook_rate_burst` | `0.0` (falls back to the rate, minimum one token, when the limiter is on) | `AI_MEMORY_HOOK_RATE_BURST` | Burst size of the hook ingest limiter. |
+| `capture_assistant` | `false` | `AI_MEMORY_CAPTURE_ASSISTANT` | Server side half of the assistant turn capture opt-in on Claude Code `Stop` events. |
+| `consolidate_on_session_end` | `false` | `AI_MEMORY_CONSOLIDATE_ON_SESSION_END` | Queue LLM consolidation on SessionEnd when an LLM provider is configured. |
+| `backfill_on_start` | `true` | `AI_MEMORY_BACKFILL_ON_START` | Import a project's existing local harness history once, when SessionStart finds its store empty. |
+| `run_autowire` | `true` | `AI_MEMORY_RUN_AUTOWIRE` | Install a harness's hooks and MCP server on the first `ai-memory run` launch when they are missing. |
+| `claude_true_yolo` | `false` | `AI_MEMORY_CLAUDE_TRUE_YOLO` | Make `ai-memory run --yolo` on Claude force `bypassPermissions` over any settings `defaultMode`. |
+| `strip_root_combinators` | `false` | `AI_MEMORY_STRIP_ROOT_COMBINATORS` | Strip root level `anyOf`, `oneOf` and `allOf` from MCP tool input schemas on every `tools/list`. |
+| `gemini_safe_schemas` | `false` | `AI_MEMORY_GEMINI_SAFE_SCHEMAS` | Serve MCP tool schemas in the subset Vertex and Gemini accept. Implies `strip_root_combinators`. |
+| `reranker` | unset | `AI_MEMORY_RERANKER` | Post-fusion reranker for `memory_query`. The only value is `llm`, which needs an LLM provider. |
+| `llm_provider` | unset | `AI_MEMORY_LLM_PROVIDER` | LLM provider: `anthropic`, `openai`, `gemini`, `openai-compat`, `openai-oauth`, `anthropic-oauth`, `codex`, `copilot`, `opencode` or `cursor`. |
+| `llm_model` | unset | `AI_MEMORY_LLM_MODEL` | Model override for the LLM provider. |
+| `llm_base_url` | unset | `AI_MEMORY_LLM_BASE_URL` | Endpoint override for the LLM provider. Required for `openai-compat`. |
+| `llm_compat_strict` | `true` | `AI_MEMORY_LLM_COMPAT_STRICT` | Send `response_format=json_schema` (strict) to the `openai-compat` provider. |
+| `llm_compat_disable_thinking` | `false` | `AI_MEMORY_LLM_COMPAT_DISABLE_THINKING` | Send `chat_template_kwargs: {"enable_thinking": false}` on every `openai-compat` chat request. |
+| `llm_timeout_secs` | `300` (`ai_memory_llm::DEFAULT_REQUEST_TIMEOUT_SECS`) | `AI_MEMORY_LLM_TIMEOUT_SECS` | Per-request timeout for chat completions and the Copilot token exchange. The openai-oauth token refresh keeps its own ceiling. |
+| `llm_reasoning_effort` | unset (the model default applies) | `AI_MEMORY_LLM_REASONING_EFFORT` | Reasoning effort: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `ultra` or `persistent`. |
+| `llm_headers` | `[]` | `AI_MEMORY_LLM_HEADERS` | Extra HTTP headers on every LLM chat request, as `Name: Value` or `Name=Value` entries. |
+| `embedding_provider` | unset (in-process local embeddings) | `AI_MEMORY_EMBEDDING_PROVIDER` | Embedding provider: `none`, `openai`, `voyage`, `google` or `gemini`, or `openai-compat`. |
+| `embedding_model` | unset | `AI_MEMORY_EMBEDDING_MODEL` | Provider-specific embedding model override. |
+| `embedding_dim` | unset | `AI_MEMORY_EMBEDDING_DIM` | Embedding dimension override. It must match the model. |
+| `embedding_base_url` | unset | `AI_MEMORY_EMBEDDING_BASE_URL` | Embedding endpoint override. Required when `embedding_provider` is `openai-compat`. |
+| `embedding_query_prefix` | unset | `AI_MEMORY_EMBEDDING_QUERY_PREFIX` | Text prepended to every embedding query for the `openai` and `openai-compat` embedders. Kept verbatim. |
+| `embedding_document_prefix` | unset | `AI_MEMORY_EMBEDDING_DOCUMENT_PREFIX` | Text prepended to every page before embedding. Part of the stored embedding identity. |
+| `contradiction_band_min` | `0.4` (`DEFAULT_CONTRADICTION_SIM_LOW`) | `AI_MEMORY_CONTRADICTION_BAND_MIN` | Lower edge, inclusive, of the cosine band `memory_lint` uses to flag likely contradictions. |
+| `contradiction_band_max` | `0.75` (`DEFAULT_CONTRADICTION_SIM_HIGH`) | `AI_MEMORY_CONTRADICTION_BAND_MAX` | Upper edge, exclusive, of that band. At or above it, two pages count as near-duplicates. |
+
+## `[[llm_fallbacks]]`
+
+An array of tables. Each entry is tried in order after the primary provider, only when a call fails transiently. The default is an empty list. Config load rejects an entry with no provider or model. The list has no environment form.
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `provider` | empty (required) | - | Provider for this candidate, using the same names as `llm_provider`. |
+| `model` | empty (required) | - | Model id for this candidate. |
+| `base_url` | unset | - | Endpoint override for this candidate. Required for `openai-compat`. |
+| `api_key_env` | unset | - | Name of the environment variable holding this candidate's key. Required unless the provider has a native credential source. |
+
+## `[[admission_webhooks]]`
+
+An array of tables, defined by `WebhookConfig` in `ai-memory-wiki`. The default is an empty list, which attaches no chain.
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `name` | required | `AI_MEMORY_ADMISSION_WEBHOOKS_JSON` | Stable identifier used in loop-prevention skip lists and log fields. |
+| `url` | required | `AI_MEMORY_ADMISSION_WEBHOOKS_JSON` | HTTP endpoint the payload is POSTed to. |
+| `timeout_ms` | `2000` | `AI_MEMORY_ADMISSION_WEBHOOKS_JSON` | Per-request timeout in milliseconds. |
+| `failure_policy` | `ignore` | `AI_MEMORY_ADMISSION_WEBHOOKS_JSON` | `ignore` logs a warning and continues. `reject` aborts the write. |
+| `events` | required | `AI_MEMORY_ADMISSION_WEBHOOKS_JSON` | Operations the webhook subscribes to. An empty list means it never fires. |
+| `blocking` | `true` | `AI_MEMORY_ADMISSION_WEBHOOKS_JSON` | `true` runs inside the write path and can change the page. `false` fires after the page lands and ignores the response. |
+
+`AI_MEMORY_ADMISSION_WEBHOOKS_JSON` takes a JSON array of these entries and replaces the list from the file. Valid `events` are `write_page`, `consolidate`, `delete`, `delete_event_ledger`, `purge_project`, `purge_session`, `purge_workspace`, `move_project`, `move_session`, `handoff_begin`, `handoff_accept`, `handoff_cancel`, `message_send`, `message_pop` and `message_cancel`.
+
+## `[run]`
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `require_server` | `false` | `AI_MEMORY_RUN_REQUIRE_SERVER` | Fail a managed launch when the server is unreachable. The variable can only turn it on. |
+| `profiles.<name>.env` | none | - | Named table of string environment overrides, selected with `ai-memory run --profile <name>`. |
+
+Profile names use 1 to 64 ASCII letters, digits, `.`, `_` or `-`. A config holds at most 128 profiles, each with at most 128 entries. A key is at most 256 bytes and a value at most 64 KiB.
+
+## `[sessions]`
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `idle_end_after_hours` | `0` (off) | `AI_MEMORY_SESSIONS__IDLE_END_AFTER_HOURS` | Hours of silence after which the maintenance tick ends an open session that never got a SessionEnd. 0 or 1 to 8760. |
+
+## `[decay]`
+
+The defaults for `lambda` through `hard_delete_after_days` come from `ai_memory_store::DecayParams::default()`.
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `lambda` | `0.02` | `AI_MEMORY_DECAY__LAMBDA` | Per-day decay rate of page retention. |
+| `sigma` | `0.6` | `AI_MEMORY_DECAY__SIGMA` | Magnitude of the access reinforcement. |
+| `mu` | `0.04` | `AI_MEMORY_DECAY__MU` | Per-day decay of the access reinforcement. |
+| `salience_default` | `1.0` | `AI_MEMORY_DECAY__SALIENCE_DEFAULT` | Default page salience. |
+| `cold_threshold` | `0.20` | `AI_MEMORY_DECAY__COLD_THRESHOLD` | Retention score below which a page is evicted. |
+| `hard_delete_after_days` | `180` | `AI_MEMORY_DECAY__HARD_DELETE_AFTER_DAYS` | Grace period before an evicted version chain is deleted permanently. |
+| `breadth_weight` | `0.0` | `AI_MEMORY_DECAY__BREADTH_WEIGHT` | Weight for the number of distinct authenticated readers of a page. |
+| `observation_retention_days` | `0` (off) | `AI_MEMORY_DECAY__OBSERVATION_RETENTION_DAYS` | Age past which a consolidated session's raw observations may be pruned. Irreversible. |
+| `observation_prune_batch` | `5000` (`DEFAULT_OBSERVATION_PRUNE_BATCH`) | `AI_MEMORY_DECAY__OBSERVATION_PRUNE_BATCH` | Observation rows deleted per prune transaction. |
+| `ledger_retention_months` | `0` (off) | `AI_MEMORY_DECAY__LEDGER_RETENTION_MONTHS` | Whole UTC months after a month ends before the sweep deletes its `log-YYYY-MM.md` ledger. |
+| `compact_cold_episodic` | `false` | `AI_MEMORY_DECAY__COMPACT_COLD_EPISODIC` | Compact a cold episodic page to its abstract, summary and keep-token set instead of evicting it. |
+| `dedup_cold_clusters` | `false` | `AI_MEMORY_DECAY__DEDUP_COLD_CLUSTERS` | Collapse near-duplicate cold episodic pages to one survivor. Needs an embedder. |
+| `dedup_min_pts` | `0` (uses 2, `DEFAULT_DEDUP_MIN_PTS`) | `AI_MEMORY_DECAY__DEDUP_MIN_PTS` | DBSCAN density floor for the dedup pass. |
+| `dedup_max_eps` | `0.0` (uses 0.15, `DEFAULT_DEDUP_MAX_EPS`) | `AI_MEMORY_DECAY__DEDUP_MAX_EPS` | Ceiling on the adaptive eps, as cosine distance. Lower merges less. |
+
+## `[decay.half_life_days]`
+
+Per-tier half-lives in days. A tier that sets one decays at `ln(2) / days`. A tier that leaves it unset keeps `decay.lambda`. Each value must be finite and above zero.
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `working` | unset | `AI_MEMORY_DECAY__HALF_LIFE_DAYS__WORKING` | Half-life for `working` tier pages. |
+| `episodic` | unset | `AI_MEMORY_DECAY__HALF_LIFE_DAYS__EPISODIC` | Half-life for `episodic` tier pages. |
+| `semantic` | unset | `AI_MEMORY_DECAY__HALF_LIFE_DAYS__SEMANTIC` | Half-life for `semantic` tier pages. |
+| `procedural` | unset | `AI_MEMORY_DECAY__HALF_LIFE_DAYS__PROCEDURAL` | Half-life for `procedural` tier pages. |
+
+## `[maintenance]`
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `enabled` | `true` | `AI_MEMORY_MAINTENANCE__ENABLED` | Master switch for scheduled server jobs. |
+| `forget_sweep_interval_secs` | `86400` | `AI_MEMORY_MAINTENANCE__FORGET_SWEEP_INTERVAL_SECS` | Interval of the retention forget sweep. 0 disables the job. |
+| `lint_interval_secs` | `86400` | `AI_MEMORY_MAINTENANCE__LINT_INTERVAL_SECS` | Interval of rule-based wiki lint. 0 disables the job. |
+| `embedding_backfill_interval_secs` | `0` (off) | `AI_MEMORY_MAINTENANCE__EMBEDDING_BACKFILL_INTERVAL_SECS` | Interval of embedding backfill. Off by default because it may call a paid provider. |
+| `reconcile_tombstones_deleted_pages` | `false` | `AI_MEMORY_MAINTENANCE__RECONCILE_TOMBSTONES_DELETED_PAGES` | Let the watcher tombstone an OKF-imported page whose file stayed missing on two consecutive passes. |
+
+## `[dream]`
+
+A zero in a numeric key selects the built-in default named in the Default cell.
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `enabled` | `false` | `AI_MEMORY_DREAM__ENABLED` | Master switch for the LLM pass that rewrites and merges clusters of cold pages. |
+| `interval_secs` | `3600` | `AI_MEMORY_DREAM__INTERVAL_SECS` | How often the scheduler considers a run. 0 uses 3600. |
+| `idle_window_secs` | `0` (uses 300, `DEFAULT_DREAM_IDLE_WINDOW_SECS`) | `AI_MEMORY_DREAM__IDLE_WINDOW_SECS` | Quiet seconds required before a run starts, and after which returning activity cancels it. |
+| `min_pts` | `0` (uses 2, `DEFAULT_DEDUP_MIN_PTS`) | `AI_MEMORY_DREAM__MIN_PTS` | DBSCAN density floor. |
+| `max_eps` | `0.0` (uses 0.15, `DEFAULT_DEDUP_MAX_EPS`) | `AI_MEMORY_DREAM__MAX_EPS` | Ceiling on eps, as cosine distance. Lower merges less. |
+| `max_clusters_per_run` | `0` (uses 8, `DEFAULT_DREAM_MAX_CLUSTERS_PER_RUN`) | `AI_MEMORY_DREAM__MAX_CLUSTERS_PER_RUN` | Clusters rewritten in one run. |
+| `min_cold_pages` | `0` (uses 2, `DEFAULT_DREAM_MIN_COLD_PAGES`) | `AI_MEMORY_DREAM__MIN_COLD_PAGES` | Cold pages needed before a run does work. |
+
+## `[retrieval]`
+
+The defaults come from `ai_memory_store::RetrievalTuning::default()`.
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `query_intent` | `false` | `AI_MEMORY_RETRIEVAL__QUERY_INTENT` | Route queries that ask for a past session so session pages skip the kind and tier authority penalty they normally pay. |
+| `session_recall_bonus` | `0.25` | `AI_MEMORY_RETRIEVAL__SESSION_RECALL_BONUS` | Extra authority for session pages when the routing fires, on top of cancelling that penalty. |
+| `abstract_vectors` | `false` | `AI_MEMORY_RETRIEVAL__ABSTRACT_VECTORS` | Add the L0 abstract embedding stream to the rank fusion. |
+| `belief_authority_weight` | `0.0` | `AI_MEMORY_RETRIEVAL__BELIEF_AUTHORITY_WEIGHT` | Weight of a page's evidence-derived confidence in its authority. 0 is inert and negatives clamp to 0. |
+| `observation_stream` | `true` | `AI_MEMORY_RETRIEVAL__OBSERVATION_STREAM` | Add the observation evidence stream, where matching observation bodies vote for their session's page. |
+
+## `[search.fts]`
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `stopwords` | unset (the built-in English list) | `AI_MEMORY_SEARCH_FTS_STOPWORDS` (comma separated, blank ignored) | Words dropped from a bare natural-language query. `[]` turns the filter off. A list replaces the built-in one. |
+
+## `[slots]`
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `per_user` | `false` | `AI_MEMORY_SLOTS__PER_USER` | Namespace engine-written slots under the operator who produced them and inject only shared plus own slots. |
+
+## `[consolidation]`
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `verbatim_residue` | `false` | `AI_MEMORY_CONSOLIDATION__VERBATIM_RESIDUE` | Add bounded literal excerpts of observations the normal projection omitted or truncated. |
+| `max_input_tokens` | `100000` (`DEFAULT_CONSOLIDATION_MAX_INPUT_TOKENS`) | `AI_MEMORY_CONSOLIDATION__MAX_INPUT_TOKENS` | Approximate token target for the whole consolidation prompt. |
+| `max_output_tokens` | `32000` (`DEFAULT_CONSOLIDATION_MAX_OUTPUT_TOKENS`) | `AI_MEMORY_CONSOLIDATION__MAX_OUTPUT_TOKENS` | Maximum tokens the provider may generate for one consolidation response. |
+| `input_token_safety_margin` | `0.8` (`DEFAULT_CONSOLIDATION_INPUT_TOKEN_SAFETY_MARGIN`) | `AI_MEMORY_CONSOLIDATION__INPUT_TOKEN_SAFETY_MARGIN` | Multiplier on the input budget, above 0 and at most 1. |
+
+## `[auto_improve]`
+
+The defaults named `DEFAULT_AUTO_IMPROVE_*` are constants in `ai-memory-consolidate`.
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `require_approval` | `false` | `AI_MEMORY_AUTO_IMPROVE__REQUIRE_APPROVAL` | Keep proposals pending until an admin approves them. |
+| `on_session_end` | `false` | `AI_MEMORY_AUTO_IMPROVE__ON_SESSION_END` | Schedule a reviewer run on SessionEnd. |
+| `min_observations` | `8` (`DEFAULT_AUTO_IMPROVE_MIN_OBSERVATIONS`) | `AI_MEMORY_AUTO_IMPROVE__MIN_OBSERVATIONS` | Observations a session needs before it is reviewed. |
+| `min_session_duration_secs` | `120` (`DEFAULT_AUTO_IMPROVE_MIN_SESSION_DURATION_SECS`) | `AI_MEMORY_AUTO_IMPROVE__MIN_SESSION_DURATION_SECS` | Minimum span between first and last observation before review. |
+| `min_confidence` | `0.75` (`DEFAULT_AUTO_IMPROVE_MIN_CONFIDENCE`) | `AI_MEMORY_AUTO_IMPROVE__MIN_CONFIDENCE` | Lowest model confidence validation accepts. |
+| `max_input_tokens` | `24000` (`DEFAULT_AUTO_IMPROVE_MAX_INPUT_TOKENS`) | `AI_MEMORY_AUTO_IMPROVE__MAX_INPUT_TOKENS` | Approximate prompt budget for one review. |
+| `max_proposals_per_run` | `5` (`DEFAULT_AUTO_IMPROVE_MAX_PROPOSALS`) | `AI_MEMORY_AUTO_IMPROVE__MAX_PROPOSALS_PER_RUN` | Validated proposals returned from one run. |
+| `max_patchable_pages` | `8` (`DEFAULT_AUTO_IMPROVE_MAX_PATCHABLE_PAGES`) | `AI_MEMORY_AUTO_IMPROVE__MAX_PATCHABLE_PAGES` | Existing pages included as context for patch proposals. |
+| `patchable_page_prefixes` | `["_rules/", "procedures/"]` (`DEFAULT_AUTO_IMPROVE_PATCHABLE_PAGE_PREFIXES`) | `AI_MEMORY_AUTO_IMPROVE__PATCHABLE_PAGE_PREFIXES` | Wiki folder prefixes whose page bodies the reviewer may read. |
+| `max_patchable_body_chars` | `8000` (`DEFAULT_AUTO_IMPROVE_MAX_PATCHABLE_BODY_CHARS`) | `AI_MEMORY_AUTO_IMPROVE__MAX_PATCHABLE_BODY_CHARS` | Body characters rendered per patchable page. |
+| `max_edits_per_proposal` | `5` (`DEFAULT_AUTO_IMPROVE_MAX_EDITS_PER_PROPOSAL`) | `AI_MEMORY_AUTO_IMPROVE__MAX_EDITS_PER_PROPOSAL` | Patch edits in one proposal. |
+| `max_edit_content_chars` | `4000` (`DEFAULT_AUTO_IMPROVE_MAX_EDIT_CONTENT_CHARS`) | `AI_MEMORY_AUTO_IMPROVE__MAX_EDIT_CONTENT_CHARS` | Content characters in one patch edit. |
+| `max_changed_chars_per_proposal` | `12000` (`DEFAULT_AUTO_IMPROVE_MAX_CHANGED_CHARS_PER_PROPOSAL`) | `AI_MEMORY_AUTO_IMPROVE__MAX_CHANGED_CHARS_PER_PROPOSAL` | Aggregate changed characters in one patch proposal. |
+| `max_patch_edits_per_run` | `8` (`DEFAULT_AUTO_IMPROVE_MAX_PATCH_EDITS_PER_RUN`) | `AI_MEMORY_AUTO_IMPROVE__MAX_PATCH_EDITS_PER_RUN` | Patch edits accepted across one review run. |
+| `max_rejection_context` | `50` (`DEFAULT_AUTO_IMPROVE_MAX_REJECTION_CONTEXT`) | `AI_MEMORY_AUTO_IMPROVE__MAX_REJECTION_CONTEXT` | Recent rejection-buffer entries rendered into the prompt. |
+| `rejection_context_days` | `180` (`DEFAULT_AUTO_IMPROVE_REJECTION_CONTEXT_DAYS`) | `AI_MEMORY_AUTO_IMPROVE__REJECTION_CONTEXT_DAYS` | Maximum age in days of a rejection-buffer entry in the prompt. |
+| `max_final_body_chars` | `32000` (`DEFAULT_AUTO_IMPROVE_MAX_FINAL_BODY_CHARS`) | `AI_MEMORY_AUTO_IMPROVE__MAX_FINAL_BODY_CHARS` | Largest materialized body a proposal may produce. Code caps it at 32000, so a higher value has no effect. |
+| `max_rule_page_tokens` | `2000` (`DEFAULT_AUTO_IMPROVE_MAX_RULE_PAGE_TOKENS`) | `AI_MEMORY_AUTO_IMPROVE__MAX_RULE_PAGE_TOKENS` | Approximate tokens allowed in one `_rules/` page. |
+| `max_procedure_page_tokens` | `2000` (`DEFAULT_AUTO_IMPROVE_MAX_PROCEDURE_PAGE_TOKENS`) | `AI_MEMORY_AUTO_IMPROVE__MAX_PROCEDURE_PAGE_TOKENS` | Approximate tokens allowed in one `procedures/` page. |
+| `include_raw_fallback` | `false` | `AI_MEMORY_AUTO_IMPROVE__INCLUDE_RAW_FALLBACK` | Let the reviewer include raw observation fallback details. |
+| `proposal_actor` | `auto_improve` (`DEFAULT_AUTO_IMPROVE_PROPOSAL_ACTOR`) | `AI_MEMORY_AUTO_IMPROVE__PROPOSAL_ACTOR` | Synthetic actor recorded as the author of autonomous proposals. |
+| `pending_path` | `_pending/auto-improve` (`DEFAULT_AUTO_IMPROVE_PENDING_PATH`) | `AI_MEMORY_AUTO_IMPROVE__PENDING_PATH` | Wiki-relative folder for non-indexed pending proposal files. |
+
+## `[auto_improve.eval]`
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `enabled` | `false` | `AI_MEMORY_AUTO_IMPROVE__EVAL__ENABLED` | Turn on the external eval command gate. |
+| `command` | empty | `AI_MEMORY_AUTO_IMPROVE__EVAL__COMMAND` | Executable plus whitespace-separated arguments, run directly without a shell. |
+| `timeout_secs` | `120` | `AI_MEMORY_AUTO_IMPROVE__EVAL__TIMEOUT_SECS` | Timeout per proposal eval command. |
+| `targets` | `["_rules", "procedures"]` (`default_auto_improve_eval_targets`) | `AI_MEMORY_AUTO_IMPROVE__EVAL__TARGETS` | Wiki path prefixes that require the eval when it is enabled. |
+| `min_delta` | `0.0` | `AI_MEMORY_AUTO_IMPROVE__EVAL__MIN_DELTA` | Required `score_after` minus `score_before` when scores are present. |
+
+## `[auto_improve.scheduler]`
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `enabled` | `true` | `AI_MEMORY_AUTO_IMPROVE__SCHEDULER__ENABLED` | Review newly completed sessions in the background. |
+| `interval_secs` | `3600` | `AI_MEMORY_AUTO_IMPROVE__SCHEDULER__INTERVAL_SECS` | Scheduler cadence. 0 disables the scheduler and keeps manual runs. |
+| `max_sessions_per_tick` | `1` | `AI_MEMORY_AUTO_IMPROVE__SCHEDULER__MAX_SESSIONS_PER_TICK` | Sessions reviewed per project in one tick. 0 disables the scheduler. |
+| `min_session_age_secs` | `600` | `AI_MEMORY_AUTO_IMPROVE__SCHEDULER__MIN_SESSION_AGE_SECS` | Minimum age after SessionEnd before a session is eligible. |
+| `experience_every_sessions` | `0` (off) | `AI_MEMORY_AUTO_IMPROVE__SCHEDULER__EXPERIENCE_EVERY_SESSIONS` | Run the cross-session experience pass after this many new completed sessions per project. |
+| `experience_sessions` | `10` | `AI_MEMORY_AUTO_IMPROVE__SCHEDULER__EXPERIENCE_SESSIONS` | Recent session summary pages one experience pass reads. |
+
+## `[auto_improve.scheduler.experience_entropy_filter]`
+
+Defined by `EntropyFilterConfig` in `ai-memory-consolidate`. A skipped page is left alone and never deleted.
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `enabled` | `false` | `AI_MEMORY_AUTO_IMPROVE__SCHEDULER__EXPERIENCE_ENTROPY_FILTER__ENABLED` | Skip low-information session pages in the experience pass. |
+| `min_chars` | `16` | `AI_MEMORY_AUTO_IMPROVE__SCHEDULER__EXPERIENCE_ENTROPY_FILTER__MIN_CHARS` | Minimum non-whitespace characters. Shorter text is skipped as near-empty. |
+| `min_entropy_bits_per_char` | `2.0` | `AI_MEMORY_AUTO_IMPROVE__SCHEDULER__EXPERIENCE_ENTROPY_FILTER__MIN_ENTROPY_BITS_PER_CHAR` | Minimum Shannon entropy per character. Finite and at least 0. |
+| `max_repetition_ratio` | `0.7` | `AI_MEMORY_AUTO_IMPROVE__SCHEDULER__EXPERIENCE_ENTROPY_FILTER__MAX_REPETITION_RATIO` | Repetition ratio (`1 - distinct_tokens / total_tokens`) above which text is skipped. 0.0 to 1.0. |
+| `repetition_min_tokens` | `6` | `AI_MEMORY_AUTO_IMPROVE__SCHEDULER__EXPERIENCE_ENTROPY_FILTER__REPETITION_MIN_TOKENS` | Token count a body needs before the repetition check applies. |
+
+## `[handoff]`
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `claim_on_session_start` | `true` | `AI_MEMORY_HANDOFF__CLAIM_ON_SESSION_START` | Claim a pending handoff automatically at SessionStart. `false` renders a notice and waits for `memory_handoff_accept`. |
+| `create_on_session_end` | `true` | `AI_MEMORY_HANDOFF__CREATE_ON_SESSION_END` | Create an automatic open handoff when an unmanaged session ends. |
+
+## `[profile]`
+
+Defined by `ProfileSettings` in `ai-memory-core`.
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `enabled` | `auto` | `AI_MEMORY_PROFILE__ENABLED` | `auto`, `true` or `false`. Auto turns the profile on for a single-operator server and off for a multi-user one. |
+| `share` | `auto` | `AI_MEMORY_PROFILE__SHARE` | Where the profile lives: `auto`, `global`, `workspace`, `user` or `off`. |
+| `min_projects` | `2` (`DEFAULT_MIN_PROJECTS`) | `AI_MEMORY_PROFILE__MIN_PROJECTS` | Distinct projects a choice must appear in to become an entry. |
+| `inject_on_session_start` | `true` | `AI_MEMORY_PROFILE__INJECT_ON_SESSION_START` | Deliver the profile digest at SessionStart. |
+| `digest_max_bytes` | `3000` (`DEFAULT_DIGEST_MAX_BYTES`) | `AI_MEMORY_PROFILE__DIGEST_MAX_BYTES` | Digest budget in UTF-8 bytes, clamped to 1500 through 12000. |
+| `baseline_max_bytes` | `6000` (`DEFAULT_BASELINE_MAX_BYTES`) | `AI_MEMORY_PROFILE__BASELINE_MAX_BYTES` | Digest budget for a project with no pages yet, clamped to 2000 through 20000. |
+| `apply_max_lines` | `40` (`DEFAULT_APPLY_MAX_LINES`) | `AI_MEMORY_PROFILE__APPLY_MAX_LINES` | Most lines `ai-memory profile apply` writes into a rules file. |
+| `llm` | `true` | `AI_MEMORY_PROFILE__LLM` | Use the configured LLM provider for the profile when there is one. |
+
+## `[sanitize]`
+
+Defined by `SanitizeConfig` in `ai-memory-core`. Built-in redaction patterns always run.
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `extra_patterns` | `[]` | `AI_MEMORY_SANITIZE__EXTRA_PATTERNS` | Additional regex patterns to redact. An invalid regex aborts startup. |
+| `allowlist` | `[]` | `AI_MEMORY_SANITIZE__ALLOWLIST` | Substrings that are never redacted, even when a pattern matches them. Blank entries are dropped. |
+
+## `[ingest]`
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `drop_tool_use_id_prefixes` | `[]` | `AI_MEMORY_INGEST__DROP_TOOL_USE_ID_PREFIXES` | Drop a tool event whose `tool_use_id` starts with one of these. |
+| `drop_tool_names` | `[]` | `AI_MEMORY_INGEST__DROP_TOOL_NAMES` | Drop a tool event whose tool name equals one of these exactly. |
+| `drop_events` | `[]` | `AI_MEMORY_INGEST__DROP_EVENTS` | Drop whole hook event kinds. `session-start` and `session-end` are rejected at load. |
+
+## `[hook_spool]`
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `max_attempts` | `8` (`DEFAULT_HOOK_SPOOL_MAX_ATTEMPTS`) | `AI_MEMORY_HOOK_SPOOL_MAX_ATTEMPTS` | Failed drain passes before a spooled hook event is dropped. 0 disables the limit. |
+
+## `[routing]`
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `mid_session` | `follow-cwd` | `AI_MEMORY_ROUTING__MID_SESSION` | Attribution of a mid-session event after the cwd moved: `follow-cwd` or `sticky`. |
+
+## `[auto_scope]`
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `mode` | `per_actor` | `AI_MEMORY_AUTO_SCOPE__MODE` | Keying of the active-project pointer: `per_actor`, `per_session` or `single`. |
+| `session_ttl_secs` | `3600` (`DEFAULT_PER_KEY_TTL`) | `AI_MEMORY_AUTO_SCOPE__SESSION_TTL_SECS` | Lifetime of a per-key entry in the `per_session` and `per_actor` modes. 0 uses the default. |
+| `max_entries` | `4096` (`DEFAULT_MAX_ENTRIES`) | `AI_MEMORY_AUTO_SCOPE__MAX_ENTRIES` | Cap on the per-key map, evicting the oldest insertions first. |
+
+## `[auth]`
+
+Keys that `ai-memory init` writes or generates are marked in the Purpose column. Prefer the environment variables for secrets.
+
+| Key | Default | Env equivalent | Purpose |
+| --- | --- | --- | --- |
+| `bearer_token` | unset | `AI_MEMORY_AUTH_TOKEN` | Shared bearer token required on HTTP routes. Generate one with `ai-memory generate-auth-token`. |
+| `bearer_token_file` | unset | `AI_MEMORY_AUTH__BEARER_TOKEN_FILE` | Owner-only file holding the shared bearer token. Managed by `ai-memory init` and `ai-memory auth enable`, which set `auth-tokens/default`. |
+| `new_projects_restricted` | `false` | `AI_MEMORY_AUTH__NEW_PROJECTS_RESTRICTED` | Create new projects as `restricted` instead of `open`. |
+| `secure_cookie` | `false` | `AI_MEMORY_AUTH__SECURE_COOKIE` | Mark the browser session cookie `Secure`, for `/web` behind an HTTPS-terminating proxy. |
+| `root_username` | unset | `AI_MEMORY_AUTH__ROOT_USERNAME` | Username attributed to writes authenticated by the bearer token. |
+| `root_issuer` | unset | `AI_MEMORY_AUTH__ROOT_ISSUER` | OIDC issuer of the root operator behind a trusted proxy. Set together with `root_subject`. |
+| `root_subject` | unset | `AI_MEMORY_AUTH__ROOT_SUBJECT` | OIDC subject of the root operator. Set together with `root_issuer`. |
+| `root_email` | unset | `AI_MEMORY_AUTH__ROOT_EMAIL` | Email shown for the root user in the web UI and `/api/v1`. |
+| `root_name` | unset | `AI_MEMORY_AUTH__ROOT_NAME` | Display name of the root user. Falls back to `root_username`. |
+| `token_pepper` | unset | `AI_MEMORY_AUTH__TOKEN_PEPPER` | Per-server pepper for native API key hashes. Generated by `ai-memory init`. Do not change it after the first key is added. |
+| `actor_proxy_bearer_token` | unset | `AI_MEMORY_AUTH__ACTOR_PROXY_BEARER_TOKEN` | Bearer token for a trusted authenticating proxy that names the real user in `X-Memory-Actor-*` headers. |
+| `initial_root_password` | unset | `AI_MEMORY_AUTH__INITIAL_ROOT_PASSWORD` | One-shot root password consumed on greenfield bootstrap. Set it through the environment. |
+| `recovery_token` | unset | `AI_MEMORY_AUTH__RECOVERY_TOKEN` | Break-glass secret for `POST /auth/recovery`. Set it through the environment. |
+| `trusted_proxy_cidrs` | `[]` | `AI_MEMORY_AUTH__TRUSTED_PROXY_CIDRS` | CIDRs allowed to supply `X-Forwarded-For` for login rate limiting. |