Belief-Aware Memory in akm 0.8.0: How Agents Decide What to Remember vs. What to Update

Most agent memory systems treat every new observation as an append operation. akm 0.8.0 introduces a different approach: belief-aware memory that distinguishes between learning something new and correcting something wrong. The release also ships task assets for persistent agent workflows and a redesigned improve command that consolidates maintenance operations.

This matters because agent memory management is a plumbing problem, not a prompt problem. When an agent writes to its stash (akm’s term for persistent state), it needs to know whether it is adding a fact or revising a belief. Get it wrong and you either accumulate contradictions or lose valid history.

The Belief-Aware Memory Pattern

Traditional agent memory systems append observations to a log or vector store. When an agent learns “the API endpoint is /v1/users,” it writes that fact. When it later learns “the API endpoint is /v2/users,” it writes that fact too. Now the stash contains conflicting information, and retrieval becomes a ranking problem.

Belief-aware memory solves this by tracking what the agent currently believes to be true. When a new observation contradicts an existing belief, the system overwrites the old entry instead of appending. When a new observation adds information, it appends.

The implementation requires three components:

1. Belief state tracking: The stash maintains a structured representation of what the agent believes, not just what it has observed.
2. Contradiction detection: Before writing, the system checks whether the new information conflicts with existing beliefs.
3. Update vs. append logic: Contradictions trigger updates; new information triggers appends.

akm implements this through its stash update mechanism. When an agent proposes a change to the stash, the system evaluates whether the change represents a correction (belief revision) or new information (belief extension). The evaluation happens at write time, not retrieval time, which keeps the stash consistent.

Task Assets: Persistent Agent Workflows

Task assets are a new first-class type in akm 0.8.0. They define agent workflows that persist across CLI invocations. Unlike ephemeral agent runs, task assets store:

• Workflow definitions (what the agent should do)
• Scheduling information (when to run)
• Trigger conditions (what events start execution)
• Context and state (what the agent knows)

A task asset looks like this in the stash:

type: task
name: update-dependency-graph
schedule: daily
triggers:
  - event: package.json.modified
  - event: go.mod.modified
context:
  - asset: dependency-rules
  - asset: security-policy
workflow:
  - step: extract-dependencies
  - step: check-vulnerabilities
  - step: propose-updates

Task assets solve the session boundary problem. Most CLI-based agent tools lose context when the process exits. Task assets persist the workflow definition and execution state in the stash, so the next invocation picks up where the last one stopped.

The storage model uses state.db (a SQLite database) for execution logs and the git-backed stash for workflow definitions. This split keeps fast-changing execution state separate from slowly-changing workflow definitions.

The Redesigned improve Command

The improve command is now the single entry point for agent-driven maintenance. Previous versions scattered maintenance operations across index, propose, and manual commands. Version 0.8.0 consolidates them:

# Old pattern (0.7.x)
akm index              # Update metadata
akm infer-memory       # Run memory inference
akm extract-graph      # Extract knowledge graph
akm propose            # Generate proposals

# New pattern (0.8.0)
akm improve            # Does all of the above

The command runs in phases:

1. Consolidation: Gather pending changes and agent observations
2. Inference: Run memory inference and graph extraction (slow operations)
3. Proposal generation: Create stash update proposals
4. Auto-sync: Commit changes to git-backed stash (if enabled)

The --sync and --push flags control git operations. Auto-sync uses token-based commit messages that include the agent’s reasoning, making the git log a readable audit trail.

Breaking change: akm index no longer runs memory inference or graph extraction. It only updates metadata. Slow maintenance operations moved to improve because they require agent context and should run after consolidation, not during fast indexing.

Proposal Queue Redesign

The proposal queue commands moved from flat verbs to a nested structure:

Old Command	New Command	Purpose
akm proposals	akm proposal list	List pending proposals
akm show proposal	akm proposal show	Show proposal details
akm diff proposal	akm proposal diff	Show proposed changes
akm accept	akm proposal accept	Accept and apply proposal
akm reject	akm proposal reject	Reject proposal

The new structure groups related operations and makes room for future proposal types (not just stash updates). The proposal queue stores proposals in state.db with status tracking (pending, accepted, rejected) and links to the originating agent run.

Health Monitoring with akm health

The new akm health command reports runtime state:

• state.db integrity and size
• Task execution logs (recent runs, failures)
• Agent availability (which agents are configured)
• Recent improve telemetry (execution time, proposal count)

This is an operational command, not a debugging command. It answers “is the system healthy?” not “why did this specific run fail?” The output is structured JSON for scripting:

{
  "state_db": {
    "size_mb": 12.4,
    "integrity": "ok"
  },
  "tasks": {
    "total": 8,
    "recent_failures": 1,
    "last_run": "2026-06-03T22:15:00Z"
  },
  "agents": {
    "configured": ["gpt-4", "claude-3"],
    "available": ["gpt-4"]
  }
}

Architecture: Where Belief-Aware Memory Fits

The belief-aware memory system sits between the agent’s proposal generation and the stash write path:

1. Agent observes new information during a run
2. Agent generates a stash update proposal
3. Belief-aware memory evaluates the proposal against current stash state
4. System determines: update existing belief or append new belief
5. Proposal queue stores the decision
6. User (or automated policy) accepts or rejects
7. Stash applies the change

The evaluation step is where the work happens. The system loads the relevant portion of the stash (not the entire history), extracts current beliefs, compares them to the proposed change, and classifies the operation. This requires structured stash entries, not free-form text.

akm uses YAML for stash entries with a schema that includes belief metadata:

type: belief
subject: api-endpoint
value: /v2/users
confidence: high
source: agent-run-2026-06-03
supersedes: belief-api-endpoint-v1

The supersedes field creates an audit trail. When a belief is updated, the old entry is not deleted. It is marked as superseded and moved to history. This preserves the reasoning chain without polluting current beliefs.

Failure Modes and Mitigations

Contradiction detection false negatives: The system might fail to recognize that two beliefs conflict if they use different terminology. Mitigation: structured schemas with controlled vocabularies. If beliefs about “API endpoint” and “service URL” are stored in different fields, the system will not catch the conflict.

Belief churn: If the agent frequently revises beliefs based on noisy observations, the stash will thrash. Mitigation: confidence thresholds. Only high-confidence observations trigger belief updates. Low-confidence observations append as tentative.

Stale beliefs: If the agent stops observing a domain, beliefs about that domain become stale but remain in the stash. Mitigation: time-based decay or explicit invalidation. akm does not implement this yet.

Merge conflicts in git-backed stash: If two agents update the same belief concurrently, git will conflict. Mitigation: proposal queue serialization. Only one proposal can be accepted at a time, and acceptance includes a git commit.

Migration from 0.7.x

The upgrade is breaking. Scripts and agent instructions need updates:

• Replace akm proposals with akm proposal list
• Replace akm accept with akm proposal accept
• Move memory inference and graph extraction from akm index to akm improve
• Add --sync or --no-sync flags to akm improve calls
• Update task definitions to use the new task asset schema

The v1 migration guide (linked in the source) covers the per-surface delta. Expect to spend an hour updating automation scripts and another hour testing agent workflows.

Technical Verdict

Use akm 0.8.0 when:

• You need agent memory that corrects itself instead of accumulating contradictions
• You run agents in CLI environments and need persistent workflow state across sessions
• You want git-backed audit trails for agent decisions
• You are building multi-agent systems where belief consistency matters

Avoid when:

• You need real-time agent operations (the proposal queue adds latency)
• Your agents do not produce structured observations (belief-aware memory requires schemas)
• You are running in serverless or stateless environments (task assets assume persistent storage)
• You need sub-second agent response times (the improve command runs slow maintenance operations)

The belief-aware memory pattern is a step toward agents that maintain coherent world models instead of append-only logs. The implementation is opinionated (git-backed stash, SQLite state, YAML schemas) but the pattern is portable. If you are building agent infrastructure, the distinction between belief updates and belief extensions is worth implementing, even if you do not use akm.

Source Links

• akm 0.8.0 Release Announcement