pi-memory-evolution 0.2.0

package/src/memory/progress-targets.ts

@@ -0,0 +1,52 @@
+import type { DurableMemory } from './memory-store.ts';
+import type { OperationResource } from '../adapter/operations.ts';
+import { queryFeatures, queryText, type RecallInput } from './query.ts';
+import { features } from './search.ts';
+import { clipBytes, redact } from './privacy.ts';
+
+const GENERIC_NAMES = new Set(['work','home','tmp','src','test','tests','docs','project','projects','repo','repository','node_modules']);
+const ESCAPE = /[.*+?^${}()|[\]\\]/gu;
+const genericTopic = new Set(['优化','完善','排查','任务','工作','实现','完成','进行','继续','接着','core','requirements','requirement','implement','optimize','finish']);
+const pending = /待|尚未|未完成|未提交|未推送|未验证|进行中|仍在|\b(?:pending|not (?:yet |final |fully )?(?:committed|pushed|accepted|verified|complete)|in (?:progress|validation)|validation\/tuning)\b/iu;
+function names(text: string, name: string): boolean {
+ return name.length >= 3 && !GENERIC_NAMES.has(name.toLowerCase())
+  && new RegExp(`(?<![\\p{L}\\p{N}_-])${name.replace(ESCAPE,'\\$&')}(?![\\p{L}\\p{N}_-])`, 'iu').test(text);
+}
+
+/** Update nomination is deliberately separate from answering a question. It retains
+ * affected/stale state candidates, not only top-2 near-duplicate answer snippets.
+ * Resource identity nominates; it never verifies success or authorizes cross-origin writes. */
+export function nominateProgress(memories: readonly DurableMemory[], input: { scope: string; query: RecallInput; resources: readonly OperationResource[] }, limit = 8) {
+ const topic = new Set([...queryFeatures(queryText(input.query))].filter(w => !genericTopic.has(w)));
+ const resources = [...new Map(input.resources.map(r => [r.path, r])).values()].slice(0,16);
+ const rows = memories.map(memory => {
+  let reason = memory.scope !== input.scope ? 'other-origin' : memory.kind !== 'project_state' ? 'not-project-state'
+   : memory.layer === 'pinned' ? 'pinned' : ['forgotten','conflicted'].includes(memory.status) || memory.feedback?.accuracy?.verdict === 'incorrect' ? 'suppressed' : '';
+  const body = features(memory.content), aliases = features((memory.searchTerms ?? []).join(' '));
+  let resourceScore = 0, resourceReason = '', resourceConflict = false;
+  for (const resource of resources) {
+   const path = resource.path.toLowerCase();
+   const literals = [...body].filter(w => w.startsWith('literal:/')).map(w => w.slice(8));
+   const exact = literals.some(l => l === path || (resource.kind === 'directory' && l.startsWith(path + '/')));
+   const named = resource.kind === 'directory' && names(memory.content, resource.name);
+   // Equal basenames of explicitly different absolute resources are not identity.
+   const conflictingPath = literals.some(l => names(l, resource.name) && l !== path && !l.startsWith(path + '/'));
+   resourceConflict ||= conflictingPath;
+   const score = exact ? 60 : named && !conflictingPath ? 50 : 0;
+   if (score > resourceScore) { resourceScore = score; resourceReason = exact ? 'operation-resource' : 'explicit-project-name'; }
+  }
+  const matched = [...topic].filter(w => body.has(w) || aliases.has(w));
+  const coverage = topic.size ? matched.length / topic.size : 0;
+  const topical = matched.length >= 2 || (topic.size === 1 && matched.length === 1);
+  const relevant = resourceScore > 0 || (!resourceConflict && topical && coverage >= 0.3);
+  if (!reason) reason = relevant ? resourceReason || 'user-topic' : resourceConflict ? 'resource-conflict' : 'unrelated';
+  const eligible = relevant && ['operation-resource','explicit-project-name','user-topic'].includes(reason);
+  const score = resourceScore + Math.min(matched.length, 8) * 2 + (eligible && pending.test(memory.content) ? 20 : 0);
+  return { memory, reason, eligible, score };
+ });
+ rows.sort((a,b) => Number(b.eligible)-Number(a.eligible) || b.score-a.score
+  || Date.parse(a.memory.updatedAt)-Date.parse(b.memory.updatedAt) || a.memory.id.localeCompare(b.memory.id));
+ const selected = rows.filter(r => r.eligible).slice(0,Math.max(0,Math.min(8,limit))).map(r => r.memory.id);
+ return { targets: selected, diagnostics: { mode: 'operation-and-topic', resources: resources.map(r => ({ path: clipBytes(redact(r.path),160), kind:r.kind })),
+  eligible: rows.filter(r=>r.eligible).length, selected, candidates: rows.slice(0,16).map(r=>({id:clipBytes(redact(r.memory.id),120),score:r.score,reason:r.eligible&&!selected.includes(r.memory.id)?'candidate-limit':r.reason})) } };
+}

package/src/memory/quality.ts

@@ -0,0 +1,81 @@
+import type { DurableMemory, MemoryKind, Source } from "./memory-store.ts";
+
+export type EvidenceBasis = "summary" | "user_statement" | "tool_observation" | "manual_correction";
+export interface Evidence {
+	basis: EvidenceBasis;
+	method: "local" | "model" | "manual";
+	sourceId: string;
+	at: string;
+}
+export type FeedbackVerdict = "useful" | "unhelpful" | "accurate" | "incorrect";
+export interface FeedbackSignal { verdict: FeedbackVerdict; at: string; sourceId: string }
+export interface MemoryFeedback { utility?: FeedbackSignal; accuracy?: FeedbackSignal }
+export const FEEDBACK_VERDICTS = new Set<FeedbackVerdict>(["useful", "unhelpful", "accurate", "incorrect"]);
+const date = (v: unknown) => typeof v === "string" && Number.isFinite(Date.parse(v));
+const identifier = (v: unknown) => typeof v === "string" && v.length > 0 && v.length <= 512 && !/[\u0000-\u001f]/u.test(v);
+
+export function validEvidence(value: unknown): value is Evidence | undefined {
+	if (value === undefined) return true;
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const e = value as Evidence;
+	return Object.keys(e).every(k => ["basis", "method", "sourceId", "at"].includes(k))
+		&& ["summary", "user_statement", "tool_observation", "manual_correction"].includes(e.basis)
+		&& ["local", "model", "manual"].includes(e.method) && identifier(e.sourceId) && date(e.at)
+		&& (e.basis === "manual_correction" ? e.method === "manual"
+			: e.basis === "summary" ? e.method !== "manual" : e.method === "model");
+}
+export function validFeedback(value: unknown): value is MemoryFeedback | undefined {
+	if (value === undefined) return true;
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	return Object.entries(value).every(([key, signal]) => {
+		if (!["utility", "accuracy"].includes(key) || !signal || typeof signal !== "object" || Array.isArray(signal)) return false;
+		const s = signal as FeedbackSignal;
+		return Object.keys(s).every(k => ["verdict", "at", "sourceId"].includes(k)) && date(s.at) && identifier(s.sourceId)
+			&& (key === "utility" ? ["useful", "unhelpful"].includes(s.verdict) : ["accurate", "incorrect"].includes(s.verdict));
+	});
+}
+export function sourceEvidence(source: Source, method: "local" | "model"): Evidence {
+	return { basis: source.kind === "user" ? "user_statement" : source.kind === "progress" ? "tool_observation" : "summary",
+		method, sourceId: source.id, at: source.createdAt };
+}
+
+/** An ordinal evidence policy, NOT a probability, verification or model self-confidence.
+ * User statements are especially appropriate for preferences, not proof of execution. */
+export function evidencePriority(kind: MemoryKind, basis?: EvidenceBasis): number {
+	if (basis === "manual_correction") return 4;
+	if (basis === "user_statement") return kind === "preference" || kind === "decision" ? 3 : 2;
+	if (basis === "tool_observation") return kind === "project_state" ? 3 : 1;
+	return basis === "summary" ? 1 : 0;
+}
+export function mayReplace(old: DurableMemory, incoming: Evidence): boolean {
+	const priority = evidencePriority(old.kind, old.evidence?.basis);
+	const protectedPriority = old.status === "confirmed" || old.feedback?.accuracy?.verdict === "accurate" ? Math.max(4, priority) : priority;
+	// Explicit current user corrections can replace prior manual corrections; summaries cannot.
+	return incoming.basis === "user_statement" || (old.kind === "project_state" && incoming.basis === "tool_observation")
+		|| evidencePriority(old.kind, incoming.basis) >= protectedPriority;
+}
+
+const DAY = 86400_000;
+/** No new expiry for stable facts/preferences/decisions and no revival of old states.
+ * Floors preserve old useful knowledge; project states retain their seven-day safety cap. */
+export const AGING: Record<MemoryKind, { halfLifeDays: number; floor: number; expiresDays?: number }> = {
+	project_state: { halfLifeDays: 3, floor: 0.5, expiresDays: 7 },
+	fact: { halfLifeDays: 90, floor: 0.75 },
+	decision: { halfLifeDays: 180, floor: 0.85 },
+	preference: { halfLifeDays: 365, floor: 0.95 },
+};
+export function memoryQuality(memory: DurableMemory, now = Date.now()) {
+	const policy = AGING[memory.kind];
+	const ageDays = Math.max(0, (now - Date.parse(memory.updatedAt)) / DAY);
+	const pinned = memory.layer === "pinned";
+	const freshness = pinned ? 1 : policy.floor + (1 - policy.floor) * 2 ** (-ageDays / policy.halfLifeDays);
+	const expired = !pinned && policy.expiresDays !== undefined && ageDays > policy.expiresDays;
+	const basis = memory.evidence?.basis ?? "unknown";
+	const priority = evidencePriority(memory.kind, memory.evidence?.basis);
+	const evidenceWeight = 1 + priority * 0.04;
+	// Last explicit verdict wins, not frequency. Usefulness never increases evidence priority.
+	const utility = memory.feedback?.utility?.verdict === "useful" ? 1.05 : memory.feedback?.utility?.verdict === "unhelpful" ? 0.9 : 1;
+	const accuracy = memory.feedback?.accuracy?.verdict === "accurate" ? 1.05 : memory.feedback?.accuracy?.verdict === "incorrect" ? 0.5 : 1;
+	return { basis, method: memory.evidence?.method ?? "unknown", ageDays, freshness, expired,
+		evidenceWeight, utility, accuracy, factor: freshness * evidenceWeight * utility * accuracy };
+}

package/src/memory/query.ts

@@ -0,0 +1,87 @@
+import { clipBytes, redact } from './privacy.ts';
+import { features, transformProse } from './search.ts';
+
+export interface RecallQuery {
+ query: string;
+ /** Supporting subject only: the current query remains mandatory when refining it. */
+ context?: string;
+ mode: 'direct' | 'followup' | 'empty' | 'reset';
+}
+export type RecallInput = string | RecallQuery;
+const RESET = /换个话题|新话题|从头开始|不是那个|不是这个|\b(?:new topic|start over|forget that|not that|not this)\b/iu;
+const FOLLOWUP = /继续|接着|接上|这个|那个|它|其|呢[？?。.!]*$|\b(?:this|that|its?|their|continue|resume|what about|how about)\b/iu;
+const FILLER = /为什么|什么|多少|这个|那个|这些|那些|这里|那里|换个话题|新话题|从头开始|不是那个|不是这个|不对|不行|有错|错误|好的|好吧|没错|没问题|有没有|会不会|是不是|能不能|需不需要|还能|你要|我要|记得|回忆|接着|接上|未完成|未完|没完成|刚才|以后|看下|做完|开干|开始|讨论|聊聊|帮我|一下|事情|怎么说|说过|[我你它的了呢吗吧啊呀么那这]|\b(?:go ahead|proceed|okay|ok|thanks|thank you|start over|new topic|forget that)\b/giu;
+// These express the act of asking, not a subject. Query-only: stored evidence is intact.
+const DISCOURSE = new Set(`有 无 还 好 也 能 会 要 是 很 都 请 先 再 与 就 对 嗯 哦 啊 说 相关 有关 还有 其他 这里 那里 自动 不会 能够 不能 系统 具体 详细 详情 信息 内容 记录 历史 当时 previously still related relevant regarding discussion discussed conversation conversations talked talking said remind reminder reminders details detail information history historical matter matters earlier already exactly know known tell us let's lets please could would does did can you our your about`.split(/\s+/u));
+const WEAK = new Set(['配置', '设置', 'config', 'configuration', 'settings', 'setup']);
+// Facets can refine an established subject; they cannot make a new named subject inherit
+// unrelated context. This is a grammatical/attribute vocabulary, not a domain allowlist.
+export const FACETS = new Set([...features('端口 认证 进度 版本 超时 价格 状态 路径 输出 输入 安装 连接 性能 错误 port auth progress version timeout price status path output input installation connection performance error')]);
+const clean = (text: string) => clipBytes(redact(text), 2048).trim();
+
+/** Asking to retrieve an existing memory is not an instruction to learn a new one. */
+export function isRecallQuestion(text: string): boolean {
+ return /记得|回忆|\b(?:you\s+(?:still\s+)?(?:remember|recall)|remind\s+me|memories\s+(?:about|of|on|related))\b/iu.test(text);
+}
+
+export function queryFeatures(text: string): Set<string> {
+ const normalized = transformProse(clean(text), prose => {
+  // Remove recall-request framing, not technical subjects such as memory recall systems.
+  let value = prose
+   .replace(/(?:相关|有关)(?:的)?记忆/gu, ' ')
+   .replace(/关于([\s\S]+?)的(?:记忆|印象)/gu, '$1')
+   .replace(/\bmemories\s+(?:(?:related|relevant)\s+to|about|of|on|regarding)\b/giu, ' ')
+   .replace(/\b(?:do|can|could|would|will)?\s*you\s+(?:still\s+)?recall\b/giu, ' ')
+   .replace(/\bremind\s+me\b/giu, ' ');
+  if (/记得|回忆/u.test(value) && !/记忆(?:系统|库|召回|检索|注入|算法)/u.test(value)) value = value.replace(/记忆/gu, ' ');
+  return value.replace(FILLER, ' ');
+ });
+ // Keep unindexed single-character subjects on the query side as barriers rather
+ // than mistaking them for a topic-less continuation. They earn no fragment matches.
+ const result = features(normalized, true);
+ for (const word of result) {
+  if (DISCOURSE.has(word) || WEAK.has(word)) result.delete(word);
+  // A qualified path is one constraint, not a second vote for its shared basename.
+  if (word.startsWith('literal:') && word.includes('/')) result.delete(`literal:${word.split('/').at(-1)}`);
+ }
+ return result;
+}
+
+function advance(current: string, previous?: RecallQuery): RecallQuery {
+ const terms = queryFeatures(current);
+ if (RESET.test(current)) return { query: terms.size ? current : '', mode: 'reset' };
+ if (!terms.size) return previous?.query ? { ...previous, mode: 'followup' } : { query: '', mode: 'empty' };
+ if (previous?.query && FOLLOWUP.test(current)) {
+  const prior = queryFeatures(queryText(previous));
+  const subject = [...terms].filter(term => !FACETS.has(term));
+  if (subject.every(term => prior.has(term))) {
+   // Keep the established subject, not a growing trail of older attribute questions.
+   const context = previous.context ?? previous.query;
+   if (queryFeatures(context).size && context !== current) return { query: current, context, mode: 'followup' };
+  }
+ }
+ return { query: current, mode: 'direct' };
+}
+
+/** Replay only bounded active-user context, oldest first, so chained refinements retain
+ * their subject and explicit new/reset topics form barriers. No corpus or assistant text. */
+export function resolveRecallQuery(prompt: string, recentUsers: readonly string[] = []): RecallQuery {
+ const current = clean(prompt);
+ let previous: RecallQuery | undefined;
+ for (const text of recentUsers.slice(-6)) {
+  const value = clean(text);
+  // Pi may already include this turn in its active context.
+  if (value !== current) previous = advance(value, previous);
+ }
+ return advance(current, previous);
+}
+
+export function queryText(input: RecallInput): string {
+ return typeof input === 'string' ? input : [input.query, input.context].filter(Boolean).join('\n');
+}
+
+/** String facade retained for callers that only need the resolved topic text. Runtime
+ * retrieval uses the structured plan to keep current focus separate from context. */
+export function recallQuery(prompt: string, recentUsers: readonly string[] = []): string {
+ return queryText(resolveRecallQuery(prompt, recentUsers));
+}

package/src/memory/recovery.ts

@@ -0,0 +1,23 @@
+/** Bounded background work; retries are persisted by MemoryStore, not session timers. */
+export const EVOLUTION_TIMEOUT_MS = 120_000;
+export const EVOLUTION_MAX_TOKENS = 8192;
+export const RECOVERY_POLL_MS = 15_000;
+export const LEASE_GRACE_MS = 30_000;
+export const MAX_FAILURES = 5;
+const RETRY_DELAYS_MS = [60_000, 300_000, 900_000, 3_600_000];
+
+export const FAILURE_CODES = ["timeout", "cancelled", "output_limit", "invalid_output", "stale", "write_rejected", "unavailable", "provider", "interrupted", "unknown"] as const;
+export type FailureCode = typeof FAILURE_CODES[number];
+
+/** Never persist raw exception messages/provider bodies (they may contain secrets). */
+export class EvolutionError extends Error {
+	readonly code: FailureCode;
+	constructor(code: FailureCode) { super(`Memory evolution: ${code}`); this.code = code; }
+}
+export function failureCode(error: unknown, signal?: AbortSignal): FailureCode {
+	if (signal?.aborted) return signal.reason?.name === "TimeoutError" ? "timeout" : "cancelled";
+	return error instanceof EvolutionError ? error.code : "unknown";
+}
+export function retryAt(failures: number, now: number): number {
+	return failures >= MAX_FAILURES ? 0 : now + RETRY_DELAYS_MS[Math.max(0, failures - 1)]!;
+}

package/src/memory/retriever.ts

@@ -0,0 +1,181 @@
+import type { DurableMemory } from "./memory-store.ts";
+import { clipBytes, fingerprint, redact } from "./privacy.ts";
+import { features, featureOffset } from "./search.ts";
+import { memoryQuality } from "./quality.ts";
+import { FACETS, queryFeatures, resolveRecallQuery, type RecallInput } from "./query.ts";
+export { recallQuery, resolveRecallQuery } from "./query.ts";
+
+function overlap(text: string, query: Set<string>): number {
+	const tokens = features(text);
+	return [...query].filter((word) => tokens.has(word)).length;
+}
+
+/** Relevance scores are NOT confidence/truth scores. No authority bonus for cwd,
+ * legacy labels, source IDs or dates. Metadata can only help an explicit origin query. */
+type RecallOptions = { includeExpiredProjectState?: boolean };
+type RankedMemory = { memory: DurableMemory; score: number; rankScore: number; quality: ReturnType<typeof memoryQuality>; coverage: number; matches: string[]; reason?: string };
+export interface RecallDiagnostics {
+	mode: string;
+	query: string[];
+	context: string[];
+	eligible: number;
+	excluded: number;
+	matched: number;
+	selected: string[];
+	candidates: { id: string; score: number; rankScore: number; quality: ReturnType<typeof memoryQuality>; coverage: number; matches: string[]; reason: string }[];
+	exclusions?: { id: string; reason: string }[];
+}
+
+function evaluate(memories: readonly DurableMemory[], prompt: RecallInput, now: number, options: RecallOptions) {
+	const plan = typeof prompt === 'string' ? resolveRecallQuery(prompt) : prompt;
+	const query = queryFeatures(plan.query);
+	const context = queryFeatures(plan.context ?? '');
+	for (const word of query) context.delete(word);
+	const qualities = new Map(memories.map(m => [m.id, memoryQuality(m, now)]));
+	const excludedReason = (m: DurableMemory) => ["forgotten", "conflicted"].includes(m.status) ? m.status
+		: m.feedback?.accuracy?.verdict === "incorrect" ? "disputed"
+		: !options.includeExpiredProjectState && qualities.get(m.id)!.expired ? "expired-project-state" : undefined;
+	const active = memories.filter(m => !excludedReason(m));
+	const diagnostics: RecallDiagnostics = { mode: plan.mode, query: [...query].slice(0, 32), context: [...context].slice(0, 32),
+		eligible: active.length, excluded: memories.length - active.length, matched: 0, selected: [], candidates: [],
+		exclusions: memories.filter(m => excludedReason(m)).slice(0, 10).map(m => ({ id: clipBytes(redact(m.id), 120), reason: excludedReason(m)! })) };
+	if (!query.size) return { ranked: [] as RankedMemory[], diagnostics };
+	// Repeated origins/aliases (and duplicate legacy text) need segmentation only once
+	// per query. No persistent cache of user queries or credential-bearing input.
+	const cache = new Map<string, Set<string>>();
+	const tokenize = (text: string) => {
+		let result = cache.get(text);
+		if (!result) { result = features(text); cache.set(text, result); }
+		return result;
+	};
+	const documents = active.map((memory) => ({ memory,
+		// A quoted question in an incident/replay note is a mention, not its answer.
+		body: tokenize(memory.content.replace(/“[^”\n]*[?？]”|「[^」\n]*[?？]」|"[^"\n]*[?？]"/gu, ' ')),
+		mentions: tokenize(memory.content),
+		aliases: tokenize((memory.searchTerms ?? []).join(" ")),
+		origin: new Set(memory.scope === "legacy" ? [] : [...tokenize(memory.scope),
+			...tokenize(memory.scope.split(/[\\/]/u).at(-1) ?? "")].filter((word) => !word.startsWith("concept:"))) }));
+	const unknown = new Set<string>();
+	const weights = new Map([...query, ...context].map((word) => {
+		const df = documents.filter((d) => d.mentions.has(word) || d.aliases.has(word) || d.origin.has(word)).length;
+		if (!df) unknown.add(word);
+		// No evidence is not rare evidence: unseen question words must not receive
+		// the largest IDF. Exact resource constraints and thin-match gates still apply.
+		return [word, (word.startsWith("literal:") ? 2 : 1) * (df ? 1 + Math.log((documents.length + 1) / (df + 1)) : 1)];
+	}));
+	const total = [...query].reduce((sum, word) => sum + weights.get(word)!, 0);
+	const literals = [...query, ...context].filter(word => word.startsWith('literal:'));
+	const subjects = [...context].filter(word => !FACETS.has(word));
+	const subjectWeight = subjects.reduce((sum, word) => sum + weights.get(word)!, 0);
+	const namedSubjects = subjects.filter(word => !word.startsWith('concept:'));
+	// A short named-subject attribute query must not substitute another subject or
+	// another attribute when its best answer has been forgotten/quarantined.
+	// Generic status/progress words describe the request, not a required answer token.
+	const directNames = [...query].filter(word => !word.startsWith('concept:') && !word.startsWith('literal:') && !/^\d/u.test(word) && !FACETS.has(word));
+	const directFacets = [...query].filter(word => FACETS.has(word) && !['concept:status', 'concept:progress', 'error', '错误'].includes(word));
+	const focusedDirect = !context.size && query.size <= 4 && directNames.length === 1 && directFacets.length > 0;
+	const evaluated: RankedMemory[] = documents.map(({ memory, body, mentions, aliases, origin }) => {
+		let score = 0, covered = 0, focusMatches = 0, evidenceMatches = 0;
+		const matches: string[] = [];
+		for (const [word, weight] of weights) {
+			const factor = body.has(word) ? 1 : aliases.has(word) ? 0.8 : mentions.has(word) ? 0.25 : origin.has(word) ? 0.2 : 0;
+			if (factor) {
+				score += weight * factor * (query.has(word) ? 1 : 0.35);
+				if (query.has(word)) {
+					covered += weight; focusMatches++;
+					if (body.has(word) || aliases.has(word) || origin.has(word)) evidenceMatches++;
+				}
+				matches.push(word);
+			}
+		}
+		// Mild length normalization rewards focused evidence without erasing useful
+		// long claims or letting brevity overcome a missing subject/constraint.
+		score *= 0.8 + 0.2 * Math.min(1, 12 / Math.max(1, body.size));
+		const coverage = covered / total;
+		const reason = literals.some(word => !matches.includes(word)) ? 'resource-mismatch'
+			: !focusMatches ? 'no-focus-match'
+			: !evidenceMatches ? 'question-only'
+			: focusedDirect && (directNames.some(word => !body.has(word) && !aliases.has(word) && !origin.has(word))
+				|| directFacets.some(word => !body.has(word) && !aliases.has(word))) ? 'subject-attribute-mismatch'
+			: (namedSubjects.length ? namedSubjects.some(word => !matches.includes(word))
+				: subjects.length && subjects.filter(word => matches.includes(word)).reduce((sum, word) => sum + weights.get(word)!, 0) / subjectWeight < 0.6) ? 'context-mismatch'
+			: coverage < 0.45 ? 'low-coverage'
+			: (query.size >= 3 && focusMatches < 2) || (focusMatches === 1 && [...query].some(word => unknown.has(word) && !FACETS.has(word))) ? 'thin-match'
+			: undefined;
+		const quality = qualities.get(memory.id)!;
+		return { memory, score, rankScore: score * quality.factor, quality, coverage, matches, reason };
+	});
+	const best = evaluated.reduce((best, r) => !r.reason ? Math.max(best, r.score) : best, 0);
+	// Quality only orders already-relevant evidence. It cannot rescue weak matches.
+	for (const item of evaluated) if (!item.reason && item.score < best * 0.75) item.reason = 'relative-cutoff';
+	evaluated.sort((a,b) => b.rankScore-a.rankScore || Number(b.memory.layer === "pinned")-Number(a.memory.layer === "pinned")
+		|| Date.parse(b.memory.updatedAt)-Date.parse(a.memory.updatedAt) || a.memory.id.localeCompare(b.memory.id));
+	const ranked = evaluated.filter(r => !r.reason);
+	diagnostics.matched = ranked.length;
+	diagnostics.candidates = evaluated.filter(r => r.score > 0).slice(0, 10).map(r => ({ id: clipBytes(redact(r.memory.id), 120),
+		score: Number(r.score.toFixed(3)), rankScore: Number(r.rankScore.toFixed(3)), quality: r.quality,
+		coverage: Number(r.coverage.toFixed(3)), matches: r.matches.slice(0, 16), reason: r.reason ?? 'eligible' }));
+	return { ranked, diagnostics };
+}
+
+export function rankMemories(memories: readonly DurableMemory[], prompt: RecallInput, now = Date.now(), options: RecallOptions = {}) {
+	return evaluate(memories, prompt, now, options).ranked;
+}
+
+function selectRanked(ranked: RankedMemory[], limit: number): DurableMemory[] {
+	if (limit <= 0) return [];
+	const selected: DurableMemory[] = [];
+	const seen = new Set<string>();
+	const covered = new Map<string, Set<string>>();
+	for (const { memory, matches } of ranked) {
+		const key = fingerprint(JSON.stringify([memory.scope, memory.content]));
+		if (seen.has(key)) continue;
+		// For specific multi-feature questions, don't spend another slot repeating the
+		// same matched facets from the same origin. Different origins remain distinct.
+		// A progress note mentioning a question must not hide a preference/fact that
+		// answers it. Facet diversity is tracked separately for each evidence kind.
+		const facetKey = JSON.stringify([memory.scope, memory.kind]);
+		const previous = covered.get(facetKey) ?? new Set<string>();
+		if (matches.length >= 2 && ranked[0].matches.length >= 3 && matches.every((term) => previous.has(term))) continue;
+		seen.add(key); matches.forEach((term) => previous.add(term)); covered.set(facetKey, previous);
+		selected.push(memory);
+		if (selected.length >= limit) break;
+	}
+	return selected;
+}
+
+/** One evaluation for both injection and transient diagnostics; never persists queries. */
+export function retrieveMemories(memories: readonly DurableMemory[], prompt: RecallInput, limit = 3, now = Date.now(), options: RecallOptions = {}) {
+	const { ranked, diagnostics } = evaluate(memories, prompt, now, options);
+	const selected = selectRanked(ranked, limit);
+	diagnostics.selected = selected.map(m => clipBytes(redact(m.id), 120));
+	for (const item of diagnostics.candidates) if (item.reason === 'eligible') {
+		item.reason = diagnostics.selected.includes(item.id) ? 'selected' : 'selection-limit-or-redundancy';
+	}
+	return { selected, diagnostics };
+}
+
+export function selectRelevantMemories(memories: readonly DurableMemory[], prompt: RecallInput, limit = 3, now = Date.now(), options: RecallOptions = {}): DurableMemory[] {
+	return retrieveMemories(memories, prompt, limit, now, options).selected;
+}
+
+/** Use the matching sentence instead of blindly cutting off the beginning. */
+export function excerpt(content: string, prompt: RecallInput, budget = 400): string {
+	const clean = redact(content).trim();
+	if (Buffer.byteLength(clean) <= budget) return clean;
+	if (budget <= 3) return clipBytes(clean, Math.max(0, budget));
+	const query = queryFeatures(typeof prompt === 'string' ? prompt : prompt.query);
+	const context = queryFeatures(typeof prompt === 'string' ? '' : prompt.context ?? '');
+	const sentences = clean.split(/(?<=[。！？!?])\s*|(?<=\.)\s+|\n+/u).filter(Boolean);
+	sentences.sort((a,b) => overlap(b, query)-overlap(a, query) || overlap(b, context)-overlap(a, context));
+	const best = sentences[0] ?? clean;
+	if (Buffer.byteLength(best) <= budget - 3) return best + "…";
+	const positions = [...query].map((word) => featureOffset(best, word)).filter((index) => index >= 0);
+	const offset = positions.length ? Math.min(...positions) : 0;
+	// Keep a little preceding context, cutting only at code-point boundaries.
+	const reversed = [...best.slice(0, offset)].reverse().join("");
+	const prefix = [...clipBytes(reversed, Math.floor((budget - 6) / 3))].reverse().join("");
+	const start = offset - prefix.length;
+	const lead = start > 0 && budget >= 6 ? "…" : "";
+	return lead + clipBytes(best.slice(start), budget - Buffer.byteLength(lead) - 3) + "…";
+}

package/src/memory/search.ts

@@ -0,0 +1,105 @@
+import { redact } from "./privacy.ts";
+
+// Small, explicit bilingual bootstrap for existing records, not a general translator.
+// New model-derived searchTerms extend recall beyond this vocabulary without model calls
+// on the recall path. Synonyms form ONE feature, not several independent votes.
+const CONCEPTS: [string, RegExp][] = [
+	["memory", /记忆|\bmemor(?:y|ies)\b/giu],
+	["session", /会话|\bsessions?\b/giu],
+	["project", /项目|\bprojects?\b/giu],
+	["directory", /目录|文件夹|\b(?:director(?:y|ies)|folders?|cwd)\b/giu],
+	["cross-context", /跨会话|跨项目|跨目录|限定|限制|不限于?|\b(?:across|regardless|restrict(?:ed|ion|ions)?|limit(?:ed|ation|ations)?|cross-session|cross-project|cross-directory)\b/giu],
+	["recall", /召回|检索|\b(?:recall|retrieval|retrieve|search)\b/giu],
+	["injection", /注入|\binject(?:ion|ed|ing)?\b/giu],
+	["preference", /偏好|\bprefer(?:ence|ences|red)?\b/giu],
+	["model", /模型|\bmodels?\b/giu],
+	["auth", /认证|鉴权|\b(?:auth|authentication|authorization)\b/giu],
+	["reuse", /复用|重用|\breus(?:e|ed|ing)\b/giu],
+	["database", /数据库|\bdatabases?\b/giu],
+	["port", /端口|\bports?\b/giu],
+	["network", /网络|\bnetwork(?:s|ing)?\b/giu],
+	["bluetooth", /蓝牙|\bbluetooth\b/giu],
+	["audio", /音响|音频|\b(?:audio|speakers?)\b/giu],
+	["review", /审查|审阅|\breview(?:ed|ing)?\b/giu],
+	["commit", /提交|\bcommit(?:s|ted|ting)?\b/giu],
+	["push", /推送|\bpush(?:ed|ing)?\b/giu],
+	["progress", /进度|进展|\bprogress\b/giu],
+	["pending", /尚未|仍在|待完成|未完成|\b(?:pending|not yet|in progress)\b/giu],
+	["done", /已完成|完成了|\b(?:completed|finished|done)\b/giu],
+	["test", /测试|\btests?(?:ing|ed)?\b/giu],
+	["verification", /验证|校验|\b(?:verify|verified|verification|validation|validate)\b/giu],
+	// General conversational attributes, including short CJK words ICU may split.
+	["timeout", /超时|\btime[ -]?outs?\b/giu],
+	["version", /版本|\bversions?\b/giu],
+	["price", /价格|价钱|\b(?:prices?|pricing|costs?)\b/giu],
+	["status", /状态|\bstatus\b/giu],
+	["path", /路径|\bpaths?\b/giu],
+	["output", /输出|\boutputs?\b/giu],
+	["input", /输入|\binputs?\b/giu],
+	["installation", /安装|\binstall(?:ation|ed|ing)?\b/giu],
+	["connection", /连接|\bconnect(?:ion|ions|ed|ing)?\b/giu],
+	["performance", /性能|\bperformance\b/giu],
+];
+const STOP = new Set(`的 了 是 在 有 没有 现在 目前 当前 这个 那个 这些 那些 什么 哪些 哪个 为什么 怎样 如何 怎么 是否 可以 需要 问题 看看 一下 我们 你们 然后 但是 以及 关于 帮我 谢谢 应该 还是 继续 之前 上次 修复 修改 检查 处理 记住
+ the and for with continue resume previous this that these those it its they them their we our you your i me my a an of to in on at is are was were be been do does did has have had no not without now current currently what which who how why can could should would please help check look see any there here also just again about other anything something else one problem problems issue issues wrong broken use used using work home src tmp user users fix change changes need remember discuss show describe explain tell where`.split(/\s+/u));
+const WORDS = new Intl.Segmenter("zh", { granularity: "word" });
+// Paths and filenames are an exact-literal channel. Their components must not turn a
+// repository named pi-memory-evolution into evidence about the meaning of "memory".
+const LITERALS = /(?<![\p{L}\p{N}_])(?:~?\/|\.\.?\/)[^\s`"'<>，。！？,;!?]+|(?<![\w./-])(?:[\w.-]+\/)*[\w-]+\.(?:[cm]?[jt]sx?|json|md|sqlite|toml|ya?ml|sh|py|go|rs)\b|(?<![a-z0-9-])[a-z][a-z0-9]*(?:-[a-z0-9]+){2,}/giu;
+
+/** Query-language cleanup must never rewrite literal paths/filenames. */
+export function transformProse(text: string, transform: (prose: string) => string): string {
+	let result = "", start = 0;
+	for (const match of text.matchAll(LITERALS)) {
+		result += transform(text.slice(start, match.index)) + match[0];
+		start = match.index + match[0].length;
+	}
+	return result + transform(text.slice(start));
+}
+
+export function features(text: string, includeSingle = false): Set<string> {
+	const result = new Set<string>();
+	let prose = redact(text).replace(/\[REDACTED[^\]\n]*\]/gu, " ");
+	prose = prose.replace(LITERALS, (literal) => {
+		const clean = literal.replace(/[.:]+$/u, "").toLowerCase();
+		result.add(`literal:${clean}`);
+		result.add(`literal:${clean.split("/").at(-1)}`);
+		return " ";
+	});
+	// Detect all concepts on the original prose so overlapping phrases such as
+	// 跨会话 contribute session + cross-context, but not duplicated English synonyms.
+	const masked = prose.split("");
+	for (const [name, pattern] of CONCEPTS) {
+		pattern.lastIndex = 0;
+		for (const match of prose.matchAll(pattern)) {
+			result.add(`concept:${name}`);
+			for (let i = match.index; i < match.index + match[0].length; i++) masked[i] = " ";
+		}
+	}
+	prose = masked.join("");
+	prose = prose.replace(/([a-z])([A-Z])/gu, "$1 $2").toLowerCase();
+	for (const word of WORDS.segment(prose)) {
+		if (!word.isWordLike || (!includeSingle && word.segment.length < 2) || STOP.has(word.segment)) continue;
+		result.add(word.segment);
+	}
+	return result;
+}
+
+export function featureOffset(text: string, feature: string): number {
+	// Preserve offsets while applying the same literal/prose boundary as indexing.
+	const prose = feature.startsWith("literal:") ? text : text.replace(LITERALS, (literal) => " ".repeat(literal.length));
+	if (feature.startsWith("concept:")) {
+		const pattern = CONCEPTS.find(([name]) => `concept:${name}` === feature)?.[1];
+		if (!pattern) return -1;
+		pattern.lastIndex = 0;
+		return pattern.exec(prose)?.index ?? -1;
+	}
+	return prose.toLowerCase().indexOf(feature.replace(/^literal:/u, ""));
+}
+
+export function validSearchTerms(value: unknown): value is string[] | undefined {
+	return value === undefined || (Array.isArray(value) && value.length <= 8 && value.every((term) =>
+		typeof term === "string" && term.trim() === term && term.length >= 2 && term.length <= 64
+		&& !term.includes("[REDACTED") && redact(term) === term && !/[\r\n]/u.test(term))
+		&& Buffer.byteLength(JSON.stringify(value)) <= 1024);
+}

package/src/memory/sqlite.ts

@@ -0,0 +1,7 @@
+import { createRequire } from "node:module";
+
+/** Pi's standalone binary uses Bun; npm Pi and tests use Node. Both bundle SQLite. */
+const require = createRequire(import.meta.url);
+export type Database = import("node:sqlite").DatabaseSync;
+export const Database: typeof import("node:sqlite").DatabaseSync =
+	"Bun" in globalThis ? require("bun:sqlite").Database : require("node:sqlite").DatabaseSync;