akm docs

Workspace read models and actions

The operations of akm-cli/workspace and the JSON they return, for a trusted local host such as AKM Desktop. Each operation owns its behaviour (policy, revisions, the write lease, redaction) and everything it returns comes from the function the matching CLI command renders, so it never disagrees with the CLI. Transport (authentication, HTTP, status codes) belongs to the host; Desktop's is described in its own documentation, not here.

Experimental (see STABILITY.md). The shapes below are what 0.10 ships; they may change in any release, and nothing outside a host that tracks akm's version should depend on them. Use the CLI's --format json for that.

Conventions

A limit input is a positive integer capped at 200.

activity.meta

The running akm version, the machine's host name and the runtime.

{
  "ok": true,
  "data": {
    "version": "0.10.261005",
    "hostname": "workstation",
    "runtime": "bun"
  }
}

runtime is bun or node. hostname identifies the machine running akm.

activity.overview

Everything an overview needs in one call. Input:

Parameter Default Meaning
metricsSince 30d Metrics window start, as akm doctor metrics --since.
probe off true probes whether each connection's endpoint answers and what each harness's --version prints, and checks for a newer akm release (network). Off by default so loading an overview makes no outbound calls.
{
  "ok": true,
  "data": {
    "health": {
      "schemaVersion": 3,
      "ok": true,
      "status": "pass",
      "since": "2026-10-15T15:41:20.499Z",
      "hardChecks": [{ "name": "state-db-schema", "kind": "deterministic", "status": "pass", "confidence": "high", "message": "...", "evidence": {} }],
      "advisories": [],
      "metrics": { "taskFailRate": 0, "agentFailureRate": 0, "stuckActiveRuns": 0, "llmUsage": {} },
      "improve": {},
      "runs": [],
      "windows": [{ "name": "current", "since": "...", "until": "...", "runs": 1, "improve": {}, "metrics": {} }, { "name": "prior" }],
      "deltas": {}
    },
    "metrics": { "schemaVersion": 1, "window": {}, "usage": {}, "feedback": {}, "utility": {}, "llm": {}, "proposals": {}, "notes": [] },
    "improveRuns": [
      {
        "id": "run-1",
        "startedAt": "2026-10-16T15:42:09.487Z",
        "completedAt": "2026-10-16T15:43:09.487Z",
        "ok": true,
        "durationMs": 60000,
        "strategy": "default",
        "scope": { "mode": "all" },
        "modelCalls": {
          "total": 5,
          "failures": 1,
          "byProcess": { "reflect": { "calls": 3, "failures": 1 }, "triage.judgment": { "calls": 2, "failures": 0 } }
        },
        "usage": [{ "process": "reflect", "engine": "local", "model": "qwen", "calls": 3, "failures": 1, "promptTokens": 900, "completionTokens": 300, "totalTokens": 1200, "usageCalls": 3 }],
        "noCalls": [{ "process": "distill", "reason": "no_signal" }],
        "terminated": null,
        "errors": { "count": 1, "shown": [{ "ref": "memory:a", "mode": "reflect-failed", "error": "..." }] },
        "preRunSync": { "committed": false, "pushed": false, "skipped": true, "reason": "no remote" },
        "sync": { "committed": true, "pushed": false, "skipped": false },
        "triage": { "promoted": 2, "rejected": 1, "deferred": 0, "failed": 0, "skippedByCap": 0 }
      }
    ],
    "taskFailures": [{ "taskId": "weekly-review", "runs": 6, "failed": 2, "medianMs": 4000 }]
  }
}

activity.improveRun

Requires id. Returns the one improve run with that id, however old (the overview lists the latest 10), in the shape of an improveRuns entry above. An unknown id throws NotFoundError (IMPROVE_RUN_NOT_FOUND).

activity.health

The health part of activity.overview on its own, with the same probe parameter. A host calls it with probe set to run all checks.

activity.taskHistory

Requires taskId; optional since (default 30d, same syntax as metrics) and limit (default 50, maximum 200). Returns { available, totalCount, count, runs }, newest first. Each run has recorded status, startedAt, nullable durationMs, nullable trigger (schedule when the OS scheduler started it, manual otherwise; null on a run recorded before akm stored it, or one that failed before it was dispatched), and nullable decoded detail (reason, error, exitCode, runId when recorded). Invalid/missing historical detail stays unknown. No log paths are returned or files read; these are existing state.db records. available: false means state.db is absent or needs migration, not that this task has never failed.

activity.taskRuns

Optional since (default 30d). Every scheduled-task run that started in the window, for all tasks, newest first: { available, window, truncated, runs: [{ taskId, status, startedAt, finishedAt, durationMs, trigger, targetKind, targetRef }] }. trigger is as in taskHistory. At most 20,000 runs; truncated says the window held more. taskHistory has one task's runs with their detail.

activity.workflowRuns

Optional since (default 30d). The workflow runs created in the window, or still active, newest first, as akm workflow list lists them: { available, window, runs: [{ id, workflowRef, title, status, createdAt, updatedAt, completedAt, harness, session }] }. harness and session are the agent that started the run, when it was recorded. Child runs are not listed; they are in their parent's workflowRun. Like the other activity reads it uses the read-only state connection: an absent state.db, or one that needs a migration, is available: false, and nothing is created or migrated.

activity.workflowRun

Requires id. One run as akm workflow status <id> --units reads it: { run, steps, units, children }. run is the run summary without its params. steps are in order (id, title, status, sequenceIndex, completedAt). Each unit has its step, phase (gate for a gate check), status, runtime kind, engine, tokens, start and finish, failure reason, its clipped and redacted diagnostic, and attempts (attempt, phase, status, startedAt, finishedAt, tokens, failureReason). A step has no start time of its own; its units' times give its span. An unknown id, or a state.db that is absent or needs a migration, is a NotFoundError (WORKFLOW_NOT_FOUND); nothing is created or migrated.

activity.events

Optional since (default 24h) and until (default now). Every search, show, feedback and curate row of the window from every source, oldest first, as akm doctor metrics --detail full lists them (rows.usage): { available, window, truncated, events }. A search writes one summary row (no ref, with resultCount) and one row per hit. An event carries agent: { harness, session? } when the agent harness that made it was recorded (from this release; older rows have none). At most 20,000 events; truncated says the window held more.

assets.graph

No input; returns a promise. Every asset of the enabled bundles (no env, secret or session assets) and the declared links between them, in column form, so 30,000 assets stay a few megabytes:

{
  "available": true,
  "note": "…",
  "types": ["knowledge", "memory"],
  "bundles": ["team-wiki"],
  "beliefs": ["superseded"],
  "use": { "since": "2026-08-15T08:00:00.000Z", "source": "user" },
  "kinds": ["xref", "links_to"],
  "tags": ["deploy"],
  "nodes": { "ref": ["team-wiki//knowledge/a"], "type": [0], "bundle": [0], "belief": [-1], "shows": [12],
             "lastShownAt": ["2026-11-02T09:14:03Z"], "modifiedAt": ["2026-03-30T17:02:11.000Z"],
             "positive": [2], "negative": [0], "tags": [[0]] },
  "links": { "from": [0], "to": [3], "kind": [1] },
  "duplicates": { "threshold": 0.96, "a": [0], "b": [9], "cosine": [0.9871], "truncated": false },
  "groups": { "count": 36, "group": [4], "x": [12.5], "y": [-3.1], "z": [40.2] }
}

Node i is index i of every nodes array; type, bundle, belief and kind index types, bundles, beliefs and kinds, and each entry of nodes.tags[i] indexes tags, the asset's own frontmatter tags (lower case, once each). bundles runs from the bundle with the most assets to the one with the fewest. belief is the asset's recorded belief state, -1 when it has none. A link runs from the asset that declares it to its target; links whose target is missing, of a type that is not returned, or in a bundle that is not enabled are left out. shows is counted from the usage events when the operation is called: events of source user (people and their agent sessions, not scheduled tasks or Improve) at or after use.since, the start of the usage retention window. It is zero, and the note says so, when no usage history is available. lastShownAt is the latest of those shows (UTC), null when there is none in the window. positive and negative count feedback from people inside the retention window, as search ranks by it (a negative answered by an accepted fix does not count). modifiedAt is the file's modification time, null when it cannot be read; in a Git checkout it is when the file was last written there, not its last commit.

groups and duplicates are computed by akm index at the end of each build whose vectors changed, over every embedded asset, and stored in index.db; the read only looks them up. The embedded assets are grouped by meaning (spherical k-means on their vectors, from a fixed start, so the same vectors give the same groups), at most 36 groups. groups.group[i] is asset i's group (-1 when it has no vector), and x, y, z its place in 3D: groups alike in meaning lie near each other, and an asset sits inside its group's sphere. duplicates lists pairs of assets (indexes into nodes) whose stored embeddings have a cosine of at least threshold (0.96), most alike first, at most 2,000 (truncated says there were more); only pairs inside a group are compared. Pairs and places of assets that are not returned (a bundle that is not enabled) are left out. Both are null without at least eight embedded assets, and until an akm index of this release has run. available is false, with a note, when there is no index.

bundles.list

One card per configured bundle, plus the index state. Git status is read from the repository as it is: nothing is fetched, so ahead/behind are measured against the remote-tracking branch as the last akm sync left it.

{
  "ok": true,
  "data": {
    "defaultBundle": "stash",
    "defaultWriteTarget": null,
    "workingStash": null,
    "bundles": [
      {
        "name": "stash",
        "kind": "filesystem",
        "default": true,
        "source": { "kind": "path", "locator": "/home/me/akm" },
        "path": "/home/me/akm",
        "writable": true,
        "version": null,
        "exists": true,
        "itemCount": 14,
        "byType": { "fact": 12, "knowledge": 2 },
        "git": {
          "branch": "main",
          "upstream": "origin/main",
          "ahead": 1,
          "behind": 0,
          "dirtyPaths": 0,
          "lastCommit": { "sha": "7591a50789d4cddc", "time": "2026-10-16T10:46:41-05:00", "subject": "akm save 2026-10-16 10:00:00" }
        }
      }
    ],
    "index": {
      "entryCount": 14,
      "byType": { "fact": 12, "knowledge": 2 },
      "lastBuiltAt": "2026-10-16T15:34:00.512Z",
      "hasEmbeddings": false,
      "embeddingCount": 0,
      "embeddingCoverage": 0,
      "semanticSearch": { "mode": "off", "status": "disabled" }
    }
  }
}

assets.bundleFiles

Lists one directory in an enabled registered bundle. bundle selects its resolved content root; path is relative to it (default: root); hidden=1 includes dot-files. Absolute paths and symlink escapes are refused. Internal symbolic links can be traversed; unavailable links are labelled.

The result is {bundle, path, parent, indexAvailable, entries}. parent is null at the root. Each entry has name, bundle-relative path, kind (directory, file, or other), and assets: [{ref, type}], with optional symlink and unavailable. Directories sort first, then names. Internal links retain their displayed path and their target's indexed assets. Assets come only from exact physical-file rows already in the index; absent indexes leave them empty. No content is read, recursive scan run, index written, or source refreshed. Listing does not imply editability.

config.get

The effective configuration, as akm config list shows it, with where each value comes from.

{
  "ok": true,
  "data": {
    "path": "/home/me/.config/akm/config.json",
    "exists": true,
    "config": {
      "semanticSearchMode": "off",
      "connections": { "default": { "endpoint": "https://llm.example.test/v1?token=%5Bredacted%5D", "models": { "fast": "chat-model" } } },
      "harnesses": { "claude": {} },
      "defaultBundle": "stash"
    },
    "automaticWriteTarget": { "name": "stash", "path": "/home/me/akm", "workingStash": false },
    "projectWarnings": [],
    "entries": [
      { "path": "semanticSearchMode", "value": "off", "source": "file" },
      { "path": "output.format", "value": "json", "source": "default" }
    ],
    "connections": [{ "name": "default", "endpoint": "https://llm.example.test/v1?token=%5Bredacted%5D", "models": { "fast": "chat-model" } }],
    "harnesses": [{ "name": "claude" }],
    "env": [{ "name": "AKM_BUNDLE_DIR", "value": "/home/me/akm" }]
  }
}

proposals.list

The proposal queue, as akm proposal list reads it. Input: status=pending (default) or recent, limit (default 100). Optional source and age (underDay, underWeek, older, unknown) filter before applying the limit. Age is less than one day, one to seven days, seven days or more, or an invalid/future date. It uses the most recent reopen timestamp when present. totalCount is the filtered count; fullCount and bySource describe the full selected status queue. backlog groups that full queue by source and these four age bands, before any list cap. It is a current snapshot, not a time-series of historical queue size.

{
  "ok": true,
  "data": {
    "status": "pending",
    "totalCount": 3,
    "fullCount": 3,
    "bySource": { "consolidate-pair": 2, "reflect": 1 },
    "backlog": [{ "source": "consolidate-pair", "underDay": 2, "underWeek": 0, "older": 0, "unknown": 0 }, { "source": "reflect", "underDay": 0, "underWeek": 1, "older": 0, "unknown": 0 }],
    "proposals": [
      {
        "id": "d6bb7f94-69aa-48cf-9084-5dba2fa1afb3",
        "source": "consolidate-pair",
        "ref": "stash//knowledge/old-note",
        "status": "pending",
        "createdAt": "2026-10-16T15:46:41.896Z",
        "updatedAt": "2026-10-16T15:46:41.896Z",
        "waitingSince": "2026-10-16T15:46:41.896Z",
        "confidence": null,
        "gateDecision": { "outcome": "deferred", "reason": "judgment-deferred", "decidedAt": "..." },
        "review": null,
        "isRetire": true,
        "retirement": {
          "retiredRef": "stash//knowledge/old-note",
          "successorRef": "stash//knowledge/new-note",
          "reason": "duplicate",
          "judgeLabel": "duplicate",
          "judgeReason": "Same procedure, newer wording.",
          "cosine": 0.93,
          "onlyInRetired": [],
          "onlyInSuccessor": ["Adds the rollback step."],
          "continuityRisk": null
        }
      }
    ]
  }
}

Two further filters drill down from a chart: week=YYYY-MM-DD (a Monday) keeps proposals whose current decision was made that ISO week (UTC), and class=judge|you|unknown|rejected|reverted keeps one outcome class. They combine with source and age.

proposals.get

One proposal, as akm proposal show plus akm proposal diff. :id is a proposal id, or an unambiguous prefix of a pending one, or an asset ref. Unknown: PROPOSAL_NOT_FOUND.

{
  "ok": true,
  "data": {
    "proposal": {
      "id": "d6bb7f94-69aa-48cf-9084-5dba2fa1afb3",
      "source": "reflect",
      "ref": "stash//lessons/rg",
      "status": "pending",
      "createdAt": "2026-10-16T15:46:41.896Z",
      "updatedAt": "2026-10-16T15:46:41.896Z",
      "waitingSince": "2026-10-16T15:46:41.896Z",
      "confidence": null,
      "gateDecision": null,
      "review": null,
      "isRetire": false,
      "retirement": null,
      "sourceRun": "run-1",
      "proposedTarget": { "source": "stash", "root": "/home/me/akm" },
      "payload": { "frontmatter": { "description": "Use ripgrep" } },
      "changes": [{ "op": "create", "path": "lessons/rg.md" }]
    },
    "validation": {
      "ok": true,
      "findings": [{ "kind": "invalid-description", "message": "...", "severity": "warn" }]
    },
    "diff": {
      "unified": "--- /dev/null\n+++ stash//lessons/rg (proposed, new asset)\n@@ 0,0 1,9 @@\n+---\n...",
      "isNew": true,
      "targetPath": "/home/me/akm/lessons/rg.md",
      "before": null,
      "after": "---\ndescription: Use ripgrep\n---\n\nPrefer rg over grep.\n",
      "truncated": false,
      "redacted": false
    },
    "diffError": null
  }
}

Deciding proposals

Six operations decide proposals. Each calls the function the CLI command calls (akmProposalAccept, akmProposalReject, akmProposalAcceptMany, akmProposalRevert, akmProposalReopen) with the arguments the CLI passes, so a decision made here is recorded exactly like akm proposal accept / reject: the same state.db rows and events, the same asset write and the same git commit.

Failures keep the usual code:

Kind code When
usage MISSING_REQUIRED_ARGUMENT, INVALID_FLAG_VALUE, INVALID_PROPOSAL, ... Bad input: no or empty reason, an ids list outside 1 to 200, a proposal that fails validation.
not found PROPOSAL_NOT_FOUND No proposal has that id (or an ambiguous or unknown prefix).
conflict PROPOSAL_STALE The asset changed (or was created) after the proposal was made, so accepting would overwrite newer content. Nothing is written.
conflict PROPOSAL_NOT_PENDING The proposal was already accepted, rejected or reverted.
conflict ASSET_MUTATION_LEASE_HELD Another akm process (an improve run, the CLI) or caller holds the write lease. Retry in a moment; the operation waits only a few seconds.
conflict other config codes A config refusal the user can address.
transient other transient codes Other contention; retry.

proposals.accept

Accept one pending proposal. :id is a proposal id or unambiguous prefix. The input is {id}.

{
  "ok": true,
  "data": {
    "schemaVersion": 1,
    "ok": true,
    "id": "d6bb7f94-69aa-48cf-9084-5dba2fa1afb3",
    "ref": "stash//lessons/rg",
    "assetPath": "/home/me/akm/lessons/rg.md",
    "proposal": { "id": "d6bb7f94-...", "status": "accepted", "ref": "stash//lessons/rg", "...": "summary fields as in proposals.list" },
    "commit": { "sha": "9f1c...", "time": "2026-10-16T16:02:11-05:00", "subject": "akm accept: reflect d6bb7f94 stash//lessons/rg", "repo": "/home/me/akm" }
  }
}

proposals.reject

Reject one pending proposal. The input is {id, reason}: required, a string, trimmed, 1 to 2000 characters, else MISSING_REQUIRED_ARGUMENT (or INVALID_FLAG_VALUE when too long). The asset and the repository are untouched.

{
  "ok": true,
  "data": {
    "schemaVersion": 1,
    "ok": true,
    "id": "d6bb7f94-69aa-48cf-9084-5dba2fa1afb3",
    "ref": "stash//lessons/rg",
    "reason": "Duplicates lessons/ripgrep.",
    "proposal": { "id": "d6bb7f94-...", "status": "rejected", "review": { "outcome": "rejected", "reason": "Duplicates lessons/ripgrep." } }
  }
}

A rejection can be undone with akm proposal reopen, and an accepted change with akm proposal revert; both are operations below.

proposals.acceptMany

Accept several pending proposals and commit them once (akmProposalAcceptMany, the call behind akm proposal accept <id> <id> ...). The input is {ids: ["<id>", ...]}: 1 to 200 non-empty strings; repeats are dropped. An id that fails is reported and the rest carry on; what was accepted is committed either way.

{
  "ok": true,
  "data": {
    "accepted": 3,
    "failed": 1,
    "results": [
      { "schemaVersion": 1, "ok": true, "id": "...", "ref": "stash//lessons/a", "assetPath": "/home/me/akm/lessons/a.md", "proposal": { "status": "accepted" } },
      { "schemaVersion": 1, "ok": false, "id": "...", "error": "Proposal target changed after proposal ... was created; refusing to overwrite newer content.", "code": "PROPOSAL_STALE" }
    ],
    "commit": { "sha": "...", "time": "...", "subject": "akm proposal accept: 3 accepted (reflect 3)", "repo": "/home/me/akm" }
  }
}

proposals.rejectMany

Reject several pending proposals with one shared reason ({ids: ["<id>", ...], reason}, the same limits as a single rejection and 1 to 200 ids). Each id is decided on its own through akmProposalReject, so a failure is reported and the rest are still rejected. There is no undo for the batch; each rejected proposal can be reopened on its own.

{ "ok": true, "data": { "rejected": 2, "failed": 1, "results": [
  { "ok": true, "id": "...", "ref": "stash//lessons/a", "proposal": { "status": "rejected" } },
  { "ok": false, "id": "missing-id", "error": "Proposal \"missing-id\" not found", "code": "PROPOSAL_NOT_FOUND" }
] } }

proposals.revert

Undo an accepted change (akmProposalRevert, the call behind akm proposal revert): the target is restored from the backup taken at accept, the proposal becomes reverted, and a target edited since acceptance is never overwritten. The body is empty. A proposal that created a new asset has no backup and is refused. The summary carries revertable (true for an accepted proposal that kept a backup) so a host can offer Undo only where it works.

proposals.reopen

Return a rejected proposal to the pending queue (akmProposalReopen, the call behind akm proposal reopen). The input is {id}. A proposal that is not rejected, or whose target changed since, is refused.

The proposal summary gains two fields: revertable (above) and decider ("triage" for the judge, "human" for a person, null for a decision recorded before decidedBy existed).

proposals.recentChanges

Recent commits of the write-target stash (defaultWriteTarget, else the default bundle), from its git log. Input: limit (default 50).

{
  "ok": true,
  "data": {
    "bundle": "stash",
    "path": "/home/me/akm",
    "git": true,
    "commits": [
      {
        "sha": "7591a50789d4cddc89ab53ef9bdb2dfc9863444",
        "shortSha": "7591a507",
        "time": "2026-10-16T10:46:41-05:00",
        "author": "akm-test",
        "subject": "akm save 2026-10-16 10:00:00",
        "origin": "sync",
        "paths": ["knowledge/more.md"],
        "pathCount": 1
      }
    ]
  }
}

assets.search

akm search, with the same results for the same inputs. Input:

Parameter Meaning
q The query. Empty lists everything, as akm search with no query does; a trailing-slash prefix (memories/projecta/) enumerates a subtree.
type Asset type filter (knowledge, skill, memory, ...), exact match.
bundle Narrow to one configured bundle (akm search --from <name>). Unknown names are a usage error.
belief current (default), all, or historical, forwarded to the existing search policy.
scope_user, scope_agent, scope_run, scope_channel Existing exact scope filters; blank values are omitted.
limit Maximum hits. Default 20.

data is the search function's own response (what akm search --format json shapes down for the terminal), unshaped:

{
  "ok": true,
  "data": {
    "schemaVersion": 1,
    "bundleDir": "/home/me/akm",
    "source": "local",
    "hits": [
      {
        "type": "knowledge",
        "name": "deploy",
        "path": "/home/me/akm/knowledge/deploy.md",
        "ref": "knowledge/deploy",
        "origin": "stash",
        "editable": true,
        "description": "Deploy guide",
        "tags": ["deploy"],
        "size": "small",
        "action": "akm show knowledge/deploy -> read reference material",
        "score": 0.016393,
        "whyMatched": ["lexical rank 1"],
        "estimatedTokens": 24,
        "quality": "generated"
      }
    ],
    "searchMode": "keyword",
    "tip": "...",
    "warnings": ["..."],
    "timing": { "totalMs": 4, "rankMs": 1, "embedMs": 1 }
  }
}

tip and warnings appear when there is something to say (an empty index, a stale one). Pass a hit's ref to assets.show. Registry results are never included, and no search is counted as demand.

assets.show

akm show, plus feedback. Input: ref (required), [bundle//]conceptId[#fragment] as akm show takes it.

{
  "ok": true,
  "data": {
    "redacted": false,
    "durableRef": "stash//knowledge/guide",
    "asset": {
      "type": "knowledge",
      "name": "guide",
      "path": "/home/me/akm/knowledge/guide.md",
      "ref": "knowledge/guide",
      "origin": "stash",
      "editable": true,
      "action": "Reference material - read the content below. ...",
      "content": "---\ndescription: Deploy guide\n---\n# Deploy guide\n...",
      "links": { "outgoing": { "xref": { "total": 1, "refs": ["knowledge/notes"] } } }
    },
    "feedback": {
      "counts": { "positive": 1, "negative": 1 },
      "history": [
        { "at": "2026-10-16T15:46:41.000Z", "signal": "negative", "source": "user" },
        { "at": "2026-10-16T15:46:41.000Z", "signal": "positive", "source": "user", "reason": "clear", "tags": ["code:x"] }
      ]
    }
  }
}

The response also supplies location ({bundle, path, parent} relative to the resolved bundle root, or null), feedbackRequireReason, the owning bundle, headings with existing AKM fragment selectors, and a links map for supported relative inline Markdown links. A relative .md target must already be indexed in the same bundle. Missing/out-of-bundle paths remain text; no arbitrary-file read is added. Explicit cross-bundle refs remain available. Relative images, uploads, universal title/alias resolution and unsupported Markdown extensions are not provided. A host renders basic tables and disabled task-list checkboxes; raw HTML is always escaped.

documents.readSource

Input: ref (required, without a fragment). Returns {ref, type, content, revision} for an indexed, enabled, writable AKM knowledge or memory file. content is the full live UTF-8 source, including frontmatter; revision is its SHA-256 over raw source bytes, independent of the indexed hash. The same authorized indexed-file resolution used by show applies. Unsupported adapters, read-only targets, stale target identities and invalid UTF-8 are refused, with the errors of workspace actions: a read-only bundle is a conflict, not an internal error. Source editing is also refused when URL redaction would change its contents, so saving never replaces hidden credentials with their displayed redactions. This operation does not prepare a Git boundary, fetch or write anything.

assets.related

Input: ref (required), scope (all, the default, or bundle for the asset's own bundle). The assets whose stored embeddings are nearest to this asset's, best first: {available, note, matches: [{ref, title, type, cosine}]}, at most 20. Only stored vectors are read: no query is embedded and nothing leaves the machine. available is false, with a note, when there is no index, the asset has no stored embedding, or its embedding belongs to an older model than the index's current one (re-index first). Matches follow search's entry filter (enabled bundles, no proposed-quality entries) and never include the asset itself or env, secret and session assets. A redacted asset has no related content.

assets.history

Input: ref (required), limit (default 30, maximum 200), optional revision chosen from the returned commit IDs. Returns {available, commits, diff?} using the same Git summary shape as proposals.recentChanges, scoped to this file. diff contains before, after, unified, truncated; sides/patches are capped at the existing 512 × 1024 character diff limit. History is unavailable for non-Git bundles and protected env/secret assets. Unknown Git expressions or commit IDs outside the returned file history are refused. No fetch, restore, rename tracking or additional version store exists.

assets.improvement

What improve proposed for one asset and how the asset has been used since. ref (<bundle>//<type>/<name>) is required.

activity.improveImpact

What improve proposed and changed, week by week. since 90d (default) or 365d (one year). Each store read (proposals, reopened, library, usage, cost) stands on its own: one that fails reads as empty and is named under errors, and the rest is still returned. When the state database is unavailable the response is { "available": false }.

A proposal that was later reverted is dated by its accept (acceptedAt) in outcomes, reviewFlow, changedAssets and summary.kept, and keeps the decider of its accept in judgeAndYou. The revert itself is the reverted entry of harm.

activity.pulse

The last seven days against the eight weeks before them, the four-week improve line, and what needs attention.

activity.retrievalTrend

The per-day user search series (since, 90d by default): days inside the data's coverage are filled with zeros, and the first and last day are marked partial. Each day has searches, zeroResults, and medianMs. The median uses only recorded nonnegative durations; no samples means null, not zero. Missing result counts do not mean zero results. The queries behind zeroResults are listed by assets.searchMisses.

weekly is the same data by ISO week as a p-chart: per week week, x (found nothing), n (searches), rate, and the control limits lower and upper (centre ± 3 standard errors at that week's own n); signal is true for a week outside its limits. A week with no searches has null for all three. centre is the pooled share.

assets.searchMisses

User searches that found nothing, grouped by normalised query: query, count, days (distinct UTC days), lastAt and repeated (true when it came up on two or more days). since is 30d by default. The response also carries searches (all user searches in the window) and foundNothing.

setup.detect

What first-run setup could use on this computer, read from the file system and PATH only: nothing is contacted and nothing is written. It returns stashDir, the library directory the config already names, else ~/akm or another existing candidate, else the default (AKM_BUNDLE_DIR, else ~/akm, or Documents\akm on Windows); harnesses, the agent programs found on PATH that akm can run work on, each {platform, path, modelWorkNote} (akm's words for whether its model calls on that program can be limited to reading and searching); enabled, the platforms the config already enables; modelCalls, where akm's own model calls (improve, judging, extraction) run: description in the words of akm setup's summary, and platform when they run on a harness (else null); connection, the name of the connection that takes them when no agent does (null when there is none); and learning, background learning: on is the host-wide switch alone (improve.enabled is not false, or the all-seven-processes-off that earlier Desktop versions wrote), whether or not anything is set up to run; harness, the platform improve runs on (null for a connection, or nowhere); and scheduled, whether the improve task is enabled.

{
  "ok": true,
  "data": {
    "stashDir": "/home/ada/akm",
    "harnesses": [{ "platform": "claude", "path": "/home/ada/.local/bin/claude" }],
    "modelCalls": { "platform": null, "description": "off: no connection or harness is configured" },
    "connection": null,
    "learning": { "on": false, "harness": null, "scheduled": false }
  }
}

Workspace actions

The other writing operations. Each takes the input shown, applies the operation named, and keeps the guards of the CLI command it mirrors. A host should ask for confirmation before bundles.remove and documents.retire, and never retry a failed write automatically.

Operation Input and existing behaviour
feedback.record {ref, signal: "positive"|"negative", reason?, tags?: string[], fix?: [{replace, with}]} → akm feedback. The ref is resolved as the CLI resolves it; tags follow existing key:value validation. Negative feedback requires a reason when feedback.requireReason is enabled. Submissions are recorded with source user unless AKM_EVENT_SOURCE is already set (for example under an improve or task run), which wins as it does for every akm child; they retain existing ranking/utility/event effects. Feedback does not save config, so it works under a config that still holds a literal API key.
setup.apply {dir?, harness?: string[], connection?: {endpoint, model, apiKeyEnv?}, learning?: {on, harness?}}. With harness: akm setup --yes --no-probe [--dir=<dir>] --harness=<list>, which enables the named agent programs (the first becomes the default harness) and creates the library when there is none. Without it: akm bundle create --dir=<dir> (dir defaults to the configured library, else the default location). akm setup --yes alone would enable every agent program it finds, which a host asks for per program. dir must be absolute. connection writes the default connection (checked as akm setup --endpoint --api-key-env checks it: a base URL and the NAME of a variable, never a key). learning: {on: false} writes improve.enabled: false and nothing else (no placement, no task change). {on: true} removes it (and an earlier Desktop's all-seven-off), sets improve.harness to the enabled harness's entry, or else improve.connection to the default connection unless it already names one, and ensures the improve task exists and is enabled, adding it from akm's core/improve template when the library has none. A learning that cannot be honoured (a harness that is not enabled, or no connection for akm itself) is written off, with a warning. Offline: nothing is probed, downloaded or indexed. Returns setup.detect as it reads afterwards. Other fields are ignored with one warning.
tasks.list {} → {tasks: [{id, schedule, enabled, description?}]}: the default bundle's tasks that have a schedule, and whether this host has each enabled (scheduler.enabled). Reads only.
tasks.enable {task} → akm task enable --bundle=<default bundle> -- <task>: schedules the task in this host's scheduler and syncs the OS scheduler (cron, launchd or Task Scheduler). Returns {ref, enabled, changed, sync}. An unknown task is not-found.
tasks.disable {task} → akm task disable --bundle=<default bundle> -- <task>: the reverse.
backups.prune {olderThan?, dryRun?: true, confirm?: true} → akm backups prune [--dry-run | --yes] [--older-than=<duration>]. Removes entries under the data directory's backups/ older than olderThan (default 30d) and keeps the newest entry of each folder. A dry run reports {dryRun, olderThan, cutoff, count, bytes, folders: [{folder, count, bytes, kept}]} and removes nothing; a real run returns the same and needs confirm: true.
bundles.add {source, name?, writable?} → akm bundle add, including source validation. Existing provider restrictions apply; no insecure-transport bypass is exposed.
bundles.update {bundle} → akm bundle update -- <bundle>. Fetches/reindexes only on explicit submission. A rare update requiring destructive confirmation remains refused; --yes is never passed silently.
bundles.rename {bundle, name, dryRun?: true} → akm bundle rename [--dry-run] -- <bundle> <name>. The result is the CLI's rename plan (applied is false for a dry run).
bundles.remove {bundle, confirm: true} → akm bundle remove --yes -- <bundle>. Managed installs may be deleted; local filesystem source files remain on disk.
bundles.setSettings {bundle?, enabled?, writable?, componentWritability?: {existingComponent: boolean}} → existing schema-walking config setters inside mutateConfig. Only changed controls are submitted. Existing validation rejects disabled targets and writable npm/website sources. The default bundle and write target are edited through config.change.
config.change {set?: {key: string}, unset?: string[]} → akm config set / unset on each key, in one validated, atomic write. Values are strings, as on the command line, and are coerced and checked against the schema; literal API keys and configVersion are refused. An unset is refused with TARGET_NOT_UPDATABLE when the key is inherited from an extends base or sits inside a connection or harness entry akm ignores, and an unset with no config file writes nothing (saved: false), all as akm config unset does.
config.changeProjects {set?: {name: project}, unset?: string[]} → adds, replaces and removes projects entries in one validated, atomic write; a rename sets the new name and unsets the old. Each set value is a whole project (paths, from, filters, prefer, write), written exactly as sent (the reader takes a project whole by name, so an inherited project's unchanged fields are written too, and a malformed local entry is replaced), and checked by akm's config schema. none, __proto__, constructor, prototype and empty names are refused. An unset (so a rename) of a project config.json does not hold, inherited or ignored by akm, is refused with TARGET_NOT_UPDATABLE. A set is a no-op (saved: false, nothing written or backed up) only when config.json already holds exactly that entry; one with parts akm ignores is rewritten. Names are not dotted keys, so they may contain a dot, which config.change cannot address. Unrelated config and credential references are kept, as for config.change.
documents.createKnowledge {bundle, name, path?, content} → akm import - with Markdown on stdin. Uses the existing writable AKM target, name/path validation, frontmatter preservation, index/Git effects, and no --force. Existing files are never overwritten. Fails fast with ASSET_MUTATION_LEASE_HELD while another writer holds the asset-mutation lease.
documents.save {ref, revision, content} → the existing shared Markdown writer with force and the expected raw-content hash. Only indexed writable AKM knowledge/memory documents accepted by documents.readSource can be edited. The writer takes the asset-mutation lease and compares the live source with revision inside it, immediately before writing. While another writer holds the lease the save fails fast with ASSET_MUTATION_LEASE_HELD instead of waiting. A stale revision raises ASSET_CONTENT_CHANGED without writing; a source deleted after it was loaded is refused (ASSET_NOT_FOUND) rather than recreated. An identical save returns unchanged: true without rewriting, reindexing or recording an event. Changed saves retain normal writer validation, indexing and Git effects.
documents.retire {ref, revision} → retires an indexed writable AKM asset the way akm feedback's typed fix applies a change: it mints a retire proposal (source propose, no judged pair) and accepts it at once, so the asset follows the ordinary proposal-retire lifecycle. Skill packages, env/secret files and sessions are excluded; memory retirement carries its derived twin. The current raw SHA-256 revision is required, and the accept is refused if the bytes changed since.

The documents.retire receipt is {proposalId, ref, bundle, archiveDirs, warnings}. Undo is proposals.revert with that id: the archive moves back without overwriting an occupied path and its tombstone is removed. Like any accepted retirement, the archived bytes are purged after the grace period at the next akm improve (git-backed bundles only), and the row is listed in Review and Activity. If the accept is refused, the proposal is rejected and the operation fails. Task definitions do not change installed schedules until explicit akm doctor scheduler sync.

Configuration-affecting actions do not round-trip the redacted configuration. Existing mutation helpers retain unknown/unrelated fields, local overrides and supported $VAR/${ref} credential references. If the existing config sanitizer would remove unrelated legacy literal credentials, a bundle add or remove, or a settings change that would write config, is refused with INVALID_FLAG_VALUE and the user is asked to correct those settings through the CLI first. A settings request that changes nothing writes nothing and is not refused. It never writes "[redacted]" back as a credential. Bundle update writes only the lockfile, and feedback, knowledge creation and document editing do not save config, so none of them use that config-sanitizer check. Unsetting an inherited defaultBundle or defaultWriteTarget through config.change is refused with TARGET_NOT_UPDATABLE, as akm config unset refuses it.

The shared Markdown writer participates in the existing mutation lease, including CLI import/remember callers; omitting the optional expected hash retains their normal write/force behavior. This serializes cooperating AKM writers; an external editor does not acquire AKM's lease. There is no lock held while a user edits a draft. Untouched source preserves exact bytes, including leading newlines and mixed line endings. Actual edits preserve uniform CRLF line endings.

The operations that run an akm child process report its failure with the code in the child's JSON error; the kind follows its exit code: 2 usage, 1 not found, 78 config conflict, 75 other transient contention, and 70, a killed or unstartable child, or any other error akm does not classify is an internal error. A child that exits zero without a valid expected JSON result rejects with INVALID_COMMAND_RESPONSE. Its side effects may already have happened; reload before retrying, and never retry automatically. Historical restore and media ingestion remain separate work.