akm-cli 0.9.29 → 0.9.31

package/docs/reference/env-and-secrets.md

@@ -0,0 +1,126 @@
+# Environment & Secrets
+
+Reference for `akm env` and `akm secret` — the two protected-value asset
+types. For task-oriented guidance on capturing knowledge in general, see
+[Capture Knowledge](../guides/capture-knowledge.md); this page states exact
+contract, defaults, and security behavior.
+
+## env vs secret
+
+`akm env` manages a `.env`-backed group of configuration (a whole `.env` file
+loaded wholesale). `akm secret` manages a single standalone sensitive value —
+one value per file, mirroring Docker's secret model. There is no `akm vault`
+command; use `env` or `secret`.
+
+| | `env` | `secret` |
+| --- | --- | --- |
+| Purpose | configuration — related settings for an app/service | authentication — one sensitive value |
+| Holds | a `.env` file of many `KEY=value` pairs | one value per file |
+| Discoverable | key *names* (not values) | name only (the whole file is the value) |
+| Injects | many vars at once (`env run`) | one var (`secret run <ref> <VAR>`) |
+
+## Core security guarantee
+
+Values never appear in akm's structured output. `env list` and `akm show
+env/<name>` surface key names only — comment text is never surfaced either,
+since comments routinely contain commented-out credentials and are treated
+like values. `secret list` surfaces the secret's name only; the file content
+is never shown. Values reach a process only through the safe injection
+paths, `akm env run` and `akm secret run`, which pass values directly into
+the child process — never through akm's own stdout, the index, or `akm
+show`.
+
+```sh
+akm env create prod                       # create an empty .env group
+akm env create prod --from-file ./.env    # or ingest an existing .env
+
+# akm does not manage individual keys — edit the whole file with your own editor:
+$EDITOR "$(akm env path env/prod --quiet)"
+
+akm env list
+akm show env/prod                         # key names only
+
+# Inject the whole .env into a subprocess (never onto stdout):
+akm env run env/prod -- ./deploy.sh
+akm env run env/prod -- $SHELL            # interactive session with the env loaded
+akm env run env/prod --only DATABASE_URL -- ./migrate
+
+# Store a single credential as a secret:
+printf '%s' "$TOKEN" | akm secret set secrets/deploy-token
+akm secret run secrets/deploy-token GITHUB_TOKEN -- gh release create v1.0.0
+
+# Write into a specific source instead of the working bundle:
+akm secret set secrets/deploy-token --target team --from-file ./token
+```
+
+`env export --out <file>` writes a safe, sourceable `export KEY='value'`
+script (re-serialised single-quoted, so shell substitutions in the source
+`.env` become literal strings) — it requires `--out` and never prints values
+to stdout.
+
+## File modes and storage
+
+`.env` files are stored at mode 0600 under `env/` in the target bundle;
+standalone secrets are stored at mode 0600 under `secrets/`. A secret write
+is atomic under an exclusive per-secret lock held in akm's data directory;
+maximum secret size is 5 MB.
+Values never cross argv (no `/proc/cmdline` exposure). An `env` file or
+secret can carry a sibling `.sensitive` marker that excludes it from `list`
+output and from the search index entirely; the value remains usable via
+`run`.
+
+## Write-target resolution
+
+Env/secret **mutations** (`env create`, `env remove`, `secret set`) choose
+their write destination like every other write command: an explicit
+`--target <source>` wins, else `defaultWriteTarget`, else the working
+bundle. The chosen source must be writable — a non-writable target fails
+with a `ConfigError` before anything is written — and a git-backed writable
+target commits the mutation at a single operation boundary. Reads (`list`,
+`show`, `path`, `run`, `export`) still span all configured sources.
+
+## Subprocess residency
+
+`akm env run` and `akm secret run` inject values directly into the child
+process — never through a shell — but the child controls its own
+stdout/stderr, so a command that prints its own environment will still leak
+values into your terminal or agent transcript. Injected values live in the
+child process environment for its entire lifetime and are visible to every
+subprocess the child spawns.
+
+- Prefer `akm secret run secrets/<name> <VAR> -- <command>` over `akm env
+  run` when a command only needs one value.
+- Avoid `env run` / `secret run` for long-lived daemon or server processes;
+  for those, point the process at the secret file directly
+  (`<bundle>/secrets/<name>`) so the value never sits in a process
+  environment variable at all.
+- Avoid running commands that print the environment (`env`, `printenv`,
+  shell tracing, verbose diagnostics) in agent contexts unless you
+  explicitly intend to expose the child environment.
+- Before spawning, injected key names are scanned for known
+  process-hijacking variables (`LD_PRELOAD`, `PATH`, `GIT_CONFIG_*`, ...): a
+  first-party bundle warns and proceeds, a third-party-sourced bundle is
+  refused.
+
+## Stability
+
+`env list`, `env path`, `env export`, `env run`, `secret list`, and `secret
+run` — the read-and-inject surface — are Stable. `env create`, `env remove`,
+and `secret set` — the write verbs — are Experimental. Check
+[STABILITY.md](../../STABILITY.md) for the current tier of any command
+before depending on its exact output shape.
+
+## What this page does not cover
+
+This page documents akm's own guarantees for these two asset types, not the
+broader threat model (what a compromised bundle or malicious script could
+still do, what filesystem-level exposure remains, how this compares to a
+dedicated secrets manager). See [SECURITY.md](../../SECURITY.md) for that
+fuller picture, including plaintext-at-rest scope and rotation guidance.
+
+## See also
+
+- [Capture Knowledge](../guides/capture-knowledge.md) — `remember`, `import`,
+  and when to reach for each
+- [CLI Reference](cli.md) — full flag documentation for `env` and `secret`
+- [SECURITY.md](../../SECURITY.md) — full threat model

package/docs/reference/memory.md

@@ -0,0 +1,124 @@
+# Memory
+
+Reference for the `memory` asset type: capture, belief states, and derived
+memories.
+
+## Contract
+
+Memories are context fragments — observations, decisions, snippets —
+captured as markdown files. Capture one directly in your working bundle with
+`akm remember "..."`, or point akm at any directory of memory files written
+by another tool:
+
+```sh
+# File-based memory store from another tool
+akm bundle add ~/my-agent/memories
+```
+
+Memory assets appear in search results with the `memory` type, giving agents
+access to recalled context from previous sessions.
+
+## Schema
+
+Memories captured with `akm remember` can carry optional YAML frontmatter
+that the indexer records:
+
+| Field | Purpose |
+| --- | --- |
+| `tags` | Free-form categorization |
+| `source` | Where the memory came from (also used as the derived-memory parent backref — see below) |
+| `observed_at` | When the observation happened |
+| `expires` | When the memory should stop being considered current |
+| `subjective` | Marks the memory as opinion/preference rather than fact |
+| `description` | Short human-readable summary |
+| `captureMode` | `hot` (written via `akm remember`) or `background` (inferred by `akm improve`) |
+| `beliefState` | See belief states below |
+| `supersededBy` | Points at the memory that replaced this one |
+
+Supply frontmatter fields explicitly with `--tag`/`--expires`/`--source`,
+derive them from the body heuristically with `--auto`, or have the
+configured LLM propose them with `--enrich`. See
+[`akm remember`](cli.md#remember) for the full flag list.
+
+### Belief states
+
+Memories carry a `beliefState` field that records how current they are.
+Search ranking does not read it; the `--belief` filter below does. The
+supported values, from strongest to weakest authority:
+
+| State | When it's set | `--belief` |
+| --- | --- | --- |
+| `asserted` | Written directly by `akm remember` (user-explicit) | current |
+| `active` | Default for memories with no explicit state | current |
+| `deprecated` | Marked as no-longer-current but not yet superseded; frozen (never auto-refreshed) | historical |
+| `superseded` | Replaced by another memory via the `supersededBy` field | historical |
+| `contradicted` | Marked as contradicted by other evidence | historical |
+| `archived` | Soft-deleted; retained for audit | historical |
+
+`akm search` filters via `--belief current|historical|all`:
+
+- `current` → `active` + `asserted`
+- `historical` → `deprecated` + `superseded` + `contradicted` + `archived`
+- `all` (default — no filter) → every belief state, including `archived` and
+  `contradicted` memories, is eligible to surface.
+
+### Derived memories as retrieval shortcuts
+
+When `akm improve` infers a derived memory from a parent (e.g. distilling a
+verbose memory into a focused summary), the derived memory is written with a
+`source:` frontmatter backref naming the parent, and the indexer records the
+parent/child link in the `derived_from` column. This provenance backref is a
+sanctioned internal channel that carries a bare parent name, not a public
+[ref](refs.md) — agents never construct it.
+
+Search hits for the parent memory are then enriched in-place: the parent's
+description and tags are swapped with the derived child's surface text, and
+an `expandTo: memories/<derived>` field on the hit points at the richer
+derived ref. The parent ref itself is preserved on the hit, so existing
+automation keeps working — agents that want the deeper summary follow
+`expandTo`.
+
+## Defaults
+
+- Hot-path memories (those written via `akm remember`) receive
+  `captureMode: hot` and `beliefState: asserted` in their frontmatter
+  automatically.
+- Background-derived memories (those inferred from other assets by `akm
+  improve`) receive `captureMode: background`.
+- A memory with no explicit `beliefState` defaults to `active`.
+- `akm search --belief` defaults to `all` — no filter is applied unless you
+  pass `current` or `historical` explicitly.
+
+## Security / persistence implications
+
+- Memories are plain markdown files inside a bundle directory; there is no
+  separate memory store. `akm improve` and `akm lint` only operate on
+  writable sources — a read-only registry-cached memory source is excluded
+  from cleanup and derivation passes even if it's indexed.
+- The derived-memory `source:` backref and the index's `derived_from` column
+  are an internal provenance channel, not a ref an agent should read,
+  construct, or rely on programmatically. Use the `expandTo` field on a
+  search hit instead.
+- Belief-state frontmatter is rewritten in place by `akm improve`'s memory
+  cleanup lane when autonomy is enabled (`experimental.improveAutonomy`);
+  with autonomy off, cleanup is analyzed but not applied. See
+  `STABILITY.md`'s "`akm improve` autonomy" section.
+
+## Stability
+
+Per `STABILITY.md`, **memory belief-state transitions are Experimental**:
+`captureMode`, `beliefState`, contradiction edges, and the consolidate
+journal are observable but the algorithm that writes them is tuning across
+patch releases. Do not script against the exact transition logic — the
+frontmatter fields and their meanings above are the stable-enough surface to
+read, but when and how akm assigns them is still settling. The `lesson`
+asset type, which shares the same distillation pipeline, is also
+Experimental for the same reason.
+
+## See also
+
+- [Concepts](../guides/concepts.md) — how a memory fits the capability model
+- [Refs](refs.md) — the public ref grammar (distinct from the internal derived-memory backref)
+- [Asset Types](asset-types.md) — where `memory` sits in the full type taxonomy
+- [`akm remember`](cli.md#remember) — the capture command and its flags
+- `STABILITY.md` — the full stability tier index, including `akm improve` autonomy

package/docs/reference/refs.md

@@ -0,0 +1,156 @@
+# Refs
+
+Reference for the ref grammar `akm search` emits and `akm show` consumes,
+rename semantics, and namespacing conventions.
+
+## Contract
+
+A **ref** is a compact handle identifying one capability. Agents should
+treat refs as opaque tokens — get them from search or curate, pass them to
+show. The structured `conceptId` and `bundle` fields in search results
+provide the same information in parseable form; never parse a ref string by
+hand.
+
+## Grammar
+
+```text
+[bundle//]conceptId[#fragment]
+```
+
+| Part | Required | Description |
+| --- | --- | --- |
+| `bundle` | no | Narrows lookup to one installed bundle, separated from the rest of the ref by `//`. Omit it and the ref resolves against the workspace `defaultBundle`, then the remaining bundles in installation-priority order. |
+| `conceptId` | yes | Subdir-qualified within its bundle: the placement subdirectory followed by the item's canonical name (extension stripped for markdown-like types; scripts and secrets keep their natural filename). `type` is not part of a ref — the subdirectory carries that signal. |
+| `fragment` | no | A selector for part of the item. Input-only — never stored. |
+
+Examples: `scripts/deploy.sh`, `agents/reviewer`, `knowledge/api-guide`,
+`workflows/ship-release`, `team-catalog//scripts/deploy.sh`,
+`personal//knowledge/guide`, `knowledge/api-guide#authentication`.
+
+Source locators like `github:owner/repo` and `npm:@scope/pkg` are **install
+refs**, a distinct grammar accepted only by `akm bundle add` and `akm
+clone`. They are not asset refs and are never addressable through `akm
+show`.
+
+This reference page is deliberately non-normative prose over the same
+grammar; [`docs/architecture/specs/ref.md`](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/ref.md)
+is the normative spec, including the `parseBundleRef` grammar, fragment
+resolution rules, and reserved-name handling.
+
+## Namespacing
+
+AKM supports **physical-subdirectory namespacing** — no extra flags
+required. Drop assets under nested directories beneath the type folder and
+the path becomes part of the ref's name:
+
+```text
+memories/projectA/auth-tip.md    →  memories/projectA/auth-tip
+memories/teamA/clientX/notes.md  →  memories/teamA/clientX/notes
+skills/projectB/lint-fix.md      →  skills/projectB/lint-fix
+knowledge/clientX/api-guide.md   →  knowledge/clientX/api-guide
+```
+
+This works for **any** asset type. The subpath segments become part of the
+conceptId, so `akm search "projectA" --type memory` narrows results to that
+subtree, and `akm show memories/projectA/auth-tip` resolves the full ref.
+
+There is also a **ref-prefix query syntax** — a query that is a conceptId
+prefix ending in `/` enumerates that subtree instead of keyword-matching:
+
+```sh
+akm search "memories/"                  # every memory
+akm search "memories/projectA/"         # exactly that subtree
+akm search "team-catalog//"             # every item in one bundle
+akm search "team-catalog//skills/"      # one subtree of one bundle
+```
+
+Enumeration is `/`-boundary exact — a sibling `projectAlpha/` scope does not
+leak — and hits are a deterministic listing with the fixed browse score `1`,
+not a relevance ranking. Because it matches conceptIds, it works for items
+from every adapter, and you can copy a ref prefix straight out of search
+output and paste it back as a query. A complete ref
+(`memories/projectA/auth-tip`, no trailing `/`) stays an ordinary keyword
+search — resolving a single ref is `akm show`'s job.
+
+**Recommendation:** use physical subdirectories now to organize multi-project
+or multi-team bundles. They sort cleanly on disk and require no
+configuration.
+
+**Which subdirectory?** Choose the partition axis by asset **type**:
+scope-born types (`memory`, `lesson`, `task`, `env`, `secret`) take the
+current **project/client** slug; reuse-born types (`knowledge`, `skill`,
+`fact`, `script`) take a stable **domain**; global types (`command`, `agent`,
+`workflow`) stay at the type root or a tool slug. The full rules — depth
+limits, no-volatile-facets, off-axis facets as tags, and how to cross-link
+for retrieval — ship as the `facts/conventions/organization`,
+`facts/conventions/backlinks`, and `facts/conventions/domains` convention
+facts in the bundle skeleton, and are surfaced to agents automatically at
+authoring time.
+
+### Planned
+
+Not part of the current stability contract; see
+[ROADMAP.md](../../ROADMAP.md) for what's committed:
+
+- A `--namespace <ns>` flag to provide a thin name-prefix normalizer on
+  `search`, `remember`, `improve`, and `feedback` so the same prefix doesn't
+  have to be typed every time.
+- A `::` delimiter (for example `projectA::memories/auth-tip`) to provide
+  strict isolation so refs from different namespaces never collide in
+  ranking or recall.
+
+Until those land, physical subdirectories remain the recommended pattern.
+
+## Renames and moves
+
+**Treat a ref as permanent.** A rename is **delete plus create**: the new
+path is a new identity, so the destination starts with fresh learned state
+(utility, salience, usage history) and any inbound refs to the old path
+dangle. When you must rename:
+
+```sh
+mv ~/akm/memories/old-note.md ~/akm/memories/new-note.md
+# update any intentional refs (they are fully qualified: bundle//memories/old-note)
+akm index
+akm lint          # confirms nothing dangles
+```
+
+Moving an item between bundles is copy/import followed by deletion from the
+source — both the bundle and the concept identity change. `akm mv`, which
+promised identity-preserving renames, was removed in 0.9.0: its inbound-ref
+rewriting targeted bare conceptIds rather than the anchored
+`bundle//conceptId` prose form, so it could rewrite non-refs while leaving
+real refs dangling. The procedure above is the only supported path today.
+
+To carry an asset's earned signal (feedback, usage, salience/outcome
+history) across a rename, the maintainer script `scripts/rekey-asset-ref.ts`
+re-keys those rows onto the new ref before `akm index` runs; it is Internal
+tooling, not a supported command surface. See
+[the decision record](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/0.9.0-decisions.md#d3--renames-are-delete--create-akm-mv-ships-experimental).
+
+## Refs in prose
+
+Refs embedded in prose must use the fully-qualified `bundle//conceptId` form
+— the bundle-slug charset makes such a token lexically anchored — or a
+native link form owned by the adapter (OKF links, wiki links). A bare
+conceptId in prose is ordinary text, not a ref, and no akm tool rewrites it.
+
+## Stability
+
+Per `STABILITY.md`, this is **Stable** surface: the
+`[bundle//]conceptId[#fragment]` grammar (durable state always stores the
+fully-qualified `bundle//conceptId`; the short form is accepted input only),
+conceptId-prefix enumeration, and the rename-is-delete-plus-create procedure
+are all named explicitly in the Stable tier, and the ref grammar is called
+out as frozen at 1.0 alongside the supported source model, search behavior,
+and write-target rules. The `--namespace` flag and `::` delimiter above are
+On the horizon, not yet part of the contract. See `STABILITY.md` for the
+full command- and surface-level tier index.
+
+## See also
+
+- [Concepts](../guides/concepts.md) — where refs fit in the retrieval loop
+- [Asset Types](asset-types.md) — how a conceptId's subdirectory maps to an asset type
+- [Memory](memory.md) — parent/derived-memory provenance backrefs
+- [`docs/architecture/specs/ref.md`](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/ref.md) — the normative ref grammar spec
+- [ROADMAP.md](../../ROADMAP.md) — planned ref-syntax additions