dsh-cortex-memory 0.2.0-rc.13 → 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

@@ -181,7 +181,7 @@ window.__ModuleLoader__.load({
         graphReject: '拒绝',
         graphCandidateConfidence: '置信',
         settingsTitle: '运行设置',
-        settingsHint: '设置与指标均为只读快照。',
+        settingsHint: '功能开关与指标为只读快照；权限修改会写入本机配置，重启后生效。',
         runtime: '运行时',
         features: '功能开关',
         permissions: '权限 / 网络',
@@ -243,7 +243,7 @@ window.__ModuleLoader__.load({
         p95: 'p95',
         max: 'max',
         metricsEmpty: '还没有指标样本。',
-        readOnlyNote: '只读：此页不会写入设置或记忆。',
+        readOnlyNote: '快照只读；权限按钮可写，需确认并重启。',
         refreshAll: '全部刷新',
         metricAt: '采样时间',
         notAvailable: '不可用',
@@ -444,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',
@@ -506,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',

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,6 +1,6 @@
 {
   "name": "dsh-cortex-memory",
-  "version": "0.2.0-rc.13",
+  "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",
@@ -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/",