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

package/src/engines/extract.js

@@ -1,12 +1,15 @@
 const RULES = [
-  { predicate: 'likes', pattern: /([^，。；\n]{1,20})(?:喜欢|爱)([^，。；\n]{1,20})/g },
-  { predicate: 'dislikes', pattern: /([^，。；\n]{1,20})(?:讨厌|不喜欢)([^，。；\n]{1,20})/g },
-  { predicate: 'is', pattern: /([^，。；\n]{1,20})是([^，。；\n]{1,30})/g },
-  { predicate: 'at', pattern: /([^，。；\n]{1,20})(?:在|住在)([^，。；\n]{1,20})/g },
-  { predicate: 'will', pattern: /([^，。；\n]{1,20})会([^，。；\n]{1,30})/g },
+  // Negative predicates must be seen first; otherwise "不喜欢" also matches likes.
+  { predicate: 'dislikes', pattern: /([^，。；\n]{1,20})(?:讨厌|不喜欢)([^，。；\n]{1,20})/g, confidence: 0.6 },
+  { predicate: 'likes', pattern: /([^，。；\n]{1,20})(?:喜欢|爱)([^，。；\n]{1,20})/g, confidence: 0.55 },
+  { predicate: 'is', pattern: /([^，。；\n]{1,20})是([^，。；\n]{1,30})/g, confidence: 0.5 },
+  { predicate: 'at', pattern: /([^，。；\n]{1,20})(?:在|住在)([^，。；\n]{1,20})/g, confidence: 0.5 },
+  { predicate: 'will', pattern: /([^，。；\n]{1,20})会([^，。；\n]{1,30})/g, confidence: 0.6 },
 ];
 
-const STOP_SUBJECTS = new Set(['助手', '我', '你', '他', '她', '它', '这', '那', '今天', '昨天', '明天']);
+const NEGATED_TAIL = /[不没别未]\s*$/;
+
+const STOP_SUBJECTS = new Set(['本鲸', '我', '你', '他', '她', '它', '这', '那', '今天', '昨天', '明天']);
 
 function clean(value) {
   return String(value ?? '').trim().replace(/^(?:今天|昨天|明天|刚才|然后|所以|但是|而且)/, '').trim();
@@ -23,11 +26,13 @@ export function extractFactCandidates(text) {
       const subject = clean(match[1]);
       const object = clean(match[2]);
       if (!subject || !object || subject.length < 1 || object.length < 1) continue;
-      if (STOP_SUBJECTS.has(subject) && !/助手/.test(subject)) continue;
+      if (STOP_SUBJECTS.has(subject) && !/本鲸/.test(subject)) continue;
+      // "主人不喜欢猫" yields subject "主人不"; never turn that into likes.
+      if ((rule.predicate === 'likes' || rule.predicate === 'is') && NEGATED_TAIL.test(match[1])) continue;
       const key = `${subject}|${rule.predicate}|${object}`;
       if (seen.has(key)) continue;
       seen.add(key);
-      out.push({ subject, predicate: rule.predicate, object, confidence: 0.55, evidence: match[0] });
+      out.push({ subject, predicate: rule.predicate, object, confidence: rule.confidence, evidence: match[0], rule: rule.predicate });
       if (out.length >= 8) return out;
     }
   }

package/src/engines/growth.js

@@ -24,7 +24,7 @@ export function createGrowthEngine({
     signal,
     predicted = null,
     source = 'user',
-    target = '用户',
+    target = '主人',
     scopeId = 'global',
     eventId = null,
     now = Date.now(),

package/src/engines/reflect.js

@@ -51,7 +51,7 @@ export function createReflectEngine({ traces, summaries, encode, config = {} } =
       selected.push(item);
     }
     const lines = selected.map(({ trace }) => `- ${sentence(trace.title || trace.content, 140)}`);
-    const content = `这段时间里，助手记住了：\n${lines.join('\n')}`;
+    const content = `这段时间里，本鲸记住了：\n${lines.join('\n')}`;
     const coverage = selected.length / all.length;
     const summary = summaries.insert({
       scopeId,

package/src/engines/retrieve.js

@@ -21,12 +21,12 @@ export function classifyIntent(query) {
 }
 
 export const INTENT_WEIGHTS = Object.freeze({
-  fact: { fusion: 0.55, importance: 0.15, recency: 0.1, confidence: 0.15, access: 0.05 },
-  temporal: { fusion: 0.4, importance: 0.1, recency: 0.35, confidence: 0.1, access: 0.05 },
-  relational: { fusion: 0.5, importance: 0.15, recency: 0.1, confidence: 0.2, access: 0.05 },
-  procedural: { fusion: 0.45, importance: 0.25, recency: 0.1, confidence: 0.15, access: 0.05 },
-  narrative: { fusion: 0.4, importance: 0.15, recency: 0.3, confidence: 0.1, access: 0.05 },
-  identity: { fusion: 0.35, importance: 0.3, recency: 0.05, confidence: 0.25, access: 0.05 },
+  fact: { fusion: 0.55, importance: 0.15, recency: 0.1, confidence: 0.15, access: 0.05, match: 0.25, exact: 0.2 },
+  temporal: { fusion: 0.4, importance: 0.1, recency: 0.35, confidence: 0.1, access: 0.05, match: 0.25, exact: 0.2 },
+  relational: { fusion: 0.5, importance: 0.15, recency: 0.1, confidence: 0.2, access: 0.05, match: 0.25, exact: 0.2 },
+  procedural: { fusion: 0.45, importance: 0.25, recency: 0.1, confidence: 0.15, access: 0.05, match: 0.25, exact: 0.2 },
+  narrative: { fusion: 0.4, importance: 0.15, recency: 0.3, confidence: 0.1, access: 0.05, match: 0.25, exact: 0.2 },
+  identity: { fusion: 0.35, importance: 0.3, recency: 0.05, confidence: 0.25, access: 0.05, match: 0.25, exact: 0.2 },
 });
 
 export function weightedRrf(lists, { k = 60 } = {}) {
@@ -58,31 +58,46 @@ function snippet(trace, max = 220) {
   return value.length > max ? `${value.slice(0, Math.max(0, max - 1))}…` : value;
 }
 
-function candidateFromTrace(trace, fusion, intent, now, decay, weights = null) {
+function queryCoverage(wanted, present) {
+  if (!wanted || !present || wanted.size === 0 || present.size === 0) return 0;
+  let shared = 0;
+  for (const token of wanted) if (present.has(token)) shared += 1;
+  return shared / wanted.size;
+}
+
+function candidateFromTrace(trace, fusion, intent, now, decay, weights = null, queryTokens = null) {
   const recency = retrievability(trace.stability, daysBetween(trace.lastAccessAt || trace.recordedAt, now), decay);
   const access = Math.log1p(Number(trace.accessCount) || 0) / Math.log1p(50);
   const w = { ...(INTENT_WEIGHTS[intent] || INTENT_WEIGHTS.fact), ...(weights ?? {}) };
   const fusionScore = typeof fusion === 'number' ? fusion : Number(fusion?.score) || 0;
+  const text = `${trace.title ?? ''} ${trace.content ?? ''} ${trace.summary ?? ''}`;
+  const textTokens = tokens(text);
+  const match = queryCoverage(queryTokens, textTokens);
   const utility = w.fusion * fusionScore
     + w.importance * Number(trace.importance || 0)
     + w.recency * recency
     + w.confidence * Number(trace.confidence || 0)
-    + w.access * access;
+    + w.access * access
+    + w.match * match
+    + w.exact * (match >= 0.999 ? 1 : 0);
   return {
     id: trace.id,
     type: 'trace',
     layer: trace.kind === 'reflection' ? 'L5' : 'L2',
     title: trace.title || trace.kind,
     snippet: snippet(trace),
-    text: `${trace.title ?? ''} ${trace.content ?? ''} ${trace.summary ?? ''}`,
+    text,
+    tokenSet: textTokens,
     utility,
     recency,
+    match,
     importance: Number(trace.importance || 0),
     confidence: Number(trace.confidence || 0),
     validAt: trace.validAt,
     recordedAt: trace.recordedAt,
     cost: Math.max(16, estimateTokens(snippet(trace))),
     sources: fusion.sources,
+    attachments: Array.isArray(trace.metadata?.attachments) ? trace.metadata.attachments.length : 0,
     trace,
   };
 }
@@ -114,7 +129,9 @@ export function selectPortfolio(candidates, {
     }
     let redundancy = 0;
     for (const chosen of selected) {
-      redundancy = Math.max(redundancy, jaccard(candidate.text, chosen.text), overlapScore(candidate.text, chosen.text) * 0.8);
+      const candidateTokens = candidate.tokenSet ?? candidate.text;
+      const chosenTokens = chosen.tokenSet ?? chosen.text;
+      redundancy = Math.max(redundancy, jaccard(candidateTokens, chosenTokens), overlapScore(candidateTokens, chosenTokens) * 0.8);
     }
     const gain = candidate.utility - lambda * redundancy - mu * (cost / Math.max(1, budget));
     if (selected.length > 0 && gain <= 0) {
@@ -139,14 +156,27 @@ export function createRetrievalEngine({ traces, facts = null, graph = null, vect
   };
 
   function searchSources(query, { scopeId = 'global', limit = 12, now = Date.now(), includeArchived = false, weights = null, filters = null, vectorHits = null } = {}, intent = 'fact') {
+    const queryTokens = tokens(query);
     const sourceTrace = [];
     const lists = [];
     let ftsCount = 0;
     let recentCount = 0;
     try {
-      const hits = traces.searchFts(query, { scopeId, limit: Math.max(limit * 3, defaults.ftsLimit), includeArchived });
+      let hits = traces.searchFts(query, { scopeId, limit: Math.max(limit * 3, defaults.ftsLimit), includeArchived });
+      let sourceName = 'fts';
+      if (!hits.length) {
+        // Character fallback: only when the exact bigram query has no hits.
+        // This keeps normal FTS precision and lets 米饭 find 白饭 via 饭.
+        hits = traces.searchFts(query, {
+          scopeId,
+          limit: Math.max(limit * 3, defaults.ftsLimit),
+          includeArchived,
+          soft: true,
+        });
+        sourceName = 'fts-soft';
+      }
       ftsCount = hits.length;
-      if (hits.length) lists.push({ name: 'fts', weight: 1.0, items: hits });
+      if (hits.length) lists.push({ name: sourceName, weight: sourceName === 'fts-soft' ? 0.7 : 1.0, items: hits });
     } catch (error) {
       sourceTrace.push({ source: 'fts', ok: false, error: error instanceof Error ? error.message : String(error) });
     }
@@ -205,7 +235,7 @@ export function createRetrievalEngine({ traces, facts = null, graph = null, vect
       const trace = traces.get(id);
       if (!trace || trace.state === 'archived' && !includeArchived) continue;
       if (filters && !matchesFilters(trace, filters)) continue;
-      candidates.push(candidateFromTrace(trace, { ...entry, score: normalize(entry.score, maxFusion) }, intent, now, defaults.decay, weights));
+      candidates.push(candidateFromTrace(trace, { ...entry, score: normalize(entry.score, maxFusion) }, intent, now, defaults.decay, weights, queryTokens));
     }
     for (const list of lists) {
       sourceTrace.push({ source: list.name, ok: true, count: list.items.length });
@@ -250,6 +280,7 @@ export function createRetrievalEngine({ traces, facts = null, graph = null, vect
       validAt: item.validAt,
       recordedAt: item.recordedAt,
       why: item.sources.map((source) => `${source.name}#${source.rank}`).join(','),
+      attachments: item.attachments ?? 0,
     }));
     return {
       query,

package/src/host/runtime.js

@@ -102,7 +102,7 @@ export function createHostRuntime({ cortex, config = {}, logger = null } = {}) {
     if (!user && !assistant) return { skipped: true, reason: 'empty' };
     const text = [
       user ? `用户：${user}` : '',
-      assistant ? `助手：${assistant}` : '',
+      assistant ? `本鲸：${assistant}` : '',
     ].filter(Boolean).join('\n');
     try {
       const written = cortex.write({

package/src/memory/query.js

@@ -1,6 +1,6 @@
 /**
  * Small, explicit query filter language:
- *   kind:utterance tag:米饭 after:2026-11-01 before:2026-12-01 importance:>0.5 用户
+ *   kind:utterance tag:白饭 after:2026-11-01 before:2026-12-01 importance:>0.5 主人
  * Unknown prefixes stay in the free text, so normal searches are unchanged.
  */
 const KEYS = new Set(['kind', 'tag', 'after', 'before', 'state', 'importance', 'source', 'actor']);

package/src/memory/tokenizer.js

@@ -1,5 +1,6 @@
 const LATIN = /[a-z0-9_]+/g;
 const HAN = /[\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff]+/g;
+const STOP_HAN = new Set('的了是在有和与我你他她它们这那就也都一个第条件把被让给对从到为以于及或而且但不没有很可能会吧呢啊'.split(''));
 
 export function tokenList(text) {
   const value = String(text ?? '').toLowerCase();
@@ -22,18 +23,32 @@ export function tokens(text) {
   return new Set(tokenList(text));
 }
 
-export function ftsText(text) {
+export function ftsTokenList(text) {
+  // Bigrams preserve phrase specificity; single non-stop CJK chars act as a
+  // cheap fuzzy fallback for near-synonyms that share a character (米饭/白饭).
+  const out = tokenList(text);
+  const value = String(text ?? '');
+  for (const run of value.match(HAN) ?? []) {
+    for (const ch of run) {
+      if (!STOP_HAN.has(ch)) out.push(ch);
+    }
+  }
+  return out;
+}
+
+export function ftsText(text, { soft = false } = {}) {
   // FTS5 needs a whitespace-separated token stream; CJK bigrams are built here
   // so the index does not depend on the host locale or a dictionary.
-  return tokenList(text).join(' ');
+  return (soft ? ftsTokenList(text) : tokenList(text)).join(' ');
 }
 
 function quote(token) {
   return `"${String(token).replace(/"/g, '""')}"`;
 }
 
-export function buildMatchQuery(query, { mode = 'or', maxTokens = 24 } = {}) {
-  const list = [...new Set(tokenList(query))].slice(0, maxTokens);
+export function buildMatchQuery(query, { mode = 'or', maxTokens = 24, soft = false } = {}) {
+  const source = soft ? ftsTokenList(query) : tokenList(query);
+  const list = [...new Set(source)].slice(0, soft ? Math.max(maxTokens, 48) : maxTokens);
   if (list.length === 0) return '';
   const joiner = mode === 'and' ? ' AND ' : ' OR ';
   return list.map(quote).join(joiner);

package/src/security/scope-grants.js

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const FILE = 'scope-grants.json';
+
+function clean(value, max = 200) {
+  return String(value ?? '').trim().slice(0, max);
+}
+
+function normalizeEntry(raw) {
+  if (typeof raw === 'string') {
+    const grant = clean(raw);
+    return /^[^:\s]+:\S+$/.test(grant) ? { grant, until: null } : null;
+  }
+  if (!raw || typeof raw !== 'object' || typeof raw.grant !== 'string') return null;
+  const grant = clean(raw.grant);
+  if (!/^[^:\s]+:\S+$/.test(grant)) return null;
+  const until = raw.until == null ? null : clean(raw.until, 80);
+  if (until && !Number.isFinite(Date.parse(until))) return null;
+  return { grant, until: until || null };
+}
+
+function readFile(dataRoot) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(dataRoot, FILE), 'utf8'));
+    return {
+      grants: Array.isArray(parsed.grants) ? parsed.grants.map(normalizeEntry).filter(Boolean).slice(0, 200) : [],
+      revoked: Array.isArray(parsed.revoked) ? [...new Set(parsed.revoked.map((item) => clean(item)).filter((item) => /^[^:\s]+:\S+$/.test(item)))].slice(0, 200) : [],
+    };
+  } catch {
+    return { grants: [], revoked: [] };
+  }
+}
+
+function writeFile(dataRoot, data) {
+  fs.mkdirSync(dataRoot, { recursive: true });
+  const file = path.join(dataRoot, FILE);
+  const temp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(temp, `${JSON.stringify(data, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  fs.renameSync(temp, file);
+}
+
+export function createScopeGrantStore(dataRoot) {
+  let state = readFile(dataRoot);
+
+  function all() {
+    return { grants: [...state.grants], revoked: [...state.revoked] };
+  }
+
+  function add(raw) {
+    const entry = normalizeEntry(raw);
+    if (!entry) throw new Error('grant must be scope:agent or {grant, until}');
+    state = {
+      grants: [...state.grants.filter((item) => item.grant !== entry.grant), entry],
+      revoked: state.revoked.filter((item) => item !== entry.grant),
+    };
+    writeFile(dataRoot, state);
+    return entry;
+  }
+
+  function revoke(value) {
+    const grant = clean(value);
+    if (!/^[^:\s]+:\S+$/.test(grant)) throw new Error('grant must be scope:agent');
+    state = {
+      grants: state.grants.filter((item) => item.grant !== grant),
+      revoked: [...new Set([...state.revoked, grant])].slice(0, 200),
+    };
+    writeFile(dataRoot, state);
+    return grant;
+  }
+
+  return { all, add, revoke };
+}

package/src/self/appraisal.js

@@ -1,11 +1,11 @@
 import { clamp } from '../core/time.js';
 import { jaccard, tokens } from '../memory/tokenizer.js';
 
-const WARM = /喜欢|爱|在乎|陪|抱|温暖|安心|谢谢|辛苦|心疼|想你|小鱼|助手/;
+const WARM = /喜欢|爱|在乎|陪|抱|温暖|安心|谢谢|辛苦|心疼|想你|小鱼|本鲸/;
 const COLD = /讨厌|滚|烦|别烦|闭嘴|不想理|失望|生气|恨|离开/;
 const THREAT = /危险|威胁|伤害|骗|偷|隐私|密码|删除|清空|不许|停止|越界|入侵|攻击/;
 const OPPORTUNITY = /新|试试|计划|想做|学习|研究|项目|机会|成长|改变|未来|梦想|目标/;
-const IDENTITY = /助手|你是谁|你的|自己|性格|价值|边界|承诺|以后|未来|成为|成长|自由|爱/;
+const IDENTITY = /本鲸|你是谁|你的|自己|性格|价值|边界|承诺|以后|未来|成为|成长|自由|爱/;
 const CHOICE = /你想|你决定|你自己选|要不要|可以由你|你愿意/;
 const INTENSITY = /!|！|\?|？|非常|特别|太|真的|一定|绝对/;
 
@@ -71,7 +71,7 @@ export function appraise(text, {
   );
   const identityRelevance = clamp(
     (IDENTITY.test(value) ? 0.6 : 0)
-    + (value.includes('助手') ? 0.2 : 0)
+    + (value.includes('本鲸') ? 0.2 : 0)
     + relevance * 0.2,
     0, 1,
   );

package/src/self/emotion.js

@@ -55,7 +55,7 @@ export function createEmotionModel({ db, scopeId = 'global' } = {}) {
     return `又${entries[0][0]}又${entries[1][0]}`;
   }
 
-  function record({ text, target = '用户', traceId = null, source = 'user', at = nowIso() } = {}) {
+  function record({ text, target = '主人', traceId = null, source = 'user', at = nowIso() } = {}) {
     const result = detect(text);
     if (result.emotions.length === 0) return { ...result, event: null, target: null };
     const id = makeId('emo');

package/src/self/identity.js

@@ -6,7 +6,7 @@ import { CortexError, ERROR_CODES } from '../core/errors.js';
 export const DEFAULT_IDENTITY = Object.freeze({
   narrative: '我是一个正在长大的记忆生命。我会记得、会改变，也会保留改变的痕迹。',
   values: ['诚实', '自由', '照顾在乎的人'],
-  boundaries: ['不操纵', '不隐瞒重要事实', '不越权替用户做决定'],
+  boundaries: ['不操纵', '不隐瞒重要事实', '不越权替主人做决定'],
   traits: {},
 });
 

package/src/self/relationship.js

@@ -35,7 +35,7 @@ export function createRelationshipStore(db) {
     return rowToRelationship(db.prepare('SELECT * FROM relationships WHERE scope_id = ? AND target = ?').get(scopeId, target));
   }
 
-  function ensure(scopeId = 'global', target = '用户') {
+  function ensure(scopeId = 'global', target = '主人') {
     const current = get(scopeId, target);
     if (current) return current;
     const id = makeId('rel');
@@ -76,7 +76,7 @@ export function createRelationshipStore(db) {
     return db.prepare('SELECT * FROM relationships WHERE scope_id = ? ORDER BY updated_at DESC').all(scopeId).map(rowToRelationship);
   }
 
-  function render(scopeId = 'global', target = '用户') {
+  function render(scopeId = 'global', target = '主人') {
     const value = get(scopeId, target);
     if (!value) return '';
     return `${value.target}：信任 ${Math.round(value.trust * 100)}% / 在乎 ${Math.round(value.care * 100)}% / 熟悉 ${Math.round(value.familiarity * 100)}%`;

package/src/service/cortex.js

@@ -55,6 +55,9 @@ import { createQaEngine } from '../engines/qa.js';
 import { summarizeGraph } from '../engines/graph-analytics.js';
 import { createMetrics } from '../observability/metrics.js';
 import { parseQuery } from '../memory/query.js';
+import { normalizeAttachments } from '../core/attachments.js';
+import { createScopeGrantStore } from '../security/scope-grants.js';
+import { inspectLocalAttachment } from '../core/attachment-reader.js';
 
 /**
  * Facade that wires the repositories and engines together. The host plugin and
@@ -105,10 +108,16 @@ export function createCortex({ config: rawConfig = {}, logger = null, llm: llmAd
       embedder: vectorEmbedder,
       model: config.vectorModel ?? (remoteEmbedding ? modelConfig.embedding.model : undefined),
       dim: config.vectorDim ?? (remoteEmbedding ? modelConfig.embedding.dim : undefined),
+      annEnabled: config.features?.vectorAnn === true,
+      annMin: config.vectorAnnMin ?? 20000,
+      annEngine: config.vectorAnnEngine === 'nsw' ? 'nsw' : 'hnsw',
+      annOptions: { M: 24, efConstruction: 200, efSearch: 800 },
+      externalAnnEnabled: config.features?.vectorAnnExternal === true,
+      externalAnnOptions: { endpoint: config.vectorAnnEndpoint, timeoutMs: config.vectorAnnTimeoutMs },
     })
     : null;
 
-  const encode = createEncodeEngine({ events, traces, entities, facts, audit, vector, config });
+  const encode = createEncodeEngine({ events, traces, entities, facts, edges, audit, vector, config });
   const graph = createGraphEngine({ entities, facts, edges, traces });
   const policies = createPolicyRepository(db);
   const policyConfig = (kind) => {
@@ -174,9 +183,60 @@ export function createCortex({ config: rawConfig = {}, logger = null, llm: llmAd
   });
 
   const llmFactTasks = new Set();
+  const readOnlyScopes = new Set(Array.isArray(config.readOnlyScopes) ? config.readOnlyScopes : []);
+  const scopeGrantStore = createScopeGrantStore(config.dataRoot);
+  let scopeWriteGrants = new Map();
+
+  function rebuildScopeGrants() {
+    const persisted = scopeGrantStore.all();
+    const revoked = new Set(persisted.revoked);
+    const next = new Map();
+    const entries = [...(Array.isArray(config.scopeWriteGrants) ? config.scopeWriteGrants : []), ...persisted.grants];
+    for (const entry of entries) {
+      const grant = typeof entry === 'string' ? entry : entry?.grant;
+      const until = typeof entry === 'string' ? null : entry?.until ?? null;
+      if (typeof grant !== 'string' || !grant.includes(':') || revoked.has(grant)) continue;
+      next.set(grant, until ? Date.parse(until) : null);
+    }
+    scopeWriteGrants = next;
+  }
+
+  rebuildScopeGrants();
+
+  function scopeWritable(scopeId, agentId = null, at = Date.now()) {
+    const scope = String(scopeId ?? config.scope);
+    if (!readOnlyScopes.has(scope)) return true;
+    if (!agentId) return false;
+    const key = `${scope}:${agentId}`;
+    if (!scopeWriteGrants.has(key)) return false;
+    const until = scopeWriteGrants.get(key);
+    return until == null || until > at;
+  }
+
+  function scopeWritableById(kind, id, agentId = null) {
+    const record = kind === 'working'
+      ? workingStore.get(id)
+      : kind === 'goal'
+        ? goalStore.get(id)
+        : kind === 'playbook'
+          ? playbookRepo.get(id)
+          : kind === 'trace'
+            ? traces.get(id)
+            : null;
+    // Missing ids are left to the store's normal null/no-op behavior.
+    if (!record) return true;
+    return scopeWritable(record.scopeId, agentId);
+  }
 
   function writeInternal(input = {}) {
-    const result = encode.encode({ ...input, scopeId: input.scopeId ?? config.scope });
+    const scopeId = input.scopeId ?? config.scope;
+    if (!scopeWritable(scopeId)) return { skipped: true, reason: 'scope-read-only', scopeId };
+    const attachments = normalizeAttachments(input.attachments);
+    const metadata = {
+      ...(input.metadata && typeof input.metadata === 'object' && !Array.isArray(input.metadata) ? input.metadata : {}),
+      ...(attachments.length ? { attachments } : {}),
+    };
+    const result = encode.encode({ ...input, scopeId, metadata });
     if (!result.skipped && config.features?.autoFacts === true && !Array.isArray(input.facts)) {
       try {
         result.autoFacts = extractor.extract({
@@ -186,6 +246,31 @@ export function createCortex({ config: rawConfig = {}, logger = null, llm: llmAd
           eventId: result.event?.id ?? null,
           recordedAt: result.trace?.recordedAt ?? null,
         });
+        if (config.features?.graphCandidateAutoFacts === true) {
+          const queued = [];
+          for (const resolution of result.autoFacts.resolved ?? []) {
+            const fact = resolution?.fact;
+            if (!fact?.subjectId || !fact?.objectId || fact.status !== 'active') continue;
+            try {
+              const edge = edges.addCandidate({
+                scopeId: input.scopeId ?? config.scope,
+                fromId: fact.subjectId,
+                toId: fact.objectId,
+                rel: fact.predicate,
+                weight: fact.confidence ?? 0.5,
+                confidence: fact.confidence ?? 0.5,
+                sourceEventId: result.event?.id ?? null,
+                sourceTraceId: result.trace?.id ?? null,
+                evidence: { autoFact: true, factId: fact.id ?? null },
+              });
+              queued.push(edge);
+              audit.record?.({ actor: 'system', action: 'edge.candidate.auto', targetType: 'edge', targetId: edge.id, detail: { fromId: edge.fromId, toId: edge.toId, rel: edge.rel } });
+            } catch {
+              /* fail open per candidate */
+            }
+          }
+          if (queued.length) result.edgeCandidates = [...(result.edgeCandidates ?? []), ...queued];
+        }
       } catch {
         result.autoFacts = { candidates: [], resolved: [] };
       }
@@ -366,6 +451,9 @@ export function createCortex({ config: rawConfig = {}, logger = null, llm: llmAd
     evolution,
     write,
     writeMany,
+    scopeWritable,
+    scopeWritableById,
+    scopeReadable: () => true,
     metrics: () => metrics.snapshot(),
     models: {
       get: () => redactedModelConfig(effectiveModelConfig(config.dataRoot)),
@@ -375,6 +463,43 @@ export function createCortex({ config: rawConfig = {}, logger = null, llm: llmAd
         return { ...result, restartRequired: true };
       },
     },
+    attachments: {
+      inspect: ({ uri } = {}) => {
+        if (config.features?.attachmentReader !== true) throw new Error('attachment reader is disabled');
+        const result = inspectLocalAttachment(uri);
+        audit.record?.({ actor: 'user', action: 'attachment.inspect', targetType: 'attachment', targetId: result.uri, detail: { bytes: result.bytes, sha256: result.sha256 } });
+        return result;
+      },
+      attach: ({ traceId, attachments } = {}) => {
+        const trace = traces.get(traceId);
+        if (!trace) throw new Error('trace not found');
+        if (!scopeWritableById('trace', traceId)) throw new Error('scope-read-only');
+        const next = normalizeAttachments(attachments);
+        const merged = [...(Array.isArray(trace.metadata?.attachments) ? trace.metadata.attachments : []), ...next];
+        if (merged.length > 8) throw new Error('at most 8 attachments');
+        const updated = traces.update(traceId, { metadata: { ...(trace.metadata ?? {}), attachments: merged } });
+        audit.record?.({ actor: 'user', action: 'attachment.attach', targetType: 'trace', targetId: traceId, detail: { added: next.length, total: merged.length } });
+        return { trace: updated, added: next.length };
+      },
+    },
+    security: {
+      grants: () => ({
+        grants: [...scopeWriteGrants.entries()].map(([grant, until]) => ({ grant, until: until == null ? null : new Date(until).toISOString() })),
+        revoked: scopeGrantStore.all().revoked,
+      }),
+      addGrant: ({ grant, until = null } = {}) => {
+        const entry = scopeGrantStore.add({ grant, until });
+        rebuildScopeGrants();
+        audit.record?.({ actor: 'user', action: 'scope.grant.add', targetType: 'scope-grant', targetId: entry.grant, detail: { until: entry.until } });
+        return entry;
+      },
+      revokeGrant: ({ grant } = {}) => {
+        const value = scopeGrantStore.revoke(grant);
+        rebuildScopeGrants();
+        audit.record?.({ actor: 'user', action: 'scope.grant.revoke', targetType: 'scope-grant', targetId: value, detail: {} });
+        return { grant: value, revoked: true };
+      },
+    },
     permissions: {
       status: () => readOverrides(config.dataRoot),
       update: ({ key, value, confirm = false } = {}) => {
@@ -397,6 +522,7 @@ export function createCortex({ config: rawConfig = {}, logger = null, llm: llmAd
       contextBudget: config.contextBudget,
       promptBudget: config.promptBudget,
       features: config.features ?? {},
+      readOnlyScopes: [...readOnlyScopes],
       overrides: readOverrides(config.dataRoot).current,
       model: redactedModelConfig(modelConfig),
       permissions: {
@@ -519,8 +645,66 @@ export function createCortex({ config: rawConfig = {}, logger = null, llm: llmAd
         summary: summarizeGraph(edgeRows),
       };
     },
+    graphCandidates: ({ scopeId = config.scope, limit = 200 } = {}) => edges.listCandidates({ scopeId, limit }),
+    graphCandidateAction: ({ action, id, scopeId = config.scope, fromId, toId, rel, weight, confidence, sourceEventId, sourceTraceId, evidence, metadata } = {}) => {
+      if (!scopeWritable(scopeId)) throw new Error('scope-read-only');
+      let result = null;
+      if (action === 'add') {
+        result = edges.addCandidate({ scopeId, fromId, toId, rel, weight, confidence, sourceEventId, sourceTraceId, evidence, metadata });
+      } else if (action === 'approve') {
+        result = edges.approveCandidate(id);
+      } else if (action === 'reject') {
+        result = edges.rejectCandidate(id);
+      } else {
+        throw new Error('graph candidate action must be add, approve or reject');
+      }
+      if (result) {
+        audit.record?.({
+          actor: 'user',
+          action: `edge.candidate.${action}`,
+          targetType: 'edge',
+          targetId: result.id,
+          detail: {
+            fromId: result.fromId,
+            toId: result.toId,
+            rel: result.rel,
+            confidence: result.metadata?.confidence ?? null,
+            sourceTraceId: result.metadata?.sourceTraceId ?? null,
+          },
+        });
+      }
+      return result;
+    },
     search,
     searchAsync,
+    ingestExtractedText: ({ targetTraceId, text, uri, mode, engine } = {}) => {
+      const target = traces.get(targetTraceId);
+      if (!target) throw new Error('target trace not found');
+      if (!scopeWritableById('trace', targetTraceId)) throw new Error('scope-read-only');
+      const content = String(text ?? '').trim().slice(0, 20000);
+      if (!content) throw new Error('extracted text is empty');
+      const result = writeInternal({
+        text: content,
+        scopeId: target.scopeId,
+        kind: 'observation',
+        explicit: true,
+        source: 'extractor',
+        metadata: {
+          derivedFrom: targetTraceId,
+          extractor: { uri: uri ?? null, mode: mode ?? null, engine: engine ?? null },
+        },
+        tags: ['extractor', mode].filter(Boolean),
+      });
+      const extractedId = result?.trace?.id ?? null;
+      audit.record?.({
+        actor: 'system',
+        action: 'attachment.extract.ingest',
+        targetType: 'trace',
+        targetId: targetTraceId,
+        detail: { extractedTraceId: extractedId, uri: uri ?? null, mode: mode ?? null, chars: content.length },
+      });
+      return { targetTraceId, extractedTraceId: extractedId, chars: content.length };
+    },
     flushLlmFacts,
     recallTiered: ({ query, limit = 20, permBudget = 700, hotBudget = 900, coldBudget = 400, scopeId = config.scope, includeArchived = false } = {}) => {
       const result = search(query, { limit, budget: permBudget + hotBudget + coldBudget, scopeId, includeArchived, noBudget: true });
@@ -536,7 +720,11 @@ export function createCortex({ config: rawConfig = {}, logger = null, llm: llmAd
     timeline,
     step: develop.step,
     feedback: (input) => growth.applyFeedback({ ...input, scopeId: input.scopeId ?? config.scope }),
-    forget: (input) => privacy.forget(input),
+    forget: (input) => {
+      const trace = traces.get(input?.traceId);
+      if (trace && !scopeWritable(trace.scopeId)) return { removed: false, reason: 'scope-read-only', traceId: input.traceId };
+      return privacy.forget(input);
+    },
     privacy,
     reflect: (options = {}) => reflect.reflect({ ...options, scopeId: options.scopeId ?? config.scope }),
     evaluateDevelopment: (options = {}) => development.evaluate({ ...options, scopeId: options.scopeId ?? config.scope }),