Skip to content

config.json

agent-mem reads one file, config.json in the data folder (agent-mem paths shows it as “Settings”). It is optional. Every key you leave out keeps its default, and you only write the keys you want to change:

config.json
{
"budgets": { "session_start": 4000 },
"observe": { "providers": ["opencode", "claude", "codex", "copilot", "ollama"] },
"viewer": { "port": 37800 }
}

The file is read by every process at start; there is nothing to restart. A running viewer keeps its port until it is restarted, and a running MCP server keeps its settings until the agent restarts it.

ProblemWhat happensWhere you see it
the file is not valid JSON, or not an objectall defaultsconfig: … is not valid JSON
an unknown keyignoredconfig: unknown key 'observe.provider' ignored
a group that is not an objectdefaults for that groupconfig: 'budgets' must be an object
a value of the wrong type (a string for a number, a negative number)default for that keyconfig: invalid value for 'viewer.port', default kept
a number outside its rangedefault for that keyconfig: 'hook_deadline_ms' must be between 100 and 10000, default kept

The warnings appear in agent-mem doctor and, at most two of them, in the panel at session start. The ranges exist because a well-typed value can still break agent-mem silently: a deadline of 0 would spool every event, stdin_bytes: 0 would record nothing, duplicate_min_cosine: 0 would retire every older fact.

KeyDefaultRange / typeEffect
capturetrueboolfalse: nothing is recorded anywhere; recall still works
native_notestrueboolread Claude Code’s memory/*.md and Codex’s rollout summaries as notes (details)
hook_deadline_ms400100–10,000how long a hook works before it spools the event and prints nothing
exclude_globs16 patterns (below)list of stringsfiles whose content is never stored; replaces the default list
excluded_projects[]list of pathsnothing in these folders is recorded
exclude_globs default
[".env", ".env.*", "*.pem", "*.key", "*.p12", "*.pfx", "id_rsa*", "id_ed25519*", "id_ecdsa*",
".npmrc", ".netrc", ".pypirc", "secrets/**", "**/secrets/**", "*.kdbx", "credentials*"]

Estimated tokens per injected block (a quarter token per ASCII character, one per other character). Each is also capped by what the agent passes in one piece (per-agent caps).

KeyDefaultRangeBlock
budgets.session_start8000–200,000the briefing at session start and for subagents
budgets.prompt24000–100,000matching memories for a prompt
budgets.failure4000–20,000the fix hint after a failed command
budgets.warning3000–20,000a rule note before a tool
budgets.file_history12000–20,000file history before a read or edit
budgets.compact40000–200,000the block after compaction

0 turns a block off. budgets.session_start: 2000 gives about a quarter of the default briefing.

KeyDefaultRangeEffect
retrieval.inject_min_score0.350–1score a hit needs to be injected or listed as confident
retrieval.min_term_coverage0.50–1share of the question’s words a word-match hit must contain
retrieval.max_per_session31–1,000turns per session in one result list
retrieval.rrf_k601–1,000rank fusion constant; larger flattens differences between ranks
retrieval.current_project_boost1.2≥ 0multiplier for hits from the current project
retrieval.min_vector_score0.450–1cosine floor for meaning-based candidates (calibrated for MiniLM)

Lower inject_min_score and min_term_coverage for more context and more noise; raise them for less. See Search Architecture.

KeyDefaultRangeEffect
retention.payload_days301–36,500after this, event payloads are trimmed to kind, category, error line and trust; quarantine notes are deleted
retention.access_days1801–36,500after this, shown/warned/injected access rows and model-call logs are deleted
retention.max_db_mb102464–1,048,576above this size the oldest payloads are trimmed and the database vacuumed, once a day at most
retention.stale_turn_minutes301–10,080an open turn without activity is closed as unknown after this
KeyDefaultRangeEffect
limits.prompt_chars16000200–1,000,000stored characters of a prompt
limits.answer_chars16000200–1,000,000stored characters of an answer
limits.tool_output_chars8000200–1,000,000stored characters of a tool’s output (head, error lines, tail)
limits.tool_input_chars4000200–1,000,000stored characters of a tool’s input
limits.stdin_bytes4194304 (4 MiB)64 KiB–64 MiBa larger hook payload is refused and noted in quarantine
KeyDefaultRangeEffect
rules.auto_enablefalsebooltrue: a rule switches on by itself after min_corrections and then blocks the command
rules.min_corrections21–100how often you must state “use X instead of Y” before a preference is stored
rules.expire_days901–36,500an enabled rule that has not fired for this long is switched off

Search by meaning; needs the [semantic] extra.

KeyDefaultRangeEffect
semantic.enabledtrueboolfalse: word search and graph only
semantic.modelsentence-transformers/paraphrase-multilingual-MiniLM-L12-v2fastembed model namethe embedder; changing it re-embeds everything and rebuilds the mem0 index
semantic.batch_size321–1,024texts per embedding batch
semantic.duplicate_min_cosine0.900.8–1an older observer or agent memory this similar to a newer one is retired; 1 turns it off

E5 models (intfloat/multilingual-e5-*) get their query: and passage: prefixes automatically.

The background fact writer; needs the [observer] extra. See Observer Pipeline.

KeyDefaultRangeEffect
observe.enabledtrueboolfalse: no model calls at all; requests are still recorded and searchable, turns are not queued
observe.providers["opencode", "claude", "codex", "copilot"]opencode, claude, codex, copilot, ollamastages that may write facts, in order
observe.cross_vendorfalsebooltrue: any installed CLI may take any agent’s turns; false: a turn only goes to its own vendor (and Ollama)
observe.claude_model"haiku"stringclaude -p --model …
observe.codex_model"gpt-6-luna"stringcodex exec -m … (low reasoning effort)
observe.copilot_model"auto"stringcopilot -s --model …; auto adds --auto-tier efficiency
observe.opencode_model"opencode/big-pickle"stringopencode run --model …, free; for OpenCode turns
observe.ollama_model"qwen3.5:4b-mlx"stringOllama model, when ollama is in providers
observe.entity_model"en_core_web_sm"spaCy model nametopic links for facts; use the language of your facts (de_core_news_sm), then agent-mem models install
observe.daily_limit300≥ 0model calls per UTC day; over it, turns wait until midnight UTC (Ollama is not limited)
observe.idle_seconds90≥ 0the observer exits after this long without work
observe.lease_seconds90060–86,400how long a worker holds a turn before another may take it
observe.bundle_turns51–50turns of one session per extraction call
observe.bundle_tokens20000500–200,000size of one extraction call; larger bundles are split at turn boundaries
observe.tool_output_chars1200100–100,000characters of each tool output the model sees
observe.turn_tool_chars120000–1,000,000tool output characters per turn in total; 0 sends none
observe.pause_minutes60≥ 0a stage that hit a usage limit or lost its login pauses this long

A model name the CLI refuses (your plan does not offer it, the CLI is too old for the flag) is retried once with the CLI’s own default.

KeyDefaultRangeEffect
viewer.enabledtrueboolfalse: the hooks never start the viewer and setup writes no login item
viewer.port377781,024–65,535the port on 127.0.0.1
viewer.refresh_seconds102–3,600how often an open tab reloads
config.json (all defaults)
{
"capture": true,
"native_notes": true,
"hook_deadline_ms": 400,
"exclude_globs": [".env", ".env.*", "*.pem", "*.key", "*.p12", "*.pfx", "id_rsa*", "id_ed25519*", "id_ecdsa*",
".npmrc", ".netrc", ".pypirc", "secrets/**", "**/secrets/**", "*.kdbx", "credentials*"],
"excluded_projects": [],
"budgets": {"session_start": 800, "prompt": 2400, "failure": 400, "warning": 300, "file_history": 1200, "compact": 4000},
"retrieval": {"inject_min_score": 0.35, "min_term_coverage": 0.5, "max_per_session": 3, "rrf_k": 60,
"current_project_boost": 1.2, "min_vector_score": 0.45},
"retention": {"payload_days": 30, "access_days": 180, "max_db_mb": 1024, "stale_turn_minutes": 30},
"limits": {"prompt_chars": 16000, "answer_chars": 16000, "tool_output_chars": 8000, "tool_input_chars": 4000,
"stdin_bytes": 4194304},
"rules": {"auto_enable": false, "min_corrections": 2, "expire_days": 90},
"semantic": {"enabled": true, "model": "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2",
"batch_size": 32, "duplicate_min_cosine": 0.9},
"observe": {"enabled": true, "providers": ["opencode", "claude", "codex", "copilot"], "cross_vendor": false,
"claude_model": "haiku", "codex_model": "gpt-6-luna", "copilot_model": "auto",
"opencode_model": "opencode/big-pickle", "ollama_model": "qwen3.5:4b-mlx", "entity_model": "en_core_web_sm", "daily_limit": 300,
"idle_seconds": 90, "lease_seconds": 900, "bundle_turns": 5, "bundle_tokens": 20000,
"tool_output_chars": 1200, "turn_tool_chars": 12000, "pause_minutes": 60},
"viewer": {"enabled": true, "port": 37778, "refresh_seconds": 10}
}

data_dir and warnings are not settable in the file. The data folder comes from --data-dir, AGENT_MEM_DATA_DIR or the system default (Environment).