akm-cli 0.9.0-beta.29 → 0.9.0-beta.30

package/CHANGELOG.md

@@ -6,6 +6,25 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.0-beta.30] — 2026-06-20
+
+### Changed / Fixed
+
+- **#632 — recombine cluster tuning (opt-in, default-preserving).** Recombine
+  clustered memories by frontmatter tag and preferred the LARGEST buckets, so it
+  always picked the coarsest whole-stash tags (`session`/`claude`/`akm`, 63–171
+  members) and produced bland generalizations. Two new `processes.recombine` knobs:
+  `maxClusterSize` (skip clusters larger than N, so over-broad buckets no longer
+  reach/starve the largest-first slice) and `excludeTags` (tags that may never form
+  a tag cluster). Both UNSET = byte-identical to prior behavior.
+- **#633 — recombine confirmation loop fixed.** The hypothesis confirmation streak
+  was keyed on a hash of the EXACT member set, so a growing stash drifted the key
+  every run → a fresh row at count 1 → `confirmThreshold` never reached → no
+  hypothesis ever promoted to a lesson (a dead two-pass loop). A freshly-induced
+  cluster now matches an existing pending row by signature + Jaccard
+  membership-overlap (≥ 0.7) and reuses its stable ref, so the streak accumulates
+  through membership drift. First/non-overlapping induction is unchanged.
+
 ## [0.9.0-beta.29] — 2026-06-20
 
 ### Reverted

package/dist/commands/improve/improve.js

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

package/dist/commands/improve/recombine.js

@@ -45,7 +45,7 @@ import { resolveStashDir } from "../../core/common.js";
 import { getDefaultLlmConfig, loadConfig } from "../../core/config/config.js";
 import { appendEvent } from "../../core/events.js";
 import { parseEmbeddedJsonResponse } from "../../core/parse.js";
-import { decayUnseenRecombineHypotheses, getRecombineHypothesis, getStateDbPath, markRecombineHypothesisPromoted, openStateDatabase, recordRecombineInduction, } from "../../core/state-db.js";
+import { decayUnseenRecombineHypotheses, findMatchingRecombineHypothesis, getRecombineHypothesis, getStateDbPath, markRecombineHypothesisPromoted, openStateDatabase, recordRecombineInduction, } from "../../core/state-db.js";
 import { warn } from "../../core/warn.js";
 import { closeDatabase, getAllEntries, getEntitiesByEntryIds, openExistingDatabase, } from "../../indexer/db/db.js";
 import { resolveImproveProcessRunnerFromProfile, runnerIsLlm } from "../../integrations/agent/runner.js";
@@ -59,6 +59,13 @@ const DEFAULT_MAX_CLUSTERS_PER_RUN = 5;
 const DEFAULT_RELATEDNESS_SOURCE = "tags";
 /** #625 — re-induction count required before a hypothesis promotes to a lesson. */
 const DEFAULT_CONFIRM_THRESHOLD = 2;
+/**
+ * #633 — Jaccard membership-overlap threshold for matching a freshly-induced
+ * hypothesis to an existing pending row under the SAME signature. A growing
+ * stash drifts the exact member set every run; an overlap >= this lets the
+ * confirmation streak keep accumulating under one row instead of resetting to 1.
+ */
+const DEFAULT_RECOMBINE_OVERLAP = 0.7;
 // ── Clustering by relatedness (NOT similarity) ────────────────────────────────
 /**
  * Build relatedness clusters from the memory pool. Clustering is driven purely
@@ -99,21 +106,33 @@ 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.
+    const excludeTags = new Set(opts.excludeTags ?? []);
     for (const entry of memories) {
         if (useTags || tagsFallback) {
-            for (const tag of entry.entry.tags ?? [])
+            for (const tag of entry.entry.tags ?? []) {
+                if (excludeTags.has(tag))
+                    continue;
                 add(`tag:${tag}`, entry);
+            }
         }
         if (useGraph && opts.entityByEntryId) {
             for (const ent of opts.entityByEntryId.get(entry.id) ?? [])
                 add(`entity:${ent}`, entry);
         }
     }
-    // Keep only groups at or above the minimum cluster size.
+    // Keep only groups at or above the minimum cluster size. #632 — when
+    // maxClusterSize is set, also SKIP groups strictly larger than the cap so an
+    // over-broad bucket never reaches (and starves) the largest-first slice.
+    // UNSET = no upper bound = identical to the pre-#632 behaviour.
     let clusters = [];
     for (const [signature, members] of groups) {
-        if (members.length >= opts.minClusterSize)
-            clusters.push({ signature, members });
+        if (members.length < opts.minClusterSize)
+            continue;
+        if (opts.maxClusterSize != null && members.length > opts.maxClusterSize)
+            continue;
+        clusters.push({ signature, members });
     }
     // De-duplicate clusters that share the exact same member set (e.g. a tag and
     // an entity that co-occur on the same trio). Keep the first by signature.
@@ -295,6 +314,8 @@ export async function akmRecombine(opts) {
         maxClustersPerRun,
         relatednessSource,
         ...(entityByEntryId ? { entityByEntryId } : {}),
+        ...(opts.maxClusterSize != null ? { maxClusterSize: opts.maxClusterSize } : {}),
+        ...(opts.excludeTags ? { excludeTags: opts.excludeTags } : {}),
     });
     let clustersFormed = 0;
     let proposalsEmitted = 0;
@@ -337,7 +358,24 @@ export async function akmRecombine(opts) {
                 }, opts.ctx);
                 continue;
             }
-            const lessonRef = deriveRecombineLessonRef(cluster);
+            // #633 — the confirmation identity is decoupled from the EXACT member
+            // set. We first look for an existing pending hypothesis row under the
+            // SAME signature whose membership overlaps this cluster (Jaccard >=
+            // threshold) and, if found, REUSE that row's stable ref so a
+            // drifting-but-overlapping cluster keeps accumulating its streak under one
+            // row instead of spawning a fresh row (count=1) every run. With no match
+            // (first induction, or membership drifted past the overlap floor) we fall
+            // back to the deterministic member-set ref exactly as before.
+            const memberKey = recombineMemberKey(cluster);
+            const derivedRef = deriveRecombineLessonRef(cluster);
+            const matchedRow = stateDb
+                ? findMatchingRecombineHypothesis(stateDb, {
+                    signature: cluster.signature,
+                    memberKey,
+                    minOverlap: DEFAULT_RECOMBINE_OVERLAP,
+                })
+                : undefined;
+            const lessonRef = matchedRow?.hypothesis_ref ?? derivedRef;
             const sourceRefs = cluster.members.map((m) => `memory:${m.entry.name}`);
             // Quality gate (always-run): the frontmatter description must be present
             // and non-truncated. This runs BEFORE createProposal on BOTH the
@@ -360,9 +398,11 @@ export async function akmRecombine(opts) {
             // A defensible generalization was produced this run — record it so it is
             // NOT decayed by the unseen sweep below.
             seenThisRun.add(lessonRef);
-            // #625 — record the re-induction and read the prior promotion state. The
-            // member key and the ref hash derive from the SAME member set, so
-            // re-induction of an identical cluster maps back to the same row.
+            // #625/#633 — record the re-induction and read the prior promotion state.
+            // `lessonRef` is the matched row's ref (overlap match) or the freshly
+            // derived member-set ref (first/non-overlapping induction). The induction
+            // refreshes the row's `member_key` to the current membership so the
+            // overlap window slides with the drifting cluster.
             const nowIso = new Date().toISOString();
             const priorRow = stateDb ? getRecombineHypothesis(stateDb, lessonRef) : undefined;
             const alreadyPromoted = priorRow?.promoted_at != null;
@@ -370,7 +410,7 @@ export async function akmRecombine(opts) {
                 ? recordRecombineInduction(stateDb, {
                     hypothesisRef: lessonRef,
                     signature: cluster.signature,
-                    memberKey: recombineMemberKey(cluster),
+                    memberKey,
                     seenAt: nowIso,
                     run: sourceRun,
                 })

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

@@ -302,6 +302,15 @@ export const ImproveProcessConfigSchema = z
     // #609 — recombine process: hard cap on clusters processed per run (one
     // bounded LLM call each). Default 5. Only meaningful on `recombine`.
     maxClustersPerRun: positiveInt.optional(),
+    // #632 — recombine process: max members a cluster may contain before it is
+    // SKIPPED (drops bland over-broad buckets). When set, largest-first ranking
+    // no longer starves tighter clusters. Default UNSET = no cap. Only
+    // meaningful on `recombine`.
+    maxClusterSize: positiveInt.optional(),
+    // #632 — recombine process: tag values that must never form a tag cluster
+    // (generic project-wide tags). Default UNSET/[]. Only meaningful on
+    // `recombine`.
+    excludeTags: 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`.

package/dist/core/state-db.js

@@ -1599,6 +1599,54 @@ export function recordRecombineInduction(db, input) {
         .get(input.hypothesisRef, input.signature, input.memberKey, input.seenAt, input.seenAt, input.run);
     return row?.consecutive_count ?? 0;
 }
+/**
+ * #633 — find an existing pending (non-promoted) hypothesis row whose cluster
+ * is the SAME generalization as a newly-induced one, matched by SIGNATURE plus
+ * a Jaccard membership-overlap test, rather than an exact member-set hash.
+ *
+ * In a growing stash any added/removed memory changes the exact member set, so
+ * the ref hash (and member_key) shift every run → a fresh row at count=1 → the
+ * streak never reaches `confirmThreshold` and nothing ever promotes. Matching
+ * on overlap lets a drifting-but-stable cluster keep accumulating under one row.
+ *
+ * Returns the matched row with the HIGHEST overlap (ties broken by most-recent
+ * `last_seen_at`), or `undefined` when none clears `minOverlap`. Already-promoted
+ * rows are ignored so a confirmed lesson is not reopened by a later induction.
+ *
+ * @param memberKey  the candidate cluster's membership fingerprint
+ *                   (sorted member entryKeys joined by `|`).
+ * @param minOverlap Jaccard threshold in [0,1]; a candidate matches when
+ *                   |A∩B| / |A∪B| >= minOverlap.
+ */
+export function findMatchingRecombineHypothesis(db, input) {
+    const candidateMembers = new Set(input.memberKey.split("|").filter((m) => m.length > 0));
+    if (candidateMembers.size === 0)
+        return undefined;
+    const rows = db
+        .prepare("SELECT * FROM recombine_hypotheses WHERE signature = ? AND promoted_at IS NULL ORDER BY last_seen_at DESC")
+        .all(input.signature);
+    let best;
+    let bestOverlap = -1;
+    for (const row of rows) {
+        const rowMembers = row.member_key.split("|").filter((m) => m.length > 0);
+        if (rowMembers.length === 0)
+            continue;
+        let intersection = 0;
+        for (const m of rowMembers) {
+            if (candidateMembers.has(m))
+                intersection += 1;
+        }
+        const union = candidateMembers.size + rowMembers.length - intersection;
+        const overlap = union === 0 ? 0 : intersection / union;
+        // rows are ordered last_seen_at DESC, so a strict `>` keeps the most-recent
+        // row on ties.
+        if (overlap >= input.minOverlap && overlap > bestOverlap) {
+            best = row;
+            bestOverlap = overlap;
+        }
+    }
+    return best;
+}
 /**
  * Fetch a single recombine hypothesis row, or `undefined` when the ref has
  * never been induced. Normalizes bun:sqlite null → undefined like

package/dist/scripts/migrate-storage.js

@@ -9002,6 +9002,7 @@ __export(exports_state_db, {
   getExtractedSession: () => getExtractedSession,
   getConsolidationJudgedMap: () => getConsolidationJudgedMap,
   getBodyEmbeddings: () => getBodyEmbeddings,
+  findMatchingRecombineHypothesis: () => findMatchingRecombineHypothesis,
   eventRowToEnvelope: () => eventRowToEnvelope,
   embeddingToBlob: () => embeddingToBlob,
   decayUnseenRecombineHypotheses: () => decayUnseenRecombineHypotheses,
@@ -9479,6 +9480,31 @@ function recordRecombineInduction(db, input) {
     `).get(input.hypothesisRef, input.signature, input.memberKey, input.seenAt, input.seenAt, input.run);
   return row?.consecutive_count ?? 0;
 }
+function findMatchingRecombineHypothesis(db, input) {
+  const candidateMembers = new Set(input.memberKey.split("|").filter((m) => m.length > 0));
+  if (candidateMembers.size === 0)
+    return;
+  const rows = db.prepare("SELECT * FROM recombine_hypotheses WHERE signature = ? AND promoted_at IS NULL ORDER BY last_seen_at DESC").all(input.signature);
+  let best;
+  let bestOverlap = -1;
+  for (const row of rows) {
+    const rowMembers = row.member_key.split("|").filter((m) => m.length > 0);
+    if (rowMembers.length === 0)
+      continue;
+    let intersection = 0;
+    for (const m of rowMembers) {
+      if (candidateMembers.has(m))
+        intersection += 1;
+    }
+    const union = candidateMembers.size + rowMembers.length - intersection;
+    const overlap = union === 0 ? 0 : intersection / union;
+    if (overlap >= input.minOverlap && overlap > bestOverlap) {
+      best = row;
+      bestOverlap = overlap;
+    }
+  }
+  return best;
+}
 function getRecombineHypothesis(db, hypothesisRef) {
   const row = db.prepare("SELECT * FROM recombine_hypotheses WHERE hypothesis_ref = ?").get(hypothesisRef);
   return row ?? undefined;
@@ -15887,6 +15913,8 @@ var init_config_schema = __esm(() => {
     }).strict().optional(),
     minClusterSize: exports_external.number().int().min(2).optional(),
     maxClustersPerRun: positiveInt.optional(),
+    maxClusterSize: positiveInt.optional(),
+    excludeTags: 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.29",
+  "version": "0.9.0-beta.30",
   "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": [