@agenr/agenr-plugin 1.6.0 → 1.7.0

package/dist/index.js

@@ -7156,6 +7156,12 @@ function createNoopRecallTraceSink() {
 
 // ../../src/core/recall/search.ts
 var MIN_VECTOR_ONLY_EVIDENCE = 0.3;
+var HISTORICAL_STATE_FLAT_RECENCY = 0.5;
+var HISTORICAL_PREDECESSOR_BOOST = 0.08;
+var HISTORICAL_RETIRED_PREDECESSOR_BOOST = 0.06;
+var HISTORICAL_OLDER_STATE_BOOST = 0.08;
+var HISTORICAL_TOPIC_SHARED_PREFIX_MIN = 2;
+var HISTORICAL_TOPIC_PREFIX_OF_CANDIDATE_MIN = 0.6;
 async function recall(query, ports, options = {}) {
   const text = query.text.trim();
   const limit = normalizeLimit(query.limit);
@@ -7207,10 +7213,26 @@ async function recall(query, ports, options = {}) {
     ]);
     const mergeStartedAt = Date.now();
     const mergedCandidates = mergeCandidates(vectorCandidates, ftsCandidates);
+    await expandHistoricalCandidates(mergedCandidates, queryEmbedding, ports, {
+      activeEntryIds: Array.from(mergedCandidates.keys()),
+      rankingProfile: query.rankingProfile
+    });
     summary.candidateCounts.merged = mergedCandidates.size;
     summary.timings.mergeCandidatesMs = elapsedMs(mergeStartedAt);
     const scoreStartedAt = Date.now();
-    const scored = Array.from(mergedCandidates.values()).map((candidate) => scoreMergedCandidate(candidate, text, queryEmbedding, aroundDate, query.aroundRadius)).sort((left, right) => right.score - left.score);
+    const scored = applyHistoricalLineageBoosts(
+      Array.from(mergedCandidates.values()).map(
+        (candidate) => scoreMergedCandidate(candidate, text, queryEmbedding, {
+          aroundDate,
+          aroundRadius: query.aroundRadius,
+          rankingProfile: query.rankingProfile
+        })
+      ),
+      {
+        aroundDate,
+        rankingProfile: query.rankingProfile
+      }
+    ).sort((left, right) => right.score - left.score);
     summary.timings.scoreCandidatesMs = elapsedMs(scoreStartedAt);
     const thresholdStartedAt = Date.now();
     const thresholded = scored.filter((result) => hasSufficientReturnEvidence(result) && result.score >= threshold);
@@ -7306,10 +7328,10 @@ function finishRecallTrace(summary, trace, noResultReason) {
   }
   trace.reportSummary(summary);
 }
-function scoreMergedCandidate(candidate, queryText, queryEmbedding, aroundDate, aroundRadius) {
+function scoreMergedCandidate(candidate, queryText, queryEmbedding, params) {
   const vector = candidate.vectorSim ?? cosineSimilarity(candidate.entry.embedding ?? [], queryEmbedding);
   const lexical = computeLexicalScore(queryText, candidate.entry.subject, candidate.entry.content);
-  const recency = aroundDate ? gaussianRecency(candidate.entry.created_at, aroundDate, normalizeAroundRadius(aroundRadius)) : recencyScore(candidate.entry.created_at, candidate.entry.expiry);
+  const recency = resolveRecencyScore(candidate.entry, params);
   const importance = importanceScore(candidate.entry.importance);
   const scored = scoreCandidate({
     vectorSim: vector,
@@ -7323,6 +7345,97 @@ function scoreMergedCandidate(candidate, queryText, queryEmbedding, aroundDate,
     scores: scored.scores
   };
 }
+async function expandHistoricalCandidates(mergedCandidates, queryEmbedding, ports, params) {
+  if (params.rankingProfile !== "historical_state" || mergedCandidates.size === 0 || !ports.fetchPredecessors) {
+    return;
+  }
+  const predecessors = await ports.fetchPredecessors({
+    activeEntryIds: params.activeEntryIds
+  });
+  for (const entry of predecessors) {
+    if (mergedCandidates.has(entry.id)) {
+      continue;
+    }
+    mergedCandidates.set(entry.id, {
+      entry,
+      vectorSim: cosineSimilarity(entry.embedding ?? [], queryEmbedding)
+    });
+  }
+}
+function resolveRecencyScore(entry, params) {
+  if (params.aroundDate) {
+    return gaussianRecency(entry.created_at, params.aroundDate, normalizeAroundRadius(params.aroundRadius));
+  }
+  if (params.rankingProfile === "historical_state") {
+    return HISTORICAL_STATE_FLAT_RECENCY;
+  }
+  return recencyScore(entry.created_at, entry.expiry);
+}
+function applyHistoricalLineageBoosts(candidates, params) {
+  if (params.rankingProfile !== "historical_state") {
+    return candidates;
+  }
+  const entries = candidates.map((candidate) => candidate.entry);
+  return candidates.map((candidate) => {
+    const bonus = resolveHistoricalLineageBonus(candidate.entry, entries, params.aroundDate);
+    if (bonus <= 0) {
+      return candidate;
+    }
+    return {
+      ...candidate,
+      score: Math.min(1, candidate.score + bonus)
+    };
+  });
+}
+function resolveHistoricalLineageBonus(entry, entries, aroundDate) {
+  if (entries.some((peer) => peer.id !== entry.id && entry.superseded_by === peer.id)) {
+    return HISTORICAL_PREDECESSOR_BOOST;
+  }
+  if (aroundDate) {
+    return 0;
+  }
+  const activePeers = entries.filter((peer) => peer.id !== entry.id && isPotentialCurrentPeer(peer) && isOlderHistoricalPeer(entry, peer));
+  if (activePeers.length === 0) {
+    return 0;
+  }
+  return entry.retired ? HISTORICAL_RETIRED_PREDECESSOR_BOOST : HISTORICAL_OLDER_STATE_BOOST;
+}
+function isPotentialCurrentPeer(entry) {
+  return !entry.retired && entry.superseded_by === void 0;
+}
+function isOlderHistoricalPeer(left, right) {
+  return createdAtMs(left.created_at) < createdAtMs(right.created_at) && sharesHistoricalLineage(left, right);
+}
+function sharesHistoricalLineage(left, right) {
+  if (left.claim_key && right.claim_key && left.claim_key === right.claim_key) {
+    return true;
+  }
+  return sharesHistoricalTopic(left, right);
+}
+function sharesHistoricalTopic(left, right) {
+  const leftTokens = tokenize(left.subject);
+  const rightTokens = tokenize(right.subject);
+  if (leftTokens.length === 0 || rightTokens.length === 0) {
+    return false;
+  }
+  const sharedPrefixCount = countSharedPrefixTokens(leftTokens, rightTokens);
+  return sharedPrefixCount >= HISTORICAL_TOPIC_SHARED_PREFIX_MIN && sharedPrefixCount / leftTokens.length >= HISTORICAL_TOPIC_PREFIX_OF_CANDIDATE_MIN;
+}
+function createdAtMs(value) {
+  const timestamp = new Date(value).getTime();
+  return Number.isFinite(timestamp) ? timestamp : 0;
+}
+function countSharedPrefixTokens(leftTokens, rightTokens) {
+  const length = Math.min(leftTokens.length, rightTokens.length);
+  let sharedPrefixCount = 0;
+  for (let index = 0; index < length; index += 1) {
+    if (leftTokens[index] !== rightTokens[index]) {
+      break;
+    }
+    sharedPrefixCount += 1;
+  }
+  return sharedPrefixCount;
+}
 function hasSufficientReturnEvidence(candidate) {
   if (candidate.scores.lexical > 0) {
     return true;
@@ -7972,12 +8085,36 @@ var EPISODE_FRESHNESS_NOTICE = "Episodes cover consolidated prior sessions only;
 var EPISODE_SEMANTIC_FALLBACK_NOTICE = "Semantic episode search unavailable - showing temporal results only.";
 var EPISODE_SEMANTIC_UNAVAILABLE_NOTICE = "Semantic episode search unavailable - no semantic episode results could be returned.";
 var ENTRY_FILTER_NOTICE = "Threshold, type filters, and tag filters were applied to entries only.";
+var HISTORICAL_STATE_PATTERNS = [
+  "what was the previous",
+  "what was the earlier",
+  "what did we use before",
+  "what was the old",
+  "what changed",
+  "changed from",
+  "replaced by",
+  "before we switched",
+  "before we migrated",
+  "previous approach",
+  "earlier plan",
+  "old workflow"
+];
+var HISTORICAL_STATE_REGEX_PATTERNS = [
+  /\bwhat\b.*\bused?\b.*\bbefore\b/u,
+  /\bwhat\b.*\bworkflow\b.*\bbefore\b/u,
+  /\bwhat\b.*\bplan\b.*\bearlier\b/u,
+  /\bwhat\b.*\bplan\b.*\bbefore\b/u
+];
 async function runUnifiedRecall(input, deps) {
   const now = deps.now ?? /* @__PURE__ */ new Date();
   const requested = normalizeMode(input.mode);
   const parsedTimeWindow = parseTemporalWindow(input.text, now);
   const hasEntryFilters = hasEntryScopedFilters(input);
   const topicAnchor = hasTopicAnchor(input.text, hasEntryFilters);
+  const historicalStatePattern = detectHistoricalStatePattern(input.text);
+  if (historicalStatePattern) {
+    deps.debugLog?.(`[agenr] unified recall matched historical-state pattern=${JSON.stringify(historicalStatePattern)} query=${JSON.stringify(input.text)}`);
+  }
   const routing = routeRecall({
     requested,
     text: input.text,
@@ -7989,6 +8126,7 @@ async function runUnifiedRecall(input, deps) {
     text: input.text,
     limit: input.limit,
     requested,
+    detectedIntent: routing.detectedIntent,
     parsedTimeWindow,
     topicAnchor,
     embedQuery: deps.embedQuery
@@ -8033,11 +8171,12 @@ function routeRecall(params) {
   const lower = params.text.trim().toLowerCase();
   const factual = /^(when did|when was|what decision|what preference|what(?:'s| is) the default|which version|what threshold)\b/.test(lower);
   const narrative = /\b(what happened|what were we doing|what was going on|summarize|catch me up)\b/.test(lower);
+  const historicalState = detectHistoricalStatePattern(params.text) !== void 0;
   const topicAnchor = hasTopicAnchor(params.text, params.hasEntryFilters);
   if (params.requested === "entries") {
     return {
       requested: params.requested,
-      detectedIntent: factual ? "factual" : params.parsedTimeWindow ? "mixed" : "factual",
+      detectedIntent: historicalState ? "historical_state" : factual ? "factual" : params.parsedTimeWindow ? "mixed" : "factual",
       queried: ["entries"],
       reason: "Explicit mode=entries override."
     };
@@ -8045,11 +8184,19 @@ function routeRecall(params) {
   if (params.requested === "episodes") {
     return {
       requested: params.requested,
-      detectedIntent: params.parsedTimeWindow ? "temporal_narrative" : "mixed",
+      detectedIntent: historicalState ? "historical_state" : params.parsedTimeWindow ? "temporal_narrative" : "mixed",
       queried: ["episodes"],
       reason: params.parsedTimeWindow ? "Explicit mode=episodes override with a resolved time window." : "Explicit mode=episodes override without a resolved time window."
     };
   }
+  if (historicalState) {
+    return {
+      requested: params.requested,
+      detectedIntent: "historical_state",
+      queried: ["entries", "episodes"],
+      reason: params.parsedTimeWindow ? "The query asks about a previous state or transition and includes a supported time expression, so both entries and episodes were queried." : "The query asks about a previous state or transition, so both entries and episodes were queried."
+    };
+  }
   if (factual && params.parsedTimeWindow) {
     return {
       requested: params.requested,
@@ -8099,7 +8246,7 @@ function routeRecall(params) {
 }
 async function buildEpisodeQueryPlan(params) {
   const notices = [];
-  const shouldUseSemantic = params.parsedTimeWindow ? params.topicAnchor : params.requested === "episodes";
+  const shouldUseSemantic = params.detectedIntent === "historical_state" || (params.parsedTimeWindow ? params.topicAnchor : params.requested === "episodes");
   let embedding;
   if (shouldUseSemantic) {
     embedding = await maybeEmbedEpisodeQuery(params.text, params.embedQuery);
@@ -8141,17 +8288,18 @@ async function maybeRunEntryRecall(params) {
   }
   return {
     kind: "results",
-    results: await recall(buildEntryRecallInput(params.input, params.parsedTimeWindow), params.deps.recall)
+    results: await recall(buildEntryRecallInput(params.input, params.parsedTimeWindow, params.routing), params.deps.recall, params.deps.recallOptions)
   };
 }
-function buildEntryRecallInput(input, parsedTimeWindow) {
+function buildEntryRecallInput(input, parsedTimeWindow, routing) {
   const request = {
     text: input.text,
     ...input.limit !== void 0 ? { limit: input.limit } : {},
     ...input.threshold !== void 0 ? { threshold: input.threshold } : {},
     ...input.types && input.types.length > 0 ? { types: input.types } : {},
     ...input.tags && input.tags.length > 0 ? { tags: input.tags } : {},
-    ...input.sessionKey ? { sessionKey: input.sessionKey } : {}
+    ...input.sessionKey ? { sessionKey: input.sessionKey } : {},
+    ...routing.detectedIntent === "historical_state" ? { rankingProfile: "historical_state" } : {}
   };
   if (!parsedTimeWindow) {
     return request;
@@ -8168,6 +8316,15 @@ function buildEntryRecallInput(input, parsedTimeWindow) {
     aroundRadius: radiusDays
   };
 }
+function detectHistoricalStatePattern(text) {
+  const lower = text.trim().toLowerCase();
+  const explicitPattern = HISTORICAL_STATE_PATTERNS.find((pattern) => lower.includes(pattern));
+  if (explicitPattern) {
+    return explicitPattern;
+  }
+  const regexPattern = HISTORICAL_STATE_REGEX_PATTERNS.find((pattern) => pattern.test(lower));
+  return regexPattern?.source;
+}
 function normalizeMode(value) {
   return value === "entries" || value === "episodes" ? value : "auto";
 }
@@ -8209,7 +8366,7 @@ var EPISODE_ACTIVITY_LEVELS = ["substantial", "minimal", "none"];
 
 // ../../src/adapters/openclaw/tools/shared.ts
 import { failedTextResult, readStringParam } from "openclaw/plugin-sdk/agent-runtime";
-var ENTRY_TYPE_DESCRIPTION = "Knowledge type to store. Use fact for durable information about people, places, systems, or how things work. Use decision for standing rules, constraints, or chosen approaches. Use preference for stated wants, values, or opinions. Use lesson for non-obvious insights learned from specific experience. Use milestone for notable one-time events worth remembering (a move, a launch, a life change, a hire, a trip). Use relationship for meaningful connections between people, groups, or systems.";
+var ENTRY_TYPE_DESCRIPTION = "Knowledge type to store. Use fact for durable truth about a person, system, place, or how something works. Use decision for a standing rule, constraint, policy, or chosen approach future sessions should follow - not a progress update or completed action. Use preference for what someone likes, wants, values, or wants avoided. Use lesson for a non-obvious takeaway learned from experience that should change future behavior. Use milestone for a rare one-time event with durable future significance - not ordinary execution progress. Use relationship for a meaningful durable connection between people, groups, or systems.";
 var EXPIRY_DESCRIPTION = "Lifetime bucket: core (always injected at session start, use sparingly), permanent (durable and recalled on demand), or temporary (short-horizon).";
 var UPDATE_EXPIRY_DESCRIPTION = `${EXPIRY_DESCRIPTION} Accepted values: ${EXPIRY_LEVELS.join(", ")}.`;
 var DEFAULT_RECALL_LIMIT = 10;
@@ -8388,29 +8545,15 @@ function formatUnifiedRecallResults(result) {
     lines.push(`${result.timeWindow.start} -> ${result.timeWindow.end} (${result.timeWindow.timezone}) from ${JSON.stringify(result.timeWindow.resolvedFrom)}`);
     lines.push("");
   }
-  lines.push("Episode Matches");
-  if (result.episodes.length === 0) {
-    lines.push("None.");
-  } else {
-    for (const [index, episode] of result.episodes.entries()) {
-      lines.push(
-        `${index + 1}. ${episode.episode.id} | ${episode.episode.source} | ${episode.episode.startedAt} -> ${episode.episode.endedAt ?? episode.episode.startedAt} | score ${episode.score.toFixed(2)}`
-      );
-      lines.push(`   ${index < 3 ? episode.episode.summary.trim() : truncate(episode.episode.summary.trim(), 220)}`);
-      lines.push(`   why_matched=${describeEpisodeMatch(episode)}`);
-    }
-  }
-  lines.push("");
-  lines.push("Entry Matches");
-  if (result.entries.length === 0) {
-    lines.push("None.");
+  const renderEntriesFirst = result.routing.detectedIntent === "historical_state";
+  if (renderEntriesFirst) {
+    appendEntryMatches(lines, result);
+    lines.push("");
+    appendEpisodeMatches(lines, result);
   } else {
-    for (const [index, entry] of result.entries.entries()) {
-      lines.push(
-        `${index + 1}. ${entry.entry.id} | ${entry.entry.type} | ${entry.entry.subject} | score ${entry.score.toFixed(2)} | importance ${entry.entry.importance}`
-      );
-      lines.push(`   ${truncate(entry.entry.content, 220)}`);
-    }
+    appendEpisodeMatches(lines, result);
+    lines.push("");
+    appendEntryMatches(lines, result);
   }
   if (result.notices.length > 0) {
     lines.push("");
@@ -8421,6 +8564,33 @@ function formatUnifiedRecallResults(result) {
   }
   return lines.join("\n");
 }
+function appendEntryMatches(lines, result) {
+  lines.push("Entry Matches");
+  if (result.entries.length === 0) {
+    lines.push("None.");
+    return;
+  }
+  for (const [index, entry] of result.entries.entries()) {
+    lines.push(
+      `${index + 1}. ${entry.entry.id} | ${entry.entry.type} | ${entry.entry.subject} | score ${entry.score.toFixed(2)} | importance ${entry.entry.importance}`
+    );
+    lines.push(`   ${truncate(entry.entry.content, 220)}`);
+  }
+}
+function appendEpisodeMatches(lines, result) {
+  lines.push("Episode Matches");
+  if (result.episodes.length === 0) {
+    lines.push("None.");
+    return;
+  }
+  for (const [index, episode] of result.episodes.entries()) {
+    lines.push(
+      `${index + 1}. ${episode.episode.id} | ${episode.episode.source} | ${episode.episode.startedAt} -> ${episode.episode.endedAt ?? episode.episode.startedAt} | score ${episode.score.toFixed(2)}`
+    );
+    lines.push(`   ${index < 3 ? episode.episode.summary.trim() : truncate(episode.episode.summary.trim(), 220)}`);
+    lines.push(`   why_matched=${describeEpisodeMatch(episode)}`);
+  }
+}
 function formatUnifiedRecallLogSummary(result) {
   const entrySubjects = result.entries.map((entry) => entry.entry.subject.trim()).filter((subject) => subject.length > 0);
   const displayed = entrySubjects.slice(0, RESULT_SUBJECT_LOG_LIMIT).map((subject) => JSON.stringify(truncate(subject, 80)));
@@ -8513,12 +8683,12 @@ var RECALL_TOOL_PARAMETERS = {
   properties: {
     query: {
       type: "string",
-      description: "What you need to remember. Use a focused natural-language query rather than a broad 'everything' search."
+      description: "What you need to remember. Use a focused natural-language query rather than a broad 'everything' search. Phrase prior-state asks directly, for example 'what was the previous approach' or 'what changed from X to Y'."
     },
     mode: {
       type: "string",
       enum: [...RECALL_MODES],
-      description: "Recall mode: auto routes between entries and episodes, entries forces semantic recall, and episodes forces temporal session recall."
+      description: "Recall mode: auto routes between exact entry recall, historical-state recall, and episodes; entries forces semantic recall; episodes forces temporal or semantic session recall."
     },
     limit: {
       type: "integer",
@@ -8552,7 +8722,7 @@ function createAgenrRecallTool(ctx, servicesPromise, logger) {
   return {
     name: "agenr_recall",
     label: "Agenr Recall",
-    description: "Retrieve knowledge from agenr long-term memory. Use mode=auto for the normal path, mode=entries for exact facts and decisions, and mode=episodes for time-bounded 'what happened' questions. Time periods are parsed from the query text. Session-start recall is already handled automatically.",
+    description: "Retrieve knowledge from agenr long-term memory. Use mode=auto for the normal path, including historical-state questions like what was the previous approach or what changed from X to Y; use mode=entries for exact facts and decisions; use mode=episodes for time-bounded 'what happened' questions. Time periods are parsed from the query text. Session-start recall is already handled automatically.",
     parameters: RECALL_TOOL_PARAMETERS,
     async execute(_toolCallId, rawParams) {
       try {
@@ -8598,6 +8768,9 @@ function createAgenrRecallTool(ctx, servicesPromise, logger) {
           recall: services.recall,
           embeddingAvailable: services.embeddingStatus.available,
           embeddingError: services.embeddingStatus.error,
+          debugLog: (message) => {
+            logger.debug?.(message);
+          },
           embedQuery: services.embeddingStatus.available ? async (text) => {
             const vectors = await services.embedding.embed([text]);
             return vectors[0] ?? [];
@@ -8710,52 +8883,655 @@ import { failedTextResult as failedTextResult3, readNumberParam as readNumberPar
 // ../../src/core/store/pipeline.ts
 import { randomUUID } from "crypto";
 
-// ../../src/core/store/claim-extraction.ts
-var SELF_REFERENTIAL_ENTITIES = /* @__PURE__ */ new Set(["i", "me", "the_user", "myself", "user", "we", "our_team", "the_project", "this_project"]);
-async function extractClaimKey(entry, entityHints, llm, config) {
-  if (!config.enabled || !config.eligibleTypes.includes(entry.type)) {
+// ../../src/core/supersession.ts
+function validateSupersessionRules(oldEntry, newEntry) {
+  if (oldEntry.type !== newEntry.type) {
+    return {
+      ok: false,
+      reason: "type_mismatch"
+    };
+  }
+  if (oldEntry.type === "milestone") {
+    return {
+      ok: false,
+      reason: "milestone"
+    };
+  }
+  if (oldEntry.expiry === "core") {
+    return {
+      ok: false,
+      reason: "core_expiry"
+    };
+  }
+  return {
+    ok: true
+  };
+}
+function describeSupersessionRuleFailure(reason) {
+  switch (reason) {
+    case "type_mismatch":
+      return "Supersession requires both entries to have the same type.";
+    case "milestone":
+      return "Milestone entries are never superseded automatically.";
+    case "core_expiry":
+      return "Core-expiry entries are never superseded automatically.";
+  }
+}
+
+// ../../src/core/claim-key.ts
+var UNKNOWN_SEGMENT = "unknown";
+var SELF_REFERENTIAL_ENTITIES = /* @__PURE__ */ new Set(["i", "me", "myself", "the_user", "user", "we", "our_team", "the_project", "this_project"]);
+var GENERIC_ATTRIBUTES = /* @__PURE__ */ new Set(["info", "details", "config", "stuff", "thing", "data"]);
+var COMPACTION_RELATION_TOKENS = /* @__PURE__ */ new Set([
+  "after",
+  "before",
+  "depend",
+  "depends",
+  "follows",
+  "follow",
+  "keep",
+  "keeps",
+  "maintain",
+  "maintains",
+  "need",
+  "needs",
+  "precede",
+  "precedes",
+  "preserve",
+  "preserves",
+  "require",
+  "required",
+  "requires",
+  "retain",
+  "retains"
+]);
+var COMPACTION_BREAK_TOKENS = /* @__PURE__ */ new Set(["about", "across", "and", "between", "during", "for", "from", "into", "onto", "or", "to", "with"]);
+var COMPACTION_WEAK_LEADING_TOKENS = /* @__PURE__ */ new Set(["actual", "authoritative", "canonical", "concrete", "current", "durable", "existing", "real"]);
+var ACTION_CONDITION_TOKENS = /* @__PURE__ */ new Set(["activate", "activation", "apply", "fire", "launch", "run", "start", "trigger"]);
+var TRAILING_OBJECT_COMPACTION_PREPOSITIONS = /* @__PURE__ */ new Set(["about", "for", "from", "into", "onto", "to", "with"]);
+var TRAILING_OBJECT_TRANSFER_HEADS = /* @__PURE__ */ new Set([
+  "access",
+  "boundary",
+  "condition",
+  "contract",
+  "guide",
+  "path",
+  "policy",
+  "preference",
+  "process",
+  "rule",
+  "schedule",
+  "support",
+  "surface",
+  "window",
+  "workflow"
+]);
+var STABLE_ATTRIBUTE_HEADS = /* @__PURE__ */ new Set([
+  "access",
+  "boundary",
+  "condition",
+  "contract",
+  "default",
+  "dependency",
+  "guide",
+  "mode",
+  "order",
+  "path",
+  "policy",
+  "preference",
+  "preservation",
+  "process",
+  "requirement",
+  "rule",
+  "schedule",
+  "setting",
+  "status",
+  "strategy",
+  "support",
+  "surface",
+  "timezone",
+  "truth",
+  "version",
+  "window",
+  "workflow"
+]);
+function normalizeClaimKeySegment(value) {
+  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
+}
+function normalizeClaimKey(value) {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    return { ok: false, reason: "empty" };
+  }
+  const slashCount = Array.from(trimmed).filter((character) => character === "/").length;
+  if (slashCount === 0) {
+    return { ok: false, reason: "missing_separator" };
+  }
+  if (slashCount !== 1) {
+    return { ok: false, reason: "too_many_segments" };
+  }
+  const [rawEntity = "", rawAttribute = ""] = trimmed.split("/");
+  const entity = normalizeClaimKeySegment(rawEntity);
+  if (entity.length === 0) {
+    return { ok: false, reason: "empty_entity" };
+  }
+  const attribute = normalizeClaimKeySegment(rawAttribute);
+  if (attribute.length === 0) {
+    return { ok: false, reason: "empty_attribute" };
+  }
+  if (entity === UNKNOWN_SEGMENT && attribute === UNKNOWN_SEGMENT) {
+    return { ok: false, reason: "unknown_pair" };
+  }
+  return {
+    ok: true,
+    value: {
+      claimKey: `${entity}/${attribute}`,
+      entity,
+      attribute
+    }
+  };
+}
+function compactClaimKey(claimKey) {
+  const normalized = normalizeClaimKey(claimKey);
+  if (!normalized.ok) {
     return null;
   }
-  const response = await llm.completeJson(buildClaimExtractionSystemPrompt(entityHints), buildClaimExtractionUserPrompt(entry));
-  if (response.no_claim === true) {
+  let attributeTokens = normalized.value.attribute.split("_").filter((token) => token.length > 0);
+  const entityTokens = normalized.value.entity.split("_").filter((token) => token.length > 0);
+  const reasons = [];
+  if (entityTokens.length > 0 && startsWithTokens(attributeTokens, entityTokens) && attributeTokens.length > entityTokens.length) {
+    attributeTokens = attributeTokens.slice(entityTokens.length);
+    reasons.push("removed duplicated entity prefix from attribute");
+  }
+  if (entityTokens.length > 0 && attributeTokens.length > entityTokens.length + 1 && endsWithTokens(attributeTokens, entityTokens) && TRAILING_OBJECT_COMPACTION_PREPOSITIONS.has(attributeTokens[attributeTokens.length - entityTokens.length - 1] ?? "")) {
+    attributeTokens = attributeTokens.slice(0, attributeTokens.length - entityTokens.length - 1);
+    reasons.push("removed duplicated entity suffix from attribute");
+  }
+  const sourceOfTruthCompaction = compactSourceOfTruthAttribute(attributeTokens);
+  if (sourceOfTruthCompaction) {
+    attributeTokens = sourceOfTruthCompaction.attributeTokens;
+    reasons.push(sourceOfTruthCompaction.reason);
+  } else {
+    const relationCompaction = compactRelationAttribute(attributeTokens);
+    if (relationCompaction) {
+      attributeTokens = relationCompaction.attributeTokens;
+      reasons.push(relationCompaction.reason);
+    } else {
+      const trailingObjectCompaction = compactTrailingObjectAttribute(attributeTokens);
+      if (trailingObjectCompaction) {
+        attributeTokens = trailingObjectCompaction.attributeTokens;
+        reasons.push(trailingObjectCompaction.reason);
+      }
+    }
+  }
+  const attribute = attributeTokens.join("_");
+  if (attribute.length === 0) {
+    return {
+      claimKey: normalized.value.claimKey,
+      entity: normalized.value.entity,
+      attribute: normalized.value.attribute,
+      compactedFrom: null,
+      reason: null
+    };
+  }
+  const compactedClaimKey = `${normalized.value.entity}/${attribute}`;
+  return {
+    claimKey: compactedClaimKey,
+    entity: normalized.value.entity,
+    attribute,
+    compactedFrom: compactedClaimKey !== normalized.value.claimKey ? normalized.value.claimKey : null,
+    reason: reasons.length > 0 ? joinCompactionReasons(reasons) : null
+  };
+}
+function validateExtractedClaimKey(claimKey) {
+  if (SELF_REFERENTIAL_ENTITIES.has(claimKey.entity)) {
+    return {
+      ok: false,
+      reason: "self_referential_entity",
+      value: claimKey
+    };
+  }
+  if (GENERIC_ATTRIBUTES.has(claimKey.attribute)) {
+    return {
+      ok: false,
+      reason: "generic_attribute",
+      value: claimKey
+    };
+  }
+  if (isValueShapedAttribute(claimKey.attribute)) {
+    return {
+      ok: false,
+      reason: "value_shaped_attribute",
+      value: claimKey
+    };
+  }
+  return {
+    ok: true,
+    value: claimKey
+  };
+}
+function describeClaimKeyNormalizationFailure(reason) {
+  switch (reason) {
+    case "empty":
+      return "claim key was empty";
+    case "missing_separator":
+      return "claim key must contain exactly one '/'";
+    case "too_many_segments":
+      return "claim key must contain exactly one '/'";
+    case "empty_entity":
+      return "claim key entity was empty after normalization";
+    case "empty_attribute":
+      return "claim key attribute was empty after normalization";
+    case "unknown_pair":
+      return 'claim key "unknown/unknown" is not allowed';
+  }
+}
+function describeExtractedClaimKeyRejection(reason, claimKey) {
+  switch (reason) {
+    case "self_referential_entity":
+      return `entity "${claimKey.entity}" is self-referential`;
+    case "generic_attribute":
+      return `attribute "${claimKey.attribute}" is too generic`;
+    case "value_shaped_attribute":
+      return `attribute "${claimKey.attribute}" looks value-shaped`;
+  }
+}
+function isValueShapedAttribute(attribute) {
+  return /^\d+(?:_\d+)*$/u.test(attribute) || /^v\d+(?:_\d+)*$/u.test(attribute);
+}
+function compactSourceOfTruthAttribute(attributeTokens) {
+  const sourceOfTruthIndex = findSourceOfTruthPhraseIndex(attributeTokens);
+  if (sourceOfTruthIndex === -1) {
     return null;
   }
-  const confidence = normalizeConfidence(response.confidence);
-  if (confidence < config.confidenceThreshold) {
+  const normalizedPhrase = ["source", "of", "truth"];
+  if (attributeTokens.length === normalizedPhrase.length && startsWithTokens(attributeTokens, normalizedPhrase)) {
     return null;
   }
-  const rawEntity = typeof response.entity === "string" ? response.entity.trim() : "";
-  const rawAttribute = typeof response.attribute === "string" ? response.attribute.trim() : "";
-  const entity = normalizeEntity(rawEntity, entityHints);
-  const attribute = normalizeClaimKeyPart(rawAttribute);
-  if (!entity || !attribute) {
+  const before = attributeTokens.slice(0, sourceOfTruthIndex);
+  const after = attributeTokens.slice(sourceOfTruthIndex + normalizedPhrase.length);
+  const leadingAllowed = before.every((token) => COMPACTION_WEAK_LEADING_TOKENS.has(token));
+  const hasMixedStableFamily = before.some((token) => STABLE_ATTRIBUTE_HEADS.has(token)) || after.some((token) => STABLE_ATTRIBUTE_HEADS.has(token));
+  const hasConjunctionNoise = before.includes("and") || before.includes("or") || after.includes("and") || after.includes("or");
+  if (!leadingAllowed || hasMixedStableFamily || hasConjunctionNoise) {
     return null;
   }
   return {
-    claimKey: `${entity}/${attribute}`,
-    confidence,
-    rawEntity,
-    rawAttribute
+    attributeTokens: normalizedPhrase,
+    reason: "collapsed source-of-truth phrasing into the stable canonical slot"
+  };
+}
+function compactRelationAttribute(attributeTokens) {
+  const relationIndex = attributeTokens.findIndex((token) => COMPACTION_RELATION_TOKENS.has(token));
+  if (relationIndex === -1) {
+    return null;
+  }
+  const relation = attributeTokens[relationIndex] ?? "";
+  const left = attributeTokens.slice(0, relationIndex);
+  const right = attributeTokens.slice(relationIndex + 1);
+  if (left.length === 0 && right.length === 0) {
+    return null;
+  }
+  if (isRequirementRelation(relation)) {
+    const conditionAction = extractConditionAction(right);
+    if (conditionAction) {
+      return {
+        attributeTokens: [conditionAction, "condition"],
+        reason: `collapsed a sentence-like ${conditionAction} requirement into a stable condition slot`
+      };
+    }
+    const requirementFocus = extractCompactionFocus(right, 2) ?? extractCompactionFocus(left, 2);
+    if (!requirementFocus) {
+      return null;
+    }
+    return {
+      attributeTokens: [...requirementFocus, "requirement"],
+      reason: "collapsed a sentence-like requirement phrase into a stable requirement slot"
+    };
+  }
+  if (isOrderingRelation(relation)) {
+    const orderingFocus = extractCompactionFocus(right, 2) ?? extractCompactionFocus(left, 2);
+    if (!orderingFocus) {
+      return null;
+    }
+    return {
+      attributeTokens: [...orderingFocus, "order"],
+      reason: "collapsed a sentence-like ordering phrase into a stable order slot"
+    };
+  }
+  if (isPreservationRelation(relation)) {
+    const preservationFocus = extractCompactionFocus(right, 2) ?? extractCompactionFocus(left, 2);
+    if (!preservationFocus) {
+      return null;
+    }
+    return {
+      attributeTokens: [...preservationFocus, "preservation"],
+      reason: "collapsed a sentence-like preservation phrase into a stable preservation slot"
+    };
+  }
+  return null;
+}
+function compactTrailingObjectAttribute(attributeTokens) {
+  const prepositionIndex = attributeTokens.findIndex((token) => TRAILING_OBJECT_COMPACTION_PREPOSITIONS.has(token));
+  if (prepositionIndex <= 0 || prepositionIndex >= attributeTokens.length - 1) {
+    return null;
+  }
+  const left = trimWeakLeadingTokens(attributeTokens.slice(0, prepositionIndex));
+  const right = attributeTokens.slice(prepositionIndex + 1);
+  if (left.length === 0 || left.length > 3 || left.includes("and") || left.includes("or") || left.some((token) => COMPACTION_RELATION_TOKENS.has(token))) {
+    return null;
+  }
+  const head = left[left.length - 1];
+  if (!head || !TRAILING_OBJECT_TRANSFER_HEADS.has(head)) {
+    return null;
+  }
+  const objectFocus = extractCompactionFocus(right, 2);
+  if (!objectFocus) {
+    return null;
+  }
+  const headCore = extractStableHeadCore(left, 2);
+  if (!headCore) {
+    return null;
+  }
+  return {
+    attributeTokens: [...objectFocus, ...headCore],
+    reason: "collapsed a trailing object phrase into a compact stable slot name"
   };
 }
+function findSourceOfTruthPhraseIndex(tokens) {
+  for (let index = 0; index <= tokens.length - 3; index += 1) {
+    if (tokens[index] === "source" && tokens[index + 1] === "of" && tokens[index + 2] === "truth") {
+      return index;
+    }
+  }
+  return -1;
+}
+function extractConditionAction(tokens) {
+  for (let index = tokens.length - 1; index >= 0; index -= 1) {
+    const token = tokens[index];
+    if (token && ACTION_CONDITION_TOKENS.has(token)) {
+      return token;
+    }
+  }
+  return null;
+}
+function extractCompactionFocus(tokens, limit) {
+  const compactable = trimWeakLeadingTokens(tokens).filter((token) => token.length > 0);
+  const segments = splitTokensOnBreaks(compactable).filter((segment) => segment.length > 0);
+  const preferredSegment = segments[0];
+  if (!preferredSegment || preferredSegment.length === 0) {
+    return null;
+  }
+  return preferredSegment.slice(0, limit);
+}
+function extractStableHeadCore(tokens, limit) {
+  const compactable = trimWeakLeadingTokens(tokens).filter((token) => token.length > 0);
+  const head = compactable[compactable.length - 1];
+  if (!head || !STABLE_ATTRIBUTE_HEADS.has(head)) {
+    return null;
+  }
+  return compactable.slice(Math.max(0, compactable.length - limit));
+}
+function splitTokensOnBreaks(tokens) {
+  const segments = [];
+  let current = [];
+  for (const token of tokens) {
+    if (COMPACTION_BREAK_TOKENS.has(token)) {
+      if (current.length > 0) {
+        segments.push(current);
+        current = [];
+      }
+      continue;
+    }
+    current.push(token);
+  }
+  if (current.length > 0) {
+    segments.push(current);
+  }
+  return segments;
+}
+function trimWeakLeadingTokens(tokens) {
+  let start = 0;
+  while (start < tokens.length && COMPACTION_WEAK_LEADING_TOKENS.has(tokens[start] ?? "")) {
+    start += 1;
+  }
+  return tokens.slice(start);
+}
+function joinCompactionReasons(reasons) {
+  if (reasons.length <= 1) {
+    return reasons[0] ?? "";
+  }
+  return `${reasons.slice(0, -1).join(", ")} and ${reasons[reasons.length - 1]}`;
+}
+function isRequirementRelation(token) {
+  return token === "depend" || token === "depends" || token === "need" || token === "needs" || token === "required" || token === "require" || token === "requires";
+}
+function isOrderingRelation(token) {
+  return token === "after" || token === "before" || token === "follow" || token === "follows" || token === "precede" || token === "precedes";
+}
+function isPreservationRelation(token) {
+  return token === "keep" || token === "keeps" || token === "maintain" || token === "maintains" || token === "preserve" || token === "preserves" || token === "retain" || token === "retains";
+}
+function startsWithTokens(tokens, prefix) {
+  return prefix.every((token, index) => tokens[index] === token);
+}
+function endsWithTokens(tokens, suffix) {
+  return suffix.every((token, index) => tokens[tokens.length - suffix.length + index] === token);
+}
+
+// ../../src/core/store/claim-extraction.ts
+var SELF_REFERENTIAL_ENTITIES2 = /* @__PURE__ */ new Set(["i", "me", "the_user", "myself", "user", "we", "our_team", "the_project", "this_project"]);
+var USER_REFERENTIAL_ENTITIES = /* @__PURE__ */ new Set(["i", "me", "myself", "the_user", "user"]);
+var PROJECT_REFERENTIAL_ENTITIES = /* @__PURE__ */ new Set(["the_project", "this_project"]);
+var DETERMINISTIC_ATTRIBUTE_HEADS = /* @__PURE__ */ new Set([
+  "budget",
+  "city",
+  "config",
+  "deadline",
+  "email",
+  "employer",
+  "language",
+  "limit",
+  "location",
+  "mode",
+  "model",
+  "name",
+  "owner",
+  "plan",
+  "policy",
+  "preference",
+  "priority",
+  "quota",
+  "region",
+  "role",
+  "schedule",
+  "setting",
+  "status",
+  "strategy",
+  "team",
+  "theme",
+  "timezone",
+  "version",
+  "window"
+]);
+var MAX_ENTITY_HINTS = 12;
+var MAX_CLAIM_KEY_EXAMPLES = 8;
+var DEFAULT_REPAIR_CONFIDENCE = 0.86;
+async function previewClaimKeyExtraction(entry, llm, config, options = {}) {
+  if (!config.enabled || !config.eligibleTypes.includes(entry.type)) {
+    return null;
+  }
+  const normalizedHints = normalizeClaimExtractionHints(options.hints ?? {});
+  let attempt;
+  try {
+    attempt = await attemptClaimExtraction(entry, normalizedHints, llm);
+  } catch (error) {
+    const repaired = tryDeterministicClaimKeyRepair(entry, normalizedHints);
+    if (repaired) {
+      return repaired;
+    }
+    throw error;
+  }
+  if (attempt.response.no_claim === true) {
+    options.onPreviewOutcome?.(buildPreviewOutcome("no_claim", attempt));
+    return null;
+  }
+  const candidate = buildClaimExtractionCandidate(entry, attempt.response, normalizedHints, options.onWarning);
+  if (candidate) {
+    options.onPreviewOutcome?.({
+      outcome: "candidate",
+      confidence: candidate.confidence,
+      rawEntity: candidate.rawEntity,
+      rawAttribute: candidate.rawAttribute,
+      path: attempt.path
+    });
+    return {
+      claimKey: candidate.claimKey,
+      confidence: candidate.confidence,
+      rawEntity: candidate.rawEntity,
+      rawAttribute: candidate.rawAttribute,
+      path: attempt.path,
+      ...candidate.compactedFrom ? {
+        compactedFrom: candidate.compactedFrom,
+        compactionReason: candidate.compactionReason
+      } : {}
+    };
+  }
+  options.onPreviewOutcome?.(buildPreviewOutcome("rejected_candidate", attempt));
+  return tryDeterministicClaimKeyRepair(entry, normalizedHints);
+}
+async function extractClaimKey(entry, llm, config, options = {}) {
+  const preview = await previewClaimKeyExtraction(entry, llm, config, options);
+  if (!preview) {
+    return null;
+  }
+  if (preview.path === "deterministic_repair" || preview.confidence >= config.confidenceThreshold) {
+    return preview;
+  }
+  const deterministicRepair = tryDeterministicClaimKeyRepair(entry, normalizeClaimExtractionHints(options.hints ?? {}));
+  if (deterministicRepair) {
+    return deterministicRepair;
+  }
+  return null;
+}
 async function getEntityHints(db) {
   return db.getDistinctClaimKeyPrefixes();
 }
-function buildClaimExtractionSystemPrompt(entityHints) {
-  const normalizedHints = Array.from(new Set(entityHints.map((entityHint) => normalizeClaimKeyPart(entityHint)).filter((entityHint) => entityHint.length > 0)));
+async function runBatchClaimExtraction(results, ports, config, _concurrency = 10, onWarning) {
+  if (!config.enabled) {
+    return /* @__PURE__ */ new Map();
+  }
+  const hintState = await loadClaimExtractionHintState(ports.db);
+  const llm = ports.createLlm();
+  const extractedEntries = /* @__PURE__ */ new Map();
+  for (const result of results) {
+    for (const entry of result.entries) {
+      if (entry.claim_key) {
+        recordClaimKeyHint(hintState, entry.claim_key);
+        continue;
+      }
+      if (!config.eligibleTypes.includes(entry.type)) {
+        continue;
+      }
+      try {
+        const extracted = await extractClaimKey(
+          {
+            type: entry.type,
+            subject: entry.subject,
+            content: entry.content
+          },
+          llm,
+          config,
+          {
+            hints: buildEntryHints(hintState, entry),
+            onWarning
+          }
+        );
+        if (extracted?.claimKey) {
+          entry.claim_key = extracted.claimKey;
+          recordClaimKeyHint(hintState, extracted.claimKey);
+          extractedEntries.set(entry, extracted);
+        }
+      } catch {
+      }
+    }
+  }
+  return extractedEntries;
+}
+function buildClaimExtractionSystemPrompt(hints, promptMode) {
+  const metadataHints = [hints.userEntity ? `user_id=${hints.userEntity}` : null, hints.projectEntity ? `project=${hints.projectEntity}` : null].filter(
+    (value) => value !== null
+  );
+  const groundingHints = [
+    hints.tags.length > 0 ? `tags=${hints.tags.join(", ")}` : null,
+    hints.sourceContext ? `source_context=${hints.sourceContext}` : null
+  ].filter((value) => value !== null);
+  const retryInstructions = promptMode === "json_retry" ? [
+    "",
+    "Your previous answer was invalid JSON.",
+    "Reply with exactly one JSON object and nothing else.",
+    "Do not use markdown fences, commentary, or trailing text."
+  ] : [];
   return [
-    "You are a knowledge entry classifier. Extract the claim key for a knowledge entry.",
-    "A claim key identifies the specific slot this fact occupies: entity/attribute in lowercase snake_case.",
+    "You are a knowledge entry classifier. Extract one stable claim key for a durable knowledge entry.",
+    "A claim key names the durable slot this entry updates: entity/attribute in lowercase snake_case.",
+    "The goal is stable slot naming, not a paraphrase of the current value.",
+    "",
+    "Stability rules:",
+    "- Prefer stable slot names over transient wording.",
+    "- Choose attribute names that still make sense if the value changes.",
+    "- Prefer short noun-like slot names over sentence-like attribute phrases.",
+    "- When a candidate sounds like a rule or explanation sentence, compress it into the reusable slot it governs.",
+    "- Prefer concrete entities over pronouns, deictic phrases, or self-referential placeholders.",
+    "- Reuse an existing entity or full claim-key example when it clearly matches the same slot.",
+    "- Stay domain-general. The same rules apply to people, devices, services, projects, places, organizations, products, datasets, policies, and preferences.",
+    "- If the entry states a durable rule, default, workflow, guardrail, source-of-truth rule, architecture boundary, or process constraint plus rationale, extract the primary durable slot rather than the supporting rationale.",
+    "- Do not return no_claim just because the entry explains why the rule exists. The durable policy or system slot is usually still the target.",
+    "- Avoid full action clauses like requires_x_to_y, preserves_x_across_y, or x_precedes_y when a shorter stable slot such as trigger_condition, context_preservation, source_of_truth, or handoff_order would carry the same durable meaning.",
+    "",
+    "Return no_claim when:",
+    "- The entry is narrative, multi-fact, or mostly a story about what happened.",
+    "- The entry is an event or milestone without one continuing slot.",
+    "- The entity is ambiguous or can only be named with a pronoun or vague placeholder.",
+    "- The entry does not express one durable property, preference, decision, configuration, relationship, or other stable slot.",
+    "- When unsure, prefer no_claim over inventing a weak key.",
+    "",
+    "Positive examples:",
+    `- "Jim's timezone is America/Chicago." -> jim/timezone`,
+    '- "Jim prefers oat milk in coffee." -> jim/coffee_preference',
+    '- "Pixel 8 is set to dark mode." -> pixel_8/theme_mode',
+    '- "Postgres max_connections is 200." -> postgres/max_connections',
+    '- "Agenr defaults to gpt-5.4-mini." -> agenr/default_model',
+    '- "Mac mini updates should stay manual so debugging stays predictable." -> mac_mini/manual_update_policy',
+    '- "Use the warehouse inventory sheet as the source of truth for stock counts." -> stock_counts/source_of_truth',
+    '- "The repo workflow is defined by AGENTS.md, even when older notes disagree." -> repo_workflow/source_of_truth',
+    '- "Agenr keeps pure logic in src/core and adapters outside it so future hosts can plug in cleanly." -> agenr/core_adapter_boundary',
+    '- "The before-prompt-build hook only triggers after a real agent turn or message." -> before_prompt_build_hook/trigger_condition',
+    '- "Durable memory preserves context across sessions." -> durable_memory/context_preservation',
     "",
-    "Rules:",
-    "- entity: the primary noun this fact is about - the thing being described. Could be a person, project, system, tool, service, concept, dataset, organization, or any other identifiable noun.",
-    "- attribute: the specific property or aspect of that entity being stated. Should be narrow enough that two entries with the same entity/attribute are likely describing the same slot of knowledge.",
-    "- Format: entity/attribute (both lowercase snake_case)",
-    "- If the entry describes multiple unrelated facts, narrative content, or a vague opinion with no single dominant slot, set no_claim to true.",
-    "- Confidence: 0.0 to 1.0, how precisely this claim key captures the entry's single dominant slot. Use 0.9+ only when the slot is unambiguous.",
+    "Negative examples:",
+    "- Bad: jim/america_chicago -> Good: jim/timezone",
+    "- Bad: project_x/details -> Good: project_x/deploy_strategy",
+    "- Bad: we/deployment_process -> Good: platform_team/deploy_strategy",
+    "- Bad: jim/oat_milk -> Good: jim/coffee_preference",
+    "- Bad: release_notes/because_rollbacks_are_hard -> Good: release_process/source_of_truth",
+    "- Bad: openclaw/requires_real_agent_turn_or_message_to_trigger -> Good: openclaw/trigger_condition",
+    "- Bad: session_continuity/durable_memory_preserves_context_across_sessions -> Good: session_continuity/context_preservation",
+    "- Bad: incident_story/we_spent_two_hours_debugging -> Good: no_claim",
     "",
-    `Known entities already in the knowledge base: ${normalizedHints.length > 0 ? normalizedHints.join(", ") : "(none)"}`,
-    `If the entry is clearly about one of these existing entities, use that name. Do not invent a new entity name when an existing one matches (e.g., don't create "react_router_v7" if "react_router" already exists and the entry is about React Router).`,
+    "Field rules:",
+    "- entity: the main concrete thing being described. It can be a person, device, service, product, organization, workflow area, or other durable system/process anchor.",
+    "- attribute: the narrow stable slot on that entity. For policy/process entries, name the governing slot such as source_of_truth, default_mode, update_policy, architecture_boundary, deploy_strategy, or escalation_workflow.",
+    "- Confidence: 0.0 to 1.0. Use 0.9+ only when the slot is unambiguous and durable.",
+    "",
+    `Known entity hints: ${hints.entityHints.length > 0 ? hints.entityHints.join(", ") : "(none)"}`,
+    `Known claim-key examples: ${hints.claimKeyExamples.length > 0 ? hints.claimKeyExamples.join(", ") : "(none)"}`,
+    `Current entry metadata hints: ${metadataHints.length > 0 ? metadataHints.join(", ") : "(none)"}`,
+    `Current entry grounding clues: ${groundingHints.length > 0 ? groundingHints.join(", ") : "(none)"}`,
+    'If project metadata is present, it may resolve phrases like "the project" when that mapping is obvious.',
+    'If user metadata is present, it may resolve phrases like "the user", "I", or "me" when that mapping is obvious.',
+    "Tags and source_context are local grounding clues, not proof. Use them to pick the right durable slot only when the entry content already supports that slot.",
+    ...retryInstructions,
     "",
     'Respond with JSON: { "entity": string, "attribute": string, "confidence": number, "no_claim"?: boolean }'
   ].join("\n");
@@ -8763,28 +9539,270 @@ function buildClaimExtractionSystemPrompt(entityHints) {
 function buildClaimExtractionUserPrompt(entry) {
   return [`Entry type: ${entry.type}`, `Subject: ${entry.subject}`, `Content: ${entry.content}`].join("\n");
 }
+async function attemptClaimExtraction(entry, hints, llm) {
+  const userPrompt = buildClaimExtractionUserPrompt(entry);
+  try {
+    return {
+      path: "model",
+      response: await llm.completeJson(buildClaimExtractionSystemPrompt(hints, "standard"), userPrompt)
+    };
+  } catch (error) {
+    if (!isMalformedJsonError(error)) {
+      throw error;
+    }
+  }
+  return {
+    path: "json_retry",
+    response: await llm.completeJson(buildClaimExtractionSystemPrompt(hints, "json_retry"), userPrompt)
+  };
+}
+function buildClaimExtractionCandidate(entry, response, hints, onWarning) {
+  const confidence = normalizeConfidence(response.confidence);
+  const rawEntity = typeof response.entity === "string" ? response.entity.trim() : "";
+  const rawAttribute = typeof response.attribute === "string" ? response.attribute.trim() : "";
+  const entity = normalizeEntity(rawEntity, hints);
+  const attribute = normalizeClaimKeySegment(rawAttribute);
+  const normalizedClaimKey = normalizeClaimKey(`${entity}/${attribute}`);
+  if (!normalizedClaimKey.ok) {
+    onWarning?.(`Claim extraction dropped claim key for "${entry.subject}": ${describeClaimKeyNormalizationFailure(normalizedClaimKey.reason)}.`);
+    return null;
+  }
+  const compactedClaimKey = compactClaimKey(normalizedClaimKey.value.claimKey);
+  if (!compactedClaimKey) {
+    onWarning?.(`Claim extraction dropped claim key for "${entry.subject}": claim key could not be compacted safely.`);
+    return null;
+  }
+  const validatedClaimKey = validateExtractedClaimKey(compactedClaimKey);
+  if (!validatedClaimKey.ok) {
+    onWarning?.(
+      `Claim extraction rejected "${validatedClaimKey.value.claimKey}" for "${entry.subject}": ${describeExtractedClaimKeyRejection(validatedClaimKey.reason, validatedClaimKey.value)}.`
+    );
+    return null;
+  }
+  return {
+    claimKey: validatedClaimKey.value.claimKey,
+    confidence,
+    rawEntity,
+    rawAttribute,
+    compactedFrom: compactedClaimKey.compactedFrom,
+    compactionReason: compactedClaimKey.reason
+  };
+}
+function tryDeterministicClaimKeyRepair(entry, hints) {
+  const repaired = parsePossessiveClaim(entry.subject) ?? parsePossessiveStatement(entry.content);
+  if (!repaired) {
+    return null;
+  }
+  const attribute = normalizeClaimKeySegment(repaired.attribute);
+  if (!looksLikeDeterministicAttribute(attribute)) {
+    return null;
+  }
+  const entity = normalizeEntity(repaired.entity, hints);
+  const normalizedClaimKey = normalizeClaimKey(`${entity}/${attribute}`);
+  if (!normalizedClaimKey.ok) {
+    return null;
+  }
+  const validatedClaimKey = validateExtractedClaimKey(normalizedClaimKey.value);
+  if (!validatedClaimKey.ok) {
+    return null;
+  }
+  return {
+    claimKey: validatedClaimKey.value.claimKey,
+    confidence: DEFAULT_REPAIR_CONFIDENCE,
+    rawEntity: repaired.entity,
+    rawAttribute: repaired.attribute,
+    path: "deterministic_repair"
+  };
+}
+async function loadClaimExtractionHintState(db) {
+  const [entityHintResult, claimKeyExampleResult] = await Promise.allSettled([getEntityHints(db), getClaimKeyExamples(db)]);
+  return createHintState({
+    entityHints: entityHintResult.status === "fulfilled" ? entityHintResult.value : [],
+    claimKeyExamples: claimKeyExampleResult.status === "fulfilled" ? claimKeyExampleResult.value : []
+  });
+}
+async function getClaimKeyExamples(db) {
+  if (typeof db.getClaimKeyExamples !== "function") {
+    return [];
+  }
+  return db.getClaimKeyExamples(MAX_CLAIM_KEY_EXAMPLES);
+}
+function createHintState(input) {
+  const claimKeyExamples = normalizeClaimKeyExamples(input.claimKeyExamples ?? []);
+  const entityHints = limitUnique(
+    [
+      ...normalizeEntityHints(input.entityHints ?? []),
+      ...claimKeyExamples.flatMap((claimKey) => {
+        const normalizedClaimKey = normalizeClaimKey(claimKey);
+        return normalizedClaimKey.ok ? [normalizedClaimKey.value.entity] : [];
+      })
+    ],
+    MAX_ENTITY_HINTS
+  );
+  return {
+    entityHints,
+    claimKeyExamples
+  };
+}
+function buildEntryHints(state, entry) {
+  return {
+    entityHints: [...state.entityHints],
+    claimKeyExamples: [...state.claimKeyExamples],
+    userId: entry.user_id,
+    project: entry.project,
+    tags: entry.tags,
+    sourceContext: entry.source_context
+  };
+}
+function recordClaimKeyHint(state, claimKey) {
+  const normalizedClaimKey = normalizeClaimKey(claimKey);
+  if (!normalizedClaimKey.ok) {
+    return;
+  }
+  state.claimKeyExamples = prependUnique(state.claimKeyExamples, normalizedClaimKey.value.claimKey, MAX_CLAIM_KEY_EXAMPLES);
+  state.entityHints = prependUnique(state.entityHints, normalizedClaimKey.value.entity, MAX_ENTITY_HINTS);
+}
+function normalizeClaimExtractionHints(hints) {
+  const claimKeyExamples = normalizeClaimKeyExamples(hints.claimKeyExamples ?? []);
+  return {
+    entityHints: limitUnique(
+      [
+        ...normalizeEntityHints(hints.entityHints ?? []),
+        ...claimKeyExamples.flatMap((claimKey) => {
+          const normalizedClaimKey = normalizeClaimKey(claimKey);
+          return normalizedClaimKey.ok ? [normalizedClaimKey.value.entity] : [];
+        })
+      ],
+      MAX_ENTITY_HINTS
+    ),
+    claimKeyExamples,
+    userEntity: normalizeMetadataEntity(hints.userId),
+    projectEntity: normalizeMetadataEntity(hints.project),
+    tags: normalizeHintTags(hints.tags ?? []),
+    sourceContext: normalizeSourceContextHint(hints.sourceContext)
+  };
+}
+function buildPreviewOutcome(outcome, attempt) {
+  return {
+    outcome,
+    confidence: normalizeConfidence(attempt.response.confidence),
+    rawEntity: typeof attempt.response.entity === "string" ? attempt.response.entity.trim() : "",
+    rawAttribute: typeof attempt.response.attribute === "string" ? attempt.response.attribute.trim() : "",
+    path: attempt.path
+  };
+}
 function normalizeConfidence(value) {
   if (typeof value !== "number" || !Number.isFinite(value)) {
     return 0;
   }
   return Math.min(1, Math.max(0, value));
 }
-function normalizeEntity(value, entityHints) {
-  const normalizedValue = normalizeClaimKeyPart(value);
+function normalizeEntity(value, hints) {
+  const normalizedValue = normalizeClaimKeySegment(value);
   if (normalizedValue.length === 0) {
     return "";
   }
-  const normalizedHints = Array.from(new Set(entityHints.map((entityHint) => normalizeClaimKeyPart(entityHint)).filter((entityHint) => entityHint.length > 0)));
-  if (SELF_REFERENTIAL_ENTITIES.has(normalizedValue)) {
-    if (normalizedHints.length === 1) {
-      return normalizedHints[0] ?? normalizedValue;
-    }
+  if (!SELF_REFERENTIAL_ENTITIES2.has(normalizedValue)) {
     return normalizedValue;
   }
+  if (USER_REFERENTIAL_ENTITIES.has(normalizedValue) && hints.userEntity) {
+    return hints.userEntity;
+  }
+  if (PROJECT_REFERENTIAL_ENTITIES.has(normalizedValue) && hints.projectEntity) {
+    return hints.projectEntity;
+  }
+  const concreteCandidates = limitUnique(
+    [hints.projectEntity, hints.userEntity, ...hints.entityHints].filter(
+      (candidate) => typeof candidate === "string" && candidate.length > 0
+    ),
+    MAX_ENTITY_HINTS
+  );
+  if (concreteCandidates.length === 1) {
+    return concreteCandidates[0] ?? normalizedValue;
+  }
+  if (hints.entityHints.length === 1) {
+    return hints.entityHints[0] ?? normalizedValue;
+  }
   return normalizedValue;
 }
-function normalizeClaimKeyPart(value) {
-  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
+function normalizeEntityHints(entityHints) {
+  return limitUnique(
+    entityHints.map((entityHint) => normalizeClaimKeySegment(entityHint)).filter((entityHint) => entityHint.length > 0 && !SELF_REFERENTIAL_ENTITIES2.has(entityHint)),
+    MAX_ENTITY_HINTS
+  );
+}
+function normalizeClaimKeyExamples(claimKeyExamples) {
+  return limitUnique(
+    claimKeyExamples.flatMap((claimKeyExample) => {
+      const normalizedClaimKey = normalizeClaimKey(claimKeyExample);
+      return normalizedClaimKey.ok ? [normalizedClaimKey.value.claimKey] : [];
+    }),
+    MAX_CLAIM_KEY_EXAMPLES
+  );
+}
+function normalizeMetadataEntity(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const normalized = normalizeClaimKeySegment(value);
+  if (normalized.length === 0 || SELF_REFERENTIAL_ENTITIES2.has(normalized) || !/[a-z]/u.test(normalized)) {
+    return void 0;
+  }
+  return normalized;
+}
+function normalizeHintTags(tags) {
+  return limitUnique(
+    tags.map((tag) => normalizeClaimKeySegment(tag)).filter((tag) => tag.length > 0),
+    8
+  );
+}
+function normalizeSourceContextHint(value) {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return void 0;
+  }
+  return trimmed.length <= 160 ? trimmed : `${trimmed.slice(0, 157).trimEnd()}...`;
+}
+function isMalformedJsonError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return /json|unexpected token|unexpected end|unexpected non-whitespace|unterminated|position \d+/iu.test(message);
+}
+function parsePossessiveClaim(subject) {
+  const match = /^\s*(?<entity>[^.!?\n]+?)[’']s\s+(?<attribute>[^.!?\n]+?)\s*$/iu.exec(subject);
+  if (!match?.groups) {
+    return null;
+  }
+  return {
+    entity: stripTrailingPunctuation(match.groups.entity),
+    attribute: stripTrailingPunctuation(match.groups.attribute)
+  };
+}
+function parsePossessiveStatement(content) {
+  const match = /^\s*(?<entity>[^.!?\n]+?)[’']s\s+(?<attribute>[^.!?\n]+?)\s+(?:is|are|was|were)\b/iu.exec(content);
+  if (!match?.groups) {
+    return null;
+  }
+  return {
+    entity: stripTrailingPunctuation(match.groups.entity),
+    attribute: stripTrailingPunctuation(match.groups.attribute)
+  };
+}
+function stripTrailingPunctuation(value) {
+  return value.trim().replace(/[\s"'“”‘’.,:;!?]+$/gu, "").trim();
+}
+function looksLikeDeterministicAttribute(attribute) {
+  const parts = attribute.split("_").filter((part) => part.length > 0);
+  if (parts.length === 0 || parts.length > 4) {
+    return false;
+  }
+  const head = parts[parts.length - 1];
+  return typeof head === "string" && DETERMINISTIC_ATTRIBUTE_HEADS.has(head);
+}
+function prependUnique(values, value, limit) {
+  return limitUnique([value, ...values], limit);
+}
+function limitUnique(values, limit) {
+  return Array.from(new Set(values.filter((value) => value.length > 0))).slice(0, limit);
 }
 
 // ../../src/core/store/embedding-text.ts
@@ -8809,6 +9827,7 @@ var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-
 function validateEntriesWithIndexes(inputs) {
   const valid = [];
   const errors = [];
+  const warnings = [];
   const rejectedInputIndexes = [];
   for (const [index, input] of inputs.entries()) {
     const subject = normalizeString(input.subject);
@@ -8848,11 +9867,6 @@ function validateEntriesWithIndexes(inputs) {
       rejectedInputIndexes.push(index);
       continue;
     }
-    if (input.claim_key !== void 0 && typeof input.claim_key !== "string") {
-      errors.push(`Entry ${index} has an invalid claim key.`);
-      rejectedInputIndexes.push(index);
-      continue;
-    }
     if (input.valid_from !== void 0 && !isIsoTimestamp(input.valid_from)) {
       errors.push(`Entry ${index} has an invalid valid_from timestamp.`);
       rejectedInputIndexes.push(index);
@@ -8863,6 +9877,21 @@ function validateEntriesWithIndexes(inputs) {
       rejectedInputIndexes.push(index);
       continue;
     }
+    let normalizedClaimKey;
+    if (input.claim_key !== void 0) {
+      if (typeof input.claim_key !== "string") {
+        warnings.push(`Entry ${index} provided a non-string claim key and it was dropped.`);
+      } else {
+        const claimKey = normalizeClaimKey(input.claim_key);
+        if (claimKey.ok) {
+          normalizedClaimKey = claimKey.value.claimKey;
+        } else {
+          warnings.push(
+            `Entry ${index} provided invalid claim key ${JSON.stringify(input.claim_key)} and it was dropped: ${describeClaimKeyNormalizationFailure(claimKey.reason)}.`
+          );
+        }
+      }
+    }
     valid.push({
       inputIndex: index,
       input: {
@@ -8878,7 +9907,7 @@ function validateEntriesWithIndexes(inputs) {
         project: normalizeOptionalString(input.project),
         created_at: normalizeOptionalString(input.created_at),
         supersedes: normalizeOptionalString(input.supersedes),
-        claim_key: normalizeOptionalString(input.claim_key),
+        claim_key: normalizedClaimKey,
         valid_from: normalizeOptionalString(input.valid_from),
         valid_to: normalizeOptionalString(input.valid_to)
       }
@@ -8888,7 +9917,8 @@ function validateEntriesWithIndexes(inputs) {
     valid,
     rejected: errors.length,
     rejectedInputIndexes,
-    errors
+    errors,
+    warnings
   };
 }
 function clampImportance(value) {
@@ -8922,11 +9952,16 @@ function isIsoTimestamp(value) {
 }
 
 // ../../src/core/store/pipeline.ts
+var AUTO_SUPERSESSION_MIN_EXTRACTED_CONFIDENCE = 0.9;
+var AUTO_SUPERSESSION_ELIGIBLE_PATHS = /* @__PURE__ */ new Set(["model", "json_retry"]);
 async function storeEntriesDetailed(inputs, db, embedding, options = {}) {
   if (inputs.length === 0) {
     return { stored: 0, skipped: 0, rejected: 0, details: [] };
   }
   const plan = await buildStorePlan(inputs, db);
+  for (const warning of plan.warnings) {
+    options.onWarning?.(warning);
+  }
   if (plan.pendingEntries.length === 0) {
     return {
       stored: 0,
@@ -8951,9 +9986,9 @@ async function storeEntriesDetailed(inputs, db, embedding, options = {}) {
     };
   }
   const pendingEntries = plan.pendingEntries;
-  await maybeExtractClaimKeys(pendingEntries, options);
+  const extractedClaimKeys = await maybeExtractClaimKeys(pendingEntries, options);
   const embeddings = await resolvePendingEmbeddings(inputs, pendingEntries, embedding, options.precomputedEmbeddings);
-  await persistEntries(db, pendingEntries, embeddings, options.onWarning);
+  await persistEntries(db, pendingEntries, embeddings, extractedClaimKeys, options.claimExtraction?.config, options.onWarning);
   return {
     stored: pendingEntries.length,
     skipped: plan.skipped,
@@ -8990,9 +10025,11 @@ async function embedPendingEntries(entries, embedding) {
   }
   return vectors;
 }
-async function persistEntries(db, preparedEntries, embeddings, onWarning) {
+async function persistEntries(db, preparedEntries, embeddings, extractedClaimKeys, claimExtractionConfig, onWarning) {
   const writeBatch = async (targetDb) => {
     let stored = 0;
+    const autoSupersessionPlans = await planAutoSupersession(targetDb, preparedEntries, extractedClaimKeys, claimExtractionConfig);
+    const emittedWarnings = /* @__PURE__ */ new Set();
     for (const [index, preparedEntry] of preparedEntries.entries()) {
       const embedding = embeddings[index] ?? [];
       const entry = buildEntry(preparedEntry, embedding);
@@ -9004,11 +10041,27 @@ async function persistEntries(db, preparedEntries, embeddings, onWarning) {
           onWarning?.(`Stored entry ${entryId} but could not supersede ${supersededEntryId} because the target was missing or inactive.`);
         }
       }
+      const autoSupersessionPlan = autoSupersessionPlans.get(preparedEntry.inputIndex);
+      if (autoSupersessionPlan?.kind === "link" && autoSupersessionPlan.oldEntryId) {
+        const superseded = await targetDb.supersedeEntry(autoSupersessionPlan.oldEntryId, entryId, "update");
+        if (!superseded) {
+          onWarning?.(
+            `Stored entry ${entryId} with claim_key "${preparedEntry.input.claim_key}" but could not auto-supersede ${autoSupersessionPlan.oldEntryId} because the target was missing or inactive.`
+          );
+        }
+      }
+      if (autoSupersessionPlan?.warning && !emittedWarnings.has(autoSupersessionPlan.warning)) {
+        emittedWarnings.add(autoSupersessionPlan.warning);
+        onWarning?.(autoSupersessionPlan.warning);
+      }
       stored += 1;
     }
     return stored;
   };
-  if (hasTransactionSupport(db) && (preparedEntries.length > 1 || preparedEntries.some((entry) => entry.input.supersedes !== void 0))) {
+  if (hasTransactionSupport(db) && preparedEntries.some((entry) => entry.input.supersedes !== void 0 || entry.input.claim_key !== void 0)) {
+    return db.withTransaction(writeBatch);
+  }
+  if (hasTransactionSupport(db) && preparedEntries.length > 1) {
     return db.withTransaction(writeBatch);
   }
   return writeBatch(db);
@@ -9043,39 +10096,147 @@ function buildEntry(preparedEntry, embedding) {
 async function maybeExtractClaimKeys(preparedEntries, options) {
   const claimExtraction = options.claimExtraction;
   if (!claimExtraction || preparedEntries.length === 0) {
-    return;
+    return /* @__PURE__ */ new Map();
   }
-  let entityHints = [];
   try {
-    entityHints = await getEntityHints(claimExtraction.db);
+    const extractedEntries = await runBatchClaimExtraction(
+      [
+        {
+          entries: preparedEntries.map((preparedEntry) => preparedEntry.input)
+        }
+      ],
+      {
+        createLlm: () => claimExtraction.llm,
+        db: claimExtraction.db
+      },
+      claimExtraction.config,
+      1,
+      options.onWarning
+    );
+    const extractedClaimKeys = /* @__PURE__ */ new Map();
+    for (const preparedEntry of preparedEntries) {
+      const extracted = extractedEntries.get(preparedEntry.input);
+      if (extracted) {
+        extractedClaimKeys.set(preparedEntry.inputIndex, extracted);
+      }
+    }
+    return extractedClaimKeys;
   } catch (error) {
-    options.onWarning?.(`Claim extraction hint lookup failed: ${formatPipelineError(error)}`);
+    const subject = preparedEntries[0]?.input.subject ?? "batch";
+    options.onWarning?.(`Claim extraction failed for "${subject}": ${formatPipelineError(error)}`);
+    return /* @__PURE__ */ new Map();
   }
+}
+function hasTransactionSupport(db) {
+  return typeof db.withTransaction === "function";
+}
+async function planAutoSupersession(db, preparedEntries, extractedClaimKeys, claimExtractionConfig) {
+  const plans = /* @__PURE__ */ new Map();
+  const preparedEntriesByClaimKey = groupPreparedEntriesByClaimKey(preparedEntries);
+  const siblingCache = /* @__PURE__ */ new Map();
   for (const preparedEntry of preparedEntries) {
-    if (preparedEntry.input.claim_key) {
+    const claimKey = preparedEntry.input.claim_key;
+    if (!claimKey || preparedEntry.input.supersedes) {
       continue;
     }
-    try {
-      const extracted = await extractClaimKey(
-        {
-          type: preparedEntry.input.type,
-          subject: preparedEntry.input.subject,
-          content: preparedEntry.input.content
-        },
-        entityHints,
-        claimExtraction.llm,
-        claimExtraction.config
-      );
-      if (extracted?.claimKey) {
-        preparedEntry.input.claim_key = extracted.claimKey;
-      }
-    } catch (error) {
-      options.onWarning?.(`Claim extraction failed for "${preparedEntry.input.subject}": ${formatPipelineError(error)}`);
+    const siblings = await getClaimKeySiblings(db, siblingCache, claimKey);
+    if (siblings.length === 0) {
+      continue;
+    }
+    const batchSiblingCount = preparedEntriesByClaimKey.get(claimKey)?.length ?? 0;
+    if (batchSiblingCount > 1) {
+      plans.set(preparedEntry.inputIndex, {
+        kind: "skip",
+        warning: `Skipped auto-supersession for claim_key "${claimKey}" because this store batch contains ${batchSiblingCount} entries for the same slot.`
+      });
+      continue;
+    }
+    if (siblings.length > 1) {
+      plans.set(preparedEntry.inputIndex, {
+        kind: "skip",
+        warning: `Skipped auto-supersession for claim_key "${claimKey}" because ${siblings.length} active siblings already exist for that slot.`
+      });
+      continue;
+    }
+    const sibling = siblings[0];
+    if (!sibling) {
+      continue;
+    }
+    if (!isAutoSupersessionEligible(preparedEntry, extractedClaimKeys, claimExtractionConfig)) {
+      plans.set(preparedEntry.inputIndex, {
+        kind: "skip",
+        warning: buildAutoSupersessionEligibilityWarning(preparedEntry, extractedClaimKeys.get(preparedEntry.inputIndex))
+      });
+      continue;
+    }
+    const supersessionValidation = validateSupersessionRules(sibling, {
+      type: preparedEntry.input.type,
+      expiry: preparedEntry.input.expiry ?? "temporary"
+    });
+    if (!supersessionValidation.ok) {
+      plans.set(preparedEntry.inputIndex, {
+        kind: "skip",
+        warning: buildAutoSupersessionRuleWarning(preparedEntry, sibling, supersessionValidation.reason)
+      });
+      continue;
     }
+    plans.set(preparedEntry.inputIndex, {
+      kind: "link",
+      oldEntryId: sibling.id
+    });
   }
+  return plans;
 }
-function hasTransactionSupport(db) {
-  return typeof db.withTransaction === "function";
+function groupPreparedEntriesByClaimKey(preparedEntries) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const preparedEntry of preparedEntries) {
+    const claimKey = preparedEntry.input.claim_key;
+    if (!claimKey) {
+      continue;
+    }
+    const existing = grouped.get(claimKey) ?? [];
+    existing.push(preparedEntry);
+    grouped.set(claimKey, existing);
+  }
+  return grouped;
+}
+async function getClaimKeySiblings(db, cache, claimKey) {
+  const cached = cache.get(claimKey);
+  if (cached) {
+    return cached;
+  }
+  const siblings = await db.findActiveEntriesByClaimKey(claimKey);
+  cache.set(claimKey, siblings);
+  return siblings;
+}
+function isAutoSupersessionEligible(preparedEntry, extractedClaimKeys, claimExtractionConfig) {
+  if (preparedEntry.claimKeySource === "manual") {
+    return true;
+  }
+  const extractedClaimKey = extractedClaimKeys.get(preparedEntry.inputIndex);
+  if (!extractedClaimKey || !claimExtractionConfig) {
+    return false;
+  }
+  if (!AUTO_SUPERSESSION_ELIGIBLE_PATHS.has(extractedClaimKey.path)) {
+    return false;
+  }
+  return extractedClaimKey.confidence >= Math.max(claimExtractionConfig.confidenceThreshold, AUTO_SUPERSESSION_MIN_EXTRACTED_CONFIDENCE);
+}
+function buildAutoSupersessionEligibilityWarning(preparedEntry, extractedClaimKey) {
+  const claimKey = preparedEntry.input.claim_key ?? "(missing)";
+  if (preparedEntry.claimKeySource === "manual") {
+    return `Stored entry "${preparedEntry.input.subject}" with claim_key "${claimKey}" but skipped auto-supersession because the claim-key provenance was not eligible for automatic linking.`;
+  }
+  if (extractedClaimKey) {
+    return `Stored entry "${preparedEntry.input.subject}" with claim_key "${claimKey}" but skipped auto-supersession because the extracted claim key came from ${extractedClaimKey.path} at confidence ${extractedClaimKey.confidence.toFixed(2)}. Only explicit/manual claim keys or model-extracted keys at ${AUTO_SUPERSESSION_MIN_EXTRACTED_CONFIDENCE.toFixed(2)}+ auto-link.`;
+  }
+  return `Stored entry "${preparedEntry.input.subject}" with claim_key "${claimKey}" but skipped auto-supersession because the claim-key provenance was not explicit or a tracked high-confidence extraction.`;
+}
+function buildAutoSupersessionRuleWarning(preparedEntry, sibling, reason) {
+  if (reason === "type_mismatch") {
+    return `Stored entry "${preparedEntry.input.subject}" with claim_key "${preparedEntry.input.claim_key}" but skipped auto-supersession because the matching active entry is type "${sibling.type}" and the new entry is type "${preparedEntry.input.type}". ${describeSupersessionRuleFailure(reason)}`;
+  }
+  return `Stored entry "${preparedEntry.input.subject}" with claim_key "${preparedEntry.input.claim_key}" but skipped auto-supersession: ${describeSupersessionRuleFailure(reason)}`;
 }
 async function buildStorePlan(inputs, db) {
   const validation = validateEntriesWithIndexes(inputs);
@@ -9088,7 +10249,8 @@ async function buildStorePlan(inputs, db) {
     input,
     inputIndex,
     contentHash: computeContentHash(input.content, input.source_file),
-    normContentHash: computeNormContentHash(input.content)
+    normContentHash: computeNormContentHash(input.content),
+    claimKeySource: input.claim_key ? "manual" : void 0
   }));
   const afterBatchContentHash = dedupePreparedEntries(preparedEntries, "contentHash", "content_hash", details);
   const existingHashes = await db.findExistingHashes(afterBatchContentHash.map((entry) => entry.contentHash));
@@ -9100,7 +10262,8 @@ async function buildStorePlan(inputs, db) {
     pendingEntries,
     skipped: details.filter((detail) => detail.outcome === "skipped").length,
     rejected: validation.rejected,
-    details
+    details,
+    warnings: validation.warnings
   };
 }
 function dedupePreparedEntries(entries, field, reason, details) {
@@ -9156,11 +10319,11 @@ var STORE_TOOL_PARAMETERS = {
     },
     subject: {
       type: "string",
-      description: "Short subject line future recall can match. Name the decision, preference, person, system, or risk directly."
+      description: "Short subject line future recall can match. Name the durable takeaway, person, system, rule, relationship, or milestone directly."
     },
     content: {
       type: "string",
-      description: "What a fresh session should remember. Store the durable takeaway, not a transient progress snapshot."
+      description: "What a fresh session should remember. Store the durable takeaway, not the activity log, canonical record, or transient progress snapshot."
     },
     importance: {
       type: "integer",
@@ -9205,7 +10368,7 @@ function createAgenrStoreTool(ctx, servicesPromise, logger) {
   return {
     name: "agenr_store",
     label: "Agenr Store",
-    description: "Store a new knowledge entry in agenr long-term memory. Call immediately after decisions, preferences, lessons, and durable facts - but apply the future-session test first: will a fresh session need this to make a better decision, or are you just logging what happened?\n\nStore: architecture decisions, workflow constraints, recurring problems, user preferences, durable technical facts, operational lessons, important open risks.\n\nDo not store: version shipping events (changelogs are the record), issue/PR filing records (the tracker is the record), phase plans or release sequencing (stale within a session), progress snapshots (stale within minutes), prompt file locations or build logistics.\n\nWhen replacing an existing fact, pass `supersedes` with the old entry's ID. When storing a slot-like fact (for example, a library version or a rollout strategy), pass `claimKey` to enable future supersession detection.\n\nDo not ask before storing - but do ask whether future-you actually needs it.",
+    description: "Store a new durable memory entry in agenr. Apply the future-session test first: will a fresh future session make a better decision because this was stored, or are you just logging that something happened?\n\nIf another system is already the canonical record - such as version control, a task or ticket tracker, a calendar, a signed document, a chat or email thread, or a database/CRM - usually do not store that record here. Store only the durable takeaway: the standing implication, rule, lesson, preference, risk, or relationship.\n\nType guide: fact = durable truth about a person, system, place, or how something works. decision = a standing rule, constraint, policy, or chosen approach future sessions should follow. preference = what someone likes, wants, values, or wants avoided. lesson = a non-obvious takeaway learned from experience that should change future behavior. milestone = a rare one-time event with durable future significance, not ordinary execution progress. relationship = a meaningful durable connection between people, groups, or systems.\n\nUsually do not store: 'I merged PR #123.', 'I filed a ticket with support.', 'We had a meeting at 3 PM.', 'I sent the contract for signature.', 'We spent two hours debugging the outage.' Do store the takeaway instead: 'Always use the structured export path because raw sync corrupts timestamps.' 'Jim prefers text-first updates and dislikes surprise calls.' 'Service restarts fail unless config Y is enabled.' 'The office Wi-Fi name is Acorn-5G.'\n\nDo not use decision as a catch-all for important activity updates. Do not store plans, checklists, speculative future state, progress snapshots, session narration, or rephrased recalled material.\n\nWhen replacing an existing fact, pass `supersedes` with the old entry's ID. When storing a slot-like fact (for example, a library version or a rollout strategy), pass `claimKey` to enable future supersession detection.\n\nDo not ask before storing - but do ask whether future-you actually needs it.",
     parameters: STORE_TOOL_PARAMETERS,
     async execute(_toolCallId, rawParams) {
       try {
@@ -9410,25 +10573,32 @@ function createAgenrUpdateTool(ctx, servicesPromise, logger) {
         const subject = readStringParam6(params, "subject");
         const importance = readNumberParam3(params, "importance", { integer: true, strict: true });
         const expiry = parseExpiry(readStringParam6(params, "expiry"));
-        const claimKey = readStringParam6(params, "claimKey");
+        const claimKeyInput = readStringParam6(params, "claimKey");
         const validFrom = readStringParam6(params, "validFrom");
         const validTo = readStringParam6(params, "validTo");
+        const normalizedClaimKey = claimKeyInput === void 0 ? void 0 : (() => {
+          const claimKey = normalizeClaimKey(claimKeyInput);
+          if (!claimKey.ok) {
+            throw new Error("claimKey must use canonical entity/attribute format.");
+          }
+          return claimKey.value.claimKey;
+        })();
         logToolCall(
           logger,
           "agenr_update",
           ctx,
           `target=${formatTargetSelector(id, subject)}${importance !== void 0 ? ` importance=${importance}` : ""}${expiry !== void 0 ? ` expiry=${expiry}` : ""}`,
-          sanitizeUpdateToolParams({ id, subject, importance, expiry, claimKey, validFrom, validTo })
+          sanitizeUpdateToolParams({ id, subject, importance, expiry, claimKey: normalizedClaimKey, validFrom, validTo })
         );
         const services = await servicesPromise;
         const entry = await resolveTargetEntry(services, params);
-        if (importance === void 0 && expiry === void 0 && claimKey === void 0 && validFrom === void 0 && validTo === void 0) {
+        if (importance === void 0 && expiry === void 0 && normalizedClaimKey === void 0 && validFrom === void 0 && validTo === void 0) {
           throw new Error("Provide at least one update field: importance, expiry, claimKey, validFrom, or validTo.");
         }
         const updated = await services.entries.updateEntry(entry.id, {
           ...importance !== void 0 ? { importance } : {},
           ...expiry !== void 0 ? { expiry } : {},
-          ...claimKey !== void 0 ? { claim_key: claimKey } : {},
+          ...normalizedClaimKey !== void 0 ? { claim_key: normalizedClaimKey } : {},
           ...validFrom !== void 0 ? { valid_from: validFrom } : {},
           ...validTo !== void 0 ? { valid_to: validTo } : {}
         });
@@ -9445,7 +10615,7 @@ function createAgenrUpdateTool(ctx, servicesPromise, logger) {
           sessionKey: ctx.sessionKey,
           ...importance !== void 0 ? { importance } : {},
           ...expiry !== void 0 ? { expiry } : {},
-          ...claimKey !== void 0 ? { claimKey } : {},
+          ...normalizedClaimKey !== void 0 ? { claimKey: normalizedClaimKey } : {},
           ...validFrom !== void 0 ? { validFrom } : {},
           ...validTo !== void 0 ? { validTo } : {}
         });
@@ -9470,7 +10640,7 @@ function registerAgenrOpenClawTools(api, servicesPromise, logger) {
 var openclaw_plugin_default = {
   id: "agenr",
   name: "agenr",
-  version: "1.6.0",
+  version: "1.7.0",
   description: "agenr memory plugin for OpenClaw",
   kind: "memory",
   contracts: {
@@ -9723,7 +10893,7 @@ function buildAgenrMemoryPromptSection({
   const lines = [
     "## Memory Recall",
     "Before answering anything about prior work, decisions, preferences, people, dates, unfinished work, or past sessions, call agenr_recall first. Session-start recall is automatic; use agenr_recall mid-session when you need context you do not already have.",
-    "agenr_recall supports two recall kinds behind one tool: use mode=entries for exact facts, decisions, thresholds, and versions; use mode=episodes or auto for what-happened questions tied to a time period.",
+    "agenr_recall supports exact fact recall plus historical and episodic recall behind one tool: use mode=entries for exact facts, decisions, thresholds, and versions; use mode=auto for prior-state questions like what was the previous approach, what did we use before, or what changed from X to Y; use mode=episodes when you explicitly want session narrative recall.",
     "For temporal narrative questions, put the time phrase in the query itself: examples include yesterday, last week, this month, 2 weeks ago, or in March.",
     "One focused agenr_recall call with the right scope beats several broad ones.",
     "Memory authority, strongest to weakest:",
@@ -9735,7 +10905,20 @@ function buildAgenrMemoryPromptSection({
   ];
   if (availableTools.has(MEMORY_TOOL_NAMES.store)) {
     lines.push(
-      "Store decisions, preferences, lessons, durable facts, and important open risks with agenr_store immediately after they happen. Apply the future-session test: will a fresh session need this to make a better decision?"
+      "Use agenr_store for durable memory, not for logging. Apply the future-session test: will a fresh future session make a better decision because this was stored, or are you just recording that something happened?"
+    );
+    lines.push(
+      "If another system already holds the canonical record - such as version control, a task or ticket tracker, a calendar, a signed document, a chat or email thread, or a database/CRM - usually do not store that record. Store only the durable takeaway: the standing rule, implication, lesson, preference, risk, or relationship."
+    );
+    lines.push(
+      "Type guide: fact = durable truth about a person, system, place, or how something works; decision = standing rule, constraint, policy, or chosen approach future sessions should follow; preference = what someone likes, wants, values, or wants avoided; lesson = non-obvious takeaway from experience that should change future behavior; milestone = rare one-time event with durable future significance, not ordinary task completion."
+    );
+    lines.push("Do not use decision as a catch-all for important activity updates.");
+    lines.push(
+      "Usually do not store: 'I merged PR #123.', 'I filed a support ticket.', 'We had a meeting at 3 PM.', 'I sent the contract for signature.', or 'We spent two hours debugging the outage.'"
+    );
+    lines.push(
+      "Do store the durable takeaway instead: 'Always use the structured export path because raw sync corrupts timestamps.' (decision or lesson), 'Jim prefers text-first updates and dislikes surprise calls.' (preference), 'Service restarts fail unless config Y is enabled.' (lesson), 'The office Wi-Fi name is Acorn-5G.' (fact)."
     );
     lines.push("Do not store progress snapshots or current-state narration about what is happening right now as durable memory.");
     lines.push("Do not store plans, checklists, or speculative future state as facts or decisions.");
@@ -10921,6 +12104,26 @@ function firstStringArgValue(args, max) {
   }
   return void 0;
 }
+function extractAgenrStoreEntries(args) {
+  const nestedEntries = Array.isArray(args.entries) ? args.entries.flatMap((entry) => {
+    const record = asRecord3(entry);
+    return record ? [record] : [];
+  }) : [];
+  if (nestedEntries.length > 0) {
+    return nestedEntries;
+  }
+  if (getString(args.type) || getString(args.subject) || getString(args.content) || getString(args.claimKey) || getString(args.claim_key) || getString(args.supersedes)) {
+    return [args];
+  }
+  return [];
+}
+function summarizeAgenrStoreEntry(entry) {
+  const type = getString(entry.type) ?? "unknown";
+  const subject = getString(entry.subject) ?? "(no subject)";
+  const claimKey = getString(entry.claimKey) ?? getString(entry.claim_key);
+  const claimKeySuffix = claimKey ? ` claim_key=${JSON.stringify(truncateInline(claimKey.trim(), 120))}` : "";
+  return `${type}: "${truncateInline(subject, 60)}"${claimKeySuffix}`;
+}
 function toolIdentifier(toolName, args) {
   const normalizedToolName = toolName.trim().toLowerCase();
   if (normalizedToolName === "read" || normalizedToolName === "edit" || normalizedToolName === "write") {
@@ -10942,7 +12145,7 @@ function toolIdentifier(toolName, args) {
     return targetUrl ? `${action} ${targetUrl}` : action;
   }
   if (normalizedToolName === "agenr_store") {
-    const entries = Array.isArray(args.entries) ? args.entries : [];
+    const entries = extractAgenrStoreEntries(args);
     return `${entries.length} entr${entries.length === 1 ? "y" : "ies"}`;
   }
   if (normalizedToolName === "agenr_recall") {
@@ -11037,19 +12240,11 @@ function summarizeToolCall(call, options) {
     return `[called message: ${truncateInline(action, 200)} to ${truncateInline(target, 200)}]`;
   }
   if (normalizedToolName === "agenr_store") {
-    const entries = Array.isArray(args.entries) ? args.entries : [];
+    const entries = extractAgenrStoreEntries(args);
     if (entries.length === 0) {
       return "[attempted brain store: (empty)]";
     }
-    const summaries = entries.slice(0, 3).map((entry) => {
-      const record = asRecord3(entry);
-      if (!record) {
-        return null;
-      }
-      const type = getString(record.type) ?? "unknown";
-      const subject = getString(record.subject) ?? "(no subject)";
-      return `${type}: "${truncateInline(subject, 60)}"`;
-    }).filter((summary) => summary !== null);
+    const summaries = entries.slice(0, 3).map(summarizeAgenrStoreEntry);
     const countSuffix = entries.length > 3 ? ` (+${entries.length - 3} more)` : "";
     return `[attempted brain store: ${summaries.join(", ")}${countSuffix}]`;
   }
@@ -13489,8 +14684,9 @@ var AUTH_METHOD_DEFINITIONS = [
 var AUTH_METHOD_SET = new Set(AUTH_METHOD_DEFINITIONS.map((definition) => definition.id));
 var DEFAULT_CONFIG_DIR = path7.join(os2.homedir(), ".agenr");
 var DEFAULT_DB_NAME = "knowledge.db";
+var DEFAULT_CLAIM_EXTRACTION_CONCURRENCY = 10;
 var DEFAULT_CLAIM_EXTRACTION_CONFIDENCE_THRESHOLD = 0.8;
-var DEFAULT_CLAIM_EXTRACTION_ELIGIBLE_TYPES = ["fact", "preference", "decision"];
+var DEFAULT_CLAIM_EXTRACTION_ELIGIBLE_TYPES = ["fact", "preference", "decision", "lesson"];
 function resolveConfigDir() {
   return process.env.AGENR_CONFIG_DIR ?? DEFAULT_CONFIG_DIR;
 }
@@ -13516,7 +14712,8 @@ function resolveClaimExtractionConfig(config) {
   return {
     enabled: config?.claimExtraction?.enabled ?? true,
     confidenceThreshold: normalizeClaimExtractionConfidence(config?.claimExtraction?.confidenceThreshold),
-    eligibleTypes: normalizeClaimExtractionEligibleTypes(config?.claimExtraction?.eligibleTypes)
+    eligibleTypes: normalizeClaimExtractionEligibleTypes(config?.claimExtraction?.eligibleTypes),
+    concurrency: normalizeClaimExtractionConcurrency(config?.claimExtraction?.concurrency)
   };
 }
 function readConfig(options = {}) {
@@ -13590,6 +14787,13 @@ function normalizeClaimExtractionEligibleTypes(value) {
   const normalized = Array.from(new Set(value.filter((candidate) => ENTRY_TYPES.includes(candidate))));
   return normalized.length > 0 ? normalized : [...DEFAULT_CLAIM_EXTRACTION_ELIGIBLE_TYPES];
 }
+function normalizeClaimExtractionConcurrency(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return DEFAULT_CLAIM_EXTRACTION_CONCURRENCY;
+  }
+  const normalized = Math.trunc(value);
+  return normalized > 0 ? normalized : DEFAULT_CLAIM_EXTRACTION_CONCURRENCY;
+}
 
 // ../../src/adapters/db/client.ts
 import fs9 from "fs/promises";
@@ -14493,7 +15697,26 @@ async function getDistinctClaimKeyPrefixes(executor) {
     return typeof prefix === "string" && prefix.length > 0 ? [prefix] : [];
   });
 }
-async function updateEntry(executor, id, fields) {
+async function getClaimKeyExamples2(executor, limit = 8) {
+  const normalizedLimit = Number.isFinite(limit) ? Math.max(1, Math.floor(limit)) : 8;
+  const result = await executor.execute({
+    sql: `
+      SELECT claim_key
+      FROM entries
+      WHERE claim_key IS NOT NULL
+        AND ${ACTIVE_ENTRY_CLAUSE}
+      GROUP BY claim_key
+      ORDER BY COUNT(*) DESC, MAX(importance) DESC, MAX(created_at) DESC, claim_key ASC
+      LIMIT ?
+    `,
+    args: [normalizedLimit]
+  });
+  return result.rows.flatMap((row) => {
+    const claimKey = row.claim_key;
+    return typeof claimKey === "string" && claimKey.length > 0 ? [claimKey] : [];
+  });
+}
+async function updateEntry(executor, id, fields, options) {
   const assignments = [];
   const args = [];
   if (fields.importance !== void 0) {
@@ -14527,7 +15750,7 @@ async function updateEntry(executor, id, fields) {
       UPDATE entries
       SET ${assignments.join(", ")}
       WHERE id = ?
-        AND ${ACTIVE_ENTRY_CLAUSE}
+        AND ${options?.includeInactive === true ? "1 = 1" : ACTIVE_ENTRY_CLAUSE}
     `,
     args
   });
@@ -14629,7 +15852,7 @@ function normalizeInteger(value, fallback) {
 }
 
 // ../../src/adapters/db/schema.ts
-var SCHEMA_VERSION = "6";
+var SCHEMA_VERSION = "7";
 var VECTOR_INDEX_NAME = "idx_entries_embedding";
 var EPISODE_VECTOR_INDEX_NAME = "idx_episodes_embedding";
 var BULK_WRITE_STATE_META_KEY = "bulk_write_state";
@@ -14778,6 +16001,7 @@ var CREATE_SURGEON_RUN_ACTIONS_TABLE_SQL = `
     entry_ids TEXT NOT NULL DEFAULT '[]',
     reasoning TEXT NOT NULL DEFAULT '',
     recall_delta TEXT,
+    details_json TEXT,
     created_at TEXT NOT NULL
   )
 `;
@@ -14793,6 +16017,35 @@ var CREATE_SURGEON_RUN_ACTIONS_CREATED_AT_INDEX_SQL = `
   CREATE INDEX IF NOT EXISTS idx_surgeon_run_actions_created_at
   ON surgeon_run_actions(created_at)
 `;
+var CREATE_SURGEON_RUN_PROPOSALS_TABLE_SQL = `
+  CREATE TABLE IF NOT EXISTS surgeon_run_proposals (
+    id TEXT PRIMARY KEY,
+    run_id TEXT NOT NULL REFERENCES surgeon_runs(id),
+    group_id TEXT NOT NULL,
+    issue_kind TEXT NOT NULL,
+    scope TEXT NOT NULL,
+    entry_ids TEXT NOT NULL DEFAULT '[]',
+    current_claim_keys TEXT NOT NULL DEFAULT '[]',
+    proposed_claim_keys TEXT NOT NULL DEFAULT '[]',
+    rationale TEXT NOT NULL DEFAULT '',
+    confidence REAL NOT NULL DEFAULT 0,
+    source TEXT NOT NULL DEFAULT '',
+    eligible_for_apply INTEGER NOT NULL DEFAULT 0,
+    created_at TEXT NOT NULL
+  )
+`;
+var CREATE_SURGEON_RUN_PROPOSALS_RUN_ID_INDEX_SQL = `
+  CREATE INDEX IF NOT EXISTS idx_surgeon_run_proposals_run_id
+  ON surgeon_run_proposals(run_id)
+`;
+var CREATE_SURGEON_RUN_PROPOSALS_GROUP_ID_INDEX_SQL = `
+  CREATE INDEX IF NOT EXISTS idx_surgeon_run_proposals_group_id
+  ON surgeon_run_proposals(group_id)
+`;
+var CREATE_SURGEON_RUN_PROPOSALS_CREATED_AT_INDEX_SQL = `
+  CREATE INDEX IF NOT EXISTS idx_surgeon_run_proposals_created_at
+  ON surgeon_run_proposals(created_at)
+`;
 var CREATE_META_TABLE_SQL = `
   CREATE TABLE IF NOT EXISTS _meta (
     key TEXT PRIMARY KEY,
@@ -14911,6 +16164,10 @@ var SCHEMA_STATEMENTS = [
   CREATE_SURGEON_RUN_ACTIONS_RUN_ID_INDEX_SQL,
   CREATE_SURGEON_RUN_ACTIONS_ENTRY_ID_INDEX_SQL,
   CREATE_SURGEON_RUN_ACTIONS_CREATED_AT_INDEX_SQL,
+  CREATE_SURGEON_RUN_PROPOSALS_TABLE_SQL,
+  CREATE_SURGEON_RUN_PROPOSALS_RUN_ID_INDEX_SQL,
+  CREATE_SURGEON_RUN_PROPOSALS_GROUP_ID_INDEX_SQL,
+  CREATE_SURGEON_RUN_PROPOSALS_CREATED_AT_INDEX_SQL,
   CREATE_META_TABLE_SQL,
   CREATE_ENTRIES_CONTENT_HASH_INDEX_SQL,
   CREATE_ENTRIES_NORM_CONTENT_HASH_INDEX_SQL,
@@ -14932,10 +16189,15 @@ var SCHEMA_STATEMENTS = [
 ];
 async function initSchema(db) {
   await db.execute("PRAGMA foreign_keys = ON");
-  const currentVersion = await getSchemaVersion(db);
+  let currentVersion = await getSchemaVersion(db);
   await assertSupportedSchemaState(db, currentVersion);
   if (currentVersion === "5") {
     await migrateV5ToV6(db);
+    currentVersion = "6";
+  }
+  if (currentVersion === "6") {
+    await migrateV6ToV7(db);
+    currentVersion = "7";
   }
   const hadEntriesFts = await tableExists(db, "entries_fts");
   for (const statement of SCHEMA_STATEMENTS) {
@@ -14959,7 +16221,7 @@ async function initSchema(db) {
   await ensureVectorIndexes(db);
 }
 async function assertSupportedSchemaState(db, currentVersion) {
-  if (currentVersion && currentVersion !== "5" && currentVersion !== SCHEMA_VERSION) {
+  if (currentVersion && currentVersion !== "5" && currentVersion !== "6" && currentVersion !== SCHEMA_VERSION) {
     throw new Error(
       `Unsupported agenr database schema version "${currentVersion}". This build only supports schema version ${SCHEMA_VERSION}. Create a fresh database with \`agenr db reset\` or manually migrate the data into a new database.`
     );
@@ -14987,6 +16249,21 @@ async function migrateV5ToV6(db) {
     }
   }
 }
+async function migrateV6ToV7(db) {
+  if (await tableExists(db, "surgeon_run_actions")) {
+    try {
+      await db.execute("ALTER TABLE surgeon_run_actions ADD COLUMN details_json TEXT");
+    } catch (error) {
+      if (!(error instanceof Error && /duplicate column/i.test(error.message))) {
+        throw error;
+      }
+    }
+  }
+  await db.execute(CREATE_SURGEON_RUN_PROPOSALS_TABLE_SQL);
+  await db.execute(CREATE_SURGEON_RUN_PROPOSALS_RUN_ID_INDEX_SQL);
+  await db.execute(CREATE_SURGEON_RUN_PROPOSALS_GROUP_ID_INDEX_SQL);
+  await db.execute(CREATE_SURGEON_RUN_PROPOSALS_CREATED_AT_INDEX_SQL);
+}
 async function rebuildFts(db) {
   await db.execute("INSERT INTO entries_fts(entries_fts) VALUES ('rebuild')");
 }
@@ -15204,6 +16481,10 @@ var LibsqlDatabase = class _LibsqlDatabase {
   async getDistinctClaimKeyPrefixes() {
     return getDistinctClaimKeyPrefixes(this.executor);
   }
+  /** Lists bounded full claim-key examples ordered for extraction hinting. */
+  async getClaimKeyExamples(limit) {
+    return getClaimKeyExamples2(this.executor, limit);
+  }
   /** Updates mutable entry fields such as importance, expiry, and temporal metadata. */
   async updateEntry(id, fields) {
     return updateEntry(this.executor, id, fields);
@@ -15529,9 +16810,14 @@ var RECALL_CANDIDATE_SELECT_COLUMNS = `
   e.importance,
   e.expiry,
   e.embedding,
+  e.superseded_by,
+  e.claim_key,
+  e.retired,
   e.created_at
 `;
 var FTS_TIERS = ["exact", "all_tokens", "any_tokens"];
+var PREDECESSOR_EXPANSION_LIMIT_PER_SEED = 8;
+var PREDECESSOR_EXPANSION_MAX_RESULTS = 40;
 function createRecallAdapter(executor, embeddingPort) {
   return new LibsqlRecallAdapter(executor, embeddingPort);
 }
@@ -15631,6 +16917,74 @@ var LibsqlRecallAdapter = class {
     }
     return Array.from(matches.values()).sort((left, right) => compareFtsCandidates(left, right)).slice(0, params.limit);
   }
+  /**
+   * Finds historical predecessors scoped to a seed set of active candidate IDs.
+   *
+   * Direct supersession links are preferred. Same-claim-key siblings are used as
+   * the structural lineage path, with retired same-subject entries preserved as
+   * a weaker fallback when explicit slot identity is unavailable.
+   */
+  async fetchPredecessors(params) {
+    const normalizedIds = normalizeStrings(params.activeEntryIds);
+    if (normalizedIds.length === 0) {
+      return [];
+    }
+    const placeholders = normalizedIds.map(() => "?").join(", ");
+    const expansionLimit = normalizePredecessorExpansionLimit(normalizedIds.length);
+    const result = await this.executor.execute({
+      sql: `
+        WITH seed AS (
+          SELECT id, subject, claim_key
+          FROM entries
+          WHERE id IN (${placeholders})
+        ),
+        seed_subjects AS (
+          SELECT DISTINCT subject
+          FROM seed
+          WHERE TRIM(subject) <> ''
+        ),
+        seed_claim_keys AS (
+          SELECT DISTINCT claim_key
+          FROM seed
+          WHERE claim_key IS NOT NULL
+        ),
+        lineage AS (
+          SELECT
+            ${RECALL_CANDIDATE_SELECT_COLUMNS},
+            CASE
+              WHEN e.superseded_by IN (SELECT id FROM seed) THEN 0
+              WHEN e.claim_key IS NOT NULL
+                AND e.claim_key IN (SELECT claim_key FROM seed_claim_keys)
+                AND (e.retired = 1 OR e.superseded_by IS NOT NULL) THEN 1
+              WHEN e.claim_key IS NOT NULL
+                AND e.claim_key IN (SELECT claim_key FROM seed_claim_keys) THEN 2
+              WHEN e.retired = 1
+                AND e.subject IN (SELECT subject FROM seed_subjects) THEN 3
+              ELSE 4
+            END AS lineage_priority
+          FROM entries AS e
+          WHERE e.id NOT IN (SELECT id FROM seed)
+            AND (
+              e.superseded_by IN (SELECT id FROM seed)
+              OR (
+                e.claim_key IS NOT NULL
+                AND e.claim_key IN (SELECT claim_key FROM seed_claim_keys)
+              )
+              OR (
+                e.retired = 1
+                AND e.subject IN (SELECT subject FROM seed_subjects)
+              )
+            )
+        )
+        SELECT *
+        FROM lineage
+        ORDER BY lineage_priority ASC, created_at ASC, id ASC
+        LIMIT ?
+      `,
+      args: [...normalizedIds, expansionLimit]
+    });
+    return result.rows.map((row) => mapRecallCandidateRow(row));
+  }
   /** Hydrates full entries for the final ranked result set. */
   async hydrateEntries(ids) {
     const normalizedIds = normalizeStrings(ids);
@@ -15643,8 +16997,7 @@ var LibsqlRecallAdapter = class {
         SELECT
           ${ENTRY_SELECT_COLUMNS2}
         FROM entries AS e
-        WHERE ${buildActiveEntryClause("e")}
-          AND e.id IN (${placeholders})
+        WHERE e.id IN (${placeholders})
       `,
       args: normalizedIds
     });
@@ -15735,9 +17088,15 @@ function mapRecallCandidateRow(row) {
     importance: readNumber(row, "importance", 0),
     expiry,
     embedding: readEmbedding(row, "embedding"),
+    superseded_by: readOptionalString(row, "superseded_by"),
+    claim_key: readOptionalString(row, "claim_key"),
+    retired: readBoolean(row, "retired"),
     created_at: readRequiredString(row, "created_at")
   };
 }
+function normalizePredecessorExpansionLimit(seedCount) {
+  return Math.min(PREDECESSOR_EXPANSION_MAX_RESULTS, seedCount * PREDECESSOR_EXPANSION_LIMIT_PER_SEED);
+}
 function wrapVectorError(error) {
   const message = error instanceof Error ? error.message : String(error);
   return new Error(`Vector search is unavailable: ${message}`);