dsh-cortex-memory 0.1.0 → 0.2.0-rc.13

package/src/store/database.js

@@ -5,10 +5,19 @@ import { DatabaseSync } from 'node:sqlite';
 import { nowIso } from '../core/time.js';
 import { normalizeConfig, validateConfig } from '../core/config.js';
 import { CortexError, ERROR_CODES } from '../core/errors.js';
+import { ftsText } from '../memory/tokenizer.js';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const SCHEMA_FILE = path.join(HERE, 'schema.sql');
 export const SCHEMA_VERSION = 6;
+export const FTS_INDEX_VERSION = 2;
+
+function ensureTraceColumns(db) {
+  const columns = db.prepare('PRAGMA table_info(traces)').all();
+  if (!columns.some((column) => column.name === 'metadata_json')) {
+    db.exec("ALTER TABLE traces ADD COLUMN metadata_json TEXT NOT NULL DEFAULT '{}'");
+  }
+}
 
 function ensureFactsColumns(db) {
   const columns = db.prepare('PRAGMA table_info(facts)').all();
@@ -25,6 +34,27 @@ function ensureParent(file) {
   fs.mkdirSync(path.dirname(file), { recursive: true });
 }
 
+function rebuildFtsIndex(db) {
+  db.exec('DELETE FROM traces_fts_index');
+  const insert = db.prepare('INSERT INTO traces_fts_index(trace_id, text) VALUES (?, ?)');
+  const rows = db.prepare('SELECT id, title, content, summary FROM traces').all();
+  for (const row of rows) {
+    const text = ftsText(`${row.title ?? ''} ${row.content ?? ''} ${row.summary ?? ''}`, { soft: true });
+    if (text) insert.run(row.id, text);
+  }
+}
+
+function ensureFtsIndex(db) {
+  const row = db.prepare('SELECT value FROM meta WHERE key = ?').get('fts_index_version');
+  if (Number(row?.value ?? 0) === FTS_INDEX_VERSION) return false;
+  rebuildFtsIndex(db);
+  db.prepare(`
+    INSERT INTO meta(key, value, updated_at) VALUES (?, ?, ?)
+    ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at
+  `).run('fts_index_version', String(FTS_INDEX_VERSION), nowIso());
+  return true;
+}
+
 function readSchema() {
   return fs.readFileSync(SCHEMA_FILE, 'utf8');
 }
@@ -44,6 +74,7 @@ export function migrate(db, { version = SCHEMA_VERSION } = {}) {
   db.exec('BEGIN IMMEDIATE');
   try {
     db.exec(readSchema());
+    ensureTraceColumns(db);
     ensureFactsColumns(db);
     const row = db.prepare('SELECT value FROM meta WHERE key = ?').get('schema_version');
     if (!row) {
@@ -53,8 +84,9 @@ export function migrate(db, { version = SCHEMA_VERSION } = {}) {
     } else if (Number(row.value) < version) {
       db.prepare('UPDATE meta SET value = ?, updated_at = ? WHERE key = ?').run(String(version), nowIso(), 'schema_version');
     }
+    const ftsRebuilt = ensureFtsIndex(db);
     db.exec('COMMIT');
-    return { version, applied: true };
+    return { version, applied: true, ftsRebuilt };
   } catch (error) {
     try { db.exec('ROLLBACK'); } catch { /* ignore rollback failure */ }
     throw error;

package/src/store/repositories/edges.js

@@ -31,6 +31,9 @@ export function createEdgeRepository(db) {
       ORDER BY valid_from DESC LIMIT 1
     `).get(scopeId, fromId, toId, rel, validFrom);
     if (existing) {
+      const current = rowToEdge(existing);
+      // A candidate must never downgrade an already-active edge.
+      if (metadata?.status === 'candidate' && current.metadata?.status !== 'candidate') return current;
       db.prepare('UPDATE edges SET weight = ?, metadata_json = ?, updated_at = ? WHERE id = ?')
         .run(Number(weight), stableStringify(metadata), nowIso(), existing.id);
       return get(existing.id);
@@ -68,13 +71,54 @@ export function createEdgeRepository(db) {
     return rows.map(rowToEdge).filter((edge) => {
       if (seen.has(edge.id)) return false;
       seen.add(edge.id);
-      return true;
+      return edge.metadata?.status !== 'candidate' && edge.metadata?.status !== 'rejected';
     });
   }
 
-  function list({ scopeId = 'global', limit = 200 } = {}) {
+  function list({ scopeId = 'global', limit = 200, includeCandidates = false } = {}) {
     const count = Math.max(1, Math.min(10000, Number(limit) || 200));
-    return db.prepare('SELECT * FROM edges WHERE scope_id = ? ORDER BY updated_at DESC LIMIT ?').all(scopeId, count).map(rowToEdge);
+    return db.prepare('SELECT * FROM edges WHERE scope_id = ? ORDER BY updated_at DESC LIMIT ?').all(scopeId, count)
+      .map(rowToEdge)
+      .filter((edge) => includeCandidates || (edge.metadata?.status !== 'candidate' && edge.metadata?.status !== 'rejected'));
+  }
+
+  function addCandidate({ scopeId = 'global', fromId, toId, rel = 'related', weight = 0.5, confidence = 0.5, sourceEventId = null, sourceTraceId = null, evidence = null, metadata = {} } = {}) {
+    return upsert({
+      scopeId,
+      fromId,
+      toId,
+      rel,
+      weight,
+      metadata: {
+        ...metadata,
+        status: 'candidate',
+        confidence,
+        sourceEventId,
+        sourceTraceId,
+        evidence,
+        proposedAt: nowIso(),
+      },
+    });
+  }
+
+  function listCandidates({ scopeId = 'global', limit = 200 } = {}) {
+    return list({ scopeId, limit, includeCandidates: true }).filter((edge) => edge.metadata?.status === 'candidate');
+  }
+
+  function approveCandidate(id, { at = nowIso() } = {}) {
+    const edge = get(id);
+    if (!edge || edge.metadata?.status !== 'candidate') return null;
+    db.prepare('UPDATE edges SET metadata_json = ?, updated_at = ? WHERE id = ?')
+      .run(stableStringify({ ...edge.metadata, status: 'active', approvedAt: at }), at, id);
+    return get(id);
+  }
+
+  function rejectCandidate(id, { at = nowIso() } = {}) {
+    const edge = get(id);
+    if (!edge || edge.metadata?.status !== 'candidate') return null;
+    db.prepare('UPDATE edges SET valid_to = ?, metadata_json = ?, updated_at = ? WHERE id = ?')
+      .run(at, stableStringify({ ...edge.metadata, status: 'rejected', rejectedAt: at }), at, id);
+    return get(id);
   }
 
   function invalidate(id, { at = nowIso() } = {}) {
@@ -82,5 +126,5 @@ export function createEdgeRepository(db) {
     return get(id);
   }
 
-  return { get, upsert, neighbors, list, invalidate };
+  return { get, upsert, neighbors, list, addCandidate, listCandidates, approveCandidate, rejectCandidate, invalidate };
 }

package/src/store/repositories/traces.js

@@ -1,11 +1,12 @@
 import { hashText, traceId } from '../../core/ids.js';
-import { asJsonArray, stableStringify } from '../../core/json.js';
+import { asJsonArray, asJsonObject, stableStringify } from '../../core/json.js';
 import { nowIso } from '../../core/time.js';
 import { ftsText, buildMatchQuery } from '../../memory/tokenizer.js';
 import { CortexError, ERROR_CODES } from '../../core/errors.js';
+import { FTS_INDEX_VERSION } from '../database.js';
 
 const COLUMNS = [
-  'title', 'content', 'summary', 'keywords_json', 'tags_json', 'event_id',
+  'title', 'content', 'summary', 'keywords_json', 'tags_json', 'metadata_json', 'event_id',
   'session_id', 'turn_id', 'actor', 'source', 'valid_at', 'recorded_at',
   'last_access_at', 'access_count', 'importance', 'confidence', 'salience',
   'valence', 'arousal', 'sensitivity', 'state', 'compression', 'stability',
@@ -20,6 +21,7 @@ const FIELD_MAP = Object.freeze({
   kind: 'kind',
   keywords: 'keywords_json',
   tags: 'tags_json',
+  metadata: 'metadata_json',
   eventId: 'event_id',
   sessionId: 'session_id',
   turnId: 'turn_id',
@@ -57,6 +59,7 @@ function rowToTrace(row) {
     summary: row.summary,
     keywords: asJsonArray(row.keywords_json),
     tags: asJsonArray(row.tags_json),
+    metadata: asJsonObject(row.metadata_json),
     eventId: row.event_id,
     sessionId: row.session_id,
     turnId: row.turn_id,
@@ -87,9 +90,11 @@ function rowToTrace(row) {
 }
 
 export function createTraceRepository(db) {
-  function syncFts(trace) {
-    db.prepare('DELETE FROM traces_fts_index WHERE trace_id = ?').run(trace.id);
-    const text = ftsText(`${trace.title ?? ''} ${trace.content ?? ''} ${trace.summary ?? ''}`);
+  function syncFts(trace, { replace = true } = {}) {
+    // trace_id is UNINDEXED in FTS5. Deleting by it on a brand-new insert scans
+    // the whole index and makes bulk writes quadratic; only updates need delete.
+    if (replace) db.prepare('DELETE FROM traces_fts_index WHERE trace_id = ?').run(trace.id);
+    const text = ftsText(`${trace.title ?? ''} ${trace.content ?? ''} ${trace.summary ?? ''}`, { soft: true });
     if (text) {
       db.prepare('INSERT INTO traces_fts_index(trace_id, text) VALUES (?, ?)').run(trace.id, text);
     }
@@ -110,6 +115,7 @@ export function createTraceRepository(db) {
       summary: input.summary ?? null,
       keywords: asJsonArray(input.keywords),
       tags: asJsonArray(input.tags),
+      metadata: asJsonObject(input.metadata),
       eventId: input.eventId,
       sessionId: input.sessionId ?? null,
       turnId: input.turnId ?? null,
@@ -140,15 +146,15 @@ export function createTraceRepository(db) {
     db.prepare(`
       INSERT INTO traces(
         id, scope_id, kind, title, content, summary, keywords_json, tags_json,
-        event_id, session_id, turn_id, actor, source, valid_at, recorded_at,
+        metadata_json, event_id, session_id, turn_id, actor, source, valid_at, recorded_at,
         last_access_at, access_count, importance, confidence, salience, valence,
         arousal, sensitivity, state, compression, stability, difficulty,
         retrievability, review_count, lapse_count, last_review_at, hash,
         created_at, updated_at
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(
       trace.id, trace.scopeId, trace.kind, trace.title, trace.content, trace.summary,
-      stableStringify(trace.keywords), stableStringify(trace.tags), trace.eventId,
+      stableStringify(trace.keywords), stableStringify(trace.tags), stableStringify(trace.metadata), trace.eventId,
       trace.sessionId, trace.turnId, trace.actor, trace.source, trace.validAt,
       trace.recordedAt, trace.lastAccessAt, trace.accessCount, trace.importance,
       trace.confidence, trace.salience, trace.valence, trace.arousal,
@@ -156,7 +162,7 @@ export function createTraceRepository(db) {
       trace.difficulty, trace.retrievability, trace.reviewCount, trace.lapseCount,
       trace.lastReviewAt, trace.hash, trace.createdAt, trace.updatedAt,
     );
-    syncFts(trace);
+    syncFts(trace, { replace: false });
     return trace;
   }
 
@@ -198,6 +204,7 @@ export function createTraceRepository(db) {
       if (!(key in patch)) continue;
       let value = patch[key];
       if (key === 'keywords' || key === 'tags') value = stableStringify(asJsonArray(value));
+      if (key === 'metadata') value = stableStringify(asJsonObject(value));
       sets.push(`${column} = ?`);
       values.push(value);
     }
@@ -222,8 +229,8 @@ export function createTraceRepository(db) {
     return result.changes > 0;
   }
 
-  function searchFts(query, { scopeId = 'global', limit = 30, includeArchived = false } = {}) {
-    const match = buildMatchQuery(query);
+  function searchFts(query, { scopeId = 'global', limit = 30, includeArchived = false, soft = false } = {}) {
+    const match = buildMatchQuery(query, { soft });
     if (!match) return [];
     const count = Math.max(1, Math.min(200, Number(limit) || 30));
     const stateClause = includeArchived ? "t.state IN ('active','archived')" : "t.state = 'active'";
@@ -253,7 +260,11 @@ export function createTraceRepository(db) {
   function reindexFts() {
     db.exec('DELETE FROM traces_fts_index');
     const rows = db.prepare('SELECT id, title, content, summary FROM traces').all();
-    for (const row of rows) syncFts({ id: row.id, title: row.title, content: row.content, summary: row.summary });
+    for (const row of rows) syncFts({ id: row.id, title: row.title, content: row.content, summary: row.summary }, { replace: false });
+    db.prepare(`
+      INSERT INTO meta(key, value, updated_at) VALUES (?, ?, ?)
+      ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at
+    `).run('fts_index_version', String(FTS_INDEX_VERSION), nowIso());
     return rows.length;
   }
 

package/src/store/schema.sql

@@ -40,6 +40,7 @@ CREATE TABLE IF NOT EXISTS traces (
   summary TEXT,
   keywords_json TEXT NOT NULL DEFAULT '[]',
   tags_json TEXT NOT NULL DEFAULT '[]',
+  metadata_json TEXT NOT NULL DEFAULT '{}',
   event_id TEXT NOT NULL REFERENCES events(id),
   session_id TEXT,
   turn_id TEXT,

package/src/tools/definitions.js

@@ -118,15 +118,23 @@ export function createToolDefinitions(service) {
       isConcurrencySafe: () => false,
       async execute(args = {}) {
         if (args.action === 'add') {
+          if (!service.scopeWritable(service.settings().scope)) return { text: '未执行：当前 scope 只读共享。' };
           const item = service.working.add({ text: args.text, kind: args.kind, priority: args.priority, pinned: args.pinned === true, ttlMs: args.ttlMs });
           return { text: `已加入工作记忆 ${item.id}：${item.text}` };
         }
         if (args.action === 'pin') {
+          if (args.id && !service.scopeWritableById('working', args.id)) return { text: '未执行：该工作项属于只读共享 scope。' };
           const item = service.working.update(args.id, { pinned: args.pinned !== false });
           return { text: item ? `已${item.pinned ? '置顶' : '取消置顶'} ${item.id}` : `没有 ${args.id}` };
         }
-        if (args.action === 'remove') return { text: service.working.remove(args.id) ? `已删除 ${args.id}` : `没有 ${args.id}` };
-        if (args.action === 'purge') return { text: `已清理 ${service.working.purgeExpired()} 条过期工作记忆` };
+        if (args.action === 'remove') {
+          if (args.id && !service.scopeWritableById('working', args.id)) return { text: '未执行：该工作项属于只读共享 scope。' };
+          return { text: service.working.remove(args.id) ? `已删除 ${args.id}` : `没有 ${args.id}` };
+        }
+        if (args.action === 'purge') {
+          if (!service.scopeWritable(service.settings().scope)) return { text: '未执行：当前 scope 只读共享。' };
+          return { text: `已清理 ${service.working.purgeExpired()} 条过期工作记忆` };
+        }
         const items = service.working.list();
         return { text: items.length ? items.map((item) => `- ${item.pinned ? '[pin] ' : ''}${item.id} (${item.priority}) ${item.text}`).join('\n') : '（工作记忆为空）' };
       },
@@ -153,14 +161,17 @@ export function createToolDefinitions(service) {
       isConcurrencySafe: () => false,
       async execute(args = {}) {
         if (args.action === 'add') {
+          if (!service.scopeWritable(service.settings().scope)) return { text: '未执行：当前 scope 只读共享。' };
           const goal = service.goals.add({ title: args.title, description: args.description, priority: args.priority });
           return { text: `目标已建 ${goal.id}：${goal.title}` };
         }
         if (args.action === 'complete') {
+          if (args.id && !service.scopeWritableById('goal', args.id)) return { text: '未执行：该目标属于只读共享 scope。' };
           const done = service.goals.complete(args.id);
           return { text: done ? `目标已完成：${done.title}` : `没有这个目标：${args.id}` };
         }
         if (args.action === 'update') {
+          if (args.id && !service.scopeWritableById('goal', args.id)) return { text: '未执行：该目标属于只读共享 scope。' };
           const goal = service.goals.update(args.id, { title: args.title, description: args.description, priority: args.priority, progress: args.progress, status: args.status });
           return { text: goal ? `已更新 ${goal.id}：${goal.status} ${Math.round(goal.progress * 100)}%` : `没有 ${args.id}` };
         }
@@ -190,6 +201,7 @@ export function createToolDefinitions(service) {
           return { text: result.revived ? `已复活 ${args.id}（下一次检索可命中）` : `没有这条记忆：${args.id}` };
         }
         if (args.action === 'compress') {
+          if (!service.scopeWritable(service.settings().scope)) return { text: '未执行：当前 scope 只读共享。' };
           const result = service.compression.compress({ limit: args.limit });
           return { text: `压缩归档 ${result.archived} 条。${result.items.map((item) => `\n- ${item.id} coverage ${item.coverage.toFixed(2)}`).join('')}` };
         }
@@ -219,6 +231,7 @@ export function createToolDefinitions(service) {
       isConcurrencySafe: () => false,
       async execute(args = {}) {
         if (args.action === 'diary-write') {
+          if (!service.scopeWritable(service.settings().scope)) return { text: '未执行：当前 scope 只读共享。' };
           const item = service.life.diaryWrite({ text: args.text, mood: args.mood });
           return { text: `日记已写：${item.id}\n${item.text}` };
         }
@@ -230,6 +243,7 @@ export function createToolDefinitions(service) {
           return { text: service.life.diaryForget(args.id) ? `已删日记 ${args.id}` : `没有这条日记：${args.id}` };
         }
         if (args.action === 'dream') {
+          if (!service.scopeWritable(service.settings().scope)) return { text: '未执行：当前 scope 只读共享。' };
           const dream = await service.life.dreamGenerate();
           return { text: `梦 ${dream.id}（来源 ${dream.sourceCount} 条，${dream.model}）：\n${dream.text}` };
         }
@@ -237,6 +251,7 @@ export function createToolDefinitions(service) {
           const list = service.life.sleepRuns({ limit: args.limit });
           return { text: list.length ? list.map((item) => `- ${item.id} · ${item.at}：${JSON.stringify(item.report)}`).join('\n') : '（还没有睡眠记录）' };
         }
+        if (!service.scopeWritable(service.settings().scope)) return { text: '未执行：当前 scope 只读共享。' };
         const report = await service.life.sleep({ windowDays: args.windowDays ?? 1 });
         return { text: `睡眠整理完成：清理工作记忆 ${report.purgedWorking} 条 · 反思 ${report.reflected} · 阶段 ${report.stage ?? '—'} · 情感对象 ${report.affectTargets}` };
       },
@@ -265,6 +280,7 @@ export function createToolDefinitions(service) {
           return { text: result.emotions.length ? result.emotions.map((item) => `${item.name}:${item.score}`).join(' / ') : '没有命中情绪词。' };
         }
         if (args.action === 'record') {
+          if (!service.scopeWritable(service.settings().scope)) return { text: '未执行：当前 scope 只读共享。' };
           const result = service.emotion.record({ text: args.text, target: args.target, traceId: args.traceId });
           return { text: result.event ? `已记情绪事件 ${result.event.id}：${result.emotions.map((item) => item.name).join('、')} → ${result.event.target}（${result.target.attitude}）` : '没有命中情绪词。' };
         }
@@ -352,6 +368,7 @@ export function createToolDefinitions(service) {
         if (args.action === 'sync') {
           const dir = args.dir;
           if (!dir) return { text: '同步 Markdown 需要 dir。' };
+          if (args.dryRun !== true && !service.scopeWritable(args.scope ?? service.settings().scope)) return { text: '未执行：该 scope 只读共享。' };
           const result = service.syncMarkdown(dir, { dryRun: args.dryRun === true, scopeId: args.scope });
           return { text: `Markdown 同步${result.dryRun ? '（dry-run）' : ''}：更新 ${result.updated}，新建 ${result.created}，文件 ${result.files}` };
         }
@@ -497,6 +514,7 @@ export function createToolDefinitions(service) {
         if (args.action === 'add') {
           if (!args.title) return { text: '准则需要 title。' };
           if (!args.body) return { text: '准则需要 body。' };
+          if (!service.scopeWritable(args.scope ?? service.settings().scope)) return { text: '未执行：该 scope 只读共享。' };
           const rule = service.playbook.add({ title: args.title, body: args.body, tags: args.tags, validTo: args.validTo ?? null, scopeId: args.scope });
           return { text: `已加准则 ${rule.id}：${rule.title}${rule.validTo ? `（到期 ${rule.validTo}）` : ''}` };
         }
@@ -506,20 +524,24 @@ export function createToolDefinitions(service) {
         }
         if (args.action === 'vote') {
           if (!args.id) return { text: '投票需要 id。' };
+          if (!service.scopeWritableById('playbook', args.id)) return { text: '未执行：该准则属于只读共享 scope。' };
           const rule = service.playbook.vote({ id: args.id, signal: args.signal ?? 'helpful' });
           return { text: rule ? `已记 ${rule.id}：helpful=${rule.helpful} harmful=${rule.harmful}` : `没有准则 ${args.id}` };
         }
         if (args.action === 'retire') {
           if (!args.id) return { text: '停用需要 id。' };
+          if (!service.scopeWritableById('playbook', args.id)) return { text: '未执行：该准则属于只读共享 scope。' };
           const rule = service.playbook.retire(args.id);
           return { text: rule ? `已停用 ${rule.id}` : `没有准则 ${args.id}` };
         }
         if (args.action === 'suggest') {
+          if (!service.scopeWritable(args.scope ?? service.settings().scope)) return { text: '未执行：该 scope 只读共享。' };
           const result = service.playbook.suggest({ scopeId: args.scope, limit: args.limit ?? 5 });
           return { text: result.count ? result.candidates.map((rule) => `- [candidate] ${rule.id} · ${rule.title}：${rule.body}`).join('\n') : '（没有新的准则候选）' };
         }
         if (args.action === 'approve') {
           if (!args.id) return { text: '确认需要 id。' };
+          if (!service.scopeWritableById('playbook', args.id)) return { text: '未执行：该准则属于只读共享 scope。' };
           const rule = service.playbook.approve(args.id);
           return { text: rule ? `已确认 ${rule.id}，下一轮生效` : `没有准则 ${args.id}` };
         }
@@ -567,6 +589,7 @@ export function createToolDefinitions(service) {
       output: TEXT_OUTPUT,
       isConcurrencySafe: () => true,
       async execute(args = {}) {
+        if (!args.id || !String(args.id).trim()) return { text: `没有这条记忆：${args.id}` };
         const trace = service.get(args.id);
         if (!trace) return { text: `没有这条记忆：${args.id}` };
         return {
@@ -614,6 +637,23 @@ export function createToolDefinitions(service) {
               required: ['subject', 'predicate'],
             },
           },
+          attachments: {
+            type: 'array',
+            description: 'Reference-only attachment metadata; no bytes are fetched or stored.',
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                kind: { type: 'string', enum: ['image', 'audio', 'video', 'file'] },
+                uri: { type: 'string' },
+                name: { type: 'string' },
+                mime: { type: 'string' },
+                bytes: { type: 'number' },
+                sha256: { type: 'string' },
+              },
+              required: ['kind', 'uri'],
+            },
+          },
         },
       },
       output: TEXT_OUTPUT,
@@ -629,10 +669,25 @@ export function createToolDefinitions(service) {
           operationId: args.operationId,
           scopeId: args.scope,
           facts: args.facts,
+          attachments: args.attachments,
         });
-        if (result.skipped) return { text: `未写入：${result.reason}${result.trace ? `（已有 ${result.trace.id}）` : ''}` };
+        if (result.skipped) {
+          const hint = {
+            'low-compression': '内容信息密度太低。若确实是用户要求记住的，请传 explicit: true，或提高 importance 后再试。',
+            'too-short': '内容太短。请写成一条完整、可检索的记忆。',
+            'stop-phrase': '这是停用短语。若确实要记，请换一条有具体内容的表达。',
+            duplicate: '已有相同内容。可以继续使用已有 trace，不必重复写。',
+            idempotent: '同一个 operationId 已处理过。可以继续使用已有 trace。',
+            'scope-read-only': '这个 scope 是只读共享的；请换到可写 scope，或让宿主解除只读。',
+          }[result.reason];
+          const factsNote = result.facts?.length ? `\n已应用 ${result.facts.length} 条事实。` : '';
+          const edgeNote = result.edgeCandidates?.length ? `\n候选边：${result.edgeCandidates.length} 条（待审核）。` : '';
+          return {
+            text: `未写入：${result.reason}${result.trace ? `（已有 ${result.trace.id}）` : ''}${factsNote}${edgeNote}${hint ? `\n提示：${hint}` : ''}`,
+          };
+        }
         return {
-          text: `已写入 ${result.trace.id}（${result.trace.kind}）\n事件：${result.event.id}\n压缩值：${result.compression.toFixed(3)}${result.facts?.length ? `\n事实：${result.facts.length} 条` : ''}`,
+          text: `已写入 ${result.trace.id}（${result.trace.kind}）\n事件：${result.event.id}\n压缩值：${result.compression.toFixed(3)}${result.facts?.length ? `\n事实：${result.facts.length} 条` : ''}${result.edgeCandidates?.length ? `\n候选边：${result.edgeCandidates.length} 条（待审核）` : ''}${result.trace.metadata?.attachments?.length ? `\n附件：${result.trace.metadata.attachments.length} 个（仅元数据）` : ''}`,
         };
       },
       presentCall: () => ({ card: 'generic', title: '写入记忆', kind: 'other' }),
@@ -676,8 +731,12 @@ export function createToolDefinitions(service) {
       output: TEXT_OUTPUT,
       isConcurrencySafe: () => false,
       async execute(args = {}) {
+        if (!args.id || !String(args.id).trim()) throw new Error('traceId is required');
+        if (!service.scopeWritableById('trace', args.id)) return { text: '未执行：该记忆属于只读共享 scope。' };
         const result = service.forget({ traceId: args.id, mode: args.mode });
-        if (!result.removed) return { text: `没有这条记忆：${args.id}` };
+        if (!result.removed) {
+          return { text: result.reason === 'scope-read-only' ? '未执行：该记忆属于只读共享 scope。' : `没有这条记忆：${args.id}` };
+        }
         return { text: args.mode === 'delete' ? `已删除 ${args.id}，并级联清理派生数据。` : `已归档 ${args.id}，可用关键词唤醒。` };
       },
       presentCall: () => ({ card: 'generic', title: '遗忘/删除记忆', kind: 'other' }),

package/src/vector/external-ann.js

@@ -0,0 +1,37 @@
+/**
+ * Future external ANN client. It is intentionally not wired into the search
+ * path yet: a local index service with its own lifecycle must exist first.
+ */
+export function createExternalAnnClient({ endpoint, timeoutMs = 800, headers = {}, fetchImpl = fetch } = {}) {
+  const url = String(endpoint ?? '').trim();
+  if (!/^https?:\/\//i.test(url)) throw new Error('external ANN endpoint must be http(s)');
+  const timeout = Math.max(100, Math.min(10000, Number(timeoutMs) || 800));
+
+  async function search(vector, k = 10, { signal } = {}) {
+    if (!Array.isArray(vector) || !vector.length) throw new Error('external ANN query vector is required');
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    const onAbort = () => controller.abort();
+    signal?.addEventListener?.('abort', onAbort, { once: true });
+    try {
+      const response = await fetchImpl(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...headers },
+        body: JSON.stringify({ vector, k: Math.max(1, Math.min(200, Number(k) || 10)) }),
+        signal: controller.signal,
+      });
+      if (!response.ok) throw new Error(`external ANN returned ${response.status}`);
+      const body = await response.json();
+      if (!Array.isArray(body?.items)) throw new Error('external ANN response needs items[]');
+      return body.items
+        .filter((item) => typeof item?.id === 'string' && Number.isFinite(item?.score))
+        .map((item) => ({ id: item.id, score: item.score }))
+        .slice(0, Math.max(1, Math.min(200, Number(k) || 10)));
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener?.('abort', onAbort);
+    }
+  }
+
+  return { endpoint: url, search };
+}