akm-cli
Version:
akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cur
333 lines (259 loc) • 17.1 kB
Markdown
---
title: 'akm 0.8.0: CLI Redesign, Task Assets, and Belief-Aware Memory'
cover_image: 'https://raw.githubusercontent.com/itlackey/akm/main/docs/posts/akm-logo-sized.webp'
series: akm-releases
description: 'akm 0.8.0 introduces a redesigned `improve` command, task assets for persistent agent workflows, and belief-aware memory for more accurate stash updates.'
tags:
- ai
- agents
- cli
- release
published: true
---
> This is a dated article from AKM's publishing archive. For current product behavior, see the
> [documentation index](https://github.com/itlackey/akm/blob/main/docs/README.md).
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.
```sh
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:
```sh
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:
```jsonc
"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:
```yaml
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.
```sh
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:
```sh
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.
See the 0.8.0 migration guide's
[graph extraction section](../migration/v0.7-to-v0.8.md#memory-inference-and-graph-extraction-moved-out-of-index).
- **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](../migration/v0.7-to-v0.8.md#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:
```jsonc
// 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:
```sh
# Preview the transformation
akm config migrate --dry-run # doclint:ignore (historical — akm 0.8.0 release announcement; config-schema migration command not present in 0.9.0)
# Apply (writes a timestamped backup first)
akm config migrate # doclint:ignore (historical — akm 0.8.0 release announcement; config-schema migration command not present in 0.9.0)
```
Full reference: [configuration reference](../reference/configuration.md).
Full key mapping: [v0.7 to v0.8 migration guide — Config 0.8.0 migration](../migration/v0.7-to-v0.8.md#config-080-migration-unified-profiles).
## 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
```sh
# 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 # doclint:ignore (historical — akm 0.8.0 release announcement; `tasks` renamed `task` in 0.9.0)
# Run improve with a specific profile (reflect mode comes from the profile)
akm improve memory:my-note --profile fast-llm # doclint:ignore (historical — akm 0.8.0 release announcement; `--profile` renamed `--strategy` in 0.9.0)
```
## Verification
After upgrading:
```sh
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 — doclint:ignore (historical — akm 0.8.0 release announcement; `tasks list` inspection moved to `akm search`/`akm show` by 0.9.0)
akm config get configVersion # "0.8.0" after akm config migrate
```
Full details in the [v0.7 to v0.8 migration guide](../migration/v0.7-to-v0.8.md) and the [configuration reference](../reference/configuration.md).
Full changelog at [CHANGELOG.md](https://github.com/itlackey/akm/blob/main/CHANGELOG.md).