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

package/README.md

@@ -91,3 +91,9 @@ auto-linked into them.
 MIT. External ideas are cited in the research notes; no third-party source
 code is copied into this package.
 
+
+## Security and privacy
+
+- [Permissions and scopes](./docs/permissions.md)
+- [Privacy notes](./docs/privacy.md)
+

package/client.js

@@ -105,6 +105,11 @@ window.__ModuleLoader__.load({
         extractTitle: '从本地提取到记忆',
         extractHint: 'OCR/ASR 结果会写成一条派生记忆，不改原 trace。',
         extractTarget: '目标记忆',
+        extractLayout: '版面',
+        layoutAuto: '自动',
+        layoutSingle: '单栏',
+        layoutTwoColumn: '双栏',
+        layoutHandwriting: '手写',
         extractRun: '提取并写入',
         extractSaved: '已写入派生记忆',
         extractSuggested: '建议：当前这条',
@@ -176,7 +181,7 @@ window.__ModuleLoader__.load({
         graphReject: '拒绝',
         graphCandidateConfidence: '置信',
         settingsTitle: '运行设置',
-        settingsHint: '设置与指标均为只读快照。',
+        settingsHint: '功能开关与指标为只读快照；权限修改会写入本机配置，重启后生效。',
         runtime: '运行时',
         features: '功能开关',
         permissions: '权限 / 网络',
@@ -238,7 +243,7 @@ window.__ModuleLoader__.load({
         p95: 'p95',
         max: 'max',
         metricsEmpty: '还没有指标样本。',
-        readOnlyNote: '只读：此页不会写入设置或记忆。',
+        readOnlyNote: '快照只读；权限按钮可写，需确认并重启。',
         refreshAll: '全部刷新',
         metricAt: '采样时间',
         notAvailable: '不可用',
@@ -363,6 +368,11 @@ window.__ModuleLoader__.load({
         extractTitle: 'Extract into memory',
         extractHint: 'OCR/ASR output is stored as a derived trace; the original trace is unchanged.',
         extractTarget: 'Target trace',
+        extractLayout: 'Layout',
+        layoutAuto: 'Auto',
+        layoutSingle: 'Single column',
+        layoutTwoColumn: 'Two columns',
+        layoutHandwriting: 'Handwriting',
         extractRun: 'Extract and write',
         extractSaved: 'Derived trace written',
         extractSuggested: 'Suggested: current trace',
@@ -434,7 +444,7 @@ window.__ModuleLoader__.load({
         graphReject: 'Reject',
         graphCandidateConfidence: 'Confidence',
         settingsTitle: 'Runtime settings',
-        settingsHint: 'Settings and metrics are read-only snapshots.',
+        settingsHint: 'Feature flags and metrics are read-only snapshots; permission changes write local config and apply after restart.',
         runtime: 'Runtime',
         features: 'Feature flags',
         permissions: 'Permissions / network',
@@ -496,7 +506,7 @@ window.__ModuleLoader__.load({
         p95: 'p95',
         max: 'max',
         metricsEmpty: 'No metric samples yet.',
-        readOnlyNote: 'Read-only: this page never writes settings or memories.',
+        readOnlyNote: 'Snapshots are read-only; permission buttons write config after confirmation and need a restart.',
         refreshAll: 'Refresh all',
         metricAt: 'Sampled at',
         notAvailable: 'Not available',
@@ -1080,6 +1090,7 @@ button.cortex-badge:disabled{cursor:not-allowed;opacity:.55}
       const [uri, setUri] = useState('');
       const [mode, setMode] = useState('ocr');
       const [language, setLanguage] = useState('');
+      const [layout, setLayout] = useState('auto');
       const [targetId, setTargetId] = useState(trace.id);
       const [candidates, setCandidates] = useState([{ id: trace.id, title: trace.title || trace.snippet || trace.id }]);
       const [busy, setBusy] = useState(false);
@@ -1110,7 +1121,7 @@ button.cortex-badge:disabled{cursor:not-allowed;opacity:.55}
         try {
           const result = await api('/attachments/extract', {
             method: 'POST',
-            body: JSON.stringify({ uri: uri.trim(), mode, language: language.trim() || undefined, traceId: targetId }),
+            body: JSON.stringify({ uri: uri.trim(), mode, language: language.trim() || undefined, layout, traceId: targetId }),
           });
           setNote(`${t('extractSaved')} ${result.extractedTraceId ?? ''}`.trim());
           setUri('');
@@ -1129,6 +1140,12 @@ button.cortex-badge:disabled{cursor:not-allowed;opacity:.55}
             h('option', { key: 'asr', value: 'asr' }, 'ASR'),
           ]),
           h('input', { className: 'cortex-input', value: language, placeholder: mode === 'ocr' ? 'zh-Hans' : 'zh', onChange: (event) => setLanguage(event.target.value) }),
+          h('select', { className: 'cortex-input', value: layout, title: t('extractLayout'), onChange: (event) => setLayout(event.target.value) }, [
+            h('option', { key: 'auto', value: 'auto' }, t('layoutAuto')),
+            h('option', { key: 'single', value: 'single' }, t('layoutSingle')),
+            h('option', { key: 'two-column', value: 'two-column' }, t('layoutTwoColumn')),
+            h('option', { key: 'handwriting', value: 'handwriting' }, t('layoutHandwriting')),
+          ]),
         ]),
         h('label', { className: 'cortex-line', style: { marginTop: 8 } }, [
           t('extractTarget'),

package/docs/permissions.md

@@ -0,0 +1,49 @@
+# Permissions and scopes
+
+Cortex is local-first. The defaults are intentionally conservative.
+
+## Local API
+
+- The API is loopback-only by default.
+- Requests carry a local token; cross-origin and unsafe POSTs are rejected.
+- `POST /permissions` requires `confirm: true`; a permission change writes a local override and takes effect after a DSH restart.
+- `POST /permissions/rollback` removes the override and also takes effect after restart.
+
+## Scopes
+
+- Every trace, fact, relation, goal and working item has a scope.
+- The global scope is writable by default; shared scopes may be read-only.
+- Scope resolution order is header, then query, then body, then the server default.
+- A write to a read-only scope is refused; it is not silently redirected.
+
+## Shared write grants
+
+- Shared write grants are for API clients that send `x-cortex-agent`.
+- A grant is a `scope:agent` pair, with an optional expiry.
+- Revoke takes effect immediately; the tool path does not send an agent header.
+- The grant list is visible in the Settings tab.
+
+## Network permissions
+
+- `llm`: allow the configured model service for QA, consolidation or extraction facts.
+- `embed`: allow remote embedding; local embeddings remain available.
+- `rerank`: allow remote reranking.
+- `vector`: enable vector indexing/search.
+- If a provider fails or a permission is off, Cortex falls back to non-vector or evidence-only paths instead of inventing data.
+
+## Feature flags
+
+Feature flags and metrics on the Settings page are a read-only snapshot. Permission buttons are the writable part; they always show a confirmation and a restart notice.
+
+## Audit and rollback
+
+- Writes, merges, forgets, permission changes and guardian operations append to the audit ledger.
+- `cortex_guard` can back up, validate, export and restore.
+- Delete is a privacy cascade; the event ledger keeps only a content hash.
+- A bad permission override can be removed with the rollback button.
+
+## What Cortex does not do
+
+- It does not read arbitrary files just because they are on disk.
+- It does not send memories to a model unless the corresponding permission and provider are configured.
+- It does not store API keys or passwords in memory.

package/docs/privacy.md

@@ -0,0 +1,48 @@
+# Privacy notes
+
+## Where data lives
+
+Default data root:
+
+```text
+~/.dsh/cortex/
+  cortex.sqlite
+  backups/
+  vector/
+```
+
+The exact paths are shown in the Settings tab. This data stays on the machine unless the user configures a remote provider or moves it.
+
+## What is stored
+
+- traces (episodic, semantic, reflective, derived)
+- facts and graph edges
+- working memory, goals, playbook rules
+- audit events
+- emotional appraisals and relationship state
+- optional derived text from local OCR/ASR, with source URI and engine metadata
+
+## What is not stored
+
+- API keys, tokens or passwords
+- raw model files
+- the contents of arbitrary local files that were not explicitly passed to an extraction tool
+- a copy of a deleted trace's body (delete cascades; the ledger keeps a content hash)
+
+## Deletion and export
+
+- `cortex_forget` archive keeps a trace recoverable; delete removes it and its derived data.
+- `cortex_guard export` writes a Markdown mirror for inspection.
+- `cortex_guard backup` creates a SQLite backup; validate a backup before restoring.
+- Attachments are metadata references; the default attachment reader is disabled.
+
+## OCR / ASR
+
+- Extraction is explicit: a `file://` URI and a configured local engine.
+- The extractor never downloads a model automatically.
+- Extracted text is written as a **derived trace**; the target trace is unchanged.
+- PaddleOCR/Tesseract/Whisper models are local files owned by the user.
+
+## Cloud / network
+
+Remote LLM, embedding and rerank calls are off unless explicitly enabled and configured. The local API is loopback-only by default. There is no automatic telemetry from Cortex itself.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-cortex-memory",
-  "version": "0.2.0-rc.11",
-  "description": "A local-first layered memory engine for DeepSeek Harness: temporal facts, hybrid retrieval, DSR forgetting, reflection, growth and controlled evolution.",
+  "version": "0.2.0",
+  "description": "A layered, temporal, self-developing memory engine for DeepSeek Harness: working, episodic, semantic, procedural and reflective memory with hybrid retrieval, DSR forgetting, reflection, consolidation, gated self-evolution and guardian.",
   "type": "module",
   "main": "./index.js",
   "icon": "./icon.svg",
@@ -31,7 +31,9 @@
     "docs/scopes.md",
     "docs/multimodal.md",
     "examples",
-    "LICENSE"
+    "LICENSE",
+    "docs/permissions.md",
+    "docs/privacy.md"
   ],
   "scripts": {
     "test": "node --test test/unit/ test/integration/",

package/src/api/routes.js

@@ -299,6 +299,9 @@ export function createApiHandler({ cortex, logger = null, getExtractor = 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' });
         }
@@ -369,6 +372,7 @@ export function createApiHandler({ cortex, logger = null, getExtractor = null }
             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 }),

package/src/tools/definitions.js

@@ -589,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 {
@@ -730,6 +731,7 @@ 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) {