akm-cli 0.9.17-alpha.8 → 0.9.17-alpha.9

package/CHANGELOG.md

@@ -6,6 +6,340 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.17-alpha.9] - 2026-09-29
+
+`akm improve` now forgets, reversibly and under review. A consolidation pair
+pass compares each new or changed memory, flat knowledge file or lesson with
+its nearest neighbours; where an LLM judge calls a pair duplicate, subsumed or
+superseding, it mints a retire proposal that a person reviews (`akm proposal
+list --generator consolidate-pair`). Accepting one archives the older or
+contained copy, and `akm proposal revert` restores it exactly; an accepted
+promotion now retires its source memory, so promotion no longer leaves a
+duplicate. A continuity check flags a retirement whose survivor does not rank
+where the retired asset did for its own past searches, and a flagged proposal
+is never bulk-accepted. Archived files are purged 30 days after retirement,
+only when git holds them unmodified. The per-run forgetting-safety lane, LLM
+metadata enrichment and LLM entity-graph extraction are removed: each measured
+no benefit. Decide pending retire proposals before downgrading to
+0.9.17-alpha.8.
+
+### Added
+
+- **Consolidate pair pass: duplicate, subsumed and superseding memories are
+  now retired, review-gated.** A second pass inside `akmConsolidate`,
+  alongside the existing promote pass. It walks memory-tier assets (a
+  memory, base or `.derived`; a flat `knowledge/` asset; or a lesson) in the
+  retrieval scope that are new to the pass or whose body has changed since
+  their last full attempt — tracked by content hash, not a time window, so
+  an initiator the nightly cap or a pending-proposal collision leaves out
+  stays eligible rather than being marked settled, and the pass's own
+  ledger rows are never retrieval-scope evidence for the other improve
+  lanes — takes each one's nearest neighbours by stored vector (fetching 20,
+  keeping the first 5 that clear every filter; same bundle, memory tier
+  only — structured knowledge in subfolders is excluded), and judges every
+  pair at cosine >= `T_pair` (0.93) with one LLM call using the calibrated
+  relation prompt (`src/assets/prompts/consolidate-pair.md`, six labels:
+  `duplicate`, `subsumed`, `supersedes`, `contradicts`, `overlap`,
+  `unrelated`). An initiator with no prior attempt is held to a higher
+  `T_pair` >= 0.95, unless it is new material (git first-added within the
+  last 7 days), which judges at the ordinary 0.93. "Older"/"newer" for the
+  judge's own A/B labelling comes from one `git log` per run over the
+  bundle (first-add time, following renames so a moved or renamed file
+  keeps its original date), not frontmatter or file mtime — mtime is only
+  the fallback for a file git does not know, or a bundle with no `.git` at
+  all. At most 300 pairs are judged a night, admitted a whole initiator at
+  a time rather than by flat cosine rank: new-or-changed initiators first,
+  then the existing backlog by its own best cosine, each admitted only if
+  every one of its candidate pairs fits in what remains of the 300 — so an
+  initiator blocked on another pending decision never spends a slot doing
+  nothing, and a smaller initiator further down still fits when a larger
+  one ahead of it does not. `duplicate`, `subsumed` and `supersedes` mint a
+  reviewed `retire` proposal for the losing side (owner-calibrated
+  precision 20/22 = 0.91 [0.72, 0.97] against a second-rater baseline of
+  0.17 for `supersedes` alone); `contradicts` is counted but stays a human
+  decision, and `overlap`/`unrelated` get no proposal. Guards: never a
+  `captureMode: hot` memory, never a `.derived` memory whose parent still
+  exists, never a pair where either side already has a pending retire
+  proposal (as the retired ref or its successor), and never retiring or
+  reusing as a successor an asset already spent earlier in the same run.
+  (`src/commands/improve/consolidate/pair-pass.ts`,
+  `src/commands/improve/retrieval-scope.ts`,
+  `src/storage/repositories/improve-ledger-repository.ts`,
+  `src/assets/prompts/consolidate-pair.md`)
+- **Retire proposals.** A pair-pass retire proposal mints under its own
+  source, `consolidate-pair` — kept apart from the promote pass's
+  `consolidate` proposals, so a bulk `accept`/`reject --generator
+  consolidate` never sweeps a retirement, and the reverse; a bare `akm
+  proposal accept <ref>` never resolves to one either (it matches the
+  newest non-retire proposal for the ref, if any — a retire is reached by
+  its own proposal id, or the bulk `--generator consolidate-pair` form),
+  and retention expiry never drops a pending one for age alone. A pair the owner
+  rejected or reverted is not proposed again while both sides are unchanged. Its primary
+  change deletes its target instead of writing content. Accepting one first
+  confirms the decision is still fresh — the successor still exists, and
+  both sides' recorded body hashes still match their current files, not
+  just the retired side's, so a decision a later accept elsewhere made
+  stale (an A->B/B->C chain, or A->B/B->A both minted) is refused cleanly
+  rather than partially applied — then archives the asset (and its
+  `.derived` twin, if one exists) through a generalized
+  `archiveCleanupCandidate` (now usable on any memory, knowledge or lesson
+  file, not only `.derived` memories): the same
+  `.akm/memory-cleanup/archive/` encoding memory cleanup already used,
+  never the dead `.akm/archive/`. A `supersedes` judgement first writes the
+  `supersededBy` edge on the older asset, then archives it. Triage never
+  auto-accepts a retire proposal, whatever `applyMode` says — it waits for
+  a direct `akm proposal accept`, reviewed the same way as any other
+  proposal (`akm proposal list`, `show`, `diff`, bulk `accept --generator
+  consolidate-pair`; `--max-diff-lines` counts a retire by its target's own
+  line count). `accept` is crash-safe: it records its full intent —
+  `backupContent` and which file is about to move — durably before moving
+  anything, so a crash partway through, including between a primary and its
+  `.derived` twin, resumes and finishes from what was recorded rather than
+  leaving an asset stranded or the decision unrecorded. `revert` needs no
+  intent of its own — it resumes from what `accept` already recorded, and
+  refuses instead of overwriting a path that was reused by an unrelated file
+  since (its current content no longer matching what was retired). `revert`
+  restores the archived file(s) byte-for-byte from the bytes recorded at
+  accept, even a file that had no trailing newline — YAML comments, key
+  order and any human-written edge all survive the round trip. A ref to a retired asset keeps resolving to its tombstone
+  (`isArchivedRelPath`) — fixed along the way: that resolver assumed only
+  memories are ever archived, so an xref to a retired knowledge or lesson
+  asset was wrongly reported `missing-ref` by `akm lint` until now. Pending
+  retire proposals must be accepted or rejected before downgrading to
+  0.9.17-alpha.8 or earlier — that release predates the retire shape
+  entirely and exits 70 on one in `show`/`diff`/`drain`, and drain's own
+  nightly pre-pass failing on the first one it meets stops that run's
+  auto-promotion for the whole stash. Downgrading also revives the
+  new-material starvation this same branch fixed forward-only: 0.9.17-alpha.8
+  counts a pair-pass ledger row as retrieval-scope evidence again, so its own
+  nightly attempts crowd new material back out of every other improve lane —
+  measured, two nights left only 341 of 2,183 new-only assets still in scope
+  once read under alpha.8
+  (`docs/architecture/persisted-data-compat.md`).
+  (`src/commands/proposal/repository.ts`,
+  `src/commands/improve/memory/memory-improve.ts`,
+  `src/commands/lint/base-linter.ts`)
+- **A promotion retires its source memory (O1).** When `akm proposal accept`
+  promotes a consolidate `promote` proposal — by a person or by triage
+  auto-promotion — it now archives the source memory (and its `.derived`
+  twin) through the same retire-archive path, tombstoned `reason: promoted`,
+  provided the source's body still matches the hash recorded when the
+  promotion was minted; an edit since then leaves the source alone (a
+  proposal minted before this hash existed is never archived, for the same
+  reason). A promotion no longer leaves a memory/knowledge duplicate behind.
+  Best-effort: a failure to archive the source only warns; the promotion
+  itself is not undone. (`src/commands/improve/consolidate.ts`,
+  `src/commands/proposal/repository.ts`)
+- **Retirement continuity check (rule R3).** Before the pair pass mints a
+  `retire` proposal, it replays up to five of the retired asset's own past
+  `search`/`curate` queries through akm's own search, in-process — the
+  ranking a user actually gets, no LLM. For every query where the retired
+  asset ranked in the top 10, the successor must too; compared directly,
+  since search itself returns at most the top 10 hits. A failing
+  query never blocks the mint — the
+  proposal's `retirement.continuityRisk` records the failing query count
+  and, per failing query, the retired asset's rank and the successor's
+  (`null` when the successor did not rank in the top 10 at all). A proposal
+  carrying `continuityRisk` is excluded from every bulk accept path (`accept
+  --generator …`, with or without `--yes`) but not from bulk reject —
+  declining a flagged proposal is always the safe direction; a person can
+  always accept one by id. An asset with no recorded queries is not checked
+  at all. A query that never ran (the search call threw) or that fell back
+  to keyword-only ranking (an unreachable embedding endpoint, most often)
+  is never silently trusted or silently dropped either: it counts as
+  "unverified" and, on its own, is enough to flag `continuityRisk` — an
+  endpoint outage reads as "risk unknown," never as "no risk found," for
+  every proposal checked while it stays down, not just the first. The
+  first fallback in a pair-pass run forces every later query in that same
+  run to skip the semantic attempt entirely, so a dead endpoint costs one
+  failed attempt total, not one per remaining query. Two fixes against false
+  flags, measured on a real night-1 admission (300 pairs, 6 flags, 3
+  spurious): replayed queries are the same cleaned set the retrieval
+  regression gate uses (`loadRetrievalQueries`) — stash-README boilerplate,
+  harness/tool envelopes, pastes over 2,000 characters, and near-duplicate
+  queries (equal once whitespace is collapsed) are dropped before replay,
+  not just capped at five raw entries; and the check does not run at all
+  when the retired and successor bodies are content-identical once
+  whitespace is collapsed — search's own content-dedupe already hides the
+  successor behind the retired asset for every such query, so a "successor
+  missing" finding would not be a real risk.
+  (`src/commands/improve/consolidate/continuity-check.ts`,
+  `src/commands/proposal/proposal-types.ts`,
+  `src/commands/proposal/proposal.ts`)
+- **Continuity-risk visibility, and a `--generator` filter for `proposal
+  list`.** A retire proposal carrying `retirement.continuityRisk` now
+  shows `⚠ continuity-risk` inline in the default `akm proposal list`
+  output (and `--format text`), not just in `proposal show`. `proposal
+  show`'s text output now lists the actual failing query text and rank per
+  query, not just a count, and separately reports `unverifiedQueries` when
+  the risk is (also, or only) an unverified query rather than a rank
+  failure. `akm proposal accept --generator … --dry-run` (and a real bulk
+  run) now reports `skippedForContinuityRisk`, the count of otherwise
+  matching proposals excluded specifically for this reason, apart from an
+  ordinary `--max-diff-lines`/`--older-than` miss. `akm proposal list` gains
+  a `--generator <name>` filter, the same value `accept`/`reject
+  --generator` already take, so the (potentially large) backlog of one
+  generator's retire proposals can be reviewed as its own list.
+  (`src/commands/proposal/proposal.ts`, `src/commands/proposal/proposal-cli.ts`,
+  `src/output/text/proposal-format.ts`, `src/output/shapes/helpers.ts`)
+- **Archive purge sweep.** Deterministic, no LLM, run once at the very start
+  of every `akm improve` invocation, ahead of index bootstrap and triage.
+  For a git-backed bundle, deletes the archived asset file(s) of a
+  retirement — never its `cleanup.md` tombstone — once `retiredAt` is more
+  than 30 days old (`RETIRE_GRACE_DAYS`) AND every file under that
+  retirement's archive directory is git-tracked, clean (`git ls-files` plus
+  `git status --porcelain -uall`), and verifiable (`git ls-files -v`: a
+  file marked `assume-unchanged` or `skip-worktree` hides its own edits
+  from `git status`, so it is never trusted as clean either) — each checked
+  once per sweep; git history keeps the bytes. `.git` presence alone is not
+  enough: `proposal accept` only commits for a `kind: "git"` write target,
+  and improve's own auto-sync stages only the paths its own run wrote, so a
+  filesystem-kind bundle can carry archived retirements that were never
+  committed — the tracked/clean/verifiable check is what keeps the sweep
+  from deleting the only surviving copy of those. A directory with even one
+  untracked, modified, or unverifiable file (tombstone included) is left
+  whole for a later sweep — and so is the ENTIRE archive for that sweep if
+  the underlying `git status` or `git ls-files` call itself fails (a broken
+  submodule, for instance, can fail `git status` while `git ls-files`
+  still succeeds): an empty result from a failed check is never treated as
+  "nothing to protect", and the sweep warns once rather than silently
+  purging nothing. A memory-cleanup family-prune archive carries no
+  `retiredAt`, so this sweep never touches that older archive class. Every
+  deleted file is journaled individually, so the end-of-run auto-sync
+  commits the removal the same way it commits the archive move itself.
+  (`src/commands/improve/memory/memory-improve.ts`,
+  `src/sources/providers/git-stash.ts`, `src/commands/improve/improve.ts`)
+- **`akm health`'s `memory-cleanup-archive` advisory now covers every
+  bundle**, not just one with no `.git` at all. A bundle with no `.git` of
+  its own keeps every retirement's archived bytes forever (there is no
+  history to fall back on, so the purge sweep never runs there), and its
+  size and file count are reported as before. A git-backed bundle can ALSO
+  carry archived bytes the purge sweep will never remove — `.git` presence
+  alone never proved a retirement was committed — so this now runs the same
+  tracked/clean/verifiable check the purge sweep itself uses and reports
+  how many files and bytes of the archive cannot currently be purged
+  (untracked, modified, or unverifiable), alongside the total. Silent
+  whenever there is nothing to say: the archive is empty or absent, or (for
+  a git-backed bundle) every byte in it is purgeable once it ages out.
+  (`src/commands/health/archive-usage.ts`, `src/commands/health/data-dir-usage.ts`)
+
+### Removed
+
+- **LLM metadata enrichment (`index.metadataEnhance`) is retired.** On 49
+  stratified queries, with every eligible candidate enriched (1,968
+  entries): search nDCG@10 moved −0.0092 [−0.0324, +0.0165], curate P@5
+  +0.000 [−0.037, +0.045], and long prompts lost −0.054 [−0.093, −0.012]. A
+  Doc2Query-- filter made it worse (P@5 −0.020 [−0.045, −0.004]). The pass
+  replaced authored descriptions on 89% of the entries it rewrote, and a
+  full pass costs about 27 B70-hours (RS-D, owner ruling 2026-09-28). It was
+  already off by default and off in the maintainer's config. The LLM call
+  (`src/llm/metadata-enhance.ts`), its `akm index` dispatch, and the
+  `metadata_enhance` feature-gate key are gone; the deterministic metadata
+  pass, `quality: "generated"`, and memory inference are unaffected. A
+  config that still sets `index.metadataEnhance` loads, named once by the
+  same unknown-config-key path every other retired key uses: kept in
+  memory, round-trips through ordinary writes, and is dropped only by
+  `akm migrate apply`. The pass's `llm_enrichment_cache` rows (the default
+  `cache_variant`; graph and memory inference use their own named variants)
+  are deleted on the next writable open of `index.db`. An index built while
+  enrichment was on keeps its entries' LLM-written descriptions on
+  incremental runs — nothing rewrites an unchanged row; run
+  `akm index --full` once to replace them with the deterministic ones.
+  (`src/indexer/indexer.ts`, `src/llm/feature-gate.ts`,
+  `src/core/config/config.ts`, `src/core/config/schema/index-config.ts`,
+  `src/storage/repositories/index-schema.ts`)
+- **The LLM entity-graph extraction pass.** `akm improve`'s per-file
+  entity/relation extraction, its persisted tables (`graph_meta`,
+  `graph_files`, `graph_file_entities`, `graph_file_relations`), and `akm
+  show`'s `related` list are gone. On the navigation eval, vector kNN beat
+  the LLM `related` list by 0.157 P@5 [0.051, 0.260]; the ranking boost it
+  once fed was already removed in 0.9.17-alpha.4. Declared links (#935,
+  alpha.8) are the only navigation surface `akm show` has now, and curate's
+  support refs already came from them, not the graph. index.db is a
+  regenerable cache, so the graph tables are dropped unconditionally on the
+  next writable open — nothing migrates or backs them up.
+- **The `graph-refresh` improve strategy** and the `akm-graph-refresh-weekly`
+  task template are deleted. Naming `graph-refresh` via `--strategy` or a task
+  now fails with a message naming the retirement, unconditionally — even when
+  `improve.strategies["graph-refresh"]` still has a leftover override block
+  from customizing the built-in (the message names it; `akm migrate apply`
+  drops it). `defaults.improveStrategy: "graph-refresh"` still loads config
+  successfully — the refusal happens lazily, when the strategy is actually
+  resolved, not at every command's config load.
+- **Retired config keys:** `index.graph.*` and every strategy's
+  `processes.graphExtraction.*`. An old config that still sets them keeps
+  loading and the keys are unread, but `index.graph` is now also named once
+  by the unknown-config-key warning (it previously validated silently
+  against the generic per-pass catchall) and, like any other retired key,
+  is dropped only by `akm migrate apply` — not by an ordinary config write.
+- **`akm health` drops every graph metric** — the KPI card, summary-table
+  rows, per-run duration/entity/relation columns, and the
+  `improve.graphExtraction.failures` window-compare delta. `--window-compare`
+  and `--group-by run` still count every run, including a pre-alpha.9 one:
+  its stored `graphExtraction`/`graphExtractionDurationMs` result fields and
+  its `graph-extraction` `plan.stages` / `graphExtraction` `plan.processes`
+  entries still decode, read-only, same as any other retired field (AGENTS.md
+  "Reading persisted data") — they are just no longer rendered. The
+  `improve_completed` event's `graphExtractionExtractedFiles`,
+  `graphExtractionDurationMs`, `graphCoverage`, `graphDensity`, and
+  `graphEntities` metadata fields are no longer emitted.
+- **The per-run forgetting-safety lane.** `scoreSalience`'s stash-wide
+  salience-rank comparison, `applyForgettingSafety`, and the
+  `improve_salience_rank_change` event are gone. It was a one-time WS-1
+  cutover guard from the June 2026 ranking-formula change that had kept
+  running on every improve run since; the last 30 days of events
+  (2026-08-30 to 2026-09-29: 47 `improve_salience_rank_change` events, 5
+  refs flagged across 4 runs — 09-05, 09-08 x2, 09-19, 09-28) showed no
+  marginal pick over the signal-delta lane and the retrieval scope: 4 of
+  the 5 flagged refs were also picked that same run by signal-delta
+  (adjacent event ids/timestamps, 2–26 minutes after the rank-change
+  event), and the 5th (`workflows/create-github-issues-from-spec`, flagged
+  09-05) has no `reflect_invoked` or `distill_invoked` event in the
+  retained history, but that run's `improve_runs.plannedRefs` shows it,
+  too, was planned under `signal-delta` — just not reflected (a
+  dispatch/budget limit that run, not a lane-exclusive pick). All 5
+  flagged refs were signal-delta picks; zero were forgetting-safety-only.
+  It also protected
+  `asset_salience.rank_score`, which only improve itself ever read — a rank
+  drop could not hide anything from search. `buildRankChangeReport` (its
+  comparator) is also gone: the new retirement continuity check (see
+  Added) compares ranks directly instead, and nothing else called it.
+  `forgetting-safety` stays a valid `eligibilitySource`/event-type
+  value so old proposals and events still decode, but nothing assigns or
+  emits it any more. (`src/commands/improve/preparation.ts`,
+  `src/commands/improve/salience.ts`, `src/core/events.ts`,
+  `src/storage/repositories/salience-repository.ts`)
+- **`improve.strategies.<name>.processes.consolidate.incrementalSince` and
+  `.neighborsPerChanged`.** The consolidate pair pass is now the candidate
+  generator, narrowing per initiator through the improve ledger rather than
+  a global time window; neither key was set anywhere in the owner's config.
+  `narrowToIncrementalCandidates` goes with them, along with its
+  now-orphaned `parseSinceToIsoLenient` helper. A config that still sets
+  either key keeps loading under the retired-key contract: named once as
+  unknown, it survives an ordinary config write, and only `akm migrate
+  apply` drops it. (`src/core/config/schema/improve-processes.ts`,
+  `src/commands/improve/consolidate.ts`, `src/core/time.ts`,
+  `docs/reference/configuration.md`)
+
+### Fixed
+
+- **Stale "advisory merge/delete/contradict" documentation.** Consolidation
+  stopped executing its merge/delete/contradict operations at `e82eec811`
+  (2026-07, #732; they had run in production until then, not "never
+  executed" as a couple of doc comments and `improve-workflow.md` claimed),
+  and 0.9.17-alpha.1 (`f4ebd763a`) dropped them from the prompt and schema,
+  which have offered `promote` only since. But `docs/architecture/
+  improvement.md`, `STABILITY.md` and `docs/architecture/internals/
+  improve-workflow.md` still described them as advisory planned output.
+  Corrected, and `improve-workflow.md` gains a section documenting the pair
+  pass, retire proposals and O1. Also corrected: the `default` strategy's
+  "advisory consolidation" description, two comments that still credited a
+  `beliefState` ranking boost alpha.4 removed (`memory-belief.ts`,
+  `knowledge.ts`), and D27's stale `archiveMemory` naming in the
+  architecture decision history. Deleted the unused
+  `src/assets/prompts/contradiction-judge.md` (no reader since
+  `e82eec811`).
+
 ## [0.9.17-alpha.8] - 2026-09-28
 
 `akm index` now records the links a bundle already declares (`xrefs`,

package/STABILITY.md

@@ -366,8 +366,8 @@ for scripted use.
 ### `akm improve` autonomy — opt-in in 0.9.0
 
 **`akm improve` is review-first by default in 0.9.0.** The command itself is ON
-— its schedules, reflect/distill proposals, and graph extraction all run — but
-the lanes that mutate assets *without* review require an explicit opt-in:
+— its schedules and reflect/distill proposals all run — but the lanes that
+mutate assets *without* review require an explicit opt-in:
 
 ```sh
 akm config set experimental.improveAutonomy true
@@ -388,9 +388,10 @@ review-first config correctly shows `queue`.
 | memory cleanup | Belief-state frontmatter rewrites, archive moves | analyzed but not applied |
 | `triage` `applyMode: "promote"` | Auto-accepts queued proposals into the bundle | downgraded to `queue` — triage still runs, it just does not auto-accept |
 
-Consolidation remains enabled with autonomy off because merge, delete, and
-contradiction operations are advisory; promotion only emits a reviewable
-proposal.
+Consolidation remains enabled with autonomy off: both its passes (promotion,
+and the pair pass's duplicate/subsumed/supersedes judging) only ever emit a
+reviewable proposal, and a pair-pass `retire` proposal is never auto-accepted
+by `triage` `applyMode: "promote"` regardless of this gate.
 
 Because the gate is applied before the LLM preflight, a review-first workspace
 also needs fewer engines configured: a strategy whose only model-backed process
@@ -409,9 +410,9 @@ Autonomy is never inferred: an absent `experimental` section, an absent key, and
 an explicit `false` all read as off, so a partially-written or older config is
 review-first rather than accidentally permissive.
 
-Reflect, distill, extract candidates, validation, proactive-maintenance
-selection, and graph extraction are proposal-only and never write assets
-directly. Two further direct writes are ungated by design: `extract`'s session
+Reflect, distill, extract candidates, validation, and proactive-maintenance
+selection are proposal-only and never write assets directly. Two further
+direct writes are ungated by design: `extract`'s session
 indexing (additive `sessions/**` writes,
 `processes.extract.indexSessions`, default on) and distill's
 encoding-salience frontmatter stamp (metadata only).

package/dist/assets/hints/cli-hints-full.md

@@ -245,10 +245,9 @@ akm improve --no-push                         # commit but skip push for this ru
 akm improve --sync                            # force sync even on strategies that disable it
 ```
 
-Strategy sync defaults: `catchup`, `consolidate`, `default`,
-`graph-refresh`, `quick`, and `thorough` auto-commit + push;
-`proactive-maintenance` and `reflect-distill` skip sync entirely. Override
-with `--sync` / `--no-sync` flags.
+Strategy sync defaults: `catchup`, `consolidate`, `default`, `quick`, and
+`thorough` auto-commit + push; `proactive-maintenance` and `reflect-distill`
+skip sync entirely. Override with `--sync` / `--no-sync` flags.
 
 The `--writable` flag on `akm bundle add` opts a remote git bundle into push-on-sync:
 
@@ -308,8 +307,8 @@ akm bundle create                                      # Initialize working bund
 akm setup                                     # Interactive wizard: bundle + LLM/embedding + agent + registry config
 akm setup --dir ~/custom-bundle                # Run the wizard against a custom bundle path
 akm setup --yes                               # Non-interactive, accepts all defaults
-akm index                                     # Rebuild search index (metadata enrichment when configured)
-akm index --full                              # Full reindex (metadata enrichment when configured)
+akm index                                     # Rebuild search index
+akm index --full                              # Full reindex
 akm bundle list                                      # List all sources
 akm lint                                      # Structural lint over the bundle; exits 0 regardless of findings
 akm lint --fix                                # Auto-fix Tier 1 issues
@@ -399,7 +398,7 @@ akm agent --model sonnet --prompt "..."         # Model override (aliases or exa
 ```sh
 akm info                                       # Capabilities, bundle dir, index stats, semantic-search status
 akm health                                     # Runtime diagnostics; exit 0 ok / 4 warn / 1 fail
-akm health --report                            # Adds accept-rate and graph-coverage metrics
+akm health --report                            # Adds accept-rate metrics
 akm log                                        # Append-only event stream (mutations, feedback, indexing)
 akm log --ref <ref>                            # One asset's event trail
 akm log --since @offset:<id>                   # Durable row-id cursor — poll this to follow the stream

package/dist/assets/improve-strategies/catchup.json

@@ -16,9 +16,6 @@
     "memoryInference": {
       "enabled": false
     },
-    "graphExtraction": {
-      "enabled": false
-    },
     "extract": {
       "enabled": false
     },

package/dist/assets/improve-strategies/consolidate.json

@@ -5,7 +5,6 @@
     "distill": { "enabled": false },
     "consolidate": { "enabled": true, "allowedTypes": ["memory"], "maxChunkSize": 25 },
     "memoryInference": { "enabled": false },
-    "graphExtraction": { "enabled": false },
     "extract": { "enabled": false },
     "triage": { "enabled": false },
     "validation": { "enabled": false },

package/dist/assets/improve-strategies/default.json

@@ -1,5 +1,5 @@
 {
-  "description": "Standard improve pass — reflect, distill, advisory consolidation, graph extraction, and validation. Memory inference is listed below but only runs when experimental.improveAutonomy is set; improve-stage extract and proactive maintenance off.",
+  "description": "Standard improve pass — reflect, distill, consolidation (promotion plus the reviewed pair-pass retire/supersede proposals), and validation. Memory inference is listed below but only runs when experimental.improveAutonomy is set; improve-stage extract and proactive maintenance off.",
   "processes": {
     "reflect": {
       "enabled": true,
@@ -9,7 +9,6 @@
     "distill": { "enabled": true, "allowedTypes": ["memory"], "requirePlannedRefs": true },
     "consolidate": { "enabled": true, "allowedTypes": ["memory"] },
     "memoryInference": { "enabled": true },
-    "graphExtraction": { "enabled": true },
     "extract": { "enabled": false, "triage": { "enabled": true, "minScore": 2 } },
     "validation": { "enabled": true },
     "proactiveMaintenance": { "enabled": false, "dueDays": 30, "maxPerRun": 15 },

package/dist/assets/improve-strategies/proactive-maintenance.json

@@ -1,5 +1,5 @@
 {
-  "description": "Opt-in proactive-maintenance pass — reflect, distill, proposal triage (promote, high budget), and the proactive-maintenance lane (maxPerRun 100); consolidate/memoryInference/graphExtraction/extract off. Sync disabled: an interrupted run would otherwise leave an uncommitted backlog.",
+  "description": "Opt-in proactive-maintenance pass — reflect, distill, proposal triage (promote, high budget), and the proactive-maintenance lane (maxPerRun 100); consolidate/memoryInference/extract off. Sync disabled: an interrupted run would otherwise leave an uncommitted backlog.",
   "processes": {
     "reflect": {
       "enabled": true,
@@ -8,7 +8,6 @@
     "distill": { "enabled": true, "allowedTypes": ["memory"] },
     "consolidate": { "enabled": false },
     "memoryInference": { "enabled": false },
-    "graphExtraction": { "enabled": false },
     "extract": { "enabled": false },
     "validation": { "enabled": false },
     "triage": {

package/dist/assets/improve-strategies/quick.json

@@ -1,5 +1,5 @@
 {
-  "description": "Reflect-only pass — no extract, distill, consolidate, memoryInference, or graphExtraction.",
+  "description": "Reflect-only pass — no extract, distill, consolidate, or memoryInference.",
   "processes": {
     "reflect": {
       "enabled": true,
@@ -9,7 +9,6 @@
     "distill": { "enabled": false },
     "consolidate": { "enabled": false },
     "memoryInference": { "enabled": false },
-    "graphExtraction": { "enabled": false },
     "triage": { "enabled": false },
     "validation": { "enabled": false },
     "proactiveMaintenance": { "enabled": false }

package/dist/assets/improve-strategies/reflect-distill.json

@@ -1,5 +1,5 @@
 {
-  "description": "Reflect + distill pass — reflect, distill, memoryInference, and proposal triage (promote); proactiveMaintenance/consolidate/graphExtraction/extract off. Sync disabled: an interrupted run would otherwise leave an uncommitted backlog.",
+  "description": "Reflect + distill pass — reflect, distill, memoryInference, and proposal triage (promote); proactiveMaintenance/consolidate/extract off. Sync disabled: an interrupted run would otherwise leave an uncommitted backlog.",
   "processes": {
     "reflect": {
       "enabled": true,
@@ -8,7 +8,6 @@
     "distill": { "enabled": true, "allowedTypes": ["memory"], "requirePlannedRefs": false },
     "consolidate": { "enabled": false },
     "memoryInference": { "enabled": true },
-    "graphExtraction": { "enabled": false },
     "extract": {
       "enabled": false,
       "timeoutMs": 300000,

package/dist/assets/improve-strategies/thorough.json

@@ -18,9 +18,6 @@
     "memoryInference": {
       "enabled": true
     },
-    "graphExtraction": {
-      "enabled": true
-    },
     "extract": {
       "enabled": false,
       "triage": {

package/dist/assets/prompts/consolidate-pair.md

@@ -0,0 +1,20 @@
+You compare two assets from one person's agent-memory library (memories and knowledge notes an AI coding agent reads). Asset A is the OLDER one and asset B the NEWER one, by the dates shown.
+
+Classify the relation between them as exactly one of:
+
+- "duplicate": they state the same durable facts. Wording, title or formatting may differ, but neither adds a claim a reader would need that the other lacks.
+- "subsumed": one of them contains every durable claim of the other, plus more. The smaller one is redundant.
+- "supersedes": B updates, corrects, reverses or replaces a claim in A (a newer version, a changed decision, a fixed bug, a new value). A is now stale or wrong on that point.
+- "contradicts": they make logically exclusive claims about the same thing and nothing shows which one is current.
+- "overlap": same subject, but each has durable claims the other lacks. Keeping both loses nothing; merging them would keep both sets of claims.
+- "unrelated": different subjects or different facts that happen to share words.
+
+Rules:
+- A durable claim is a fact, decision, value, command, path, number or rule someone would act on. Ignore dates, headings, tags and phrasing.
+- Prefer "overlap" over "duplicate" when either asset has a specific detail (a number, command, file, version or condition) that the other lacks.
+- "supersedes" needs a specific claim in A that B changes. Being newer or longer is not enough.
+- "contradicts" needs two claims that cannot both be true. Different scope, project or time is not a contradiction.
+
+Set "redundant" to "A" or "B" when that asset could be removed with no loss (only for "duplicate" or "subsumed"; for "duplicate" name the less complete or older one), else null. Set "stale" to "A" when the relation is "supersedes", else null.
+
+Answer ONLY with JSON: {"relation": "...", "redundant": "A"|"B"|null, "stale": "A"|null, "confidence": 0.0-1.0, "reason": "<at most 25 words>"}

package/dist/assets/stash-skeleton/facts/conventions/backlinks.md

@@ -8,11 +8,11 @@ updated: 2026-09-28
 
 <!--
   SOFT guidance only — advice, not a contract. Back-linking here is a RETRIEVAL
-  mechanism, not decoration: `xrefs:` frontmatter folds into the search index;
-  the entity/relation graph is extracted from BODY prose (memory + knowledge),
-  never from frontmatter. Over-linking degrades ranking, so these rules are
-  deliberately conservative. (LLM-wiki bundles carry their own xref system in
-  their pages' frontmatter — this convention is for in-stash assets.)
+  mechanism, not decoration: `xrefs:` frontmatter folds into the search index
+  and is stored as a declared link `akm show` lists on both assets.
+  Over-linking degrades ranking, so these rules are deliberately conservative.
+  (LLM-wiki bundles carry their own xref system in their pages' frontmatter —
+  this convention is for in-stash assets.)
 -->
 
 # Back-linking conventions
@@ -21,9 +21,8 @@ Cross-references are how knowledge compounds instead of being re-derived every
 session. In AKM they are also **indexed**: the strings in an asset's `xrefs:`
 frontmatter fold into its search-hint text and are stored as links that
 `akm show` lists on both assets (with `supersededBy:`, `contradictedBy:` and a
-`.derived` memory's parent), and knowledge/memory bodies feed an LLM-extracted
-entity/relation graph that boosts ranking. So links are a retrieval
-lever — which means both too few and too many hurt.
+`.derived` memory's parent). So links are a retrieval lever — which means both
+too few and too many hurt.
 
 ```yaml
 ---
@@ -48,10 +47,8 @@ xrefs:
 - **Associative xrefs are discretionary — real relationships only.** Add one when
   you already know a genuine load-bearing connection. Do **not** hit a link
   quota by pointing at the topically-nearest sibling — a plausible-but-wrong
-  xref makes this asset a false search match for the other topic, and a wrong
-  relationship asserted in prose poisons the entity graph. A relationship you
-  want the graph to learn must be named in the body (e.g. open with "Corrects
-  knowledge/auth/oauth-refresh-races").
+  xref makes this asset a false search match for the other topic and a false
+  declared link on both assets' `akm show` output.
 - **Cap total xrefs at ~5 (a heuristic, not a measured threshold).** Each xref
   folds its ref tokens into THIS asset's search hints — past a handful, the
   asset matches queries about several other topics and its own ranking signal
@@ -80,19 +77,20 @@ prose is indexed in the lowest-weight `content` field, so
 `description:`/`when_to_use:` remain the primary orientation channel. Then
 open the body with a plain title plus a one-line
 orientation naming what it is, its scope/domain, and its key entities in
-canonical spelling (`Postgres`, `OAuth`, `TLS`, `Acme`) — the entity/relation
-graph is extracted from body prose, and readers land here from `akm show`.
-Keep the canonical-spelling list in `facts/conventions/domains` so agents don't
-fragment `postgres` / `postgresql` / `pg`.
+canonical spelling (`Postgres`, `OAuth`, `TLS`, `Acme`) — consistent spelling
+keeps search matches from fragmenting across variants, and readers land here
+from `akm show`. Keep the canonical-spelling list in `facts/conventions/domains`
+so agents don't fragment `postgres` / `postgresql` / `pg`.
 
 ## Hubs are optional, not per-namespace obligations
 
 A hub (a `knowledge/` overview page that xrefs the key assets in a domain) is
 worth authoring for a **few genuinely high-traffic domains**. Do **not**
 mandate a hub per namespace and do not edit a hub on every write: that is O(n)
-maintenance, a concurrent-write contention point, and it flattens the multi-hop
-graph into a namespace-wide star. Let the FTS index be the catalog; spend the
-effort on per-asset self-situating headers instead.
+maintenance, a concurrent-write contention point, and it flattens every linked
+asset's declared links into a namespace-wide star centered on the hub. Let the
+FTS index be the catalog; spend the effort on per-asset self-situating headers
+instead.
 
 ## Keep assets atomic
 

package/dist/assets/stash-skeleton/facts/conventions/domains.md

@@ -48,8 +48,8 @@ volume justifies it.
 ## Canonical entity spellings
 
 Pick ONE name per entity and use it everywhere in asset **bodies** — retrieval
-is case-insensitive but treats aliases as different entities, so alias variants
-fragment the entity graph. Extend as your stash grows.
+is case-insensitive but treats aliases as different terms, so alias variants
+fragment search matches. Extend as your stash grows.
 
 - Postgres (not postgresql / pg)
 - Kubernetes (not k8s)