DEV Community: IT Lackey

One Schema to Rule Them All: The Config v2 Rewrite

IT Lackey — Thu, 04 Jun 2026 00:31:43 +0000

This is part sixteen in a series about managing the growing pile of skills, scripts, and context that AI coding agents depend on. The 0.8.0 release notes cover the storage and pipeline changes that shipped alongside this rewrite; Part thirteen covers how the new profiles.improve config drives the improve pipeline.

Config files are where projects go to accumulate technical debt quietly. Each new feature gets a new key. Each new key gets a new parser. Each parser has slightly different error handling, slightly different defaults, and slightly different ideas about what "invalid" means. Nobody notices until a user files an issue that says "I had a typo in my config and akm just silently used defaults for three weeks."

That was the state of akm's config layer going into 0.8.0.

What the Old Shape Looked Like

The v1 config had three top-level blocks that grew independently over two years: llm.* for LLM connection settings, agent.* for agent process settings, and llm.features.* boolean flags gating per-feature LLM calls. The features block was nested under llm for historical reasons even though many features used the agent, not the LLM. The agent's per-process map lived under agent.processes, while LLM-gated features used llm.features.index.metadata_enhance style dotted paths.

Each block had its own parser function. parseLlmConfig, parseEmbeddingConfig, parseIndexConfig, and a dozen more. The comment at the top of the new config-schema.ts is blunt about it: the Zod schema "replaces the ~1.4k LOC of legacy per-shape parsers."

The problems that accumulated in that ~1.4k LOC:

Unknown keys were silently accepted. If you wrote llm.temperaure (typo), the parser ignored it and fell back to the default temperature. No warning. You tuned a key that did nothing.

Bad JSON was masked. The config loader caught JSON parse errors and fell back to DEFAULT_CONFIG — the compiled-in defaults. Your entire config file could be corrupt and akm would start without complaint, using defaults across the board.

Missing files fell back to defaults. Same behavior. A missing config file and a present-but-corrupt one looked identical at runtime.

Adding a field meant adding a parser. Want a new boolean flag under a feature? Find the right parser function, add the extraction logic, add the type declaration, add the hint string, add the test. The cost of a new field was not one line — it was a small PR touching four or five places.

What Zod Gives You

The 0.8.0 rewrite consolidates all of that into src/core/config-schema.ts: a single Zod schema that is the source of truth for the on-disk shape.

Zod handles the parse, transform, and validate steps that were previously scattered across ~1.4k LOC of hand-written code. A new config field is a one-line schema addition. Type inference means the TypeScript types for AkmConfig are derived from the schema automatically — no parallel maintenance between the schema and the type declarations.

The schema design makes deliberate tradeoffs between strictness and resilience:

The top-level object uses .passthrough() so unknown future keys round-trip intact. If a user upgrades and then downgrades, keys added by the newer version survive without triggering errors on the older version. sanitizeConfigForWrite decides what to strip on write.

Nested sub-objects use .catch(undefined) for field-level shape errors so that a typo in one field does not destroy an otherwise valid config. This preserves the legacy parser's warn-and-ignore semantics for individual fields while still catching structural problems.

.strict() walls gate the records that are most typo-prone: registries[], sources[], and profiles.* sub-shapes. A typo in a profile name or a source type now produces a validation error at load time.

Two cases are hard-rejected by superRefine rather than silently dropped: the old stashes[] key (replaced by sources[]) and a legacy source type that had been removed. Both have explicit migration paths — silently ignoring them would mask user data loss.

The Silent Failure Fixes

The new loader changed three behaviors that were causing silent failures in the field.

Unknown keys now error at the profile level. A typo in profiles.llm.my-profile is caught at load time rather than ignored. The error message names the unexpected key and points at the profile block.

Bad JSON now throws. If config.json is not valid JSON, akm throws a ConfigError with the file path and the parse error. No fallback to defaults. The user finds out immediately.

Missing files stay missing. A missing config file is a different situation from a corrupt one, and akm treats them differently now. First run with no config: akm setup or an explicit akm config set creates the file. A missing file during a subsequent run is an error, not a silent fallback.

Auto-Generated JSON Schema

With a Zod schema as the source of truth, generating a JSON schema for editor autocompletion is a natural output. The schemas/akm-config.json file is generated from the Zod schema and checked in. A CI drift test fails if the checked-in file is out of sync with the schema source — there is no manual step to remember when adding a field.

Point your editor at the schema and you get field completion and inline documentation in config.json:

{
  "$schema": "https://itlackey.github.io/akm/schemas/akm-config.0.8.0.json",
  "configVersion": "0.8.0"
}

The $schema key is optional. VSCode and other JSON Schema-aware editors pick it up automatically for field completion and inline docs.

The New Config Shape

The 0.8.0 shape replaces the scattered llm.*, agent.*, and llm.features.* blocks with a unified profiles tree and first-class feature sections.

Old location	New location
`llm.endpoint`, `llm.model`, `llm.apiKey`	`profiles.llm.<name>.endpoint`, `.model`, `.apiKey`
`agent.platform`, `agent.bin`, `agent.args`	`profiles.agent.<name>.platform`, `.bin`, `.args`
`agent.processes.<name>.*`	`profiles.improve.<name>.processes.*`
`llm.features.index.metadata_enhance`	`index.metadataEnhance.enabled`
`llm.features.search.curate_rerank`	`search.curateRerank.enabled`

Named LLM connections live under profiles.llm.<name>, declared once and referenced by name from process entries. Named agent connections live under profiles.agent.<name>. The improve profile (profiles.improve.<name>.processes.*) binds processes to specific LLM or agent profiles and controls per-process gating. Non-improve features (index.metadataEnhance, index.stalenessDetection, search.curateRerank) are first-class top-level entries.

The configVersion field is the version gate. Configs without it, or with a pre-0.8.0 value, are auto-migrated at first run.

The Minimal Working Config

The smallest config that gets you a fully functional 0.8.0 installation with a cloud LLM for improve operations:

{
  "configVersion": "0.8.0",
  "$schema": "https://itlackey.github.io/akm/schemas/akm-config.0.8.0.json",
  "profiles": {
    "llm": {
      "openai-mini": {
        "endpoint": "https://api.openai.com/v1/chat/completions",
        "model": "gpt-4o-mini",
        "apiKey": "${OPENAI_API_KEY}",
        "temperature": 0.3,
        "supportsJsonSchema": true
      }
    },
    "agent": {
      "opencode-default": { "platform": "opencode", "bin": "opencode", "args": ["run"] }
    },
    "improve": {
      "default": {
        "processes": {
          "reflect": { "enabled": true, "mode": "llm", "profile": "openai-mini" },
          "distill": { "enabled": true, "mode": "llm", "profile": "openai-mini" },
          "consolidate": { "enabled": true, "mode": "llm", "profile": "openai-mini" },
          "memoryInference": { "enabled": true },
          "graphExtraction": { "enabled": true, "profile": "openai-mini" }
        }
      }
    }
  },
  "defaults": {
    "llm": "openai-mini",
    "agent": "opencode-default",
    "improve": "default"
  },
  "embedding": {
    "endpoint": "http://localhost:11434/v1/embeddings",
    "model": "nomic-embed-text",
    "dimension": 384
  },
  "stashDir": "~/akm"
}

This is a trimmed example focused on the core profiles and defaults. The full minimal config in docs/configuration.md also includes feedbackDistillation, index, and search top-level blocks with their defaults. If you omit those blocks, akm uses compiled-in defaults for them.

For local models, swap openai-mini for an Ollama or LM Studio profile and drop the apiKey field. The supportsJsonSchema flag tells akm to use structured JSON output for providers that support it — set it to true for OpenAI-compatible endpoints that honor response_format: {type: "json_schema"}, leave it off for local models that do not.

Migrating from v1

If you are on 0.7.x, you do not need to hand-edit your config. The migration command handles the key remapping:

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

# Apply migration — writes a timestamped backup first
akm config migrate

--dry-run shows which keys move and what the new shape looks like without writing anything. When you run without --dry-run, akm writes a timestamped backup to ~/.cache/akm/config-backups/ before touching the live file. Locate it with:

ls -1t ~/.cache/akm/config-backups/ | head

Auto-migration also runs on the first command after upgrade — a one-time notice prints to stderr with the backup path and a reminder to set AKM_NO_AUTO_MIGRATE=1 to suppress future auto-migration. That env flag is useful for read-only CI mounts where you want to run akm config migrate explicitly in a deploy step.

After migration, verify the result:

akm config get configVersion
# "0.8.0"

akm config
# Full config in the new shape

The complete old-to-new key mapping is in docs/migration/v0.7-to-v0.8.md.

What Adding a Field Looks Like Now

Before the rewrite, adding a new per-process option involved touching the parser function, the type declaration, the hint string, and the test. In the Zod schema, the same change is one line in the relevant sub-schema object. TypeScript picks up the new field automatically through inference. The JSON schema regenerates on the next build. The CI drift test catches it if the regeneration step is skipped.

The cost of that improvement is worth making concrete: the schema file is 641 LOC. The migration logic is another 643 LOC. The config loader itself is 590 LOC. That is 1,874 lines total (approximate) — replacing the ~1.4k LOC of parsers while also adding the migration pipeline, the strict validation, and the structured error reporting that were not present before. The maintenance surface per feature is lower, not higher.

Config v2 is in akm 0.8.0. The full configuration reference is in docs/configuration.md. The 0.8.0 release notes cover the broader storage and pipeline changes that landed alongside the config rewrite. If you are running the improve pipeline and want to see how the profiles.improve config behaves in practice, Your Agent Has a Memory That Runs While You Sleep covers 24 hours of autonomous operation with the full process config in place.

If you are upgrading, start with akm config migrate --dry-run and check that the output matches your expectations before applying.

The Proposal Queue Safety Net

IT Lackey — Thu, 04 Jun 2026 00:31:34 +0000

This is part fifteen in a series about managing the growing pile of skills, scripts, and context that AI coding agents depend on. Part ten introduced the improve pipeline and how it generates proposals. Part twelve covered belief-aware memory, which feeds directly into the confidence scores covered here.

The fundamental problem with agent-generated stash updates is trust. You want to capture what the agent learned — the debugging insight from last Tuesday's session, the architectural pattern it derived from reviewing twenty PRs — without blindly writing unreviewed content into the knowledge base your other agents depend on. One bad promotion and you've contaminated search results with a hallucinated fact that will keep showing up until someone notices.

akm's proposal queue is the answer to that problem. Introduced in 0.7.0 and extended in 0.8.0, it separates generation from promotion. Every agent-driven change writes to a durable queue first. Nothing reaches your live stash until you explicitly accept it. The queue is the safety net.

How the Queue Works

When akm improve or akm propose runs, the output goes to the proposal queue — not to your stash. Proposals live outside the asset tree. They never appear in akm search results and never get indexed alongside your real assets. The quality: "proposed" marker ensures this at the database level: proposed assets are excluded from default search and only surface through the akm proposal * commands or an explicit --include-proposed flag.

This means an agent can generate dozens of proposals in a single akm improve run and none of them affect your live stash until you decide they should. Multiple proposals for the same ref coexist without filesystem collisions. You can review them at your own pace, reject the bad ones, and accept the rest in whatever order makes sense.

The complete review workflow:

akm proposal list                        # see what's pending
akm proposal show <id>                   # render the full proposal content
akm proposal diff <id>                   # diff vs. the live version of that ref
akm proposal accept <id>                 # validate, then promote to stash
akm proposal reject <id> --reason "…"   # archive with a reason

akm proposal accept does not just write the file. It runs full validation and routes the write through the same writeAssetToSource() path used by akm remember and akm import. There is no bypass path. A proposal that fails validation does not get promoted.

The 0.8.0 Additions

0.8.0 reorganized the proposal commands under the akm proposal subcommand (the old flat verbs — akm proposals, akm accept, akm reject, etc. — still work as deprecated aliases until 0.9.0) and added three features that change how you interact with the queue at scale: confidence scores, expiration, and per-proposal revert.

Confidence scores. Each proposal now carries an optional confidence field (a value from 0 to 1) set by the pipeline that generated it. akm proposal show <id> includes this field in its JSON output. A high-confidence proposal is one the pipeline assessed as a strong, well-supported improvement. A low-confidence one is speculative or weakly supported. The score is not a gate — you still decide — but it gives you signal for triage. When you have thirty proposals and limited review time, work high-confidence proposals first. (The belief model that drives these scores is covered in Belief-Aware Memory.)

Expiration. Proposals expire after a configurable number of days. Set improve.archiveRetentionDays in your akm config to control the window (default: 30 days). Stale proposals that you never got around to reviewing are automatically archived rather than accumulating indefinitely. Anything that mattered enough to act on should have been reviewed before it aged out; the archive preserves the full audit trail if you need to look back.

Per-proposal revert. After you accept a proposal, akm proposal revert <id> restores the backup of the previous version. This is not a bulk operation and it is not reversible in batch. You revert one proposal at a time, by ID:

akm proposal revert <id>    # restore the backup for a specific accepted proposal

The no-batch-revert constraint is intentional. Bulk accept without bulk revert is the guardrail that forces deliberate review. If you accept fifty proposals in a single command and three of them are bad, you revert those three individually. The discipline is the point — if you were going to bulk-revert, it means you bulk-accepted without reviewing, and the queue exists precisely to prevent that pattern.

Bulk Accept Guardrails

For cases where you want to process more than one proposal at a time without bypassing judgment entirely, 0.8.0 extended akm proposal accept with generator-scoped batch flags.

akm proposal accept supports generator-scoped bulk operations. When you want to accept all pending proposals from a specific generator, pass --generator without a positional id. Bulk accept requires -y/--yes:

akm proposal accept --generator reflect --yes        # accept all reflect proposals
akm proposal accept --generator distill --yes        # accept all distill proposals

The --yes flag removes the interactive confirmation prompt required in non-interactive shells. Use it only after you have already reviewed the queue via akm proposal list and akm proposal diff. Bulk accept without prior review is exactly the pattern the queue exists to prevent.

Auto-Accept for Trusted Sources

If you have a source you fully trust — a well-constrained task asset running against a curated input set, or a distill job that only ever touches a specific category — you can set a high autoAccept threshold in that improve profile. Proposals whose confidence meets or exceeds the threshold are promoted directly to the stash without manual review.

This is off by default and should stay off for most sources. The value of the queue is exactly that it sits between agent output and your live stash. Auto-accept makes sense only when the source is trusted, the scope is narrow, and you are comfortable with the output quality from experience rather than assumption.

A Daily Review Habit

The proposal queue only helps if you actually review it. Left unattended, it either accumulates into a backlog that's too large to meaningfully triage, or proposals expire before you get to them. A brief daily review pass keeps it manageable.

The workflow that works:

# Start with the full pending list
akm proposal list

# For each proposal worth reading, diff it against the live ref
akm proposal diff <id>

# Accept the ones that look right
akm proposal accept <id>

# Reject the ones that don't, with a reason you'll understand later
akm proposal reject <id> --reason "hallucinated — no source for this claim"

The diff is the most useful step. akm proposal diff <id> shows you the delta between the proposal and whatever currently exists for that ref in your live stash. A proposal that adds accurate new context to a ref you already maintain is easy to accept. A proposal that rewrites a ref you know well with confident-sounding but unverifiable claims is easy to reject. The diff makes the difference visible.

If the queue is empty, the daily review takes thirty seconds. If akm improve ran overnight and produced twenty proposals, budget ten minutes. The point is not to process every proposal — it is to stay close enough to the queue that nothing accumulates into a block of work large enough to skip.

For teams running akm improve on a schedule, the confidence scores make triage faster. High-confidence proposals need a quick diff and a decision. Low-confidence proposals need closer reading or an outright reject. Over time, the pattern of what the pipeline marks as high-confidence and what actually turns out to be good teaches you where to focus attention.

The Shape of Safe Agent Memory

The proposal queue is not a bureaucratic checkpoint. It is the mechanism that makes it safe to run akm improve continuously, trust agent-driven reflection passes, and still maintain a knowledge base where you know what is in it and why.

Without the queue, you are choosing between running the improve pipeline (accepting everything it produces) or not running it (getting nothing it produces). The queue is the third option: run it continuously, review the output deliberately, promote what earned it. The 0.8.0 guardrails — confidence scores, expiration, per-proposal revert, and generator-scoped bulk accept — are the tools that make that third option practical at the scale continuous operation produces.

The proposal queue is available as of akm 0.7.0. The 0.8.0 additions — confidence scores, expiration, akm proposal revert, and generator-scoped bulk accept — require 0.8.0 or later. Full reference at docs/cli.md and the configuration reference.

Your Agent Has a Memory That Runs While You Sleep

IT Lackey — Thu, 04 Jun 2026 00:31:26 +0000

This post is part of the akm-knowledge series. Part ten introduced the improve pipeline — what each phase does and how to schedule it. This post goes deeper on what continuous operation looks like in practice: the hardware numbers, the reliability bugs we hit at 48 runs per day, and the observability layer we built to keep watch.

Most people think of AI agent memory as something that happens during a session. You talk to your agent, it learns things, maybe you save a few notes, the session ends. The next session starts cold.

akm improve is built around a different model: a continuous background process that runs on your own hardware, against local models, and quietly curates your agent's knowledge base while you work on other things. No cloud API required. No per-token billing for the maintenance pass. A GPU you already own, a model you already have downloaded, running on a schedule.

This post covers what 24 hours of autonomous operation actually looks like, how consumer-grade GPUs handle the load, the reliability work that makes continuous operation viable, and the observability layer that lets you know it's working without watching logs.

What akm improve Does in 24 Hours

akm improve is a multi-phase pipeline. The core pass — consolidation — loads your memory pool, groups related memories into chunks, sends each chunk to a local LLM for a consolidation plan (merge similar memories, promote high-signal ones to your stash, delete redundant ones, surface contradictions), and then executes those plans. After consolidation, memory inference runs a lightweight factual extraction pass, and graph extraction updates the entity-relation index.

The pipeline is scheduled to run automatically. Here is what one 24-hour window produced:

Metric	Value
Runs completed	48 / 48 — zero failures
Memories processed	14,189
Promoted to stash	1,361
Merged (deduplication)	49 (64 secondaries absorbed)
Contradictions surfaced	211
Deleted (redundant)	31
Memory inference yield	69.3% — 115 new atomic facts written
Graph entities extracted	181 across 9 files
Task fail rate	0%
Index entries	7,398 — all embedded, status `ready-vec`

Every run that completes leaves your stash in better shape than before it started. Memories that accumulated across dozens of agent sessions get compressed, merged, and organized without manual intervention. The 1,361 promotions in this window represent memories that were considered significant enough by the local LLM to persist as named stash entries. The 49 merges collapsed near-duplicate content. The 211 contradictions were flagged for review rather than silently overwritten.

This is the loop. It runs every 30 minutes. You don't have to think about it.

Running It on Consumer Hardware

The consolidation LLM in this setup is qwen3.5-9b (or similar) running locally via LM Studio on an OpenAI-compatible endpoint. The model fits comfortably on most modern gaming GPUs. No API key. No per-call cost. The inference happens on hardware sitting on your desk.

We run two LM Studio servers — both serving the same model via OpenAI-compatible endpoints — and benchmarked them head to head.

Shredder is a desktop with an RTX 5090. Splinter runs an RTX 4060 Ti, a card that launched at $299 and is common in mid-range gaming builds. Same model weights. Same chunk sizes. Different VRAM bandwidth and tensor core counts.

	RTX 5090 (Shredder)	RTX 4060 Ti (Splinter)
Per-chunk latency	~6.8s	~22.6s
13-chunk consolidation	~87s (~1.5 min)	~290s (~4.8 min)
Speed ratio	1× (baseline)	3.3× slower
Runs per hour (fits schedule)	✅ yes	✅ yes
Approximate street price	~$2,000	~$300

The 5090 is faster, but the 4060 Ti finishes a full consolidation pass in under 5 minutes — well inside the 30-minute run window. Both cards sustain 48 runs per day without missing a cycle.

Where the gap shows up is in the tail. Because the 24h window included runs on both backends, the aggregate latency numbers reflect both:

Phase	Median	P95	What drives the P95
Total (end-to-end)	7.2 min	23.4 min	Splinter-routed consolidation runs
Consolidation	1.4 min	5.8 min	Chunk count variance + Splinter
Memory inference	5.9s	25.3s	Fresh (non-cached) inference attempts
Graph extraction	< 1s	53s	Cache misses on modified files

The median of 7.2 minutes reflects the majority of runs going to Shredder. The P95 of 23.4 minutes is almost entirely Splinter runs with larger chunk windows. A setup running exclusively on a 4060 Ti would see a flatter distribution — median around 10–12 minutes, P95 around 18–20 minutes — with no 5090 runs pulling the median down.

For most setups, a single mid-range GPU is the right starting point. The consolidation pass is CPU-light and network-light — the bottleneck is token generation throughput on the GPU. If you have a second machine with a GPU and spare VRAM, you can point a second LM Studio server at it and split load exactly as we did here.

The embeddings server is separate — nomic-embed-text-v1.5 running on localhost — and handles the semantic search index. It stays warm between runs, so re-embedding after promotions adds negligible latency. Any GPU with 4GB+ of VRAM can host it alongside the consolidation model if you have the headroom, or it runs on CPU at acceptable speed for indexing workloads.

What "Local Models" Actually Means for Quality

The concern with local models is usually quality: will a 9B parameter model running on a gaming GPU produce consolidation plans good enough to trust with your knowledge base?

The answer, based on 48 runs and 14,189 memories, is yes — with the right constraints.

The consolidation prompt is designed to be conservative. The LLM is asked to identify candidates for merge, promote, or delete within a bounded chunk of related memories. It is not given unbounded latitude. Plans are validated against the loaded memory pool before execution — if the model invents a ref that doesn't exist, the op is dropped with a warning. If a promoted memory fails schema validation, it is rejected.

The 69.3% yield rate on memory inference tells the same story. Out of 166 fresh attempts at factual extraction, 115 produced usable atomic facts. The model is making useful inferences at a rate that justifies running it continuously.

The practical limit of local 9B models shows up in graph extraction: 2 truncations in the 24h window indicate chunks that exceeded the model's context window. These produce partial rather than failed extractions — the model handles what it can see. Larger models extend this ceiling; a 5090 can hold larger quantizations in VRAM.

Making Continuous Operation Reliable

Running 48 times a day means reliability issues that would be minor in a manual workflow become systemic. Two bugs were affecting the consolidation pass and wasting inference on every affected run.

The stale database problem. After a run that deleted files, the database retained entries pointing to files that no longer existed on disk. The next run loaded those ghost entries, the LLM generated merge plans against them, and Phase B failed silently when the file wasn't found. Every affected secondary in those plans was charged a wasted inference call.

The fix is a pre-flight filter that runs before the LLM sees anything:

memories = memories.filter((m) => fs.existsSync(m.filePath));

Stale entries never reach the model. A warning is logged so the count is visible in health output if the filter ever catches something:

Pre-flight: filtered 3 stale DB entries (file absent on disk) from memory pool before chunking.

The hallucination problem. On certain chunk compositions — particularly when session checkpoint memories and named sessions appear in the same window — the local model would blend naming conventions and produce a merge plan with a primary ref that didn't exist in the pool.

A typical example: memory:opencode-session-20260529-a1b2 and memory:checkpoint-20260529T214550 in the same chunk produce a hallucinated primary of memory:opencode-session-20260529T214550-ses_18a4. The plan looks reasonable at the chunk level. The ref doesn't exist at the pool level.

Before the fix, that hallucinated primary would reach Phase B and charge every real secondary (typically 4–8 refs) with a failed merge skip. After the fix, mergePlans() validates every primary ref against the loaded pool before execution:

const knownRefs = new Set(memories.map((m) => `memory:${m.name}`));
const { ops: allOps, warnings: mergeWarnings } = mergePlans(chunkOpsArrays, knownRefs);

Real merge plans proceed. Hallucinated roots are dropped. The warning is distinguishable from the stale-DB warning, so health metrics can tell the two apart:

mergePlans: primary memory:... not in loaded memory pool (LLM hallucination) — dropping op before execution.

Both fixes eliminate wasted inference. On the 4060 Ti at 22.6s per chunk, a single hallucinated primary that would have charged 6 secondaries saves over 2 minutes of inference time per occurrence — time that can go toward real consolidation work instead.

Knowing It's Working

Running autonomously in the background only helps if you know when something goes wrong. akm health provides a structured view of recent improve activity:

akm health --since 4h
akm health --since 24h --format text

It surfaces run counts, skip reason breakdowns, consolidation outcomes, memory inference yield, and phase latencies in a single command. The same JSON output feeds automation.

For continuous monitoring, we built a cron task that posts a rolling 4-hour health report to Discord every hour:

# ~/akm/tasks/akm-health-report.yml
schedule: 0 * * * *
command: akm env run fwdslsh -- bash ~/akm/scripts/akm-health-discord.sh
enabled: true

The script calls akm health --since 4h and --since 8h, computes deltas for trend context, and posts a Discord embed:

akm tasks sync   # register the cron

The embed has three inline fields — Output (promoted, merged, MI yield), Failures (chunk failures, skip reason anomalies), and Latency (median, P95, previous-window comparison) — plus a Needs Attention section that only appears when something is actually off. The footer includes the hostname and timestamp so reports from multiple machines are distinguishable at a glance.

The result: a health check fires every 30 minutes from the pipeline, and a visibility report fires every hour to Discord. You see degradation before it accumulates.

The Full Picture

Here is what autonomous local-model memory curation looks like across a full day:

48 runs completed without intervention
14,189 memories reviewed, organized, and curated
1,361 promoted to the permanent stash
1.4 minute median per consolidation pass on the faster GPU; under 5 minutes on the 4060 Ti
Zero API calls — all inference runs locally on hardware you own
Hourly Discord reports — no manual health checks needed

The hardware requirement to run this continuously is a mid-range gaming GPU. The model requirement is a 7–9B parameter instruction-tuned model quantized to 4–8 bits. Both are things a lot of developers already have.

The value is in what compounds. Each run makes the stash slightly more accurate, slightly more consolidated, slightly more consistent. After 48 runs, 14,000 memories have been through a curation pass that would have taken hours to do manually. After a week, the stash is a different kind of asset — not a pile of notes, but a continuously maintained knowledge base that your agent can rely on across sessions.

akm improve is part of akm 0.8.x. The full pipeline configuration and local model setup docs are in the configuration reference. Hardware requirements and LM Studio setup are covered in the getting started guide.

From 30 Minutes to 8: How LLM-Mode Reflect Works

IT Lackey — Thu, 04 Jun 2026 00:31:15 +0000

This is part thirteen in a series about managing the growing pile of skills, scripts, and context that AI coding agents depend on. Part ten covered the full improve pipeline — all five phases and how they connect. Part fourteen covers what 48 runs per day looks like in practice, including hardware benchmarks and the reliability bugs that surface at that frequency.

The reflect pass inside akm improve has three execution modes. Most installs are still running the slowest one.

Agent mode — the original — spawns an opencode or claude subprocess for each reflect call. The subprocess starts cold, acquires a session, assembles context, makes its LLM call, and exits. That cold-start overhead is real: each call takes approximately 30 seconds on a quiet machine. Run akm improve against a 69-ref stash and the reflect phase alone costs about 35 minutes.

SDK mode eliminated the subprocess. The reflect call runs in-process, cutting per-call latency to 10–15 seconds. A 69-ref run drops to 12–17 minutes — better, but still bounded by round-trip overhead that the reflect task does not actually need.

LLM mode removes the round trip entirely. The context for reflect is statically pre-assembled — no live tool calls, no file reads, no external context needed. A direct HTTP call to the LLM endpoint is sufficient, and it costs 6–10 seconds per call. A 69-ref run completes in 8–10 minutes.

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

The 3–4× end-to-end improvement is from eliminating overhead that was never necessary for what reflect does.

Why Reflect Does Not Need an Agent

The reflect pass takes a stash asset, examines its current content, and proposes a refined version. The inputs are fixed before the pass starts: the asset text, its metadata, and the improvement prompt. Nothing changes mid-call. No files need to be opened. No search queries need to fire. No external context needs to be pulled in.

Agent mode was useful when akm's improve pipeline was first built — the agent subprocess was already the primary execution model, and reflect rode along. But the properties that make agents valuable (tool use, live context access, multi-step reasoning over changing state) are not exercised by reflect. Spawning a full agent process for a stateless inference call trades 20+ seconds of overhead for no quality benefit.

LLM mode makes the execution match the task: assemble the context once, make one HTTP call, get the result.

Multi-Turn Self-Refine

LLM mode adds a capability that agent mode does not have: multi-turn self-refine.

When reflect runs in LLM mode, it sends the initial draft back as an assistant turn. The model sees its own prior output and the refine prompt together in the same context window. This is a standard multi-turn pattern for iterative generation — the model can catch inconsistencies, tighten reasoning, and improve the draft without requiring a second top-level call.

Agent mode, by contrast, passes context forward through prompt text. Each subprocess run starts fresh. There is no conversation history to reason against.

The practical difference shows on longer or more complex assets, where a single forward pass produces a draft with inconsistencies the model catches immediately when it sees its own output. Multi-turn self-refine handles this inside the single reflect call.

Structured Output

For providers that advertise supportsJsonSchema: true in their profile config, LLM mode requests structured JSON output. The response is validated against the reflect output schema before being accepted as a proposal.

This eliminates a class of parse failures that occurs when a model returns well-formed prose but with section markers or formatting that does not align with the expected output shape. The model knows the schema before it generates the response, so the output conforms rather than being post-hoc parsed.

Agent mode produces unstructured text that the pipeline parses with heuristics. LLM mode with supportsJsonSchema: true eliminates the heuristics.

Config to Enable LLM Mode

LLM mode requires Config v2 (configVersion: "0.8.0"). If you have not migrated yet:

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

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

With v2 in place, add a named LLM profile and point the reflect process at it:

{
  "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" }
}

That is the complete change. On the next akm improve run, reflect dispatches HTTP calls to the openai-mini profile instead of spawning subprocesses. The proposal queue, review workflow, and everything downstream are unchanged.

Local Models and LM Studio

The profile config is an endpoint and a model name. Nothing in the LLM mode path is OpenAI-specific — it issues standard chat completions requests. Any OpenAI-compatible server works, including LM Studio running locally.

To point reflect at a local LM Studio instance:

{
  "configVersion": "0.8.0",
  "profiles": {
    "llm": {
      "local-reflect": {
        "endpoint": "http://192.168.1.100:1234/v1/chat/completions",
        "model": "your-local-model-name",
        "supportsJsonSchema": false
      }
    },
    "improve": {
      "default": {
        "processes": {
          "reflect": { "mode": "llm", "profile": "local-reflect" }
        }
      }
    }
  }
}

Set supportsJsonSchema: false unless you have confirmed that the local model and LM Studio version support structured output. Most local models handle the reflect task correctly through standard chat completions without schema enforcement — the output is smaller and more predictable than consolidation plans, so parse failures are rare.

For a machine running a 9B model on an RTX 4060 Ti, LLM mode reflect benchmarks in the 8–12 second range per call — comparable to the cloud figures in the table above, with no API costs and no data leaving your network.

When to Stay on Agent Mode

LLM mode is appropriate for reflect because reflect has static inputs. Other improve processes do not share that property.

Stay on agent mode when the process needs live tool calls. If you have a custom improve workflow that reads files, calls akm search, or pulls external context mid-run, that process requires an agent that can execute tools. LLM mode does not have tool dispatch — it is a direct HTTP call to a completions endpoint, nothing more.

Stay on agent mode when the reflect task for a specific asset type requires context that is assembled dynamically — search results, graph lookups, or file reads that depend on the asset's content. Those lookups require a running agent.

The standard reflect pass — refining an existing asset based on its content and metadata — does not require either of these. LLM mode is the right default for it.

What Changes in Practice

A 69-ref akm improve run that used to block for 35 minutes now completes in under 10. The reflect proposals are the same quality — in some cases better, because multi-turn self-refine catches first-draft inconsistencies. Structured output for cloud providers eliminates parse failures that previously required manual retries.

The change is a config update:

# Migrate config if still on v1
akm config migrate

# Then add the llm profile + reflect process entry (see snippet above)
# Preview what the next run would process without writing anything
akm improve --dry-run

The next improve run after that shows reflect calls completing in the 6–10 second range instead of 30.

LLM mode reflect is available in akm 0.8.0. The full configuration reference is in docs/configuration.md. The Config v2 key mapping is in the v0.7 to v0.8 migration guide.

For a broader view of the improve pipeline — all five phases, scheduling, and how reflect feeds the downstream consolidation and distill passes — see The Improvement Loop: How akm Keeps Your Agent Sharp. For debugging improve runs when something goes wrong (stale DB entries, hallucinated merge plans, pre-flight filters), see Your Agent Has a Memory That Runs While You Sleep.

Belief-Aware Memory: Teaching Your Agent When Not to Write

IT Lackey — Thu, 04 Jun 2026 00:31:07 +0000

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.

The Two Capture Modes

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.

The Belief States

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.

What the Improve Loop Actually Checks

When akm improve starts a consolidation chunk, it evaluates captureMode before making any LLM call. The sequence is:

Load the memory pool for the chunk.
Check captureMode for every memory in the chunk.
If all memories are hot, record the chunk as judgedNoAction and skip to the next chunk. No model call.
If any memory is 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.
The model sees 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.

Enabling Belief-Aware Memory

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 Workflow in Practice

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.

What This Protects Against

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.

Task Assets: Agent Workflows That Run While You Sleep

IT Lackey — Thu, 04 Jun 2026 00:30:58 +0000

This is part eleven in a series about managing the growing pile of skills, scripts, and context that AI coding agents depend on. Part nine covered workflow assets and resumable procedures. Part ten introduced the improve pipeline that continuously curates your stash. Earlier parts addressed teams, distributed stashes, and community knowledge.

Most automation with AI agents is reactive. You open a session, give the agent a task, wait for the result, close the session. The agent's clock runs when you run it.

Task assets flip that model. A task is a YAML file in your stash that defines a workflow — what to run, when to run it, what environment it needs, and how long it's allowed to take. Once registered, the task runs on schedule without your involvement. The OS scheduler calls akm tasks run <id>, which executes the task and writes the result to state.db. You find out what happened when you check akm health or look at the log.

This is the piece of akm 0.8.0 that makes continuous operation possible. The improve loop runs twice an hour because a task asset says it does. The hourly Discord health report fires because a task asset says it does. Neither requires an open terminal.

The Task Asset Format

Task assets live at <stash>/tasks/<id>.yml. The filename is the task ID. A minimal task looks like this:

schedule: 0 * * * *
command: akm improve --auto-accept 90
enabled: true

That's enough to install a cron entry and run akm improve at the top of every hour. The full schema adds metadata and per-task timeout control:

schedule: "7,37 * * * *"
command: akm improve --auto-accept 90 --timeout-ms 1620000
enabled: true
timeoutMs: 1800000
name: akm-improve
description: Run the improve pass at :07 and :37 — reflect, distill, consolidate, lint, and eval.
when_to_use: Twice per hour; leaves ~23 minutes of idle headroom between completions.
tags:
  - improve
  - maintenance

The fields that matter most:

Field	Required	Purpose
`schedule`	yes	Standard cron expression. Maps to crontab on Linux, launchd plist on macOS, schtasks XML on Windows. Wrap expressions containing special characters in quotes.
`command` or `prompt`	one of the two	`command` runs as a plain shell command. `prompt` dispatches through the configured agent profile. A third option, `workflow`, targets a stash workflow ref directly.
`enabled`	yes	`false` keeps the task definition in your stash without installing a scheduler entry.
`timeoutMs`	no	Per-task timeout in milliseconds, overriding whatever the agent profile sets globally. `null` removes the kill timer entirely — useful for long-running local-model tasks.
`name`, `description`, `when_to_use`, `tags`	no	Metadata. `name` appears in `akm tasks list`; the others exist for your own records and for search.

command: vs prompt:

The distinction between command and prompt reflects two different execution models.

A command task is a shell invocation. akm tasks run executes the string directly in a child process. There is no agent involved. The command can call akm, run a shell script, invoke any binary. The exit code is what gets logged.

command: akm improve --auto-accept 90

A prompt task dispatches to the agent configured in your default agent profile (or the profile specified in --profile). The value of prompt becomes the task instruction. The agent runs autonomously, can use akm commands, write files, and call tools according to its allowed tool set. The result is determined by whether the agent exits cleanly.

prompt: |
  Run akm wiki ingest research and then run akm wiki lint research.
  Fix any orphan pages the lint step reports.

The practical split: use command for tasks where the execution is fully scripted and the outcome is deterministic. Use prompt when you want the agent to exercise judgment — synthesizing content, triaging output, making decisions based on what it finds. The curate-to-wiki task is a good example of the latter: it runs a multi-step workflow where the agent reads each step's instructions, substitutes parameters, and advances the workflow run through to completion. Workflow assets themselves are covered in part nine of this series.

Registering Tasks

There are two ways to get a task into the scheduler.

The first way is akm tasks add, which creates the YAML file and installs it in one step:

akm tasks add my-task \
  --schedule "0 9 * * *" \
  --command "akm improve --auto-accept 80" \
  --name "Morning improve pass" \
  --description "Daily improve at 9 AM"

The second way is to write the YAML file directly into your stash's tasks/ directory and then call:

akm tasks sync

sync reconciles all .yml files in tasks/ against the OS scheduler. Any task that's enabled: true and not yet installed gets a scheduler entry. Any task that's enabled: false or missing gets its entry removed. This is the right command to run after pulling stash changes that include new or updated task files.

Other task management commands:

akm tasks list                        # all defined tasks with status
akm tasks show <id>                   # parsed YAML + scheduler state
akm tasks run <id>                    # execute immediately
akm tasks enable <id>                 # install the scheduler entry
akm tasks disable <id>                # remove the scheduler entry, keep the file
akm tasks remove <id>                 # delete the file and uninstall
akm tasks history [--id <id>]         # recent runs from state.db
akm tasks doctor                      # scheduler backend + cron path

akm tasks run is the same command the scheduler calls. You can run a task immediately to test it before committing it to a schedule.

Environment Injection with akm env run

Tasks that need secrets or environment-specific configuration use akm env vaults. A vault is an encrypted .env file stored in your stash under env/<name>.env. You inject it into a child process using akm env run:

akm env run env:fwdslsh -- bash ./scripts/post-to-discord.sh

The env: prefix is the canonical ref form. In task YAML, akm also resolves bare vault names — the worked example below uses the bare name to match the production file exactly.

In a task command field, the same pattern applies directly:

command: akm env run fwdslsh -- bash /home/founder3/akm/scripts/akm-health-discord.sh

This injects every variable in the fwdslsh vault into the shell process that runs the script. The variables live only in that child process — they are never written to disk or exported to the parent environment. The task definition itself contains no secrets, only the vault reference. You can commit task YAML to your stash and share it without exposing credentials.

If a task needs only a subset of the vault's variables, --only narrows the injection:

akm env run env:fwdslsh --only DISCORD_WEBHOOK_URL -- bash ./post.sh

--only accepts a single key or a comma-separated list. Use --except to inject everything in the vault except specific keys.

Worked Example: The Discord Health Report

This is the health report task used in production to monitor the improve pipeline:

# ~/akm/tasks/akm-health-report.yml
schedule: 0 * * * *
command: akm env run fwdslsh -- bash /home/founder3/akm/scripts/akm-health-discord.sh
enabled: true
name: AKM Health Report → Discord
description: "Hourly: post a 4h rolling health report to Discord. Driven by
  akm health --since=4h — same data source as manual reports."
tags:
  - health
  - discord
  - monitoring

The task fires at the top of every hour. It injects the fwdslsh vault (which contains the Discord webhook URL and any other credentials the script needs), then runs the health report script. The script calls akm health --since=4h and akm health --since=8h, computes deltas between the two windows for trend context, and posts a formatted embed to Discord.

The embed has three inline fields — Output (promoted refs, merged memories, memory inference yield), Failures (chunk failures, skip reason anomalies), and Latency (median, P95, prior-window comparison) — plus a Needs Attention section that only appears when something is actually off. The footer includes the hostname and run timestamp so reports from multiple machines are distinguishable at a glance.

To register the task after writing the YAML:

akm tasks sync
akm tasks list
# → akm-health-report   0 * * * *   enabled   last run: —

Run it once immediately to confirm the script works before relying on the scheduled version:

akm tasks run akm-health-report

Check the result:

akm tasks history --id akm-health-report --limit 5

Logging

Every task run is recorded in state.db under the task_history table. akm tasks history surfaces that data. For log output, each run writes to:

~/.cache/akm/tasks/logs/<id>.log

akm health inspects task_history for missing log files, stale active runs (tasks that started but never completed), and recent failure rates. A task run that never wrote a tasks_completed event shows up in akm health output as a stuck active run — a reliable signal that something went wrong even if the log file doesn't say much.

akm health --since 4h

The health check correlates the task_history events with the log files on disk. If a log file is missing for a completed run, logBackingRate drops below 1.0, which flags as a warning. This is the task-log-backing hard check — one of the deterministic checks that akm health runs before it looks at any metrics.

Building a Task-Driven Operation

The pattern that emerges from several tasks working together is an operation that runs itself. The improve loop consolidates and curates the stash twice an hour — what that pipeline does internally is covered in part ten. The health report surfaces the results every hour. A daily curation task pulls new articles from configured sources and ingests them into the research wiki. None of these require an open terminal.

Adding a new automated behavior follows the same steps regardless of what the task does:

Write the YAML to <stash>/tasks/<id>.yml.
Run akm tasks sync to install the scheduler entry.
Run akm tasks run <id> to test it immediately.
Confirm the output with akm tasks history and check the log.
Add the task file to git if you want it version-controlled with your stash.

The task YAML is the contract between what you want to happen and when it happens. The log and state.db are the record of what actually did.

Task assets are available in akm 0.8.0. The full command reference is in docs/cli.md. The environment vault documentation is in docs/cli.md. If you're upgrading from 0.7.x, task .md files from the old format are not auto-discovered — check the migration guide for the conversion path.

The Improvement Loop: How akm Keeps Your Agent Sharp

IT Lackey — Thu, 04 Jun 2026 00:30:50 +0000

This is part ten in a series about managing the growing pile of skills, scripts, and context that AI coding agents depend on. Part nine covered workflow assets, vault assets, and the writable git stash. Part eight tackled multi-wiki support for structured research. Earlier parts addressed teams, distributed stashes, feedback scoring, and community knowledge.

This one is about entropy.

You ship a feature. Your agent writes several memories during the session — partial findings, a workaround, a note about the build step that kept failing. Those memories are accurate when written. Three sprints later, the workaround is no longer needed, two of the memories say slightly different things about the same subsystem, and the note about the build step refers to a CI config that was replaced. None of this is catastrophic. But it accumulates. After six months, a significant fraction of your stash is stale, redundant, or quietly wrong.

You could audit it manually. In practice, you won't — the stash is too large, the relevance of any given memory is hard to assess without the context where it was created, and the judgment calls (merge these two? promote this? delete that?) are exactly the kind of work that's tedious for a human and tractable for an LLM.

akm improve is the answer to that problem. It is a multi-phase pipeline that reads your stash, evaluates asset quality, consolidates scattered memories, extracts structured facts, and maps entity relationships — on a schedule, without manual intervention, producing proposals you can review before anything changes.

The Five Phases

akm improve is not a single LLM call. It is a sequenced pipeline where each phase produces inputs for the next.

Reflect evaluates asset quality. For each asset in scope, the reflect pass reviews the content against usage signals — search hits, retrieval counts, feedback — and produces a quality assessment. Low-quality assets are flagged as candidates for improvement. Since 0.8.0, reflect can run as a direct LLM HTTP call instead of spawning an agent subprocess, which cuts per-call latency from ~30 seconds to ~6–10 seconds:

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

Distill turns observations from reflect into lesson proposals. Where reflect says "this skill is incomplete and frequently retrieved with poor satisfaction," distill produces a draft improvement — a new version of the skill, a supplementary lesson, or a deprecation proposal. These proposals go into the queue; nothing is written to your stash until you accept them.

Consolidate handles the memory pool specifically. Your memory pool accumulates entries from agent sessions — akm remember calls, auto-captured observations, and task agent outputs. Consolidation groups related memories into chunks, sends each chunk to the LLM for a curation plan (merge near-duplicates, promote high-signal items, delete redundant entries, surface contradictions), and executes those plans. The result is a smaller, cleaner memory pool and new stash promotions.

Memory inference runs after consolidation. It takes the post-consolidation state and runs a lightweight factual extraction pass — pulling out atomic facts that did not make it into explicit memory entries. These become additional promotion candidates. In steady-state operation, memory inference yields around 60–70% (69.3% in a recent 24-hour window) usable atomic facts on each pass.

Graph extraction runs last, against the final post-improve state. It builds the entity-relation index that powers akm graph commands — which stash entries mention a given entity, which entities co-occur, and which assets produced zero entities (quality-triage candidates via akm graph orphans). As of 0.8.0, extraction is incremental: only assets that changed during the improve run are re-extracted, and batches of four run in parallel by default.

Each phase is independently enabled or disabled per profile. A quick profile runs reflect only. A memory-focus profile runs reflect and memory inference on memory and lesson types. A thorough profile runs all five phases and auto-syncs the result to your git-backed stash.

Running the Loop

The basic invocation:

akm improve

That runs all enabled phases on the full stash, scoped by your default improve profile. Before running for the first time, use --dry-run to see what would be processed without writing anything:

akm improve --dry-run

The dry-run output shows which assets are selected, in what order, and which phases would run. Nothing is written to state.db from the dry-run path — the improve result is flagged .dryRun: true and excluded from health metrics.

To scope the pass to a specific asset type:

akm improve memory          # memory pool only
akm improve skill           # skills only
akm improve skill:deploy    # one specific asset

To add extra guidance for the pass — useful when you know a particular focus area is relevant:

akm improve --task "focus on deduplication in the build tooling notes"

To cap the number of assets processed (highest-utility first by default):

akm improve --limit 20

The asset selection order is: assets with recent feedback signals first, then high-retrieval-count assets with no feedback, then everything else. Use --require-feedback-signal to restrict the pass to assets that have received explicit feedback and skip the retrieval fallback entirely.

Profiles

A profile controls which phases run, which LLM connections are used, whether auto-sync fires at the end of the run, and the confidence threshold for auto-accepting proposals. Built-in profiles:

Profile	Phases	Auto-sync	Auto-push
`default`	All five	Yes	Yes
`thorough`	All five, larger batches	Yes	Yes
`quick`	Reflect only	No	No
`memory-focus`	Reflect + memory inference, memory and lesson types only	No	No

Pass --profile to override for a single run:

akm improve --profile quick
akm improve --profile memory-focus

Define custom profiles in your config under profiles.improve.<name>. Each process entry in the profile uses a unified {mode, profile, timeoutMs, options} shape, so you can point reflect at a fast local model and consolidation at a more capable one:

{
  "configVersion": "0.8.0",
  "profiles": {
    "llm": {
      "fast": { "endpoint": "http://localhost:1234/v1/chat/completions", "model": "qwen3.5-9b" },
      "careful": { "endpoint": "http://192.168.0.99:1234/v1/chat/completions", "model": "qwen3-32b" }
    },
    "improve": {
      "default": {
        "processes": {
          "reflect": { "mode": "llm", "profile": "fast" },
          "consolidate": { "mode": "llm", "profile": "careful" }
        }
      }
    }
  }
}

The Proposal Queue

Every improvement that akm improve generates flows through the proposal queue before touching your stash. Nothing is written directly. The queue is the safety layer.

After a run, review what was generated:

akm proposal list
akm proposal list --status pending

Inspect a specific proposal:

akm proposal show <id>
akm proposal diff <id>       # side-by-side diff vs. the live asset

Accept or reject:

akm proposal accept <id>
akm proposal reject <id> --reason "duplicates the deployment-gotchas lesson"

akm proposal accept runs full schema validation before writing anything to the stash. Accepted proposals are promoted as normal stash assets and become immediately searchable.

The --auto-accept flag enables confidence-threshold-based auto-promotion. The default safe threshold is 90 — proposals where the LLM scored its own confidence at 90 or above are promoted automatically; everything below goes to the queue for manual review:

akm improve --auto-accept=90     # explicit threshold (same as the default)
akm improve --auto-accept=false  # disable auto-accept, send everything to queue

For the first few runs on a new stash, disable auto-accept and review the queue manually. Once you have a sense of what the pipeline generates, you can raise the threshold progressively.

Scheduling

Running akm improve once is useful. Running it continuously is where the compounding starts.

The pipeline is designed to run on a cron schedule. In production, every 30 minutes is a common cadence — enough time for the consolidation LLM calls to complete, short enough that memories from any given session get curated within the hour.

Define a task asset to schedule it:

# ~/akm/tasks/improve-loop.yml
name: improve-loop
trigger:
  cron: '*/30 * * * *'
agent:
  command: akm
  args: ["improve", "--profile", "default", "--limit", "30"]
enabled: true

akm tasks sync

After that, akm improve runs every 30 minutes without manual intervention. The --limit 30 cap keeps each run predictably bounded. If there is nothing worth improving — no new feedback, no high-retrieval zero-feedback assets — the run completes quickly after selection with zero proposals generated.

For git-backed stashes, the default and thorough profiles auto-commit at the end of each run. The commit message template is configurable:

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

Use --no-sync to suppress the commit for a specific run, or --no-push to commit locally without pushing.

Knowing the Loop Is Working

akm health gives you a structured view of recent improve activity without querying SQLite directly:

akm health --since 24h
akm health --since 4h --format text

The output covers run counts, skip reason breakdowns, consolidation outcomes, memory inference yield, and phase latencies. If a run was a dry-run, it is excluded from the health metrics automatically.

After any significant stash change, running akm health is the fastest way to confirm the pipeline is in a healthy state rather than silently stuck on a locked journal or a stale database entry.

What Changes Over Time

The value of the improve loop is not in any single run. It is in what accumulates.

After a week of 30-minute cycles on an active stash, the memory pool is smaller and more coherent. Duplicate memories from related sessions have been merged. High-signal observations have been promoted to named stash entries your agent can reference directly. The graph extraction index has been built up incrementally so akm graph entity <name> returns useful results instead of nothing.

After a month, the stash reflects your actual working patterns rather than the raw notes from when you first captured something. Assets that were retrieved frequently and rated poorly have been flagged and improved. Assets that were never retrieved have surfaced as candidates for deletion or consolidation. The memory you have is accurate to what you know now, not what you wrote six months ago.

That is the loop. It runs while you work. It runs while you sleep. Each pass leaves the stash slightly more accurate, slightly more consolidated, slightly more useful. The proposals it generates are the visible surface — the queue where you can see what the pipeline decided and override it. The underlying stash quality improvement is what compounds.

akm improve is part of akm 0.8.x. The full pipeline configuration reference is at docs/configuration.md. Profile options, LLM connection setup, and scheduling details are in the improvement loop feature doc. For a concrete look at 24 hours of autonomous operation — hardware benchmarks, the two reliability fixes that make continuous runs viable, and the Discord health report setup — see Your Agent Has a Memory That Runs While You Sleep. The repo is at github.com/itlackey/akm.

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

IT Lackey — Wed, 03 Jun 2026 22:36:48 +0000

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:

Update any scripts or automation that still target the pre-0.8 proposal queue and indexing workflow.
Prefer akm improve for the main refinement/maintenance workflow.
Stop calling akm index --enrich; use plain akm index plus akm improve maintenance flows.
Use akm health --since 24h after upgrade to confirm state-db and task-history health.
Rename proposal queue commands as per the table above.
Review task definitions for Windows path compatibility if using absolute paths.
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.

What akm Actually Does: A Command-by-Command Tour

IT Lackey — Thu, 07 May 2026 23:51:17 +0000

If you've looked at akm for the first time and thought "this seems useful, but what do all these commands actually do?" this post is for you.

At a high level, akm is a package manager for AI agent capabilities. It gives your agents a searchable library of scripts, skills, commands, agents, knowledge docs, workflows, vaults, wikis, lessons, and memories. Instead of dumping everything into a giant system prompt, you let the agent discover what it needs with search, then load the right asset at the right time.

That's the big idea. The practical question is how the command surface fits together in day-to-day work.

This post walks through the CLI by job-to-be-done, with real examples of when you'd use each command.

This command-family framing reflects akm v0.8.0.

The Short Version

You can think about akm in seven layers:

Set up the workspace — setup, init, config, info, index
Connect sources and discover new ones — add, list, update, remove, clone, save, registry
Find and inspect assets — curate, search, show
Build local knowledge and operational context — remember, import, wiki, vault
Run repeatable procedures — workflow
Continuously improve the stash — feedback, history, events, improve, propose, proposals, accept, reject
Operate the CLI comfortably — help, hints, completions, upgrade

If you only remember one mental model, make it this:

akm add tells akm where content lives
akm index makes that content searchable
akm curate gives the best first shortlist for a request
akm search is for deeper discovery when you need more than the curated list
akm show loads the full thing

Everything else supports one of those steps.

What akm Is Really For

Most teams already have agent assets. They're just scattered.

Claude Code skills in one folder
OpenCode commands in another
project notes in random markdown files
internal runbooks in a docs repo
half-remembered lessons buried in old chats

akm turns that mess into a searchable, reusable library.

For example, imagine a team that ships a web app every week. They might use akm to unify:

local review and release skills
a shared Git repo of deployment workflows
internal docs imported as knowledge
a production vault that exposes secret keys without leaking values
memories like "staging deploys require VPN"

Now an agent can start with a curated shortlist for "ship release", load the release workflow, check the deployment vault, read the runbook section it needs, and only fall back to broader search if it needs more options.

1. First-Run and Environment Commands

`akm setup`

Use this when you want the guided on-ramp.

akm setup

Real-world use: you just installed akm on a new laptop and want the wizard to create the working stash, configure providers, and build the first index without editing config by hand.

`akm init`

Use this when you want to skip the wizard and just create the working stash.

akm init --dir ~/akm

Real-world use: you're scripting environment bootstrap for a devcontainer or CI image and want a known stash location without interactive prompts.

`akm config`

Use this to inspect or change settings.

akm config get output.format
akm config set output.detail full
akm config path --all

Real-world use: your agent prefers text output in one repo and JSON in another, or you want to set a default write target for memories and imports.

`akm info`

Use this as the health check.

akm info

Real-world use: after setup, you want to confirm the version, active sources, registries, and whether semantic search is actually ready.

`akm index`

Use this whenever content changed and you want search to reflect it.

akm index
akm index --full

Real-world use: you added a GitHub stash, imported some docs, and created two memories. akm index refreshes the local search database so the agent can discover them.

2. Source and Registry Commands

These commands answer two related questions:

where should akm look for assets right now?
where can I discover more stashes later?

`akm add`

This is how you register a source.

akm add ~/.claude/skills
akm add github:your-org/team-agent-toolkit
akm add @scope/platform-stash
akm add https://docs.example.com --name public-docs

Real-world use:

point akm at your existing Claude Code skills
pull in a shared team stash from GitHub
install an npm-published stash
crawl a documentation site as searchable knowledge

`akm list`

Shows what sources are already connected.

akm list

Real-world use: you're debugging why a search result isn't appearing and want to verify whether the expected repo or local directory is even registered.

`akm update`

Refreshes managed sources.

akm update --all

Real-world use: your platform team shipped an updated deployment stash and everyone pulls the latest version before a release.

`akm remove`

Disconnect a source you no longer want indexed.

akm remove public-docs

Real-world use: a website source became noisy or outdated and you want it out of search results.

`akm clone`

Copies a single asset into your working stash or another directory so you can edit it locally.

akm clone skill:code-review
akm clone "npm:@scope/platform-stash//workflow:ship-release"

Real-world use: you find a good community skill, clone it into your local stash, and tailor it for your team's code review conventions.

`akm save`

Commit local stash changes, and optionally push if the source is writable.

akm save -m "Tighten release workflow"

Real-world use: your team keeps its shared stash in Git. After improving a workflow and a vault comment, akm save records the change like normal code.

`akm registry`

Use registries to discover new stashes you have not installed yet.

akm registry search "code review"
akm registry add https://example.com/registry/index.json --name team

Real-world use: platform engineering publishes an internal stash registry, and teams browse it the same way they'd browse a package registry.

3. Discovery Commands

This is the heart of the product.

`akm curate`

Start here for a request or prompt. curate is the preferred first stop because it returns a tighter, more task-ready shortlist.

akm curate "review a large pull request"
akm curate "ship a bun release"

Real-world use: the agent needs a deploy workflow, a release checklist, or a review skill and wants the best few candidates first instead of a broad result set.

`akm search`

Use this when you want deeper discovery beyond the curated shortlist.

akm search "review a large pull request"
akm search "kubernetes deploy" --type workflow

Real-world use: curate gave you a solid starting point, but now you want to dig wider, inspect additional assets, or explore the long tail of relevant results.

`akm show`

Load the full content of a specific asset.

akm show skill:code-review
akm show workflow:ship-release
akm show knowledge:incident-runbook section "Rollback"

Real-world use: curate or search identifies the right asset; show gives the agent the actual instructions, prompt template, workflow steps, or document section it needs to act.

4. Local Knowledge and Operational Context

This is the part of akm that turns a stash into living local context instead of a static pile of files.

Some commands capture what your team knows. Others make that knowledge safer or more structured. They belong together because they all define the working context your agent can rely on later.

`akm remember`

Write a memory.

akm remember "Staging deploys require VPN access" --tag ops --tag deploy

Real-world use: after an incident or a successful fix, you capture the lesson in a searchable format so the next agent run doesn't rediscover it the hard way.

`akm import`

Bring a document into the stash as knowledge.

akm import ./docs/release-checklist.md
akm import https://example.com/internal-guide/auth

Real-world use: you have a good architecture note or ops runbook outside the stash and want it indexed alongside everything else.

`akm wiki`

Use wikis for long-lived, agent-maintained knowledge bases.

akm wiki create architecture
akm wiki stash architecture ./notes/auth-redesign.md
akm wiki lint architecture

Real-world use: your team wants a research or architecture wiki with raw sources, curated pages, and deterministic linting instead of ad hoc markdown sprawl.

wiki belongs with local knowledge, not off to the side. It's the command family you reach for when a single imported doc or memory is not enough and you need a maintained body of team knowledge.

`akm vault`

Use vaults when the agent needs operational context about secrets without seeing the secret values.

akm show vault:production
akm vault run vault:production -- env

Real-world use: a deploy workflow needs DATABASE_URL and DEPLOY_TOKEN. The agent can verify the keys are present, then load the environment only at execution time.

Vaults fit here because they are part of the local operating context. They tell the agent what environment shape exists and let commands run safely without exposing secret values in the chat transcript.

5. Procedure Commands

Once you have the right knowledge and context, the next problem is execution across time.

`akm workflow`

Use workflows for repeatable, resumable procedures.

akm workflow start workflow:ship-release --params '{"version":"2.4.0"}'
akm workflow next workflow:ship-release
akm workflow complete run-123 --step validate --notes "Version and branch confirmed"

Real-world use: shipping a release, rotating secrets, onboarding a new service, or any other multi-step process that should survive across sessions instead of living only in chat history.

6. Continuous Improvement Commands

This is the loop that makes akm better over time.

The flow is simple:

an agent uses an asset
you record whether it helped with feedback
you inspect what happened with history or events
you ask for improvements with reflect or propose
you review the result with proposal
you distill recurring feedback into reusable lessons with distill

These commands should be thought about as one system, not as isolated features.

`akm feedback`

Record whether an asset helped.

akm feedback workflow:ship-release --positive
akm feedback skill:legacy-deploy --negative --note "Outdated after platform migration"

Real-world use: over time, assets that consistently help rise in ranking and stale ones become easier to spot.

`akm history`

Inspect the recorded state changes for an asset or the stash.

akm history --ref workflow:ship-release

Real-world use: you want to know whether a workflow was searched, shown, or downvoted recently while cleaning up a team's stash.

`akm events`

Read the append-only realtime event stream.

akm events tail --format jsonl

Real-world use: another process is watching akm activity and reacting when new feedback, imports, or proposals land.

`akm improve`

Ask an external agent to propose improvements to an existing asset or to generate a new asset proposal.

akm improve skill:code-review --task "make this stricter about test coverage"

Real-world use: you have a decent review skill, but you want an agent to improve it based on how it's actually being used.

`akm propose`

Generate a brand-new asset proposal.

akm propose workflow incident-rollback --task "Rollback procedure for failed production deploys"

Real-world use: repeated gaps in your stash show up in history and events, so you create a first draft for the missing workflow or skill.

Proposal Queue

Review, diff, accept, or reject queued proposals.

akm proposal list
akm proposal diff 42
akm proposal accept 42

Real-world use: keep human review in the loop before generated assets become part of the live stash.

`akm improve`

Summarize feedback into a reusable lesson proposal.

akm improve skill:code-review

Real-world use: repeated feedback on a skill gets turned into a lesson asset that captures what people learned from using it.

7. Operator Ergonomics

These are the commands that make the CLI easier to live with day to day.

`akm help`

Focused help topics, especially migrations.

akm help migrate latest

Real-world use: you upgraded akm and want the release-specific migration notes without leaving the terminal.

`akm hints`

Print instructions you can drop into AGENTS.md or CLAUDE.md.

akm hints

Real-world use: you want every project to tell its coding agent how to use the local akm installation.

`akm completions`

Generate or install shell completion.

akm completions --install

Real-world use: you use akm daily and want tab completion for commands and flags.

`akm upgrade`

Upgrade the akm binary itself.

akm upgrade --check

Real-world use: you installed the standalone binary and want to see whether a newer release is available.

8. The Commands People Use Most

In practice, most teams live in a much smaller subset of the CLI:

akm setup
akm add ...
akm index
akm curate "..."
akm show <ref>
akm remember "..."
akm feedback <ref> --positive

If your use case grows, the rest of the command surface is there:

workflow when procedures need state
wiki when local knowledge needs structure
vault when local operational context includes secrets
registry when discovery goes beyond your local stash
feedback / history / events / reflect / propose / proposal / distill when you want a real improvement loop

A Simple End-to-End Example

Let's say your team is onboarding a new service.

Run akm add github:your-org/platform-stash
Run akm add ./docs/runbooks
Run akm index
Start with akm curate "onboard a new service"
Open the best match with akm show workflow:service-onboarding
Check required environment keys with akm show vault:staging
Add the final onboarding notes to the team wiki with akm wiki stash onboarding ./notes/service-onboarding.md
Capture a new lesson with akm remember "Service onboarding requires DNS approval from ops" --tag ops
Record whether the workflow helped with akm feedback workflow:service-onboarding --positive
If the workflow was weak, run akm reflect workflow:service-onboarding --task "improve this after the latest run" or akm distill workflow:service-onboarding

That's akm in a nutshell: connect sources, index them, find what matters, load only what you need, and keep the library getting better.

Final Takeaway

akm is not trying to replace your coding assistant. It's the layer that makes your assistant's skills, docs, procedures, and institutional memory manageable at scale.

If you want the one-sentence version:

akm is the command line system that helps agents discover, load, share, improve, and safely reuse the capabilities they need to do real work.

And if you're wondering where to start, start here:

akm setup
akm add ~/.claude/skills
akm add github:your-org/team-agent-toolkit
akm index
akm curate "code review"
akm show skill:code-review

That gets you from "I installed it" to "my agent can actually use it" in a few minutes.

akm 0.7.0: Proposal Queue, Reflection Commands, Lessons, and akm-bench

IT Lackey — Tue, 05 May 2026 02:20:48 +0000

akm 0.7.0 is out. This is the last pre-1.0 ship in the v1 cycle. The headline features are a durable proposal queue that routes all agent-suggested changes through a single reviewable path, three new CLI surfaces (reflect, propose, distill) that write into that queue, a lesson asset type for synthesized knowledge, per-call-site LLM feature gates that are all off by default, and a paired-run benchmarking framework (akm-bench) for measuring whether your stash actually improves agent outcomes. A batch of security, UX, and hygiene hardening rounds out the release.

If you are on 0.6.x, the v1 migration guide covers the per-surface delta. The upgrade is opt-in — everything new requires explicit configuration or a new command invocation.

TL;DR

Proposal queue (akm proposal list/show/diff/accept/reject) — all agent-generated changes flow through a durable queue before touching your stash.
akm reflect, akm propose, akm distill — three new commands that produce proposals without mutating live stash content.
lesson asset type — first-class synthesized knowledge, produced by akm distill and promoted via akm proposal accept.
llm.features.* map — seven opt-in gates (all false by default) for bounded in-tree LLM call sites.
quality: "proposed" — proposed assets are excluded from default search; surface them via --include-proposed or akm proposal *.
akm-bench v1 — paired noakm/akm runs, per-ref attribution, delta reporting.
Security hardening — git message sanitization, bench env isolation, LLM body redaction, npm tarball host validation.

Proposal queue (`akm proposal *`)

The fundamental problem with agent-generated suggestions is trust: you want to capture what the agent learned without blindly writing unreviewed content into your stash. The proposal queue solves this by separating generation from promotion.

All proposal-producing commands write to a durable queue that lives outside the asset tree. Unaccepted drafts never appear in search results or get committed. When you're ready to accept a proposal, akm proposal accept runs full validation and then routes the write through the same writeAssetToSource() path used by akm remember and akm import — no special handling, no bypass.

akm proposal list                       # list pending proposals
akm proposal show <id>                  # render one proposal
akm proposal diff <id>                  # diff vs. the live ref
akm proposal accept <id>                # validate, then promote to stash
akm proposal reject <id> --reason "…"  # archive with reason

Multiple proposals for the same ref coexist without filesystem collisions. Auto-accept can be enabled per-source via autoAcceptProposals: true in your stash config (requires a writable source, defaults off).

Three new commands: `reflect`, `propose`, `distill`

These three commands are the primary way to generate proposals.

akm reflect [ref] [--task ...]        # reflect on an asset and propose improvements
akm propose <type> <name> --task "…"  # generate a new asset as a proposal
akm distill <ref>                     # synthesize a lesson from an asset

reflect and propose shell out to your configured agent CLI and write only to the proposal queue — they never mutate live stash content. distill is a bounded in-tree LLM call, gated behind llm.features.feedback_distillation, that produces a lesson-type proposal from an existing asset.

All three emit usage events so you can track which workflows you're actually using.

`lesson` asset type

lesson is a new first-class asset type designed for synthesized knowledge — the kind your agent derives from experience rather than imports from a source. Lessons are stored under lessons/<name>.md in your working stash, parallel to memories/. Required frontmatter: description and when_to_use.

The canonical workflow: akm distill <ref> produces a lesson proposal → akm proposal list shows it → akm proposal accept <id> promotes it to your stash. Direct authoring via akm import or akm remember-style flows is also supported if you want to write lessons manually.

`llm.features.*` — opt-in LLM gates

Every bounded in-tree LLM call site is now gated behind exactly one feature flag. All defaults are false, so enabling the schema has no effect until you opt in. Seven flags ship in 0.7.0:

Key	What it enables
`curate_rerank`	LLM rerank in `akm curate`
`tag_dedup`	LLM tag dedup during indexer enrichment
`memory_consolidation`	`akm remember --enrich` consolidation
`feedback_distillation`	`akm distill <ref>`
`embedding_fallback_score`	Scorer fallback when embeddings unavailable
`memory_inference`	Indexer split of pending memories into atomic facts
`graph_extraction`	Indexer entity/relation extraction → SQLite graph tables

Turn on what you want:

akm config set llm.features.feedback_distillation true
akm config set llm.features.memory_consolidation true

Every gated call site uses the tryLlmFeature() wrapper from src/llm/feature-gate.ts, which guarantees: disabled → fallback returned without ever calling the LLM; throw → error swallowed, fallback returned; timeout → 30-second hard limit, fallback returned.

`quality: "proposed"` and `--include-proposed`

SearchHit.quality now has three well-known values: "generated", "curated", and "proposed". The first two appear in default search. Proposed assets are excluded by default — they only surface via akm search ... --include-proposed or via the akm proposal * commands. Unknown quality values parse-warn-include so plugin authors can extend the set without breaking the indexer.

`akm-bench` v1

Bench grows from a smoke test into a paired-utility framework:

Track A — paired noakm/akm runs. For each task, bench runs your agent CLI twice (without and with akm available), captures per-tool-call utility, and emits a comparable score pair.
Track B — registry attribution. Utility deltas are mapped back to specific [origin//]type:name refs so you can see which assets in your stash actually contributed to the improvement.
akm-bench compare — aggregates paired runs into a delta report.
akm-bench attribute — surfaces the per-ref attribution report.

akm-bench compare results/noakm results/akm
akm-bench attribute results/akm

The technical reference is at docs/technical/benchmark.md.

Security hardening (PR #275)

Five security, UX, and hygiene issues landed together in the pre-prod hardening batch:

Security:

#270 — git message sanitization. Commit messages and remote URLs written by akm are sanitized to prevent shell-substitution and control-character injection through user-supplied content.
#271 — bench env isolation. Each agent invocation in akm-bench runs in a scrubbed environment so host secrets don't leak into bench transcripts.
#272 — LLM body redact + npm tarball host validation. Outbound LLM request/response bodies are redacted in error reporting before surfacing to stderr. akm add npm:… now validates the tarball download host against your configured npm registry instead of blindly following arbitrary dist.tarball URLs.

UX:

#273 — workflow noise gate, stashes deprecation warn, setup --help. akm workflow next/complete/status no longer print spurious progress noise on quiet runs. Configs using the legacy stashes[] key now emit a single deprecation warning per process (was: per call site). akm setup --help renders the full help block.

Hygiene:

#274 — tsconfig + HF pin + shapes throw. tsconfig.json now covers tests/ so bunx tsc --noEmit catches test-file errors. The HF embeddings model is pinned to a specific revision. The output-shape registry now throws on a missing shape rather than silently falling back to JSON.stringify.
#276 — bench tmp redirect. akm-bench no longer writes scratch state under /tmp; everything lands under ~/.cache/akm/bench/.

Upgrade

npm install -g akm-cli@0.7.0
# or
bun install -g akm-cli@0.7.0
# or from an existing install
akm upgrade

Verify:

akm info --format text     # version 0.7.x
akm proposal list          # queue starts empty — that's expected

Try the new surfaces:

akm setup                                            # detects installed agent CLIs
akm config set llm.features.feedback_distillation true
akm distill memory:my-debugging-notes               # produces a lesson proposal
akm proposal list
akm proposal accept <id>

No manual migration is required for users on 0.6.x with no agent or llm.features blocks configured. Everything new is opt-in.

Full details in the v1 migration guide and the 0.7.0 release notes.

Full changelog at CHANGELOG.md.

Building Agent Knowledge Bases That Actually Scale

IT Lackey — Tue, 05 May 2026 02:19:53 +0000

This is part eight in a series about managing the growing pile of skills, scripts, and context that AI coding agents depend on. Part one introduced progressive disclosure. Part two unified your local assets across platforms. Part three added persistent memory. Previous parts addressed teams, distributed stashes, and community knowledge.

This one is about a different problem: knowledge accumulation.

You start a new research area — say, LLM inference optimization. You read papers. You take notes. You save PDFs. Your agent writes summaries, discovers connections, asks follow-up questions that lead to more notes. Six weeks later you have a pile of markdown files, half-digested papers in a downloads folder, and a memory that says "we covered KV cache quantization somewhere." You search for it. You get three files with different partial takes on the same topic. None of them have the answer you need.

This isn't a storage problem. You have all the information. It's a structural problem — and that's what akm's multi-wiki support is built to fix.

Karpathy's LLM Wiki Pattern

In a GitHub gist, Andrej Karpathy described a pattern for maintaining a markdown knowledge base that a human and LLM build and maintain together. The core idea is deceptively simple: a structured directory of markdown pages, with an agent responsible for synthesizing incoming information into those pages over time.

The insight is that agents are genuinely good at certain things that humans find tedious. Summarizing a 40-page paper into a two-paragraph page entry. Finding the connection between a new paper and something already in the knowledge base. Keeping a log of what was added and why. Updating an existing page when new information contradicts or extends it.

What agents are not good at: maintaining invariants. An agent won't reliably enforce slug uniqueness. It won't regenerate an index consistently. It will sometimes overwrite a source file you meant to keep immutable. It loses track of what's been ingested when sessions end.

So you need a division of labor. The agent does the synthesis. The tooling enforces the invariants. That's the gap akm's wiki support fills.

The Problem: Knowledge That Accumulates and Gets Lost

Most developers hit this in one of two ways.

The first way: you import a file as a knowledge asset (akm import ./paper.md) and your agent reads it directly. That works fine for one or two documents. At ten documents, the agent is loading full text into every relevant session. At thirty documents, you're spending tokens on context you don't need, and the agent is trying to mentally synthesize relationships across thirty separate files per session. Nothing is connected. Nothing is indexed.

The second way: you ask your agent to "take notes" in a notes.md file. The file grows. It becomes a wall of text with no structure. Searching it is grep. Updating it means the agent has to read the whole thing before writing anything. After a few sessions the agent starts ignoring sections it wrote two weeks ago because they're below the fold.

Both patterns fail in the same way: there's no structural home for the knowledge. No schema that says what a page is. No index that makes things findable. No log that tracks what happened. No separation between raw sources and synthesized pages.

How akm's Multi-Wiki Works

A wiki in akm is a named subdirectory under ~/akm/wikis/. Each wiki has a fixed structure:

~/akm/wikis/
  research/
    schema.md       # per-wiki rulebook: page kinds, voice, contradiction policy
    index.md        # catalog of all pages — regenerated by akm index
    log.md          # append-only activity log
    raw/            # immutable ingested sources (never edit these)
    attention.md    # a synthesized page
    transformers/
      architecture.md

You create a wiki with one command:

akm wiki create research

That scaffolds the directory, stubs out schema.md with sensible defaults, creates empty index.md and log.md, and makes the raw/ directory. You're not starting from a blank directory — you're starting from a structural contract.

The schema.md file is important. It's where you define the rules for this particular wiki: what page kinds are allowed, what the voice should be, how contradictions are handled, what the minimum viable page looks like. You edit it once when you create the wiki, and the agent reads it at the start of every ingest session. It's the wiki's constitution.

Walking Through a Real Workflow

Say you're building a research wiki on transformer architectures. You have a paper PDF, some notes from a talk, and a few bookmarked articles.

Start by bringing in the raw sources:

akm wiki stash research ./attention-paper.pdf --as attention
akm wiki stash research ./transformer-scaling-notes.md --as scaling-notes
echo "# Key quote from Sutton talk" | akm wiki stash research -

The stash command copies each source into raw/ with a unique slug. If you try to stash the same slug twice, it errors rather than overwriting. That's one of those invariants the agent can't reliably maintain — akm handles it.

Now ask your agent to start the ingest workflow:

akm wiki ingest research

This dispatches the configured agent (from config.defaults.agent or --profile) with the wiki's ingest workflow as its prompt. The workflow tells the agent to: read schema.md to understand the page structure, check index.md to see what pages already exist, read each unprocessed file in raw/, synthesize content into pages using Write or Edit, update index.md, append a summary to log.md. akm owns the schema-aware commands (stash, search, lint, index, show); the agent owns the reasoning.

After the agent runs the ingest workflow:

akm wiki pages research
# → research/attention.md   "Self-attention mechanism and complexity analysis"
# → research/transformers/architecture.md   "Encoder-decoder structure, residual connections"

Later, when you want to check the health of the wiki:

akm wiki lint research

Lint runs deterministic structural checks: orphan pages (not in index.md), broken xrefs in frontmatter, missing descriptions, raw files that appear uncited in any page, and whether the index is stale relative to the directory contents. These are checks that require counting and comparing file state — exactly the kind of thing agents do inconsistently.

The "akm Surfaces, the Agent Writes" Principle

This division of labor is worth making explicit, because it determines what belongs in akm and what doesn't.

akm handles operations that require invariants an agent can't reliably enforce across sessions:

Scaffolding (ensures required files exist with the right names)
Source import (unique slugs, never overwrites, immutable raw/)
Lint (deterministic structural checks against file system state)
Index regeneration (consistent format, triggered by normal indexing)
Workflow printing (a recipe the agent can follow without reinventing it)

The agent handles everything that requires judgment:

Writing and updating pages
Synthesizing connections between sources
Deciding what a page should say and how to structure it
Appending meaningful log entries
Adding xrefs in frontmatter

The reason this split matters: agents are good at synthesis and bad at reliability. If you ask an agent to "update the index," it will sometimes do it correctly, sometimes produce a subtly wrong format, and sometimes forget. If you ask it to write a page on attention mechanisms from three source documents, it will do that well every time. The tool enforces the boring, brittle parts so the agent can focus on what it's actually good at.

There are no unconditional LLM calls inside akm for wiki operations. The wiki commands are pure file operations, SQLite, and structural analysis — fast, deterministic, and usable offline. (akm does ship bounded opt-in LLM calls for other workflows, like akm improve and akm curate, gated behind per-process toggles under profiles.improve.<name>.processes.* and the first-class index.* / search.* feature sections — all off by default. But the wiki tooling itself never touches an LLM.)

akm wiki search vs akm search --type wiki

Once you have a few wikis, you'll use two different search paths depending on what you need.

akm wiki search research "attention mechanism" runs a scoped search within the research wiki only. Use this when you know which wiki holds the answer and you want precision — no noise from other wikis or other asset types. The results are page refs with descriptions, scoped to research/. Raw sources under raw/ plus the wiki root infrastructure files schema.md, index.md, and log.md are excluded from the search index and never appear as search hits.

akm search --type wiki "attention mechanism" runs the full stash-wide search across all wiki pages. Use this when you're not sure which wiki something lives in, or when you want to see if anything from multiple wikis is relevant to a task before loading anything.

In practice: scoped search during active work in a specific domain, wide search when starting a new session or doing cross-domain research. Wiki pages participate in the same FTS5 scoring pipeline as every other asset type, so --type wiki is not a second-class citizen — a highly relevant wiki page will outrank a mediocre skill in a general search.

Practical Example: Building a Research Wiki

Here's the complete workflow for setting up and using a research wiki from scratch.

Initial setup:

akm wiki create research
# Edit wikis/research/schema.md to define your page kinds
# (technical-summary, comparison, open-question, etc.)

Bring in sources as you find them:

akm wiki stash research ./papers/attention-is-all-you-need.pdf --as attention-2017
akm wiki stash research ./papers/flash-attention-v2.pdf --as flash-attention-v2
akm wiki stash research ./notes/scaling-laws-talk.md --as scaling-laws-notes

Run ingest when you're ready to synthesize:

akm wiki ingest research
# Agent reads the recipe, reads raw/ files, writes pages, updates index, logs activity

Check what exists:

akm wiki pages research
akm wiki show research

Search when working on a related task:

akm wiki search research "KV cache memory"
# Returns: research/attention.md, research/flash-attention/optimization.md

Lint before a long agent session to catch structural drift:

akm wiki lint research
# Orphans: none
# Broken xrefs: research/flash-attention/optimization.md → research/kv-cache.md (missing)
# Stale index: yes (run akm index)

Fix the stale index:

akm index
# Rebuilds SQLite search index, regenerates wikis/research/index.md as a side effect

At the end of a few weeks, you have a structured, searchable knowledge base. Your agent can load specific pages by ref instead of reading all thirty raw sources every session. You can run lint any time to catch drift. The log tells you what was synthesized and when. The raw sources are still there if you ever need to re-derive something from primary material.

What This Isn't

Multi-wiki is not a document management system. If you want to store and retrieve original documents, akm import and the knowledge type already do that.

It's not a notes app. Single notes go in memories. Reference material goes in knowledge. Wikis are specifically for synthesized, structured knowledge that grows over time through an active ingest process.

As of 0.8.0, akm wiki ingest <name> dispatches the configured agent (defaults.agent or --profile) to execute the ingest workflow end-to-end. The agent reads the schema, finds related pages, creates new pages, updates xrefs, appends to log.md, and reindexes — all through akm's schema-aware commands. The wiki tooling owns the invariants; the agent owns the reasoning.

Getting Started

Multi-wiki has been available since akm 0.5.0. If you're already using akm, upgrade and try:

akm wiki create research
akm wiki list

The Getting Started guide covers initial setup if you're new to akm. The wiki commands are available immediately once you have a stash configured.

If you're working in a domain where knowledge accumulates — research, security analysis, architecture decisions, competitive analysis — give it a run and see if the structure helps. The repo is at github.com/itlackey/akm. Questions and feedback in the issues.

Agents That Remember Where They Were

IT Lackey — Tue, 05 May 2026 02:19:50 +0000

This is part nine in a series about managing the growing pile of skills, scripts, and context that AI coding agents depend on. Part one introduced progressive disclosure. Part two unified your local assets across platforms. Part seven covered shared team skills via Git repos.

Ask an agent to ship a release and it will start confidently. It runs the build, opens the changelog, checks the branch. Then something interrupts the session — you close the terminal, the context window fills up, you need to switch tasks. When you come back, the agent has no idea where it left off. You either restart from scratch or spend time reconstructing what happened.

This is the central problem with agents and multi-step work. They're good at individual tasks. They're not naturally good at procedures — sequences of steps that span time, accumulate state, and need to be resumable when interrupted.

akm ships three features that address this directly: workflow assets for stored, resumable procedures; vault assets for secret-aware environment config; and a writable git stash that keeps your skill collection in sync across machines. This post explains what each one does and how they fit together.

The Problem: Tasks Versus Procedures

A task is "write this function." A procedure is "ship this release." Tasks have a beginning and end that fit inside a single context window. Procedures have steps, dependencies between steps, and state that persists across sessions.

When agents handle procedures today, the state lives only in the conversation. That's fine for a five-minute task. It breaks down for anything that takes an hour, involves multiple sessions, or needs to be audited later. If something fails at step four of seven, there's no standard way to resume at step five without replaying the whole context.

The workaround most developers reach for is a checklist in a markdown file. The agent checks off items as it goes. This works, but it's manual, fragile, and the state isn't queryable. You can't ask "which deployments are currently in-progress" if the state is scattered across markdown checkboxes in different files.

Workflow assets are the structured version of that checklist.

Workflow Assets: Stored Procedures Your Agent Can Step Through

Workflows live in workflows/ in your stash. Each workflow is a markdown file with frontmatter declaring the procedure's parameters and a standard step format. You write the workflow once; the agent follows it on every run.

Here's what a release workflow looks like:

---
description: Ship a production release
params:
  version: "The version to release (e.g. 1.2.3)"
---
# Workflow: Ship Release

## Step: Validate inputs
Step ID: validate
### Instructions
Check that version follows semver and that the release branch exists.
### Completion Criteria
- Version matches x.y.z
- Branch release/{{ version }} exists

## Step: Build
Step ID: build
### Instructions
Run `bun run build` and verify dist/ was generated.

## Step: Deploy to staging
Step ID: staging
### Instructions
Run `./scripts/deploy.sh staging` and verify the health check passes.

## Step: Deploy to production
Step ID: production
### Instructions
Run `./scripts/deploy.sh production` after staging health check is green.

The workflow defines the procedure. To run it, the agent creates a run — an instance of that procedure with a specific set of params:

akm workflow start workflow:ship-release --params '{"version":"1.2.3"}'
# Returns a run ID: run-abc123

Now the procedure has state. The agent calls akm workflow next to get the current actionable step:

akm workflow next workflow:ship-release
# Returns: Step "validate" — Check that version follows semver...

When the agent completes a step, it marks it done with notes:

akm workflow complete run-abc123 --step validate --state completed --notes "Version 1.2.3, branch release/1.2.3 confirmed"

--state defaults to completed when omitted, so the --state completed above is redundant but explicit.

And the next call to akm workflow next returns the following step. The run persists independently of the conversation. If the session ends, a new agent picks up exactly where the previous one left off:

akm workflow next workflow:ship-release
# Returns: Step "build" — still in progress from the interrupted session

Want to see the full state of a run?

akm workflow status run-abc123

workflow status also accepts a workflow ref directly, resolving to the most-recently-updated run:

akm workflow status workflow:ship-release

Ref-based workflow commands are scoped to the current working context, not all
workflow runs on the machine. In practice akm groups runs by the current
project/worktree/directory, so an active run in one repo or sandbox does not
block a different directory from starting its own run of the same workflow.

That shows each step with its status and any notes the agent recorded. You can list all active runs:

akm workflow list --active

The procedure is now auditable. You know which step failed, when, and what the agent noted. You can hand the run off to a different agent or a different developer. The state is outside the context window where it's durable.

If you need a starting point, akm workflow template prints a starter workflow doc you can adapt.

Resuming blocked or failed runs

Sometimes a run gets blocked — a step requires human input, an external dependency is unavailable, or a tool call fails. When that happens, the run transitions to blocked or failed. Use workflow resume to flip it back to active without discarding progress:

akm workflow resume run-abc123

Completed runs cannot be resumed. Use workflow list to find runs by status.

Vault Assets: The Agent Knows What It Needs, Not What the Values Are

Procedures that touch production environments need secrets — database URLs, API keys, deploy tokens. Putting those secrets in a skill file or a prompt is an obvious problem. But the agent still needs to know which secrets a given procedure requires.

Vault assets solve this. A vault is a .env file stored in vaults/ in your stash. The design has one rule: values are never surfaced in structured output. The agent can inspect a vault and learn what keys exist. It never sees what those keys are set to.

akm show vault:production
# Returns keys/comments only, never values

This is enough for the agent to confirm "yes, the right secrets are configured for this environment" without the secrets appearing anywhere in the conversation or the context window.

When a script actually needs the values — at runtime, not at planning time — the agent runs the command through vault run:

akm vault run vault:production -- ./deploy.sh

The values are loaded into the child process environment. They never pass through the agent's structured output. The agent's conversation log is clean.

Combined with a workflow, this fits naturally into an environment verification step. The agent calls akm show vault:production to confirm all required keys are present, marks the step complete, then later calls akm vault run vault:production -- <command> when a command actually needs the secrets. The workflow knows what's required. The agent confirms it. The command gets what it needs.

Writable Git Stash: Your Skills Sync Like Code

So far in this series, stashes have been read-only: you pull in a team repo or a remote source, and akm indexes it. In 0.5.0, a stash can be writable.

When you create a stash with --writable, akm save will stage, commit, and push your changes back to the remote:

akm add git@github.com:your-org/skills.git --provider git --name team-skills --writable

# After editing or adding an asset
akm save team-skills -m "Add deploy workflow"

The behavior depends on the stash configuration:

State	What happens
Not a git repo	Skipped
Git repo, no remote	Stage and commit only
Git repo, has remote, writable: false	Stage and commit only
Git repo, has remote, writable: true	Stage, commit, and push

Your default stash — the one akm init creates — is auto-initialized as a local git repo. So by default, akm save gives you a commit history of every change you've made to your skill collection, without requiring a remote. Add a remote and flip writable: true when you're ready to sync across machines.

This changes how you think about managing your personal stash. It's not a pile of files in ~/.akm. It's a versioned repository. You can see when you wrote a skill, what it looked like before you changed it, and whether your teammates have made updates since you last pulled.

How These Three Features Work Together

Consider a deployment procedure that a team runs regularly. Before 0.5.0, you'd write a deploy skill and hope the agent followed the steps in the right order. With 0.5.0:

Step 1: Write the workflow once.

akm workflow create ship-release
# Edit workflows/ship-release.md with your team's exact steps

Step 2: Add a vault with the production secrets.

The vault file lives at vaults/production.env in your stash. The keys are there; the values are managed separately through whatever secret management you use.

Step 3: Save both to the team stash.

akm save team-skills -m "Add ship-release workflow and production vault"

Every developer on the team pulls the update with akm update --all. Now everyone has the same workflow and the same vault definition.

Step 4: When it's time to deploy, the agent runs the procedure.

# Agent starts a run
akm workflow start workflow:ship-release --params '{"version":"2.0.0"}'

# Gets the first step
akm workflow next workflow:ship-release
# → "Validate inputs: confirm version and vault keys"

# Checks the vault without reading secrets
akm show vault:production
# → keys/comments only, never values

# Marks the step complete
akm workflow complete run-xyz --step validate --notes "All keys present"

# Gets the next step
akm workflow next workflow:ship-release
# → "Build: run bun run build..."

If the session ends at the staging step, a fresh agent picks up with:

akm workflow next workflow:ship-release
# → "Deploy to staging" — still pending from the previous session

No context reconstruction. No "where did we leave off?" The procedure state is in the workflow run, not the conversation.

When the deploy is done, commit any skill or workflow improvements back to the team repo:

akm save team-skills -m "Improve staging health check step"

The team gets the improvement on next akm update.

Security Model

Vault assets have a clear security contract. Understanding it prevents both
false confidence and unnecessary alarm.

Values never leave disk via akm commands. This is the core invariant.
akm show, akm vault list, akm search, and every other structured output
command expose only key names and comments — never values. The two supported
paths that actually use values are source "$(akm vault path vault:name)" (the
shell loads the file directly) and akm vault run vault:name -- <command>
(values are injected into the child process environment). Neither path passes
values through akm's structured output.

Key names are metadata — they are intentionally discoverable. Key names
appear in vault list, vault show, search results, and agent context by
design. This is how an agent can confirm "yes, DATABASE_URL is configured in
this vault" without seeing its value. Do not treat key names as secrets.

The --sensitive flag hides a vault from vault list only. Creating a
vault with akm vault create prod --sensitive prevents it from appearing in
the default vault list output. It does not prevent key names from showing up
in search results or when the vault is shown directly with akm show vault:prod. Use --sensitive to reduce noise, not to enforce secrecy.

Dangerous key detection. Vault keys with names like LD_PRELOAD, PATH,
DYLD_INSERT_LIBRARIES, or NODE_OPTIONS can be used to hijack process
execution when the vault is loaded via akm vault run. akm add and
akm lint both scan for these names. During install, akm add pauses and
asks for confirmation when dangerous keys are found (non-interactive mode fails
unless --allow-insecure is passed). The full list of 23 flagged key names is
documented in the CLI reference.

When to use --allow-insecure. Pass --allow-insecure to akm add when
you have reviewed a stash manually and confirmed that a dangerous vault key is
legitimate (for example, a hermetic toolchain that overrides PATH). The flag
also bypasses plain-HTTP source rejection. It is not a global config setting —
it applies only to the single install invocation.

Getting Started

If you're on akm already, upgrade to the latest version:

npm install -g akm-cli@latest
# or
akm upgrade

To try workflows:

akm workflow template
# Copy the output to workflows/your-first-workflow.md and edit it
akm workflow create your-first-workflow
akm workflow start workflow:your-first-workflow

To add a vault, drop a .env file in vaults/ in your stash. The format is standard .env — one KEY=value per line, comments with #.

To make your default stash writable, add a remote to the git repo in ~/.akm/stash and update your stash config with --writable. Run akm save -m "Initial commit" to verify it pushes.

The repo is at github.com/itlackey/akm. The Getting Started guide covers initial setup if you're coming in new.

Agents are most useful when they can handle real work end-to-end. Real work usually involves multiple steps, sensitive configuration, and sessions that get interrupted. Workflows, vaults, and a writable stash close those gaps. Give them a try on the next multi-step task you'd normally hand off with a checklist.

DEV Community: IT Lackey

One Schema to Rule Them All: The Config v2 Rewrite

What the Old Shape Looked Like

What Zod Gives You

The Silent Failure Fixes

Auto-Generated JSON Schema

The New Config Shape

The Minimal Working Config

Migrating from v1

What Adding a Field Looks Like Now

The Proposal Queue Safety Net

How the Queue Works

The 0.8.0 Additions

Bulk Accept Guardrails

Auto-Accept for Trusted Sources

A Daily Review Habit

The Shape of Safe Agent Memory

Your Agent Has a Memory That Runs While You Sleep

What akm improve Does in 24 Hours

Running It on Consumer Hardware

What "Local Models" Actually Means for Quality

Making Continuous Operation Reliable

Knowing It's Working

The Full Picture

From 30 Minutes to 8: How LLM-Mode Reflect Works

Why Reflect Does Not Need an Agent

Multi-Turn Self-Refine

Structured Output

Config to Enable LLM Mode

Local Models and LM Studio

When to Stay on Agent Mode

What Changes in Practice

Belief-Aware Memory: Teaching Your Agent When Not to Write

The Two Capture Modes

The Belief States

What the Improve Loop Actually Checks

Enabling Belief-Aware Memory

The Workflow in Practice

What This Protects Against

Task Assets: Agent Workflows That Run While You Sleep

The Task Asset Format

command: vs prompt:

Registering Tasks

Environment Injection with akm env run

Worked Example: The Discord Health Report

Logging

Building a Task-Driven Operation

The Improvement Loop: How akm Keeps Your Agent Sharp

The Five Phases

Running the Loop

Profiles

The Proposal Queue

Scheduling

Knowing the Loop Is Working

What Changes Over Time

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

TL;DR

akm improve: The New Self-Improvement Surface

End-of-Run Git Sync and Commit Templating

Consolidate Reliability Improvements

Task Assets: Persistent Agent Workflows

Belief-Aware Memory

Proposal Queue: Renamed Commands

akm health: Runtime Checks in One Command

Agent Command Builder: Platform-Aware Dispatch

Graph Extraction: Faster, Cleaner, Schema-Stable

Config v2 and reflect LLM mode

Migration Guidance

Try the New Surfaces

Verification

What akm Actually Does: A Command-by-Command Tour

The Short Version

What akm Is Really For

1. First-Run and Environment Commands

akm setup

akm init

akm config

akm info

akm index

2. Source and Registry Commands

`akm improve`: The New Self-Improvement Surface

`akm health`: Runtime Checks in One Command

`akm setup`

`akm init`

`akm config`

`akm info`

`akm index`

`akm add`

`akm list`

`akm update`

`akm remove`

`akm clone`

`akm save`

`akm registry`

`akm curate`

`akm search`

`akm show`

`akm remember`

`akm import`

`akm wiki`

`akm vault`

`akm workflow`

`akm feedback`

`akm history`

`akm events`

`akm improve`

`akm propose`

`akm improve`

`akm help`

`akm hints`

`akm completions`

`akm upgrade`

Proposal queue (`akm proposal *`)

Three new commands: `reflect`, `propose`, `distill`

`lesson` asset type

`llm.features.*` — opt-in LLM gates

`quality: "proposed"` and `--include-proposed`

`akm-bench` v1