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.mdindex 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: dataflow, 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 specand milestone plan.- [`docs/install.md`](docs/install.md) — installation cookbook for everydiff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 toolcalls stay with the session they advise (#1779).+ a492ec23 (docs(config): map every toml key into template and properties doc)## [3.2.9] - 2026-10-27diff --git a/crates/ai-memory-cli/templates/config.default.toml b/crates/ai-memory-cli/templates/config.default.tomlindex 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 observationsobservation_prune_batch = 5000 # rows per prune transactionledger_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 = 100000max_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 = 5include_raw_fallback = falseproposal_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 = 3600max_sessions_per_tick = 1 # per projectmin_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.mdnew file mode 100644index 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. |