minimal-agent 0.10.0 → 0.12.0

package/src/memory/retrieval.js

@@ -0,0 +1,108 @@
+import { countTextTokens } from '../context/tokenCounter.js';
+import { DEFAULT_REVIEW_WINDOWS } from './constants.js';
+import { BM25_DOCUMENT_THRESHOLD, Bm25Index, recordSearchIndexBuild, recordSearchIndexCacheHit, recordSearchIndexFallback, recordSearchStrategy, searchTerms, } from './searchIndex.js';
+const snapshotIndexes = new WeakMap();
+export function memoryTerms(query) {
+    return searchTerms(query);
+}
+export function isReviewDue(record, settings, now = Date.now()) {
+    const days = settings.reviewAfterDays?.[record.category] ??
+        DEFAULT_REVIEW_WINDOWS[record.category];
+    return now - record.lastConfirmedAt > days * 86_400_000;
+}
+export function scoreMemory(record, query, settings) {
+    if (record.status === 'superseded')
+        return Number.NEGATIVE_INFINITY;
+    const haystack = `${record.category} ${record.subject} ${record.topicKey} ${record.aliases.join(' ')} ${record.statement}`.toLocaleLowerCase();
+    const terms = memoryTerms(query);
+    const lexical = terms.reduce((sum, term) => sum + (haystack.includes(term) ? 10 : 0), 0);
+    const phrase = query.trim() && haystack.includes(query.trim().toLocaleLowerCase())
+        ? 25
+        : 0;
+    const stalePenalty = isReviewDue(record, settings) || record.status === 'needs_review' ? 8 : 0;
+    return lexical + phrase - stalePenalty + record.lastConfirmedAt / 1e13;
+}
+export function recallFromSnapshot(snapshot, query, settings, limit) {
+    const eligible = snapshot.records.filter((record) => record.status !== 'superseded');
+    if (!query.trim() || eligible.length < BM25_DOCUMENT_THRESHOLD) {
+        recordSearchStrategy('lexical', eligible.length);
+        return snapshot.records
+            .map((record) => ({ record, score: scoreMemory(record, query, settings) }))
+            .filter((item) => Number.isFinite(item.score) && (!query.trim() || item.score >= 2))
+            .sort((a, b) => b.score - a.score)
+            .slice(0, Math.min(100, Math.max(1, limit)))
+            .map((item) => item.record);
+    }
+    try {
+        let index = snapshotIndexes.get(snapshot);
+        if (!index) {
+            index = new Bm25Index(eligible.map((record) => ({
+                id: record.id,
+                fields: [
+                    { text: record.subject, weight: 4 },
+                    { text: record.aliases.join(' '), weight: 3 },
+                    { text: `${record.topicKey} ${record.category}`, weight: 2 },
+                    { text: record.statement, weight: 1 },
+                ],
+            })));
+            snapshotIndexes.set(snapshot, index);
+            recordSearchIndexBuild();
+        }
+        else {
+            recordSearchIndexCacheHit();
+        }
+        recordSearchStrategy('bm25', eligible.length);
+        const bm25 = index.search(query);
+        const normalized = query.trim().toLocaleLowerCase();
+        return eligible
+            .map((record) => {
+            const haystack = `${record.category} ${record.subject} ${record.topicKey} ${record.aliases.join(' ')} ${record.statement}`.toLocaleLowerCase();
+            const phrase = normalized && haystack.includes(normalized) ? 25 : 0;
+            const stalePenalty = isReviewDue(record, settings) || record.status === 'needs_review' ? 8 : 0;
+            return {
+                record,
+                score: (bm25.get(record.id) ?? 0) * 10 + phrase - stalePenalty + record.lastConfirmedAt / 1e13,
+            };
+        })
+            .filter((item) => (bm25.get(item.record.id) ?? 0) > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, Math.min(100, Math.max(1, limit)))
+            .map((item) => item.record);
+    }
+    catch {
+        recordSearchIndexFallback();
+        recordSearchStrategy('lexical', eligible.length);
+        return snapshot.records
+            .map((record) => ({ record, score: scoreMemory(record, query, settings) }))
+            .filter((item) => Number.isFinite(item.score) && item.score >= 2)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, Math.min(100, Math.max(1, limit)))
+            .map((item) => item.record);
+    }
+}
+export function takeTokenBudget(lines, maxTokens) {
+    const result = [];
+    let used = 0;
+    for (const line of lines) {
+        const tokens = countTextTokens(line);
+        if (used + tokens > maxTokens)
+            break;
+        result.push(line);
+        used += tokens;
+    }
+    return result;
+}
+export function truncateTokenBudget(text, maxTokens) {
+    if (countTextTokens(text) <= maxTokens)
+        return text;
+    let low = 0;
+    let high = text.length;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (countTextTokens(text.slice(0, middle)) <= maxTokens)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    return `${text.slice(0, low).trimEnd()}…`;
+}

package/src/memory/retrieval.ts

@@ -0,0 +1,145 @@
+import { countTextTokens } from '../context/tokenCounter.js';
+import { DEFAULT_REVIEW_WINDOWS } from './constants.js';
+import type {
+  MemoryRecordV2,
+  MemorySettings,
+  MemorySnapshot,
+} from './types.js';
+import {
+  BM25_DOCUMENT_THRESHOLD,
+  Bm25Index,
+  recordSearchIndexBuild,
+  recordSearchIndexCacheHit,
+  recordSearchIndexFallback,
+  recordSearchStrategy,
+  searchTerms,
+} from './searchIndex.js';
+
+const snapshotIndexes = new WeakMap<MemorySnapshot, Bm25Index>();
+
+export function memoryTerms(query: string): string[] {
+  return searchTerms(query);
+}
+
+export function isReviewDue(
+  record: MemoryRecordV2,
+  settings: MemorySettings,
+  now = Date.now(),
+): boolean {
+  const days =
+    settings.reviewAfterDays?.[record.category] ??
+    DEFAULT_REVIEW_WINDOWS[record.category];
+  return now - record.lastConfirmedAt > days * 86_400_000;
+}
+
+export function scoreMemory(
+  record: MemoryRecordV2,
+  query: string,
+  settings: MemorySettings,
+): number {
+  if (record.status === 'superseded') return Number.NEGATIVE_INFINITY;
+  const haystack =
+    `${record.category} ${record.subject} ${record.topicKey} ${record.aliases.join(' ')} ${record.statement}`.toLocaleLowerCase();
+  const terms = memoryTerms(query);
+  const lexical = terms.reduce(
+    (sum, term) => sum + (haystack.includes(term) ? 10 : 0),
+    0,
+  );
+  const phrase =
+    query.trim() && haystack.includes(query.trim().toLocaleLowerCase())
+      ? 25
+      : 0;
+  const stalePenalty =
+    isReviewDue(record, settings) || record.status === 'needs_review' ? 8 : 0;
+  return lexical + phrase - stalePenalty + record.lastConfirmedAt / 1e13;
+}
+
+export function recallFromSnapshot(
+  snapshot: MemorySnapshot,
+  query: string,
+  settings: MemorySettings,
+  limit: number,
+): MemoryRecordV2[] {
+  const eligible = snapshot.records.filter((record) => record.status !== 'superseded');
+  if (!query.trim() || eligible.length < BM25_DOCUMENT_THRESHOLD) {
+    recordSearchStrategy('lexical', eligible.length);
+    return snapshot.records
+    .map((record) => ({ record, score: scoreMemory(record, query, settings) }))
+    .filter(
+      (item) =>
+        Number.isFinite(item.score) && (!query.trim() || item.score >= 2),
+    )
+    .sort((a, b) => b.score - a.score)
+    .slice(0, Math.min(100, Math.max(1, limit)))
+    .map((item) => item.record);
+  }
+
+  try {
+    let index = snapshotIndexes.get(snapshot);
+    if (!index) {
+      index = new Bm25Index(eligible.map((record) => ({
+        id: record.id,
+        fields: [
+          { text: record.subject, weight: 4 },
+          { text: record.aliases.join(' '), weight: 3 },
+          { text: `${record.topicKey} ${record.category}`, weight: 2 },
+          { text: record.statement, weight: 1 },
+        ],
+      })));
+      snapshotIndexes.set(snapshot, index);
+      recordSearchIndexBuild();
+    } else {
+      recordSearchIndexCacheHit();
+    }
+    recordSearchStrategy('bm25', eligible.length);
+    const bm25 = index.search(query);
+    const normalized = query.trim().toLocaleLowerCase();
+    return eligible
+      .map((record) => {
+        const haystack = `${record.category} ${record.subject} ${record.topicKey} ${record.aliases.join(' ')} ${record.statement}`.toLocaleLowerCase();
+        const phrase = normalized && haystack.includes(normalized) ? 25 : 0;
+        const stalePenalty = isReviewDue(record, settings) || record.status === 'needs_review' ? 8 : 0;
+        return {
+          record,
+          score: (bm25.get(record.id) ?? 0) * 10 + phrase - stalePenalty + record.lastConfirmedAt / 1e13,
+        };
+      })
+      .filter((item) => (bm25.get(item.record.id) ?? 0) > 0)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, Math.min(100, Math.max(1, limit)))
+      .map((item) => item.record);
+  } catch {
+    recordSearchIndexFallback();
+    recordSearchStrategy('lexical', eligible.length);
+    return snapshot.records
+      .map((record) => ({ record, score: scoreMemory(record, query, settings) }))
+      .filter((item) => Number.isFinite(item.score) && item.score >= 2)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, Math.min(100, Math.max(1, limit)))
+      .map((item) => item.record);
+  }
+}
+
+export function takeTokenBudget(lines: string[], maxTokens: number): string[] {
+  const result: string[] = [];
+  let used = 0;
+  for (const line of lines) {
+    const tokens = countTextTokens(line);
+    if (used + tokens > maxTokens) break;
+    result.push(line);
+    used += tokens;
+  }
+  return result;
+}
+
+export function truncateTokenBudget(text: string, maxTokens: number): string {
+  if (countTextTokens(text) <= maxTokens) return text;
+  let low = 0;
+  let high = text.length;
+  while (low < high) {
+    const middle = Math.ceil((low + high) / 2);
+    if (countTextTokens(text.slice(0, middle)) <= maxTokens) low = middle;
+    else high = middle - 1;
+  }
+  return `${text.slice(0, low).trimEnd()}…`;
+}

package/src/memory/searchIndex.js

@@ -0,0 +1,107 @@
+export const BM25_DOCUMENT_THRESHOLD = 200;
+const BM25_K1 = 1.2;
+const BM25_B = 0.75;
+const diagnostics = {
+    builds: 0,
+    cacheHits: 0,
+    queries: 0,
+    fallbacks: 0,
+    lastStrategy: 'lexical',
+    lastDocumentCount: 0,
+};
+export function searchIndexDiagnostics() {
+    return { ...diagnostics };
+}
+export function resetSearchIndexDiagnostics() {
+    diagnostics.builds = 0;
+    diagnostics.cacheHits = 0;
+    diagnostics.queries = 0;
+    diagnostics.fallbacks = 0;
+    diagnostics.lastStrategy = 'lexical';
+    diagnostics.lastDocumentCount = 0;
+}
+export function recordSearchStrategy(strategy, documentCount) {
+    diagnostics.queries += 1;
+    diagnostics.lastStrategy = strategy;
+    diagnostics.lastDocumentCount = documentCount;
+}
+export function recordSearchIndexBuild() {
+    diagnostics.builds += 1;
+}
+export function recordSearchIndexCacheHit() {
+    diagnostics.cacheHits += 1;
+}
+export function recordSearchIndexFallback() {
+    diagnostics.fallbacks += 1;
+}
+/** Shared dependency-free tokenizer for lexical and BM25 retrieval. */
+function tokenizeSearchText(input) {
+    const normalized = input.normalize('NFKC').toLocaleLowerCase();
+    const tokens = normalized
+        .split(/[\s,，。；;:：/\\()[\]{}"'`！？!?\p{P}\p{S}]+/u)
+        .filter((item) => item.length > 1);
+    const cjkSequences = normalized.match(/[\p{Script=Han}]{2,}/gu) ?? [];
+    for (const sequence of cjkSequences) {
+        for (let index = 0; index < sequence.length - 1; index += 1) {
+            tokens.push(sequence.slice(index, index + 2));
+        }
+    }
+    return tokens;
+}
+export function searchTerms(input) {
+    return Array.from(new Set(tokenizeSearchText(input)));
+}
+export class Bm25Index {
+    documentCount;
+    documents;
+    documentFrequency = new Map();
+    averageLength;
+    constructor(input) {
+        this.documents = input.map((document) => {
+            const frequencies = new Map();
+            let length = 0;
+            for (const field of document.fields) {
+                if (!field.text || field.weight <= 0)
+                    continue;
+                const terms = tokenizeSearchText(field.text);
+                length += terms.length * field.weight;
+                for (const term of terms) {
+                    frequencies.set(term, (frequencies.get(term) ?? 0) + field.weight);
+                }
+            }
+            for (const term of frequencies.keys()) {
+                this.documentFrequency.set(term, (this.documentFrequency.get(term) ?? 0) + 1);
+            }
+            return { id: document.id, length: Math.max(1, length), frequencies };
+        });
+        this.documentCount = this.documents.length;
+        this.averageLength = this.documentCount
+            ? this.documents.reduce((sum, document) => sum + document.length, 0)
+                / this.documentCount
+            : 1;
+    }
+    search(query) {
+        const terms = searchTerms(query);
+        const scores = new Map();
+        if (!terms.length || !this.documentCount)
+            return scores;
+        for (const document of this.documents) {
+            let score = 0;
+            for (const term of terms) {
+                const frequency = document.frequencies.get(term) ?? 0;
+                if (!frequency)
+                    continue;
+                const documentFrequency = this.documentFrequency.get(term) ?? 0;
+                const inverseDocumentFrequency = Math.log(1 + (this.documentCount - documentFrequency + 0.5)
+                    / (documentFrequency + 0.5));
+                const normalization = frequency
+                    + BM25_K1 * (1 - BM25_B + BM25_B * document.length / this.averageLength);
+                score += inverseDocumentFrequency
+                    * (frequency * (BM25_K1 + 1)) / normalization;
+            }
+            if (score > 0)
+                scores.set(document.id, score);
+        }
+        return scores;
+    }
+}

package/src/memory/searchIndex.ts

@@ -0,0 +1,153 @@
+export const BM25_DOCUMENT_THRESHOLD = 200;
+
+const BM25_K1 = 1.2;
+const BM25_B = 0.75;
+
+export type SearchStrategy = 'lexical' | 'bm25';
+
+export interface WeightedSearchField {
+  text: string;
+  weight: number;
+}
+
+export interface WeightedSearchDocument {
+  id: string;
+  fields: WeightedSearchField[];
+}
+
+interface IndexedDocument {
+  id: string;
+  length: number;
+  frequencies: Map<string, number>;
+}
+
+export interface SearchIndexDiagnostics {
+  builds: number;
+  cacheHits: number;
+  queries: number;
+  fallbacks: number;
+  lastStrategy: SearchStrategy;
+  lastDocumentCount: number;
+}
+
+const diagnostics: SearchIndexDiagnostics = {
+  builds: 0,
+  cacheHits: 0,
+  queries: 0,
+  fallbacks: 0,
+  lastStrategy: 'lexical',
+  lastDocumentCount: 0,
+};
+
+export function searchIndexDiagnostics(): Readonly<SearchIndexDiagnostics> {
+  return { ...diagnostics };
+}
+
+export function resetSearchIndexDiagnostics(): void {
+  diagnostics.builds = 0;
+  diagnostics.cacheHits = 0;
+  diagnostics.queries = 0;
+  diagnostics.fallbacks = 0;
+  diagnostics.lastStrategy = 'lexical';
+  diagnostics.lastDocumentCount = 0;
+}
+
+export function recordSearchStrategy(
+  strategy: SearchStrategy,
+  documentCount: number,
+): void {
+  diagnostics.queries += 1;
+  diagnostics.lastStrategy = strategy;
+  diagnostics.lastDocumentCount = documentCount;
+}
+
+export function recordSearchIndexBuild(): void {
+  diagnostics.builds += 1;
+}
+
+export function recordSearchIndexCacheHit(): void {
+  diagnostics.cacheHits += 1;
+}
+
+export function recordSearchIndexFallback(): void {
+  diagnostics.fallbacks += 1;
+}
+
+/** Shared dependency-free tokenizer for lexical and BM25 retrieval. */
+function tokenizeSearchText(input: string): string[] {
+  const normalized = input.normalize('NFKC').toLocaleLowerCase();
+  const tokens = normalized
+    .split(/[\s,，。；;:：/\\()[\]{}"'`！？!?\p{P}\p{S}]+/u)
+    .filter((item) => item.length > 1);
+  const cjkSequences = normalized.match(/[\p{Script=Han}]{2,}/gu) ?? [];
+  for (const sequence of cjkSequences) {
+    for (let index = 0; index < sequence.length - 1; index += 1) {
+      tokens.push(sequence.slice(index, index + 2));
+    }
+  }
+  return tokens;
+}
+
+export function searchTerms(input: string): string[] {
+  return Array.from(new Set(tokenizeSearchText(input)));
+}
+
+export class Bm25Index {
+  readonly documentCount: number;
+  private readonly documents: IndexedDocument[];
+  private readonly documentFrequency = new Map<string, number>();
+  private readonly averageLength: number;
+
+  constructor(input: readonly WeightedSearchDocument[]) {
+    this.documents = input.map((document) => {
+      const frequencies = new Map<string, number>();
+      let length = 0;
+      for (const field of document.fields) {
+        if (!field.text || field.weight <= 0) continue;
+        const terms = tokenizeSearchText(field.text);
+        length += terms.length * field.weight;
+        for (const term of terms) {
+          frequencies.set(term, (frequencies.get(term) ?? 0) + field.weight);
+        }
+      }
+      for (const term of frequencies.keys()) {
+        this.documentFrequency.set(
+          term,
+          (this.documentFrequency.get(term) ?? 0) + 1,
+        );
+      }
+      return { id: document.id, length: Math.max(1, length), frequencies };
+    });
+    this.documentCount = this.documents.length;
+    this.averageLength = this.documentCount
+      ? this.documents.reduce((sum, document) => sum + document.length, 0)
+        / this.documentCount
+      : 1;
+  }
+
+  search(query: string): Map<string, number> {
+    const terms = searchTerms(query);
+    const scores = new Map<string, number>();
+    if (!terms.length || !this.documentCount) return scores;
+    for (const document of this.documents) {
+      let score = 0;
+      for (const term of terms) {
+        const frequency = document.frequencies.get(term) ?? 0;
+        if (!frequency) continue;
+        const documentFrequency = this.documentFrequency.get(term) ?? 0;
+        const inverseDocumentFrequency = Math.log(
+          1 + (this.documentCount - documentFrequency + 0.5)
+            / (documentFrequency + 0.5),
+        );
+        const normalization = frequency
+          + BM25_K1 * (
+            1 - BM25_B + BM25_B * document.length / this.averageLength
+          );
+        score += inverseDocumentFrequency
+          * (frequency * (BM25_K1 + 1)) / normalization;
+      }
+      if (score > 0) scores.set(document.id, score);
+    }
+    return scores;
+  }
+}

package/src/memory/topicView.js

@@ -0,0 +1,82 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ALL_CATEGORIES } from './constants.js';
+import { atomicWriteFile, scopeDirectory } from './fileStore.js';
+import { sha256 } from './codec.js';
+const GENERATED_HEADER = '<!-- minimal-agent generated topic view; do not edit';
+export function topicViewPath(scope, workspaceId) {
+    return join(scopeDirectory(scope, workspaceId), 'views', 'topics.md');
+}
+function viewGeneration(snapshot) {
+    const entries = snapshot.records
+        .map((record) => `${record.id}:${snapshot.versions[record.id] ?? ''}`)
+        .sort();
+    return sha256(entries.join('\n'));
+}
+function recordLine(record) {
+    const aliases = record.aliases.length ? record.aliases.join(', ') : '—';
+    const statement = record.sensitivity === 'sensitive'
+        ? '[敏感记忆内容已隐藏；请读取权威 UUID 记录并遵守访问权限]'
+        : record.statement;
+    return [
+        `- **${record.subject}** — ${statement}`,
+        `  - id: \`${record.id}\`; revision: ${record.revision}; status: ${record.status}; updated: ${new Date(record.updatedAt).toISOString()}`,
+        `  - aliases: ${aliases}`,
+    ];
+}
+function topicRecords(records) {
+    const grouped = new Map();
+    for (const record of records) {
+        const values = grouped.get(record.topicKey) ?? [];
+        values.push(record);
+        grouped.set(record.topicKey, values);
+    }
+    for (const values of grouped.values()) {
+        values.sort((a, b) => {
+            const activeRank = (record) => record.status === 'active' ? 0 : record.status === 'needs_review' ? 1 : 2;
+            return activeRank(a) - activeRank(b) || b.updatedAt - a.updatedAt || a.id.localeCompare(b.id);
+        });
+    }
+    return grouped;
+}
+export function renderTopicView(snapshot) {
+    const generation = viewGeneration(snapshot);
+    const lines = [
+        `${GENERATED_HEADER}; generation:${generation} -->`,
+        '# Memory Topics',
+        '',
+        '> 自动生成、禁止编辑。UUID Markdown 记录是唯一权威来源；删除本文件后会自动重建。',
+    ];
+    for (const category of ALL_CATEGORIES) {
+        const records = snapshot.records.filter((record) => record.category === category);
+        if (!records.length)
+            continue;
+        lines.push('', `## ${category}`);
+        const grouped = topicRecords(records);
+        for (const topicKey of [...grouped.keys()].sort((a, b) => a.localeCompare(b, 'zh-CN'))) {
+            lines.push('', `### ${topicKey}`);
+            const values = grouped.get(topicKey);
+            const current = values.filter((record) => record.status !== 'superseded');
+            const superseded = values.filter((record) => record.status === 'superseded');
+            for (const record of current)
+                lines.push(...recordLine(record));
+            if (superseded.length) {
+                lines.push('- 被替代记录：');
+                for (const record of superseded) {
+                    lines.push(`  - \`${record.id}\` revision ${record.revision}, updated ${new Date(record.updatedAt).toISOString()}`);
+                }
+            }
+        }
+    }
+    if (!snapshot.records.length)
+        lines.push('', '_当前没有记忆记录。_');
+    return `${lines.join('\n')}\n`;
+}
+export async function ensureTopicView(snapshot, scope, workspaceId) {
+    const path = topicViewPath(scope, workspaceId);
+    const expectedPrefix = `${GENERATED_HEADER}; generation:${viewGeneration(snapshot)} -->`;
+    const current = await readFile(path, 'utf8').catch(() => '');
+    if (current.startsWith(expectedPrefix))
+        return;
+    await atomicWriteFile(path, renderTopicView(snapshot));
+}

package/src/memory/topicView.ts

@@ -0,0 +1,95 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { ALL_CATEGORIES } from './constants.js';
+import { atomicWriteFile, scopeDirectory } from './fileStore.js';
+import { sha256 } from './codec.js';
+import type {
+  MemoryRecordV2,
+  MemoryScope,
+  MemorySnapshot,
+} from './types.js';
+
+const GENERATED_HEADER = '<!-- minimal-agent generated topic view; do not edit';
+
+export function topicViewPath(scope: MemoryScope, workspaceId?: string): string {
+  return join(scopeDirectory(scope, workspaceId), 'views', 'topics.md');
+}
+
+function viewGeneration(snapshot: MemorySnapshot): string {
+  const entries = snapshot.records
+    .map((record) => `${record.id}:${snapshot.versions[record.id] ?? ''}`)
+    .sort();
+  return sha256(entries.join('\n'));
+}
+
+function recordLine(record: MemoryRecordV2): string[] {
+  const aliases = record.aliases.length ? record.aliases.join(', ') : '—';
+  const statement = record.sensitivity === 'sensitive'
+    ? '[敏感记忆内容已隐藏；请读取权威 UUID 记录并遵守访问权限]'
+    : record.statement;
+  return [
+    `- **${record.subject}** — ${statement}`,
+    `  - id: \`${record.id}\`; revision: ${record.revision}; status: ${record.status}; updated: ${new Date(record.updatedAt).toISOString()}`,
+    `  - aliases: ${aliases}`,
+  ];
+}
+
+function topicRecords(records: MemoryRecordV2[]): Map<string, MemoryRecordV2[]> {
+  const grouped = new Map<string, MemoryRecordV2[]>();
+  for (const record of records) {
+    const values = grouped.get(record.topicKey) ?? [];
+    values.push(record);
+    grouped.set(record.topicKey, values);
+  }
+  for (const values of grouped.values()) {
+    values.sort((a, b) => {
+      const activeRank = (record: MemoryRecordV2) => record.status === 'active' ? 0 : record.status === 'needs_review' ? 1 : 2;
+      return activeRank(a) - activeRank(b) || b.updatedAt - a.updatedAt || a.id.localeCompare(b.id);
+    });
+  }
+  return grouped;
+}
+
+export function renderTopicView(snapshot: MemorySnapshot): string {
+  const generation = viewGeneration(snapshot);
+  const lines = [
+    `${GENERATED_HEADER}; generation:${generation} -->`,
+    '# Memory Topics',
+    '',
+    '> 自动生成、禁止编辑。UUID Markdown 记录是唯一权威来源；删除本文件后会自动重建。',
+  ];
+  for (const category of ALL_CATEGORIES) {
+    const records = snapshot.records.filter((record) => record.category === category);
+    if (!records.length) continue;
+    lines.push('', `## ${category}`);
+    const grouped = topicRecords(records);
+    for (const topicKey of [...grouped.keys()].sort((a, b) => a.localeCompare(b, 'zh-CN'))) {
+      lines.push('', `### ${topicKey}`);
+      const values = grouped.get(topicKey)!;
+      const current = values.filter((record) => record.status !== 'superseded');
+      const superseded = values.filter((record) => record.status === 'superseded');
+      for (const record of current) lines.push(...recordLine(record));
+      if (superseded.length) {
+        lines.push('- 被替代记录：');
+        for (const record of superseded) {
+          lines.push(`  - \`${record.id}\` revision ${record.revision}, updated ${new Date(record.updatedAt).toISOString()}`);
+        }
+      }
+    }
+  }
+  if (!snapshot.records.length) lines.push('', '_当前没有记忆记录。_');
+  return `${lines.join('\n')}\n`;
+}
+
+export async function ensureTopicView(
+  snapshot: MemorySnapshot,
+  scope: MemoryScope,
+  workspaceId?: string,
+): Promise<void> {
+  const path = topicViewPath(scope, workspaceId);
+  const expectedPrefix = `${GENERATED_HEADER}; generation:${viewGeneration(snapshot)} -->`;
+  const current = await readFile(path, 'utf8').catch(() => '');
+  if (current.startsWith(expectedPrefix)) return;
+  await atomicWriteFile(path, renderTopicView(snapshot));
+}