Forem: IT Lackey

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.7.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, reflect, propose, proposal, distill
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 reflect`

Ask an external agent to propose improvements to an existing asset.

akm reflect 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.

`akm proposal`

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 distill`

Summarize feedback into a reusable lesson proposal.

akm distill 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 → `graph.json`

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 prints a step-by-step recipe for what the agent should do next. Something like: 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. The command itself writes nothing — it just prints the workflow. Execution is entirely the agent's job, using its native file tools.

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 distill and akm curate, gated behind llm.features.* flags that are 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.

It's also not autonomous. akm prints the ingest recipe; your agent runs it. If you want fully automated ingestion, you'd wire up a workflow that calls akm wiki ingest, then asks the agent to execute the printed steps. The wiki tooling is the substrate, not the automation layer.

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.

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.

akm 0.6.0: Clean Break to Stash, Quieter CLI, Easier Migration

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

akm 0.6.0 is out. This one is deliberately boring: a stabilization release that takes a clean break from pre-v1 terminology so the surface area we carry into v1 is honest. The domain model now has one noun for "a source of content" (stash) and one noun for "a service that helps discover them" (registry). The parallel vocabulary that accreted during earlier experiments — "kit", "source", hand-special-cased provider types — is gone. A handful of additive quality-of-life improvements ship alongside, but the headline story is fewer concepts, not more.

If you are on 0.5.x, read the v0.5 → v0.6 migration guide before upgrading. Most projects will work without edits thanks to automatic on-disk migrations; a small number of config fields and CLI flags need explicit updates.

TL;DR

One domain noun: kits / sources → stash everywhere. Wire format, config, CLI help, and docs all use the same word.
Schema v3 for the registry index: stashes[] replaces kits[]. Pre-0.6.0 indexes are no longer read.
akm.lock replaces stash.lock; auto-copied on first run, no action needed.
stashInheritance: "merge" | "replace" replaces the boolean disableGlobalStashes.
primary: true on a stash entry replaces the top-level stashDir field.
--detail=agent is the preferred spelling; --for-agent stays as a deprecated alias.
akm enable context-hub / akm disable context-hub are gone — add context-hub as a regular git stash.
Discovery: registry indexes only packages/repos tagged akm-stash. The pre-0.6.0 akm-kit / agentikit keywords/topics are not honored as fallbacks.

Full details — including before/after code for every item — live in the migration guide.

What "clean break" means

This is a simplification, not a rebrand. Through the pre-v1 releases, akm accumulated three overlapping nouns for the same concept:

"source" — the config field users saw
"kit" — the packaging / publishing story
"stash" — the runtime/storage layer

Three words for one thing made every doc page ambiguous and every new feature pick a side. 0.6.0 collapses the three into stash at every layer — config, wire format, CLI text, docs, error messages. "Agent Kit Manager" stays as the project tagline and akm-cli stays as the package name, because those are product names, not data-model terms. Everything below the product surface is stash.

The registry wire format follows the same logic. Schema v3 drops kits[] and parses only stashes[]. Pre-v1 is the right time to do this: there is no installed base we need to keep parsing legacy wire formats for, and holding onto kits[] just to be polite would trap the v1 contract in historical cruft.

Breaking changes at a glance

Each bullet below links to its section in the migration guide, which has the exact before/after code or config diff.

stash.lock → akm.lock — auto-copied on first run.
installed[] → stashes[] + akm.lock — config cleanup happens on next write.
stashDir → primary: true — automatic.
disableGlobalStashes → stashInheritance — manual, one-line config edit.
--for-agent → --detail=agent — old flag still works as a deprecated alias for one release cycle.
akm enable/disable context-hub removed — add it as a regular git stash.
Wire format kits[] → stashes[] — registry publishers must regenerate.
Discovery keyword / topic akm-kit → akm-stash — publishers must re-tag.

If you consume only the public registry and do not maintain your own, the publisher changes do not apply to you.

What's new (low-key)

A few additive improvements rode along with the cleanup.

akm workflow validate <ref|path> — new subcommand for validating a workflow markdown file or ref; lists every error in one pass (without running a full reindex). A workflow debugging tool to surface issues before they bite at run time.
Memory frontmatter on akm remember — --tag (repeatable), --expires 30d, --source <any-string>, plus opt-in --auto (heuristics) and --enrich (LLM) for deriving tags from the body. Zero-flag akm remember "body" still writes a flat memory, so existing agent scripts are unchanged. Issue #169.

  akm remember "VPN required for staging deploys" \
    --tag ops --tag networking --expires 90d --source "skill:deploy"

Workflow parser accepts intro prose — you can now put a short advisory paragraph between # Workflow: and the first ## Step: without tripping a validation error. Issue #158.
Workflow resume reclassifies blocked steps — akm workflow resume <id> now re-opens the currently-blocked step so you can mark it completed, failed, or skipped after resolving the blocker. Issue #156.
Workflow create works in clean stashes — akm workflow create <name> (and --from <file>) no longer false-positive on a path escape when any ancestor of the stash is a symlink. Issue #157.
Registry search drops empty hit objects — providers returning partial records no longer surface as {} in JSON output; dropped counts appear in warnings so the upstream bug stays visible. Issue #159.
Isolated sandbox recipe — getting-started.md now includes the one-terminal recipe for a throwaway HOME + XDG_* + AKM_STASH_DIR sandbox. Handy for agent testing, CI, and issue reproduction. Issue #160.

None of these require migration action; they are upgrades-by-default once you install 0.6.0.

Migration

Install:

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

Read:

v0.5 → v0.6 migration guide — every breaking change with before/after code; publisher checklist if you maintain a registry or an npm/GitHub stash.

Verify:

akm info --format text            # version 0.6.x, no context-hub provider
akm config list                   # stashes[] populated, no installed[]
akm list                          # your sources resolve cleanly

If something looks wrong after upgrade, the guide has a troubleshooting section covering the common pitfalls (stale context-hub entries, v2 registry URLs, empty stashes[] after a read-only upgrade path).

What's next

0.6.0 is a punctuation mark, not a destination. The next moves are narrower scope and fewer concepts, in that order. Expect the 0.6.x series to pick up whatever friction falls out of this rename; 0.7 starts shaping the contract we intend to freeze at v1.

Thank you to everyone who stayed on pre-v1 through the terminology churn. The point of doing this now — while the installed base is small enough to move together — is that we only do it once. The v1 surface begins here.

Full changelog at CHANGELOG.md.

akm 0.5.0: Wikis, Workflows, Vaults, and a Writable Stash

IT Lackey — Fri, 24 Apr 2026 05:18:44 +0000

akm 0.5.0 is out. This release adds three new asset types — wikis, workflows, and vaults are now first-class citizens — plus writable git stash support so your stash can sync back to a remote. It also upgrades the self-update path to cover npm, bun, pnpm, and binary installs, and ships a new akm help migrate command for release-to-release guidance. There is one breaking change for anyone who was using the single-wiki LLM POC from 0.4.x.

TL;DR

akm wiki create|register|list|show|remove|pages|search|stash|lint|ingest — multi-wiki support, no LLM required
akm workflow template|create|start|next|complete|status|list|resume — multi-step agent procedures in the stash
akm vault list|show|create|set|unset|load — .env-backed secrets that never appear in structured output
akm add <source> --writable + akm save — push your stash changes back to a remote git repo
akm add <source> --trust — bypass the install audit for a single install
akm add --type wiki --name <name> <source> / akm wiki register — register an existing directory or repo as a first-class wiki
akm upgrade now covers npm, bun, pnpm, and standalone-binary installs
akm help migrate <version> prints release notes and migration guidance for any shipped release
Breaking: the single-wiki LLM POC is removed; migrate to akm wiki …

Multi-wiki support

The biggest addition in 0.5.0 is a proper wiki asset type. A wiki is a structured knowledge base living at <stashDir>/wikis/<name>/ with a defined layout: schema.md describes what goes in it, index.md is auto-generated by akm index, log.md tracks change history, raw/ holds unprocessed source material, and the rest are agent-authored pages.

# Create a new wiki
akm wiki create architecture

# List all wikis
akm wiki list

# See what pages a wiki has
akm wiki pages architecture

# Search within a wiki
akm wiki search architecture "deployment"

# Lint a wiki for structural problems
akm wiki lint architecture

# Ingest raw content into raw/
akm wiki stash architecture ./notes/adr-001.md

# Print the ingest workflow for the wiki
akm wiki ingest architecture

Wiki pages are indexed by akm index and show up in stash-wide akm search, so you do not need to remember which wiki a page lives in. Raw sources under raw/ plus the wiki root infrastructure files schema.md, index.md, and log.md are intentionally excluded from indexing and search results. Running akm index also regenerates each wiki's index.md as a side effect.

The design principle is akm surfaces, the agent writes. akm makes no LLM calls. It owns only the operations where correctness is structural and deterministic: lifecycle management, raw-slug uniqueness, lint checks, index regeneration. The agent owns page content. This keeps the CLI fast and predictable — a wiki command always completes in milliseconds, and you can run it in any environment without model configuration.

The 10-verb surface (create, register, list, show, remove, pages, search, stash, lint, ingest) covers the full lifecycle from creation to indexing to removal.

If you already have a wiki-shaped directory or repo you want to adopt without copying it, use akm wiki register:

# Register a local directory as a first-class wiki
akm wiki register notes ~/team/notes

# Or via the unified add command
akm add --type wiki --name notes ~/team/notes

# Registered external wikis show up in both `akm list` and `akm wiki list`

Registration refreshes source state and wiki search hits immediately, and the indexer normalizes external wiki refs on subsequent runs.

Workflow asset type

Workflows are multi-step procedures stored in the stash. An agent running a complex process — a release checklist, an onboarding sequence, a debugging runbook — can use akm workflow next to step through it deterministically rather than relying on its context window to track state.

# Author a workflow
akm workflow create release-checklist

# Start an instance
akm workflow start workflow:release-checklist

# Advance to the next step
akm workflow next workflow:release-checklist

# Check where you are
akm workflow status workflow:release-checklist

# Mark a specific step done (defaults to --state completed)
akm workflow complete <run-id> --step validate --notes "Inputs verified"

# List all workflow runs
akm workflow list

# Print a starter workflow you can adapt
akm workflow template

Workflows live in the stash like any other asset, so akm search workflow:… finds them and akm show workflow:release-checklist renders the current step. They can be shared in a stash and versioned in a git stash.

Vault asset type

Vaults store secrets and environment configuration. Each vault is a .env file in the stash. The key constraint: vault values never appear in structured output. akm show vault:<name> and akm vault list display key names and metadata, but not the values themselves.

# List vaults
akm vault list

# Show keys in a vault (no values)
akm show vault:prod-secrets

# Create a new empty vault
akm vault create prod-secrets

# Set a key (three-positional form or combined KEY=VALUE form)
akm vault set vault:prod-secrets API_KEY abc123
akm vault set vault:prod-secrets API_KEY=abc123 --comment "Rotate every 90 days"

# Remove a key
akm vault unset vault:prod-secrets API_KEY

# Print the vault file path for current-shell loading
source "$(akm vault path vault:prod-secrets)"

# Run one command with the vault injected
akm vault run vault:prod-secrets -- env

akm vault path is the current-shell loading path and akm vault run is the one-shot command execution path. Values never appear in structured output; vault run passes them directly to the child process environment.

This is a deliberate tradeoff: vaults are not a full secrets manager. They are a thin, auditable layer that keeps your .env files alongside your other agent assets and prevents accidental leakage through akm show or akm search results.

Writable git stash and `akm save`

Until now, git-backed stashes were read-only: akm add github:owner/repo would clone the repo, but you could not push changes back. 0.5.0 changes that.

# Clone a git stash and opt it into push-on-save
akm add github:your-org/your-stash --writable

# Make some changes — add a skill, author a wiki page, record a memory
akm remember "Production DB is read-only on Sundays"

# Commit and push
akm save -m "add production DB note"

If the stash has a remote configured and --writable was used on install, akm save runs git commit and git push. Without --writable (or without a remote), it commits locally only.

The default stash is now auto-initialized as a git repo on akm setup, so akm save works out of the box even before you wire up a remote.

The git stash provider also switches from HTTP tarball download to git clone, which means you get proper git history and the ability to git pull manually if you prefer.

`--trust` flag for installs

akm 0.4.0 added a pre-install audit that scans stash contents for dangerous patterns. By default, installs from unrecognized sources require confirmation. For sources you know and trust, you can skip the audit entirely:

akm add github:your-org/internal-stash --trust

--trust is a one-off bypass — it does not add the source to any persistent allowlist. Use it when you control the source and do not want to step through the audit prompt in a non-interactive context (a CI script, an automated agent workflow, a container build).

When a blocked install error occurs, the error message includes a hint field referencing --trust as a remediation option.

Breaking change: single-wiki LLM POC removed

If you were using the wiki functionality introduced in 0.4.1, you will need to migrate. The following have been removed:

akm lint command
akm import --llm and akm import --dry-run flags
knowledge.pageKinds config key
The ingestKnowledgeSource and lintKnowledge LLM prompts

Migration path:

Create a wiki for your content: akm wiki create <name>
Move raw source files into wikis/<name>/raw/: akm wiki stash <name> <file>
Have your agent author wiki pages from the raw content
Run akm index to regenerate the wiki index

The new surface is more capable — 10 verbs vs the old 2, proper multi-wiki support, structural lint, and page search — and it does not require an LLM to be configured for any of the CLI operations.

Broader `akm upgrade` coverage

akm upgrade used to assume a standalone-binary install. 0.5.0 detects how akm was installed (npm, bun, pnpm, or binary) and runs the right self-update path for each. The same command now works whether you bootstrapped from the install script or from a package manager, and the internal runtime-asset coverage was expanded so newly shipped asset types stay up to date after an upgrade.

akm upgrade              # Works for binary, npm, bun, and pnpm installs
akm upgrade --check      # Report whether an update is available, without installing

`akm help migrate <version>` — release notes at the CLI

Release notes belong where you're actually working. akm help migrate prints the relevant CHANGELOG section plus embedded migration guidance for a given version, so you can review what changed (and what to do about it) without leaving the terminal.

akm help migrate 0.5.0     # or v0.5.0
akm help migrate latest    # resolve against the most recent CHANGELOG entry

It favors the bundled CHANGELOG section when it exists and falls back to an embedded summary and a link to the full changelog otherwise.

Upgrade

akm upgrade

Or reinstall from scratch:

curl -fsSL https://raw.githubusercontent.com/itlackey/akm/main/install.sh | bash

Full changelog at CHANGELOG.md.

Note (2026-04-23): This post has been updated to align with akm 0.6.0 terminology. Earlier wording referred to a kit and the Kit Maker's Guide; those terms have been renamed to stash and Stash Maker's Guide throughout. The pre-rename text is preserved in this repository's git history.

Your Agent Loads 47 Skills at Startup. It Needs Three.

IT Lackey — Tue, 21 Apr 2026 03:24:25 +0000

Quick recap if you're joining mid-series. In part one, I introduced the problem: your agent's skill list is growing faster than you can manage it, and dumping everything into context makes things worse, not better. Part two showed how akm unifies your existing Claude Code, Cursor, and Codex assets into one searchable stash. Part three covered persistent memory across sessions. Part four connected your agent to community knowledge through a shared git stash.

This post zooms in on the pattern that makes all of that work: progressive disclosure. I've mentioned it in every post so far, but I haven't really shown the math or walked through what actually happens under the hood. Let's fix that.

You're Paying for Context You Don't Use

Say you've got 47 skills across three platforms. That's not a crazy number — if you've been building with agents for a few months, you're probably there already. The average skill file runs about 1,000 tokens.

Now do the napkin math.

Load everything at startup: 47,000 tokens. Your agent sees all of it, whether the current task needs zero skills or five. Those extra 42,000 tokens aren't free. They degrade response quality, increase latency, and cost real money on metered APIs.

Search first, load second: A search query comes back with 20 results at ~100 tokens each. That's 2,000 tokens. Your agent reads the summaries, decides it needs one skill, and loads it: 1,000 tokens. Total: 3,000 tokens.

That's a 94% reduction. Not by being clever with compression or prompt engineering. Just by not loading stuff you don't need.

The math alone justifies the pattern. But the implementation is where it gets interesting.

How It Actually Works

There are three steps. Search, load, and drill down. Here's what each one looks like.

Search

akm search "deploy to staging"

This returns a ranked list of matching assets across all your sources. Each result has the asset type and name (skill:deploy-staging), where it came from, a description snippet, and a relevance score.

Total cost: ~100 tokens per result. Your agent scans this list and decides what's relevant. Most of the time, it needs one or two assets out of twenty results. The other eighteen never enter the context window.

Load

akm show skill:deploy-staging

Now the agent loads the full content of a single asset. The complete skill definition, instructions, examples — everything it needs to act. This is the only moment the full content enters the context window, and only for the assets the agent specifically chose.

Cost: ~500-1,500 tokens per asset, depending on complexity.

Drill Down

akm show knowledge:api-guide toc
akm show knowledge:api-guide section "Authentication"

For knowledge assets — documentation, guides, API references — akm supports table-of-contents navigation. The agent can see the structure of a document and request a specific section instead of loading the whole thing.

A 10,000-token API guide becomes a 200-token table of contents, then a 1,500-token section load. The agent never sees the eight sections it doesn't need.

It Works Across All Your Tools

Here's the part that most implementations miss. Claude Code does progressive disclosure for skills in ~/.claude/skills/. That's great — for Claude Code. But what about your Cursor rules? Your Codex agents? Your team's shared Git repository of skills?

Every platform implements this pattern within its own silo. akm implements it across silos.

# One-time setup: point akm at everything
akm add ~/.claude/skills
akm add ~/.codex/skills
akm add .cursor/rules
akm add github:your-org/team-skills

# Every search hits all sources
akm search "database migration"

That single search query returns ranked results from every source. The scoring pipeline treats local filesystem assets and remote Git-hosted assets fairly — no source gets artificially boosted or suppressed. The best match wins, regardless of where it lives.

What a Real Session Looks Like

Your agent gets a task: "Deploy the staging environment with the new database migration."

Search. The agent runs akm search "deploy staging database migration". Gets 15 results across three sources.
Evaluate. The agent reads the result summaries (~1,500 tokens). Identifies two relevant assets: skill:deploy-staging and knowledge:migration-runbook.
Load. The agent runs akm show skill:deploy-staging and akm show knowledge:migration-runbook. Loads ~2,500 tokens of directly relevant content.
Act. The agent executes the deployment using the loaded skill and references the runbook for the migration steps.

Total context cost: ~4,000 tokens. Without progressive disclosure, the agent would've loaded all 47 skills (47,000 tokens) and still might not have found the migration runbook because it lives in a different source than the deployment skill.

Setting It Up

The agent integration is a two-line addition to your AGENTS.md:

## Agent Stash

Search for skills, commands, and knowledge using `akm search <query>`.
View full details with `akm show <ref>`.

That's the entire interface. The agent knows how to search, knows how to load, and handles the progressive disclosure pattern on its own. No configuration, no routing rules, no platform-specific adapters.

This Is What Makes Teams Work

Progressive disclosure becomes even more valuable at team scale. When your team has hundreds of shared skills plus each developer's personal collection, front-loading is physically impossible. Search-then-load isn't just an optimization — it's the only viable approach.

In the next post, I'll cover how teams can share skills across a group while preserving individual customization. The progressive disclosure pattern is the foundation that makes team-scale skill management work.

If you want to see this in action, the repo is at github.com/itlackey/akm. Point it at your skill directories, run a search, and see how much context you've been wasting.

Note (2026-04-23): This post has been updated to align with akm 0.6.0 terminology. Earlier wording referred to a kit and the Kit Maker's Guide; those terms have been renamed to stash and Stash Maker's Guide throughout. The pre-rename text is preserved in this repository's git history.

Your Team's Agent Skills Are a Mess. Here's How to Fix It.

IT Lackey — Tue, 31 Mar 2026 06:22:03 +0000

This is part seven 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 remote context via OpenViking. Part four connected community knowledge through Context Hub.

Everything up to now has been about you. Your skills. Your stash. Your agent. That's fine when you're working solo, but most of us aren't.

You've got a deploy skill. Your teammate has one too. They do slightly different things — yours includes the canary step, theirs adds a Slack notification you didn't know about. A third person on the team wrote theirs for Codex and it skips the canary entirely.

Now the deploy process changes. Say the team adds a new staging environment. You update your skill. You mention it in standup. Your teammate says they'll update theirs later. The third person was out that day and doesn't hear about it. Two weeks later, someone deploys to the wrong environment because their skill still has the old configuration.

This isn't hypothetical. If your team uses AI coding assistants, this is happening right now. Every developer building up their own skill collection, no shared source of truth, no way to know when someone else has a better version of the same thing.

Every agent skills article on the internet is written for individual developers. But teams are where skills become both most valuable and most chaotic. Here's how to fix it.

The Simplest Thing: A Shared Directory

Your team already has a shared drive or mounted directory? Use it.

# Team lead creates the shared source
mkdir -p /mnt/shared/team-skills/skills/deploy
cat > /mnt/shared/team-skills/skills/deploy/SKILL.md << 'EOF'
# Deploy to Production

Standard deployment workflow for all services.

## Steps
1. Run test suite: `bun test`
2. Build: `bun run build`
3. Deploy to staging: `./scripts/deploy.sh staging`
4. Run smoke tests: `./scripts/smoke.sh staging`
5. Deploy to production: `./scripts/deploy.sh production`
6. Notify #deploys channel in Slack

## Rollback
If smoke tests fail: `./scripts/rollback.sh staging`
EOF

Each developer adds it as a source:

akm add /mnt/shared/team-skills
akm search "deploy"

That's it. The shared skill shows up in everyone's search results alongside their personal skills. When the team lead updates the deploy skill, everyone sees the update on the next index refresh. No copying. No syncing. No "hey, I updated the deploy skill" messages in Slack.

This works best for co-located teams or teams that already share infrastructure. Zero overhead to set up.

Git for Distributed Teams

If your team is distributed, a Git repo is the natural choice. You already use Git for everything else — why not for skills?

# Team lead creates the repo
# github.com/your-org/team-agent-skills
# Standard stash structure: skills/, commands/, knowledge/

# Each developer adds it
akm add github:your-org/team-agent-skills

# Pull latest when needed
akm update --all

This buys you everything Git already provides:

Version history. See when the deploy skill changed and why.
Pull request review. New skills and updates go through the same review process as code.
Branch-based testing. Try a new version of a skill on a branch before merging.
CI integration. Lint your skill files, validate structure, run tests.

A new developer runs akm add, and they've got the entire team's skill library indexed and searchable immediately. No onboarding doc that says "copy these files to these directories."

Private Registry for Larger Orgs

For larger teams or organizations that want discoverability without mandating specific skills, akm supports private registries. Think npm for agent skills, but hosted internally.

# Search the team registry
akm search "deploy" --registry https://registry.internal.company.com

# Install a specific skill from the registry
akm add registry:deploy-to-k8s

This makes more sense when your organization has dozens of teams, each with their own skills, and you want cross-team discovery without requiring everyone to index everything. Also handy when you need access control — some skills are sensitive.

When the Team Skill Doesn't Quite Fit

Here's the scenario every team hits: the standard deploy skill works for 90% of cases. But your project has a specific environment variable, an extra pre-deploy step, or a different notification channel.

You don't want to modify the team skill — that breaks it for everyone else. You don't want to write your own from scratch — that's the duplication problem we started with.

akm clone solves this:

# Fork the team skill into your personal source
akm clone skill:deploy

# Now you have a local copy to customize
# Edit ~/.akm/sources/default/skills/deploy/SKILL.md
# Add your project-specific steps

The team version stays clean. Your fork is yours to customize. Both appear in your search results — the team version and your customized version — with the local fork ranked higher since it's in your personal source.

When the team updates their version, you can re-clone to get the update and reapply your customizations. Or diff the two versions to see what changed.

Putting It Together

Here's what the full workflow looks like for a team of five:

Team lead (one-time setup):

# Create the team skills repo
mkdir team-agent-skills
cd team-agent-skills
akm setup
# Add skills, commands, knowledge
# Push to github.com/your-org/team-agent-skills

Each developer (one-time setup):

# Add team source alongside personal sources
akm add github:your-org/team-agent-skills
akm add ~/.claude/skills
akm add ~/.codex/skills

Daily workflow:

# Search finds results from all sources
akm search "deploy"

# Team skill and personal skills appear together
# Best match wins, regardless of source

# Pull team updates
akm update --all

When customization is needed:

akm clone skill:deploy
# Edit local copy
# Both versions stay searchable

No file copying. No sync scripts. No "which version is correct?" conversations. The team source is the source of truth. Personal forks are explicitly personal. Search finds everything.

Why This Scales

This whole workflow is built on the progressive disclosure pattern from the previous post. At team scale, it's not just an optimization — it's a necessity.

A team of five, each with 30 personal skills plus 50 shared team skills, has 200 total skills in play. Front-loading all of them into every agent session would cost 200,000+ tokens. With akm's search-then-load pattern, each session uses only the 2-5 skills it actually needs.

The agent doesn't know or care whether a skill came from the team source, a personal directory, or a Git repository. It searches, it finds, it loads. The source management is your concern as a developer. The skill content is the agent's concern. Clean separation.

Getting Started

If you're a team lead looking to set up shared skills:

Pick your approach — shared filesystem for co-located teams, Git repo for distributed teams, registry for large organizations
Create the shared source with a standard stash structure
Have each developer run akm add to register the source
Start with 3-5 high-value skills that everyone uses (deploy, test, review, etc.)
Iterate from there

The infrastructure is minimal. The payoff is immediate.

Give it a shot and let me know how it holds up. The repo's at github.com/itlackey/akm, and the Getting Started guide will get you wired up in a few minutes.

Note (2026-04-23): This post has been updated to align with akm 0.6.0 terminology. Earlier wording referred to a kit and the Kit Maker's Guide; those terms have been renamed to stash and Stash Maker's Guide throughout. The pre-rename text is preserved in this repository's git history.

Stop Copying Skills Between Claude Code, Cursor, and Codex

IT Lackey — Sun, 29 Mar 2026 16:31:49 +0000

This is part five in a series about wrangling the growing pile of skills, scripts, and context that AI coding agents depend on. In part one, I covered why progressive disclosure beats dumping everything into context. Part two showed how akm unifies your local assets across platforms into one searchable stash. Part three added remote context via OpenViking for teams. And part four plugged in community knowledge through Context Hub.

All of that assumed you were picking one tool. But you're probably not. You've got Claude Code at work, Codex for side projects, Cursor for quick edits. Each one has its own skills directory — ~/.claude/skills/, ~/.codex/skills/, .cursor/rules/ — and none of them can see each other.

So you rebuild the same deploy skill twice. You forget where the good version of your testing scaffold lives. You copy files between directories and they drift within a week. You end up grepping across three different paths trying to find the one that handled database migrations correctly.

This isn't a tooling problem. It's a discovery problem. And in the past week alone, three separate products launched to fix it — a macOS GUI for browsing skill files, a web-based editor for organizing them, a designer's viral Medium post about layered architecture for skills. People are clearly hurting here.

But every one of those solutions wants you to move your files somewhere. Copy them into a central location. Sync them between directories. Maintain one source of truth that you manually keep updated.

There's a better approach: don't move anything. Just make everything searchable.

Copy and Sync (The Obvious Way)

Pick a canonical directory, copy everything into it, keep it updated. Tools like ClaudeMDEditor make this easier with a GUI, and symlinks can automate some of it.

Works great — until it doesn't. You update the original and forget to sync. The copy drifts. You end up with two versions of the same skill, slightly different, and no way to tell which is current. The maintenance overhead scales linearly with every new skill and every new platform.

GUI Discovery (The Pretty Way)

Tools like Chops give you a nice interface for browsing your skill files. You can see what's where, organize them visually, tag them.

But your agent can't use a GUI. When Claude Code is mid-task and needs a deployment skill, it can't open an Electron app and browse around. It needs something it can call — a programmatic interface that returns results without human intervention.

Index in Place (The akm Way)

This is the approach akm takes. Don't move your files. Don't copy them. Don't sync them. Just point at them and build an index.

Your skills stay exactly where each tool expects them. Claude Code still finds its skills in ~/.claude/skills/. Cursor still reads .cursor/rules/. Nothing breaks. But now there's a single search layer across all of them.

When your agent needs something, it searches once and gets results from every source. When you update a skill in its original location, the index picks up the change. No sync step. No drift.

Five Commands and You're Done

Here's the full setup. Takes about 30 seconds.

# Install
curl -fsSL https://raw.githubusercontent.com/itlackey/akm/main/install.sh | bash

# Initialize
akm setup

# Point at your existing skill directories
akm add ~/.claude/skills
akm add ~/.codex/skills
akm add .cursor/rules

# Search across all of them
akm search "deploy"

That last command returns results from every source, ranked by relevance. Each result shows the asset type, name, source, and a snippet. Your agent — or you — can load the full content:

akm show skill:deploy-to-production

Only the skill you need gets loaded into context. Everything else stays out.

Tell Your Agent About It

Here's the part that ties it all together. Drop this into your AGENTS.md, CLAUDE.md, or system prompt:

## Resources & Capabilities

Search for skills, commands, and knowledge using `akm search <query>`.
View full details with `akm show <ref>`.

That's the entire integration. No plugins, no SDKs, no integration code. Any model that can run shell commands can use akm. Claude Code, Codex, Cursor — if it has a terminal, it works.

The agent runs akm search to find what it needs, akm show to load the content, and gets to work. Everything else stays out of context. Progressive disclosure — the agent discovers what exists, then activates only what it needs. If that pattern sounds familiar, I covered the architecture behind it in part one.

What's Next

This post covered the individual developer workflow — one person, multiple tools, skills everywhere. But what happens when a team of five developers each has their own skills across three platforms? That's where things get interesting, and where akm's source model, Git integration, and private registry support come into play.

For now: install akm, point it at your directories, and run akm search. You'll be surprised how many skills you already have.

Give it a look at github.com/itlackey/akm. If you've got agent assets scattered across platforms, give it a shot and let me know what breaks.

Your Agent Doesn't Know What the Community Already Figured Out

IT Lackey — Wed, 18 Mar 2026 18:09:15 +0000

This is part four in a series about managing the growing pile of skills, scripts, and context that AI coding agents depend on. In part one, I covered why progressive disclosure beats dumping everything into context. Part two showed how akm unifies your local assets across platforms into one searchable stash. Part three added remote context via OpenViking for teams that need persistent, shared knowledge.

All of that assumed you were building your own library from scratch. Your skills. Your knowledge docs. Your team's accumulated context. That's fine — and it's necessary — but it ignores a much larger resource: everything everyone else has already built.

Right now, there are high-quality skills and knowledge documents sitting in public repositories that solve problems you're going to hit next week. Prompt-chaining patterns. API integration guides. Framework-specific coding conventions. Stuff that experienced practitioners have refined and published, ready to use. Your agent has no idea any of it exists.

That's what the Context Hub integration fixes.

What Is Context Hub?

Context Hub is a public GitHub repository — originally curated by Andrew Ng's team — structured specifically for agent consumption. It organizes community-contributed knowledge and skills into a browsable, searchable hierarchy under a content/ directory. Each entry is either a DOC.md (knowledge) or a SKILL.md (skill), with frontmatter metadata for descriptions, tags, languages, and versions.

Think of it like a curated package registry, except instead of code libraries, it's agent context. Each document is a self-contained piece of knowledge or a skill definition that any agent can pick up and use immediately. No installation, no dependencies, no build step.

The structure is intentionally simple:

content/
  openai/
    docs/
      chat-api/
        python/
          DOC.md
    skills/
      prompt-chaining/
        SKILL.md
  anthropic/
    docs/
      tool-use/
        typescript/
          DOC.md

Every entry gets indexed into the same search pipeline as your local assets, which means akm can search and display it the same way it handles anything else in your stash.

One Command to Connect

If you already have akm installed:

akm add context-hub

That's the full setup. Under the hood, this adds the default Context Hub repository as a git source. It downloads the repo as an archive, extracts it into a local cache, and on the next akm index, every DOC.md and SKILL.md gets indexed into the same FTS5 search pipeline as your local assets.

The cache refreshes automatically every 12 hours. If the network is down, it falls back to stale cache for up to 7 days. Your local stash still works regardless — the Context Hub provider degrades gracefully without taking anything else down with it.

Verify it's registered:

akm list

You should see context-hub in the list alongside your local stash directories and any other providers you've configured.

Search Works the Same Way

Here's what changes in practice: nothing about your workflow. You still run akm search. The difference is that results now include entries from Context Hub alongside your local assets.

akm search "prompt chaining patterns"

This might return a local skill you wrote last month and a community-contributed skill from Context Hub. The results are unified — same ranking, same format, same type:name refs. Context Hub assets go through the same scoring pipeline as everything else. No special handling, no second-class results.

Want to narrow it down to just skills?

akm search "api integration" --type skill

Or just knowledge documents?

akm search "coding standards" --type knowledge

The type filter applies across all sources — local, remote, and Context Hub alike.

Show Works Too

When you find something useful, load it the same way you'd load any other asset:

akm show skill:prompt-chaining

Your agent gets the full content — frontmatter, description, the complete skill definition — in the same format as every other akm show result. It doesn't need to know the asset lives on GitHub. It doesn't need a GitHub token. It just works. The ref is type:name, same as a local asset.

Context Hub assets support the same view modes as local knowledge docs:

# Table of contents
akm show knowledge:chat-api toc

# A specific section
akm show knowledge:chat-api section "Authentication"

# A line range
akm show knowledge:chat-api lines 10 25

For large documents, the toc and section views keep context lean. Your agent can scan the table of contents first, then pull only the section it needs. Progressive disclosure all the way down.

Custom Context Hub Repositories

The default akm add context-hub points at Andrew Ng's repository, but you're not limited to that. Any GitHub repository works as a git source — you don't need to follow a specific directory convention. akm walks the repo, classifies files by type, and indexes everything.

Say your organization maintains an internal knowledge base for agent context — API references, architecture decisions, coding standards:

akm add https://github.com/your-org/team-knowledge \
  --provider git \
  --name "team-knowledge"

Now akm search queries your team's knowledge base alongside the public Context Hub and your local stash. All in one search. You can add as many git sources as you want — each gets its own cache and index.

Need a specific branch instead of main?

akm add https://github.com/your-org/team-knowledge/tree/staging \
  --provider git \
  --name "team-staging"

The provider parses the GitHub URL and pulls the right branch automatically.

What Your Agent Actually Sees

This is where the pieces from the whole series come together. After four posts, here's what a fully-wired akm search looks like from your agent's perspective:

akm search "deploy containers to production"

Results might include:

A local script from your primary stash — the deploy script you wrote last month
A team skill from an installed GitHub stash — the Docker Compose workflow your teammate packaged
A knowledge doc from OpenViking — the architecture decision about container orchestration from last sprint
A community skill from Context Hub — a battle-tested container deployment pattern that 50 other people have already vetted

Four different sources. One result set. One akm show command to load whichever one the agent needs. Everything else stays out of context.

The agent doesn't need to care about where an asset lives. Local file, managed source, OpenViking server, git repo — every result uses the same type:name ref. The agent searches, picks, loads, and gets to work.

The Full Stack

Here's what the complete setup looks like after four posts:

# Install
curl -fsSL https://raw.githubusercontent.com/itlackey/akm/main/install.sh | bash
akm setup

# Local platform assets
akm add ~/.claude/skills
akm add .opencode/skills
akm add .cursor/rules

# Community and team stashes
akm add github:your-org/team-agent-toolkit
akm add @scope/deploy-skills

# Community knowledge (Context Hub is just a git repo)
akm add context-hub

# Team knowledge (any git repo works)
akm add https://github.com/your-org/team-knowledge \
  --provider git \
  --name team-knowledge

# Remote context server
akm add https://your-viking.internal:1933 \
  --provider openviking \
  --name team-context \
  --options '{"apiKey":"..."}'

# Build the local index
akm index

Drop the AGENTS.md snippet into every project:

## Resources & Capabilities

You have access to a searchable library of scripts, skills, commands, agents,
knowledge, and memories via the `akm` CLI. Use `akm -h` for details.

And your agent has access to everything: local skills, platform assets, team stashes, community registries, remote knowledge, persistent memories, and curated community context. One search, one interface.

Why This Matters

The value of agent skills and knowledge compounds when it's shared. A prompt-chaining pattern that one person refines over a weekend becomes infrastructure when a thousand agents can find it. A coding standard document that one team writes becomes a community resource when it's discoverable from any stash.

Context Hub isn't the only way this will happen — community registries, marketplace-style discovery, and decentralized skill sharing are all coming. But it's working today, it's open source, and it plugs directly into the same akm search / akm show workflow you're already using.

If you've written skills or knowledge docs worth sharing, consider contributing them to Context Hub. Structure them with frontmatter, put them in a content/ directory, and they become searchable for every agent running akm.

The repo is at github.com/itlackey/akm. Context Hub is at github.com/andrewyng/context-hub. If you've got a team knowledge base in a git repo, add it as a git source and let me know how it holds up.

Update (March 2026): This post was updated to reflect akm's current CLI. akm add replaces the earlier akm stash add for adding sources (including git and OpenViking providers), akm setup replaces akm init, and akm list replaces akm stash list. Sources (formerly "stash sources") are now managed through a single akm add / akm remove interface. If you're following along with an older version, akm upgrade will get you current.

Note (2026-04-23): This post has been updated to align with akm 0.6.0 terminology. Earlier wording referred to a kit and the Kit Maker's Guide; those terms have been renamed to stash and Stash Maker's Guide throughout. The pre-rename text is preserved in this repository's git history.

Your Agent's Memory Shouldn't Disappear When the Session Ends

IT Lackey — Tue, 17 Mar 2026 16:07:09 +0000

This is part three in a series about managing the growing pile of skills, scripts, and context that AI coding agents depend on. In part one, I talked about why progressive disclosure beats loading everything into context. In part two, I showed how akm unifies your existing Claude Code, OpenCode, and Cursor assets into one searchable stash.

Both of those were about files on disk. Local skills, local scripts, local knowledge documents. That covers most people's immediate pain, but it leaves a bigger problem on the table: what happens when the context your agent needs isn't local?

Think about project architecture docs that live in a shared knowledge base. Team decisions captured during previous sessions. Coding standards that evolve over time and shouldn't be copy-pasted into every developer's stash. Agent memories that accumulate across conversations and need to persist somewhere more durable than a markdown file in a git repo.

That's where OpenViking comes in, and why akm now supports it as a first-class provider.

What Is OpenViking?

OpenViking is an open-source context database built by ByteDance's Volcano Engine team. Instead of treating agent context as flat vectors in a RAG pipeline, it organizes everything — memories, resources, skills — into a hierarchical virtual filesystem with semantic search.

The part that matters: it stores and retrieves agent context (project docs, team decisions, coding standards) via a REST API. When you connect it to akm, its content shows up in search results alongside your local assets — same type:name refs, same ranking, same akm show workflow.

The part that matters for akm is the API. OpenViking exposes REST endpoints for search (semantic and text), content read, and file stat. That's exactly what a provider needs: the ability to find things and retrieve them. So we built one.

Adding OpenViking as a Source

If you already have akm installed and an OpenViking server running, the setup is one command:

akm add http://localhost:1933 --provider openviking

That registers the server as a source. From that point on, akm search queries your local stash and the OpenViking server in parallel. Results from both show up in the same hits[] array, ranked together.

If your server requires authentication:

akm add http://localhost:1933 \
  --provider openviking \
  --options '{"apiKey":"your-api-key"}'

Give it a name to keep things tidy:

akm add http://localhost:1933 \
  --provider openviking \
  --name "team-context" \
  --options '{"apiKey":"your-api-key"}'

Verify it's registered:

akm list

That's the full setup. No config files to hand-edit, no environment variables to set. The provider handles caching, retries, and graceful degradation — if the server goes down, your local stash still works fine and the provider falls back to cached results for up to an hour.

Searching Remote and Local Together

Here's what changes in practice. Before OpenViking, an akm search hit your local stash — your primary directory, search paths, and managed sources. Now it also hits any OpenViking servers you've registered.

akm search "project architecture"

This might return a local skill from your Claude Code directory and a knowledge doc from OpenViking. The results are unified: same format, same scoring, same type:name refs. Your agent can't tell the difference between a local asset and one from OpenViking — and it shouldn't need to.

akm show knowledge:project-context

That fetches the content — from the local index if available, or from the OpenViking server as a fallback. The response comes back in the same format as any other akm show — with a content field, an action field, and type metadata.

By default, OpenViking search uses semantic matching (via POST /api/v1/search/find). If you prefer text search for exact matching, configure the provider with:

akm add http://localhost:1933 \
  --provider openviking \
  --options '{"apiKey":"your-key","searchType":"text"}'

Text search uses OpenViking's grep endpoint, which deduplicates results by URI and ranks them by match frequency.

Standing Up a Test Server

If you want to try this locally before pointing at a shared server, the akm repo includes a ready-made Docker Compose setup:

git clone https://github.com/itlackey/akm.git
cd akm/tests/fixtures/openviking

# Start the server
docker compose up -d

# Wait a few seconds, then seed sample content
./seed.sh

The seed script loads a handful of test documents — project architecture notes, coding standards, an API reference, and a project memory — into the OpenViking server.

Now register it:

akm add http://localhost:1933 \
  --provider openviking \
  --name openviking \
  --options '{"apiKey":"akm-test-key"}'

And test:

akm search "project architecture"
akm show knowledge:project-context

You should get back the full markdown content of the project architecture document. Search works across all sources:

akm search "coding standards"

And if you have Ollama running locally, you can enable semantic search by updating the ov.conf to point the embedding endpoint at your Ollama instance (http://host.docker.internal:11434/v1). Without embeddings, text search and direct content access still work fine.

Tear it down when you're done:

docker compose down

Why This Matters for Teams

The OpenViking integration solves a class of problems that local-only management can't.

Shared context without shared files. Your team can maintain a single OpenViking instance with project documentation, architectural decisions, and coding standards. Every developer's agent can search and retrieve that context without syncing files, mounting network drives, or maintaining parallel copies. Update a document in OpenViking and every agent sees the change immediately.

Persistent memory across sessions. OpenViking's memory system stores recalled context fragments that survive across conversations. When your agent starts a new session, it can search for memories from previous work — akm search "sprint planning decisions" --type memory — and get back what it learned last week. That's a fundamentally different capability than loading the same static skills every time.

Unified search across everything. This is the compounding effect of the whole series. Part one gave you progressive disclosure for local skills. Part two unified your multi-platform assets into one searchable stash. Now part three adds remote context to the same search surface. One akm search query, one result set, one akm show command — regardless of whether the asset is a Claude Code skill in ~/.claude/skills/, a script from an npm stash, or a knowledge document on an OpenViking server across the network.

The Full Picture

After three posts, here's what a fully-wired setup looks like:

# Install
curl -fsSL https://raw.githubusercontent.com/itlackey/akm/main/install.sh | bash
akm setup

# Local platform assets
akm add ~/.claude/skills
akm add .opencode/skills
akm add .cursor/rules

# Community and team stashes
akm add github:your-org/team-agent-toolkit
akm add @scope/deploy-skills

# Remote context server
akm add https://your-viking.internal:1933 \
  --provider openviking \
  --name team-context \
  --options '{"apiKey":"..."}'

# Build the index
akm index

Now drop the AGENTS.md snippet into every project and your agent has access to all of it:

## Resources & Capabilities

You have access to a searchable library of scripts, skills, commands, agents,
knowledge, and memories via the `akm` CLI. Use `akm -h` for details.

Local skills, remote knowledge, team stashes, community registries, persistent memories. One search, one interface, every agent.

The repo is at github.com/itlackey/akm. OpenViking is at github.com/volcengine/OpenViking. Both are open source, both are moving fast, and the combination is genuinely useful infrastructure for anyone running agents in production.

Update (March 2026): This post was updated to reflect akm's current CLI. akm add replaces the earlier akm stash add for adding sources (including OpenViking providers), akm setup replaces akm init, and akm list replaces akm stash list. Sources (formerly "stash sources") are now managed through a single akm add / akm remove interface. If you're following along with an older version, akm upgrade will get you current.

Note (2026-04-23): This post has been updated to align with akm 0.6.0 terminology. Earlier wording referred to a kit and the Kit Maker's Guide; those terms have been renamed to stash and Stash Maker's Guide throughout. The pre-rename text is preserved in this repository's git history.

You Already Have Dozens of Agent Skills. You Just Can't Find Them.

IT Lackey — Mon, 16 Mar 2026 17:26:29 +0000

In the last post, I talked about the problem: your agent's skill collection is growing faster than your ability to manage it. Skills scattered across directories, no search, no sharing, no sanity. I introduced Agent-i-Stash as the fix — a CLI called akm that gives your agent a searchable, indexed stash of assets.

But here's what I glossed over: most of you aren't starting from zero. You've already got skills, commands, agents, and rules spread across multiple platforms. Claude Code has ~/.claude/skills/. OpenCode has .opencode/. Cursor has .cursor/rules/. Codex has its agents.md. You might be using two or three of these tools in the same week, building up assets in each one, and none of them can see each other.

That's the real unlock with akm. It doesn't care where your assets came from. Point it at a directory, and it indexes everything inside. Point it at five directories, and now you've got semantic search across all of them. One command, every platform, every model.

Let me show you how fast this actually works.

Install

Pick your poison:

# Standalone binary (no runtime needed)
curl -fsSL https://raw.githubusercontent.com/itlackey/akm/main/install.sh | bash

# Or via Bun
bun install -g akm-cli

That's it. You now have the akm binary on your PATH. And when a new version drops, akm upgrade handles it in place.

Initialize Your Stash

akm setup

This creates ~/akm with subdirectories for each asset type: scripts/, skills/, commands/, agents/, knowledge/, and memories/. If you want to put it somewhere else, set AKM_STASH_DIR before you run setup.

But the real power move isn't putting everything in one folder. It's telling akm where your stuff already lives.

Add Your Existing Platform Directories

Here's what most people's machines actually look like. You've got Claude Code skills in one place, OpenCode assets in another, maybe some Cursor rules in a third. Instead of copying files around or choosing a winner, just add them as sources.

akm add ~/.claude/skills
akm add ./my-project/.opencode/skills
akm add ./.cursor/rules

One command per directory. Each akm add registers the path, and the search index picks it up on the next build. No JSON editing, no manual config files. Your files stay exactly where they are — akm just knows about them now.

You can name sources to keep track of what's what:

akm add ~/.claude/skills --name "claude-skills"
akm add ./team-shared --name "team"

And see everything at a glance:

akm list

That shows your primary stash, all the directories you've added, and any managed sources — in priority order. Need to remove one? akm remove takes a path or a name.

For assets that live in a git repo or an npm package, akm add handles installation and makes them searchable immediately:

# A team repo full of shared skills
akm add github:your-org/team-agent-toolkit

# An npm stash
akm add @scope/deploy-skills

# A local git directory
akm add ./path/to/my-opencode-skills

Every akm add registers the stash, caches the assets, and triggers an incremental index build.

Build the Index

akm index

First run builds the full index. After that, it runs incrementally — only rescanning directories that changed. If you've configured an embedding endpoint (local Ollama, OpenAI, whatever), you get vector-based semantic search. If not, you still get solid keyword matching out of the box with the built-in local model.

Want the enhanced experience? If you're running Ollama:

ollama pull nomic-embed-text
akm config set embedding '{"endpoint":"http://localhost:11434/v1/embeddings","model":"nomic-embed-text","dimension":384}'
akm index --full

Search Across Everything

Now here's where it pays off. Say you're working in Claude Code and you vaguely remember writing a skill for Docker container management a few months ago. Was it in your OpenCode stash? Your Claude Code skills? That shared repo your teammate set up?

Doesn't matter.

akm search "docker container management"

That searches across every source you've registered — your primary stash, every directory you added with akm add, and all managed sources. Semantic search means you don't need to remember the exact filename. Describe what you're looking for and akm finds it.

Results come back with a ref you can pass straight to akm show:

akm show skill:docker-homelab

Your agent gets the full SKILL.md content, ready to use. For scripts, it gets a run command it can execute directly. For commands, the full markdown template with placeholders. For knowledge, navigable content with TOC and section views. No manual file hunting.

Want to search the community registries too? akm ships with skills.sh built in:

akm search "code review" --source both

Now you're searching your local stash and community registries in one shot. Found something useful? Install it:

akm add github:someone/great-stash

Or if you just want one asset from a stash without installing the whole thing:

akm clone "github:someone/great-stash//skill:code-review" --dest ./.claude

That clones just the skill directly into your project's Claude Code skills directory. The type subdirectory (skills/, scripts/, etc.) gets appended automatically.

Tell Your Agent About It

Here's the part that ties it all together. Drop this into your AGENTS.md, CLAUDE.md, or system prompt:

## Resources & Capabilities

You have access to a searchable library of scripts, skills, commands, agents,
knowledge, and memories via the `akm` CLI. Use `akm -h` for details.

That's the entire integration. No plugins, no SDKs, no integration code. Any model that can run shell commands can use akm. Claude Code, OpenCode, Codex, Cursor — if it has a terminal, it works.

The agent runs akm search to find what it needs, akm show to load the content, and gets to work. Everything else stays out of context.

What This Looks Like in Practice

Let's say your setup looks something like this:

Claude Code: ~/.claude/skills/ has skills for PDF generation, CMYK conversion, and print layout QA
OpenCode: .opencode/skills/ in a project has custom Azure deployment scripts and a LiteLLM manager
Shared team repo: A git repo with Docker, CI/CD, and code review assets
Cursor: .cursor/rules/ has coding conventions and architecture patterns

After setup:

akm setup
akm add ~/.claude/skills
akm add .opencode/skills
akm add .cursor/rules
akm add github:your-org/team-agent-toolkit
akm index

Now when your agent runs akm search "deploy container to azure", it finds your Azure deployment script from the OpenCode directory, the Docker skill from your team repo, and maybe a relevant knowledge doc from Cursor's rules. All in one search. All ranked by relevance.

The agent picks what it needs, loads only that, and gets to work. Progressive disclosure means your agent's context stays clean — no drowning in irrelevant skills, no missing the one it actually needs.

Why This Matters More Than It Sounds

The fragmentation problem in agent tooling is only getting worse. Every platform is building its own skill format, its own directory conventions, its own discovery mechanism. None of them talk to each other. If you're serious about building agent workflows, you're going to end up with assets in three or four of these systems within the year.

You can either manage that by hand — maintaining parallel copies, forgetting where things are, rebuilding from scratch when you switch tools — or you can index once and search everywhere.

akm isn't trying to replace any of these platforms. Your Claude Code skills stay Claude Code skills. Your OpenCode scripts stay OpenCode scripts. akm just makes them all findable from one place, regardless of which agent is asking.

Get Started

curl -fsSL https://raw.githubusercontent.com/itlackey/akm/main/install.sh | bash
akm setup
akm add ~/.claude/skills
akm index
akm search "whatever you need"

Five commands. Every skill you've ever written, searchable in seconds.

The repo is at github.com/itlackey/akm. If you've got agent assets scattered across platforms, give it a shot and let me know what breaks.

Update (March 2026): This post was updated to reflect akm's current CLI. The unified akm add command replaces the earlier akm stash add, akm setup replaces akm init, and akm list replaces akm stash list. Sources (formerly "stash sources") are now managed through a single akm add / akm remove interface. If you're following along with an older version, akm upgrade will get you current.

Note (2026-04-23): This post has been updated to align with akm 0.6.0 terminology. Earlier wording referred to a kit and the Kit Maker's Guide; those terms have been renamed to stash and Stash Maker's Guide throughout. The pre-rename text is preserved in this repository's git history.

Forem: IT Lackey

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 add

akm list

akm update

akm remove

akm clone

akm save

akm registry

3. Discovery Commands

akm curate

akm search

akm show

4. Local Knowledge and Operational Context

akm remember

akm import

akm wiki

akm vault

5. Procedure Commands

akm workflow

6. Continuous Improvement Commands

akm feedback

akm history

akm events

akm reflect

akm propose

akm proposal

akm distill

7. Operator Ergonomics

akm help

akm hints

akm completions

akm upgrade

8. The Commands People Use Most

A Simple End-to-End Example

Final Takeaway

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

TL;DR

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

Security hardening (PR #275)

Upgrade

Building Agent Knowledge Bases That Actually Scale

Karpathy's LLM Wiki Pattern

The Problem: Knowledge That Accumulates and Gets Lost

How akm's Multi-Wiki Works

Walking Through a Real Workflow

The "akm Surfaces, the Agent Writes" Principle

akm wiki search vs akm search --type wiki

Practical Example: Building a Research Wiki

What This Isn't

Getting Started

Agents That Remember Where They Were

The Problem: Tasks Versus Procedures

Workflow Assets: Stored Procedures Your Agent Can Step Through

Resuming blocked or failed runs

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

Writable Git Stash: Your Skills Sync Like Code

How These Three Features Work Together

Getting Started

akm 0.6.0: Clean Break to Stash, Quieter CLI, Easier Migration

TL;DR

What "clean break" means

Breaking changes at a glance

What's new (low-key)

Migration

What's next

`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 reflect`

`akm propose`

`akm proposal`

`akm distill`

`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

Writable git stash and `akm save`

`--trust` flag for installs

Broader `akm upgrade` coverage

`akm help migrate <version>` — release notes at the CLI