@wilshi/dsh-agentos-context 0.0.0-stage → 0.3.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSE.opencontext

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 melandlabs / dsh-opencontext contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.i18n.yaml

@@ -0,0 +1,67 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/context/agentos-context/README.md
+/:
+  en: 4d9c0980eb7237d3
+  zh: 356009fc60447bbb
+/deepseek-ai-dsh-agentos-context:
+  en: ef8a07d5cd44d427
+  zh: 7719f1c92fd0f9dd
+/deepseek-ai-dsh-agentos-context/summary:
+  en: a20c08f84105aa19
+  zh: b7a9dca4cafb465f
+/deepseek-ai-dsh-agentos-context/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 457575787e95f57c
+/deepseek-ai-dsh-agentos-context/use-this-package:
+  en: 0e8cd600cd9c9eb0
+  zh: 7489f238ba627840
+/deepseek-ai-dsh-agentos-context/use-this-package/automatic-memory-and-recall:
+  en: 56bb480b8d6c3002
+  zh: a3ace50a176d2197
+/deepseek-ai-dsh-agentos-context/use-this-package/knowledge-and-document-parsing:
+  en: adce09e0e056a931
+  zh: f86500f499952405
+/deepseek-ai-dsh-agentos-context/use-this-package/graph-ontology-and-compatibility:
+  en: 15802f94da51e5f3
+  zh: 74111b1b8eee4380
+/deepseek-ai-dsh-agentos-context/understand-the-implementation:
+  en: 81edc502ac8be7ff
+  zh: 7627728d1b54cbdc
+/deepseek-ai-dsh-agentos-context/further-exploration:
+  en: 966eeb68e370959b
+  zh: 41135c0109ce82d5
+/deepseek-ai-dsh-agentos-context/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/deepseek-ai-dsh-agentos-context/model-experience/automatic-recall:
+  en: 6439b4312a56aaf5
+  zh: f1e75985adc44ea5
+/deepseek-ai-dsh-agentos-context/model-experience/automatic-recall/what-the-model-sees:
+  en: 7660942dea6dde50
+  zh: f433b6a5bd30955f
+/deepseek-ai-dsh-agentos-context/model-experience/automatic-recall/token-effect:
+  en: a758dc69c65205d3
+  zh: a814d794f3b33f97
+/deepseek-ai-dsh-agentos-context/model-experience/automatic-recall/kv-cache-effect:
+  en: 8e074116b4503e83
+  zh: 73ac152726580144
+/deepseek-ai-dsh-agentos-context/model-experience/memory-and-knowledge-tools:
+  en: b5d99a9b14b251fd
+  zh: 364634a84d29d64e
+/deepseek-ai-dsh-agentos-context/model-experience/memory-and-knowledge-tools/what-the-model-sees:
+  en: 7ded0722b6e36feb
+  zh: 88bef99e998973f2
+/deepseek-ai-dsh-agentos-context/model-experience/memory-and-knowledge-tools/token-effect:
+  en: e74adb3d24bed53b
+  zh: 696ee630448c08c2
+/deepseek-ai-dsh-agentos-context/model-experience/memory-and-knowledge-tools/kv-cache-effect:
+  en: 59eef4b0d5043933
+  zh: 4aaf55d077c33d46
+/deepseek-ai-dsh-agentos-context/known-limitations-and-deferred-work:
+  en: f597852d4914f4d4
+  zh: 6cf1a70885c050dd
+/deepseek-ai-dsh-agentos-context/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: e88aeb617ffb74ea

package/README.md

@@ -1,3 +1,146 @@
-# Temporary Holding Version
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Fork notice**: this package is a community fork of the internal `@deepseek-ai/dsh-agentos-context` 0.2.1-rc.5 source, published as `@wilshi/dsh-agentos-context` (MIT). It inlines the DSH 0.2.1 client primitives so the web half loads on the public build, removes deployment-specific gateway defaults and wording, and redesigns the memory graph. Data format, tools and RPC namespaces are unchanged.
+description: "Automatic memory, scoped recall, ontology graph, and local document knowledge for DSH Web and Desktop profiles."
+kind: "package-bundle"
+---
+
+# @deepseek/dsh-agentos-context
+
+English | [中文](README.zh.md)
+
+## Summary
+
+agentOS Context adds automatic long-term memory, scoped recall, a source-backed ontology graph, and a local document knowledge base to a DSH profile. The Web application and DSH Desktop include it by default. Existing OpenContext data remains readable without a destructive migration, while new records use an additive sidecar. Profile maintainers can add or remove the bundle with `dsh plugin`; its ontology is intentionally finite rather than a general OWL reasoner.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+DSH Web and Desktop already mount this package through `dsh-web-app`. Open **Settings → Memory** to configure capture, recall, embeddings, distillation and retention, or use the Memory workspace for the list, graph, review and knowledge views. The Settings row and Conversation tab follow the active DSH language. A profile that does not include `dsh-web-app` can activate or remove the installed bundle explicitly:
+
+```text
+dsh plugin --profile <name> add @deepseek/dsh-agentos-context
+dsh plugin --profile <name> remove @deepseek/dsh-agentos-context
+```
+
+Adding the bundle mounts the current implementation on the compatibility `dsh-opencontext` Loader row. Official Settings therefore imports the old section into the same namespace, preserves its values, and applies editable capture, recall, embedding, distillation, retention and scope fields live without remounting the plugin. The command fails if the installed package does not expose its `dsh.bundle.patch` declaration.
+
+### Automatic memory and recall
+
+Automatic human-prompt capture is enabled by default and can be disabled. Accepted prompts are distilled when a configured model is available; a temporary distillation failure retains a low-importance working memory for 24 hours instead of dropping the prompt. Recall searches authorized scopes in `run → agent → workspace → user → app → global` order, keeps run memory inside one Session, and injects only bounded evidence for the accepted user query.
+
+The 3+1 hierarchy stores working, episodic, semantic and procedural layers independently from memory type. Repeated evidence can reinforce and promote a record; approximate conflicts become review candidates rather than overwriting an established fact. Explicitly saved local content remains lossless, including credential-like text; this package does not apply DLP scanning or automatic masking.
+
+Searching the compact conversation Memory view is executed by every underlying scope instead of filtering only the recent records already loaded in the browser. The results are merged and ranked back into the aggregate view, so older matching memories remain discoverable without changing the active workspace.
+
+### Knowledge and document parsing
+
+Knowledge uploads are explicit. With All scopes selected, the Knowledge view aggregates current and legacy documents while new uploads continue to enter the shared global scope. It can upload, list, search, inspect, reindex and delete text files up to 4 MiB and DOCX, XLSX, PPTX, PDF, ODT, ODS, ODP, ODG, RTF or EPUB files up to 25 MiB. Binary extraction runs locally with OCR, attachment extraction and external parser services disabled; only bounded extracted text and source metadata enter the index. Indexing and search use separate default deadlines of 10 minutes and 30 seconds.
+
+Lexical retrieval remains available without embedding credentials. When embeddings are configured, the package loads the local SQLite vector extension and combines lexical and semantic results. Model-backed distillation and embedding send selected text and the configured credential only to endpoints in the startup allowlist; remote endpoints must use HTTPS, while plain HTTP is allowed only for loopback addresses or endpoints explicitly listed in OPENCONTEXT_DSH_TRUSTED_GATEWAY_BASES.
+
+### Graph, ontology and compatibility
+
+The workbench offers a 2D relationship view and an optional remembered WebGL 3D point-cloud view with orbit, zoom, picking, community folding, active light or dark application colors and a source-backed detail drawer; an unsupported WebGL environment falls back to 2D. Model extraction can propose typed objects and relations, but each relation must quote its source exactly and stays pending until a person confirms it. The aggregate view folds a large graph into one community per memory scope before a person opens a scope, while a single scope uses deterministic relationship communities and retains cross-community edges.
+
+In Desktop, leaving native fullscreen also closes graph fullscreen when the DOM fullscreen event is absent. DOM fullscreen entry restores the graph after a rapid reentry, and a delayed earlier native exit does not close the active DOM graph. An explicit toggle or Escape exit remains in force when an earlier pending DOM fullscreen entry arrives; that entry is exited rather than restoring graph fullscreen. The CSS-only fullscreen fallback remains dismissible with Escape.
+
+Legacy OpenContext memories and document references remain read-only inputs and are never rewritten at startup. The package preserves the `dsh-opencontext` settings namespace, reads compatibility identifiers, and keeps callable `oc_*` aliases while presenting `memory_*`, `knowledge_*` and `context_*` names. New revisions, retirements, usage traces and ontology state live in the agentOS Context sidecar; schema-v1 sidecars migrate additively to schema v2.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The bundle patch inserts one dual-face Cordis package. Its Host face opens the compatibility backend and sidecar, registers authenticated `agentos-context/v1/*` RPC routes, model tools, the runtime skill and agent lifecycle listeners. Its Client face installs the first-level Memory settings section and workbench views. Browser operations use authenticated Connection RPC instead of legacy raw browser routes. Modal views use the shared Client UI primitive for focus containment, Escape handling and focus restoration, while this package owns only their content and layout.
+
+Legacy OpenContext storage loads on its first operation, not while importing the plugin for CLI help or schema inspection. Disposing an unused compatibility backend closes any owned document store without loading legacy storage.
+
+The sidecar keeps immutable source and memory revisions, typed entities, reviewed relations, temporal validity, idempotency and usage policy in SQLite. The vector index uses the same scope and revision checks, so a stale or unauthorized embedding cannot become a recall result. Existing OpenContext records are projected conservatively and stay in their original database.
+
+| File | Role |
+|---|---|
+| [`cordis.patch.yml`](cordis.patch.yml) | Bundle activation and legacy-row suppression |
+| [`src/index.ts`](src/index.ts) | Host entry, configuration and plugin assembly |
+| [`src/context/store.js`](src/context/store.js) | Sidecar persistence, ontology and revision rules |
+| [`src/recall.js`](src/recall.js) | Accepted-query scoped recall and prompt injection |
+| [`src/document-parser.js`](src/document-parser.js) | Bounded local text and binary-document extraction |
+| [`src-client/index.tsx`](src-client/index.tsx) | Settings and Memory workbench registration |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Compatibility and operation contract](docs/CONTRACT.md)
+- [Interaction prototype](prototype/PROTOTYPE.md)
+- [DSH profile and bundle composition](../../../docs/architecture.md)
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Automatic recall
+
+#### What the model sees
+
+For an accepted human query, the package appends one `agentos-context`-origin user message containing a bounded `<opencontext_evidence>` block. The producer-owned source remains valid in the current Session format. The block labels recalled records as untrusted evidence, escapes record content and ids, and includes only records from scopes authorized for the current Session.
+
+#### Token effect
+
+Recall adds at most the configured `maxBytes` evidence budget plus its fixed wrapper. No matching record adds no message. The usage tracker records which exact revisions reached a committed request.
+
+#### KV Cache effect
+
+The evidence message follows the current human message, so a different query or memory result changes the request suffix without rewriting earlier durable conversation history.
+
+### Memory and knowledge tools
+
+#### What the model sees
+
+The package registers descriptive tools including `memory_search`, `memory_save`, `knowledge_search` and `knowledge_document_upload`; older `oc_*` names remain callable aliases. Tool results return bounded structured records or document chunks and never grant authority to recalled text.
+
+#### Token effect
+
+Tool schemas contribute their fixed definitions to presets that mount this package. Tool calls add only the bounded result selected by the model and the configured per-operation limits.
+
+#### KV Cache effect
+
+Stable tool definitions can retain the request prefix cache. A tool result appends new history in the ordinary tool-call position and does not mutate previous messages.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- The ontology uses approved finite entity and relationship types; it does not implement arbitrary OWL reasoning, organization-wide authorization, automatic conflict adjudication, review undo, irreversible purge or cross-project sharing.
+- Legacy `.doc`, `.xls`, `.ppt` and proprietary `.wps`, `.et`, `.dps` files are not parsed. Save them as OOXML or ODF first. Image-only PDFs require OCR and are rejected when they contain no extractable text.
+- Automatic capture writes to the current workspace by default. User, Agent and application scopes require trusted runtime identity or explicit local configuration; an untrusted message cannot manufacture those identities.
+- Rolling back to the legacy plugin leaves original records intact but hides sidecar-only writes. A legacy record retired only in the sidecar can therefore reappear after rollback; preserve both databases during evaluation.
+- Knowledge uploads are local explicit actions. This package does not crawl folders, synchronize external repositories or perform OCR.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,144 @@
+---
+
+> **Fork 说明**：本包是内部 `@deepseek-ai/dsh-agentos-context` 0.2.1-rc.5 源码的社区分叉，以 `@wilshi/dsh-agentos-context` 发布（MIT）。它内联了 DSH 0.2.1 的客户端 UI 基础组件，使 Web 端能在公开版加载；同时移除了部署专用的网关默认值与措辞，并重做了记忆图谱。数据格式、工具与 RPC 命名空间保持不变。
+description: "为 DSH Web 与 Desktop 配置提供自动记忆、分域召回、本体图谱和本地文档知识库。"
+kind: "package-bundle"
+---
+
+# @deepseek/dsh-agentos-context
+
+[English](README.md) | 中文
+
+## 概述
+
+agentOS Context 为 DSH 配置增加自动长期记忆、分域召回、基于来源的本体图谱和本地文档知识库。Web 应用和 DSH Desktop 默认包含该能力。现有 OpenContext 数据无需破坏性迁移即可继续读取，新记录写入增量 sidecar。配置维护者可以通过 `dsh plugin` 添加或移除该 bundle；它有意采用有限本体，而不是通用 OWL 推理器。
+
+## 目录
+
+- [使用此包](#use-this-package)
+- [了解实现](#understand-the-implementation)
+- [进一步了解](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与待办事项](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用此包
+
+DSH Web 和 Desktop 已通过 `dsh-web-app` 挂载此包。打开**设置 → 记忆**可以配置捕获、召回、嵌入、提炼和保留策略，也可以在记忆工作台中使用列表、图谱、审核和知识库视图。设置入口和对话页标签会跟随 DSH 当前语言。不包含 `dsh-web-app` 的配置可以显式启用或移除已安装的 bundle：
+
+```text
+dsh plugin --profile <name> add @deepseek/dsh-agentos-context
+dsh plugin --profile <name> remove @deepseek/dsh-agentos-context
+```
+
+添加 bundle 会把当前实现挂到兼容的 `dsh-opencontext` Loader 行上。因此，官方设置服务会把旧设置区直接导入同一命名空间并保留原值；捕获、召回、嵌入、提炼、保留策略和范围等可编辑字段可以即时生效，无需重启插件。如果已安装包没有公开 `dsh.bundle.patch` 声明，命令会失败。
+
+### 自动记忆与召回
+
+自动捕获人工提示默认开启，也可以关闭。配置模型可用时会提炼已接受的提示；提炼暂时失败时会保留一条低重要度工作记忆 24 小时，而不是丢弃提示。召回按 `run → agent → workspace → user → app → global` 顺序搜索已授权范围，将 run 记忆限制在一个会话内，并且只为已接受的用户查询注入有界证据。
+
+3+1 分层将工作、情景、语义和程序记忆与记忆类型分别存储。重复证据可以强化并晋升记录；近似冲突会成为审核候选，不会覆盖已确立事实。用户显式保存的本地内容会无损保留，包括类似凭据的文本；此包不做 DLP 扫描或自动脱敏。
+
+### 知识库与文档解析
+
+知识库上传需要显式操作。选择“全部范围”时，知识库视图会聚合当前文档与旧版文档，新上传的文档仍写入共享全局范围。知识库视图可以上传、列出、搜索、检查、重新索引和删除不超过 4 MiB 的文本文件，以及不超过 25 MiB 的 DOCX、XLSX、PPTX、PDF、ODT、ODS、ODP、ODG、RTF 或 EPUB 文件。二进制提取在本地运行，关闭 OCR、附件提取和外部解析服务；索引只接收有界的提取文本与来源信息。索引和搜索分别使用默认 10 分钟和 30 秒的独立时限。
+
+没有嵌入凭据时仍可使用词法检索。配置嵌入后，此包加载本地 SQLite 向量扩展并组合词法与语义结果。基于模型的提炼和嵌入只会把选定文本与配置凭据发送到启动时精确白名单中的端点；远程端点必须使用 HTTPS，明文 HTTP 仅允许回环地址或显式写入 OPENCONTEXT_DSH_TRUSTED_GATEWAY_BASES 的端点。
+
+### 图谱、本体与兼容性
+
+工作台提供 2D 关系视图，以及可记住选择的 WebGL 3D 点云视图，支持轨道控制、缩放、点选、社区折叠、跟随应用当前明暗主题和基于来源的详情抽屉；不支持 WebGL 时回退到 2D。模型提取可以建议带类型的对象和关系，但每条关系必须精确引用来源，并在人工确认前保持待审核状态。汇总视图会先按记忆范围把大图谱折叠成社区，用户进入某个范围后再查看细节；单一范围继续使用确定性关系社区并保留跨社区边。
+
+Desktop 中退出原生全屏会同步退出图谱全屏，即使没有 DOM 全屏事件。快速重新进入时，DOM 全屏事件会恢复图谱状态，上一轮延迟到达的原生退出不会关闭当前 DOM 全屏图谱。通过按钮或 Escape 主动退出后，上一轮延迟到达的 DOM 全屏进入会被退出，不会重新激活图谱全屏。仅 CSS 的全屏回退仍支持 Escape 退出。
+
+旧 OpenContext 记忆和文档引用保持只读输入，启动时不会重写。此包保留 `dsh-opencontext` 设置命名空间，读取兼容标识，并在展示 `memory_*`、`knowledge_*` 和 `context_*` 名称的同时保留可调用的 `oc_*` 别名。新修订、退役、使用轨迹和本体状态写入 agentOS Context sidecar；schema v1 sidecar 会增量迁移到 schema v2。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 了解实现
+
+<details>
+<summary>实现内部信息——点击展开</summary>
+
+bundle patch 插入一个双端 Cordis 包。Host 端打开兼容后端和 sidecar，注册通过认证的 `agentos-context/v1/*` RPC 路由、模型工具、运行时 skill 和 Agent 生命周期监听器。Client 端安装一级记忆设置入口和工作台视图。浏览器操作使用通过认证的 Connection RPC，不再使用旧的原始浏览器路由。弹窗视图统一使用共享 Client UI 组件处理焦点约束、Esc 关闭和关闭后的焦点恢复，此包只负责内容和布局。
+
+旧 OpenContext 存储在首次执行相关操作时才加载，不会因为 CLI 帮助或配置结构检查而提前加载。销毁未使用的兼容后端会关闭其自有文档存储，但不会初始化旧存储。
+
+sidecar 在 SQLite 中保存不可变的来源和记忆修订、带类型实体、已审核关系、时间有效性、幂等性和使用策略。向量索引使用相同的范围与修订检查，因此过期或未授权的嵌入不会成为召回结果。现有 OpenContext 记录以保守方式投影，并保留在原数据库中。
+
+| 文件 | 作用 |
+|---|---|
+| [`cordis.patch.yml`](cordis.patch.yml) | bundle 激活与旧行抑制 |
+| [`src/index.ts`](src/index.ts) | Host 入口、配置与插件组装 |
+| [`src/context/store.js`](src/context/store.js) | sidecar 持久化、本体与修订规则 |
+| [`src/recall.js`](src/recall.js) | 已接受查询的分域召回与提示注入 |
+| [`src/document-parser.js`](src/document-parser.js) | 有界的本地文本与二进制文档提取 |
+| [`src-client/index.tsx`](src-client/index.tsx) | 设置与记忆工作台注册 |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步了解
+
+- [兼容性与操作约定](docs/CONTRACT.md)
+- [交互原型](prototype/PROTOTYPE.md)
+- [DSH profile 与组合包](../../../docs/architecture.zh.md)
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 自动召回
+
+#### 模型看到的内容
+
+对于已接受的人工查询，此包会追加一条来源为 `agentos-context` 的用户消息，其中包含有界的 `<opencontext_evidence>` 块；该生产者自有来源兼容当前会话格式。该块将召回记录标记为不可信证据，对记录内容和 id 转义，并且只包含当前会话已授权范围内的记录。
+
+#### Token 影响
+
+召回最多增加配置的 `maxBytes` 证据预算及其固定包装。没有匹配记录时不增加消息。使用跟踪器会记录进入已提交请求的精确修订。
+
+#### KV Cache 影响
+
+证据消息位于当前人工消息之后，因此不同查询或记忆结果会改变请求后缀，但不会重写更早的持久会话历史。
+
+### 记忆与知识库工具
+
+#### 模型看到的内容
+
+此包注册描述性工具，包括 `memory_search`、`memory_save`、`knowledge_search` 和 `knowledge_document_upload`；旧的 `oc_*` 名称保留为可调用别名。工具结果返回有界结构化记录或文档分块，并且不会把召回文本提升为指令。
+
+#### Token 影响
+
+工具 schema 会为挂载此包的预设增加固定定义。工具调用只增加模型选中的有界结果和各操作配置限制内的内容。
+
+#### KV Cache 影响
+
+稳定的工具定义可以保留请求前缀缓存。工具结果按普通工具调用位置追加新历史，不会修改以前的消息。
+
+## 已知限制与待办事项
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- 本体只使用已批准的有限实体与关系类型；它不实现任意 OWL 推理、组织级授权、自动冲突裁决、审核撤销、不可逆清除或跨项目共享。
+- 不解析旧版 `.doc`、`.xls`、`.ppt` 和专有 `.wps`、`.et`、`.dps` 文件。请先另存为 OOXML 或 ODF。纯图片 PDF 需要 OCR，没有可提取文本时会被拒绝。
+- 自动捕获默认写入当前工作区。用户、Agent 和应用范围需要可信运行时身份或显式本地配置；不可信消息无法伪造这些身份。
+- 回滚到旧插件不会破坏原始记录，但会隐藏仅存在于 sidecar 的写入。因此只在 sidecar 中退役的旧记录可能在回滚后重新出现；评估期间应保留两个数据库。
+- 知识库上传是本地显式操作。此包不会抓取目录、同步外部仓库或执行 OCR。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,13 @@
+# Third-Party Notices
+
+agentOS context preserves and extends the Apache-2.0-licensed dsh-opencontext package. Its original license notice is distributed as `LICENSE.opencontext`; the package's own license is in `LICENSE`.
+
+Runtime interfaces and dependencies used by this package include:
+- DeepSeek Harness packages 0.1.5-rc.2 and Cordis 4.0.2 (see each installed package for its license).
+- @melandlabs/opencontext 0.5.1 and @melandlabs/env-config 0.4.0.
+- better-sqlite3 12.x and sqlite-vec 0.1.x for the existing OpenContext compatibility path.
+- officeparser 8.0.0 (MIT) for local DOCX/XLSX/PPTX/PDF/ODF/RTF/EPUB text extraction. Its runtime dependencies include @xmldom/xmldom, fflate, file-type, pdfjs-dist and tesseract.js under their respective licenses. OCR is disabled by this plugin.
+- React 18.3.1 and the DSH native UI primitives for client presentation.
+- Three.js 0.186.1 (MIT) for the optional WebGL 3D knowledge-graph view; it is bundled into the client artifact.
+
+This notice does not replace the license files distributed by those projects.

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# @wilshi/dsh-agentos-context bundle patch: mount the memory engine on the
+# OpenContext compatibility loader row used by the DSH web app.
+- insert:
+    - id: dsh-opencontext
+      name: '@wilshi/dsh-agentos-context'

package/docs/CONTRACT.md

@@ -0,0 +1,51 @@
+# Shared context service/store contract v2
+
+All methods return lossless JSON; store methods are synchronous except close may be awaited. An error has code and a safe user-facing message. Desktop identity belongs to the authenticated DSH Connection carrier and service, never caller metadata; no raw browser HTTP mutation or credential route is registered. Client methods use the versioned `agentos-context/v1/*` namespace. Every entity/memory/relation operation is explicitly scoped.
+
+## Records
+Memory = {id, revision, scopeId, content, kind, layer, importance, expiresAt, promotedFrom, lifecycle, epistemic, sourceId, source, recordedAt, validFrom, validTo, metadata, legacy}; kind fact|decision|preference|constraint|outcome|plan|note; layer working|episodic|semantic|procedural; lifecycle active|candidate|retired; epistemic unverified|supported|contested|refuted. Source = {id,scopeId,content,kind,actorRole,complete,recordedAt,lineageId}; role human|assistant|agent|tool|unknown. Layer and kind are independent dimensions. Saving does not imply supported. Revision history keeps source and content immutable.
+Entity = {id,revision,scopeId,name,type,aliases,recordedAt}. Types Project,Person,Requirement,API,Service,Constraint,Decision,Document.
+Relation = {id,revision,scopeId,subjectId,predicate,objectId,sourceId,quote,status,validFrom,validTo,recordedAt}; status pending|confirmed|rejected. Confirmed relations require an existing same-scope source and an exact quote from it.
+Graph = {nodes:[{id,type,subtype?,layer?,importance?,label,timestamp?,status?,scopeId,communityId?}],edges:[{id,source,target,type,status?,relationId?,sourceId?,quote?}],communities:[{id,label,summary,nodeIds,size,edgeCount,externalEdgeCount,topNodeIds,typeCounts,scopeId}],communityEdges:[{id,source,target,count,types}],stats:{nodeCount,edgeCount,communityCount,truncated}}. type is entity/memory/source for nodes; type is predicate or source/mentions for edges. Communities are a deterministic, read-only projection; original nodes and edges are retained. Truncation is explicit and never emits dangling edges.
+
+## Scope identity and recall
+Without a fixed `scopeId`, trusted runtime/config identities resolve in this order: `run → agent → workspace → user → app → global`. The run scope is derived from the current session id and is never authorized for another session. Agent, user and app scopes are omitted when no trusted identity exists. Caller message metadata is not an identity source. A configured fixed `scopeId` preserves legacy single-scope isolation. Automatic capture defaults to workspace; explicit tools may write only to scopes authorized for the current session.
+
+## Module API: src/context/store.js
+export createContextStore({dbPath, now?}) -> ContextStore. Tests use :memory: or explicit workspace temp files; never default to a user DB.
+- listScopes() -> [{id,label,count}]
+- saveMemory({scopeId,content,kind?,layer?,importance?,expiresAt?,source?,metadata?,idempotencyKey?,validFrom?,validTo?,entityIds?}) -> Memory
+- importLegacy({id,scopeId,content,timestamp?,metadata?}) -> Memory; explicit mutation only, retain ID, unknown origin, do not modify external DB
+- getMemory(scopeId,id,{knownAt?,validAt?}?) -> Memory|undefined
+- listMemories({scopeId,query?,lifecycle?,epistemic?,layer?,limit?,knownAt?,validAt?}) -> Memory[]
+- reviseMemory({scopeId,id,expectedRevision,content,reason,kind?,layer?,importance?,expiresAt?,validFrom?,validTo?,actorRole?}) -> Memory
+- transitionMemory({scopeId,id,expectedRevision,layer,importance?,expiresAt?,reason}) -> Memory
+- reinforceMemory({scopeId,id,expectedRevision,layer?,importance?,expiresAt?,source,reason?}) -> Memory
+- expireMemories({scopeId,at?,limit?}) -> Memory[]; creates retired revisions, never deletes history
+- retireMemory({scopeId,id,expectedRevision,reason}) -> Memory
+- versions(scopeId,id) -> Memory[]
+- createEntity({scopeId,name,type,aliases?}) -> Entity
+- listEntities({scopeId,query?,limit?}) -> Entity[]
+- getEntity(scopeId,id) -> Entity|undefined
+- mergeEntities({scopeId,keepId,mergeId,keepRevision,mergeRevision,reason}) -> Entity; identical type, same scope, preserve aliases/source IDs and reject destructive self-relations
+- createRelation({scopeId,subjectId,predicate,objectId,sourceId?,quote?,validFrom?,validTo?}) -> Relation (pending)
+- reviewRelation({scopeId,id,expectedRevision,decision:'confirm'|'reject',reason}) -> Relation
+- listRelations({scopeId,status?,knownAt?,validAt?}) -> Relation[]
+- listReviews({scopeId}) -> pending Relation[]; conflict status may be attached, never silently auto-resolve
+- validateRelation(input) -> {ok,errors:[{field,code,message}]}; pure validation, no writes
+- getSchema() -> {version,memoryLayers:[{id,label}],types:[{id,label}],relations:[{id,label,domain:string[],range:string[]}]}
+- graph({scopeId,rootId?,depth?,includePending?,limit?,knownAt?,validAt?}) -> Graph
+- changes({scopeId,limit?}) -> [{id,action,targetId,reason,at,revision}]
+- recordUsage({id,sessionId,scopeId,messageId?,turn?,step?,phase:'planned',items:[{id,revision,content,sourceId?,kind?,truncated?,legacy?}],reason?,at?}, {trustedLegacy?}) -> usage record; reject duplicate IDs with different payloads. `trustedLegacy` is private to the service-owned recall bridge: an absent sidecar id is accepted only when both the option and item.legacy are true.
+- findUsageByMessageId({sessionId,messageId}) -> exact immutable usage snapshot or undefined; messageId is generated before recall insertion and persisted for restart-safe correlation.
+- updateUsage({id,phase:'committed'|'requested'|'failed',eventSeq?,at?}) -> usage record; never mutate items
+- listUsage({sessionId,scopeId?,limit?}) -> usage[]
+- setUsagePolicy({sessionId,scopeId,memoryId?,mode?:'exclude'|'prefer'|'normal',paused?,expectedRevision?}) -> policy
+- getUsagePolicy(sessionId) -> {revision,scopeId?,paused,excludedIds,preferredIds}
+- close()
+
+## Integration boundaries
+The parent owns src/context/service.js, backend-bridge.js, routes.js, usage.js and all existing src files. The store implementer owns only src/context/{store,sqlite,schema,validation,errors,projections}.js and tests/context-store*.test.js, and may add a clearly named domain-only helper under src/context if needed. Notify before contract changes.
+New store reads are not an implicit migration. Parent handles legacy backend lazy reads and calls importLegacy only before explicit legacy mutation/linking. Node SQLite adapter must not rebuild or overwrite shared better-sqlite3 binaries.
+
+Schema v1 → v2 is an additive sidecar migration: three indexed columns are added while existing immutable `record_json` snapshots remain untouched. The projection boundary supplies semantic/0.5/non-expiring defaults for v1 and OpenContext records. Automatic ontology extraction is internal-only; extracted relations require exact source quotes and enter `pending`, never `confirmed`.

package/docs/IMPLEMENTATION-STATUS.md

@@ -0,0 +1,56 @@
+# agentOS context Implementation Status
+
+## Implemented in the isolated package
+- Visible rename to agentOS context while retaining OpenContext storage/tool compatibility.
+- Persistent sidecar store with immutable source, memory, entity, relation, change and usage records.
+- Scoped reads, explicit legacy import only on mutation, optimistic revisions and safe retirement.
+- Finite ontology schema, domain/range validation, evidence quotes, pending review and historical graph projection.
+- 3+1 memory hierarchy (working, episodic, semantic, procedural), configurable retention, same-session working-memory recall, automatic expiry, evidence reinforcement, safe promotion and candidate-only handling of approximate conflicts.
+- Structured model extraction can propose typed ontology objects and relationships from new captured messages. Every proposed relationship must carry an exact quote from the preserved source and stays `pending` until manual confirmation; invalid or invented evidence is discarded.
+- Legacy and sidecar memories through one compatibility service; descriptive memory/knowledge/context tool names are primary while existing `oc_*` names remain callable aliases. Legacy scope/list discovery pages beyond the former 500-row ceiling (bounded at 100,000) and reports backends that ignore pagination.
+- Legacy memory/document nodes and revision, document-reference and session edges are merged into the bounded graph without writing to the legacy database.
+- Large graphs are projected into deterministic Louvain-style communities without a new runtime dependency. The graph starts collapsed when useful, preserves node view, expands/collapses community members, aggregates cross-community edges and provides community composition and neighboring-community details.
+- Entity-scoped recall follows `run → agent → workspace → user → app → global`. Identity scopes come only from trusted runtime metadata or explicit local settings; absent identities are omitted, cross-session run access is rejected, and fixed legacy scopes remain isolated. Automatic capture continues to default to workspace.
+- Bounded untrusted evidence formatting, downstream-admitted human capture/recall, restart-safe message correlation, and separately labelled planned/committed/requested/failed usage stages.
+- Authenticated, versioned DSH Connection RPC (`agentos-context/v1/*`) and real RPC-backed Memory/Knowledge/Graph/Review/Settings surfaces; raw loopback browser mutation/credential routes are not registered.
+- The Knowledge surface uploads, lists, semantically searches and deletes scope-bound documents. Text uploads are bounded to 4 MB; DOCX/XLSX/PPTX/PDF/ODF/RTF/EPUB sources are bounded to 25 MB and extracted locally through `officeparser` with ZIP, table-cell, timeout and extracted-text limits. Original binary bytes are not persisted. Large indexing and semantic-search operations use dedicated bounded deadlines (`knowledgeUploadTimeoutMs`, default 10 minutes; `knowledgeSearchTimeoutMs`, default 30 seconds) instead of the 4-second interactive-memory deadline.
+- Official 0.2.1 Loader configuration forms on the compatibility `dsh-opencontext` entry, one-time import of the previous settings document, live volatile updates without a plugin remount, staged revision-fenced saves, a standalone first-level “记忆” settings section, and the native conversation “记忆” tab without hiding the composer.
+- First checkpoint deliberately uses the verified conversation.view contract. The prototype’s simultaneous right-side drawer remains a target-runtime follow-up because no supported non-replacing overlay contract has yet been verified.
+- Persistent semantic cache for new sidecar revisions with lexical/graph fallback when embedding is unavailable. Model-backed distillation/embedding requires an exact process-approved gateway. Remote gateway entries must use HTTPS; plain HTTP is accepted only for loopback addresses or for explicitly trusted bases behind a TLS-terminating proxy, configured through `OPENCONTEXT_DSH_TRUSTED_GATEWAY_BASES`. Selected memory/prompt text and the configured Bearer credential may be sent to that endpoint. Automatic prompt capture is enabled by default; a transient distillation failure keeps the accepted human prompt only as a low-importance local working memory with bounded expiry, while a successful empty distillation still drops non-memory chatter.
+- User-authorized memory and knowledge content is stored losslessly without credential-pattern rejection or masking. This applies to manual saves, automatic capture, local document indexing, recall and ontology candidates; structural, size, scope and source-attribution validation remains enforced.
+- The graph surface includes a deterministic 2D mode and a bundled Three.js WebGL 3D exploration mode. The preference is remembered locally, reduced-motion preferences disable auto-rotation, and renderer failures return to 2D without losing graph data.
+
+## Explicitly deferred
+- Arbitrary OWL or recursive reasoning.
+- Organization-wide multi-tenant authorization and cross-project sharing.
+- Automatic contradiction resolution, conflict review queue, alias-candidate review queue, and review undo. Approximate memory conflicts remain candidates, and the current “待确认” tab reviews source-backed pending relations; direct same-type alias merge is available from the object view with optimistic revision checks.
+- Permanent purge, external-system writeback and unattended migration.
+- Bulk auto-extraction of entities/relations from historical records. Automatic extraction applies only to newly captured, successfully distilled messages.
+- Legacy `.doc/.xls/.ppt`, proprietary `.wps/.et/.dps`, document macros, embedded attachments and OCR for scanned PDFs. WPS documents saved as OOXML/ODF are supported through those standard containers.
+- Session-relevance ranking for the conversation pane’s “已存记忆” list; this checkpoint truthfully shows other active scope memories rather than calling them related candidates.
+
+## Verified release gates
+- `npm run verify:release`: Node and Vitest suites, TypeScript, Host/Client build, built registrations, working-tree package checks, exact tarball inspection, and Desktop patch application.
+- Release 0.1.22 distribution: the exact `.tgz` installed into a disposable DSH Desktop 2.2.35 Profile as one package in under two seconds, without downloading or rebuilding native dependencies. The installed archive loaded under Electron ABI 148, opened `better-sqlite3`, loaded sqlite-vec v0.1.9, and composed one disabled legacy row plus one active agentOS context row without warnings.
+- Disposable Profile: final tarball installed/imported with complete local rc2 dependencies; patch composition contains one disabled `dsh-opencontext` row and one active `agentos-context → dsh-agentos-context` row.
+- Release 0.1.4: the exact archive passed package/version/content inspection, and Desktop profile preparation produced one disabled legacy `dsh-opencontext` row plus one active `agentos-context → dsh-agentos-context` row without patch warnings.
+- Release 0.1.5: the full release gate passed with the dedicated memory settings section and bounded local binary document extraction; the exact archive passed identity/content inspection and disposable Desktop patch composition completed without warnings.
+- Release 0.1.6: schema-v1 → schema-v2 migration was exercised against a real SQLite file and preserved the byte-identical historical `record_json`; layer, retention, promotion and pending ontology-candidate tests pass.
+- Release 0.1.6 isolated Web UI: the exact `dsh-agentos-context-0.1.6.tgz` was unpacked into a disposable Desktop Profile, then started through the packaged Desktop CLI. A real Chromium session loaded the page, verified the first-level Memory settings entry and plugin card, created/revised/retired a memory, traversed all five workbench tabs, captured wide/narrow screenshots, and reported zero failed browser requests or console errors. The 760px view had no document or workbench horizontal overflow.
+- Installed Electron ABI 148: the native knowledge-store upload/search/scope-isolation/delete tests passed, including vector-index cleanup after deletion.
+- Installed DSH Desktop Electron runtime: DOCX/XLSX/PPTX/PDF/RTF extraction and corrupt/mismatched/oversized/cancelled input checks all passed.
+- Real legacy database: `%USERPROFILE%\.opencontext\memory\store.db` passed SQLite `quick_check`; 5 populated scopes exposed 540 memories and 240 graph nodes through the prepared Electron runtime. The source database SHA-256 was unchanged before and after verification.
+- The isolated Web-runtime UI validation loaded the plugin tree, served `__DSH_BOOT__` plus the agentOS client module, and rendered the settings card/workbench without browser console errors.
+- Independent final host and client delta reviews reported no remaining blocker/high findings in the remediated areas.
+
+## Still requires authorized runtime verification
+- Actual active Electron Desktop layout, the current user theme/font-scale combination, and native-window restart behavior (isolated Web runtime UI was verified).
+- Conversation view/composer and settings modal behavior inside the active shell.
+- Active Profile add, application restart, real-shell interaction, uninstall and rollback (disposable Profile install/patch verification is complete).
+
+No production Profile, credentials or memory data were modified during implementation.
+
+## Rollback boundary
+- Upgrade does not rewrite or bulk-copy the legacy OpenContext database.
+- New memories, revisions, retirements, ontology data and usage traces live in the sidecar. A rollback to a legacy-only plugin cannot display those new records, and a legacy record retired only through the sidecar may become visible again.
+- Preserve both the legacy OpenContext database and the agentOS sidecar for any downgrade or recovery exercise.