# Belief-Aware Memory: Teaching Your Agent When Not to Write > Source: > Published: 2026-06-04 00:31:07+00:00 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. ``` # Review a promoted memory akm show memory:lm-studio-server-topology # Lock it against future rewrites # Edit the frontmatter: captureMode: hot ``` 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](https://github.com/itlackey/akm/blob/main/docs/configuration.md). The improve pipeline and consolidation pass behavior are covered in the [improve pipeline debugging post](https://dev.to/itlackey/your-agent-has-a-memory-that-runs-while-you-sleep-20oh) and the [0.8.0 release notes](https://dev.to/itlackey/akm-080-cli-redesign-task-assets-and-belief-aware-memory-335a). For a walkthrough of the improve loop setup and scheduling, see [The Improve Loop: Continuous Memory Curation](https://dev.to/itlackey/the-improvement-loop-how-akm-keeps-your-agent-sharp-2d4d).