dsh-engramory 1.0.6 → 1.0.8

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
  1. package/README.en.md +242 -228
  2. package/README.md +141 -135
  3. package/client.js +103 -1
  4. package/index.js +169 -4
  5. package/package.json +79 -79
package/README.en.md CHANGED
@@ -1,228 +1,242 @@
1
- [简体中文](README.md) | **English**
2
-
3
- # dsh-engramory
4
-
5
- [![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)
6
-
7
- Long-term memory for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
8
- (dsh). What the AI remembers is kept as plain markdown files you can open and edit
9
- at any time. It is the dsh build of [Engramory](https://github.com/tinqiao-oss/engramory),
10
- which is general-purpose agent memory: Claude Code, Codex and others can use the same store.
11
-
12
- ![The memory page](https://raw.githubusercontent.com/tinqiao-oss/engramory/master/adapters/dsh/plugin/screenshots/memory-page.png)
13
-
14
- ## What it does
15
-
16
- - **The memory index rides along on every step.** The index, `MEMORY.md`, lists the
17
- notes by name. The plugin puts it into dsh's context on every step, so the AI knows
18
- what it has saved without reading a file first, and opens a note when it needs the
19
- detail. A write shows up on the next request; whatever is past the cap is left
20
- out, and the AI is told to compact.
21
- - **The index has a hard cap.** 200 lines / 25 KB by default. When the AI writes the
22
- index with dsh's file tools and the plugin can work out the result, a write that
23
- would grow it past the cap is refused before it happens, and the AI is told to
24
- compact; compaction still passes. Details in [How the cap decides](#how-the-cap-decides).
25
- - **The rules come with it.** What to save, how, and when to clean up: the rules
26
- (a skill) are registered by the plugin, with no files to install.
27
- - **A Memory page in the sidebar.** Read-only; it lists the notes by name and opens
28
- one in your computer's default app, with a check-up that flags broken links in the
29
- index and notes left out of it.
30
-
31
- ## Install
32
-
33
- Needs Node.js 18+ and `pnpm` on PATH (dsh's plugin command uses it). In dsh's desktop
34
- app you can also search for `dsh-engramory` on the Plugins page.
35
-
36
- ```sh
37
- dsh plugin --profile <name> add dsh-engramory
38
- ```
39
-
40
- To uninstall, use `remove` instead of `add`. Compatible dsh releases are listed in
41
- `dsh.compatibility.dshReleases` in [`package.json`](https://github.com/tinqiao-oss/engramory/blob/master/adapters/dsh/plugin/package.json); an unlisted release
42
- is unverified.
43
-
44
- **Where the memory lives:**
45
-
46
- - **The global store**, `~/.dsh/.engramory-memory/` (under `$DSH_HOME` when it is set).
47
- With the plugin alone this is the only store; the AI creates it on its first save.
48
- - **A project store** (optional), `.engramory-memory/` in a project's root, is created
49
- by you only: run `python tools/engramory_init.py dsh --project-root <project>` from
50
- the Engramory repo, which also git-ignores it. Where one exists, what holds only in
51
- that project goes there; everything else stays in the global store.
52
-
53
- Only one AI may write a store; two writers overwrite each other. To share it, let the
54
- others read it only: see [one writer, many readers](https://github.com/tinqiao-oss/engramory/blob/master/adapters/reader/README.md). Memories are plain text and carry machine-local detail. Inside a project's git repo
55
- the store must be git-ignored; a dedicated private repo for the store is fine.
56
-
57
- **Without the plugin:** `python tools/engramory_init.py dsh --install-skill` writes the
58
- rules into `$DSH_HOME/AGENTS.md`, installs the skill in `$DSH_HOME/skills/engramory/`
59
- (`$DSH_HOME` defaults to `~/.dsh`) and creates the global store. The AI still keeps memory, but reads the index itself, and
60
- the cap holds only if it runs `engramory_check.py` after each write.
61
-
62
- ## Companion mode (大肥鱼模式)
63
-
64
- For a character you chat with: the community's 大肥鱼, or any persona. Turn on the
65
- companion switch on the settings page, or set `companion: true`.
66
-
67
- ![The memory page in companion mode](https://raw.githubusercontent.com/tinqiao-oss/engramory/master/adapters/dsh/plugin/screenshots/companion-mode.png)
68
-
69
- - **Three more types for the character's own life** ([SKILL.md §2.2](https://github.com/tinqiao-oss/engramory/blob/master/SKILL.md)):
70
- `moment`, something you shared, with its date, folded into a monthly archive when
71
- the index fills; `upcoming`, something coming up in your life, asked about once its
72
- date passes and rewritten as a moment once you say how it went; `self`, a change in
73
- the character itself, such as a nickname. A moment or self note is deleted only when
74
- you ask it to forget.
75
- - **Recall in character.** Even a greeting may call for recall, and what it remembered,
76
- or failed to save, is told in the character's voice, without naming files or tools.
77
- - **The persona preset needs the file tools.** The memory arrives even under a preset
78
- that turns optional context off (dsh's `minimal`, for one). To save notes, though, the
79
- preset needs dsh's file tools and the skill tool; a preset with only a shell reads the
80
- memory, and its writes go past the cap.
81
-
82
- ## Social mode
83
-
84
- A choice inside companion mode, for a character other people can talk to as well, such
85
- as one wired to QQ, WeChat, Douyin or Bilibili through a bridge plugin. Choose *Social*
86
- under *Memory access* on the settings page, or set `audience: social`. If only you talk
87
- to this dsh, keep the default, *Private*.
88
-
89
- With it on, **only your own conversations get the memory**: one is yours when you have
90
- typed in it in dsh's own window (the desktop app or `dsh web`) and nobody else has.
91
- A subagent goes with its parent. Messages from a bridge plugin (unless it marks them as
92
- the owner's, below), `dsh headless`, other programs, and terminal or editor clients
93
- count as someone else's. Once anyone else has written in a conversation it stays
94
- theirs, and the memory already put into it stays in its history.
95
-
96
- Someone else's conversation gets no index and is not told where the store is; dsh's
97
- file tools there may name files only (every directory is refused), and any path into
98
- a store is refused however it is spelled. This is **not** a security boundary: a shell
99
- tool reads any file, and another profile on the same account can read the store too.
100
- Real isolation needs filesystem permissions or a sandbox. A custom `skill` (see
101
- [Configuration](#configuration)) reaches every conversation as written, someone else's
102
- included, so if it says where the store is, they are told too.
103
-
104
- ### For bridge authors
105
-
106
- With social mode on, every message a bridge submits counts as someone else's. For a
107
- message from the owner's own account (their private QQ chat with the character, say),
108
- put a `speaker` on its source:
109
-
110
- ```js
111
- agent.followup(createUserMessage({
112
- content: [{ type: 'text', text }],
113
- source: { kind: 'plugin:your-bridge', speaker: { role: 'owner' } },
114
- }))
115
- ```
116
-
117
- | `speaker.role` | Meaning |
118
- |---|---|
119
- | `owner` | The owner wrote it: it comes from the account the user set as theirs in your bridge. |
120
- | `guest` | Someone else wrote it, the same as no `speaker` at all. |
121
- | `none` | Nobody wrote it: your plugin's own report, reminder or notice. It does not make the owner's conversation someone else's. |
122
-
123
- In a group chat, add `chat: 'group'` (`{ role: 'owner', chat: 'group' }`): the whole
124
- group reads the reply, so the conversation counts as someone else's even while only the
125
- owner has spoken in it. A private chat may say `chat: 'private'` or leave it out; any
126
- other value counts as a group. A group conversation stays someone else's once anyone else in it
127
- speaks. A program that talks to dsh only through dsh web's API cannot set a source, so its messages count
128
- as someone else's; if it sends `clientTimeZone` with a prompt it is taken for the
129
- owner, so a program forwarding other people's messages must leave it out.
130
-
131
- ## Settings page and memory page
132
-
133
- ![The settings page](https://raw.githubusercontent.com/tinqiao-oss/engramory/master/adapters/dsh/plugin/screenshots/settings-page.png)
134
-
135
- - **Settings page:** on dsh's *Plugins* page, open *Engramory memory* to set companion
136
- mode, memory access and the index cap. Saving goes through dsh's own profile editor,
137
- which writes your profile's `cordis.patch.yml` and reloads the plugin. Only you, signed
138
- in, can call it, so an agent cannot use it to switch social mode off.
139
- - **Memory page:** *Memory* in the sidebar. It lists the global store and each
140
- workspace's project store (with an absolute `indexPath`, that store alone; with a
141
- relative one, none), with each index's size against the cap, its notes' names
142
- by type, and its archive. Each store comes with a check-up: the index's links to
143
- files that are not there, the notes not in the index (recall starts from the index, so
144
- the AI will not find them unless another note links to them), and notes with no type.
145
- It goes by file names and the index's links alone, never through a symbolic link, and
146
- is skipped when the index is over the cap, there is too much to check, or a file cannot
147
- be read; `engramory_doctor.py` still does the full check.
148
- Read-only, never a note's text; a name, *Open the index* and
149
- *Open the folder* open on the machine dsh runs on; a machine with no desktop (a
150
- headless server, a session over SSH) shows none of them. The switches at the top
151
- (companion mode, and memory access once it is on) save as you flip them.
152
-
153
- ## Configuration
154
-
155
- Settings the page does not cover go in your profile's `cordis.patch.yml`. Patch the
156
- EXISTING row by id; a second `- insert:` adds another engramory row and leaves the old
157
- caps in force. A patch replaces the row's whole `config`, so list every key you keep:
158
-
159
- ```yaml
160
- - id: engramory
161
- config:
162
- indexName: MEMORY.md
163
- maxLines: 200
164
- maxBytes: 25600
165
- ```
166
-
167
- | Field | Default | Meaning |
168
- |---|---|---|
169
- | `indexName` | `MEMORY.md` | The file name treated as the index. The cap matches it case-insensitively; putting the index into context needs the exact name on a case-sensitive filesystem (Linux, say). |
170
- | `maxLines` | `200` | Line cap for the index. |
171
- | `maxBytes` | `25600` | UTF-8 byte cap for the index (25 KB). |
172
- | `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. |
173
- | `registerSkill` | `true` | `false` skips the built-in rules; the cap and the index in context stay. |
174
- | `injectIndex` | `true` | `false` stops putting the index into context; the AI reads it instead. |
175
- | `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 string is English; a value that is not a string, or is empty, counts as unset. 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. |
176
- | `companion` | `false` | `true` turns companion mode on. |
177
- | `audience` | `private` | With companion mode on, `social` turns social mode on. |
178
- | `skill` | built-in | Your own markdown in place of the built-in rules; it must then say where the store is. In social mode, others' conversations see it too. |
179
-
180
- ## How the cap decides
181
-
182
- | Case | Decision |
183
- |---|---|
184
- | The index ends within the caps | allow |
185
- | The write grows the index past a cap | **deny**, with the numbers and what to compact |
186
- | 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) |
187
- | A partial edit whose result can be worked out: `edit` (`old_string`/`new_string`), `str_replace_editor`'s replace (`old_str`/`new_str`) and `insert` | its result is worked out first, then judged as above; each tool from the arguments it uses and the way it matches |
188
- | A partial edit whose result cannot be worked out (arguments missing or not recognised) | deny on an over-cap index, else allow |
189
- | 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 |
190
- | 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 |
191
- | Reads, writes to other files, unknown tools or arguments | allow; reads are never blocked, even over the cap |
192
-
193
- Lines and bytes are judged apart: only a dimension that is over its cap AND grew is
194
- refused, so a write with fewer bytes but lines grown past the cap is still refused.
195
- The line count ignores a trailing newline, so an index exactly at the cap stays
196
- writable. This table is pinned by `node --test` in CI.
197
-
198
- ## Known limits
199
-
200
- - **Only dsh's file tools are capped:** `write`, `edit`, and the `str_replace_editor`
201
- some versions and presets carry; a tool of the same name from another plugin is
202
- judged the same way. Shell tools, MCP file tools and external editors go past it: run
203
- `engramory_check.py` after editing the index and `engramory_doctor.py` now and then.
204
- - **Stores are found only where the installer puts them.** Elsewhere, or for a project
205
- store that links out of the project, set `indexPath`. A project's root is found by
206
- its `.git` only, and a project store created mid-session can take ten seconds to appear.
207
- - **Social mode knows you by what dsh's window sends.** Apart from a bridge's owner
208
- messages, only what you type in dsh's own window is yours, and not when the browser's
209
- time zone cannot be read. A kind of
210
- message a later dsh adds counts as someone else's until this plugin knows it: your
211
- conversation may lose the memory, never the other way round.
212
- - **What the memory page opens is checked by path.** dsh's opener resolves the path once
213
- more before the desktop opens it, so a process changing the store's files at that
214
- moment could redirect what opens (as with dsh's own opener for any workspace file).
215
- - **Experimental:** companion mode, social mode, and the settings and memory pages may
216
- change in a minor version.
217
-
218
- ## Versions
219
-
220
- This package carries Engramory's version: `dsh-engramory@X.Y.Z` is the repo's
221
- `vX.Y.Z`. The cap's decisions (the table above) and the settings outside the
222
- experimental features change incompatibly only in a major version. See Engramory's
223
- [Versioning](https://github.com/tinqiao-oss/engramory/blob/master/README.en.md#versioning); history is in the
224
- [CHANGELOG](https://github.com/tinqiao-oss/engramory/blob/master/CHANGELOG.md).
225
-
226
- ## License
227
-
228
- MIT — see the [Engramory repository](https://github.com/tinqiao-oss/engramory).
1
+ [简体中文](README.md) | **English**
2
+
3
+ # dsh-engramory
4
+
5
+ [![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)
6
+
7
+ Long-term memory for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
8
+ (dsh). What the AI remembers is kept as plain markdown files you can open and edit
9
+ at any time. It is the dsh build of [Engramory](https://github.com/tinqiao-oss/engramory),
10
+ which is general-purpose agent memory: Claude Code, Codex and others can use the same store.
11
+
12
+ ![The memory page](https://raw.githubusercontent.com/tinqiao-oss/engramory/master/adapters/dsh/plugin/screenshots/memory-page.png)
13
+
14
+ ## What it does
15
+
16
+ - **The memory index rides along on every step.** The index, `MEMORY.md`, lists the
17
+ notes by name. The plugin puts it into dsh's context on every step, so the AI knows
18
+ what it has saved without reading a file first, and opens a note when it needs the
19
+ detail. A write shows up on the next request; whatever is past the cap is left
20
+ out, and the AI is told to compact.
21
+ - **The index has a hard cap.** 200 lines / 25 KB by default. When the AI writes the
22
+ index with dsh's file tools and the plugin can work out the result, a write that
23
+ would grow it past the cap is refused before it happens, and the AI is told to
24
+ compact; compaction still passes. Details in [How the cap decides](#how-the-cap-decides).
25
+ - **The rules come with it.** What to save, how, and when to clean up: the rules
26
+ (a skill) are registered by the plugin, with no files to install.
27
+ - **A reminder to save before dsh compacts.** When a conversation grows long, dsh
28
+ compacts what came before into a summary, which need not keep what is worth
29
+ remembering later. As a conversation nears that point, the plugin reminds the AI to
30
+ save that first; the AI is reminded, not you.
31
+ - **A Memory page in the sidebar.** Read-only; it lists the notes by name and opens
32
+ one in your computer's default app, with a check-up that flags broken links in the
33
+ index and notes left out of it.
34
+
35
+ ## Install
36
+
37
+ Needs Node.js 18+ and `pnpm` on PATH (dsh's plugin command uses it). In dsh's desktop
38
+ app you can also search for `dsh-engramory` on the Plugins page.
39
+
40
+ ```sh
41
+ dsh plugin --profile <name> add dsh-engramory
42
+ ```
43
+
44
+ To uninstall, use `remove` instead of `add`. Compatible dsh releases are listed in
45
+ `dsh.compatibility.dshReleases` in [`package.json`](https://github.com/tinqiao-oss/engramory/blob/master/adapters/dsh/plugin/package.json); an unlisted release
46
+ is unverified.
47
+
48
+ **Where the memory lives:**
49
+
50
+ - **The global store**, `~/.dsh/.engramory-memory/` (under `$DSH_HOME` when it is set).
51
+ With the plugin alone this is the only store; the AI creates it on its first save.
52
+ - **A project store** (optional), `.engramory-memory/` in a project's root, is created
53
+ by you only: run `python tools/engramory_init.py dsh --project-root <project>` from
54
+ the Engramory repo, which also git-ignores it. Where one exists, what holds only in
55
+ that project goes there; everything else stays in the global store.
56
+
57
+ Only one AI may write a store; two writers overwrite each other. To share it, let the
58
+ others read it only: see [one writer, many readers](https://github.com/tinqiao-oss/engramory/blob/master/adapters/reader/README.md). Memories are plain text and carry machine-local detail. Inside a project's git repo
59
+ the store must be git-ignored; a dedicated private repo for the store is fine.
60
+
61
+ **Without the plugin:** `python tools/engramory_init.py dsh --install-skill` writes the
62
+ rules into `$DSH_HOME/AGENTS.md`, installs the skill in `$DSH_HOME/skills/engramory/`
63
+ (`$DSH_HOME` defaults to `~/.dsh`) and creates the global store. The AI still keeps memory, but reads the index itself, and
64
+ the cap holds only if it runs `engramory_check.py` after each write.
65
+
66
+ ## Companion mode (大肥鱼模式)
67
+
68
+ For a character you chat with: the community's 大肥鱼, or any persona. Turn on the
69
+ companion switch on the settings page, or set `companion: true`.
70
+
71
+ ![The memory page in companion mode](https://raw.githubusercontent.com/tinqiao-oss/engramory/master/adapters/dsh/plugin/screenshots/companion-mode.png)
72
+
73
+ - **Three more types for the character's own life** ([SKILL.md §2.2](https://github.com/tinqiao-oss/engramory/blob/master/SKILL.md)):
74
+ `moment`, something you shared, with its date, folded into a monthly archive when
75
+ the index fills; `upcoming`, something coming up in your life, asked about once its
76
+ date passes and rewritten as a moment once you say how it went; `self`, a change in
77
+ the character itself, such as a nickname. A moment or self note is deleted only when
78
+ you ask it to forget.
79
+ - **Recall in character.** Even a greeting may call for recall, and what it remembered,
80
+ or failed to save, is told in the character's voice, without naming files or tools.
81
+ - **The persona preset needs the file tools.** The memory arrives even under a preset
82
+ that turns optional context off (dsh's `minimal`, for one). To save notes, though, the
83
+ preset needs dsh's file tools and the skill tool; a preset with only a shell reads the
84
+ memory, and its writes go past the cap.
85
+
86
+ ## Social mode
87
+
88
+ A choice inside companion mode, for a character other people can talk to as well, such
89
+ as one wired to QQ, WeChat, Douyin or Bilibili through a bridge plugin. Choose *Social*
90
+ under *Memory access* on the settings page, or set `audience: social`. If only you talk
91
+ to this dsh, keep the default, *Private*.
92
+
93
+ With it on, **only your own conversations get the memory**: one is yours when you have
94
+ typed in it in dsh's own window (the desktop app or `dsh web`) and nobody else has.
95
+ A subagent goes with its parent. Messages from a bridge plugin (unless it marks them as
96
+ the owner's, below), `dsh headless`, other programs, and terminal or editor clients
97
+ count as someone else's. Once anyone else has written in a conversation it stays
98
+ theirs, and the memory already put into it stays in its history.
99
+
100
+ Someone else's conversation gets no index and is not told where the store is; dsh's
101
+ file tools there may name files only (every directory is refused), and any path into
102
+ a store is refused however it is spelled. This is **not** a security boundary: a shell
103
+ tool reads any file, and another profile on the same account can read the store too.
104
+ Real isolation needs filesystem permissions or a sandbox. A custom `skill` (see
105
+ [Configuration](#configuration)) reaches every conversation as written, someone else's
106
+ included, so if it says where the store is, they are told too.
107
+
108
+ ### For bridge authors
109
+
110
+ With social mode on, every message a bridge submits counts as someone else's. For a
111
+ message from the owner's own account (their private QQ chat with the character, say),
112
+ put a `speaker` on its source:
113
+
114
+ ```js
115
+ agent.followup(createUserMessage({
116
+ content: [{ type: 'text', text }],
117
+ source: { kind: 'plugin:your-bridge', speaker: { role: 'owner' } },
118
+ }))
119
+ ```
120
+
121
+ | `speaker.role` | Meaning |
122
+ |---|---|
123
+ | `owner` | The owner wrote it: it comes from the account the user set as theirs in your bridge. |
124
+ | `guest` | Someone else wrote it, the same as no `speaker` at all. |
125
+ | `none` | Nobody wrote it: your plugin's own report, reminder or notice. It does not make the owner's conversation someone else's. |
126
+
127
+ In a group chat, add `chat: 'group'` (`{ role: 'owner', chat: 'group' }`): the whole
128
+ group reads the reply, so the conversation counts as someone else's even while only the
129
+ owner has spoken in it. A private chat may say `chat: 'private'` or leave it out; any
130
+ other value counts as a group. A group conversation stays someone else's once anyone else in it
131
+ speaks. A program that talks to dsh only through dsh web's API cannot set a source, so its messages count
132
+ as someone else's; if it sends `clientTimeZone` with a prompt it is taken for the
133
+ owner, so a program forwarding other people's messages must leave it out.
134
+
135
+ ## Settings page and memory page
136
+
137
+ ![The settings page](https://raw.githubusercontent.com/tinqiao-oss/engramory/master/adapters/dsh/plugin/screenshots/settings-page.png)
138
+
139
+ - **Settings page:** on dsh's *Plugins* page, open *Engramory memory* to set companion
140
+ mode, memory access and the index cap. Saving goes through dsh's own profile editor,
141
+ which writes your profile's `cordis.patch.yml` and reloads the plugin. Only you, signed
142
+ in, can call it, so an agent cannot use it to switch social mode off.
143
+ - **Memory page:** *Memory* in the sidebar. It lists the global store and each
144
+ workspace's project store (with an absolute `indexPath`, that store alone; with a
145
+ relative one, none), with each index's size against the cap, its notes' names
146
+ by type, and its archive. Each store comes with a check-up: the index's links to
147
+ files that are not there, the notes not in the index (recall starts from the index, so
148
+ the AI will not find them unless another note links to them), and notes with no type.
149
+ It goes by file names and the index's links alone, never through a symbolic link, and
150
+ is skipped when the index is over the cap, there is too much to check, or a file cannot
151
+ be read; `engramory_doctor.py` still does the full check.
152
+ Read-only, never a note's text; a name, *Open the index* and
153
+ *Open the folder* open on the machine dsh runs on; a machine with no desktop (a
154
+ headless server, a session over SSH) shows none of them. The switches at the top
155
+ (companion mode, and memory access once it is on) save as you flip them. Below them
156
+ is a short *How to use it*, open while there is no memory yet; at the foot, where to
157
+ send feedback: a new GitHub issue (its body pre-filled with the plugin's version and the
158
+ OS family, no path and no note), or an email, with a button that copies the address.
159
+
160
+ ## Configuration
161
+
162
+ Settings the page does not cover go in your profile's `cordis.patch.yml`. Patch the
163
+ EXISTING row by id; a second `- insert:` adds another engramory row and leaves the old
164
+ caps in force. A patch replaces the row's whole `config`, so list every key you keep:
165
+
166
+ ```yaml
167
+ - id: engramory
168
+ config:
169
+ indexName: MEMORY.md
170
+ maxLines: 200
171
+ maxBytes: 25600
172
+ ```
173
+
174
+ | Field | Default | Meaning |
175
+ |---|---|---|
176
+ | `indexName` | `MEMORY.md` | The file name treated as the index. The cap matches it case-insensitively; putting the index into context needs the exact name on a case-sensitive filesystem (Linux, say). |
177
+ | `maxLines` | `200` | Line cap for the index. |
178
+ | `maxBytes` | `25600` | UTF-8 byte cap for the index (25 KB). |
179
+ | `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. |
180
+ | `registerSkill` | `true` | `false` skips the built-in rules; the cap and the index in context stay. |
181
+ | `injectIndex` | `true` | `false` stops putting the index into context; the AI reads it instead. |
182
+ | `compactionReminder` | `true` | `false` stops the reminder to save before dsh compacts. The plugin works out where dsh will compact from dsh's own compaction settings (on dsh 0.2 with DeepSeek's defaults, about 69% of the window, not 80%) and reminds at 85% of that. A best effort: a conversation that grows past the gap in one step goes unreminded; with no compaction, or automatic compaction off, there is no reminder. |
183
+ | `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 string is English; a value that is not a string, or is empty, counts as unset. 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. |
184
+ | `companion` | `false` | `true` turns companion mode on. |
185
+ | `audience` | `private` | With companion mode on, `social` turns social mode on. |
186
+ | `skill` | built-in | Your own markdown in place of the built-in rules; it must then say where the store is. In social mode, others' conversations see it too. |
187
+
188
+ ## How the cap decides
189
+
190
+ | Case | Decision |
191
+ |---|---|
192
+ | The index ends within the caps | allow |
193
+ | The write grows the index past a cap | **deny**, with the numbers and what to compact |
194
+ | 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) |
195
+ | A partial edit whose result can be worked out: `edit` (`old_string`/`new_string`), `str_replace_editor`'s replace (`old_str`/`new_str`) and `insert` | its result is worked out first, then judged as above; each tool from the arguments it uses and the way it matches |
196
+ | A partial edit whose result cannot be worked out (arguments missing or not recognised) | deny on an over-cap index, else allow |
197
+ | 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 |
198
+ | 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 |
199
+ | Reads, writes to other files, unknown tools or arguments | allow; reads are never blocked, even over the cap |
200
+
201
+ Lines and bytes are judged apart: only a dimension that is over its cap AND grew is
202
+ refused, so a write with fewer bytes but lines grown past the cap is still refused.
203
+ The line count ignores a trailing newline, so an index exactly at the cap stays
204
+ writable. This table is pinned by `node --test` in CI.
205
+
206
+ ## Known limits
207
+
208
+ - **Only dsh's file tools are capped:** `write`, `edit`, and the `str_replace_editor`
209
+ some versions and presets carry; a tool of the same name from another plugin is
210
+ judged the same way. Shell tools, MCP file tools and external editors go past it: run
211
+ `engramory_check.py` after editing the index and `engramory_doctor.py` now and then.
212
+ - **Stores are found only where the installer puts them.** Elsewhere, or for a project
213
+ store that links out of the project, set `indexPath`. A project's root is found by
214
+ its `.git` only, and a project store created mid-session can take ten seconds to appear.
215
+ - **Social mode knows you by what dsh's window sends.** Apart from a bridge's owner
216
+ messages, only what you type in dsh's own window is yours, and not when the browser's
217
+ time zone cannot be read. A kind of
218
+ message a later dsh adds counts as someone else's until this plugin knows it: your
219
+ conversation may lose the memory, never the other way round.
220
+ - **What the memory page opens is checked by path.** dsh's opener resolves the path once
221
+ more before the desktop opens it, so a process changing the store's files at that
222
+ moment could redirect what opens (as with dsh's own opener for any workspace file).
223
+ - **Experimental:** companion mode, social mode, and the settings and memory pages may
224
+ change in a minor version.
225
+
226
+ ## Feedback
227
+
228
+ For a problem or an idea, [open an issue on GitHub](https://github.com/tinqiao-oss/engramory/issues/new)
229
+ or email engramory@agent.qq.com. Emails are sorted with the help of an AI assistant, and issues
230
+ are public: do not paste your memory notes into either.
231
+
232
+ ## Versions
233
+
234
+ This package carries Engramory's version: `dsh-engramory@X.Y.Z` is the repo's
235
+ `vX.Y.Z`. The cap's decisions (the table above) and the settings outside the
236
+ experimental features change incompatibly only in a major version. See Engramory's
237
+ [Versioning](https://github.com/tinqiao-oss/engramory/blob/master/README.en.md#versioning); history is in the
238
+ [CHANGELOG](https://github.com/tinqiao-oss/engramory/blob/master/CHANGELOG.md).
239
+
240
+ ## License
241
+
242
+ MIT — see the [Engramory repository](https://github.com/tinqiao-oss/engramory).