akm-cli 0.9.29 → 0.9.31

package/docs/posts/config-v2-lessons-16.md

@@ -0,0 +1,191 @@
+---
+title: 'One Schema to Rule Them All: The Config v2 Rewrite'
+cover_image: 'https://raw.githubusercontent.com/itlackey/akm/main/docs/posts/akm-logo-sized.webp'
+series: akm-knowledge
+description: 'How replacing ~1.4k LOC of hand-written config parsers with a single Zod schema eliminated silent failures, auto-generates the JSON schema, and makes adding a new config field a one-line change.'
+tags:
+  - ai
+  - agents
+  - cli
+  - configuration
+published: true
+id: 3814550
+date: '2026-06-04T00:32:02Z'
+---
+
+> This is a dated article from AKM's publishing archive. For current product behavior, see the
+> [documentation index](https://github.com/itlackey/akm/blob/main/docs/README.md).
+
+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](https://dev.to/itlackey/akm-080-cli-redesign-task-assets-and-belief-aware-memory-335a) cover the storage and pipeline changes that shipped alongside this rewrite; [Part thirteen](https://dev.to/itlackey/from-30-minutes-to-8-how-llm-mode-reflect-works-5epl) 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`:
+
+```jsonc
+{
+  "$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:
+
+```jsonc
+{
+  "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 [configuration reference](../reference/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:
+
+```sh
+# Preview the transformation without writing
+akm config migrate --dry-run  # doclint:ignore (0.7.x→0.8.0 config-schema migration command, not present in 0.9.0)
+
+# Apply migration — writes a timestamped backup first
+akm config migrate  # doclint:ignore (0.7.x→0.8.0 config-schema migration command, not present in 0.9.0)
+```
+
+`--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:
+
+```sh
+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:
+
+```sh
+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](https://github.com/itlackey/akm/blob/main/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 [configuration reference](../reference/configuration.md). The [0.8.0 release notes](https://dev.to/itlackey/akm-080-cli-redesign-task-assets-and-belief-aware-memory-335a) 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](https://dev.to/itlackey/your-agent-has-a-memory-that-runs-while-you-sleep-20oh) 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.

package/docs/posts/improve-loop-autonomous-10.md

@@ -0,0 +1,225 @@
+---
+title: 'The Improvement Loop: How akm Keeps Your Agent Sharp'
+cover_image: 'https://raw.githubusercontent.com/itlackey/akm/main/docs/posts/akm-logo-sized.webp'
+series: akm-knowledge
+description: 'akm improve runs a multi-phase pipeline — reflect, distill, consolidate, memory inference, graph extraction — that continuously refines your agent knowledge base. Here is what each phase does and how to wire it into your workflow.'
+tags:
+  - ai
+  - agents
+  - cli
+  - automation
+published: true
+id: 3814541
+date: '2026-06-04T00:32:02Z'
+---
+
+> This is a dated article from AKM's publishing archive. For current product behavior, see the
+> [documentation index](https://github.com/itlackey/akm/blob/main/docs/README.md).
+
+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](https://dev.to/itlackey/agents-that-remember-where-they-were-1koe) covered workflow assets, vault assets, and the writable git stash. [Part eight](https://dev.to/itlackey/building-agent-knowledge-bases-that-actually-scale-23pb) 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:
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+akm improve memory          # memory pool only
+akm improve skill           # skills only
+akm improve skills/deploy   # one specific asset
+```
+
+To add extra guidance for the pass — useful when you know a particular focus area is relevant:
+
+```sh
+akm improve --task "focus on deduplication in the build tooling notes"
+```
+
+To cap the number of assets processed (highest-utility first by default):
+
+```sh
+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:
+
+```sh
+akm improve --profile quick  # doclint:ignore (0.8.0-era flag spelling for this configVersion-0.8.0 post; renamed `--strategy` in 0.9.0)
+akm improve --profile memory-focus  # doclint:ignore (0.8.0-era flag spelling for this configVersion-0.8.0 post; renamed `--strategy` in 0.9.0)
+```
+
+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:
+
+```jsonc
+{
+  "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:
+
+```sh
+akm proposal list
+akm proposal list --status pending
+```
+
+Inspect a specific proposal:
+
+```sh
+akm proposal show <id>
+akm proposal diff <id>       # side-by-side diff vs. the live asset
+```
+
+Accept or reject:
+
+```sh
+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:
+
+```sh
+akm improve --auto-accept=90     # explicit threshold (same as the default) — doclint:ignore (0.8.0-only flag; 0.9.0 replaced threshold auto-accept with the proposal queue/drain engine)
+akm improve --auto-accept=false  # disable auto-accept, send everything to queue — doclint:ignore (0.8.0-only flag; 0.9.0 replaced threshold auto-accept with the proposal queue/drain engine)
+```
+
+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:
+
+```yaml
+# ~/akm/tasks/improve-loop.yml
+name: improve-loop
+trigger:
+  cron: '*/30 * * * *'
+agent:
+  command: akm
+  args: ["improve", "--profile", "default", "--limit", "30"]
+enabled: true
+```
+
+Register the task:
+
+```sh
+akm tasks sync  # doclint:ignore (`tasks` was renamed to singular `task` in 0.9.0)
+```
+
+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:
+
+```jsonc
+"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:
+
+```sh
+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 [configuration reference](../reference/configuration.md). Profile options, LLM connection setup, and scheduling details are in the [improvement loop architecture doc](../architecture/improvement.md). 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](https://dev.to/itlackey/your-agent-has-a-memory-that-runs-while-you-sleep-20oh). The repo is at [github.com/itlackey/akm](https://github.com/itlackey/akm).

package/docs/posts/improve-pipeline-debugging-0803.md

@@ -0,0 +1,179 @@
+---
+title: 'Your Agent Has a Memory That Runs While You Sleep'
+cover_image: 'https://raw.githubusercontent.com/itlackey/akm/main/docs/posts/akm-logo-sized.webp'
+series: akm-knowledge
+description: 'akm improve runs continuously on consumer GPUs with local models, curating your agent knowledge base in the background. Here is what 24 hours of autonomous operation looks like, what hardware it takes, and what we fixed to make it reliable.'
+tags:
+  - ai
+  - agents
+  - cli
+  - local-ai
+published: true
+id: 3814547
+date: '2026-06-04T00:32:02Z'
+---
+
+> This is a dated article from AKM's publishing archive. For current product behavior, see the
+> [documentation index](https://github.com/itlackey/akm/blob/main/docs/README.md).
+
+This post is part of the akm-knowledge series. [Part ten](https://dev.to/itlackey/the-improvement-loop-how-akm-keeps-your-agent-sharp-2d4d) 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:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```sh
+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:
+
+```yaml
+# ~/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:
+
+```sh
+akm tasks sync   # register the cron; doclint:ignore (`tasks` was renamed to singular `task` in 0.9.0)
+```
+
+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](../reference/configuration.md). Hardware requirements and LM Studio setup are covered in the [getting started guide](../guides/getting-started.md).