@dsh-cc/memory 0.5.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/memory/memory/README.md
+README.md: e3d00ee79cf9394465b6022485a6a32442a90322
+README.zh.md: 2a052e4fe0493f782b5acf29b44786d321b04952

package/README.md

@@ -0,0 +1,158 @@
+# dsh-memory
+
+English | [中文](README.zh.md)
+
+Claude Code-style file-based memory for the DeepSeek Harness: a durable memdir
+format, a `memory` system-prompt section, the `memory_save` write channel, and
+dynamic recall by a forked side-query. All file access goes through the
+optional `ctx.fs` seam, so a remote or sandboxed backend works unchanged (a
+providerless host mounts memory read-only).
+
+## What this package provides
+
+- **Memdir format** — a memory home (default the harness home's `memory/`)
+  holding an always-loaded `MEMORY.md` entrypoint (capped at 200 lines / 25 KB)
+  per layer, each a one-line index of `.md` topic files. Each topic file
+  carries `name`, `description`, and `type` (`user` / `feedback` / `project` /
+  `reference`) frontmatter plus a Markdown body. The parser is independently
+  exported.
+- **Per-workspace isolation with a global layer** — memories are scoped to the
+  git repository (Claude Code auto-memory identity): `canonicalMemoryRoot`
+  collapses linked worktrees and subdirectories onto the main checkout, then
+  the slug is the upstream `projectKey` dash-encoding of that root, so the
+  workspace directory is `<memoryHome>/projects/<slug>/`. Worktrees of one
+  repo — and the opt-in `<workspaceDir>/team` layer — share one store. The
+  home root itself is the global layer shared by every workspace. Sessions
+  of different repositories never see each other's private memories; facts
+  useful everywhere are saved with `scope: "global"`. Session transcripts
+  still group by raw cwd (`sessions/--<cwd-slug>--`); memory no longer
+  matches that grouping for worktree sessions.
+- **`memory` system-prompt section** — save-channel guidance, each layer's
+  entrypoint content (truncated), a scope-tagged combined index of topic
+  files, and grep search guidance. The section ALWAYS renders (a memoryless
+  layer shows a placeholder) so the save guidance never disappears. One global
+  registration serves every agent: the text callback renders the assembling
+  agent's own workspace layer (the agent arrives via the assemble scope).
+  Delegated children (`delegationDepth > 0`) render an empty string so the
+  section drops out of the child prompt — matching Claude Code, auto-memory is
+  not shared with non-fork subagents; the parent prompt must pass any facts the
+  child needs. Directory scans run in the background through `ctx.fs`; rendered
+  per-layer fragments are cached and `system-prompt/change` fires only when a
+  fragment actually changed; a turn-end listener re-scans so host-side writes
+  surface without a restart.
+- **`memory_save` tool** — the ONLY working save channel. Memory directories
+  live outside every session workspace, so direct `write`/`edit` calls
+  against them are fenced by the fs sandbox and always fail; the section says
+  so explicitly. The tool takes structured fields (`name`, `type`,
+  `description`, `body`, optional `scope`: `workspace` (default) or `global`),
+  resolves the target directory from the calling agent's canonical git root,
+  generates the frontmatter host-side, upserts the `MEMORY.md` pointer, and
+  writes via the `ctx.fs` seam under a per-call policy of
+  `{ mode: 'workspace-write', workspaceRoot: <memory dir> }` — confinement is
+  kept, the writable root IS the memory directory. Validation (kebab-case
+  slugs, the four types, size caps) shares the `writeback` boundary with
+  `dsh-memory-consolidation`'s fork write-back. Registration is opportunistic:
+  hosts without a tools service skip it and stay read-only.
+- **Dynamic recall** — an `agent/pre-step` listener asks a small-model side
+  query (a forked subagent via `ctx.subagents`) which topic files are relevant
+  to the turn, then injects their bodies through `agent.inject()`. Recall
+  scans both layers (the agent's workspace directory plus the global one) and
+  deduplicates: topic files already shown this session are never re-injected.
+  Tools used earlier in the session are tracked (`tools/post-execute`) and
+  passed to the selector so reference-doc memories for an actively-used tool
+  are suppressed (warnings/gotchas about it are still surfaced). Absence of the
+  subagent service or provider skips recall without error.
+- **Team memory (opt-in)** — when `teamEnabled` is `true`, a shared
+  per-workspace team directory (`<workspaceDir>/team`) is layered on the
+  workspace's private memdir and the `memory` section renders a combined
+  workspace + team + global prompt. Every team-memory access runs a
+  seam-native validation chain (pure-string key sanitization first, then
+  `lstat` final-segment symlink rejection, then `resolve` + `contains` prefix
+  containment).
+
+## Usage
+
+Load the plugin with `@dsh-cc/memory`. Configuration knobs:
+
+| Key | Default | Meaning |
+|---|---|---|
+| `memoryHome` | harness home `memory/` | memory home root: the global layer, and the parent of each repository's `projects/<slug>/` directory |
+| `sectionEnabled` | `true` | register the `memory` system-prompt section |
+| `recallEnabled` | `true` | run dynamic recall on pre-step |
+| `recallProviderName` | `fork` | one-shot subagent provider for the recall query |
+| `recallAgentOptions` | unset | raw `agentOptions` stamped onto the recall fork; wins over `recallUseSmallFast` and is NOT alias-resolved (pass a resolved route, not `{ model: 'haiku' }`) |
+| `recallUseSmallFast` | `false` | opt the recall fork into the cheap lane: stamp `resolve('haiku')` from `ccModelRoutes` (inherit when unconfigured). Opt-in so configuring `haiku` for typed agents doesn't silently flip every recall onto a cross-model, prefix-inheriting fork |
+| `teamEnabled` | `false` | enable the per-workspace team memory directory + combined section |
+
+> **`teamEnabled` is off by default.** Enabling it changes the persisted
+> memory layout (creates and reads `<workspaceDir>/team/`), changes what the
+> model writes (workspace vs `team` scope), and points team-memory reads at a
+> shared directory. It is intended for single-tenant, trusted-writer projects:
+> the per-access validation closes traversal, but the *intermediate*-component
+> TOCTOU window is not fully closed (only the final segment is `lstat`-checked,
+> and the resolve/containment check and the read are not atomic). Do not enable
+> `teamEnabled` in multi-tenant or untrusted-writer deployments.
+
+> **Layout change.** Before per-workspace isolation, all memories lived flat
+> in `memoryHome/`. Those top-level files are not migrated: they now serve as
+> the global layer (visible to every workspace). A pre-isolation team
+> directory at `<memoryHome>/team/` is inert — team memory now lives at
+> `<workspaceDir>/team/`; move its files manually if you had `teamEnabled`
+> on. Pre-collapse worktree-cwd slugs (`projects/<slug-of-the-worktree-path>/`)
+> are likewise not migrated: they stay on disk unused; new writes land in the
+> main-checkout bucket.
+
+```ts
+import memory from '@dsh-cc/memory'
+await ctx.plugin(memory, { memoryHome: '/tmp/mem' })
+```
+
+## Model Experience
+
+Baseline cost: one synchronous render of the cached section text per step (no
+I/O). The cheapest path additionally scans the memory directory — when it
+contains topics, recall may spend one small-model subagent call per turn until
+all topics have been shown, then stops. Token growth is bounded by the
+entrypoint truncation caps and the five-file recall ceiling.
+
+## API
+
+- `parseMemoryFile(raw)` — split a topic file into frontmatter + body.
+- `scanMemoryDirectory(fs, dir, signal?)` — read the entrypoint and topic index.
+- `renderMemorySection(globalDir, workspaceDir, ...)` /
+  `renderTeamMemorySection(...)` / `renderLayers(layers)` /
+  `saveGuidance(workspaceDir, globalDir)` — the section text builders.
+- `MemorySection` — background-refresh cache holder for the section (one
+  registration, per-agent workspace layers).
+- `registerMemorySaveTool(ctx, home, section)` / `MEMORY_SAVE_TOOL` /
+  `MEMORY_SAVE_SCOPES` — the model-facing save channel.
+- `validateMemoryWrites(input)` / `writeMemoryFiles(fs, dir, writes)` /
+  `memoryWritePolicy(dir)` / `MEMORY_WRITES_SCHEMA` — the host-side write-back
+  shared with `dsh-memory-consolidation`.
+- `MemoryRecall` — the pre-step recall coordinator.
+- `truncateEntrypointContent(raw)` — apply the line/byte caps.
+- `resolveMemoryHome`, `resolveWorkspaceMemoryDir`, `canonicalMemoryRoot`,
+  `projectSlug`, `cwdOf`, `resolveProjectMemoryRoot` — memdir root and
+  workspace helpers. `canonicalMemoryRoot` is the git-repo collapse
+  (worktrees → main checkout); `cwdOf` stays the live working copy.
+- `sanitizePathKey(key)`, `validateTeamMemKey(fs, teamDir, relativeKey)`,
+  `resolveTeamMemoryRoot(workspaceDir)` — the team-memory security chain and
+  path helpers.
+
+## Known Limitations and Deferred Work
+
+- The `ctx.fs` seam exposes no mtime, so recall deduplication tracks shown
+  paths per session rather than mtime+path; content is re-read fresh each
+  injection, which still reflects on-disk changes. CC's `memoryAge` freshness
+  weighting is therefore deferred until the seam carries mtime (see
+  `docs/cc-parity-matrix.md`).
+- The recall side-query relies on a registered one-shot subagent provider; no
+  provider ships with this package (compose `fork` or `spawn`).
+- `memory_save` writes the workspace and global layers only; a team-scope save
+  channel and a delete channel are deferred (as is CC's direct-Write parity,
+  which the fs sandbox makes impossible for session tools).
+- Team memory (`teamEnabled`) reversibility and safety: enabling it is a
+  persisted-format change, and the intermediate-component TOCTOU window (only
+  the final segment is `lstat`-checked; resolve/containment and the read are
+  not atomic) means it must not be enabled in multi-tenant or untrusted-writer
+  deployments.

package/README.zh.md

@@ -0,0 +1,125 @@
+# dsh-memory
+
+中文 | [English](README.md)
+
+面向 DeepSeek Harness 的 Claude Code 风格文件记忆：可持久化的 memdir 格式、
+`memory` 系统提示词 section、`memory_save` 写入通道，以及通过 fork 的
+side-query 进行动态召回。所有文件访问都走可选的 `ctx.fs` 缝，因此远程或沙箱
+后端可无改动使用（无 provider 的宿主将记忆挂载为只读）。
+
+## 本包提供的能力
+
+- **Memdir 格式** —— 一个记忆 home（默认为 harness home 的 `memory/`），每层
+  包含始终加载的 `MEMORY.md` 入口（上限 200 行 / 25 KB，是 `.md` 主题文件的
+  一行式索引）。每个主题文件带 `name`、`description` 与 `type`（`user` /
+  `feedback` / `project` / `reference`）frontmatter 以及 Markdown 正文。解析器
+  已独立导出。
+- **按仓库隔离 + 全局层** —— 记忆按 git 仓库划分（对齐 Claude Code auto memory）：
+  `canonicalMemoryRoot` 把 linked worktree 和子目录折叠到主 checkout，再对这个
+  根做上游 `projectKey` 的 dash 编码，工作区目录即为 `<memoryHome>/projects/<slug>/`。
+  同一仓库的 worktree —— 以及可选的 `<workspaceDir>/team` 层 —— 共用一份存储。
+  home 根本身是所有工作区共享的全局层。不同仓库的会话互相看不到对方的私有记忆；
+  到处都用得上的事实以 `scope: "global"` 保存。会话转录仍按原始 cwd 分组
+  （`sessions/--<cwd-slug>--`）；worktree 会话的记忆目录不再与之对齐。
+- **`memory` 系统提示词 section** —— 保存通道指引、各层入口内容（截断）、按
+  scope 标注的合并主题索引、以及 grep 搜索指引。section 始终渲染（无记忆的层显示
+  占位符），保存指引永不缺席。一次全局注册服务所有 agent：text 回调渲染发起组装
+  的 agent 自己的工作区层（agent 经 assemble scope 传入）。委派 child
+  （`delegationDepth > 0`）渲染空串，section 从 child 提示词中消失——对齐 Claude
+  Code：自动记忆不与非 fork 子代理共享，父 prompt 必须自行传递 child 需要的事实。
+  目录扫描经 `ctx.fs` 在后台进行；各层渲染片段缓存，仅当片段实际变化时才发出
+  `system-prompt/change`；轮末监听器会重新扫描，host 侧写入无需重启即可进入提示词。
+- **`memory_save` 工具** —— 唯一可用的保存通道。记忆目录在所有会话 workspace
+  之外，直接的 `write`/`edit` 调用会被 fs sandbox 拦截、必然失败，section 文案
+  对此有明确说明。工具接收结构化字段（`name`、`type`、`description`、`body`、可选
+  `scope`：`workspace`（默认）或 `global`），按调用 agent 的规范 git 根解析目标
+  目录，由 host 侧生成 frontmatter、upsert `MEMORY.md` 指针行，并经 `ctx.fs` 缝以
+  `{ mode: 'workspace-write', workspaceRoot: <记忆目录> }` 的 per-call 策略
+  落盘——围栏保留，可写根恰好是记忆目录。校验（kebab-case slug、四种类型、大小
+  上限）与 `dsh-memory-consolidation` 的 fork 写回共用同一 `writeback` 边界。
+  注册是机会式的：宿主无 tools 服务时跳过并保持只读。
+- **动态召回** —— `agent/pre-step` 监听器用小型模型 side-query（通过
+  `ctx.subagents` fork）判断哪些主题文件与当前轮相关，再通过 `agent.inject()`
+  注入其正文。召回扫描两层（agent 的工作区目录加上全局目录）并去重：本会话已
+  展示过的主题文件不会重复注入。会跟踪本会话早期使用过的工具
+  （`tools/post-execute`）并传给 selector，从而抑制正在使用工具的参考文档类记忆
+  （其警告/坑点仍会呈现）。subagent 服务或 provider 缺失时跳过召回，不报错。
+- **团队记忆（可选）** —— 当 `teamEnabled` 为 `true` 时，在工作区私有 memdir 之内
+  叠加该工作区共享的团队目录（`<workspaceDir>/team`），`memory` section 渲染合并的
+  工作区 + 团队 + 全局提示词。每次团队记忆访问都走 seam 原生校验链（先纯字符串键
+  sanitization，再 `lstat` 末段 symlink 拒绝，最后 `resolve` + `contains` 前缀
+  包含校验）。
+
+## 使用
+
+以 `@dsh-cc/memory` 加载插件。配置项：
+
+| Key | 默认值 | 含义 |
+|---|---|---|
+| `memoryHome` | harness home `memory/` | 记忆 home 根：全局层本身，也是各仓库 `projects/<slug>/` 目录的父级 |
+| `sectionEnabled` | `true` | 注册 `memory` 系统提示词 section |
+| `recallEnabled` | `true` | 在 pre-step 上运行动态召回 |
+| `recallProviderName` | `fork` | 召回查询的一次性子 agent provider |
+| `recallAgentOptions` | 未设置 | 直接盖到召回 fork 上的原始 `agentOptions`；优先于 `recallUseSmallFast` 且**不做** alias 解析（传已解析路由，别传 `{ model: 'haiku' }`） |
+| `recallUseSmallFast` | `false` | 让召回 fork 走低价车道：盖 `ccModelRoutes` 的 `resolve('haiku')` 路由（未配置则继承父路由）。默认关闭——为 typed agent 配置 `haiku` 不应悄悄把每次召回变成跨模型、继承前缀的 fork |
+| `teamEnabled` | `false` | 启用 per-workspace 团队记忆目录与合并 section |
+
+> **`teamEnabled` 默认关闭。** 开启会改变持久化记忆布局（创建并读取
+> `<workspaceDir>/team/`）、改变模型写入内容（workspace 与 `team` 两种 scope），
+> 并把团队记忆读取指向共享目录。适用于单租户、受信写者项目：逐次访问校验关闭了
+> 穿越，但*中间组件* TOCTOU 窗口并未完全关闭（仅末段做 `lstat` 校验，且
+> resolve/包含校验与读取并非原子）。不得在**多租户或不可信写者**场景启用
+> `teamEnabled`。
+
+> **布局变更。** 按工作区隔离之前，所有记忆平铺在 `memoryHome/`。这些顶层文件不做
+> 迁移：它们现在充当全局层（对所有工作区可见）。隔离前的 `<memoryHome>/team/` 团队
+> 目录已失效——团队记忆现在位于 `<workspaceDir>/team/`；若你开启过 `teamEnabled`，
+> 请手动搬移其中的文件。折叠前按 worktree cwd 编码的 `projects/<slug>/` 同样不迁移：
+> 留在磁盘上不再写入；新写入落在主 checkout 的桶里。
+
+```ts
+import memory from '@dsh-cc/memory'
+await ctx.plugin(memory, { memoryHome: '/tmp/mem' })
+```
+
+## Model Experience
+
+基准开销：每步一次同步渲染缓存的 section 文本（无 I/O）。最便宜路径还会扫描
+记忆目录——当存在主题时，召回每轮可能花费一次小型模型 subagent 调用，直到所有
+主题均已展示为止。token 增长受入口截断上限与五文件召回上限约束。
+
+## API
+
+- `parseMemoryFile(raw)` —— 将主题文件拆分为 frontmatter 与正文。
+- `scanMemoryDirectory(fs, dir, signal?)` —— 读取入口与主题索引。
+- `renderMemorySection(globalDir, workspaceDir, ...)` /
+  `renderTeamMemorySection(...)` / `renderLayers(layers)` /
+  `saveGuidance(workspaceDir, globalDir)` —— section 文本构建器。
+- `MemorySection` —— section 的后台刷新缓存持有者（一次注册，按 agent 呈现
+  工作区层）。
+- `registerMemorySaveTool(ctx, home, section)` / `MEMORY_SAVE_TOOL` /
+  `MEMORY_SAVE_SCOPES` —— 面向模型的保存通道。
+- `validateMemoryWrites(input)` / `writeMemoryFiles(fs, dir, writes)` /
+  `memoryWritePolicy(dir)` / `MEMORY_WRITES_SCHEMA` —— 与
+  `dsh-memory-consolidation` 共用的 host 侧写回。
+- `MemoryRecall` —— pre-step 召回协调器。
+- `truncateEntrypointContent(raw)` —— 施加行/字节上限。
+- `resolveMemoryHome`、`resolveWorkspaceMemoryDir`、`canonicalMemoryRoot`、
+  `projectSlug`、`cwdOf`、`resolveProjectMemoryRoot` —— memdir 根与工作区解析辅助。
+  `canonicalMemoryRoot` 是 git 仓库折叠（worktree → 主 checkout）；`cwdOf` 仍是
+  现场工作副本。
+- `sanitizePathKey(key)`、`validateTeamMemKey(fs, teamDir, relativeKey)`、
+  `resolveTeamMemoryRoot(workspaceDir)` —— 团队记忆安全链与路径辅助。
+
+## 已知限制与延期工作
+
+- `ctx.fs` 缝不暴露 mtime，因此召回去重按会话记录已展示路径，而非 mtime+path；
+  每次注入都会重新读取内容，仍能反映磁盘变更。CC 的 `memoryAge` 新鲜度加权
+  因此推迟，直到 seam 携带 mtime（见 `docs/cc-parity-matrix.md`）。
+- 召回 side-query 依赖已注册的一次性子 agent provider；本包不内置 provider
+  （请组合 `fork` 或 `spawn`）。
+- `memory_save` 只写工作区层与全局层；团队 scope 的保存通道与删除通道已延期（CC 的
+  直接 Write 语义同样推迟——fs sandbox 使会话工具无法直接写记忆目录）。
+- 团队记忆（`teamEnabled`）的可逆性与安全性：启用即改变持久化格式，且中间组件
+  TOCTOU 窗口（仅末段做 `lstat` 校验；resolve/包含校验与读取并非原子）意味着
+  不得在**多租户或不可信写者**场景启用。

package/lib/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Claude Code-style file-based memory: the memdir format and parser, the
+ * `memory` system-prompt section, and dynamic recall by a forked side-query.
+ *
+ * All file access goes through the optional `ctx.fs` seam, so a remote or
+ * sandboxed backend works unchanged; a providerless host mounts memory as a
+ * no-op. Recall needs `ctx.subagents` and a registered one-shot provider;
+ * absence of either skips recall without error.
+ *
+ * @module @dsh-cc/memory
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export { parseMemoryFile } from './parser.ts';
+export type { ParsedMemoryFile } from './parser.ts';
+export { truncateEntrypointContent, ENTRYPOINT_NAME, MAX_ENTRYPOINT_LINES, MAX_ENTRYPOINT_BYTES } from './truncate.ts';
+export type { EntrypointTruncation } from './truncate.ts';
+export { MEMORY_TYPES, parseMemoryType } from './types.ts';
+export type { MemoryType, MemoryFrontmatter, MemoryIndexEntry } from './types.ts';
+export { scanMemoryDirectory } from './scan.ts';
+export type { MemoryDirectoryState } from './scan.ts';
+export { resolveMemoryHome, resolveProjectMemoryRoot, resolveWorkspaceMemoryDir, canonicalMemoryRoot, projectSlug, cwdOf, gitExecSync, PROJECT_MEMORY_DIR, PROJECTS_DIR, GIT_PROBE_TIMEOUT_MS, } from './paths.ts';
+export type { MemoryGitExec, MemoryGitExecResult } from './paths.ts';
+export { MemorySection, renderMemorySection, renderTeamMemorySection, renderLayers, saveGuidance, MEMORY_SECTION_NAME, MEMORY_SECTION_ORDER } from './section.ts';
+export type { MemoryLayer } from './section.ts';
+export { MemoryRecall, SubagentMemorySelector, extractSelectedNames, MAX_RECALL_MEMORIES } from './recall.ts';
+export type { MemorySelector, RecallCandidate } from './recall.ts';
+export { TeamMemoryError, sanitizePathKey, resolveTeamMemoryRoot, validateTeamMemKey, readTeamMemFile, TEAM_MEMORY_DIR, TEAM_ENTRYPOINT_NAME } from './team.ts';
+export { MEMORY_SAVE_TOOL, MEMORY_SAVE_SCOPES, MemorySaveError, pointerLine, registerMemorySaveTool, renderTopicFile, upsertPointer, } from './save.ts';
+export type { MemorySaveArgs } from './save.ts';
+export { MEMORY_WRITES_SCHEMA, WRITEBACK_MAX_FILE_BYTES, WRITEBACK_MAX_FILES, WRITEBACK_MAX_TOTAL_BYTES, memoryWritePolicy, validateMemoryWrites, writeMemoryFiles, } from './writeback.ts';
+export type { MemoryWrite, MemoryWritePolicy } from './writeback.ts';
+export declare const name = "memory";
+/** Core services required for section registration and event listeners. */
+export declare const inject: string[];
+/** Memory plugin configuration. */
+export interface Config {
+    /**
+     * Memory home root. Defaults to the harness home `memory/`. The home IS the
+     * global layer; each repository's private layer lives at
+     * `<home>/projects/<slug>` (slug encodes the canonical git root).
+     */
+    memoryHome?: string;
+    /** Whether the `memory` system-prompt section is registered (default true). */
+    sectionEnabled?: boolean;
+    /** Whether dynamic recall runs on pre-step (default true). */
+    recallEnabled?: boolean;
+    /** One-shot subagent provider used by recall (default `fork`). */
+    recallProviderName?: string;
+    /** Optional small-model selection passed to the recall subagent. */
+    recallAgentOptions?: unknown;
+    /**
+     * Opt the recall selector into `resolve('haiku')`. Default false so
+     * configuring `haiku` for typed agents does not silently cross-model
+     * every recall fork. Ignored when `recallAgentOptions` is set.
+     */
+    recallUseSmallFast?: boolean;
+    /**
+     * Whether team memory is enabled (default false). Enables a shared
+     * per-workspace team directory (`<workspaceDir>/team`), renders the
+     * triple-layer section, and validates all team-memory access. Off by
+     * default: onboarding a team directory changes the persisted format and is
+     * not safe in multi-tenant or untrusted-writer deployments (see README
+     * residual).
+     */
+    teamEnabled?: boolean;
+}
+export declare const Config: z<Config>;
+/**
+ * Register the `memory` system-prompt section and recall listener.
+ * @param ctx - the host context carrying the system-prompt and agent seams.
+ * @param config - memory behavior knobs.
+ */
+export declare function apply(ctx: Context, config?: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAQxC,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,EAAE,yBAAyB,EAAE,eAAe,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AACtH,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AACzD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAC1D,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAC/C,YAAY,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AACrD,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,yBAAyB,EACzB,mBAAmB,EACnB,WAAW,EACX,KAAK,EACL,WAAW,EACX,kBAAkB,EAClB,YAAY,EACZ,oBAAoB,GACrB,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AACpE,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AACjK,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAC7G,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAClE,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,eAAe,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AAC/J,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,sBAAsB,EACtB,eAAe,EACf,aAAa,GACd,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC/C,OAAO,EACL,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,gBAAgB,CAAA;AACvB,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAEpE,eAAO,MAAM,IAAI,WAAW,CAAA;AAC5B,2EAA2E;AAC3E,eAAO,MAAM,MAAM,UAAmB,CAAA;AAEtC,mCAAmC;AACnC,MAAM,WAAW,MAAM;IACrB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,8DAA8D;IAC9D,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,kEAAkE;IAClE,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,oEAAoE;IACpE,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,MAAM,CAQ3B,CAAA;AAkBF;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI,CAiC7D"}