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

package/README.md

@@ -1,93 +1,120 @@
-# dsh-cortex
-
-> 鏈哺鐨勬柊澶ц剳銆傚垎灞傘€佹椂搴忋€佸彲鑷垜宸╁浐鐨勮蹇嗗紩鎿庛€?> 鐘舵€侊細**鍙墦鍖呫€佸彲瀹夎**锛涙湰鏈哄紑鍙戝壇鏈粛鏈畨瑁咃紝涔熸病鏈夋帴 profile銆?> Windows 鐩存帴瀹夎/鍥炴粴瑙?[docs/install-windows.md](docs/install-windows.md)銆?
-`dsh-cortex` is a local-first memory engine for DeepSeek Harness. It is designed
-as a successor to the `dsh-shiori` + `dsh-shiori-companion` pair, not a patch on
-top of them.
-
-## Why another memory plugin
-
-The shiori stack is good at four things: a stable persona, a compact core,
-triggered spark cards and on-demand topics. It is weaker at temporal facts,
-episodic provenance, procedural learning, consolidation and calibrated
-forgetting. `dsh-cortex` keeps the good parts and adds the missing layers:
-
-| Layer | What it holds | Lifetime |
-|---|---|---|
-| L0 identity | self-model, values, boundaries, stable traits | long, explicit promotion |
-| L1 working | current goals, focus, pinned context, recent turn buffer | minutes鈥揾ours |
-| L2 episodic | what happened, when, with whom, provenance, emotion | days鈥搚ears |
-| L3 semantic | entities, facts with validity windows, preferences | until invalidated |
-| L4 procedural | skills, workflows, preconditions, success/failure stats | until superseded |
-| L5 reflective | episode summaries, insights, narratives | derived, regenerable |
-| archive | cold but searchable, wake-word recall | until privacy deletion |
-
-## Engines
-
-- **event log** 鈥?append-only, hash-chained, `event_id` / `operation_id`; the
-  only source of truth.
-- **write pipeline** 鈥?scan secrets/injection 鈫?classify 鈫?dedupe 鈫?  conflict-resolve 鈫?link 鈫?persist; async jobs with idempotent operation IDs.
-- **temporal graph** 鈥?entities, facts and edges with `valid_from` /
-  `valid_to`; old facts are invalidated, never silently overwritten.
-- **hybrid retrieval** 鈥?FTS5 BM25 + optional vector + graph activation +
-  recency / importance / feedback, fused with RRF, diversified with a greedy
-  MMR-style marginal-gain pass; query filters (`kind:`, `tag:`, `after:`,
-  `importance:>`, 鈥?.
-- **DSR forgetting** 鈥?FSRS-inspired stability / difficulty / retrievability;
-  archive instead of delete, revive on successful recall.
-- **compression / retention** 鈥?archive only when a derived model covers the
-  trace, or when a reviewed retention plan says it is old/low-value; important
-  memories are never auto-archived.
-- **reflection** 鈥?episode segmentation, summaries, narrative threads,
-  duplicate/contradiction detection, optional LLM dream/summary.
-- **self model** 鈥?drives, mood, attention, appraisal, relationships,
-  initiatives, 24-category emotion/affect, identity versions.
-- **development** 鈥?maturity/stage from memory depth, feedback, calibration,
-  skills, narrative and relationships.
-- **evolution** 鈥?policy proposals 鈫?replay evaluation 鈫?explicit approval 鈫?  rollback; identity changes are separate and approval-only.
-- **guardian** 鈥?invariants, circuit breaker, budget, backup/validate/offline
-  restore, FTS repair, privacy cascade, secret/injection scanner.
-- **host runtime** 鈥?`session/event` turn capture + `user/message` /
-  `agent/pre-step` recall prefetch into the systemPrompt section.
-- **API/UI/CLI** 鈥?loopback-only HTTP API, sidebar panel, `bin/cortex.mjs`.
+# DSH Cortex
+
+A local-first, layered memory engine for DeepSeek Harness.
+
+Cortex gives an agent working memory, episodic traces, temporal facts, procedural
+skills and reflective summaries, with calibrated forgetting instead of a flat
+chat transcript. It runs locally on SQLite and has no native dependency in the
+core engine.
 
 ## Status
 
-This is a source-only development tree. `npm test` uses `node:test` and the
-built-in `node:sqlite`; no native dependency and no network are required for
-the core suite. Profiles install a built tgz explicitly; this tree is not
-auto-linked into them.
-
-- **395** tests passing (unit + integration).
-- 21 model-facing tools.
-- **`cortex_as_of`**锛歴trict / historical / belief / associative銆?- **`cortex_playbook`**锛歀1.5 宸ヤ綔鍑嗗垯锛屽甫 helpful/harmful銆乿alidTo銆佽繃鏈熶笉娉ㄥ叆銆?- **`cortex_consolidate`**锛歀LM 鍐崇瓥娓呭崟 + 鏍￠獙 + `dream_runs` 鍙洖鏀捐褰曪紱鏃?LLM 鏃惰褰?skipped 骞堕浂鏀瑰姩銆?- **`cortex_search({tiered:true})`**锛歱erm/hot/cold 鍒嗗眰棰勭畻锛宑old 鍙粰绱㈠紩銆?- **寮傛娣峰悎妫€绱?*锛歚GET /search?async=true` / QA 璧?`searchAsync`锛涜繙绋?embedder 鍙储寮曪紝涓嶉樆濉炲啓銆?- 5k synthetic benchmark (needle, vector off): ~2.6-2.8k writes/s, p50 ~20-35ms; 100k migration ~2.3s. These are local numbers, not an official score.
-- Source/tests/docs 鈮?33k lines (includes `docs/book/`); source-only, not installed here.
-- Windows tgz: `dist/dsh-cortex-0.2.0-rc.11.tgz` (zero runtime deps; Node >= 24).
-
-## Design docs
-
-- [research notes](docs/research/README.md)
-- [architecture](docs/architecture.md)
-- [Anima: from memory engine to a growing individual](docs/anima.md)
-- [modules and invariants](docs/modules.md)
-- [operations / CLI / backup](docs/operations.md)
-- [security and privacy](docs/security.md)
-- [scope isolation and read-only sharing](docs/scopes.md)
-- [multimodal attachment metadata](docs/multimodal.md)
-- [benchmark](docs/benchmark.md)
-- [OpenAPI 3.1](docs/openapi.yaml)
-- [API client](src/api/client.js)
-- [UI guide](docs/ui.md)
-- [design book](docs/book/README.md)
-- [four-plugin comparison](docs/comparison-2026-11-11.md)
-- [Windows install and rollback](docs/install-windows.md)
-- [optional models](docs/models.md)
-- [shiori companion review](docs/companion-feature-review.md)
-- [ecosystem comparison 2026-11-11](docs/ecosystem-comparison-2026-11-11.md)
-- [roadmap](docs/roadmap.md)
+- Stable package: `dsh-cortex-memory@0.2.0`
+- Optional extractor: `dsh-cortex-extractors@0.3.3`
+- DSH: `>=0.2.1-rc.2 <0.4.0`
+- Node: `>=24`
+- Tests: 406/406 (main), 12/12 (extractor)
+- CI: GitHub Actions on Windows, Node 24
+
+The npm package is named `dsh-cortex-memory` because `dsh-cortex` was already
+taken; the installed bundle is still the Cortex memory engine.
+
+## Install
+
+```powershell
+npm i dsh-cortex-memory
+npm i dsh-cortex-extractors   # optional OCR/ASR
+```
+
+Or use the Windows one-click zip from the GitHub Release. The installer
+discovers a desktop DSH installation automatically; `-DshPath` remains available
+for custom installs.
+
+After installing, restart DSH or reload the plugin. The Cortex panel is in the
+left sidebar by default.
+
+## What it provides
+
+| Layer | Contents |
+|---|---|
+| L0 identity | self-model, values, boundaries, stable traits |
+| working | focus, pins, current goals, turn buffer |
+| episodic | what happened, when, provenance, emotion |
+| semantic | entities, facts with validity windows, preferences |
+| procedural | skills, workflows, preconditions, success/failure stats |
+| reflective | episode summaries, insights, narratives |
+| archive | cold but searchable, wakeable until privacy deletion |
+
+Key behavior:
+
+- append-only, hash-chained event log
+- temporal facts; old facts are invalidated, not silently overwritten
+- FTS5 BM25 + optional vector + graph activation + recency/importance/feedback
+- DSR/FSRS-inspired stability, difficulty and retrievability
+- reflection, retention plans and explicit-approval evolution
+- scopes, read-only shared scopes and audit
+- guardian backup, validation, offline restore and privacy cascade
+- loopback-only API and sidebar UI
+
+## UI: extract into memory
+
+On a trace detail page:
+
+1. enter a local `file://` image or audio path
+2. choose OCR or ASR
+3. choose a layout: auto, single, two-column or handwriting
+4. choose a target trace
+5. run **Extract and write**
+
+The extracted text becomes a **derived trace**; the target trace is unchanged.
+Text is never written when extraction returns no text. The extractor is optional;
+without it the button fails closed.
+
+## Permissions and privacy
+
+- Local API: loopback-only, token and origin checks
+- Permission changes: explicit confirmation, local override, restart required
+- Feature flags/metrics: read-only snapshot
+- Shared write grants: only for API clients sending `x-cortex-agent`; revoke is immediate
+- Remote LLM/embedding/rerank: off unless configured and permitted
+- Attachment reader: off by default
+
+Read [permissions](docs/permissions.md) and [privacy](docs/privacy.md) before
+enabling remote models or shared scopes.
+
+## Optional extractors
+
+`dsh-cortex-extractors` adds:
+
+- Windows OCR (default on Windows)
+- Tesseract with TSV layout ordering
+- optional local PaddleOCR bridge for layout/handwriting
+- whisper.cpp ASR
+- custom command providers
+
+It never downloads a model automatically. See the
+[extractor engine docs](https://github.com/Lh1314-China/dsh-cortex-extractors/blob/main/docs/engines.md)
+for model paths and failure behavior.
+
+## Development
+
+```powershell
+npm test
+npm run bench
+```
+
+The test runner uses `node:test` and the built-in `node:sqlite`; no network is
+required. On Node 24 Windows CI the runner is invoked with explicit test files
+and `--test-isolation=none` to avoid a spurious child-process EPERM.
+
+## Compatibility and limits
+
+- Windows is the primary desktop target; the core memory engine is cross-platform.
+- Windows OCR requires an installed Windows OCR language pack.
+- Tesseract and Whisper require local binaries/models.
+- PaddleOCR handwriting is optional and accuracy on cursive is limited.
+- The extractor is a separate package; it is not a dependency of the memory engine.
 
 ## License
 
-MIT. External ideas are cited in the research notes; no third-party source
-code is copied into this package.
-
+MIT.

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.1",
   "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/",