akm-cli/docs/architecture/akm-core-principles.md

akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cur

# akm Core Principles

akm is a portable capability library for AI agents — give every coding agent
the capabilities your team has already built. It indexes existing agent
assets in place, loads only what a task needs, packages capabilities into
shareable bundles, improves the library through reviewable proposals, and
runs durable workflows, locally and without tying the library to one
assistant.

This document lists the design constraints that keep that library
predictable.

## What akm Does

An agent has a task. Across configured sources (local filesystem paths and
cache-backed git/website/npm mirrors) and registry catalogs, akm helps it
discover assets such as scripts, skills, commands, agents, knowledge docs,
workflows, env files, secrets, and wiki pages.

Core flow:

```text
connect -> index -> curate -> show -> use/run -> feedback -> proposal
```

Not every task uses every stage.

## Principles

### 1. Capabilities remain portable files

Capabilities are ordinary files on disk — skills, scripts, workflows, agent
definitions, instructions, memories, knowledge docs. akm indexes what's
already there; the source files remain the source of truth, and akm's index
is a derived, rebuildable view rather than a copy of record.

### 2. Materialize sources locally and use one retrieval layer

Local filesystem paths and cache-backed git/website/npm mirrors all
materialize into one local index, so `search`, `curate`, and `show` work the
same way regardless of where a capability originated. Registries stay a
conceptually separate, read-only catalog of installable bundles: registry
results live in `registryHits`, never merged into source `hits`.

### 3. Every token must earn its place

Default output should stay lean. Search and curate are for choosing; show is
for using.

- **Search is a menu.** Default search output should expose only enough to
  choose the next asset. In the current CLI that usually means:
  - `brief`: `type`, `name`, `ref`, `action`, `estimatedTokens`, `keys` —
    `ref` is deliberately present at the leanest level so an agent can run
    `akm show <ref>` without asking for fuller detail
  - `normal`: adds `description` and `score`

  Richer provenance/debug fields belong behind fuller detail modes.

- **Show is a dispatch envelope.** Show should return the payload that lets
  the consumer act:
  - script execution hints
  - skill instructions
  - command templates
  - agent prompts
  - knowledge/wiki content
  - workflow steps and parameters
  - env key names without secret values
  - secret metadata without the secret value

### 4. Discovery chooses; show delivers

Search and curate should not accumulate show-level detail. `full` detail
modes can expose more metadata, but the base mental model stays:

```text
search/curate decide
show delivers
filesystem is optional depth
```

### 5. Refs are opaque durable handles

Consumers should treat refs as opaque lookup handles. The current wire
format is `[bundle//]conceptId[#fragment]`, but agents should pass refs
through rather than parse them. See `docs/architecture/specs/ref.md`.

### 6. Execution requires an explicit supported surface

akm retrieves every supported capability type. It directly orchestrates
defined execution surfaces such as workflows, agent dispatch, tasks, and
guarded subprocess injection. It does not blindly execute arbitrary indexed
content merely because that content appears in search results.

### 7. Improvement is evidence-driven and reviewable

Feedback and usage signal drive `akm improve`, which produces reviewable,
diffable proposals rather than silent rewrites. Accept, reject, and revert
stay human- or policy-gated, and proposals target only writable bundles.

### 8. Writes are destination-aware and fail closed

Writes target only writable bundles/adapters. Read-only adapters and
protected env/secret values are never silently written through — a write
aimed at a non-writable destination fails rather than falling back to an
unintended target.

### 9. Output serves agents first

The default consumer is structured-output automation. JSON-first and
concise detail levels are the right defaults.

### 10. Complexity belongs behind indexing and source management

The hard parts should stay inside indexing, source resolution, registry
install, and provider plumbing, not in the hot path from `search`/`curate`
to `show`/`use`.

## What akm Does Not Do

- blindly execute arbitrary indexed content just because it appears in
  search results — akm orchestrates only defined execution surfaces
  (workflows, agent dispatch, tasks, guarded subprocess injection)
- expose secret/env values through `show`
- replace live-service integrations such as MCP — akm complements MCP and
  assistant-native skills rather than replacing them
- require agents to understand source layouts or provider internals