npm - dsh-engramory - Versions diffs - 0.3.0 → 1.0.1 - Mend

dsh-engramory 0.3.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.en.md ADDED Viewed

@@ -0,0 +1,213 @@
+[简体中文](README.md) | **English**
+# dsh-engramory
+[![dsh-xray](https://img.shields.io/endpoint?url=https%3A%2F%2Funstone.github.io%2Fdsh-xray%2Fbadge%2Ftinqiao-oss__engramory.json)](https://unstone.github.io/dsh-xray/registry.html#tinqiao-oss__engramory)
+Long-term memory for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
+(dsh). What the AI remembers is kept as plain markdown files you can open and edit
+at any time. Part of [Engramory](https://github.com/tinqiao-oss/engramory).
+![The memory page](https://raw.githubusercontent.com/tinqiao-oss/engramory/master/adapters/dsh/plugin/screenshots/memory-page.png)
+## What it does
+- **The memory index rides along on every step.** The index, `MEMORY.md`, lists the
+  notes by name. The plugin puts it into dsh's context on every step, so the AI knows
+  what it has saved without reading a file first, and opens a note when it needs the
+  detail. A write shows up on the next request; whatever is past the cap is left
+  out, and the AI is told to compact.
+- **The index has a hard cap.** 200 lines / 25 KB by default. When the AI writes the
+  index with dsh's file tools and the plugin can work out the result, a write that
+  would grow it past the cap is refused before it happens, and the AI is told to
+  compact; compaction still passes. Details in [How the cap decides](#how-the-cap-decides).
+- **The rules come with it.** What to save, how, and when to clean up: the rules
+  (a skill) are registered by the plugin, with no files to install.
+- **A Memory page in the sidebar.** Read-only; it lists the notes by name and opens
+  one in your computer's default app.
+## Install
+Needs Node.js 18+ and `pnpm` on PATH (dsh's plugin command uses it). In dsh's desktop
+app you can also search for `dsh-engramory` on the Plugins page.
+```sh
+dsh plugin --profile <name> add dsh-engramory
+```
+To uninstall, use `remove` instead of `add`. Compatible dsh releases are listed in
+`dsh.compatibility.dshReleases` in [`package.json`](package.json); an unlisted release
+is unverified.
+**Where the memory lives:**
+- **The global store**, `~/.dsh/.engramory-memory/` (under `$DSH_HOME` when it is set).
+  With the plugin alone this is the only store; the AI creates it on its first save.
+- **A project store** (optional), `.engramory-memory/` in a project's root, is created
+  by you only: run `python tools/engramory_init.py dsh --project-root <project>` from
+  the Engramory repo, which also git-ignores it. Where one exists, what holds only in
+  that project goes there; everything else stays in the global store.
+Only one AI may write a store; two writers overwrite each other. To share it, let the
+others read it only: see [one writer, many readers](../../reader/README.md). Memories are plain text and carry machine-local detail. Inside a project's git repo
+the store must be git-ignored; a dedicated private repo for the store is fine.
+**Without the plugin:** `python tools/engramory_init.py dsh --install-skill` writes the
+rules into `$DSH_HOME/AGENTS.md`, installs the skill in `$DSH_HOME/skills/engramory/`
+(`$DSH_HOME` defaults to `~/.dsh`) and creates the global store. The AI still keeps memory, but reads the index itself, and
+the cap holds only if it runs `engramory_check.py` after each write.
+## Companion mode (大肥鱼模式)
+For a character you chat with: the community's 大肥鱼, or any persona. Turn on the
+companion switch on the settings page, or set `companion: true`.
+![The memory page in companion mode](https://raw.githubusercontent.com/tinqiao-oss/engramory/master/adapters/dsh/plugin/screenshots/companion-mode.png)
+- **Three more types for the character's own life** ([SKILL.md §2.2](../../../SKILL.md)):
+  `moment`, something you shared, with its date, folded into a monthly archive when
+  the index fills; `upcoming`, something coming up in your life, asked about once its
+  date passes and rewritten as a moment once you say how it went; `self`, a change in
+  the character itself, such as a nickname. A moment or self note is deleted only when
+  you ask it to forget.
+- **Recall in character.** Even a greeting may call for recall, and what it remembered,
+  or failed to save, is told in the character's voice, without naming files or tools.
+- **The persona preset needs the file tools.** The memory arrives even under a preset
+  that turns optional context off (dsh's `minimal`, for one). To save notes, though, the
+  preset needs dsh's file tools and the skill tool; a preset with only a shell reads the
+  memory, and its writes go past the cap.
+## Social mode
+A choice inside companion mode, for a character other people can talk to as well, such
+as one wired to QQ, WeChat, Douyin or Bilibili through a bridge plugin. Choose *Social*
+under *Memory access* on the settings page, or set `audience: social`. If only you talk
+to this dsh, keep the default, *Private*.
+With it on, **only your own conversations get the memory**: one is yours when you have
+typed in it in dsh's own window (the desktop app or `dsh web`) and nobody else has.
+A subagent goes with its parent. Messages from a bridge plugin (unless it marks them as
+the owner's, below), `dsh headless`, other programs, and terminal or editor clients
+count as someone else's. Once anyone else has written in a conversation it stays
+theirs, and the memory already put into it stays in its history.
+Someone else's conversation gets no index and is not told where the store is; dsh's
+file tools there may name files only (every directory is refused), and any path into
+a store is refused however it is spelled. This is **not** a security boundary: a shell
+tool reads any file, and another profile on the same account can read the store too.
+Real isolation needs filesystem permissions or a sandbox.
+### For bridge authors
+With social mode on, every message a bridge submits counts as someone else's. For a
+message from the owner's own account (their private QQ chat with the character, say),
+put a `speaker` on its source:
+```js
+agent.followup(createUserMessage({
+  content: [{ type: 'text', text }],
+  source: { kind: 'plugin:your-bridge', speaker: { role: 'owner' } },
+}))
+```
+| `speaker.role` | Meaning |
+|---|---|
+| `owner` | The owner wrote it: it comes from the account the user set as theirs in your bridge. |
+| `guest` | Someone else wrote it, the same as no `speaker` at all. |
+| `none` | Nobody wrote it: your plugin's own report, reminder or notice. It does not make the owner's conversation someone else's. |
+A group conversation stays someone else's once anyone else in it speaks. A program
+that talks to dsh only through dsh web's API cannot set a source, so its messages count
+as someone else's; if it sends `clientTimeZone` with a prompt it is taken for the
+owner, so a program forwarding other people's messages must leave it out.
+## Settings page and memory page
+![The settings page](https://raw.githubusercontent.com/tinqiao-oss/engramory/master/adapters/dsh/plugin/screenshots/settings-page.png)
+- **Settings page:** on dsh's *Plugins* page, open *Engramory memory* to set companion
+  mode, memory access and the index cap. Saving goes through dsh's own profile editor,
+  which writes your profile's `cordis.patch.yml` and reloads the plugin. Only you, signed
+  in, can call it, so an agent cannot use it to switch social mode off.
+- **Memory page:** *Memory* in the sidebar. It lists the global store and each
+  workspace's project store (with an absolute `indexPath`, that store alone; with a
+  relative one, none), with each index's size against the cap, its notes' names
+  by type, and its archive. Read-only, never a note's text; a name, *Open the index* and
+  *Open the folder* open on the machine dsh runs on. The two switches at the top save
+  as you flip them.
+## Configuration
+Settings the page does not cover go in your profile's `cordis.patch.yml`. Patch the
+EXISTING row by id; a second `- insert:` adds another engramory row and leaves the old
+caps in force. A patch replaces the row's whole `config`, so list every key you keep:
+```yaml
+- id: engramory
+  config:
+    indexName: MEMORY.md
+    maxLines: 200
+    maxBytes: 25600
+```
+| Field | Default | Meaning |
+|---|---|---|
+| `indexName` | `MEMORY.md` | The file name treated as the index, case-insensitive. |
+| `maxLines` | `200` | Line cap for the index. |
+| `maxBytes` | `25600` | UTF-8 byte cap for the index (25 KB). |
+| `indexPath` | unset | The one index to use: absolute, or relative to the session's directory. Unset, a `MEMORY.md` in any project is capped as an index; a store outside the default places also needs it to be found. |
+| `registerSkill` | `true` | `false` keeps the cap but skips the built-in rules. |
+| `injectIndex` | `true` | `false` stops putting the index into context; the AI reads it instead. |
+| `language` | dsh's | `zh` (or `zh-CN` and other regional forms) writes the store in Chinese: note names, headings such as `## 用户`, the Why/How labels. Any other value is English. Unset, it follows dsh's language; a change applies once dsh restarts. Frontmatter keys and `type:` values stay English, so every host reads the store. |
+| `companion` | `false` | `true` turns companion mode on. |
+| `audience` | `private` | With companion mode on, `social` turns social mode on. |
+| `skill` | built-in | Your own markdown in place of the built-in rules; it must then say where the store is. |
+## How the cap decides
+| Case | Decision |
+|---|---|
+| The index ends within the caps | allow |
+| The write grows the index past a cap | **deny**, with the numbers and what to compact |
+| The index is over a cap and the write shrinks it or keeps its size | allow, so compaction can go step by step (210 → 205 → 198) |
+| An edit with `old_str`/`new_str` | its result is worked out first, then judged as above |
+| A partial edit whose result cannot be worked out (e.g. `insert`) | deny on an over-cap index, else allow |
+| The index is missing, unreadable, or not a regular file | a whole-file write is judged as if it were empty; a partial edit passes |
+| The index is past the read limit (`min(16 MiB, max(1 MiB, 4 × maxBytes))`) | not read whole: a whole-file write is judged on bytes alone; a partial edit passes |
+| Reads, writes to other files, unknown tools or arguments | allow; reads are never blocked, even over the cap |
+Lines and bytes are judged apart: only a dimension that is over its cap AND grew is
+refused, so a write with fewer bytes but lines grown past the cap is still refused.
+The line count ignores a trailing newline, so an index exactly at the cap stays
+writable. This table is pinned by `node --test` in CI.
+## Known limits
+- **Only dsh's own file tools are capped** (`write`, `edit`, `str_replace_editor` and
+  the like). Shell tools, MCP file tools and external editors go past it: run
+  `engramory_check.py` after editing the index and `engramory_doctor.py` now and then.
+- **Stores are found only where the installer puts them.** Elsewhere, or for a project
+  store that links out of the project, set `indexPath`. A project's root is found by
+  its `.git` only, and a project store created mid-session can take ten seconds to appear.
+- **Social mode knows you by what dsh's window sends.** Apart from a bridge's owner
+  messages, only what you type in dsh's own window is yours, and not when the browser's
+  time zone cannot be read. A kind of
+  message a later dsh adds counts as someone else's until this plugin knows it: your
+  conversation may lose the memory, never the other way round.
+- **What the memory page opens is checked by path.** dsh's opener resolves the path once
+  more before the desktop opens it, so a process changing the store's files at that
+  moment could redirect what opens (as with dsh's own opener for any workspace file).
+- **Experimental:** companion mode, social mode, and the settings and memory pages may
+  change in a minor version.
+## Versions
+This package carries Engramory's version: `dsh-engramory@X.Y.Z` is the repo's
+`vX.Y.Z`. The cap's decisions (the table above) and the settings outside the
+experimental features change incompatibly only in a major version. See Engramory's
+[Versioning](https://github.com/tinqiao-oss/engramory/blob/master/README.en.md#versioning); history is in the
+[CHANGELOG](../../../CHANGELOG.md).
+## License
+MIT — see the [Engramory repository](https://github.com/tinqiao-oss/engramory).

package/README.md CHANGED Viewed

@@ -1,160 +1,60 @@
-[English](README.md) | [简体中文](README.zh-CN.md)
+**简体中文** | [English](README.en.md)
 # dsh-engramory
 [![dsh-xray](https://img.shields.io/endpoint?url=https%3A%2F%2Funstone.github.io%2Fdsh-xray%2Fbadge%2Ftinqiao-oss__engramory.json)](https://unstone.github.io/dsh-xray/registry.html#tinqiao-oss__engramory)
-Curated, file-based long-term memory for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) —
-plain markdown notes you can open with anything,
-[one writer and many readers](../../reader/README.md) across hosts, and a pre-write
-index guard for matched file tools. (If the store
-lives inside a project's git repo it must be git-ignored — memories carry machine-local
-detail; see SKILL.md §1. A *dedicated private* repo for the store itself is fine.)
+给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）用的长期记忆插件。AI 记住的东西存成一个个普通 markdown 文件，你随时能打开看、能改。属于 [Engramory](https://github.com/tinqiao-oss/engramory)。
-Part of [Engramory](https://github.com/tinqiao-oss/engramory).
+![记忆页](https://raw.githubusercontent.com/tinqiao-oss/engramory/master/adapters/dsh/plugin/screenshots/memory-page.png)
-## Why a plugin, when an `AGENTS.md` block already works
+## 它做什么
-The block carries the discipline. Three things it cannot do:
+- **每轮自动带上记忆索引。** 索引 `MEMORY.md` 只列笔记名字，插件每一步都把它放进上下文，AI 不用先读文件就知道自己记过什么，要细节再打开那条笔记。写入后下一轮就能看到；超出上限的部分不带上，并提醒 AI 压缩。
+- **索引有硬上限。** 默认 200 行 / 25 KB。AI 用 dsh 的文件工具写索引时，只要插件算得出写完的样子，会超上限就在写入前拒绝，让它先压缩；压缩照样放行。细节见[上限怎么判](#上限怎么判)。
+- **自带记忆规则。** 记什么、怎么记、什么时候清理，这套规则（skill）随插件注册，不用另外装文件。
+- **侧栏多一个「记忆」页。** 只读，列出笔记名字，点名字用电脑上的默认程序打开。
-**The index is already in context — recall needs no read.** On every step the plugin
-puts the memory index into dsh's runtime context: the project store
-(`<project>/.engramory-memory/MEMORY.md`, the nearest one between the session's
-directory and its git root — the way dsh finds a project's `AGENTS.md`) and the global one
-(`$DSH_HOME/.engramory-memory/MEMORY.md`, `~/.dsh` when `$DSH_HOME` is unset) —
-where `tools/engramory_init.py dsh` puts them — or, when set, `indexPath` alone. It is
-re-read whenever it changes, so a write shows on the next request, and cut at the cap:
-lines past it are left out, and the model is told to compact. Turn it off with
-`injectIndex: false`.
+## 安装
-**The cap becomes deterministic for matched tools.** `ctx.tools.guard()` is a
-synchronous, **monotonic** refusal: once a guard returns a reason, later listeners
-cannot allow the call. This keeps the index within its configured growth limits
-without relying on the agent to run a checker. Use **`dsh-engramory >= 0.2.7`**;
-[PORTING.md](../../../PORTING.md) records which hosts have shipped guards, and
-[CHANGELOG.md](../../../CHANGELOG.md) holds release history.
+需要 Node.js 18+，PATH 里要有 `pnpm`（dsh 的插件命令要用）。dsh 桌面版也可以在插件页搜 `dsh-engramory` 安装。
-**The protocol arrives with the plugin.** The skill is registered at runtime through
-dsh's skill registry — via a reactive `ctx.inject(['skills'], …)` child, so a profile
-without a registry still gets the cap and one whose registry activates late still gets
-the skill — which means it does not depend on landing files in one of the five skill
-roots dsh scans, a path that is easy to get subtly wrong and fails silently when you do.
+```sh
+dsh plugin --profile <名字> add dsh-engramory
+```
-## Install
+卸载把 `add` 换成 `remove`。兼容的 dsh 版本见 [`package.json`](package.json) 里的 `dsh.compatibility.dshReleases`，没列出的版本未经验证。
-Zero-dependency ESM with no build step; requires Node.js 18+ and `pnpm` on PATH
-for dsh's plugin command.
+**记忆存在哪：**
-```sh
-dsh plugin --profile <name> add dsh-engramory
-```
+- **全局库** `~/.dsh/.engramory-memory/`（设了 `$DSH_HOME` 就在它下面）。只装插件就用这一个，AI 第一次保存时自己建。
+- **项目库**（可选）是项目根目录下的 `.engramory-memory/`，只能由你来建：在 Engramory 仓库里运行 `python tools/engramory_init.py dsh --project-root <项目>`，它会顺手加进 `.gitignore`。有项目库时，只在这个项目成立的事记在那里，其余仍记全局库。
-Check `dsh.compatibility.dshReleases` in [`package.json`](package.json) for the
-exact compatible releases, backed by [`results.json`](../../../tests/dsh_e2e/results.json).
-Use the [E2E guide](../../../tests/dsh_e2e/README.md) to verify another release.
+一个库只能有一个 AI 写，同时写会互相覆盖；想让别的 AI 也用，让它只读，见[单写者、多读者](../../reader/README.md)。记忆是明文，带着本机细节。放在项目的 git 仓库里必须 git-ignore；给记忆库单独开一个私有仓没问题。
-The package ships a `dsh.bundle` manifest pointing at its own
-`cordis.patch.yml`, so the row is inserted into the profile's plugin tree for you — no
-hand-editing. To change a default, patch the EXISTING row by id in your profile's own
-patch layer — do **not** use a second `- insert:` (insert always appends, so you would
-end up with two engramory rows and the original caps still enforced):
+**不装插件也能用：** `python tools/engramory_init.py dsh --install-skill` 把记忆规则写进 `$DSH_HOME/AGENTS.md`、把 skill 装进 `$DSH_HOME/skills/engramory/`（`$DSH_HOME` 默认 `~/.dsh`），并建好全局库。AI 照样会记，但索引要它自己去读，上限只靠它写完后自觉运行 `engramory_check.py`。
-```yaml
-- id: engramory
-  config:
-    indexName: MEMORY.md
-    maxLines: 200
-    maxBytes: 25600
-```
+## 大肥鱼模式
-A patch replaces the targeted row's whole `config`, so list every key you mean to keep.
+给陪你聊天的角色用（社区里的大肥鱼，或任何人设）。在设置页打开「大肥鱼模式」，或在配置里写 `companion: true`。
-With the plugin alone, the memory is one global store, `$DSH_HOME/.engramory-memory/`
-(`$DSH_HOME` defaults to `~/.dsh`): the skill tells the AI where it is, and the AI
-creates it on its first save. A project can have a store of its own,
-`.engramory-memory/` in its root, which only you create — the installer does it and
-git-ignores it (`python tools/engramory_init.py dsh --project-root <project>`). The AI
-never creates one; where one exists, what holds only in that project goes there, and
-everything else stays in the global store. The installer also writes the always-on block
-into `AGENTS.md` (`python tools/engramory_init.py dsh --install-skill`).
+![大肥鱼模式下的记忆页](https://raw.githubusercontent.com/tinqiao-oss/engramory/master/adapters/dsh/plugin/screenshots/companion-mode.png)
-To uninstall:
+- **多记三类角色自己的事**（[SKILL.md §2.2](../../../SKILL.md)）：`moment`（经历）是和你一起经历的事，带日期，索引满了按月归档；`upcoming`（约定）是你将要发生的事，日子过了会问起结果，问到了再改写成经历；`self`（我自己）是角色自己的变化，比如外号。经历和我自己只有你说忘掉才删。
+- **用角色口吻回忆。** 打招呼也可能让它想起点什么；记住了、没记上，都用角色的话说，不提文件和工具。
+- **人设预设要留着文件工具。** 记忆总会送到，哪怕预设关掉了可选上下文（比如 dsh 的 `minimal`）。但角色要保存记忆，预设得带上 dsh 的文件工具和 skill 工具；只给了 shell 的预设读得到记忆，写入却绕过上限。
-```sh
-dsh plugin --profile <name> remove dsh-engramory
-```
+## 社交模式
+大肥鱼模式里的一个选项，给别人也能聊的角色用，比如通过接入插件接到 QQ、微信、抖音、B 站的角色。在设置页「记忆权限」选「社交」，或写 `audience: social`。只有你自己跟这个 dsh 聊，就保持默认的「专属」。
+打开后，**只有你本人的会话拿得到记忆**：你在 dsh 自己的窗口（桌面版或 `dsh web`）里亲手发过消息、且没有别人说过话的会话才算你的。子 agent 跟着它的父会话算。接入插件转来的消息（标明是主人的除外，见下文）、`dsh headless`、外部程序、终端和编辑器客户端发的都算别人的；一个会话只要有别人说过话，就一直算别人的，之前已经带进去的记忆仍留在对话记录里。
-## Companion mode (大肥鱼模式)
-For a character the user chats with — the community's 大肥鱼, or any persona. Turn it on
-with `companion: true`, or the 大肥鱼模式 switch on the settings page (below).
-- **Three more types for the character's own life** ([SKILL.md §2.2](../../../SKILL.md)):
-  `moment` — something the character and the user shared, with its date; kept, and
-  folded into a monthly archive when the index fills. `upcoming` — something coming up
-  in the user's life; asked about once its date passes, and rewritten as a `moment`
-  once the user has said how it went. `self` —
-  a change in the character itself, such as a nickname; updated in place, never folded.
-  A `moment` or `self` note is deleted only when the user asks to forget. In a Chinese
-  store their headings are `## 经历`, `## 约定` and `## 我自己`. The other four types
-  keep their meaning.
-- **Recall in character.** The agent is told that, when it plays a character for you,
-  any message, a greeting included, may call for recall, and to speak of what it
-  remembered — or failed to save — in character, without naming files or tools.
-- **The persona preset decides what it can do with memory.** With companion mode or
-  social mode on, what a conversation is given — the memory and its rules, or social
-  mode's note — is a *required* runtime context, so it arrives even under a preset that
-  turns optional context off (dsh-persona's `includeRuntimeContext: false`, as dsh's
-  `minimal` preset does). Saving is another matter: the preset needs dsh's file tools and
-  the skill tool for the character to write notes the way the skill describes. A preset
-  with only a shell can read the memory it is given, and its writes go past the guard.
-## Social mode
-A choice inside companion mode, for a character other people can talk to as well — one
-wired to QQ, WeChat, Douyin or Bilibili through a bridge plugin. With companion mode on,
-choose *Social* (社交) under *Memory access* (记忆权限) on the settings page, or set
-`audience: social`. The default, *Private* (专属), gives every conversation the memory:
-if only you talk to this dsh, keep it. Without companion mode, `audience` changes
-nothing.
-- **Only your own conversations get the memory.** A conversation is yours when you have
-  written in it in dsh's own window — the desktop app or `dsh web` — and nobody else has.
-  dsh stamps every user message with where it came from, and its browser client sends
-  each prompt with a request id and the browser's time zone: that is how a message you
-  typed there is told apart. Everything else is someone else's:
-  - a message a bridge plugin submits, under a kind of its own (`plugin:<name>`, as
-    dsh-onebot writes, or any other kind dsh's own producers do not use) or dsh's plain
-    `user` kind, unless the bridge marks it as yours (the standard below);
-  - a program calling dsh web's API, `dsh headless`, an editor or terminal client;
-  - a conversation an automation or a plugin opened, until you write in it;
-  - a caller dsh itself names as someone other than the owner.
-  Once anyone else has written in a conversation it stays theirs, even after you write
-  in it too: what the memory put into it earlier stays in its history. Messages dsh
-  adds itself (runtime context, skills, compaction, agent-to-agent messages) decide
-  nothing.
-- **Someone else's conversation gets no memory:** no index, a note saying so, no full path
-  to the store (the skill, which every conversation reads, gives none in social mode; your
-  own conversations are told it in their runtime context), and file tools that may name
-  files only. A directory is refused (so grep, glob and directory
-  views are — any tree may hold a store), and so is any path into a store, however it is
-  spelled or linked, including a store that does not exist yet, so none can be planted
-  for you. A subagent is yours while its live parent is — read afresh on every call —
-  and nobody else has written to it directly; a forked conversation is judged by its own
-  history, the part it inherited included. A call with no session, a
-  dsh without session projections, or a network path counts as someone else's.
-This keeps the user's memory out of others' context by the routes dsh's own file tools
-take. It is **not** a security boundary: a shell tool reads any file, and a different
-profile on the same account can still read the store's files. Keeping others away from
-the store needs filesystem permissions or a sandbox.
-### For bridge authors: marking who wrote a message
-With social mode on, every message a bridge submits counts as someone else's. For the
-owner's own chat to get the memory — their private QQ chat with the character, say —
-put a `speaker` on the message's source:
+别人的会话拿不到索引，也不知道记忆库在哪；dsh 的文件工具只能指名文件（任何目录都不让列），指向记忆库的路径不管怎么写都拒绝。这**不是**安全边界：shell 工具照样能读任何文件，同一账户下的另一个 profile 也读得到。要真正隔离，得靠文件权限或沙箱。
+### 给接入插件作者
+社交模式下，接入插件转进来的消息默认都算别人的。来自主人自己账号的消息（比如主人和角色的 QQ 私聊），在来源章上标 `speaker`：
 ```js
 agent.followup(createUserMessage({
@@ -163,154 +63,73 @@ agent.followup(createUserMessage({
 }))
 ```
-| `speaker.role` | Meaning |
+| `speaker.role` | 含义 |
 |---|---|
-| `owner` | The dsh owner wrote it: a message from the account the user set as theirs in your bridge. |
-| `guest` | Someone else wrote it — the same as no `speaker` at all. |
-| `none` | Nobody wrote it: your plugin's own report, reminder or notice. It does not turn the owner's conversation into someone else's. |
-Mark a message `owner` only when it comes from the owner's own account. A group's
-conversation stays someone else's once anyone else in it speaks. dsh keeps unknown
-source fields in the session log, so the role survives a restart.
-A program that talks to dsh only through dsh web's API cannot set a source, and its
-messages count as someone else's — unless it sends `clientTimeZone` with a prompt: dsh
-then records exactly what its own page sends, and the message counts as the owner's. A
-program forwarding other people's messages must leave `clientTimeZone` out.
-## Settings page
-On dsh's **Plugins** page, open *Engramory memory*: its page sets companion mode (a
-switch) and, while it is on, its memory access (private or social), and the index cap.
-The memory's language follows dsh's own (see `language` below).
-Saving goes through dsh's own profile editor: it validates the whole config, writes it
-to your profile's `cordis.patch.yml`, and reloads the plugin with it — or leaves the
-file as it was. A save made against settings that changed elsewhere in the meantime is
-refused, and the page reads them again. Settings put back to their defaults remove
-their override instead of pinning it. Other fields (`indexName`, `indexPath`, …) stay
-in the file.
-Only you reach the page's route — your signed-in browser, or a program holding your
-login: dsh answers 401 to a request without it and 403 to a cross-site one, so an agent
-cannot call it to switch social mode off. A dsh without the profile editor shows the page read-only.
-Companion mode and its memory access are also at the top of the memory page (below).
-## Memory page
-dsh's sidebar gets a **Memory** entry. Its page lists the stores recall can use — the
-global store under `$DSH_HOME` and each workspace's project store, found as recall finds
-one, or, with `indexPath` pinned, that index's directory alone — with each index's size
-against the cap, its notes' names by type, and its archive. It is read-only and shows
-names only, never a note's text: a name opens the note in your computer's default app,
-through dsh's own opener, on the machine dsh runs on. Where dsh says it cannot open there
-(over SSH, say), the names are plain text and the page shows where the files are.
-*Open the index* opens the index the same way; *Open the folder* shows the index in your
-file manager (Explorer and Finder select it in the store's folder; on Linux the folder
-opens), so a store with no index has no such button. At the top, companion mode and its
-memory access save as they are switched; what they mean, and the index cap, are on the
-settings page.
-The listing is bounded — 2000 entries looked at per folder, 200 workspaces, 5000 names in
-all — and never looks into a workspace on a network share path (`\\server\share\…`), or
-one whose folder has since become a link to somewhere else. A note that is a link is not
-listed; what is opened is a note or the index found again, by name, directly in its store,
-and refused if it has become a link. A relative `indexPath` follows each conversation's
-directory, so the page cannot list it. Only you reach the page's route, as the settings
-page's.
-## Configuration
-| Field | Default | Meaning |
+| `owner` | 主人发的：来自用户在你插件里设为"自己"的那个账号。 |
+| `guest` | 别人发的，和不写 `speaker` 一样。 |
+| `none` | 不是人发的：你插件自己的汇报、提醒或通知，不会让主人的会话变成别人的。 |
+群聊里只要有别人说话，那个会话就一直算别人的。只通过 dsh web 接口发消息的程序设不了来源章，消息都算别人的；它若带上 `clientTimeZone`，会被当成主人，所以替别人转发消息的程序不要带。
+## 设置页与记忆页
+![设置页](https://raw.githubusercontent.com/tinqiao-oss/engramory/master/adapters/dsh/plugin/screenshots/settings-page.png)
+- **设置页**：dsh 的「插件」页里点开「Engramory 记忆」，能改大肥鱼模式、记忆权限和索引上限。保存走 dsh 自己的配置服务，写进你 profile 的 `cordis.patch.yml` 并重新加载插件。这个接口只有登录了的你能调，AI 没法调用它关掉社交模式。
+- **记忆页**：左侧栏「记忆」。列出全局库和各工作区的项目库（设了绝对路径的 `indexPath` 时只列那一个，相对路径则列不出），显示索引离上限还有多远、按类型分组的笔记名字和归档。只读，不显示正文；点名字、「打开索引」「打开文件夹」都在运行 dsh 的那台机器上打开。顶部的两个开关拨了就保存。
+## 配置
+设置页没有的配置，写在你 profile 的 `cordis.patch.yml` 里：按 id 改已有的那一行，别再写一个 `- insert:`（那会多出第二行 engramory，旧上限照样生效）。一次 patch 会整体替换 `config`，要保留的键都列上：
+```yaml
+- id: engramory
+  config:
+    indexName: MEMORY.md
+    maxLines: 200
+    maxBytes: 25600
+```
+| 字段 | 默认值 | 含义 |
 |---|---|---|
-| `indexName` | `MEMORY.md` | Basename treated as the memory index (case-insensitive; both `file_path` and `str_replace_editor`'s `path` are checked) — the name a write is called by, or the name of the file it lands on, so a symlink under another name is caught too. An empty or non-string value falls back to the default, and so does one that is not a plain file name (a path separator, a `:`, `.` or `..`). |
-| `maxLines` | `200` | Hard line cap. Non-positive or non-finite values fall back to the default. |
-| `maxBytes` | `25600` | Hard UTF-8 byte cap (25 KB). |
-| `indexPath` | unset | Path of the ONE index to guard: absolute, or relative to each session's working directory (resolved there by the guard as by recall; the memory page lists only an absolute pin). Without it the guard matches on basename alone, so an unrelated `MEMORY.md` in another project is gated too; set this and only that exact file is. Compared by identity — the file the write lands on, whatever it is called (symlinks and `..` resolved; case-folded on Windows only) — and a path that does not exist yet still has its first write guarded. |
-| `registerSkill` | `true` | Set `false` to keep the cap but skip the runtime skill. |
-| `injectIndex` | `true` | Put the memory index into dsh's runtime context on every step (see above). Set `false` to recall by reading the file instead. |
-| `language` | dsh's | Unset (or empty), the memory follows dsh's language — the one chosen in dsh's Settings → General, else the language of the system dsh runs on (dsh's page, with no choice made, follows the browser's, so on a remote `dsh web` the two can differ); a change applies once dsh restarts. Set it to pin one: `zh` writes the store in Chinese (SKILL.md §1.1): Chinese note names, `## 用户` / `## 反馈` / `## 项目` / `## 参考` headings, `**为什么：**` / `**怎么用：**` labels, and the skill and the injected index in Chinese. Frontmatter keys and `type:` values stay English, so every host still reads the store. The cap's refusals stay English. `zh` and its regional forms (`zh-CN`, `zh-TW`, …) select Chinese; any other string selects `en`. |
-| `companion` | `false` | `true` turns companion mode on (above): three more types for the character's own life, and recall in character. Only the boolean `true` counts. |
-| `audience` | `private` | With companion mode on, `social` turns social mode on (above): only your own conversations get the memory. Any other value is `private`, where every conversation does. Without companion mode it changes nothing. |
-| `skill` | built-in | Replace the skill body with your own markdown — which must then say where the store is itself. |
-## What the guard actually does
-| Call | Decision |
+| `indexName` | `MEMORY.md` | 哪个文件名算索引，不分大小写。 |
+| `maxLines` | `200` | 索引行数上限。 |
+| `maxBytes` | `25600` | 索引字节上限（25 KB）。 |
+| `indexPath` | 不设 | 只认这一个索引：绝对路径，或相对会话目录。不设时，任何项目里叫 `MEMORY.md` 的文件都按索引卡上限；记忆库不在默认位置时也要设它，否则不会自动带上。 |
+| `registerSkill` | `true` | `false`：不注册内置的记忆规则，只留上限。 |
+| `injectIndex` | `true` | `false`：不再每轮带上索引，改由 AI 自己读。 |
+| `language` | 跟随 dsh | `zh`（`zh-CN` 等也算）用中文写记忆（笔记名、`## 用户` 这类标题、**为什么：**/**怎么用：**），其他值用英文。不设就跟 dsh 的语言，改了要重启 dsh。frontmatter 的键和 `type:` 取值始终是英文，别的宿主照样能读。 |
+| `companion` | `false` | `true` 打开大肥鱼模式。 |
+| `audience` | `private` | 大肥鱼模式下设 `social` 打开社交模式。 |
+| `skill` | 内置 | 用你自己的 markdown 换掉内置规则，这时得自己写明记忆库在哪。 |
+## 上限怎么判
+| 情况 | 结果 |
 |---|---|
-| `write` (or `str_replace_editor` `create`) ending within caps | allow |
-| `write`/`create` that GROWS the index past a cap | **deny**, naming the numbers and what to compact |
-| `write`/`create` that SHRINKS or keeps an over-cap index | allow — incremental compaction (210 → 205 → 198) must stay possible |
-| Edit carrying `old_str`/`new_str`: result simulated | judged by the RESULT, same grow/shrink rule as a write — sized before it is built, so a `replace_all` whose result would be too long to build is judged on lower bounds of its bytes and lines |
-| Unsimulable partial (e.g. `insert`) on an over-cap index | **deny**, telling the agent a shrinking whole-file write passes |
-| Unsimulable partial on a healthy index | allow |
-| `read`, `view`, or any unknown tool | allow — recall must never be blocked, even over cap |
-| Any write to any other file | allow — not the guard's business |
-| Missing/unreadable current index on a whole-file write | treated as EMPTY (mirrors the Python guard) — a within-caps write passes, an over-cap first write is refused |
-| Missing/unreadable index on a partial edit | allow — a guard must never block work over a path it cannot read |
-| A FIFO, device, or directory under the index's name | never read — counts as unreadable (a read there would hang or flood the host, which runs guards on its main thread) |
-| An index past the read limit (`min(16 MiB, max(1 MiB, 4 × maxBytes))`) | not read whole: a whole-file write is judged on bytes against the filesystem's size (every shrink passes; its line count is unknown, so lines are not capped there), and an edit passes unmeasured, as on an unreadable index |
-| Malformed execution (no arguments, non-string path/content) | allow — not recognisably a write |
-For measured results, deny only a dimension that is over its cap AND grew past
-the current file. The line count ignores a trailing newline, so an index exactly
-at the cap stays writable. This decision table is pinned by `node --test` in CI.
-Relative paths use the session's `workingDirectory` service when available,
-falling back to the process cwd. Edits match LF-normalised text and preserve the
-file's line endings when sizing the result, including CRLF bytes.
-## Known limits
-- **Unsimulable partial edits can cross the cap from below.** On a readable,
-  already-over-cap index they are denied; use a shrinking whole-file write to
-  compact. Missing/unreadable files and the read-limit exceptions are listed above.
-  Run `engramory_check.py` after index edits and `engramory_doctor.py` periodically.
-- **Coverage is limited to known file tools:** `write`/`edit` with `file_path`,
-  `str_replace`/`insert`, and mutating `str_replace_editor` commands with `path`.
-  Unknown tools pass. **Shell tools, MCP file tools, and external editors bypass
-  the guard.**
-- **Injection finds the stores where the installer puts them.** A store elsewhere
-  (`--memory-root`) needs `indexPath`. The project root is found by dsh's default `.git`
-  marker only (a profile's custom `projectRootMarkers` are not visible to a plugin), and
-  a project store created mid-session can take up to ten seconds to appear. A project
-  store whose real path leaves the project — a symlink out of the checkout — is not
-  read; point `indexPath` at it if that is deliberate. The global store's location comes
-  from `$DSH_HOME`, resolved the way dsh resolves it. What is injected is framed as notes,
-  not instructions, that may be stale; a host without runtime context
-  (no `ctx.systemPrompt.context`) goes without it.
-- **Social mode knows your typing by what dsh's browser client sends.** A program that
-  sends the same request id and time zone as dsh's own page is taken for you, and a
-  browser whose time zone cannot be read leaves your messages unmarked. dsh's terminal,
-  editor (ACP) and SDK clients do not mark them either: with social mode on, only
-  dsh's own window counts.
-- **Some of dsh's messages carry no author.** An answer to the agent's question, a
-  scheduled prompt and a message a slash command adds (`/plan <text>`, `/goal`'s
-  attachments) count as nobody's, and a queued message edited through dsh's API keeps the
-  author it had. On dsh 0.2.1 only the owner can answer, schedule or edit — in dsh's
-  window, or through a program with the owner's login, which can read the store's files
-  through dsh's own file API anyway — and a chat bridge that forwards a command runs it in
-  its own conversation, which its other messages already make someone else's.
-- **A kind of message a later dsh adds counts as someone else's** until this plugin knows
-  it: a conversation of yours may lose the memory, never the other way round.
-- **The memory page reads the disks as they answer.** On a filesystem whose directory
-  entries carry no type (some network mounts), Node stats each listed entry on dsh's main
-  thread, at most 2000 per folder; and a listing stuck on a drive that never answers keeps
-  reporting a timeout until it does, rather than starting another that would get stuck too.
-- **What the memory page opens is checked by path.** dsh's opener takes a path, which it
-  resolves once more before the desktop opens it; a process changing a store's files at
-  that very moment could still redirect what the desktop opens — as with dsh's own opener
-  for any workspace file — though not to a link the page saw.
-- dsh's plugin API can change. The plugin uses `ctx.tools.guard()` and reactive
-  `ctx.inject()` children for the skill registry, the session working directory, the
-  prompt registry, and — in social mode — dsh's session projections, where it folds
-  who has written in each session; a compatible-release declaration needs recorded host
-  evidence, not just unit tests. The recorded end-to-end runs cover the cap, the skill
-  and the injected index; companion mode, social mode, the settings page and the memory page were checked by hand on
-  a real dsh (0.2.1-rc.5) — messages typed in dsh's window, sent by `dsh headless` and by
-  a program through dsh web's API, a save through the page, and the memory page's listing,
-  a switch saved from it and a note opened from it — but are not part of that record yet.
-## License
-MIT — see the [Engramory repository](https://github.com/tinqiao-oss/engramory).
+| 写完后索引在上限内 | 放行 |
+| 写入让索引变大，并超过上限 | **拒绝**，报出数字，提示压缩什么 |
+| 索引已超限，写入让它变小或不变 | 放行（压缩可以一步步来：210 → 205 → 198） |
+| 带 `old_str`/`new_str` 的编辑 | 先算出改完的结果，再按上面三条判 |
+| 算不出结果的局部编辑（如 `insert`） | 索引已超限时拒绝，否则放行 |
+| 索引不存在、读不到，或不是普通文件 | 整文件写入当它是空的来判；局部编辑放行 |
+| 索引大到超过读取上限（`min(16 MiB, max(1 MiB, 4 × maxBytes))`） | 不整份读：整文件写入只按字节比大小；局部编辑放行 |
+| 读文件、写别的文件、不认识的工具或参数 | 放行；索引超限也不挡读取 |
+行数和字节分开判：只拒绝既超上限、又比原来变大的那一项，所以字节变少但行数涨过上限的写入照样被拒。行数不算末尾换行，正好卡在上限的索引还能写。这张表由 CI 里的 `node --test` 固定。
+## 已知限制
+- **只拦 dsh 自带的文件工具**（`write`、`edit`、`str_replace_editor` 等）。shell、MCP 文件工具和外部编辑器写入都绕过上限；改完索引跑 `engramory_check.py`，定期跑 `engramory_doctor.py`。
+- **记忆库只在默认位置自动找到。** 放在别处，或项目库是指向项目外的链接，要设 `indexPath`；项目根只按 `.git` 认；会话中途新建的项目库最多十秒后才出现。
+- **社交模式靠 dsh 窗口发来的信息认你。** 除了接入插件标明的主人消息，只有 dsh 自己窗口里打的字算你的；浏览器读不出时区时也认不出。dsh 以后新加的消息种类，插件认识之前都算别人的：你的会话可能拿不到记忆，但不会把记忆漏给别人。
+- **记忆页打开文件前按路径检查。** dsh 的打开功能拿到路径后还会再解析一次，如果恰好在这一刻有程序改动记忆库里的文件，桌面最终打开的可能是别的东西（dsh 自己打开工作区文件也是这样）。
+- **实验性功能**：大肥鱼模式、社交模式、设置页和记忆页在小版本里也可能改。
+## 版本
+本包和 Engramory 用同一个版本号：`dsh-engramory@X.Y.Z` 就是仓库的 `vX.Y.Z`。上限判定（上面那张表）和实验性功能以外的配置，只在主版本做不兼容改动。详见[版本规则](https://github.com/tinqiao-oss/engramory#版本规则)，改动历史见 [CHANGELOG](../../../CHANGELOG.md)。
+## 许可
+MIT，见 [Engramory 仓库](https://github.com/tinqiao-oss/engramory)。

package/index.js CHANGED Viewed

@@ -2090,7 +2090,7 @@ function languageOf(value) {
 /**
  * Everything this plugin says to the model, per language. The two must state the same
- * rules — adapters/dsh/plugin/test.js asserts each rule in both — and the store
+ * rules — adapters/dsh/plugin/index.test.js asserts each rule in both — and the store
  * labels in `labels` must be the ones the skill tells the model to look for.
  */
 const TEXT = {

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "dsh-engramory",
-  "version": "0.3.0",
-  "description": "Curated file-based long-term memory for DeepSeek Harness — human-readable markdown notes, one plain-file store shared across hosts (git-ignored when it lives inside a project repo), and a deterministic index cap enforced by ctx.tools.guard()",
+  "version": "1.0.1",
+  "description": "DeepSeek Harness 的长期记忆插件：AI 记住的东西存成普通 markdown 文件，每轮自动带上记忆索引，索引有大小上限。",
   "keywords": [
     "dsh-plugin",
     "deepseek-harness",
@@ -59,13 +59,14 @@
     "README.md",
     "LICENSE"
   ],
+  "author": "tinqiao-oss",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/tinqiao-oss/engramory.git",
     "directory": "adapters/dsh/plugin"
   },
-  "homepage": "https://github.com/tinqiao-oss/engramory/tree/master/adapters/dsh#readme",
+  "homepage": "https://github.com/tinqiao-oss/engramory/tree/master/adapters/dsh/plugin#readme",
   "bugs": {
     "url": "https://github.com/tinqiao-oss/engramory/issues"
   },

package/README.zh-CN.md DELETED Viewed

@@ -1,196 +0,0 @@
-[English](README.md) | **简体中文**
-# dsh-engramory
-[![dsh-xray](https://img.shields.io/endpoint?url=https%3A%2F%2Funstone.github.io%2Fdsh-xray%2Fbadge%2Ftinqiao-oss__engramory.json)](https://unstone.github.io/dsh-xray/registry.html#tinqiao-oss__engramory)
-给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 用的**策展式、文件式**长期记忆 ——
-纯 markdown 笔记,随便什么工具都能打开;跨宿主共享遵循
-[一个写入者、多个只读者](../../reader/README.md),索引守卫会在匹配的文件工具写入前检查上限。(记忆库若位于某个项目的 git 仓库内,必须 git-ignore ——
-记忆里带着本机独有的细节,见 SKILL.md §1。给记忆库单独开一个*私有仓*则完全可以。)
-隶属于 [Engramory](https://github.com/tinqiao-oss/engramory)。
-## 已经有 `AGENTS.md` 常驻块了,为什么还要插件
-那个常驻块承载了纪律。但有三件事它做不到:
-**索引已经在上下文里 —— 召回不用再读文件。** 插件在每一步都把记忆索引放进 dsh 的运行时
-上下文:项目库(`<项目>/.engramory-memory/MEMORY.md`,取会话目录到 git 根目录之间离会话最近的那个,和 dsh 找项目 `AGENTS.md` 的方式一致)和全局库
-(`$DSH_HOME/.engramory-memory/MEMORY.md`,未设 `$DSH_HOME` 时为 `~/.dsh`)—— 正是
-`tools/engramory_init.py dsh` 建库的位置;设了 `indexPath` 时则只注入它。内容一变就重新读取,
-所以写入后下一轮请求就能看到;超过上限的行会被截掉,并提示模型去压缩。用
-`injectIndex: false` 关闭。
-**匹配工具的上限由守卫确定性执行。** `ctx.tools.guard()` 提供同步、**单调**的否决:
-守卫一旦返回理由,后续监听器就不能再放行。索引的增长受配置上限约束,无需依赖 agent
-记得运行校验器。请用 **`dsh-engramory >= 0.2.7`**;
-[PORTING.md](../../../PORTING.md) 记录各宿主是否已有守卫实现,
-[CHANGELOG.md](../../../CHANGELOG.md) 保存版本历史。
-**协议随插件一起到达。** skill 是在运行时通过 dsh 的 skill 注册表注册的 —— 走一个响应式的
-`ctx.inject(['skills'], …)` 子上下文,所以没有注册表的 profile 照样拿到上限,而注册表晚一步
-挂载的 profile 也照样拿得到 skill。这意味着它**不依赖**把文件放进 dsh 扫描的那五个 skill 根
-目录之一 —— 那条路很容易在细微处放错,而一旦放错就是**静默失败**。
-## 安装
-零依赖 ESM,不需要构建;需要 Node.js 18+,dsh 的插件命令还要求 PATH 中有 `pnpm`。
-```sh
-dsh plugin --profile <名字> add dsh-engramory
-```
-确切的兼容版本以 [`package.json`](package.json) 的 `dsh.compatibility.dshReleases` 为准,
-由 [`results.json`](../../../tests/dsh_e2e/results.json) 的记录支持。
-验证其他版本请看[端到端验证指南](../../../tests/dsh_e2e/README.md)。
-这个包自带 `dsh.bundle` manifest 指向它自己的 `cordis.patch.yml`,所以那一行
-会被自动插进 profile 的插件树里 —— 不需要手改配置。要改默认值,请在你自己 profile 的 patch
-层里**按 id 修改那一行已存在的配置**,**不要**再写一个 `- insert:`(insert 永远是追加,你会得到
-两行 engramory,而原来那行的上限依旧在生效):
-```yaml
-- id: engramory
-  config:
-    indexName: MEMORY.md
-    maxLines: 200
-    maxBytes: 25600
-```
-一次 patch 会**整体替换**目标行的 `config`,所以你想保留的键要逐个列全。
-只装插件时,记忆就是一个全局库 `$DSH_HOME/.engramory-memory/`(`$DSH_HOME` 默认是 `~/.dsh`):skill 会告诉 AI 它在哪,AI 第一次保存时自己建好。项目也可以有自己的库——项目根目录下的 `.engramory-memory/`——但只能由你来建:安装器会建好并加进 .gitignore(`python tools/engramory_init.py dsh --project-root <项目>`)。AI 绝不自己建项目库;有项目库时,只在这个项目成立的事记在那里,其余的仍记在全局库。安装器还会把常驻块写进 `AGENTS.md`(`python tools/engramory_init.py dsh --install-skill`)。
-卸载:
-```sh
-dsh plugin --profile <名字> remove dsh-engramory
-```
-## 大肥鱼模式(陪伴模式)
-给用户聊天陪伴的角色用——社区里的大肥鱼,或任何人设。写 `companion: true` 打开,或者在设置页(见下文)里打开「大肥鱼模式」开关。
-- **再加三类,记角色自己的人生**([SKILL.md §2.2](../../../SKILL.md)):`moment`(经历)——和用户一起经历过的事,带日期,默认保留,索引写满时按月收进归档;`upcoming`(约定)——用户生活里将要发生的事,过了日子会问起,问到结果才改写成一条经历,绝不自己编结果;`self`(我自己)——角色自己的变化,比如外号,原地更新,不归档。经历和我自己只有用户说忘掉才删。其余四类意思不变。
-- **用角色口吻回忆。** AI 会被告知:它为你扮演角色时,用户的每句话,包括打招呼,都可能该想起点什么;记住了什么、没记上什么,都用角色口吻说,不提文件和工具。
-- **人设预设决定它能拿记忆做什么。** 大肥鱼模式或社交模式打开时,会话收到的内容——记忆和陪伴规则,或者社交模式的那条说明——是*必需*的运行时上下文,所以即使预设关掉了可选上下文(dsh-persona 的 `includeRuntimeContext: false`,dsh 自带的 `minimal` 预设就是这样),它也照样送到。保存记忆是另一回事:预设得带上 dsh 的文件工具和 skill 工具,角色才能照 skill 的格式写笔记。只有 shell 的预设读得到给它的记忆,但它写的东西绕过守卫。
-## 社交模式
-大肥鱼模式里的一个选项,给"别人也能跟它聊"的角色用——比如经接入插件接到 QQ、微信、抖音、B 站的角色。打开大肥鱼模式后,在设置页的「记忆权限」里选「社交」,或者写 `audience: social`。默认的「专属」让每个会话都能用记忆:只有你自己跟这个 dsh 聊的话,保持专属就行。大肥鱼模式没打开时,`audience` 不起作用。
-- **只有你本人的会话拿得到记忆。** 你在 dsh 自己的窗口(桌面版或 `dsh web`)里亲手发过消息、而且没有别人在里面说过话的会话,才算你的。dsh 给每条用户消息都盖了来源章,它的浏览器界面发消息时会带上请求编号和浏览器的时区,靠这个认出是你在界面里打的字。其余一律算别人的:
-  - 接入插件转进来的消息,不管用的是它自己的章(`plugin:<包名>`,dsh-onebot 就是这样;或者别的任何 dsh 自己不用的章)还是 dsh 的 `user` 章——除非插件按下面的标准标明是你;
-  - 通过 dsh web 接口调用的外部程序、`dsh headless`、编辑器或终端客户端;
-  - 自动化任务或插件开的会话,在你亲手发消息之前;
-  - dsh 自己标明不是主人的调用方。
-  一段会话只要有别人说过话,就一直算别人的,你之后再在里面发消息也一样:之前放进去的记忆还留在对话记录里。dsh 自己加的消息(运行时上下文、技能、压缩、agent 之间的消息)不影响判断。
-- **别人的会话拿不到记忆:** 没有索引,只收到一条说明,也拿不到记忆库的完整路径(社交模式下,所有会话都读的 skill 里不写完整路径;你本人的会话会在运行时上下文里得知它),而且文件工具只能指名文件:目录一律拒绝(所以 grep、glob 和目录查看都不行——任何目录树里都可能藏着记忆库),指向记忆库的路径不管怎么写、怎么链接也一律拒绝,还不存在的记忆库也算,所以没人能替你预先种下一个。子 agent 在它的父会话(每次都重新查在线的父会话)算你的、而且没有别人直接给它发过消息时,才算你的;分叉出来的会话按它自己的记录判断,继承来的那部分也算。没有会话的调用、没有会话投影服务的 dsh、网络路径,都按别人算。
-这只是让用户的记忆不经 dsh 自带文件工具的路径进入别人的上下文。它**不是**安全边界:shell 工具能读任何文件,同一账户下的另一个配置也照样读得到记忆库的文件。要让别人真正碰不到,得靠文件系统权限或沙箱。
-### 给接入插件作者:标明消息是谁发的
-社交模式打开时,接入插件转进来的每条消息都算别人的。想让主人自己的聊天(比如主人和角色的 QQ 私聊)用上记忆,就在消息的来源章上加一个 `speaker`:
-```js
-agent.followup(createUserMessage({
-  content: [{ type: 'text', text }],
-  source: { kind: 'plugin:your-bridge', speaker: { role: 'owner' } },
-}))
-```
-| `speaker.role` | 含义 |
-|---|---|
-| `owner` | dsh 的主人发的:来自用户在你插件里设为"自己"的那个账号。 |
-| `guest` | 别人发的——和不写 `speaker` 一样。 |
-| `none` | 不是人发的:你插件自己的汇报、提醒或通知。它不会让主人的会话变成别人的。 |
-只有确认来自主人自己账号的消息才标 `owner`。群聊里只要有别人说话,那个会话就一直算别人的。dsh 会把来源章里它不认识的字段原样存进会话记录,所以重启后标注还在。
-只通过 dsh web 接口和 dsh 交互的程序设不了来源章,它发的消息都算别人的——除非它发消息时带了 `clientTimeZone`:那样 dsh 记下的章和它自己页面发的一模一样,消息会被当成主人的。替别人转发消息的程序不要带 `clientTimeZone`。
-## 设置页
-在 dsh 的**插件**页里打开「Engramory 记忆」:它的页面上设置大肥鱼模式(一个开关)以及打开时的记忆权限(专属或社交)、索引上限。记忆用什么语言写跟随 dsh 自己的语言(见下文 `language`)。
-保存走 dsh 自己的配置编辑服务:它校验整份配置,写进你这个配置的 `cordis.patch.yml`,再用新配置重新加载插件——校验不过就保持文件原样。如果你打开页面之后设置在别处被改过,这次保存会被拒绝,页面重新读取。改回默认值的设置会删掉对应的覆盖,而不是把默认值钉死。其他字段(`indexName`、`indexPath` 等)仍留在文件里。
-只有你能访问这一页用的接口——你已登录的浏览器,或者带着你登录凭据的程序:没有凭据的请求 dsh 回 401,跨站请求回 403,所以 agent 没法调用它关掉社交模式。没有配置编辑服务的 dsh 上,这一页只读。大肥鱼模式和记忆权限在记忆页(见下文)顶部也有。
-## 记忆页
-dsh 左侧栏多一个「记忆」入口。点开的页面列出召回能用到的记忆库——`$DSH_HOME` 下的全局库,以及每个工作区的项目库(找法和召回一样);设了 `indexPath` 时只列那个索引所在的目录——每个库显示索引相对上限的大小、按类型分组的笔记名字,以及归档。页面只读,只显示名字,不显示笔记正文:点名字会用电脑上的默认程序打开那条笔记,走的是 dsh 自带的打开功能,在运行 dsh 的那台机器上打开。dsh 说那台机器上打不开时(比如经 SSH 访问),名字就只是文字,页面会写出文件在哪。「打开索引」同样用默认程序打开索引;「打开文件夹」在文件管理器里显示索引(资源管理器和访达会在记忆库文件夹里选中它;Linux 上是打开那个文件夹),所以没有索引的记忆库没有这个按钮。页面顶部的大肥鱼模式和记忆权限拨了就保存;它们是什么意思、索引上限,见设置页。
-列出的东西有上限——每个文件夹最多看 2000 个条目、最多 200 个工作区、总共 5000 个名字——而且不去看网络共享路径(`\\server\share\…`)上的工作区,也不去看文件夹后来被换成指向别处的链接的工作区。本身是链接的笔记不列出;打开的是按名字在记忆库里重新找到的笔记或索引,这时它若已变成链接就拒绝。相对路径的 `indexPath` 跟着每个会话的目录走,所以页面列不出来。页面用的接口和设置页一样只有你能访问。
-## 配置
-| 字段 | 默认值 | 含义 |
-|---|---|---|
-| `indexName` | `MEMORY.md` | 被当作记忆索引的文件名(不区分大小写;`file_path` 与 `str_replace_editor` 的 `path` 都会检查)—— 看写入时用的文件名,或写入实际落到的那个文件的文件名,所以换了名字的 symlink 也会被拦。空值或非字符串会回退到默认值,不是单纯文件名的(含路径分隔符、`:`,或是 `.`、`..`)也回退。 |
-| `maxLines` | `200` | 硬性行数上限。非正数或非有限值回退到默认值。 |
-| `maxBytes` | `25600` | 硬性 UTF-8 字节上限(25 KB)。 |
-| `indexPath` | 未设置 | 要守护的**那一个**索引的路径:绝对路径,或相对每个会话工作目录的路径(守卫和召回都按会话目录解析;记忆页只列绝对路径的固定索引)。不设它时,守卫只按文件名匹配,于是**别的项目里一个无关的 `MEMORY.md` 也会被拦**;设了它就只有这个确切的文件会被守。比较走的是身份而非拼写 —— 看写入实际落到的那个文件,不管它叫什么名字(symlink 与 `..` 都会解析;仅在 Windows 上折叠大小写),而且即使文件尚不存在,它的第一次写入照样受守护。 |
-| `registerSkill` | `true` | 设为 `false` 则保留上限、但跳过运行时 skill。 |
-| `injectIndex` | `true` | 每一步都把记忆索引放进 dsh 的运行时上下文(见上文)。设为 `false` 则改回由 agent 读文件召回。 |
-| `language` | 跟随 dsh | 不设(或留空)时跟随 dsh 的语言——你在 dsh「设置 → 通用」里选的那个,没选过就用运行 dsh 那台机器的系统语言(dsh 页面没选过时看的是浏览器语言,远程用 `dsh web` 时两者可能不同);改了要重启 dsh 才生效。设了就固定:`zh` 用中文写记忆库(SKILL.md §1.1):中文笔记名,`## 用户` / `## 反馈` / `## 项目` / `## 参考` 标题,`**为什么：**` / `**怎么用：**` 标签,skill 和注入的索引也换成中文。frontmatter 的键和 `type:` 取值保持英文,所以各宿主照样能读。超上限的拒绝提示仍是英文。`zh` 及其地区写法(`zh-CN`、`zh-TW` 等)选中文;其他字符串一律按 `en`。 |
-| `companion` | `false` | 设为 `true` 打开大肥鱼模式(见上文):多记三类角色人生,用角色口吻回忆。只认布尔值 `true`。 |
-| `audience` | `private` | 大肥鱼模式打开时,设为 `social` 打开社交模式(见上文):只有你本人的会话拿得到记忆。其他取值一律按 `private`(专属),每个会话都能用记忆。大肥鱼模式没打开时不起作用。 |
-| `skill` | 内置 | 用你自己的 markdown 替换 skill 正文——这时记忆库在哪也得由它自己写明。 |
-## 守卫到底做了什么
-| 调用 | 判决 |
-|---|---|
-| `write`(或 `str_replace_editor` 的 `create`)且结果在上限内 | 放行 |
-| `write`/`create` 会让索引**增长**并越过上限 | **拒绝**,并报出具体数字和该压缩什么 |
-| `write`/`create` 让一个已超限的索引**缩小或持平** | 放行 —— 增量压缩(210 → 205 → 198)必须走得通 |
-| 带 `old_str`/`new_str` 的 edit:结果可模拟 | 按**结果**判定,增长/缩小规则与整文件写入相同 —— 先算大小再构建,结果长到没法构建的 `replace_all` 按字节与行数的下界判定 |
-| 无法模拟的部分写入(如 `insert`)落在已超限的索引上 | **拒绝**,并告诉 agent:缩小的整文件写入是放行的 |
-| 无法模拟的部分写入落在健康的索引上 | 放行 |
-| `read`、`view`,以及任何未知工具 | 放行 —— 哪怕已超限,召回也绝不能被挡住 |
-| 对任何其他文件的写入 | 放行 —— 不关守卫的事 |
-| 整文件写入时当前索引缺失/读不到 | 视为**空**(与 Python 版守卫一致)—— 上限内的写入放行,而首次就超限的写入被拒 |
-| 部分编辑时索引缺失/读不到 | 放行 —— 守卫绝不能因为一个自己读不了的路径而挡住工作 |
-| 用索引名字的 FIFO、设备或目录 | 一律不读,按读不到处理(在那里读会把宿主卡死或撑爆内存,而宿主在主线程上跑守卫) |
-| 超过读取上限的索引(`min(16 MiB, max(1 MiB, 4 × maxBytes))`) | 不整份读入:整文件写入按文件系统报告的大小比较字节(缩小一律放行;行数未知,这时不卡行数),edit 无法测量,按读不到的索引处理,放行 |
-| 畸形的执行(没有 arguments、路径/内容不是字符串) | 放行 —— 它压根不像一次写入 |
-对可测量的结果,只拒绝某个维度既超出上限、又比当前文件增长的写入。行数统计忽略结尾换行,
-所以正好卡在上限的索引仍然可写。此判决表由 CI 中的 `node --test` 固定验证。
-相对路径优先通过会话的 `workingDirectory` 服务解析,服务不存在时退回进程 cwd。
-edit 在统一为 LF 的文本上匹配,计算结果大小时保留文件原有换行,包括 CRLF 的字节数。
-## 已知限制
-- **无法模拟的部分编辑可能从上限之下直接越界。** 若索引可读且已经超限,则拒绝这种编辑;
-  可以用缩小的整文件写入来压缩。文件缺失、不可读和超过读取上限的例外见上表。
-  编辑索引后运行 `engramory_check.py`,定期运行 `engramory_doctor.py`。
-- **只覆盖已知文件工具:**使用 `file_path` 的 `write`/`edit`、`str_replace`/`insert`,
-  以及使用 `path` 的 `str_replace_editor` 修改命令。未知工具放行。
-  **Shell 工具、MCP 文件工具和外部编辑器都绕过守卫。**
-- **注入只在安装器建库的位置找记忆库。** 库放在别处(`--memory-root`)时要设 `indexPath`。
-  项目根只按 dsh 默认的 `.git` 标记判断(profile 里自定义的 `projectRootMarkers` 插件看不到);
-  会话中途新建的项目库最多要十秒才会出现。真实路径跑出项目之外的项目库(比如指向仓库外的符号
-  链接)不会被读取;如果是有意为之,请把 `indexPath` 指向它。全局库的位置来自 `$DSH_HOME`,
-  解析方式与 dsh 自己一致。注入的内容被标注为"笔记而非指令、可能过时";没有运行时上下文
-  (`ctx.systemPrompt.context`)的宿主则不注入。
-- **社交模式靠 dsh 浏览器界面发来的信息认出你。** 外部程序如果带上和 dsh 页面一样的请求编号和时区,会被当成你;浏览器读不出时区时,你发的消息也不会被认出。dsh 的终端、编辑器(ACP)和 SDK 客户端发的消息同样不带这些信息:社交模式打开时,只有 dsh 自己的窗口算数。
-- **dsh 有些消息不带发送者。** 对 AI 提问的回答、定时任务发起的消息、斜杠命令附带的消息(`/plan <内容>`、`/goal` 的附件)都算"没人发的";通过 dsh 接口编辑过的排队消息,沿用原来的发送者。在 dsh 0.2.1 上,回答、定时、编辑只有主人做得了——在 dsh 窗口里,或者通过登录了主人身份的程序,而这样的程序本来就能通过 dsh 自己的文件接口读到记忆库;接入插件转发的命令跑在它自己的会话里,那个会话已经因为它的其他消息算别人的了。
-- **以后的 dsh 新加的消息种类,在本插件认识它之前都算别人的:** 你自己的会话可能因此拿不到记忆,但不会反过来把记忆漏给别人。
-- **记忆页按磁盘的响应来读。** 在目录条目不带类型的文件系统上(部分网络挂载),Node 会在 dsh 主线程上逐个 stat 列出的条目,每个文件夹最多 2000 个;卡在永不响应的盘上的那次读取会一直报超时,直到它结束,而不是再起一次同样会卡住的读取。
-- **记忆页打开什么是按路径检查的。** dsh 的打开功能接收的是路径,它在交给桌面打开前会再解析一次;如果恰好在那一刻有进程改动记忆库里的文件,桌面最终打开的东西仍可能被换掉——dsh 自己打开任何工作区文件也是如此——但换不成页面检查时看到的链接。
-- dsh 的插件 API 可能变化。本插件使用 `ctx.tools.guard()` 和响应式 `ctx.inject()`
-  子上下文,分别接入 skill 注册表、会话工作目录、提示词注册表,以及(社交模式下)dsh 的
-  会话投影,在那里累计每个会话里谁说过话;兼容声明需要真实宿主的运行记录,不能只凭单元测试。
-  记录下来的端到端运行覆盖上限、skill 和注入的索引;大肥鱼模式、社交模式、设置页和记忆页已在真实 dsh
-  (0.2.1-rc.5)上手动验证过——在 dsh 窗口里打字、用 `dsh headless` 和外部程序经 dsh web
-  接口发消息、在设置页里保存,以及记忆页的列表、在记忆页上拨开关保存、从记忆页打开笔记——但还不在那份记录里。
-## 许可
-MIT —— 见 [Engramory 仓库](https://github.com/tinqiao-oss/engramory)。