Global config

Global config is still needed for the installed or packaged Memory Layer stack. It holds machine-level defaults and secrets-adjacent settings shared by many projects: backend bind address, database URL, service token, LLM and embedding providers, MCP HTTP settings, retention, provenance, and automation defaults.

Dev-profile cargo runs are different: the dev stack ignores global config and uses a user-local project config plus config.dev.toml. See Project config for that split; the deeper source-tree reference is docs/developer/dev-stack.md.

Where it lives

The env file is loaded next to the config file and is the right place for generated service tokens and provider API keys.

What belongs here

Minimal packaged config shape

[service]
bind_addr = "127.0.0.1:4040"
capnp_tcp_addr = "127.0.0.1:4041"
request_timeout = "30s"

[database]
url = "postgres://memory_layer:<password>@127.0.0.1:5432/memory_layer"

[mcp]
enabled = true
http_enabled = true
http_path = "/mcp"
require_token = true
read_only = true

The service API token is normally provisioned automatically into memory-layer.env:

memory service ensure-api-token --rotate-placeholder

Embedding provider example

[embeddings]
active = "openai-3-small"

[[embeddings.backends]]
name = "openai-3-small"
provider = "openai"
base_url = ""
api_key_env = "OPENAI_API_KEY"
model = "text-embedding-3-small"
batch_size = 16

Put the key in the adjacent env file:

OPENAI_API_KEY=sk-proj-...

Reinforcement section

The [reinforcement] section controls self-maintaining memory. Defaults are safe for normal use: activation scoring is on (deterministic, no LLM cost) and validation is opt-in, starting in dry-run.

[reinforcement]
enabled = true                 # activation scoring, decay, ranking boost
validation_enabled = false     # background LLM validation (opt-in)
validation_dry_run = true      # report-only until you trust the verdicts
validation_threshold = 8.0     # activation at which a memory becomes due
daily_validation_cap = 20      # hard ceiling on LLM validation runs per day
auto_apply_rewording = false   # wording fixes stay human-gated by default

The full knob set (boosts, half-life, propagation depth, volatility, rank weights, retention) is documented on the concept page.

Curation section

The [curation] section controls the semantic dedup pass that runs after chunk embeddings are built. When a newly curated memory is a near-duplicate of an existing one by embedding similarity, the pair is linked and a human-gated merge proposal is queued (memory proposals). Pairs that look like contradictions rather than paraphrases are flagged for review instead of merge.

[curation]
semantic_dedup_enabled = true        # embedding-based duplicate detection
semantic_duplicate_threshold = 0.90  # min max-chunk cosine similarity

This is separate from the per-repo curation.replacement_policy agent setting, which governs lexical replacement decisions at capture time.

Consolidation section

The [consolidation] section controls memory consolidation: discovering clusters of related memories and synthesizing higher-level insight memories. Off by default and dry-run first, matching the reinforcement posture. When enabled, a deterministic cluster scan runs on the curate path and surfaces consolidation_due; with auto_trigger on, a due cluster wakes the LLM synthesis in the background. Every result is a human-gated proposal.

[consolidation]
enabled = false                # discover clusters and synthesize insights
dry_run = true                 # report clusters but do not synthesize
auto_trigger = true            # wake synthesis when usage crosses the salience floor
sim_floor = 0.82               # cosine floor for a semantic-similarity edge
min_size = 3                   # smallest cluster worth consolidating
max_size = 25                  # largest (guards against blob clusters)
min_cohesion = 0.35            # minimum intra-cluster edge density
min_salience = 2.0             # co-access / activation mass for the "use" trigger
novelty_overlap_max = 0.5      # skip clusters already covered by an insight
daily_cap = 20                 # ceiling on LLM syntheses per run

Procedural section

The [procedural] section controls procedural utility learning: each automation loop learns a utility from how its proposals are received (ACT-R delta rule). Deterministic and advisory — it informs the loop listing and recommendations, never modes or permission gates — so it defaults on. The only runtime effect is the opt-in auto-trigger floor.

[procedural]
enabled = true                 # learn per-loop utility from proposal decisions
alpha = 0.2                    # delta-rule learning rate
reward_approved = 1.0          # proposal approved as-is
reward_edited_approved = 0.4   # approved after human editing
reward_rejected = -1.0         # proposal rejected
reward_cited = 0.5             # loop-produced memory cited in an answer
min_samples = 5                # decisions before recommendations appear
utility_floor_enabled = false  # opt-in: suppress AUTO-triggers below the floor
utility_floor = 0.0

Precedence and diagnostics

For prod/profile-installed commands, config is loaded from the explicit --config path if supplied, otherwise from the discovered global config and the current repo's user-local project config when available. Environment variables with the MEMORY_LAYER__... shape override TOML values.

Useful checks:

memory doctor
memory status --project <project-slug> --json
memory service status

Next

Read Project config for repo-local and user-local overrides.