@yeaft/webchat-agent 0.1.659 → 0.1.661

package/unify/memory/recall-r6.js

@@ -1,291 +0,0 @@
-/**
- * recall-r6.js — task-334f R6 4-step recall pipeline (§Δ24.2).
- *
- * Pipeline:
- *   Step 1: Shard classifier   — fastModel OR keyword heuristic → top-1~2 shards
- *   Step 2: In-shard candidate — scan only the selected shards, filter by kind/tags/pinned
- *   Step 3: LLM rerank         — pick top-7 from candidates
- *   Step 4: Inject body only   — return entries without sourceRef (§Δ23)
- *
- * The legacy R5 recall (agent/unify/memory/recall.js) remains for back-compat
- * of callers still on MemoryStore. R6 callers should use `recallR6()` below.
- */
-
-import { createHash } from 'crypto';
-import { pickEffort } from '../effort.js';
-import {
-  VP_DEFAULT_SHARDS,
-  FEATURE_SHARDS,
-  USER_SHARDS,
-} from './schema.js';
-
-const MAX_RECALL_RESULTS = 7;
-const MAX_CANDIDATES = 15;
-
-// ─── Step 1: Shard Classifier ───────────────────────────────────
-
-/**
- * Keyword → shard heuristic. Zero-cost fallback when fastModel is unavailable.
- *
- * The lexicons are intentionally small: classifier output only needs to point
- * at the most likely shard; LLM rerank in Step 3 catches misses. Empirically
- * this covers > 70% of queries with zero LLM cost.
- */
-const SHARD_LEXICON = {
-  skill:       ['code', 'api', 'library', 'framework', 'implement', 'debug', 'syntax', 'typescript', 'vue', 'pattern', '代码', '实现', '调试', '语法', '模式', '技术'],
-  lessons:     ['mistake', 'avoid', 'lesson', 'pitfall', 'gotcha', 'bug', 'regression', '教训', '避坑', '坑', '踩坑', '反模式'],
-  preferences: ['prefer', 'like', 'style', 'convention', 'favorite', '偏好', '风格', '习惯', '喜欢'],
-  relations:   ['colleague', 'partner', 'team', 'user', 'collaborator', 'vp', '同事', '队友', '协作', '关系'],
-  // Task-memory shards
-  decision:    ['decide', 'decision', 'chose', 'picked', 'resolved', '决定', '决策', '选择'],
-  progress:    ['done', 'progress', 'milestone', 'shipped', 'finished', '完成', '进度', '交付'],
-  context:     ['background', 'context', 'requirement', 'scope', '背景', '需求', '范围'],
-  blocker:     ['block', 'stuck', 'blocker', 'issue', 'waiting', '阻塞', '卡住', '等待'],
-  artifact:    ['pr', 'commit', 'doc', 'file', 'link', 'artifact', 'deliverable', 'commit', '产出', '文档'],
-  // User-memory shards
-  profile:     ['name', 'role', 'background', 'who', 'identity', '身份', '角色', '背景'],
-  projects:    ['project', 'repo', '项目', '仓库'],
-  goals:       ['goal', 'target', 'okr', 'plan', '目标', '计划'],
-};
-
-/**
- * Pick top-N shards via keyword heuristic.
- * @param {string} prompt
- * @param {string[]} availableShards  all shards present in this store
- * @param {number} [topN=2]
- */
-export function classifyShardsByKeyword(prompt, availableShards, topN = 2) {
-  if (!prompt || !availableShards || availableShards.length === 0) return [];
-  const lower = prompt.toLowerCase();
-  const scores = new Map();
-  for (const shard of availableShards) {
-    // project-<slug> shards score via their slug
-    const lex = SHARD_LEXICON[shard] || [];
-    let score = 0;
-    for (const kw of lex) {
-      if (lower.includes(kw)) score += 1;
-    }
-    if (shard.startsWith('project-')) {
-      const slug = shard.slice('project-'.length);
-      if (slug && lower.includes(slug.toLowerCase())) score += 3;
-    }
-    if (score > 0) scores.set(shard, score);
-  }
-  const ranked = [...scores.entries()].sort((a, b) => b[1] - a[1]).map(([s]) => s);
-  if (ranked.length >= 1) return ranked.slice(0, topN);
-  // Fallback: first N defaults in the shard set
-  return availableShards.slice(0, topN);
-}
-
-/**
- * Shard classifier — calls fastModel if adapter provided, else falls back to
- * the keyword heuristic. Budget < 200 tokens (§Δ24.2).
- */
-export async function classifyShards({
-  prompt,
-  availableShards,
-  adapter,
-  fastModel,
-  topN = 2,
-}) {
-  if (!adapter || !fastModel) {
-    return classifyShardsByKeyword(prompt, availableShards, topN);
-  }
-  const system = `You classify user queries into memory shards. Return ONLY a JSON array of up to ${topN} shard names from the provided list. No prose.`;
-  const user = `Available shards: ${JSON.stringify(availableShards)}
-Query: ${JSON.stringify(prompt)}
-Return JSON array of up to ${topN} most relevant shard names.`;
-  try {
-    const res = await adapter.call({
-      model: fastModel,
-      system,
-      messages: [{ role: 'user', content: user }],
-      maxTokens: 64,
-      effort: pickEffort({ scenario: 'recall' }),
-    });
-    const m = (res.text || '').match(/\[[\s\S]*?\]/);
-    if (!m) return classifyShardsByKeyword(prompt, availableShards, topN);
-    const arr = JSON.parse(m[0]);
-    const valid = arr.filter(s => typeof s === 'string' && availableShards.includes(s));
-    if (valid.length === 0) return classifyShardsByKeyword(prompt, availableShards, topN);
-    return valid.slice(0, topN);
-  } catch {
-    return classifyShardsByKeyword(prompt, availableShards, topN);
-  }
-}
-
-// ─── Step 2: In-shard candidate generation ──────────────────────
-
-function collectCandidates(memoryShardStore, { shards, kind, tags, pinned }) {
-  const filter = {};
-  if (shards && shards.length) filter.shard = shards.length === 1 ? shards[0] : shards;
-  if (kind) filter.kind = kind;
-  if (tags && tags.length) filter.tags = tags;
-  if (pinned !== undefined) filter.pinned = pinned;
-  const { results } = memoryShardStore.query(filter);
-  return results
-    // Drop superseded entries from the candidate pool (they stay on disk
-    // for memory_trace but should not compete for recall slots).
-    .filter(rec => !rec.supersededBy)
-    .slice(0, MAX_CANDIDATES);
-}
-
-// ─── Step 3: LLM Rerank ─────────────────────────────────────────
-
-async function llmRerank({ adapter, fastModel, prompt, candidates, memoryShardStore }) {
-  if (candidates.length <= MAX_RECALL_RESULTS) {
-    return candidates.map(c => c.id);
-  }
-  const lines = candidates.map((c, i) => {
-    return `${i + 1}. [id=${c.id}] shard=${c.shard} kind=${c.kind || '?'} tags=[${(c.tags || []).join(',')}]`;
-  }).join('\n');
-  const system = `You pick the most relevant memories for the user's prompt. Return ONLY a JSON array of entry ids (up to ${MAX_RECALL_RESULTS}). No prose.`;
-  const user = `User prompt: ${JSON.stringify(prompt)}
-
-Candidate memories:
-${lines}
-
-Return JSON array of up to ${MAX_RECALL_RESULTS} ids.`;
-  try {
-    const res = await adapter.call({
-      model: fastModel,
-      system,
-      messages: [{ role: 'user', content: user }],
-      maxTokens: 256,
-      effort: pickEffort({ scenario: 'recall' }),
-    });
-    const m = (res.text || '').match(/\[[\s\S]*\]/);
-    if (!m) return candidates.slice(0, MAX_RECALL_RESULTS).map(c => c.id);
-    const arr = JSON.parse(m[0]).filter(x => typeof x === 'string');
-    const valid = arr.filter(id => candidates.find(c => c.id === id));
-    if (valid.length === 0) return candidates.slice(0, MAX_RECALL_RESULTS).map(c => c.id);
-    return valid.slice(0, MAX_RECALL_RESULTS);
-  } catch {
-    return candidates.slice(0, MAX_RECALL_RESULTS).map(c => c.id);
-  }
-}
-
-// ─── Step 4: Inject (no sourceRef) ──────────────────────────────
-
-/**
- * Produce the body-only injection payload (§Δ24.5). Prefix lines with
- * `[mem:<shard>]` so the LLM knows the category without seeing the id.
- */
-export function formatForInjection(entries) {
-  return entries.map(e => {
-    const prefix = `[mem:${e.shard}]`;
-    const body = (e.body || '').trim();
-    return `${prefix} ${body}`;
-  }).join('\n\n');
-}
-
-// ─── Fingerprint cache ──────────────────────────────────────────
-
-const _cache = new Map();
-const CACHE_TTL = 5 * 60 * 1000;
-
-function computeFingerprint({ shards, prompt, taskId }) {
-  const head = prompt.slice(0, 200);
-  const input = `${shards.join(',')}|${head}|${taskId || ''}`;
-  return createHash('sha256').update(input).digest('hex').slice(0, 16);
-}
-
-// ─── Entry point ────────────────────────────────────────────────
-
-/**
- * Run the R6 4-step recall pipeline.
- *
- * @param {{
- *   prompt: string,
- *   memoryShardStore: object,           // openMemoryShardStore() handle
- *   adapter?: object,                   // LLM adapter (null = keyword-only)
- *   fastModel?: string,                 // fast model for classifier + rerank
- *   availableShards?: string[],         // defaults to store stats
- *   taskId?: string,
- *   kind?: string, tags?: string[], pinned?: boolean,
- * }} params
- * @returns {Promise<{entries: object[], shards: string[], fingerprint: string, cached: boolean}>}
- */
-export async function recallR6(params) {
-  const {
-    prompt,
-    memoryShardStore,
-    adapter,
-    fastModel,
-    availableShards,
-    taskId,
-    kind,
-    tags,
-    pinned,
-  } = params;
-
-  if (!prompt || !prompt.trim() || !memoryShardStore) {
-    return { entries: [], shards: [], fingerprint: '', cached: false };
-  }
-
-  const shardsFromStore = availableShards
-    || Object.keys(memoryShardStore.stats().shards);
-
-  if (shardsFromStore.length === 0) {
-    return { entries: [], shards: [], fingerprint: '', cached: false };
-  }
-
-  // Step 1
-  const chosenShards = await classifyShards({
-    prompt,
-    availableShards: shardsFromStore,
-    adapter,
-    fastModel,
-    topN: 2,
-  });
-
-  const fingerprint = computeFingerprint({ shards: chosenShards, prompt, taskId });
-  const cached = _cache.get(fingerprint);
-  if (cached && Date.now() - cached.t < CACHE_TTL) {
-    return { entries: cached.entries, shards: chosenShards, fingerprint, cached: true };
-  }
-
-  // Step 2
-  const candidates = collectCandidates(memoryShardStore, {
-    shards: chosenShards,
-    kind,
-    tags,
-    pinned,
-  });
-  if (candidates.length === 0) {
-    _cache.set(fingerprint, { entries: [], t: Date.now() });
-    return { entries: [], shards: chosenShards, fingerprint, cached: false };
-  }
-
-  // Step 3
-  const selectedIds = await llmRerank({
-    adapter, fastModel, prompt, candidates, memoryShardStore,
-  });
-
-  // Step 4 — load full bodies (minus sourceRef for injection).
-  const entries = [];
-  for (const id of selectedIds) {
-    const full = memoryShardStore.get(id);
-    if (!full) continue;
-    entries.push({
-      id: full.id,
-      shard: full.shard,
-      kind: full.kind,
-      body: full.body,
-      tags: full.tags || [],
-      // deliberately do NOT expose sourceRef here (§Δ23)
-    });
-  }
-  _cache.set(fingerprint, { entries, t: Date.now() });
-  return { entries, shards: chosenShards, fingerprint, cached: false };
-}
-
-export function clearR6RecallCache() {
-  _cache.clear();
-}
-
-export const R6_DEFAULTS = {
-  VP_DEFAULT_SHARDS,
-  FEATURE_SHARDS,
-  USER_SHARDS,
-};

package/unify/memory/recall-v2.js

@@ -1,258 +0,0 @@
-/**
- * memory/recall-v2.js — DESIGN-v2 Part II: scope-based memory recall.
- *
- * Recall under v2 is structurally different from R6: instead of selecting
- * individual entry shards by tag/keyword, we assemble per-scope `memory.md`
- * + `summary.md` for the scopes that are *known* to be relevant from the
- * current turn's context (always-include rules) plus the topic scopes whose
- * summary best matches the user's prompt keywords.
- *
- * Always-include scopes (no LLM):
- *   - user                              (every turn)
- *   - group/<groupId>                   (when groupId is provided)
- *   - vp/<vpId>                         (when vpId is provided AND not a foreign vp)
- *   - feature/<featureId>               (when featureId is provided)
- *
- * Topic scopes:
- *   - Score each topic by simple keyword overlap between the prompt's
- *     extracted keywords (via recall.js → extractKeywords) and the topic's
- *     `summary.md` body. Top-N by score join the bundle.
- *   - This is a heuristic — no LLM call. Topics that the dream pipeline
- *     created already correlate with the conversation's natural language,
- *     so a cheap keyword overlap is a good first cut.
- *
- * What this module deliberately does NOT do:
- *   - No LLM side-query. R6's recall.js does a 3rd-step LLM-select; v2
- *     skips it because the unit of selection is now whole scopes (5 + N
- *     topics) instead of dozens of individual entries.
- *   - No frontmatter parsing. memory.md is markdown; the dream-state tail
- *     marker is stripped before injection (so the LLM doesn't see internal
- *     bookkeeping bytes).
- *   - No write side effects. Pure read.
- *
- * Reference: agent/unify/memory/DESIGN-v2.md §6 (recall surface).
- */
-
-import { join } from 'path';
-import { promises as fsp, existsSync } from 'fs';
-
-import {
-  DEFAULT_MEMORY_ROOT, scopeDir, readMemory, readSummary,
-} from './store-v2.js';
-import { extractKeywords } from './recall.js';
-
-/** Default cap for how many topic scopes recall pulls in. */
-export const DEFAULT_TOPIC_LIMIT = 3;
-
-/** Marker block written by dream-v2/state.js — stripped from injection. */
-const DREAM_MARKER_RE = /\n*<!-- dream-state -->[\s\S]*?<!-- \/dream-state -->\s*$/;
-
-/**
- * Strip the trailing dream-state marker block (if any) from a memory.md body.
- *
- * @param {string} body
- * @returns {string}
- */
-export function stripDreamMarker(body) {
-  if (!body || typeof body !== 'string') return '';
-  return body.replace(DREAM_MARKER_RE, '').trimEnd();
-}
-
-/**
- * List all topic scopes present under <root>/topic/. Returns paths like
- * ['science', 'physics'] (level 1) or ['life', 'parenting'] (level 2).
- *
- * @param {string} root
- * @returns {Promise<string[][]>}
- */
-async function listTopicPaths(root) {
-  const out = [];
-  const topicRoot = join(root, 'topic');
-  if (!existsSync(topicRoot)) return out;
-  let l1Names;
-  try { l1Names = await fsp.readdir(topicRoot, { withFileTypes: true }); }
-  catch { return out; }
-  for (const e1 of l1Names) {
-    if (!e1.isDirectory()) continue;
-    if (e1.name.startsWith('.')) continue;
-    // Level-1 topic is itself a scope (memory.md may sit at this level).
-    out.push([e1.name]);
-    // Walk one more level.
-    let l2Names;
-    try { l2Names = await fsp.readdir(join(topicRoot, e1.name), { withFileTypes: true }); }
-    catch { continue; }
-    for (const e2 of l2Names) {
-      if (!e2.isDirectory()) continue;
-      if (e2.name.startsWith('.')) continue;
-      out.push([e1.name, e2.name]);
-    }
-  }
-  return out;
-}
-
-/**
- * Score a topic by how many of its summary's tokens overlap the prompt's
- * keyword set. Topics with no summary score 0.
- *
- * @param {string} summary
- * @param {Set<string>} keywordSet
- * @returns {number}
- */
-function scoreTopic(summary, keywordSet) {
-  if (!summary || keywordSet.size === 0) return 0;
-  const tokens = (summary.toLowerCase()
-    .match(/[\p{L}\p{N}_-]+/gu) || [])
-    .filter(t => t.length > 1);
-  if (tokens.length === 0) return 0;
-  let hits = 0;
-  for (const t of tokens) {
-    if (keywordSet.has(t)) hits += 1;
-  }
-  return hits;
-}
-
-/**
- * @typedef {Object} RecallV2Section
- * @property {string} scope         — human label, e.g. "user", "group/g-eng"
- * @property {string} kind          — 'user' | 'vp' | 'group' | 'feature' | 'topic'
- * @property {string} memory        — memory.md body (dream marker stripped)
- * @property {string} summary       — summary.md body
- */
-
-/**
- * @typedef {Object} RecallV2Result
- * @property {RecallV2Section[]} sections
- * @property {string[]} keywords
- * @property {string} formatted     — ready to splice into the system prompt
- */
-
-/**
- * Build a scope label suitable for the formatted block heading.
- *
- * @param {import('./store-v2.js').Scope} scope
- * @returns {string}
- */
-export function scopeLabel(scope) {
-  if (scope.kind === 'user') return 'user';
-  if (scope.kind === 'topic') return `topic/${(scope.path || []).join('/')}`;
-  return `${scope.kind}/${scope.id || ''}`;
-}
-
-/**
- * Format the bundle for direct injection into the system prompt.
- *
- * @param {RecallV2Section[]} sections
- * @returns {string}
- */
-export function formatRecallV2(sections) {
-  if (!sections || sections.length === 0) return '';
-  const blocks = [];
-  for (const s of sections) {
-    const memBlock = s.memory ? s.memory.trim() : '';
-    const sumBlock = s.summary ? s.summary.trim() : '';
-    if (!memBlock && !sumBlock) continue;
-    const parts = [`### ${s.scope}`];
-    if (sumBlock) parts.push(`**Summary**\n${sumBlock}`);
-    if (memBlock) parts.push(`**Memory**\n${memBlock}`);
-    blocks.push(parts.join('\n\n'));
-  }
-  if (blocks.length === 0) return '';
-  return ['## Recalled Memory (v2)', ...blocks].join('\n\n');
-}
-
-/**
- * Read one scope's pair (memory.md + summary.md) and translate to a section.
- * Returns null when both files are empty/missing or VP ACL refuses.
- *
- * @param {import('./store-v2.js').Scope} scope
- * @param {{ root: string, currentVpId?: string }} opts
- * @returns {Promise<RecallV2Section|null>}
- */
-async function readScopeSection(scope, opts) {
-  let memory = '';
-  let summary = '';
-  try { memory = stripDreamMarker(await readMemory(scope, opts)); }
-  catch { return null; } // VP ACL or other → skip silently
-  try { summary = await readSummary(scope, opts); } catch { /* */ }
-  if (!memory && !summary) return null;
-  return {
-    scope: scopeLabel(scope),
-    kind: scope.kind,
-    memory,
-    summary,
-  };
-}
-
-/**
- * Recall v2: assemble per-scope memory.md + summary.md for the current turn.
- *
- * @param {Object} params
- * @param {string} params.prompt                    — the user's turn prompt
- * @param {string} [params.root]                    — memory root (defaults to DEFAULT_MEMORY_ROOT)
- * @param {string} [params.groupId]                 — active group, if any
- * @param {string} [params.vpId]                    — active VP for this turn (NOT used as ACL)
- * @param {string} [params.currentVpId]             — current session's VP, gates vp/<other> reads
- * @param {string} [params.featureId]               — active feature, if any
- * @param {number} [params.topicLimit]              — cap on topic scopes (default DEFAULT_TOPIC_LIMIT)
- * @returns {Promise<RecallV2Result>}
- */
-export async function recallV2({
-  prompt,
-  root = DEFAULT_MEMORY_ROOT,
-  groupId,
-  vpId,
-  currentVpId,
-  featureId,
-  topicLimit = DEFAULT_TOPIC_LIMIT,
-} = {}) {
-  const sections = [];
-  const opts = { root, currentVpId };
-  const keywords = extractKeywords(prompt || '');
-
-  // Always: user.
-  const userSec = await readScopeSection({ kind: 'user' }, opts);
-  if (userSec) sections.push(userSec);
-
-  // Conditional: group/<groupId>
-  if (groupId && typeof groupId === 'string' && groupId !== '_no-group') {
-    const sec = await readScopeSection({ kind: 'group', id: groupId }, opts);
-    if (sec) sections.push(sec);
-  }
-
-  // Conditional: vp/<vpId>
-  if (vpId && typeof vpId === 'string') {
-    const sec = await readScopeSection({ kind: 'vp', id: vpId }, opts);
-    if (sec) sections.push(sec);
-  }
-
-  // Conditional: feature/<featureId>
-  if (featureId && typeof featureId === 'string') {
-    const sec = await readScopeSection({ kind: 'feature', id: featureId }, opts);
-    if (sec) sections.push(sec);
-  }
-
-  // Topics: rank by keyword overlap on summary.
-  if (topicLimit > 0 && keywords.length > 0) {
-    const keywordSet = new Set(keywords.map(k => k.toLowerCase()));
-    const candidates = [];
-    const paths = await listTopicPaths(root);
-    for (const path of paths) {
-      const scope = { kind: 'topic', path };
-      let summary = '';
-      try { summary = await readSummary(scope, opts); } catch { /* */ }
-      const score = scoreTopic(summary, keywordSet);
-      if (score > 0) candidates.push({ scope, score });
-    }
-    candidates.sort((a, b) => b.score - a.score);
-    for (const c of candidates.slice(0, topicLimit)) {
-      const sec = await readScopeSection(c.scope, opts);
-      if (sec) sections.push(sec);
-    }
-  }
-
-  return {
-    sections,
-    keywords,
-    formatted: formatRecallV2(sections),
-  };
-}