akm-cli 0.9.0-beta.43 → 0.9.0-beta.44

package/dist/commands/improve/improve.js

@@ -3987,6 +3987,7 @@ async function runImprovePostLoopStage(args) {
                 // #632 — clustering-tuning knobs. UNSET = pre-#632 behaviour.
                 maxClusterSize: improveProfile.processes?.recombine?.maxClusterSize,
                 excludeTags: improveProfile.processes?.recombine?.excludeTags,
+                excludeEntities: improveProfile.processes?.recombine?.excludeEntities,
             });
         }
         catch (e) {

package/dist/commands/improve/recombine.js

@@ -57,7 +57,27 @@ import { isConsolidationEligibleMemoryName } from "./consolidate.js";
 const RECOMBINE_SYSTEM_PROMPT = recombineSystemPrompt;
 const DEFAULT_MIN_CLUSTER_SIZE = 3;
 const DEFAULT_MAX_CLUSTERS_PER_RUN = 5;
-const DEFAULT_RELATEDNESS_SOURCE = "tags";
+// #632 — slots in each run's processed budget reserved for the top TAG clusters
+// when entity clusters are present, so tag-only topics (a topic with a good tag
+// but no extracted graph entity) are never fully starved by entity preference.
+// Entities still take the rest of the budget; whichever kind is short, the other
+// backfills. UNSET of entities (tags-only stash) ignores this and takes top-N tags.
+const RESERVED_TAG_SLOTS = 3;
+// #632 — a tag cluster larger than this is treated as an over-broad project
+// mega-bucket (low-coherence, the bland signal #632 de-emphasizes), so the
+// reserved tag slots prefer TIGHTER clusters at or below this size first.
+const TAG_RESERVE_SOFT_CAP = 20;
+// #632 — default to the UNION of tag + graph-entity relatedness, with entity
+// clusters PREFERRED at selection time (see the rank in buildRelatednessClusters).
+// Entity clustering surfaces coherent, subject-scoped clusters (a tool/subsystem)
+// that the coarse stash-wide tag buckets miss, while tags still cover memories the
+// graph has no entity for. The `entity:` vs `tag:` signature namespaces are
+// independent, so a pure tag cluster's confirmation streak is only re-baselined
+// when its OWN membership changes — which is exactly what the session-capture pool
+// exclusion intends for the telemetry-polluted buckets (re-baselining a noisy
+// cluster's streak is correct, not a regression). A stash with no extracted graph
+// entities falls through to tag-only.
+const DEFAULT_RELATEDNESS_SOURCE = "both";
 /** #625 — re-induction count required before a hypothesis promotes to a lesson. */
 const DEFAULT_CONFIRM_THRESHOLD = 2;
 /**
@@ -131,6 +151,76 @@ export function isJunkTag(tag) {
         return true; // short hex hashes: 002c624c, 192d
     return false;
 }
+/**
+ * #632 — generic extraction-artefact entities the graph routinely emits: session
+ * bookkeeping (`session_id`, `session_checkpoint`), structured-log field names
+ * (`reason`, `harness`, `structured event log`), and the like. They are
+ * stash-wide and carry no topical signal, so an `entity:<norm>` cluster keyed on
+ * one is exactly the bland mega-bucket #632 aims to remove. Lowercased; matched
+ * against the already-normalised `entity_norm`.
+ */
+const JUNK_ENTITY_NORMS = new Set([
+    "session",
+    "session_id",
+    "session_checkpoint",
+    "checkpoint",
+    "reason",
+    "harness",
+    "event",
+    "event log",
+    "structured event",
+    "structured event log",
+    "timestamp",
+    "metadata",
+    "status",
+]);
+/**
+ * #632 — AKM session-capture telemetry memories: auto-generated session-end
+ * checkpoints named `<harness>-session-<YYYYMMDD>-<id>` or
+ * `<harness>-checkpoint-<YYYYMMDD…>-<id>`, carrying an embedded
+ * `akm_memory_kind: session_checkpoint` metadata block. Their bodies are
+ * pipeline bookkeeping, so the graph extracts their metadata FIELDS
+ * (`session_checkpoint`, `harness`, `buffered observations`, `tool_*_observed`,
+ * …) as ENTITIES — which then dominate entity clustering as bland, stash-wide
+ * mega-buckets (the #632 symptom, just under an `entity:` signature). They are
+ * session telemetry, not durable knowledge to generalize, so recombine excludes
+ * them from its pool. The `\d{8}` datestamp anchor is what distinguishes a
+ * capture name from a durable memory that merely MENTIONS session/checkpoint
+ * (e.g. `akm-plugins-session-end-extract-hook`, `session-checkpoint-lint-skips`),
+ * which stay in the pool.
+ */
+export function isSessionCaptureMemoryName(name) {
+    return /-(session|checkpoint)-\d{8}/.test(name);
+}
+/**
+ * #632 — an entity carries no clustering signal (and must be skipped) when it is
+ * a generic extraction artefact (session / structured-log bookkeeping), a raw
+ * filesystem path (absolute paths the extractor lifts verbatim), or the same
+ * number / date / hash / version / stopword junk `isJunkTag` rejects. Mirrors
+ * `isJunkTag` so the graph relatedness source does not reintroduce the very
+ * bland buckets entity clustering is meant to replace. Unlike `excludeEntities`
+ * (a fixed user list), this catches the OPEN-ENDED junk without config upkeep.
+ */
+export function isJunkEntity(entity) {
+    const e = entity.trim().toLowerCase();
+    if (e.length <= 1)
+        return true;
+    if (JUNK_ENTITY_NORMS.has(e))
+        return true;
+    if (JUNK_STOPWORD_TAGS.has(e))
+        return true;
+    if (e.includes("/") || e.includes("\\"))
+        return true; // raw file paths
+    if (/^\d+$/.test(e))
+        return true; // pure numbers + dates
+    if (/^v?\d+(?:\.\d+)+$/.test(e))
+        return true; // versions
+    if (/^v\d+$/.test(e))
+        return true; // v0, v2
+    if (/^[0-9a-f]{4,}$/.test(e) && /\d/.test(e))
+        return true; // short hex hashes
+    return false;
+}
 /**
  * Build relatedness clusters from the memory pool. Clustering is driven purely
  * by shared tags / graph entities — it MUST NOT use embedding similarity, so
@@ -146,13 +236,19 @@ export function isJunkTag(tag) {
  * A cluster is a signal whose member set is >= `minClusterSize`. Overlapping
  * clusters are de-duplicated by member-set identity, and the result is RANKED
  * by member-count descending (deterministic alphabetical tiebreak). The
- * `maxClustersPerRun` cap is NOT applied here — call {@link capClusters} on the
- * result for the processed slice; the full ranked list is retained so the
- * cap-aware decay sweep can tell cap-displacement from corpus absence (#658).
+ * `maxClustersPerRun` cap is NOT applied here — call {@link selectClustersForRun}
+ * (entity-aware blend) or {@link capClusters} (tags-only) on the result for the
+ * processed slice; the full ranked list is retained so the cap-aware decay sweep
+ * can tell cap-displacement from corpus absence (#658).
  */
 export function buildRelatednessClusters(entries, opts) {
     // Only consolidation-eligible memories participate (exclude `.derived`).
-    const memories = entries.filter((e) => e.entry.type === "memory" && isConsolidationEligibleMemoryName(e.entry.name));
+    // #632 — durable memories only: exclude `.derived` (via
+    // `isConsolidationEligibleMemoryName`) AND session-capture telemetry dumps
+    // whose embedded metadata pollutes both tag and entity clustering.
+    const memories = entries.filter((e) => e.entry.type === "memory" &&
+        isConsolidationEligibleMemoryName(e.entry.name) &&
+        !isSessionCaptureMemoryName(e.entry.name));
     // signal -> member entries
     const groups = new Map();
     const add = (signal, entry) => {
@@ -173,9 +269,13 @@ export function buildRelatednessClusters(entries, opts) {
     const hasEntities = !!opts.entityByEntryId && opts.entityByEntryId.size > 0;
     const useGraph = (opts.relatednessSource === "graph" || opts.relatednessSource === "both") && hasEntities;
     const tagsFallback = !useTags && opts.relatednessSource === "graph" && !hasEntities;
-    // #632 — tags excluded from tag-based clustering (applies regardless of
-    // source). UNSET/[] leaves clustering byte-identical to the pre-#632 path.
+    // #632 — tags/entities excluded from clustering (applies regardless of
+    // source). UNSET/[] leaves tag clustering byte-identical to the pre-#632 path.
     const excludeTags = new Set(opts.excludeTags ?? []);
+    // `entity_norm` is always lowercased (graph-dedup.ts), so normalise the
+    // user-supplied exclusion list to match — `excludeEntities: ["OpenCode"]`
+    // should suppress the stored `opencode` entity (Reviewer A, #632).
+    const excludeEntities = new Set((opts.excludeEntities ?? []).map((e) => e.toLowerCase()));
     for (const entry of memories) {
         if (useTags || tagsFallback) {
             for (const tag of entry.entry.tags ?? []) {
@@ -187,8 +287,13 @@ export function buildRelatednessClusters(entries, opts) {
             }
         }
         if (useGraph && opts.entityByEntryId) {
-            for (const ent of opts.entityByEntryId.get(entry.id) ?? [])
+            for (const ent of opts.entityByEntryId.get(entry.id) ?? []) {
+                if (excludeEntities.has(ent))
+                    continue;
+                if (isJunkEntity(ent))
+                    continue; // #632 — skip generic extraction-artefact / path entities
                 add(`entity:${ent}`, entry);
+            }
         }
     }
     // Keep only groups at or above the minimum cluster size. #632 — when
@@ -216,12 +321,25 @@ export function buildRelatednessClusters(entries, opts) {
         seenMemberKeys.add(memberKey);
         return true;
     });
-    // Rank largest-first (deterministic alphabetical tiebreak). The cap is applied
-    // by the caller via {@link capClusters}, NOT here, so the FULL formed set
-    // (every cluster that genuinely re-forms this run) stays available for the
-    // cap-aware decay sweep — a cluster displaced by the cap must not be confused
-    // with a cluster that vanished from the corpus (#658).
-    clusters.sort((a, b) => b.members.length - a.members.length || a.signature.localeCompare(b.signature));
+    // #632 — rank ENTITY clusters ahead of tag clusters, then largest-first within
+    // each kind (deterministic alphabetical tiebreak). A graph entity is an
+    // EXTRACTED SUBJECT (a tool / subsystem / component), so it is a far
+    // higher-signal cluster key than an auto-tokenized frontmatter tag, whose
+    // broadest buckets (`tag:<project>` — e.g. every memory tagged `akm`) are the
+    // coarse, bland clusters #632 set out to kill. Largest-first ALONE let those
+    // tag mega-buckets fill the `maxClustersPerRun` slice every run and starve the
+    // coherent entity clusters this pass produces. Preferring entities keeps tag
+    // clustering as the fallback (a stash with no graph entities, or a topic with a
+    // tag but no extracted entity, still clusters) while ensuring the better signal
+    // wins the cap. The processed slice is chosen by the caller via
+    // {@link selectClustersForRun} (NOT here), so the FULL formed set stays
+    // available for the cap-aware decay sweep —
+    // a cluster displaced by the cap must not be confused with a cluster that
+    // vanished from the corpus (#658).
+    const entityRank = (sig) => (sig.startsWith("entity:") ? 0 : 1);
+    clusters.sort((a, b) => entityRank(a.signature) - entityRank(b.signature) ||
+        b.members.length - a.members.length ||
+        a.signature.localeCompare(b.signature));
     return clusters;
 }
 /**
@@ -235,6 +353,54 @@ export function buildRelatednessClusters(entries, opts) {
 export function capClusters(ranked, maxClustersPerRun) {
     return ranked.slice(0, Math.max(0, maxClustersPerRun));
 }
+/**
+ * #632 — pick the per-run PROCESSED slice from the full ranked list, BLENDING
+ * entity and tag clusters so neither starves the other:
+ *
+ *   - No entity clusters → top `maxClustersPerRun` TAG clusters (a tags-only
+ *     stash is byte-identical to {@link capClusters}).
+ *   - Entity clusters present → ENTITIES LEAD the budget (the higher-signal key —
+ *     an extracted subject vs an auto-tokenized filename tag), but RESERVE up to
+ *     `RESERVED_TAG_SLOTS` for tag clusters so tag-only topics still surface every
+ *     run. Entities are never starved below one slot when present and the budget
+ *     allows. Whichever kind is short, the other backfills, so the full budget is
+ *     always used when enough clusters exist.
+ *
+ * The reserved tag slots prefer TIGHTER tag clusters (size <= `TAG_RESERVE_SOFT_CAP`,
+ * largest-first within that band, then the over-cap buckets): a broad
+ * auto-tokenized `tag:<project>` mega-bucket is exactly the bland, low-coherence
+ * signal #632 de-emphasizes, so the reserve should not spend its protected slots
+ * on the largest tags. Entities themselves stay largest-first — an entity is a
+ * coherent subject at any size.
+ *
+ * Entities lead the returned order. The FULL pre-cap `ranked` list (not this
+ * slice) still feeds the cap-aware decay sweep (#658), so a cluster left out of
+ * the processed slice this run is NOT decayed as if it vanished.
+ */
+export function selectClustersForRun(ranked, maxClustersPerRun) {
+    const max = Math.max(0, maxClustersPerRun);
+    if (max === 0)
+        return [];
+    const entities = ranked.filter((c) => c.signature.startsWith("entity:"));
+    if (entities.length === 0)
+        return ranked.slice(0, max); // tags-only → top-N (capClusters parity)
+    const tags = ranked.filter((c) => !c.signature.startsWith("entity:"));
+    // Reserve up to RESERVED_TAG_SLOTS for tags, but never below one slot for the
+    // leading entities when the budget allows (so a small `maxClustersPerRun` does
+    // not silently invert the entity preference).
+    const reservedForTags = Math.min(tags.length, RESERVED_TAG_SLOTS, Math.max(0, max - 1));
+    const entityTake = Math.min(entities.length, max - reservedForTags);
+    const tagTake = Math.min(tags.length, max - entityTake); // tags take their reserve + any slot entities left
+    // Prefer tight tags (<= soft cap) over broad mega-buckets for the reserve.
+    const reserveTags = [...tags]
+        .sort((a, b) => {
+        const aOver = a.members.length > TAG_RESERVE_SOFT_CAP ? 1 : 0;
+        const bOver = b.members.length > TAG_RESERVE_SOFT_CAP ? 1 : 0;
+        return aOver - bOver || b.members.length - a.members.length || a.signature.localeCompare(b.signature);
+    })
+        .slice(0, tagTake);
+    return [...entities.slice(0, entityTake), ...reserveTags];
+}
 // ── Prompt + ref derivation ───────────────────────────────────────────────────
 /** Read a memory body (frontmatter stripped) for the cluster prompt. */
 function readBody(entry) {
@@ -408,8 +574,9 @@ export async function akmRecombine(opts) {
         ...(entityByEntryId ? { entityByEntryId } : {}),
         ...(opts.maxClusterSize != null ? { maxClusterSize: opts.maxClusterSize } : {}),
         ...(opts.excludeTags ? { excludeTags: opts.excludeTags } : {}),
+        ...(opts.excludeEntities ? { excludeEntities: opts.excludeEntities } : {}),
     });
-    const clusters = capClusters(rankedClusters, maxClustersPerRun);
+    const clusters = selectClustersForRun(rankedClusters, maxClustersPerRun);
     let clustersFormed = 0;
     let proposalsEmitted = 0;
     let lessonsPromoted = 0;

package/dist/core/config/config-schema.js

@@ -316,9 +316,13 @@ export const ImproveProcessConfigSchema = z
     // (generic project-wide tags). Default UNSET/[]. Only meaningful on
     // `recombine`.
     excludeTags: z.array(z.string().min(1)).optional(),
+    // #632 — recombine process: entity_norm values that must never form an
+    // entity cluster (user counterpart to the built-in generic-entity filter).
+    // Default UNSET/[]. Only meaningful on `recombine`.
+    excludeEntities: z.array(z.string().min(1)).optional(),
     // #609 — recombine process: relatedness signal used to form clusters
     // (tags | graph | both). Clustering is by relatedness, never embedding
-    // similarity. Default "tags". Only meaningful on `recombine`.
+    // similarity. Default "both" (#632). Only meaningful on `recombine`.
     relatednessSource: z.enum(["tags", "graph", "both"]).optional(),
     // #609 — recombine process: consecutive re-inductions required before a
     // hypothesis is promoted to a lesson. Default 2. Only meaningful on

package/dist/scripts/migrate-storage.js

@@ -16083,6 +16083,7 @@ var init_config_schema = __esm(() => {
     maxClustersPerRun: positiveInt.optional(),
     maxClusterSize: positiveInt.optional(),
     excludeTags: exports_external.array(exports_external.string().min(1)).optional(),
+    excludeEntities: exports_external.array(exports_external.string().min(1)).optional(),
     relatednessSource: exports_external.enum(["tags", "graph", "both"]).optional(),
     confirmThreshold: exports_external.number().int().min(1).optional(),
     minRecurrence: exports_external.number().int().min(2).optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.0-beta.43",
+  "version": "0.9.0-beta.44",
   "type": "module",
   "description": "akm (Agent Knowledge Management) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [