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

package/src/api/routes.js

@@ -10,6 +10,13 @@ function header(request, name) {
   return Array.isArray(value) ? value[0] : value;
 }
 
+function agentOf(request) {
+  const value = header(request, 'x-cortex-agent');
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return /^[A-Za-z0-9._:-]{1,120}$/.test(trimmed) ? trimmed : null;
+}
+
 function isLoopback(value) {
   const address = String(value ?? '').toLowerCase().replace(/^\[|\]$/g, '');
   if (address === 'localhost' || address === 'localhost.') return true;
@@ -69,6 +76,8 @@ function sendJson(response, status, value) {
 }
 
 function toInt(value, fallback, min, max) {
+  // Number(null) is 0, which would silently turn an omitted ?limit into min.
+  if (value == null || value === '') return fallback;
   const n = Number(value);
   return Number.isFinite(n) ? Math.max(min, Math.min(max, Math.trunc(n))) : fallback;
 }
@@ -79,7 +88,7 @@ function scopeOf(request, url, body = null) {
   return value && value.length <= 120 && /^[A-Za-z0-9._:-]+$/.test(value) ? value : 'global';
 }
 
-export function createApiHandler({ cortex, logger = null } = {}) {
+export function createApiHandler({ cortex, logger = null, getExtractor = null } = {}) {
   if (!cortex) throw new Error('api handler needs cortex');
 
   async function handler(request, response) {
@@ -108,6 +117,7 @@ export function createApiHandler({ cortex, logger = null } = {}) {
         if (route === '/skills') return sendJson(response, 200, { ok: true, data: cortex.engines.skills.list({ scopeId: scopeOf(request, url), limit: 100 }) });
         if (route === '/models') return sendJson(response, 200, { ok: true, data: cortex.models.get() });
         if (route === '/permissions') return sendJson(response, 200, { ok: true, data: cortex.permissions.status() });
+        if (route === '/security/grants') return sendJson(response, 200, { ok: true, data: cortex.security.grants() });
         if (route === '/settings') return sendJson(response, 200, { ok: true, data: cortex.settings() });
         if (route === '/report') return sendJson(response, 200, { ok: true, data: cortex.report(scopeOf(request, url)) });
         if (route === '/metrics') return sendJson(response, 200, { ok: true, data: cortex.metrics() });
@@ -115,6 +125,7 @@ export function createApiHandler({ cortex, logger = null } = {}) {
         if (route === '/digest') return sendJson(response, 200, { ok: true, data: cortex.digest.daily({ date: url.searchParams.get('date') ?? undefined }) });        if (route === '/audit') return sendJson(response, 200, { ok: true, data: cortex.repos.audit.list({ limit: toInt(url.searchParams.get('limit'), 50, 1, 200) }) });
         if (route === '/graph') return sendJson(response, 200, { ok: true, data: cortex.graphSummary({ scopeId: scopeOf(request, url) }) });
         if (route === '/graph/edges') return sendJson(response, 200, { ok: true, data: cortex.graphData({ scopeId: scopeOf(request, url) }) });
+        if (route === '/graph/candidates') return sendJson(response, 200, { ok: true, data: cortex.graphCandidates({ scopeId: scopeOf(request, url), limit: toInt(url.searchParams.get('limit'), 200, 1, 2000) }) });
         if (route === '/search') {
           const query = url.searchParams.get('q') ?? '';
           const tiered = url.searchParams.get('tiered') === 'true';
@@ -206,6 +217,40 @@ export function createApiHandler({ cortex, logger = null } = {}) {
       return;
     }
     try {
+      const scopedWriteRoutes = new Set([
+        '/write',
+        '/working/add',
+        '/working/purge',
+        '/goals/add',
+        '/graph/candidates/action',
+        '/retention/apply',
+        '/consolidate',
+        '/vector/rebuild',
+        '/emotion/record',
+        '/compress',
+        '/life/diary',
+        '/life/dream',
+        '/life/sleep',
+      ]);
+      if (scopedWriteRoutes.has(route)) {
+        const writeScope = scopeOf(request, url, body);
+        if (!cortex.scopeWritable(writeScope, agentOf(request))) {
+          return sendJson(response, 403, { ok: false, error: 'scope-read-only', scopeId: writeScope });
+        }
+      }
+      const byIdWriteRoutes = {
+        '/working/update': 'working',
+        '/working/remove': 'working',
+        '/goals/update': 'goal',
+        '/goals/complete': 'goal',
+      };
+      if (byIdWriteRoutes[route]) {
+        const kind = byIdWriteRoutes[route];
+        const id = requireString(body.id, 'id', { max: 200 });
+        if (!cortex.scopeWritableById(kind, id, agentOf(request))) {
+          return sendJson(response, 403, { ok: false, error: 'scope-read-only' });
+        }
+      }
       if (route === '/search') {
         const input = validateSearch(body);
         const useAsync = body.async === true || body.tiered === true && cortex.vector?.status?.().async === true || cortex.vector?.status?.().async === true;
@@ -218,7 +263,30 @@ export function createApiHandler({ cortex, logger = null } = {}) {
         if (useAsync) return sendJson(response, 200, { ok: true, data: await cortex.searchAsync(input.query, { limit: input.limit ?? 10, budget: input.budget ?? 2200, scopeId: scopeOf(request, url, body) }) });
         return sendJson(response, 200, { ok: true, data: cortex.search(input.query, { limit: input.limit ?? 10, budget: input.budget ?? 2200, scopeId: scopeOf(request, url, body) }) });
       }
+      if (route === '/graph/candidates/action') {
+        const action = requireString(body.action, 'action', { max: 20 });
+        const result = cortex.graphCandidateAction({
+          action,
+          id: body.id ? requireString(body.id, 'id', { max: 200 }) : undefined,
+          scopeId: scopeOf(request, url, body),
+          fromId: body.fromId ? requireString(body.fromId, 'fromId', { max: 200 }) : undefined,
+          toId: body.toId ? requireString(body.toId, 'toId', { max: 200 }) : undefined,
+          rel: body.rel ? requireString(body.rel, 'rel', { max: 100 }) : undefined,
+          weight: body.weight,
+          confidence: body.confidence,
+          sourceEventId: body.sourceEventId ? requireString(body.sourceEventId, 'sourceEventId', { max: 200 }) : null,
+          sourceTraceId: body.sourceTraceId ? requireString(body.sourceTraceId, 'sourceTraceId', { max: 200 }) : null,
+          evidence: body.evidence ?? null,
+          metadata: body.metadata && typeof body.metadata === 'object' ? body.metadata : {},
+        });
+        if (!result) return sendJson(response, 404, { ok: false, error: 'candidate not found or not pending' });
+        return sendJson(response, 200, { ok: true, data: result });
+      }
       if (route === '/write') {
+        const writeScope = scopeOf(request, url, body);
+        if (!cortex.scopeWritable(writeScope, agentOf(request))) {
+          return sendJson(response, 403, { ok: false, error: 'scope-read-only', scopeId: writeScope });
+        }
         if (Array.isArray(body.items)) {
           return sendJson(response, 200, { ok: true, data: cortex.writeMany(body.items.map((item) => ({ ...validateWrite(item), scopeId: scopeOf(request, url, item) }))) });
         }
@@ -231,6 +299,12 @@ export function createApiHandler({ cortex, logger = null } = {}) {
       }
       if (route === '/forget') {
         const input = validateForget(body);
+        if (!input.id || typeof input.id !== 'string' || !input.id.trim()) {
+          return sendJson(response, 400, { ok: false, error: 'traceId is required' });
+        }
+        if (!cortex.scopeWritableById('trace', input.id, agentOf(request))) {
+          return sendJson(response, 403, { ok: false, error: 'scope-read-only' });
+        }
         return sendJson(response, 200, { ok: true, data: cortex.forget({ traceId: input.id, mode: input.mode }) });
       }
       if (route === '/reflect') {
@@ -256,7 +330,12 @@ export function createApiHandler({ cortex, logger = null } = {}) {
         return sendJson(response, 200, { ok: true, data: cortex.exportMarkdown(requireString(body.dir, 'dir', { max: 4000 })) });
       }
       if (route === '/guard/sync') {
-        return sendJson(response, 200, { ok: true, data: cortex.syncMarkdown(requireString(body.dir, 'dir', { max: 4000 }), { dryRun: body.dryRun === true, scopeId: scopeOf(request, url, body) }) });
+        const dir = requireString(body.dir, 'dir', { max: 4000 });
+        const dryRun = body.dryRun === true;
+        if (!dryRun && !cortex.scopeWritable(scopeOf(request, url, body), agentOf(request))) {
+          return sendJson(response, 403, { ok: false, error: 'scope-read-only' });
+        }
+        return sendJson(response, 200, { ok: true, data: cortex.syncMarkdown(dir, { dryRun, scopeId: scopeOf(request, url, body) }) });
       }
       if (route === '/qa') {
         const question = requireString(body.question, 'question', { max: 2000 });
@@ -264,6 +343,15 @@ export function createApiHandler({ cortex, logger = null } = {}) {
       }
       if (route === '/playbook') {
         const action = String(body.action ?? 'add');
+        if (['vote', 'retire', 'approve'].includes(action)) {
+          const id = requireString(body.id, 'id', { max: 200 });
+          if (!cortex.scopeWritableById('playbook', id, agentOf(request))) {
+            return sendJson(response, 403, { ok: false, error: 'scope-read-only' });
+          }
+        }
+        if (['add', 'suggest'].includes(action) && !cortex.scopeWritable(scopeOf(request, url, body), agentOf(request))) {
+          return sendJson(response, 403, { ok: false, error: 'scope-read-only' });
+        }
         if (action === 'add') {
           return sendJson(response, 200, { ok: true, data: cortex.playbook.add({ title: requireString(body.title, 'title', { max: 200 }), body: requireString(body.body, 'body', { max: 4000 }), tags: Array.isArray(body.tags) ? body.tags.map(String).slice(0, 20) : [], validTo: body.validTo ? requireString(body.validTo, 'validTo', { max: 40 }) : null, scopeId: scopeOf(request, url, body) }) });
         }
@@ -274,12 +362,68 @@ export function createApiHandler({ cortex, logger = null } = {}) {
         if (action === 'render') return sendJson(response, 200, { ok: true, data: cortex.playbook.render({ scopeId: scopeOf(request, url, body) }) });
         throw new Error('playbook action must be add, vote, retire, suggest, approve or render');
       }
+      if (route === '/attachments/extract') {
+        const extractor = typeof getExtractor === 'function' ? getExtractor() : null;
+        if (!extractor || typeof extractor.extract !== 'function') {
+          return sendJson(response, 503, { ok: false, error: 'extractor-unavailable' });
+        }
+        try {
+          const extracted = await extractor.extract({
+            uri: requireString(body.uri, 'uri', { max: 2000 }),
+            mode: requireString(body.mode, 'mode', { max: 16 }),
+            language: body.language ? requireString(body.language, 'language', { max: 32 }) : undefined,
+            layout: body.layout ? requireString(body.layout, 'layout', { max: 16 }) : undefined,
+          });
+          const ingested = cortex.ingestExtractedText({
+            targetTraceId: requireString(body.traceId, 'traceId', { max: 200 }),
+            text: extracted.text,
+            uri: extracted.uri,
+            mode: extracted.mode,
+            engine: extracted.engine ?? null,
+          });
+          return sendJson(response, 200, { ok: true, data: { ...extracted, ...ingested } });
+        } catch (error) {
+          return sendJson(response, 400, { ok: false, error: error instanceof Error ? error.message : String(error) });
+        }
+      }
+      if (route === '/trace/attachments') {
+        try {
+          const result = cortex.attachments.attach({
+            traceId: requireString(body.id, 'id', { max: 200 }),
+            attachments: body.attachments,
+          });
+          return sendJson(response, 200, { ok: true, data: result });
+        } catch (error) {
+          return sendJson(response, 400, { ok: false, error: error instanceof Error ? error.message : String(error) });
+        }
+      }
+      if (route === '/attachments/inspect') {
+        if (cortex.settings().features?.attachmentReader !== true) {
+          return sendJson(response, 403, { ok: false, error: 'attachment-reader-disabled' });
+        }
+        try {
+          const result = cortex.attachments.inspect({ uri: requireString(body.uri, 'uri', { max: 2000 }) });
+          return sendJson(response, 200, { ok: true, data: result });
+        } catch (error) {
+          return sendJson(response, 400, { ok: false, error: error instanceof Error ? error.message : String(error) });
+        }
+      }
       if (route === '/models') {
         return sendJson(response, 200, { ok: true, data: cortex.models.save({ embedding: body.embedding ?? {}, rerank: body.rerank ?? {}, confirm: body.confirm === true }) });
       }
       if (route === '/permissions') {
         return sendJson(response, 200, { ok: true, data: cortex.permissions.update({ key: requireString(body.key, 'key', { max: 80 }), value: body.value === true, confirm: body.confirm === true }) });
       }
+      if (route === '/security/grants') {
+        const action = requireString(body.action, 'action', { max: 20 });
+        if (action === 'add') {
+          return sendJson(response, 200, { ok: true, data: cortex.security.addGrant({ grant: requireString(body.grant, 'grant', { max: 200 }), until: body.until ?? null }) });
+        }
+        if (action === 'revoke') {
+          return sendJson(response, 200, { ok: true, data: cortex.security.revokeGrant({ grant: requireString(body.grant, 'grant', { max: 200 }) }) });
+        }
+        return sendJson(response, 400, { ok: false, error: 'grant action must be add or revoke' });
+      }
       if (route === '/permissions/rollback') {
         return sendJson(response, 200, { ok: true, data: cortex.permissions.rollback() });
       }
@@ -361,8 +505,8 @@ export function createApiHandler({ cortex, logger = null } = {}) {
   return handler;
 }
 
-export function mountApi(ctx, { cortex, logger = null } = {}) {
-  const handler = createApiHandler({ cortex, logger });
+export function mountApi(ctx, { cortex, logger = null, getExtractor = null } = {}) {
+  const handler = createApiHandler({ cortex, logger, getExtractor });
   const mount = (server) => {
     if (!server || typeof server.register !== 'function') return () => {};
     try {

package/src/api/validate.js

@@ -1,4 +1,5 @@
 import { CortexError, ERROR_CODES } from '../core/errors.js';
+import { normalizeAttachments } from '../core/attachments.js';
 
 function fail(message) {
   throw new CortexError(ERROR_CODES.INVALID_INPUT, message);
@@ -32,6 +33,29 @@ export function optionalStringArray(value, name, { max = 50 } = {}) {
   return value.map((item) => item.trim()).filter(Boolean);
 }
 
+function optionalFacts(value) {
+  if (value == null) return undefined;
+  if (!Array.isArray(value) || value.length > 50) fail('facts must be an array of at most 50 items');
+  return value.map((item, index) => {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) fail(`facts[${index}] must be an object`);
+    return {
+      subject: requireString(item.subject, `facts[${index}].subject`, { max: 200 }),
+      predicate: requireString(item.predicate, `facts[${index}].predicate`, { max: 200 }),
+      object: requireString(item.object, `facts[${index}].object`, { optional: true, max: 200 }),
+      objectLiteral: requireString(item.objectLiteral, `facts[${index}].objectLiteral`, { optional: true, max: 2000 }),
+      confidence: optionalNumber(item.confidence, `facts[${index}].confidence`, { min: 0, max: 1 }),
+    };
+  });
+}
+
+function optionalAttachments(value) {
+  try {
+    return normalizeAttachments(value);
+  } catch (error) {
+    return fail(error.message);
+  }
+}
+
 export function validateWrite(body) {
   return {
     text: requireString(body.text, 'text'),
@@ -41,6 +65,8 @@ export function validateWrite(body) {
     importance: optionalNumber(body.importance, 'importance', { min: 0, max: 1 }),
     explicit: optionalBoolean(body.explicit, 'explicit'),
     operationId: requireString(body.operationId, 'operationId', { optional: true, max: 200 }),
+    facts: optionalFacts(body.facts),
+    attachments: optionalAttachments(body.attachments),
   };
 }
 

package/src/core/attachment-reader.js

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+export const ATTACHMENT_READ_LIMIT = 50 * 1024 * 1024;
+
+export function inspectLocalAttachment(uri, { maxBytes = ATTACHMENT_READ_LIMIT } = {}) {
+  const text = String(uri ?? '').trim();
+  if (!text) throw new Error('attachment uri is required');
+  let url;
+  try {
+    url = new URL(text);
+  } catch {
+    throw new Error('attachment uri must be a file:// URL');
+  }
+  if (url.protocol !== 'file:') throw new Error('only file:// attachments can be inspected');
+  const file = fileURLToPath(url);
+  const stat = fs.statSync(file);
+  if (!stat.isFile()) throw new Error('attachment is not a regular file');
+  if (stat.size > maxBytes) throw new Error(`attachment is larger than ${maxBytes} bytes`);
+  const sha256 = crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+  return {
+    kind: 'file',
+    uri: text,
+    name: path.basename(file),
+    bytes: stat.size,
+    mtime: stat.mtime.toISOString(),
+    sha256,
+  };
+}

package/src/core/attachments.js

@@ -0,0 +1,39 @@
+const KINDS = new Set(['image', 'audio', 'video', 'file']);
+const HEX = /^[a-f0-9]{64}$/i;
+
+function clean(value, max) {
+  return String(value ?? '').trim().slice(0, max);
+}
+
+/**
+ * Reference-only multimodal metadata. No bytes are fetched, decoded or stored;
+ * callers remain responsible for the URI and for any model-side use.
+ */
+export function normalizeAttachments(value) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) throw new Error('attachments must be an array');
+  if (value.length > 8) throw new Error('at most 8 attachments');
+  return value.map((item, index) => {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) throw new Error(`attachments[${index}] must be an object`);
+    const kind = clean(item.kind ?? 'file', 20).toLowerCase();
+    if (!KINDS.has(kind)) throw new Error(`attachments[${index}].kind must be image/audio/video/file`);
+    const uri = clean(item.uri, 2000);
+    if (!uri) throw new Error(`attachments[${index}].uri is required`);
+    const out = { kind, uri };
+    const name = clean(item.name, 200);
+    const mime = clean(item.mime, 100);
+    const sha256 = clean(item.sha256, 64);
+    if (name) out.name = name;
+    if (mime) out.mime = mime;
+    if (item.bytes != null) {
+      const bytes = Number(item.bytes);
+      if (!Number.isInteger(bytes) || bytes < 0 || bytes > 1_000_000_000) throw new Error(`attachments[${index}].bytes must be 0..1e9`);
+      out.bytes = bytes;
+    }
+    if (sha256) {
+      if (!HEX.test(sha256)) throw new Error(`attachments[${index}].sha256 must be 64 hex chars`);
+      out.sha256 = sha256.toLowerCase();
+    }
+    return out;
+  });
+}

package/src/core/config.js

@@ -1,6 +1,7 @@
 import os from 'node:os';
 import path from 'node:path';
 import { clamp } from './time.js';
+import { profileDataRoot } from './profile.js';
 
 const DSH_HOME = process.env.DSH_HOME || path.join(os.homedir(), '.dsh');
 const DEFAULT_ROOT = process.env.CORTEX_HOME || path.join(DSH_HOME, 'cortex');
@@ -10,11 +11,17 @@ export const DEFAULT_CONFIG = Object.freeze({
   dbFile: path.join(DEFAULT_ROOT, 'cortex.sqlite'),
   scope: 'global',
   contextBudget: 2200,
+  readOnlyScopes: Object.freeze([]),
+  scopeWriteGrants: Object.freeze([]),
   identityBudget: 360,
   workingBudget: 800,
   recallTimeoutMs: 1200,
   ftsLimit: 40,
   vectorEnabled: false,
+  vectorAnnMin: 20000,
+  vectorAnnEngine: 'hnsw',
+  vectorAnnEndpoint: '',
+  vectorAnnTimeoutMs: 800,
   llmEnabled: false,
   asyncJobs: true,
   dsr: Object.freeze({
@@ -37,6 +44,9 @@ export const DEFAULT_CONFIG = Object.freeze({
     reflect: true,
     growth: true,
     vector: false,
+    vectorAnn: false,
+    vectorAnnExternal: false,
+    attachmentReader: false,
     graph: true,
     llm: false,
   }),
@@ -56,7 +66,7 @@ function textPath(value, fallback, base = null) {
 
 export function normalizeConfig(raw = {}) {
   const input = raw && typeof raw === 'object' ? raw : {};
-  const dataRoot = textPath(input.dataRoot, DEFAULT_CONFIG.dataRoot);
+  const dataRoot = textPath(input.dataRoot, process.env.CORTEX_HOME || profileDataRoot());
   const dbFile = textPath(input.dbFile, path.join(dataRoot, 'cortex.sqlite'), dataRoot);
   const dsrInput = input.dsr && typeof input.dsr === 'object' ? input.dsr : {};
   const compressionInput = input.compression && typeof input.compression === 'object' ? input.compression : {};
@@ -69,6 +79,31 @@ export function normalizeConfig(raw = {}) {
     dataRoot,
     dbFile,
     scope,
+    readOnlyScopes: Object.freeze(Array.isArray(input.readOnlyScopes)
+      ? [...new Set(input.readOnlyScopes.filter((value) => typeof value === 'string' && value.trim()).map((value) => value.trim()).slice(0, 100))]
+      : []),
+    scopeWriteGrants: Object.freeze((() => {
+      if (!Array.isArray(input.scopeWriteGrants)) return [];
+      const out = [];
+      const seen = new Set();
+      for (const raw of input.scopeWriteGrants) {
+        if (typeof raw === 'string' && /^[^:\s]+:\S+$/.test(raw.trim())) {
+          const grant = raw.trim();
+          const key = `${grant}\u0000`;
+          if (!seen.has(key)) { seen.add(key); out.push(Object.freeze({ grant, until: null })); }
+          continue;
+        }
+        if (raw && typeof raw === 'object' && typeof raw.grant === 'string' && /^[^:\s]+:\S+$/.test(raw.grant.trim())) {
+          const grant = raw.grant.trim();
+          const until = raw.until == null ? null : String(raw.until).trim();
+          if (until && !Number.isFinite(Date.parse(until))) continue;
+          const key = `${grant}\u0000${until ?? ''}`;
+          if (!seen.has(key)) { seen.add(key); out.push(Object.freeze({ grant, until: until || null })); }
+        }
+        if (out.length >= 200) break;
+      }
+      return out;
+    })()),
     contextBudget: numeric(input.contextBudget, DEFAULT_CONFIG.contextBudget, 256, 20000),
     identityBudget: numeric(input.identityBudget, DEFAULT_CONFIG.identityBudget, 64, 4000),
     workingBudget: numeric(input.workingBudget, DEFAULT_CONFIG.workingBudget, 128, 8000),

package/src/core/model-config.js

@@ -43,7 +43,9 @@ function clean(value) {
 
 export function readModelConfig(dataRoot) {
   try {
-    const parsed = JSON.parse(fs.readFileSync(modelConfigPath(dataRoot), 'utf8'));
+    // Windows PowerShell's `Set-Content -Encoding utf8` writes a BOM.
+    // JSON.parse rejects it, which would silently downgrade to hash embeddings.
+    const parsed = JSON.parse(fs.readFileSync(modelConfigPath(dataRoot), 'utf8').replace(/^\uFEFF/, ''));
     return normalizeModelConfig(parsed);
   } catch {
     return normalizeModelConfig({});

package/src/core/profile.js

@@ -0,0 +1,32 @@
+import os from 'node:os';
+import path from 'node:path';
+
+function homeFromEnv(env) {
+  return env.DSH_HOME || path.join(os.homedir(), '.dsh');
+}
+
+export function detectProfileName({ argv = process.argv, env = process.env } = {}) {
+  // Explicit CLI/profile-path args outrank an inherited DSH_PROFILE from the
+  // desktop app; otherwise `dsh --profile clean` would still read desktop data.
+  const args = Array.isArray(argv) ? argv.map(String) : [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--profile' && args[index + 1]) return path.basename(args[index + 1].replace(/[\\/]+$/, ''));
+    if (arg.startsWith('--profile=')) return path.basename(arg.slice('--profile='.length).replace(/[\\/]+$/, ''));
+  }
+  for (const arg of args) {
+    const match = arg.match(/[\\/]profiles[\\/]([^\\/]+)[\\/]?$/);
+    if (match) return match[1];
+  }
+  const fromEnv = String(env.DSH_PROFILE ?? '').trim();
+  if (fromEnv) return fromEnv;
+  return null;
+}
+
+export function profileDataRoot({ argv = process.argv, env = process.env } = {}) {
+  const profile = detectProfileName({ argv, env });
+  const home = homeFromEnv(env);
+  // desktop is the historical default; never silently point it at an empty DB.
+  if (!profile || profile === 'desktop') return path.join(home, 'cortex');
+  return path.join(home, 'cortex', 'profiles', profile);
+}

package/src/engines/develop.js

@@ -40,7 +40,7 @@ export function createDevelopEngine({
     goals = [],
     identity = '',
     relationship = null,
-    relationshipTarget = '用户',
+    relationshipTarget = '主人',
     recentTexts = [],
     explicit = false,
     facts: factInput = [],

package/src/engines/encode.js

@@ -59,6 +59,7 @@ export function createEncodeEngine({
   traces,
   entities = null,
   facts = null,
+  edges = null,
   audit = null,
   vector = null,
   config = {},
@@ -67,6 +68,60 @@ export function createEncodeEngine({
   const minChars = config.minContentChars ?? 2;
   const minCompression = config.minCompressionValue ?? 0.08;
 
+  function applyFacts(rawFacts, { scopeId, recordedAt, sourceEventId }) {
+    const resolved = [];
+    if (!Array.isArray(rawFacts) || !entities || !facts) return resolved;
+    for (const raw of rawFacts) {
+      if (!raw || !raw.subject || !raw.predicate) continue;
+      const subject = entities.upsert({ scopeId, name: raw.subject, type: raw.subjectType || 'concept' });
+      let objectId = null;
+      const objectLiteral = raw.objectLiteral ?? null;
+      if (raw.object && !raw.objectLiteral) {
+        const object = entities.upsert({ scopeId, name: raw.object, type: raw.objectType || 'concept' });
+        objectId = object.id;
+      }
+      const resolution = facts.resolve({
+        scopeId,
+        subjectId: subject.id,
+        predicate: raw.predicate,
+        objectId,
+        objectLiteral,
+        validFrom: raw.validFrom || recordedAt,
+        validTo: raw.validTo || null,
+        recordedAt,
+        confidence: raw.confidence ?? 0.7,
+        sourceEventId,
+      });
+      resolved.push(resolution);
+    }
+    return resolved;
+  }
+
+  function queueFactEdges(resolvedFacts, { scopeId, sourceEventId, sourceTraceId }) {
+    if (!edges || !Array.isArray(resolvedFacts) || resolvedFacts.length === 0) return [];
+    const queued = [];
+    for (const resolution of resolvedFacts) {
+      const fact = resolution?.fact;
+      if (!fact?.subjectId || !fact?.objectId || fact.status !== 'active') continue;
+      try {
+        queued.push(edges.addCandidate({
+          scopeId,
+          fromId: fact.subjectId,
+          toId: fact.objectId,
+          rel: fact.predicate,
+          weight: fact.confidence ?? 0.5,
+          confidence: fact.confidence ?? 0.5,
+          sourceEventId,
+          sourceTraceId,
+          evidence: { factId: fact.id ?? null, validFrom: fact.validFrom ?? null },
+        }));
+      } catch {
+        /* a bad candidate should not fail the write */
+      }
+    }
+    return queued;
+  }
+
   function encode(input = {}) {
     const original = String(input.text ?? input.content ?? '').trim();
     const scanned = scanText(original);
@@ -101,18 +156,24 @@ export function createEncodeEngine({
     });
 
     const existing = traces.findByEvent(event.id);
-    if (existing) return { skipped: true, reason: 'idempotent', event, trace: existing };
+    if (existing) {
+      const factsApplied = applyFacts(input.facts, { scopeId, recordedAt, sourceEventId: event.id });
+      const edgeCandidates = queueFactEdges(factsApplied, { scopeId, sourceEventId: event.id, sourceTraceId: existing.id });
+      return { skipped: true, reason: 'idempotent', event, trace: existing, facts: factsApplied, edgeCandidates };
+    }
 
     const duplicate = traces.findByHash(scopeId, hashText(text));
     if (duplicate) {
+      const factsApplied = applyFacts(input.facts, { scopeId, recordedAt, sourceEventId: event.id });
+      const edgeCandidates = queueFactEdges(factsApplied, { scopeId, sourceEventId: event.id, sourceTraceId: duplicate.id });
       audit?.record?.({
         actor: input.actor || 'user',
         action: 'trace.duplicate',
         targetType: 'trace',
         targetId: duplicate.id,
-        detail: { eventId: event.id, textHash: hashText(text) },
+        detail: { eventId: event.id, textHash: hashText(text), factsApplied: factsApplied.length, edgeCandidates: edgeCandidates.length },
       });
-      return { skipped: true, reason: 'duplicate', event, trace: duplicate };
+      return { skipped: true, reason: 'duplicate', event, trace: duplicate, facts: factsApplied, edgeCandidates };
     }
 
     const trace = traces.insert({
@@ -123,6 +184,7 @@ export function createEncodeEngine({
       summary: input.summary || null,
       keywords: input.keywords || [],
       tags: input.tags || [],
+      metadata: input.metadata && typeof input.metadata === 'object' ? input.metadata : {},
       eventId: event.id,
       sessionId: input.sessionId || null,
       turnId: input.turnId || null,
@@ -138,32 +200,8 @@ export function createEncodeEngine({
       sensitivity: sensitivity,
     });
 
-    const resolvedFacts = [];
-    if (Array.isArray(input.facts) && entities && facts) {
-      for (const raw of input.facts) {
-        if (!raw || !raw.subject || !raw.predicate) continue;
-        const subject = entities.upsert({ scopeId, name: raw.subject, type: raw.subjectType || 'concept' });
-        let objectId = null;
-        let objectLiteral = raw.objectLiteral ?? null;
-        if (raw.object && !raw.objectLiteral) {
-          const object = entities.upsert({ scopeId, name: raw.object, type: raw.objectType || 'concept' });
-          objectId = object.id;
-        }
-        const resolution = facts.resolve({
-          scopeId,
-          subjectId: subject.id,
-          predicate: raw.predicate,
-          objectId,
-          objectLiteral,
-          validFrom: raw.validFrom || recordedAt,
-          validTo: raw.validTo || null,
-          recordedAt,
-          confidence: raw.confidence ?? 0.7,
-          sourceEventId: event.id,
-        });
-        resolvedFacts.push(resolution);
-      }
-    }
+    const resolvedFacts = applyFacts(input.facts, { scopeId, recordedAt, sourceEventId: event.id });
+    const edgeCandidates = queueFactEdges(resolvedFacts, { scopeId, sourceEventId: event.id, sourceTraceId: trace.id });
 
     audit?.record?.({
       actor: input.actor || 'user',
@@ -192,7 +230,7 @@ export function createEncodeEngine({
       }
     }
 
-    return { skipped: false, event, trace, facts: resolvedFacts, compression, score: scored };
+    return { skipped: false, event, trace, facts: resolvedFacts, edgeCandidates, compression, score: scored };
   }
 
   return { encode, scoreTraceText, compressionValue };