Skip to main content
What this page is. The complete reference for Comis’s agent-memory capabilities and the exact config option for each. The memory features are ON by default (opt-out); a fresh install runs them and you edit config to turn them off. The trust boundary (rag.scoring.trustAlpha, rag.includeTrustLevels) is frozen, not a tunable capability.
The LLM build/ask features (the session review job, the one learning-reflection cron, and the memory_ask grounded-Q&A tool) spend your own LLM/API budget. They are on by default, and the daemon prints a first-run notice listing what’s active. One line turns all of them off: memory.enabled: false.
The master kill-switch is memory.enabled, and the three recall model knobs nest under memory.recall.*. The whole per-agent learning layer is one agents.<id>.learning block (one learning.enabled flag + learning.reflect.* + learning.forget.*).
Where the config lives. Capabilities are configured per agent under agents.<agentId>. in ~/.comis/config.yaml. The shared memory engine (store + embeddings + reranker + the cost kill switch) is the top-level memory: block. The config below is the effective default — set any enabled: false to opt a feature out.
On by default is necessary but not always sufficient; several capabilities also need built derived state (a populated graph, scored usefulness) before they change recall. See Dependencies & gotchas below.

​
Default config (opt-out)

This is the effective default a fresh install runs. To opt out, set the relevant enabled: false (or flip the master memory.enabled: false to silence all LLM-cost features at once).

​
Capability → config map

​
The one learning-reflection engine

Comis’s learning layer is one governed reflection engine. A single __REFLECT__ cron maintains named Mental Model docs (kind: skill | profile | topic) via byte-stable delta operations. Skill reflection uses the fused learningOutcome signal instead of text overlap alone. That signal is evidence, not a guarantee that the task actually succeeded. The whole layer is governed by one flag, agents.<id>.learning.enabled, under the master memory.enabled switch.
  • Reflection (learning.reflect.*) — for skill docs, the __REFLECT__ cron clusters trusted-origin trajectories whose configured outcome resolver reports success. A fused success label is not independent verification. Mixed tool, pipeline, judge, reaction, or correction signals can classify a session that failed overall as successful. Profile and topic docs are built from the eligible system and learned memory corpus instead of the skill outcome path. Every admitted doc is stored at trust=learned; this is a policy label and trust ceiling, not a claim that the content is reliable.
  • Admission and surfacing — a topic must pass the selected corroboration mode and the static learned-document validator before admission. Critical secret and poison patterns are rejected. Warning-level patterns, including some jailbreak-like language, are recorded but can pass. A read-only, non-evicted candidate can surface in <available_skills> before promotion so it can receive reuse feedback. active remains the higher proof tier. Mutating, stale, archived, and evicted docs do not surface.
  • Promotion, correction, and demotion — attributed reuse labeled success increments proof and can promote candidate to active at promoteAtProofCount. A recorded correction does not by itself guarantee demotion or a durable behavior change. The correction detector must be enabled, the prior turn must attribute a surfaced skill, confidence and failure corroboration must pass, and the trend must become weakening before a skill moves to stale. When an accepted profile or topic update supersedes an existing doc, the prior body is appended to history rather than hard-deleted.
  • Authority and scope — learned docs contain advisory Markdown and no executable column. The model re-authors any action through its existing tools, capability gates, approvals, credentials, and sandbox posture. The learned doc adds no execution authority. Reads and writes are scoped to (tenant, agent); this is not a per-chat or per-sender recall boundary.
  • Procedure-doc surface budget (learning.reflect.maxProcedureDocsSurfaced, default 10) — a per-agent cap on how many procedure docs surface into one prompt’s <available_skills>. With no ranked top-K at surface time, a burst of procedure docs would otherwise bloat every prompt; the budget caps that subset only. When it is exceeded the highest-proof procedure docs (highest proof count) keep their slot, surfaced in a stable listing order. User-intent skill docs and topic docs are unaffected; they keep a separate, uncapped path.
  • Forgetting (learning.forget.*) — couples a memory’s decay to its outcome-attributed failure_count and soft-evicts a sufficiently weak or stale memory: it is marked evicted_at (excluded from recall, still resolvable via asOf/inspect, reversible, never hard-deleted). A memory implicated in failureEvictionFloor (default 3) or more corroborated failures is soft-evicted regardless of its decayed strength, while a memory at/above highProofFloor (default 5) is exempt. A corroboration gate (two distinct-session observations, or one deterministic source, on every failure_count increment) plus exemptions for pinned / system / high-proof_count memories reduce induced eviction risk. The sweep runs on the keyless memoryLifecycle cron (__LIFECYCLE__).
Recall ranking itself is the fixed rag.scoring fusion (deterministic RRF + the cross-encoder reranker); there is no learned recall weight.

​
Corroboration: single-owner (default) vs distinct-sessions (learning.reflect.corroboration)

Before a topic can seed a learned doc it must satisfy the configured admission gate. The configuration calls both modes corroboration, but they provide different evidence strength:
  • mode: single_owner (default) — repetition by exactly one sender explicitly named in elevatedReply.senderTrustMap. The topic can seed after minObservations success-labeled repetitions (default 2). These observations can come from the same owner and session, so this is not independent corroboration and does not prove the guidance is correct. It exists so a single-owner deployment can learn without requiring another sender.
  • mode: distinct_sessions — requires at least two distinct (session, sender) observations. Repeats from one sender in one session count once. This is the stricter anti-domination posture, although distinct keys are still evidence signals rather than proof of correctness.
The single_owner gate excludes unknown senders and senders trusted only by defaultTrustLevel; repetition counts only for an operator-named sender. If two or more explicitly named senders are present, Comis falls back to the distinct-sessions gate. These controls reduce who can seed a doc, but they do not establish truth. Choose distinct_sessions when same-owner repetition is not enough for your risk model.
The reflect:funnel telemetry carries a singleOwnerCorroborated count (how many topics corroborated via repetition this run), so comis explain and comis system-health show the mode is active. An admitted > 0 run with maxClusterCardinality: 1 reads as single-owner learning, not a contradiction. See learning in config-yaml for every key and default, the mental_models and memory_usefulness / evicted_at storage, and the counts-only trajectory telemetry (reflect:admitted / reflect:funnel for the reflection funnel; learning:memory_demoted / learning:memory_evicted for the forget sweep) surfaced through comis explain and comis system-health.

​
Strict config schema

The config schema is strict (z.strictObject): a config.yaml that carries an unrecognized key is rejected at boot with a parse error naming the exact key, so a typo or an unsupported block is pointed straight at the line to fix. A bare config (memory:/agents: with no learning keys) loads fully-defaulted.

​
Dependencies & gotchas

  1. Some capabilities need built derived state, not just the flag:
    • KG (rag.lanes.graphSpread) is a no-op until the knowledge graph is populated with entities/edges.
    • FORGET decay (rag.forget) shows up at recall; eviction is the memoryLifecycle sweep — live as soft, reversible eviction (evicted_at) when learning.enabled is on (it reads learning.forget.*), exempting pinned/system/high-proof memories. See the one learning-reflection engine.
    • Reflection needs eligible sources and, for skill docs, enough trusted-origin trajectories resolved as success. A resolved success is a fused signal, not proof that the overall task succeeded. The cron abstains when no topic passes its selected admission gate.
  2. dialectic (memory_ask) spends tokens per ask; it is the only query-time LLM surface in the memory stack. Everything else in recall is LLM-free.
  3. Trust is frozen, not a tunable capability. rag.scoring.trustAlpha and rag.includeTrustLevels are the trust hard-boundary; leave them at the shipped values.
  4. On by default; watch your spend. The LLM build/ask features are opt-out so operators get the full memory stack from day one; they spend your own budget. Your controls are the first-run notice and the master switch memory.enabled: false (or per-feature enabled: false). Measure the effect in your own domain. Comis’s reproducible methodology and the latest costed results are on the Memory benchmarks page.
See also: Memory, Search, Embeddings, and RAG.