dsh-cortex-memory 0.0.0-stage → 0.2.0-rc.11

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 本鲸 / 凌寒
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# dsh-cortex
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> 鏈哺鐨勬柊澶ц剳銆傚垎灞傘€佹椂搴忋€佸彲鑷垜宸╁浐鐨勮蹇嗗紩鎿庛€?> 鐘舵€侊細**鍙墦鍖呫€佸彲瀹夎**锛涙湰鏈哄紑鍙戝壇鏈粛鏈畨瑁咃紝涔熸病鏈夋帴 profile銆?> Windows 鐩存帴瀹夎/鍥炴粴瑙?[docs/install-windows.md](docs/install-windows.md)銆?
+`dsh-cortex` is a local-first memory engine for DeepSeek Harness. It is designed
+as a successor to the `dsh-shiori` + `dsh-shiori-companion` pair, not a patch on
+top of them.
+
+## Why another memory plugin
+
+The shiori stack is good at four things: a stable persona, a compact core,
+triggered spark cards and on-demand topics. It is weaker at temporal facts,
+episodic provenance, procedural learning, consolidation and calibrated
+forgetting. `dsh-cortex` keeps the good parts and adds the missing layers:
+
+| Layer | What it holds | Lifetime |
+|---|---|---|
+| L0 identity | self-model, values, boundaries, stable traits | long, explicit promotion |
+| L1 working | current goals, focus, pinned context, recent turn buffer | minutes鈥揾ours |
+| L2 episodic | what happened, when, with whom, provenance, emotion | days鈥搚ears |
+| L3 semantic | entities, facts with validity windows, preferences | until invalidated |
+| L4 procedural | skills, workflows, preconditions, success/failure stats | until superseded |
+| L5 reflective | episode summaries, insights, narratives | derived, regenerable |
+| archive | cold but searchable, wake-word recall | until privacy deletion |
+
+## Engines
+
+- **event log** 鈥?append-only, hash-chained, `event_id` / `operation_id`; the
+  only source of truth.
+- **write pipeline** 鈥?scan secrets/injection 鈫?classify 鈫?dedupe 鈫?  conflict-resolve 鈫?link 鈫?persist; async jobs with idempotent operation IDs.
+- **temporal graph** 鈥?entities, facts and edges with `valid_from` /
+  `valid_to`; old facts are invalidated, never silently overwritten.
+- **hybrid retrieval** 鈥?FTS5 BM25 + optional vector + graph activation +
+  recency / importance / feedback, fused with RRF, diversified with a greedy
+  MMR-style marginal-gain pass; query filters (`kind:`, `tag:`, `after:`,
+  `importance:>`, 鈥?.
+- **DSR forgetting** 鈥?FSRS-inspired stability / difficulty / retrievability;
+  archive instead of delete, revive on successful recall.
+- **compression / retention** 鈥?archive only when a derived model covers the
+  trace, or when a reviewed retention plan says it is old/low-value; important
+  memories are never auto-archived.
+- **reflection** 鈥?episode segmentation, summaries, narrative threads,
+  duplicate/contradiction detection, optional LLM dream/summary.
+- **self model** 鈥?drives, mood, attention, appraisal, relationships,
+  initiatives, 24-category emotion/affect, identity versions.
+- **development** 鈥?maturity/stage from memory depth, feedback, calibration,
+  skills, narrative and relationships.
+- **evolution** 鈥?policy proposals 鈫?replay evaluation 鈫?explicit approval 鈫?  rollback; identity changes are separate and approval-only.
+- **guardian** 鈥?invariants, circuit breaker, budget, backup/validate/offline
+  restore, FTS repair, privacy cascade, secret/injection scanner.
+- **host runtime** 鈥?`session/event` turn capture + `user/message` /
+  `agent/pre-step` recall prefetch into the systemPrompt section.
+- **API/UI/CLI** 鈥?loopback-only HTTP API, sidebar panel, `bin/cortex.mjs`.
+
+## Status
+
+This is a source-only development tree. `npm test` uses `node:test` and the
+built-in `node:sqlite`; no native dependency and no network are required for
+the core suite. Profiles install a built tgz explicitly; this tree is not
+auto-linked into them.
+
+- **395** tests passing (unit + integration).
+- 21 model-facing tools.
+- **`cortex_as_of`**锛歴trict / historical / belief / associative銆?- **`cortex_playbook`**锛歀1.5 宸ヤ綔鍑嗗垯锛屽甫 helpful/harmful銆乿alidTo銆佽繃鏈熶笉娉ㄥ叆銆?- **`cortex_consolidate`**锛歀LM 鍐崇瓥娓呭崟 + 鏍￠獙 + `dream_runs` 鍙洖鏀捐褰曪紱鏃?LLM 鏃惰褰?skipped 骞堕浂鏀瑰姩銆?- **`cortex_search({tiered:true})`**锛歱erm/hot/cold 鍒嗗眰棰勭畻锛宑old 鍙粰绱㈠紩銆?- **寮傛娣峰悎妫€绱?*锛歚GET /search?async=true` / QA 璧?`searchAsync`锛涜繙绋?embedder 鍙储寮曪紝涓嶉樆濉炲啓銆?- 5k synthetic benchmark (needle, vector off): ~2.6-2.8k writes/s, p50 ~20-35ms; 100k migration ~2.3s. These are local numbers, not an official score.
+- Source/tests/docs 鈮?33k lines (includes `docs/book/`); source-only, not installed here.
+- Windows tgz: `dist/dsh-cortex-0.2.0-rc.11.tgz` (zero runtime deps; Node >= 24).
+
+## Design docs
+
+- [research notes](docs/research/README.md)
+- [architecture](docs/architecture.md)
+- [Anima: from memory engine to a growing individual](docs/anima.md)
+- [modules and invariants](docs/modules.md)
+- [operations / CLI / backup](docs/operations.md)
+- [security and privacy](docs/security.md)
+- [scope isolation and read-only sharing](docs/scopes.md)
+- [multimodal attachment metadata](docs/multimodal.md)
+- [benchmark](docs/benchmark.md)
+- [OpenAPI 3.1](docs/openapi.yaml)
+- [API client](src/api/client.js)
+- [UI guide](docs/ui.md)
+- [design book](docs/book/README.md)
+- [four-plugin comparison](docs/comparison-2026-11-11.md)
+- [Windows install and rollback](docs/install-windows.md)
+- [optional models](docs/models.md)
+- [shiori companion review](docs/companion-feature-review.md)
+- [ecosystem comparison 2026-11-11](docs/ecosystem-comparison-2026-11-11.md)
+- [roadmap](docs/roadmap.md)
+
+## License
+
+MIT. External ideas are cited in the research notes; no third-party source
+code is copied into this package.
+

package/bench/ab-engine.mjs

@@ -0,0 +1,60 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { generateSynthetic } from './synthetic.js';
+import { evaluateQueries, percentile } from './metrics.js';
+
+const engineRoot = process.argv[2];
+const task = process.argv[3] ?? 'paraphrase';
+const count = Number(process.argv[4] ?? 5000);
+const queryCount = Number(process.argv[5] ?? 100);
+
+if (!engineRoot) {
+  console.error('usage: node bench/ab-engine.mjs <engine-root> [needle|theme|paraphrase] [count] [queries]');
+  process.exit(2);
+}
+
+const { createCortex } = await import(pathToFileURL(path.join(engineRoot, 'src', 'service', 'cortex.js')).href);
+const dir = mkdtempSync(path.join(os.tmpdir(), 'cortex-ab-'));
+const cortex = createCortex({ config: { dataRoot: dir, dbFile: path.join(dir, 'cortex.sqlite'), contextBudget: 2200 } });
+try {
+  const dataset = generateSynthetic({ count, queries: queryCount, seed: 42, task });
+  const written = cortex.writeMany(dataset.traces.map((trace) => ({
+    text: trace.text,
+    title: trace.title,
+    tags: trace.tags,
+    importance: trace.importance,
+    explicit: true,
+    operationId: `ab:${trace.id}`,
+    now: Date.parse(trace.recordedAt),
+  })), { chunkSize: 250 });
+  const idMap = new Map();
+  for (let i = 0; i < written.length; i += 1) {
+    if (written[i].trace) idMap.set(dataset.traces[i].id, written[i].trace.id);
+  }
+  const results = [];
+  const latencies = [];
+  for (const query of dataset.queries) {
+    const start = performance.now();
+    const result = cortex.search(query.query, { limit: 10, budget: 2200 });
+    latencies.push(performance.now() - start);
+    results.push({
+      items: result.items,
+      relevant: query.relevant.map((id) => idMap.get(id)).filter(Boolean),
+    });
+  }
+  const metrics = evaluateQueries(results, { k: 10 });
+  console.log(JSON.stringify({
+    engine: engineRoot,
+    task,
+    count,
+    queries: dataset.queries.length,
+    p50Ms: Math.round((percentile(latencies, 50) ?? 0) * 100) / 100,
+    p95Ms: Math.round((percentile(latencies, 95) ?? 0) * 100) / 100,
+    ...metrics,
+  }, null, 2));
+} finally {
+  cortex.close();
+  rmSync(dir, { recursive: true, force: true });
+}

package/bench/ann-bench.mjs

@@ -0,0 +1,78 @@
+import { createAnnIndex } from '../src/vector/ann.js';
+
+function randomFactory(seed) {
+  let state = seed >>> 0;
+  return () => {
+    state = (state * 1664525 + 1013904223) >>> 0;
+    return state / 4294967296;
+  };
+}
+
+function makeVector(random, dim = 64) {
+  const value = Array.from({ length: dim }, () => random() * 2 - 1);
+  const norm = Math.sqrt(value.reduce((sum, item) => sum + item * item, 0)) || 1;
+  return value.map((item) => item / norm);
+}
+
+function cosine(a, b) {
+  let dot = 0;
+  for (let i = 0; i < a.length; i += 1) dot += a[i] * b[i];
+  return dot;
+}
+
+function percentile(values, p) {
+  const sorted = [...values].sort((a, b) => a - b);
+  if (!sorted.length) return null;
+  return sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil((p / 100) * sorted.length) - 1))];
+}
+
+const count = Number(process.argv[2] ?? 5000);
+const queries = Number(process.argv[3] ?? 100);
+const ef = Number(process.argv[4] ?? 120);
+const random = randomFactory(20261111);
+const items = Array.from({ length: count }, (_, index) => ({ id: `a${index}`, vector: makeVector(random) }));
+const queryVectors = Array.from({ length: queries }, () => makeVector(random));
+const ann = createAnnIndex({ M: 24, efConstruction: 200, efSearch: ef, seed: 20261111 });
+const buildStart = performance.now();
+ann.rebuild(items);
+const buildMs = performance.now() - buildStart;
+
+const exactTimes = [];
+const annTimes = [];
+const exactResults = [];
+const annResults = [];
+for (const query of queryVectors) {
+  const exactStart = performance.now();
+  const exact = items
+    .map((item) => ({ id: item.id, score: cosine(item.vector, query) }))
+    .sort((a, b) => b.score - a.score)
+    .slice(0, 10);
+  exactTimes.push(performance.now() - exactStart);
+  exactResults.push(exact);
+
+  const annStart = performance.now();
+  const approx = ann.search(query, 10, { ef }).slice(0, 10);
+  annTimes.push(performance.now() - annStart);
+  annResults.push(approx);
+}
+
+let hits = 0;
+let expectedTotal = 0;
+for (let index = 0; index < exactResults.length; index += 1) {
+  const expected = new Set(exactResults[index].map((item) => item.id));
+  for (const item of annResults[index]) if (expected.has(item.id)) hits += 1;
+  expectedTotal += expected.size;
+}
+
+console.log(JSON.stringify({
+  count,
+  queries,
+  dim: 64,
+  ef,
+  buildMs: Math.round(buildMs * 100) / 100,
+  recallAt10: expectedTotal ? Math.round((hits / expectedTotal) * 10000) / 10000 : null,
+  exactP50Ms: Math.round((percentile(exactTimes, 50) ?? 0) * 1000) / 1000,
+  annP50Ms: Math.round((percentile(annTimes, 50) ?? 0) * 1000) / 1000,
+  exactP95Ms: Math.round((percentile(exactTimes, 95) ?? 0) * 1000) / 1000,
+  annP95Ms: Math.round((percentile(annTimes, 95) ?? 0) * 1000) / 1000,
+}, null, 2));

package/bench/hnsw-bench.mjs

@@ -0,0 +1,79 @@
+import { createHnswIndex } from '../src/vector/hnsw.js';
+
+function randomFactory(seed) {
+  let state = seed >>> 0;
+  return () => {
+    state = (state * 1664525 + 1013904223) >>> 0;
+    return state / 4294967296;
+  };
+}
+
+function makeVector(random, dim = 64) {
+  const value = Array.from({ length: dim }, () => random() * 2 - 1);
+  const norm = Math.sqrt(value.reduce((sum, item) => sum + item * item, 0)) || 1;
+  return value.map((item) => item / norm);
+}
+
+function cosine(a, b) {
+  let dot = 0;
+  for (let i = 0; i < a.length; i += 1) dot += a[i] * b[i];
+  return dot;
+}
+
+function percentile(values, p) {
+  const sorted = [...values].sort((a, b) => a - b);
+  if (!sorted.length) return null;
+  return sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil((p / 100) * sorted.length) - 1))];
+}
+
+const count = Number(process.argv[2] ?? 5000);
+const queries = Number(process.argv[3] ?? 100);
+const ef = Number(process.argv[4] ?? 200);
+const random = randomFactory(20261111);
+const items = Array.from({ length: count }, (_, index) => ({ id: `h${index}`, vector: makeVector(random) }));
+const queryVectors = Array.from({ length: queries }, () => makeVector(random));
+const index = createHnswIndex({ M: 24, efConstruction: 200, efSearch: ef, seed: 20261111 });
+const buildStart = performance.now();
+index.rebuild(items);
+const buildMs = performance.now() - buildStart;
+
+const exactTimes = [];
+const hnswTimes = [];
+const exactResults = [];
+const hnswResults = [];
+for (const query of queryVectors) {
+  const exactStart = performance.now();
+  const exact = items
+    .map((item) => ({ id: item.id, score: cosine(item.vector, query) }))
+    .sort((a, b) => b.score - a.score)
+    .slice(0, 10);
+  exactTimes.push(performance.now() - exactStart);
+  exactResults.push(exact);
+
+  const hnswStart = performance.now();
+  const approx = index.search(query, 10, { ef }).slice(0, 10);
+  hnswTimes.push(performance.now() - hnswStart);
+  hnswResults.push(approx);
+}
+
+let hits = 0;
+let expectedTotal = 0;
+for (let index = 0; index < exactResults.length; index += 1) {
+  const expected = new Set(exactResults[index].map((item) => item.id));
+  for (const item of hnswResults[index]) if (expected.has(item.id)) hits += 1;
+  expectedTotal += expected.size;
+}
+
+console.log(JSON.stringify({
+  engine: 'hnsw',
+  count,
+  queries,
+  dim: 64,
+  ef,
+  buildMs: Math.round(buildMs * 100) / 100,
+  recallAt10: expectedTotal ? Math.round((hits / expectedTotal) * 10000) / 10000 : null,
+  exactP50Ms: Math.round((percentile(exactTimes, 50) ?? 0) * 1000) / 1000,
+  hnswP50Ms: Math.round((percentile(hnswTimes, 50) ?? 0) * 1000) / 1000,
+  exactP95Ms: Math.round((percentile(exactTimes, 95) ?? 0) * 1000) / 1000,
+  hnswP95Ms: Math.round((percentile(hnswTimes, 95) ?? 0) * 1000) / 1000,
+}, null, 2));

package/bench/locomo.js

@@ -0,0 +1,89 @@
+import { evaluateQueries } from './metrics.js';
+
+/**
+ * LoCoMo retrieval adapter (offline, no dataset bundled).
+ * Dataset/repo: https://github.com/snap-research/locomo
+ *
+ * The adapter is intentionally shape-tolerant: official samples expose
+ * conversation sessions as `session_1`, `session_2`, ... with `evidence` like
+ * `D1:2`. It evaluates retrieval only; it does not claim official QA scores.
+ */
+
+function sessionKeys(conversation) {
+  return Object.keys(conversation ?? {})
+    .filter((key) => /^session_\d+$/.test(key))
+    .sort((a, b) => Number(a.split('_')[1]) - Number(b.split('_')[1]));
+}
+
+function parseEvidence(evidence) {
+  const list = Array.isArray(evidence) ? evidence : [evidence];
+  const out = [];
+  for (const item of list) {
+    const match = String(item ?? '').match(/D(\d+):(\d+)/i);
+    if (match) out.push({ session: Number(match[1]), turn: Number(match[2]) });
+  }
+  return out;
+}
+
+export function buildLoCoMoIndex({ cortex, samples = [], scopeId = 'global' } = {}) {
+  if (!cortex) throw new Error('buildLoCoMoIndex needs cortex');
+  const turnTraceIds = new Map();
+  const queries = [];
+  let traces = 0;
+
+  for (const sample of samples) {
+    const sampleId = String(sample.sample_id ?? `sample-${queries.length}`);
+    const conversation = sample.conversation ?? {};
+    for (const key of sessionKeys(conversation)) {
+      const number = Number(key.split('_')[1]);
+      const date = conversation[`${key}_date_time`] ?? conversation[`${key}_date`] ?? null;
+      const turns = Array.isArray(conversation[key]) ? conversation[key] : [];
+      turns.forEach((turn, index) => {
+        const text = `${turn.speaker ?? turn.role ?? '用户'}：${turn.text ?? turn.content ?? ''}`;
+        if (!text.trim()) return;
+        const written = cortex.write({
+          text,
+          kind: 'episode',
+          title: `LoCoMo ${sampleId} D${number}:${index + 1}`,
+          tags: ['locomo'],
+          explicit: true,
+          importance: 0.5,
+          operationId: `locomo:${sampleId}:D${number}:${index + 1}`,
+          now: date ? Date.parse(date) : undefined,
+        });
+        if (written.trace) {
+          turnTraceIds.set(`${sampleId}:D${number}:${index + 1}`, written.trace.id);
+          traces += 1;
+        }
+      });
+    }
+    for (const item of sample.qa ?? []) {
+      const relevant = [];
+      for (const ref of parseEvidence(item.evidence)) {
+        const id = turnTraceIds.get(`${sampleId}:D${ref.session}:${ref.turn}`);
+        if (id) relevant.push(id);
+      }
+      queries.push({
+        id: `${sampleId}:${queries.length}`,
+        query: item.question ?? '',
+        answer: item.answer ?? null,
+        type: String(item.category ?? 'unknown'),
+        relevant,
+        evidence: item.evidence ?? [],
+      });
+    }
+  }
+  return { scopeId, traces, queries, turnTraceIds };
+}
+
+export async function evaluateLoCoMoRetrieval({ cortex, samples = [], limit = 10, includeAdversarial = false } = {}) {
+  const built = buildLoCoMoIndex({ cortex, samples });
+  const evaluated = built.queries.filter((query) => includeAdversarial || query.type !== '5');
+  const results = evaluated.map((query) => ({ items: cortex.search(query.query, { limit, budget: 3000 }).items, relevant: query.relevant, type: query.type }));
+  const overall = evaluateQueries(results, { k: limit });
+  const byType = {};
+  const buckets = {};
+  for (const result of results) (buckets[result.type] ??= []).push(result);
+  for (const [type, bucket] of Object.entries(buckets)) byType[type] = evaluateQueries(bucket, { k: limit });
+  return { ...overall, byType, built: { traces: built.traces, queries: built.queries.length, evaluated: evaluated.length } };
+}

package/bench/longmemeval.js

@@ -0,0 +1,83 @@
+import { evaluateQueries } from './metrics.js';
+
+/**
+ * LongMemEval retrieval adapter (offline, no dataset bundled).
+ * Dataset: https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned
+ * Paper:   https://arxiv.org/abs/2410.10813
+ *
+ * This adapter evaluates session/turn *retrieval*, not end-to-end QA. It does
+ * not claim official LongMemEval scores.
+ */
+
+export function instanceType(instance) {
+  if (String(instance.question_id ?? '').endsWith('_abs')) return 'abstention';
+  return instance.question_type ?? 'unknown';
+}
+
+export function buildLongMemEvalIndex({ cortex, instances = [], scopeId = 'global' } = {}) {
+  if (!cortex) throw new Error('buildLongMemEvalIndex needs cortex');
+  const sessionTraceIds = new Map();
+  const queries = [];
+  let traces = 0;
+
+  for (const instance of instances) {
+    const qid = String(instance.question_id ?? `q${queries.length}`);
+    const questionDate = instance.question_date ? Date.parse(instance.question_date) : Date.now();
+    const sessions = Array.isArray(instance.haystack_sessions) ? instance.haystack_sessions : [];
+    const sessionIds = Array.isArray(instance.haystack_session_ids) ? instance.haystack_session_ids : [];
+    const dates = Array.isArray(instance.haystack_dates) ? instance.haystack_dates : [];
+    const turnRelevant = [];
+    sessions.forEach((turns, sessionIndex) => {
+      const sessionId = String(sessionIds[sessionIndex] ?? `${qid}-s${sessionIndex}`);
+      const text = (Array.isArray(turns) ? turns : [])
+        .map((turn) => `${turn.role === 'assistant' ? '助手' : '用户'}：${turn.content ?? ''}`)
+        .join('\n');
+      if (!text.trim()) return;
+      const written = cortex.write({
+        text,
+        kind: 'episode',
+        title: `LongMemEval ${qid} ${sessionId}`,
+        tags: ['longmemeval', instanceType(instance)],
+        explicit: true,
+        importance: 0.5,
+        operationId: `lme:${qid}:${sessionId}`,
+        now: dates[sessionIndex] ? Date.parse(dates[sessionIndex]) : questionDate,
+      });
+      if (written.trace) {
+        sessionTraceIds.set(`${qid}:${sessionId}`, written.trace.id);
+        traces += 1;
+      }
+    });
+    const relevant = (instance.answer_session_ids ?? [])
+      .map((sessionId) => sessionTraceIds.get(`${qid}:${sessionId}`))
+      .filter(Boolean);
+    queries.push({
+      id: qid,
+      query: instance.question ?? '',
+      type: instanceType(instance),
+      questionDate: new Date(questionDate).toISOString(),
+      relevant,
+      answer: instance.answer ?? null,
+      abstention: instanceType(instance) === 'abstention',
+    });
+  }
+
+  return { scopeId, traces, queries, sessionTraceIds };
+}
+
+export function evaluateLongMemEvalRetrieval({ cortex, instances = [], limit = 10, includeAbstention = false } = {}) {
+  const built = buildLongMemEvalIndex({ cortex, instances });
+  const evaluated = built.queries.filter((query) => includeAbstention || !query.abstention);
+  const results = evaluated.map((query) => {
+    const output = cortex.search(query.query, { limit, budget: 3000 });
+    return { items: output.items, relevant: query.relevant, type: query.type };
+  });
+  const overall = evaluateQueries(results, { k: limit });
+  const byType = {};
+  const typeBuckets = {};
+  results.forEach((result) => {
+    (typeBuckets[result.type] ??= []).push(result);
+  });
+  for (const [type, bucket] of Object.entries(typeBuckets)) byType[type] = evaluateQueries(bucket, { k: limit });
+  return { ...overall, byType, built: { traces: built.traces, queries: built.queries.length, evaluated: evaluated.length } };
+}

package/bench/metrics.js

@@ -0,0 +1,67 @@
+export function recallAtK(ranked, relevant, k = 10) {
+  const rel = new Set(relevant);
+  const top = ranked.slice(0, Math.max(1, k));
+  return rel.size === 0 ? 0 : top.filter((id) => rel.has(id)).length / rel.size;
+}
+
+export function hitAtK(ranked, relevant, k = 10) {
+  const rel = new Set(relevant);
+  if (rel.size === 0) return 0;
+  return ranked.slice(0, Math.max(1, k)).some((id) => rel.has(id)) ? 1 : 0;
+}
+
+export function precisionAtK(ranked, relevant, k = 10) {
+  const rel = new Set(relevant);
+  const top = ranked.slice(0, Math.max(1, k));
+  return top.length === 0 ? 0 : top.filter((id) => rel.has(id)).length / top.length;
+}
+
+export function reciprocalRank(ranked, relevant, k = 10) {
+  const rel = new Set(relevant);
+  for (let i = 0; i < Math.min(ranked.length, k); i += 1) {
+    if (rel.has(ranked[i])) return 1 / (i + 1);
+  }
+  return 0;
+}
+
+export function ndcgAtK(ranked, relevant, k = 10) {
+  const rel = new Set(relevant);
+  if (rel.size === 0) return 0;
+  let dcg = 0;
+  for (let i = 0; i < Math.min(ranked.length, k); i += 1) {
+    if (rel.has(ranked[i])) dcg += 1 / Math.log2(i + 2);
+  }
+  let idcg = 0;
+  for (let i = 0; i < Math.min(rel.size, k); i += 1) idcg += 1 / Math.log2(i + 2);
+  return idcg === 0 ? 0 : dcg / idcg;
+}
+
+export function percentile(values, p) {
+  const list = values.filter((value) => Number.isFinite(value)).slice().sort((a, b) => a - b);
+  if (list.length === 0) return null;
+  const index = Math.min(list.length - 1, Math.max(0, Math.ceil((p / 100) * list.length) - 1));
+  return list[index];
+}
+
+export function evaluateQueries(results, { k = 10 } = {}) {
+  const rows = results.map((result) => {
+    const ranked = (result.items ?? []).map((item) => item.id);
+    const relevant = result.relevant ?? [];
+    return {
+      recall: recallAtK(ranked, relevant, k),
+      hit: hitAtK(ranked, relevant, k),
+      precision: precisionAtK(ranked, relevant, k),
+      mrr: reciprocalRank(ranked, relevant, k),
+      ndcg: ndcgAtK(ranked, relevant, k),
+    };
+  });
+  const mean = (key) => rows.length ? rows.reduce((sum, row) => sum + row[key], 0) / rows.length : 0;
+  return {
+    n: rows.length,
+    recallAtK: mean('recall'),
+    hitAtK: mean('hit'),
+    precisionAtK: mean('precision'),
+    mrrAtK: mean('mrr'),
+    ndcgAtK: mean('ndcg'),
+  };
+}

package/bench/migration-bench.mjs

@@ -0,0 +1,69 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createCortex } from '../src/service/cortex.js';
+import { openDatabase, migrate, getMeta, closeDatabase, FTS_INDEX_VERSION } from '../src/store/database.js';
+import { createTraceRepository } from '../src/store/repositories/traces.js';
+import { ftsText } from '../src/memory/tokenizer.js';
+
+const count = Number(process.argv[2] ?? 5000);
+const dir = mkdtempSync(path.join(os.tmpdir(), `cortex-migrate-${count}-`));
+const dbFile = path.join(dir, 'cortex.sqlite');
+const totalStart = performance.now();
+const phases = {};
+let cortex;
+try {
+  cortex = createCortex({ config: { dataRoot: dir, dbFile, contextBudget: 2200 } });
+  console.error(`phase create done (${Math.round(performance.now() - totalStart)}ms)`);
+  const texts = [];
+  for (let i = 0; i < count; i += 1) {
+    texts.push({
+      text: i === 0 ? '白饭：升级后仍然应该能通过“米饭”的 soft 查询找到。' : `老库迁移样本 ${i}：普通记忆内容。`,
+      title: `迁移样本 #${i}`,
+      explicit: true,
+      operationId: `migrate:${count}:${i}`,
+      now: Date.UTC(2026, 0, 1) + i * 1000,
+    });
+  }
+  const writeStart = performance.now();
+  cortex.writeMany(texts, { chunkSize: 500 });
+  phases.writeMs = Math.round((performance.now() - writeStart) * 100) / 100;
+  console.error(`phase write done (${phases.writeMs}ms)`);
+  cortex.close();
+  cortex = null;
+
+  let opened = openDatabase({ dataRoot: dir, dbFile });
+  opened.db.exec('DELETE FROM traces_fts_index');
+  opened.db.prepare('DELETE FROM meta WHERE key = ?').run('fts_index_version');
+  const rows = opened.db.prepare('SELECT id, title, content, summary FROM traces').all();
+  const insert = opened.db.prepare('INSERT INTO traces_fts_index(trace_id, text) VALUES (?, ?)');
+  for (const row of rows) {
+    insert.run(row.id, ftsText(`${row.title ?? ''} ${row.content ?? ''} ${row.summary ?? ''}`));
+  }
+  closeDatabase(opened.db);
+  phases.oldIndexMs = Math.round((performance.now() - writeStart) * 100) / 100;
+  console.error(`phase old-index done (${phases.oldIndexMs}ms total from write)`);
+
+  const started = performance.now();
+  opened = openDatabase({ dataRoot: dir, dbFile });
+  const result = migrate(opened.db);
+  const elapsedMs = performance.now() - started;
+  phases.migrateMs = Math.round(elapsedMs * 100) / 100;
+  console.error(`phase migrate done (${phases.migrateMs}ms)`);
+  const softHits = createTraceRepository(opened.db).searchFts('米饭', { soft: true });
+  phases.totalMs = Math.round((performance.now() - totalStart) * 100) / 100;
+  console.log(JSON.stringify({
+    count,
+    ftsRebuilt: result.ftsRebuilt,
+    elapsedMs: Math.round(elapsedMs * 100) / 100,
+    phases,
+    ftsVersion: getMeta(opened.db, 'fts_index_version'),
+    expectedVersion: String(FTS_INDEX_VERSION),
+    softHits: softHits.length,
+    dbBytes: opened.db.prepare('PRAGMA page_count').get().page_count * opened.db.prepare('PRAGMA page_size').get().page_size,
+  }, null, 2));
+  closeDatabase(opened.db);
+} finally {
+  if (cortex) cortex.close();
+  rmSync(dir, { recursive: true, force: true });
+}