akm 0.8.0: CLI Redesign, Task Assets, and Belief-Aware Memory

akm 0.8.0 is out. This release combines the storage reorganization and CLI redesign with the final improve-owned maintenance migration: plain akm index now keeps metadata current, while slower memory inference and graph extraction maintenance run from akm improve after consolidation.

If you are on 0.7.x, the v1 migration guide covers the per-surface delta. The upgrade requires updating scripts and agent instructions due to breaking CLI changes.

TL;DR

• akm improve — unified command for agent-driven asset refinement and post-loop maintenance.
• Improve-owned maintenance — memory inference and graph extraction now run from akm improve, not akm index.
• End-of-run auto-sync — akm improve now auto-commits git-backed stashes; --sync/--no-sync/--push/--no-push flags + token-based commit messages.
• Task assets — first-class asset type for defining persistent agent workflows with cron scheduling and manual invocation.
• Belief-aware memory — stash updates now incorporate the agent's belief state to prevent overwriting correct information.
• Proposal queue commands renamed — old flat commands (akm proposals, akm show proposal, akm diff proposal, akm accept, akm reject) are now (akm proposal list, akm proposal show, akm proposal diff, akm proposal accept, akm proposal reject).
• akm health — runtime health report for state.db, task execution logs, agent availability, and recent improve telemetry.
• CLI breaking changes — proposal queue workflows are consolidated around akm improve, akm propose, akm proposal list, akm proposal show, akm proposal diff, akm proposal accept, and akm proposal reject (old flat aliases deprecated); update your automation.
• Release hardening — empty-query search is a structured error again, remember --enrich now truly fail-softs, improve lock-leak on initialization errors fixed, and the Docker install matrix is green for Bun and binary paths.

---

akm improve: The New Self-Improvement Surface

The akm improve command consolidates asset refinement workflows. It can operate on a specific asset type (generating a new asset) or an existing asset ref (refining that asset). Under the hood, it uses the same proposal queue as before, ensuring all changes are reviewable before promotion.

akm improve <type>                 # scope the run to all assets of that type
akm improve <ref>                  # refine an existing asset and produce a proposal

This consolidates the main proposal-oriented improvement workflow. It also now owns the slow maintenance passes that used to be coupled to indexing: after distill and consolidation settle the corpus, improve runs memory inference, reindexes if inference wrote new facts, and then refreshes graph extraction against the final post-improve state.

End-of-Run Git Sync and Commit Templating

For git-backed stashes (detected by .git directory presence), akm improve
now commits all changes as a single batch at the end of the run. Two new flags
control the behavior:

akm improve              # default/thorough profiles: auto-commit + push
akm improve --no-sync    # skip the end-of-run commit for this run
akm improve --no-push    # commit but skip push
akm improve --sync       # force sync even on profiles that disable it

Sync defaults by profile:

Profile	Sync	Push
default	✓	✓
thorough	✓	✓
quick	—	—
memory-focus	—	—

Lightweight passes (quick, memory-focus) opt out of auto-sync to avoid
auto-committing partial results.

Commit message templates: The sync.message config field supports {token}
placeholders — {timestamp}, {date}, {time}, {scope}, {refs},
{accepted} — so the commit log can carry run context:

"sync": { "message": "akm improve {scope} — {refs} refs ({date})" }

The improve result includes a sync field ({ committed, pushed, skipped,
reason? }) and a stash_synced event is emitted to state.db. Sync failures
are non-fatal — they never fail a successful run.

Consolidate Reliability Improvements

The consolidate pass received two reliability fixes:

• Pre-flight stale-DB filter: entries that have gone stale in the DB since the run started are filtered out before any LLM calls, eliminating wasted tokens on already-processed content.
• Defense-in-depth merge guards: four layers of guards now prevent incorrect merges, improving correctness on edge cases.

Task Assets: Persistent Agent Workflows

Task assets (tasks/<name>.yml) allow you to define persistent agent workflows that can be triggered on a schedule or manually. Each task runs using the configured agent runtime.

Key features:

• Cron-based scheduling (with proper escaping for special characters)
• Manual invocation via akm tasks run <id>
• Proposal-driven updates (task agents propose changes via akm improve, which go through the proposal queue)

Example task asset:

name: daily-code-review
schedule: '0 9 * * *'  # every day at 9 AM
command: opencode
prompt: "Review the staged changes and suggest improvements"

Belief-Aware Memory

Memory assets now carry a beliefState frontmatter field (values: active, asserted, deprecated, superseded, contradicted, archived). The consolidation and improve passes use this field to track and transition belief state — for example, marking a memory contradicted when a newer fact conflicts with it. This reduces the chance of outdated or incorrect beliefs persisting in the stash after new information arrives.

Proposal Queue: Renamed Commands

The proposal queue itself is unchanged, but the CLI surfaces have been reorganized under a proposal subcommand:

Old Command (0.7.x)	New Command (0.8.0+)
akm proposals	akm proposal list
akm show proposal	akm proposal show
akm diff proposal	akm proposal diff
akm accept	akm proposal accept
akm reject	akm proposal reject

All commands retain the same functionality and flags (e.g., akm proposal reject <id> --reason "..."). The old flat verbs still work as deprecated aliases (they warn on stderr) and will be removed in 0.9.0 — update your scripts and documentation before then.

akm health: Runtime Checks in One Command

akm health provides a quick operator-facing snapshot of whether the local akm
runtime is healthy.

akm health
akm health --since 24h
akm health --since 7d --format text

It checks that state.db is readable and writable, verifies that required
tables exist, inspects task_history for missing log files or stale active
runs, probes the default agent profile, and summarizes recent akm improve
activity from improve_invoked, improve_skipped, and improve_completed
events.

This makes it easier to validate an upgraded installation after migration or to
spot regressions in task execution and improve-loop maintenance without querying
SQLite tables directly.

Agent Command Builder: Platform-Aware Dispatch

akm agent can now embody a stash agent asset — setting the system prompt, model, and tool policy automatically from the asset's metadata:

akm agent opencode agent:code-reviewer --prompt "review src/commands/"
akm agent claude agent:planner --model sonnet --prompt "plan the next sprint"

The <agent-ref> positional resolves the agent asset's content as the system prompt, its model: frontmatter as the model, and its tools: frontmatter as the allowed tool set. Each platform gets the exact flags its CLI expects:

• opencode: opencode run --system-prompt "..." --model opencode/claude-opus-4-7 "<prompt>"
• claude: claude --system-prompt "..." --model claude-opus-4-7 --allowedTools read,edit --print "<prompt>"

Built-in model aliases (opus, sonnet, haiku) resolve to the correct model string per platform. Add custom aliases in agent.profiles.<name>.modelAliases. Override any asset's model for a single run with --model.

Without a prompt or agent-ref, akm agent opencode still launches the agent interactively — unchanged.

Graph Extraction: Faster, Cleaner, Schema-Stable

0.8.0 reshapes how graph extraction is stored, queried, and refreshed. The
visible wins:

• Schema cascade fix. graph_files now keys on entry_id INTEGER PRIMARY KEY REFERENCES entries(id) ON DELETE CASCADE, and the child tables (graph_file_entities, graph_file_relations) cascade through. Removing a stash or deleting an entry now correctly cleans up the graph rows — no more orphans accumulating in index.db.
• Incremental refreshes. Graph extraction now filters on a candidatePaths set, so each akm improve cycle revisits only touched assets instead of the whole stash. The default graphExtractionBatchSize rose from 1 to 4 (auto-tuned against llm.contextLength).
• Fewer writes. replaceStoredGraph is now incremental — unchanged entries skip, changed entries swap their child rows in place, removed entries cascade out. Roughly 700× fewer row writes per pass on typical re-extractions.
• Faster lookups. listRelatedPathsForFile is a scoped SQL self-join instead of a full snapshot load: ~30ms → ~2ms on a typical stash.
• New commands. akm graph entity <name> inverts the entities view (every asset that mentions a given entity, by confidence). akm graph orphans surfaces assets that produced zero entities — quality-triage candidates. Both are documented in docs/cli.md.
• Better output. akm graph relations and akm graph entities now show per-row confidence. Search hits annotate the graph-boost contribution in whyMatched. Related results end with a Next: akm show '<ref>' hint pointing at the top neighbor.
• Ref-form output. Related results now show canonical refs (e.g. memory:incident-2026-05-12) instead of raw file paths.

DB_VERSION bumped to 17. The schema change uses the existing
DROP+rebuild upgrade path: non-graph tables (entries, embeddings, FTS) rebuild
automatically the first time akm opens index.db; graph tables repopulate on
the next akm improve cycle, which makes LLM calls. The first improve cycle
after upgrade is slower than steady state, but the Phase 1 / Phase 2
improvements above make it dramatically faster than equivalent re-extraction
on 0.7.x. See the migration guide section
Graph extraction will re-run after upgrade.

Config v2 and reflect LLM mode

0.8.0 introduces a new config shape (configVersion: "0.8.0") that replaces
the scattered v1 keys with a unified profiles + first-class feature tree.
Named LLM connections live under profiles.llm.<name> and named agent
connections under profiles.agent.<name>, each declared once and referenced
by name from process entries on profiles.improve.<name>. The old
llm.features.* boolean flags and agent.processes map are replaced by
profiles.improve.<name>.processes.* (improve-bound work), plus top-level
index.metadataEnhance, index.stalenessDetection, and search.curateRerank
sections (non-improve features) — each entry using a unified {mode, profile,
timeoutMs, options} shape. Configs without configVersion are auto-migrated
at first run; a timestamped backup is written before any in-place rewrite.

With the new config in place, the reflect pass inside akm improve can now
run as a direct LLM call instead of spawning an opencode subprocess. For reflect, the context is statically pre-assembled, so a direct
HTTP call captures the full quality benefit at a fraction of the cost. LLM mode
also adds multi-turn self-refine (the prior draft is sent back as an assistant
turn) and structured JSON output for providers that set supportsJsonSchema:
true. The performance difference is significant:

Mode	Time per reflect call	69-ref improve run
agent (CLI subprocess)	~30s	~35 min
sdk (in-process opencode)	~10–15s	~12–17 min
llm (direct HTTP)	~6–10s	~8–10 min

To opt in to LLM mode for reflect:

// Opt in to LLM mode for reflect (3-5x faster)
{
  "configVersion": "0.8.0",
  "profiles": {
    "llm": {
      "openai-mini": {
        "endpoint": "https://api.openai.com/v1/chat/completions",
        "model": "gpt-4o-mini",
        "apiKey": "${OPENAI_API_KEY}",
        "supportsJsonSchema": true
      }
    },
    "improve": {
      "default": {
        "processes": {
          "reflect": { "mode": "llm", "profile": "openai-mini" }
        }
      }
    }
  },
  "defaults": { "llm": "openai-mini" }
}

To migrate an existing config:

# Preview the transformation
akm config migrate --dry-run

# Apply (writes a timestamped backup first)
akm config migrate

Full reference: docs/configuration.md.
Full key mapping: docs/migration/v0.7-to-v0.8.md — Config v2 migration.

Migration Guidance

Breaking changes in 0.8.0:

• Consolidated around: akm improve, akm propose, akm proposal list, akm proposal show, akm proposal diff, akm proposal accept, akm proposal reject, akm proposal revert (old flat aliases deprecated)
• Added: task assets, renamed proposal commands
• Added: akm health for runtime and improve telemetry checks
• Added: end-of-run auto-sync for git-backed stashes (--no-sync to opt out)
• Removed: akm index --enrich and akm index --re-enrich
• Changed: plain akm index now owns metadata enhancement only; slow LLM maintenance moved to akm improve
• Windows task path parsing now correctly handles absolute paths and drive letters
• Cron expressions with apostrophes are now properly escaped in schtasks XML

To upgrade:

1. Update any scripts or automation that still target the pre-0.8 proposal queue and indexing workflow.
2. Prefer akm improve for the main refinement/maintenance workflow.
3. Stop calling akm index --enrich; use plain akm index plus akm improve maintenance flows.
4. Use akm health --since 24h after upgrade to confirm state-db and task-history health.
5. Rename proposal queue commands as per the table above.
6. Review task definitions for Windows path compatibility if using absolute paths.
7. Run akm config migrate to upgrade your config to the v2 shape and unlock LLM-mode reflect.

No manual data migration is required. The proposal queue and existing stash assets remain compatible.

Try the New Surfaces

# Scope an improve run to all memory assets
akm improve memory --task "Summarize today's debugging session"

# List improvement proposals
akm proposal list

# Show one proposal
akm proposal show <id>

# Accept a proposal (after review)
akm proposal accept <id>

# Define and run a task
akm tasks run daily-code-review

# Run improve with a specific profile (reflect mode comes from the profile)
akm improve memory:my-note --profile fast-llm

Verification

After upgrading:

akm info --format text     # version 0.8.x
akm health --since 24h     # runtime + improve telemetry checks
akm proposal list         # queue starts empty — that's expected
akm task list              # shows your defined tasks
akm config get configVersion  # "0.8.0" after akm config migrate

Full details in the v0.7 to v0.8 migration guide and the configuration reference.

Full changelog at CHANGELOG.md.