A self-improving memory loop sounds like a clear win until you watch it rewrite something correct with something outdated. The agent remembered a fact. You verified it. A later consolidation pass ran against a stale context window, decided the memory was imprecise, and replaced it with a weaker version. The original was better. You lost ground.
This is the failure mode that belief-aware memory was built to prevent. Not "agents write wrong things" — that's a model quality problem. The specific failure is: the improve loop, running unsupervised, overwrites correct content it should have left alone. A loop that can degrade its own best work is worse than no loop at all.
akm 0.8.0 ships captureMode
and beliefState
as first-class frontmatter fields on memory assets. Together they tell the consolidation pass what each memory is, what the agent believes about it, and whether it is eligible to be rewritten.
Every memory asset now carries a captureMode
field. It has two values.
hot
means the memory was written or explicitly confirmed by a human. The improve loop treats hot memories as read-only. No consolidation plan, no merge proposal, no rewrite. If every memory in a chunk is captureMode: hot
, the consolidation pass skips the LLM call for that chunk entirely — the chunk is counted as judgedNoAction
before a single token is spent. This is the all-hot chunk early-exit.
background
means the memory was generated by an agent — promoted during a prior consolidation run, written by an inference pass, produced by akm remember
without explicit human review. Background memories are eligible for improvement. The consolidation pass can propose merges, rewrites, deletions, or upgrades.
When no captureMode
is set, the memory is treated as eligible for consolidation. Memories that existed before 0.8.0 are treated this way on first encounter.
---
captureMode: hot
beliefState: asserted
description: "Primary LM Studio endpoint moved to Shredder (192.168.0.99:1234)"
---
---
captureMode: background
beliefState: active
description: Approximate token throughput for qwen3.5-9b on RTX 4060 Ti
---
The distinction matters most for memories that are both accurate and stable: architectural decisions, confirmed configuration facts, verified benchmarks. You write them once, mark them hot, and the improve loop stops touching them.
beliefState
describes the agent's current belief about the memory's accuracy. The field has five non-archived values.
active
is the default when no beliefState
is set. The memory is currently believed to be true. The consolidation pass treats it normally according to its captureMode
.
asserted
is the human-authority variant of active
. The improve loop sets this when you use akm remember
explicitly. Like active
, the consolidation pass treats it as eligible based on captureMode
— but asserted
is never automatically downgraded to active
during consolidation. It carries a stronger signal that a human touched this memory directly.
deprecated
means the memory has been superseded. The content is no longer the current best representation, but it is not wrong — it describes something that was true and has since evolved. Deprecated memories are frozen historical state — the consolidation pass will not refresh them to active
, but they are candidates for merge into a more current memory.
superseded
is the system-assigned equivalent of deprecated. The improve loop writes this when it determines a memory has been replaced by a newer one. Unlike deprecated
, superseded
can be refreshed if the superseding memory is later retracted.
contradicted
means the memory is known to be wrong. It conflicts with something else in the stash that the agent now believes more strongly. A contradicted memory is never promoted, never merged into a primary, and is queued for deletion on the next consolidation pass that touches it.
---
captureMode: background
beliefState: contradicted
contradictedBy:
- memory:lm-studio-server-topology
description: Old belief that Don was the consolidation LLM endpoint
---
The contradictedBy
field is an array of refs — the memories that supersede this one. It chains revisions explicitly. You can read the chain backward: follow each contradictedBy
ref to find the current belief. The beliefState
field is indexed as a frontmatter tag, so akm search "beliefState:contradicted"
or akm search "beliefState:deprecated"
surfaces everything the agent currently believes is wrong or outdated, which is useful for auditing stale content before a long session.
When akm improve
starts a consolidation chunk, it evaluates captureMode
before making any LLM call. The sequence is:
captureMode
for every memory in the chunk.hot
, record the chunk as judgedNoAction
and skip to the next chunk. No model call.background
(or has no captureMode
set), proceed to the LLM consolidation prompt — but pass the belief state metadata alongside each memory so the model knows what it is working with.beliefState: contradicted
on a memory and knows not to use it as a merge primary. It sees beliefState: deprecated
and treats the memory as a merge candidate rather than a standalone to preserve.The early-exit on all-hot chunks is a real cost reduction in practice. A stash where the majority of permanently-settled memories are marked hot will skip a significant fraction of chunks without touching the model at all. Those skipped chunks still count in the run's telemetry — the judgedNoAction
counter — so akm health
can show you the proportion of work that was bypassed via belief state rather than processed.
Belief-aware memory is active by default in 0.8.0. For most setups, nothing changes on upgrade. Existing memories without a captureMode
field are treated as eligible for consolidation, and existing memories without a beliefState
field resolve to active
— both match prior behavior.
The memory.belief_aware
configuration flag (enabled by default; not surfaced in akm config list
— check release notes if you need to toggle it) (documented in the release notes) gates the pre-write validation path. Leaving it on is the right default. The validation overhead is negligible. The protection against overwriting confirmed content is the point.
The intended workflow is straightforward. Run akm improve
or akm remember
normally. When the improve loop promotes a memory that you verify and want to lock, open the asset and set captureMode: hot
. That is the only required human action.
akm show memory:lm-studio-server-topology
When something in the stash becomes wrong — you find a configuration fact that has changed, a benchmark that does not reflect the current hardware — mark it contradicted and point it at the memory that replaced it:
---
captureMode: background
beliefState: contradicted
contradictedBy:
- memory:shredder-throughput-2026-05
description: Initial throughput estimate for Shredder before thermal tuning
---
The contradicted memory stays in the stash until the consolidation pass processes it. It does not disappear immediately. That is intentional — the chain of belief updates is itself a record of how your agent's understanding evolved. You can review it, audit it, and delete it explicitly when you are satisfied the current belief is stable.
For deprecated memories, the same pattern applies, but with a lighter touch. A deprecated memory is not wrong — it is outdated. The consolidation pass will eventually merge it into something more current. You can accelerate this by pointing the contradictedBy
field at the successor, but it is not required.
The improve loop is powerful because it runs continuously and without supervision. That is also the source of the failure mode. An unsupervised loop that can propose changes to anything in the stash will, given enough time and enough edge cases, propose a change to something it should not touch.
Hot memories are immune. They require no ongoing maintenance. They do not need to be defended against the loop because the loop is not allowed to reach them.
Background memories with beliefState: active
or asserted
are in normal rotation. The loop can improve them. That is the intended behavior — background memories accumulate in agent sessions and benefit from periodic consolidation.
The contradicted and deprecated states give the loop a way to reason about quality without conflating "eligible for improvement" with "currently correct." A background, active memory is eligible and believed correct. A background, contradicted memory is eligible and believed wrong — the right action is deletion or absorption, not refinement.
The combination — two capture modes, five belief states, and an explicit contradiction chain — gives you fine-grained control over what the loop does. The loop becomes an asset rather than a liability when it has enough information to distinguish what it should improve from what it should leave alone.
Belief-aware memory is part of akm 0.8.0. The full field reference is in docs/configuration.md. The improve pipeline and consolidation pass behavior are covered in the improve pipeline debugging post and the 0.8.0 release notes. For a walkthrough of the improve loop setup and scheduling, see The Improve Loop: Continuous Memory Curation.