dsh-cortex-memory 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-cortex-memory contributors
+
+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,154 @@
-# Temporary Holding Version
+# Cortex Memory for DeepSeek Harness
 
-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.
+A layered, temporal, self-developing memory engine for DeepSeek Harness (DSH).
+It is designed for long-lived personal agents: memory that can be recalled,
+audited, consolidated and changed **without silently rewriting identity**.
+
+> Current public version: **0.1.0**
+> Package: `dsh-cortex-memory` (the npm name `dsh-cortex` is already taken by another project)
+> License: MIT
+
+## Why
+
+Most memory plugins stop at "store and recall". Cortex adds four things that are
+hard to bolt on later:
+
+1. **Layered memory** — L0 identity, L1 working, L1.5 playbook, L2 episodic,
+   L3 semantic/temporal graph, L4 procedural, L5 reflection, archive.
+2. **Temporal truth** — event ledger, bitemporal facts, `strict / historical /
+   belief / associative` queries, DSR forgetting.
+3. **Gated growth** — consolidation, reflection, playbook candidates, policy
+   proposals; identity and core changes require approval and can be rolled back.
+4. **Guardian** — health audit, budgets, circuit breaker, backup/validate/restore,
+   privacy cascade, secret/injection scanning.
+
+## Install
+
+Requirements:
+
+- Node.js **>= 24** (uses the built-in `node:sqlite`)
+- DSH `>=0.2.1-rc.2 <0.4.0`
+
+### From a GitHub release tgz
+
+```powershell
+dsh plugin --profile desktop add "C:\path\to\dsh-cortex-memory-0.1.0.tgz"
+```
+
+### From npm (after publishing)
+
+```powershell
+dsh plugin --profile desktop add dsh-cortex-memory
+```
+
+The plugin owns `~/.dsh/cortex` and does not read or write another memory
+plugin's data.
+
+## Models
+
+Cortex works with **no model** by default:
+
+| Mode | What it uses | Key |
+|---|---|---|
+| `hash` | local lexical fallback | no |
+| `local` | OpenAI-compatible local service, default Ollama `bge-m3` | no |
+| `remote` | OpenAI-compatible `/embeddings` | **required** |
+
+For local semantic search:
+
+```powershell
+ollama pull bge-m3
+```
+
+Then in **Settings → Embedding / rerank models** choose `local`, keep
+`http://127.0.0.1:11434/v1`, model `bge-m3`, dimension `1024`.
+
+Remote mode refuses to save without an API key. Keys are stored in the local
+data directory and are never returned by the settings API.
+
+Optional rerank uses an OpenAI-compatible `/rerank` endpoint; if it is off or
+fails, fusion order is kept.
+
+## UI
+
+The client panel includes:
+
+- Self / working memory / search / timeline / graph
+- Emotion and life views
+- Guardian, evolution, audit, retention
+- **Playbook** with candidate review before activation
+- Settings: feature switches, embedding/rerank configuration, permission
+  overrides and rollback
+
+All settings changes that affect runtime take effect after a plugin reload or
+DSH restart.
+
+## CLI
+
+```powershell
+node bin/cortex.mjs --data C:\path\to\data health
+node bin/cortex.mjs --data C:\path\to\data search --query "米食"
+node bin/cortex.mjs --data C:\path\to\data export-md --dir C:\path\to\mirror
+```
+
+## Compatibility
+
+Tested in our environment:
+
+- Windows 11
+- DSH 0.2.2-rc.1
+- Node.js 26.13.0
+- Fresh `~/.dsh/cortex` data root
+- No native runtime dependencies
+
+Requirements:
+
+- **Node.js >= 24** (the engine uses `node:sqlite`)
+- DSH `>=0.2.1-rc.2 <0.4.0`
+- One profile should run only one `cortex` host entry
+
+It is **not** guaranteed to work on Node 20/22, older DSH releases, or a
+profile that already has another plugin using the same `cortex` id. This is a
+real compatibility boundary, not a marketing detail.
+
+## Testing
+
+```powershell
+npm test
+```
+
+The repository includes unit and integration tests for storage, retrieval,
+temporal facts, playbook, consolidation, guardian, API, client contract,
+installation packaging and edge cases. Public copy test result: **373 passing**.
+
+A package-level smoke test is also run from the packed tgz before release.
+
+
+## Architecture
+
+```text
+Host events -> capture -> encode -> event ledger + trace + facts + FTS
+                                      |
+prompt <- budgets <- tiered recall <- hybrid retrieval (FTS + graph + vector)
+                                      |
+                     reflection / consolidation / playbook / growth
+                                      |
+                     identity versions / policies / guardian / audit
+```
+
+See [docs/install-windows.md](docs/install-windows.md),
+[docs/models.md](docs/models.md) and
+[docs/compatibility.md](docs/compatibility.md).
+
+## Data and privacy
+
+- Default data root: `~/.dsh/cortex`
+- No telemetry and no network calls by default
+- `hash` mode is fully offline
+- `local` mode talks only to the configured local service
+- `remote` mode sends text to the configured embedding endpoint
+- Do not put API keys in prompts or issue reports
+
+## License
+
+MIT. See [LICENSE](LICENSE).

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,59 @@
+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 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),
+      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'),
+    precisionAtK: mean('precision'),
+    mrrAtK: mean('mrr'),
+    ndcgAtK: mean('ndcg'),
+  };
+}

package/bench/run.js

@@ -0,0 +1,74 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createCortex } from '../src/service/cortex.js';
+import { generateSynthetic } from './synthetic.js';
+import { evaluateQueries, percentile } from './metrics.js';
+
+export function runBenchmark({
+  count = Number(process.env.CORTEX_BENCH_COUNT ?? 10000),
+  queries = Number(process.env.CORTEX_BENCH_QUERIES ?? 100),
+  seed = 42,
+  vector = process.env.CORTEX_BENCH_VECTOR === '1',
+  limit = 10,
+} = {}) {
+  const dir = mkdtempSync(path.join(os.tmpdir(), 'cortex-bench-'));
+  const cortex = createCortex({ config: { dataRoot: dir, dbFile: path.join(dir, 'cortex.sqlite'), vectorEnabled: vector, contextBudget: 2200 } });
+  try {
+    const dataset = generateSynthetic({ count, queries, seed });
+    const idMap = new Map();
+    const writeStart = performance.now();
+    const inputs = dataset.traces.map((trace) => ({
+      text: trace.text,
+      title: trace.title,
+      tags: trace.tags,
+      importance: trace.importance,
+      explicit: true,
+      operationId: `bench:${trace.id}`,
+      now: Date.parse(trace.recordedAt),
+    }));
+    const written = cortex.writeMany(inputs, { chunkSize: 250 });
+    for (let i = 0; i < written.length; i += 1) {
+      if (written[i].trace) idMap.set(dataset.traces[i].id, written[i].trace.id);
+    }
+    const writeMs = performance.now() - writeStart;
+    const results = [];
+    const searchLatencies = [];
+    for (const query of dataset.queries) {
+      const start = performance.now();
+      const result = cortex.search(query.query, { limit, budget: 2200 });
+      searchLatencies.push(performance.now() - start);
+      results.push({ items: result.items, relevant: query.relevant.map((id) => idMap.get(id)).filter(Boolean) });
+    }
+    const metrics = evaluateQueries(results, { k: limit });
+    return {
+      generatedAt: dataset.generatedAt,
+      seed,
+      count,
+      queries: dataset.queries.length,
+      vector,
+      writeMs: Math.round(writeMs),
+      writesPerSecond: Math.round((count / writeMs) * 1000),
+      search: {
+        p50Ms: Math.round((percentile(searchLatencies, 50) ?? 0) * 100) / 100,
+        p95Ms: Math.round((percentile(searchLatencies, 95) ?? 0) * 100) / 100,
+        ...metrics,
+      },
+      dbBytes: (() => {
+        try { return cortex.db.prepare('PRAGMA page_count').get().page_count * cortex.db.prepare('PRAGMA page_size').get().page_size; } catch { return null; }
+      })(),
+    };
+  } finally {
+    cortex.close();
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const isMain = process.argv[1] && import.meta.url === new URL(`file://${process.argv[1].replace(/\\/g, '/')}`).href;
+if (isMain) {
+  const args = process.argv.slice(2);
+  const count = Number(args.find((arg) => arg.startsWith('--count='))?.split('=')[1] ?? 10000);
+  const queries = Number(args.find((arg) => arg.startsWith('--queries='))?.split('=')[1] ?? 100);
+  const result = runBenchmark({ count, queries, vector: args.includes('--vector') });
+  console.log(JSON.stringify(result, null, 2));
+}

package/bench/synthetic.js

@@ -0,0 +1,55 @@
+/**
+ * Deterministic synthetic memory workload. It is not a public benchmark and
+ * must not be reported as LoCoMo/LongMemEval numbers; it is a local regression
+ * and latency harness.
+ */
+
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return function random() {
+    a += 0x6D2B79F5;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+const PLACES = ['米饭', '插件', '记忆引擎', '鲸鱼', '用户', '伙伴', '直播', '语音', '项目', '代码', '测试', 'D:\\legacy-data', 'QQ', 'B站', '声音', '梦', '日记'];
+const VERBS = ['修好了', '想起来了', '决定继续', '记录一下', '有点担心', '很开心', '测试了', '重新整理了', '发现了', '计划明天'];
+const TOPICS = ['图检索', '向量检索', '遗忘曲线', '工作卡', '火花卡', '身份版本', '关系模型', '反思', '巩固', '守护', '备份', '权限'];
+
+export function generateSynthetic({ count = 1000, queries = 50, seed = 42 } = {}) {
+  const random = mulberry32(seed);
+  const pick = (list) => list[Math.floor(random() * list.length)];
+  const traces = [];
+  const idByToken = new Map();
+  for (let i = 0; i < count; i += 1) {
+    const place = pick(PLACES);
+    const verb = pick(VERBS);
+    const topic = pick(TOPICS);
+    const day = 1 + Math.floor(random() * 300);
+    const text = `${place} ${verb} ${topic}，第 ${i} 条合成记忆。`;
+    const id = `trc_syn_${i}`;
+    traces.push({
+      id,
+      text,
+      title: `${topic} #${i}`,
+      tags: [place, topic],
+      importance: Math.round(random() * 100) / 100,
+      recordedAt: new Date(Date.UTC(2026, 0, 1) + day * 86400000).toISOString(),
+    });
+    for (const token of [place, topic]) {
+      const list = idByToken.get(token) ?? [];
+      list.push(id);
+      idByToken.set(token, list);
+    }
+  }
+  const queryList = [];
+  for (let i = 0; i < queries; i += 1) {
+    const token = pick([...idByToken.keys()]);
+    const relevant = (idByToken.get(token) ?? []).slice(0, 8);
+    queryList.push({ query: token, type: 'keyword', relevant });
+  }
+  return { traces, queries: queryList, seed, generatedAt: new Date().toISOString() };
+}

package/bin/cortex.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import os from 'node:os';
+import path from 'node:path';
+import { createCortex } from '../src/service/cortex.js';
+import { createShioriImporter } from '../src/adapters/shiori.js';
+import { exportMarkdown } from '../src/adapters/markdown.js';
+import { importMarkdown } from '../src/adapters/markdown-import.js';
+import { effectiveFeatures } from '../src/core/feature-overrides.js';
+
+function parse(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const eq = arg.indexOf('=');
+      if (eq > 0) out[arg.slice(2, eq)] = arg.slice(eq + 1);
+      else if (argv[i + 1] && !argv[i + 1].startsWith('--')) { out[arg.slice(2)] = argv[i + 1]; i += 1; }
+      else out[arg.slice(2)] = true;
+    } else {
+      out._.push(arg);
+    }
+  }
+  return out;
+}
+
+function usage() {
+  console.log(`dsh-cortex CLI (source only)
+
+  --data <dir>      cortex data directory (default ~/.dsh/cortex)
+
+Commands:
+  write --text <text> [--kind <kind>] [--importance 0.5]
+  search --query <text> [--limit 10]
+  self
+  health
+  guard
+  import-shiori --root <legacy-data>
+  export-md --dir <target>
+  import-md --dir <vault> [--dry-run]
+  bench [--count 10000] [--queries 100]
+`);
+}
+
+function main() {
+  const args = parse(process.argv.slice(2));
+  const command = args._[0];
+  const dataRoot = path.resolve(args.data ?? path.join(os.homedir(), '.dsh', 'cortex'));
+  if (!command || command === 'help' || args.help) { usage(); return; }
+
+  if (command === 'bench') {
+    const count = Number(args.count ?? 10000);
+    const queries = Number(args.queries ?? 100);
+    import('../bench/run.js').then(({ runBenchmark }) => {
+      const result = runBenchmark({ count, queries, vector: args.vector === true });
+      console.log(JSON.stringify(result, null, 2));
+    });
+    return;
+  }
+
+  const baseConfig = { dataRoot, dbFile: path.join(dataRoot, 'cortex.sqlite') };
+  const effective = effectiveFeatures(baseConfig);
+  const cortex = createCortex({ config: { ...baseConfig, features: effective.features } });
+  try {
+    if (command === 'write') {
+      const result = cortex.write({ text: args.text, kind: args.kind, importance: args.importance ? Number(args.importance) : undefined, explicit: true });
+      console.log(JSON.stringify({ skipped: result.skipped, id: result.trace?.id, kind: result.trace?.kind }, null, 2));
+      return;
+    }
+    if (command === 'search') {
+      const result = cortex.search(args.query ?? '', { limit: Number(args.limit ?? 10) });
+      for (const item of result.items) console.log(`[${item.layer}] ${item.score} ${item.id} ${item.title}\n  ${item.snippet}`);
+      return;
+    }
+    if (command === 'self') { console.log(JSON.stringify(cortex.self(), null, 2)); return; }
+    if (command === 'health') { console.log(JSON.stringify(cortex.health(), null, 2)); return; }
+    if (command === 'guard') { console.log(JSON.stringify(cortex.guardian.check(), null, 2)); return; }
+    if (command === 'import-shiori') {
+      const importer = createShioriImporter({ cortex });
+      console.log(JSON.stringify(importer.importFrom(args.root), null, 2));
+      return;
+    }
+    if (command === 'export-md') {
+      console.log(JSON.stringify(exportMarkdown(cortex, args.dir ?? path.join(dataRoot, 'mirror')), null, 2));
+      return;
+    }
+    if (command === 'import-md') {
+      console.log(JSON.stringify(importMarkdown(cortex, args.dir ?? process.cwd(), { dryRun: args['dry-run'] === true }), null, 2));
+      return;
+    }
+    usage();
+  } finally {
+    cortex.close();
+  }
+}
+
+main();
+