recallnest 1.4.1

package/src/context-composer-queries.ts

@@ -0,0 +1,121 @@
+import type { StableCategory } from "./context-composer-stable.js";
+import { cleanText, dedupeText } from "./context-composer-text.js";
+import type { TaskCategory } from "./context-composer-task-selection.js";
+import {
+  ASSOCIATIVE_RECALL_CUE_TERMS,
+  containsAnyTerm,
+  extractTerms,
+  looksLikeContinuityTask,
+  looksLikeStyleTask,
+} from "./term-registry.js";
+
+export function buildStableQuery(category: StableCategory, taskSeed?: string): string {
+  if (taskSeed) {
+    switch (category) {
+      case "profile":
+        return `${taskSeed} user background identity role`;
+      case "preferences":
+        if (looksLikeStyleTask(taskSeed)) {
+          return `${taskSeed} user preferences writing tone voice style habits 口语化 不端着 自嘲 鸡血 浮夸`;
+        }
+        return `${taskSeed} user preferences workflow style`;
+      case "entities":
+        return `${taskSeed} project tools repository entities`;
+    }
+  }
+
+  switch (category) {
+    case "profile":
+      return "user background identity role";
+    case "preferences":
+      return "user preferences workflow style habits";
+    case "entities":
+      return "active project tools repository entities";
+  }
+}
+
+export function buildStylePreferenceFallbackQuery(taskSeed?: string): string {
+  const extracted = extractTerms(taskSeed).filter((term) =>
+    containsAnyTerm(term, ["写作", "风格", "语气", "偏好", "表达", "style", "tone", "voice", "preference"])
+  );
+  const lead = dedupeText([
+    "写作风格",
+    "语气",
+    "偏好",
+    "避免表达",
+    "口语化",
+    "不端着",
+    ...extracted,
+  ], 6).join(" ");
+
+  return lead || "写作风格 语气 偏好 避免表达 口语化 不端着";
+}
+
+export function buildTaskQuery(category: TaskCategory, taskSeed?: string): string {
+  if (taskSeed) {
+    return category === "patterns"
+      ? `${taskSeed} reusable workflow pattern steps`
+      : `${taskSeed} similar solved case previous fix`;
+  }
+  return category === "patterns"
+    ? "reusable workflow pattern steps"
+    : "similar solved case previous fix";
+}
+
+export function buildScopedEntityFallbackQuery(scope?: string, taskSeed?: string): string {
+  const scopeTerms = extractTerms(scope).slice(0, 4);
+  const taskTerms = extractTerms(taskSeed).slice(0, 4);
+  const query = dedupeText([
+    ...scopeTerms,
+    ...taskTerms,
+    "active project",
+    "shared memory layer",
+    "continuity",
+    "checkpoint_session",
+    "resume_context",
+    "project entity",
+    "tools",
+    "repository",
+  ], 10).join(" ");
+
+  return query || "active project continuity checkpoint_session resume_context project entity tools repository";
+}
+
+export function buildAssociativeNestEntityFallbackQuery(taskSeed?: string): string {
+  const associativeRecallCue = Boolean(
+    taskSeed &&
+    (
+      containsAnyTerm(taskSeed, ["RecallNest", "recallnest", "Nest", "nest"]) ||
+      (
+        looksLikeContinuityTask(taskSeed) &&
+        containsAnyTerm(taskSeed, ASSOCIATIVE_RECALL_CUE_TERMS)
+      )
+    )
+  );
+  if (!taskSeed || !associativeRecallCue) {
+    return "";
+  }
+
+  const taskTerms = extractTerms(taskSeed).slice(0, 4);
+  const query = dedupeText([
+    ...taskTerms,
+    "RecallNest",
+    "checkpoint_session",
+    "resume_context",
+    "store_memory",
+    "memory system",
+    "记忆系统",
+    "continuity",
+    "project entity",
+  ], 10).join(" ");
+
+  return query || "RecallNest checkpoint_session resume_context store_memory memory system continuity project entity";
+}
+
+export function formatLatestCheckpointHeadline(
+  sessionId: string,
+  updatedAt: string,
+  summary: string,
+): string {
+  return `Latest checkpoint from ${sessionId} on ${updatedAt.slice(0, 10)}: ${cleanText(summary, 220)}`;
+}

package/src/context-composer-scope.ts

@@ -0,0 +1,56 @@
+import { dedupeText } from "./context-composer-text.js";
+import {
+  GENERIC_SCOPE_TERMS,
+  buildTaskHintTerms,
+  extractTerms,
+  normalizeText,
+} from "./term-registry.js";
+
+export function normalizeScopedValue(scope: string): string {
+  const normalized = normalizeText(scope);
+  if (normalized.startsWith("memory:")) return normalized.slice("memory:".length);
+  if (normalized.startsWith("asset:")) return normalized.slice("asset:".length);
+  return normalized;
+}
+
+function buildScopeIdentityTerms(scope?: string): string[] {
+  if (!scope) return [];
+
+  const normalizedScope = normalizeScopedValue(scope);
+  const identity = normalizedScope.includes(":")
+    ? normalizedScope.slice(normalizedScope.indexOf(":") + 1)
+    : normalizedScope;
+  if (!identity) return [];
+
+  const spaced = identity.replace(/[-_/.:]+/g, " ");
+  return dedupeText([
+    identity,
+    spaced,
+    ...extractTerms(identity),
+    ...extractTerms(spaced),
+  ], 12)
+    .map((term) => normalizeText(term))
+    .filter((term) =>
+      term.length >= 2 &&
+      !GENERIC_SCOPE_TERMS.has(term),
+    );
+}
+
+export function buildProjectScopeCueTerms(scope?: string): string[] {
+  if (!scope) return [];
+  return dedupeText(extractTerms(scope), 8)
+    .map((term) => normalizeText(term))
+    .filter((term) =>
+      term.length >= 2 &&
+      !GENERIC_SCOPE_TERMS.has(term),
+    );
+}
+
+export function taskMentionsScopeIdentity(taskSeed: string | undefined, scope?: string): boolean {
+  if (!taskSeed) return false;
+  const identityTerms = buildScopeIdentityTerms(scope);
+  if (identityTerms.length === 0) return false;
+
+  const haystack = normalizeText(`${taskSeed} ${buildTaskHintTerms(taskSeed).join(" ")}`);
+  return identityTerms.some((term) => haystack.includes(term));
+}

package/src/context-composer-stable-selection.ts

@@ -0,0 +1,200 @@
+import { extractBoundaryMetadata, extractCanonicalKey, shouldUseStableMemoryResult } from "./memory-boundaries.js";
+import { buildProjectScopeCueTerms, normalizeScopedValue } from "./context-composer-scope.js";
+import { bestSummaryText, cleanText, dedupeText, stripConversationMarkers } from "./context-composer-text.js";
+import type { RetrievalResult } from "./retriever.js";
+import {
+  GENERIC_ENTITY_TASK_TERMS,
+  GENERIC_SCOPE_TERMS,
+  PREFERENCE_SPECIFICITY_GROUPS,
+  TASK_CUE_EXTRACTION_LIMIT,
+  buildTaskHintTerms,
+  containsAnyTerm,
+  containsLowSignalStableTerm,
+  extractTerms,
+  looksLikeStableInstruction,
+  normalizeText,
+} from "./term-registry.js";
+
+export type StableCategory = "profile" | "preferences" | "entities";
+
+const STABLE_CATEGORY_LABELS: Record<StableCategory, string> = {
+  profile: "Profile",
+  preferences: "Preference",
+  entities: "Entity",
+};
+
+function isDurableStableScope(scope: string): boolean {
+  return scope.startsWith("memory:") || scope.startsWith("asset:");
+}
+
+function isStableCandidateUseful(category: StableCategory, result: RetrievalResult): boolean {
+  if (!shouldUseStableMemoryResult({
+    category,
+    scope: result.entry.scope,
+    metadata: result.entry.metadata,
+  })) {
+    return false;
+  }
+
+  const stripped = stripConversationMarkers(result.entry.text);
+  const normalized = normalizeText(stripped);
+  if (!normalized || normalized.length < 8) return false;
+  if (looksLikeStableInstruction(normalized)) return false;
+  if (containsLowSignalStableTerm(normalized)) return false;
+  if (!isDurableStableScope(result.entry.scope) && stripped.length > 180) return false;
+  if (category === "entities" && /^(用户|助手|pinned asset|memory brief)/i.test(stripped)) return false;
+  return true;
+}
+
+function buildStableScopeCueTerms(scope?: string, taskSeed?: string): string[] {
+  return dedupeText([
+    ...extractTerms(scope, TASK_CUE_EXTRACTION_LIMIT),
+    ...extractTerms(taskSeed, TASK_CUE_EXTRACTION_LIMIT),
+    ...buildTaskHintTerms(taskSeed),
+  ], TASK_CUE_EXTRACTION_LIMIT)
+    .map((term) => normalizeText(term))
+    .filter((term) =>
+      term.length >= 2 &&
+      !GENERIC_SCOPE_TERMS.has(term),
+    );
+}
+
+function buildTaskEntityCueTerms(taskSeed?: string): string[] {
+  return dedupeText([
+    ...extractTerms(taskSeed, TASK_CUE_EXTRACTION_LIMIT),
+    ...buildTaskHintTerms(taskSeed),
+  ], TASK_CUE_EXTRACTION_LIMIT)
+    .map((term) => normalizeText(term))
+    .filter((term) =>
+      term.length >= 2 &&
+      !GENERIC_ENTITY_TASK_TERMS.has(term),
+    );
+}
+
+function countTaskEntityCueMatches(result: RetrievalResult, taskSeed?: string): number {
+  const cueTerms = buildTaskEntityCueTerms(taskSeed);
+  if (cueTerms.length === 0) return 0;
+
+  const haystack = normalizeText(stripConversationMarkers(result.entry.text));
+  return cueTerms.filter((term) => haystack.includes(term)).length;
+}
+
+function isRelevantToScopedStableRecall(
+  result: RetrievalResult,
+  params: { scope?: string; taskSeed?: string },
+): boolean {
+  if (!params.scope) {
+    return true;
+  }
+
+  const requestScope = normalizeScopedValue(params.scope);
+  const resultScope = normalizeScopedValue(result.entry.scope);
+  if (resultScope === requestScope) {
+    return true;
+  }
+
+  const haystack = normalizeText(stripConversationMarkers(result.entry.text));
+  const requestIsProject = requestScope.startsWith("project:");
+  const resultIsProject = resultScope.startsWith("project:");
+  if (requestIsProject && resultIsProject) {
+    const projectCueTerms = buildProjectScopeCueTerms(params.scope);
+    if (projectCueTerms.length === 0) {
+      return false;
+    }
+    return projectCueTerms.some((term) => haystack.includes(term));
+  }
+
+  const cueTerms = buildStableScopeCueTerms(params.scope, params.taskSeed);
+  if (cueTerms.length === 0) {
+    return true;
+  }
+
+  return cueTerms.some((term) => haystack.includes(term));
+}
+
+function stableResultKey(result: RetrievalResult): string {
+  return extractCanonicalKey(result.entry.metadata) || normalizeText(stripConversationMarkers(result.entry.text));
+}
+
+function scoreStableResult(
+  category: StableCategory,
+  result: RetrievalResult,
+  params: { taskSeed?: string; styleFocused?: boolean },
+): number {
+  let score = result.score;
+  const stripped = stripConversationMarkers(result.entry.text);
+  const boundary = extractBoundaryMetadata(result.entry.metadata);
+
+  if (isDurableStableScope(result.entry.scope)) score += 2;
+  if (boundary?.layer === "durable") score += 2;
+  if (extractCanonicalKey(result.entry.metadata)) score += 1;
+
+  if (
+    params.styleFocused &&
+    category === "preferences" &&
+    containsAnyTerm(
+      stripped,
+      [...extractTerms(params.taskSeed, TASK_CUE_EXTRACTION_LIMIT), ...buildTaskHintTerms(params.taskSeed)],
+    )
+  ) {
+    score += 2;
+  }
+
+  return score;
+}
+
+function hasUnsupportedPreferenceSpecificity(result: RetrievalResult, taskSeed?: string, styleFocused?: boolean): boolean {
+  if (styleFocused || !taskSeed) return false;
+
+  const taskHaystack = normalizeText(`${taskSeed} ${buildTaskHintTerms(taskSeed).join(" ")}`);
+  if (!taskHaystack) return false;
+
+  const resultHaystack = normalizeText(stripConversationMarkers(result.entry.text));
+  return PREFERENCE_SPECIFICITY_GROUPS.some((group) =>
+    group.resultTerms.some((term) => resultHaystack.includes(term)) &&
+    !group.taskTerms.some((term) => taskHaystack.includes(term))
+  );
+}
+
+function formatStableResult(category: StableCategory, result: RetrievalResult): string {
+  const text = bestSummaryText(result.entry.text, result.entry.metadata);
+  return cleanText(`${STABLE_CATEGORY_LABELS[category]}: ${text}`, 220);
+}
+
+export function selectStableResults(
+  category: StableCategory,
+  results: RetrievalResult[],
+  limit: number,
+  params: { taskSeed?: string; styleFocused?: boolean; scope?: string } = {},
+): string[] {
+  const ranked = results
+    .filter((result) =>
+      isStableCandidateUseful(category, result) &&
+      (category !== "preferences" || !hasUnsupportedPreferenceSpecificity(result, params.taskSeed, params.styleFocused)) &&
+      (category !== "entities" || isRelevantToScopedStableRecall(result, params))
+    )
+    .map((result) => ({
+      result,
+      key: stableResultKey(result),
+      score: scoreStableResult(category, result, params),
+      taskCueMatches: category === "entities" ? countTaskEntityCueMatches(result, params.taskSeed) : 0,
+    }))
+    .sort((a, b) => b.score - a.score);
+
+  const maxTaskCueMatches = category === "entities" && !params.scope
+    ? Math.max(0, ...ranked.map((item) => item.taskCueMatches))
+    : 0;
+  const filteredRanked = category === "entities" && !params.scope && maxTaskCueMatches > 0
+    ? ranked.filter((item) => item.taskCueMatches === maxTaskCueMatches)
+    : ranked;
+
+  const seen = new Set<string>();
+  const output: string[] = [];
+  for (const item of filteredRanked) {
+    if (!item.key || seen.has(item.key)) continue;
+    seen.add(item.key);
+    output.push(formatStableResult(category, item.result));
+    if (output.length >= limit) break;
+  }
+  return output;
+}

package/src/context-composer-stable.ts

@@ -0,0 +1,217 @@
+import type { PinAsset } from "./memory-assets.js";
+import type { RetrievalResult } from "./retriever.js";
+import type { SessionCheckpointRecord } from "./session-schema.js";
+import { selectPinnedContext } from "./context-composer-pins.js";
+import { cleanText, dedupeText } from "./context-composer-text.js";
+import { selectStableResults } from "./context-composer-stable-selection.js";
+import {
+  TASK_CUE_EXTRACTION_LIMIT,
+  buildTaskHintTerms,
+  containsLowSignalStableTerm,
+  extractTerms,
+  looksLikeContinuityTask,
+  looksLikeStableInstruction,
+  normalizeText,
+} from "./term-registry.js";
+
+export type { StableCategory } from "./context-composer-stable-selection.js";
+
+const TASK_FOCUS_LOW_SIGNAL_TERMS = new Set([
+  "context",
+  "composer",
+  "helper",
+  "boundary",
+  "刚才",
+  "那个",
+  "audit",
+  "ranking",
+  "scoring",
+  "selection",
+  "orchestration",
+  "stable",
+  "fallback",
+  "cleanup",
+  "regression",
+  "hardening",
+  "issue",
+  "error",
+  "problem",
+  "calling",
+  "窗口",
+  "window",
+  "系统",
+  "system",
+]);
+
+function interleaveUnique(buckets: string[][], limit: number): string[] {
+  const seen = new Set<string>();
+  const output: string[] = [];
+  let cursor = 0;
+
+  while (output.length < limit) {
+    let progressed = false;
+    for (const bucket of buckets) {
+      const value = bucket[cursor];
+      if (!value) continue;
+      const key = normalizeText(value);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      output.push(value);
+      progressed = true;
+      if (output.length >= limit) break;
+    }
+    if (!progressed) break;
+    cursor += 1;
+  }
+
+  return output;
+}
+
+function buildCheckpointStableContext(
+  checkpoint: SessionCheckpointRecord | null,
+  limit: number,
+): string[] {
+  if (!checkpoint) return [];
+
+  const items = [
+    checkpoint.summary ? `Checkpoint summary: ${checkpoint.summary}` : "",
+    checkpoint.task ? `Checkpoint focus: ${checkpoint.task}` : "",
+    checkpoint.decisions[0] ? `Checkpoint decision: ${checkpoint.decisions[0]}` : "",
+    checkpoint.nextActions[0] ? `Checkpoint next: ${checkpoint.nextActions[0]}` : "",
+    checkpoint.entities[0] ? `Checkpoint entity: ${checkpoint.entities[0]}` : "",
+  ].filter(Boolean);
+
+  return dedupeText(items.map((item) => cleanText(item, 220)), limit);
+}
+
+function buildTaskSeedStableContext(taskSeed?: string, limit = 1): string[] {
+  if (!taskSeed) return [];
+
+  const candidates = dedupeText([
+    ...buildTaskHintTerms(taskSeed),
+    ...extractTerms(taskSeed, TASK_CUE_EXTRACTION_LIMIT),
+  ], TASK_CUE_EXTRACTION_LIMIT)
+    .filter((term) => {
+      const normalized = normalizeText(term);
+      if (!normalized || normalized.length < 2) return false;
+      if (looksLikeStableInstruction(normalized)) return false;
+      if (containsLowSignalStableTerm(normalized)) return false;
+
+      if (/^[a-z0-9._/-]+$/i.test(term)) {
+        return term.length >= 3;
+      }
+
+      return (
+        term.includes("记忆") ||
+        term.includes("项目") ||
+        term.includes("连续") ||
+        term.includes("文章") ||
+        term.includes("写作") ||
+        term.includes("配图") ||
+        term.includes("封面") ||
+        term.includes("终端") ||
+        term.includes("窗口") ||
+        normalized.includes("memory") ||
+        normalized.includes("layer") ||
+        normalized.includes("nest")
+      );
+    });
+  const preferredCandidates = candidates.filter((term) => !TASK_FOCUS_LOW_SIGNAL_TERMS.has(normalizeText(term)));
+  const selectedCandidates = (preferredCandidates.length > 0 ? preferredCandidates : candidates)
+    .slice(0, limit);
+
+  return dedupeText(selectedCandidates.map((term) => `Task focus: ${term}`), limit);
+}
+
+export function buildStableContextSections(params: {
+  profileResults: RetrievalResult[];
+  preferenceResults: RetrievalResult[];
+  entityResults: RetrievalResult[];
+  pinAssets: Array<PinAsset & { path: string }>;
+  latestCheckpoint: SessionCheckpointRecord | null;
+  taskSeed?: string;
+  scope?: string;
+  stableLimit: number;
+  styleFocusedTask?: boolean;
+}): {
+  profileContext: string[];
+  preferenceContext: string[];
+  entityContext: string[];
+  checkpointContext: string[];
+  pinnedContext: string[];
+  taskFocusContext: string[];
+  stableContext: string[];
+} {
+  const {
+    profileResults,
+    preferenceResults,
+    entityResults,
+    pinAssets,
+    latestCheckpoint,
+    taskSeed,
+    scope,
+    stableLimit,
+    styleFocusedTask,
+  } = params;
+
+  const profileContext = selectStableResults("profile", profileResults, Math.max(2, stableLimit), {
+    taskSeed,
+    styleFocused: styleFocusedTask,
+    scope,
+  });
+  const preferenceContext = selectStableResults("preferences", preferenceResults, Math.max(2, stableLimit), {
+    taskSeed,
+    styleFocused: styleFocusedTask,
+    scope,
+  });
+  const entityContext = selectStableResults("entities", entityResults, Math.max(2, stableLimit), {
+    taskSeed,
+    styleFocused: styleFocusedTask,
+    scope,
+  });
+  const checkpointContext = buildCheckpointStableContext(latestCheckpoint, Math.min(3, stableLimit));
+  const taskHints = buildTaskHintTerms(taskSeed);
+  const suppressPinnedContextForGenericContinuity = Boolean(
+    !styleFocusedTask &&
+    taskHints.length === 0 &&
+    looksLikeContinuityTask(taskSeed) &&
+    (entityContext.length > 0 || checkpointContext.length > 0)
+  );
+  const pinnedContext = suppressPinnedContextForGenericContinuity
+    ? []
+    : selectPinnedContext(pinAssets, {
+        taskSeed,
+        scope,
+        limit: Math.min(2, stableLimit),
+        styleFocused: styleFocusedTask,
+        skipForStyleTask: Boolean(styleFocusedTask && preferenceContext.length > 0),
+      });
+  const taskFocusContext = (
+    checkpointContext.length === 0 &&
+    profileContext.length === 0 &&
+    preferenceContext.length === 0 &&
+    entityContext.length === 0 &&
+    pinnedContext.length === 0
+  )
+    ? buildTaskSeedStableContext(taskSeed, 1)
+    : [];
+
+  const stableContext = interleaveUnique([
+    profileContext,
+    preferenceContext,
+    entityContext,
+    checkpointContext,
+    taskFocusContext,
+    pinnedContext,
+  ], stableLimit);
+
+  return {
+    profileContext,
+    preferenceContext,
+    entityContext,
+    checkpointContext,
+    pinnedContext,
+    taskFocusContext,
+    stableContext,
+  };
+}

package/src/context-composer-task-fallbacks.ts

@@ -0,0 +1,36 @@
+import { containsAnyTerm, taskCueCoverage } from "./term-registry.js";
+
+export function buildWorkflowFallbackQuery(taskSeed?: string): string {
+  if (taskSeed) {
+    return `${taskSeed} search_memory resume_context checkpoint_session checkpoint autoRecall sessionStrategy workflow pattern steps`;
+  }
+  return "search_memory resume_context checkpoint_session checkpoint autoRecall sessionStrategy workflow pattern steps";
+}
+
+export function buildCaseFallbackQuery(taskSeed?: string): string {
+  if (taskSeed) {
+    if (containsAnyTerm(taskSeed, ["RecallNest", "recallnest"])) {
+      return `${taskSeed} scope fallback project scope handoff stable context cleanup continuity durable case 项目范围 交接 稳定上下文 问题 解决 方案 排查`;
+    }
+    return `${taskSeed} case solution fix root cause workaround cleanup continuity 问题 解决 方案 排查`;
+  }
+  return "case solution fix root cause workaround cleanup continuity 问题 解决 方案 排查";
+}
+
+export function buildContinuityFallbackPatterns(limit: number, existingItems: string[] = []): string[] {
+  const patterns = [
+    "Start fresh windows with resume_context before coding so stable context is restored early.",
+    "If resume_context still leaves gaps, run search_memory with the project name and task nouns before repo exploration drifts.",
+    "Before leaving a window, save checkpoint_session so the next session can recover decisions and next actions.",
+  ];
+  if (existingItems.length === 0) {
+    return patterns.slice(0, limit);
+  }
+
+  const coveredCues = new Set(existingItems.flatMap((item) => taskCueCoverage("patterns", item)));
+  return patterns
+    .filter((pattern) =>
+      taskCueCoverage("patterns", pattern).some((term) => !coveredCues.has(term))
+    )
+    .slice(0, limit);
+}