dsh-engramory 1.5.7 → 2.0.0

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 +284 -327
  2. package/README.md +136 -159
  3. package/client.js +1633 -1715
  4. package/index.js +3889 -5096
  5. package/package.json +72 -86
package/README.en.md CHANGED
@@ -1,327 +1,284 @@
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 comes along by itself.** The index, `MEMORY.md`, lists the notes
17
- by name. The plugin brings it into the conversation as a message, so the AI knows
18
- what it has saved without reading a file first, and opens a note when it needs the
19
- detail. It is sent again only when it changes (a write, another project, a
20
- compacted conversation): a write shows up on the next request, and a long
21
- conversation does not fill up with copies of it ([social mode](#social-mode) keeps it
22
- in dsh's runtime context, as before). Whatever is past the cap is left out, and the AI
23
- is told to compact.
24
- - **The index has a hard cap.** 200 lines / 25 KB by default. When the AI writes the
25
- index with dsh's file tools and the plugin can work out the result, a write that
26
- would grow it past the cap is refused before it happens, and the AI is told to
27
- compact; compaction still passes. Details in [How the cap decides](#how-the-cap-decides).
28
- - **The rules come with it.** What to save, how, and when to clean up: the rules
29
- (a skill) are registered by the plugin, with no files to install.
30
- - **A reminder to save before dsh compacts.** When a conversation grows long, dsh
31
- compacts what came before into a summary, which need not keep what is worth
32
- remembering later. As a conversation nears that point, the plugin reminds the AI to
33
- save that first; the AI is reminded, not you.
34
- - **A Memory page in the sidebar.** Read-only; it lists the notes by name and opens
35
- one in your computer's default app, with a check-up that flags broken links in the
36
- index and notes left out of it.
37
-
38
- ## Install
39
-
40
- Needs Node.js 22.12+ (what dsh itself needs) and `pnpm` on PATH (dsh's plugin command uses
41
- it). In dsh's desktop app you can also search for `dsh-engramory` on the Plugins page.
42
-
43
- ```sh
44
- dsh plugin --profile <name> add dsh-engramory
45
- ```
46
-
47
- To uninstall, use `remove` instead of `add`.
48
-
49
- **Name the version to upgrade**, as in `dsh plugin --profile <name> add
50
- dsh-engramory@1.5.7`: by name alone, pnpm 11 (the desktop app's own included) by default
51
- installs only a version published at least 24 hours ago. The desktop app's Plugins page has no *Update*
52
- for a plugin from outside dsh: uninstall it, search for `dsh-engramory@<version>` and
53
- install that, then quit dsh from the tray and open it again. Your memory and settings stay.
54
- *Check for updates* at the foot of the memory page finds the latest version and lists
55
- these steps.
56
-
57
- Compatible dsh releases are listed in
58
- `dsh.compatibility.dshReleases` in [`package.json`](https://github.com/tinqiao-oss/engramory/blob/master/adapters/dsh/plugin/package.json); an unlisted release
59
- is unverified. `engines.dsh` gives only a floor (`>=0.1.0-rc.7`), so a newer dsh does
60
- not refuse the install; it is just not verified yet.
61
-
62
- **Where the memory lives:**
63
-
64
- - **The global store**, by default `~/.dsh/.engramory-memory/` (under `$DSH_HOME` when it
65
- is set); the memory page can move it to another folder (see
66
- [Moving the store](#moving-the-store)). With the plugin alone this is the only store;
67
- the AI creates it on its first save.
68
- - **A project store** (optional), `.engramory-memory/` in a project's root, is created
69
- by you only: run `python tools/engramory_init.py dsh --project-root <project>` from
70
- the Engramory repo, which also git-ignores it. Where one exists, what holds only in
71
- that project goes there; everything else stays in the global store.
72
-
73
- Only one AI may write a store; two writers overwrite each other. To share it, let the
74
- 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
75
- the store must be git-ignored; a dedicated private repo for the store is fine.
76
-
77
- **Without the plugin:** `python tools/engramory_init.py dsh --install-skill` writes the
78
- rules into `$DSH_HOME/AGENTS.md`, installs the skill in `$DSH_HOME/skills/engramory/`
79
- (`$DSH_HOME` defaults to `~/.dsh`) and creates the global store. The AI still keeps memory, but reads the index itself, and
80
- the cap holds only if it runs `engramory_check.py` after each write.
81
-
82
- ## Companion mode (大肥鱼模式)
83
-
84
- For a character you chat with: the community's 大肥鱼, or any persona. Turn on the
85
- companion switch on the settings page, or set `companion: true`.
86
-
87
- ![The memory page in companion mode](https://raw.githubusercontent.com/tinqiao-oss/engramory/master/adapters/dsh/plugin/screenshots/companion-mode.png)
88
-
89
- - **Three more types for the character's own life** ([SKILL.md §2.2](https://github.com/tinqiao-oss/engramory/blob/master/SKILL.md)):
90
- `moment`, something you shared, with its date, folded into a monthly archive when
91
- the index fills; `upcoming`, something coming up in your life, asked about once its
92
- date passes and rewritten as a moment once you say how it went; `self`, a change in
93
- the character itself, such as a nickname. A moment or self note is deleted only when
94
- you ask it to forget.
95
- - **Recall in character.** Even a greeting may call for recall, and what it remembered,
96
- or failed to save, is told in the character's voice, without naming files or tools.
97
- - **The persona preset needs the file tools.** The memory arrives even under a preset
98
- that turns optional context off (dsh's `minimal`, for one; from dsh 0.2 — 0.1 then sends
99
- no runtime context at all). To save notes, though, the
100
- preset needs dsh's file tools and the skill tool; a preset with only a shell reads the
101
- memory, and its writes go past the cap.
102
-
103
- ## Social mode
104
-
105
- A choice inside companion mode, for a character other people can talk to as well, such
106
- as one wired to QQ, WeChat, Douyin or Bilibili through a bridge plugin. Choose *Social*
107
- under *Memory access* on the settings page, or set `audience: social`. If only you talk
108
- to this dsh, keep the default, *Private*.
109
-
110
- With it on, **only your own conversations get the memory**: one is yours when you have
111
- typed in it in dsh's own window (the desktop app or `dsh web`) and nobody else has.
112
- A subagent goes with its parent. Messages from a bridge plugin (unless it marks them as
113
- the owner's, below), `dsh headless`, other programs, and terminal or editor clients
114
- count as someone else's. Once anyone else has written in a conversation it stays
115
- theirs, and the memory already put into it stays in its history.
116
-
117
- Someone else's conversation gets no index and is not told where the store is; dsh's
118
- file tools there may name files only (every directory is refused), and any path into
119
- a store is refused however it is spelled; dsh's session search (an optional, experimental
120
- feature that reads the records of other conversations in the same directory) is refused
121
- there outright. This is **not** a security boundary: a shell tool reads any file, and
122
- another profile on the same account can read the store too. Real isolation needs
123
- filesystem permissions or a sandbox. A custom `skill` (see
124
- [Configuration](#configuration)) reaches every conversation as written, someone else's
125
- included, so if it says where the store is, they are told too.
126
-
127
- ### For bridge authors
128
-
129
- With social mode on, every message a bridge submits counts as someone else's. For a
130
- message from the owner's own account (their private QQ chat with the character, say),
131
- put a `speaker` on its source:
132
-
133
- ```js
134
- agent.followup(createUserMessage({
135
- content: [{ type: 'text', text }],
136
- source: { kind: 'plugin:your-bridge', speaker: { role: 'owner' } },
137
- }))
138
- ```
139
-
140
- | `speaker.role` | Meaning |
141
- |---|---|
142
- | `owner` | The owner wrote it: it comes from the account the user set as theirs in your bridge. |
143
- | `guest` | Someone else wrote it, the same as no `speaker` at all. |
144
- | `none` | Nobody wrote it: your plugin's own report, reminder or notice. It does not make the owner's conversation someone else's. |
145
-
146
- In a group chat, add `chat: 'group'` (`{ role: 'owner', chat: 'group' }`): the whole
147
- group reads the reply, so the conversation counts as someone else's even while only the
148
- owner has spoken in it. A private chat may say `chat: 'private'` or leave it out; any
149
- other value counts as a group. A group conversation stays someone else's once anyone else in it
150
- speaks. A program that talks to dsh only through dsh web's API cannot set a source, so its messages count
151
- as someone else's; if it sends `clientTimeZone` with a prompt it is taken for the
152
- owner, so a program forwarding other people's messages must leave it out.
153
-
154
- ## Settings page and memory page
155
-
156
- ![The settings page](https://raw.githubusercontent.com/tinqiao-oss/engramory/master/adapters/dsh/plugin/screenshots/settings-page.png)
157
-
158
- - **Settings page:** on dsh's *Plugins* page, open *Engramory memory* to set companion
159
- mode, memory access and the index cap. Saving goes through dsh's own profile editor,
160
- which writes your profile's `cordis.patch.yml` and reloads the plugin. Only you, signed
161
- in, can call it, so an agent cannot use it to switch social mode off.
162
- - **Memory page:** *Memory* in the sidebar. A banner at the top, the plugin's version
163
- beside its title, says how many notes, stores and archived files are listed and when
164
- they were read, with the switches (companion mode, and memory access once it is on)
165
- that save as you flip them. Below it,
166
- tabs by note type and a filter by name, over the global store and each workspace's
167
- project store (with an absolute `indexPath`, that store alone; with a relative one,
168
- none). Each note is a row: a mark for its type, its name, its type and size; a plan's
169
- row gives its day and how far off it is (a passed date is an outcome to confirm, as a
170
- reminder: nothing is archived), and a note past 12 KB or one the index leaves out is
171
- marked. Beside each store's name: its index fill as a bar (to the nearer of its two
172
- caps), *Open the folder*, and for the global store *Change location* (see
173
- [Moving the store](#moving-the-store)). What its check-up finds is listed under
174
- it: the index's links to files that are not there, the notes not in the index (recall
175
- starts from the index, so the AI will not find them unless another note links to
176
- them), notes with no type, notes past 12 KB, an index over the cap; *Copy tidy-up
177
- instructions* copies a request for the AI to paste into a conversation, and the plugin
178
- itself changes no file. The check-up goes by file names and the index's links alone,
179
- never through a symbolic link, and is skipped when the index is over the cap, there is
180
- too much to check, or a file cannot be read; `engramory_doctor.py` still does the full
181
- check. Where the listing was cut short or a store could not be read, the page says so,
182
- rather than counting that as nothing. Read-only, never a note's text; a name and *Open
183
- the folder* open on the machine dsh runs on; a machine with no desktop (a headless
184
- server, a session over SSH) shows neither. A short *How to use
185
- it* follows, open while there is no memory yet. At the foot, the plugin's version and
186
- *Check for updates*: only when clicked, it asks npm (npmmirror when npm cannot be
187
- reached) for the latest version number, with nothing from your memory, and lists the
188
- steps that upgrade to a newer one, the version named. The plugin goes online at no other
189
- time. Below that, where to send feedback: a new GitHub issue (its body pre-filled with
190
- the plugin's version and the OS family, no path and no note), or an email, with a button
191
- that copies the address.
192
-
193
- ## Moving the store
194
-
195
- *Change location*, at the top right of the memory page's global memory (beside *No memory yet* before
196
- there is any), moves the global store to another folder: a synced one, say, or a private
197
- git repository. Click *Choose folder…* to pick it in the system's own window, or type the
198
- path, then click *Move it there*:
199
-
200
- - **Choose folder** opens dsh's own chooser, on the screen of the computer dsh runs on.
201
- Where dsh takes it that you are not at that computer (dsh on a remote server, say), there
202
- is no such button and the path is typed; dsh started locally and opened from elsewhere
203
- through an ssh tunnel still takes you to be local, and opens it on that computer's screen. A folder that
204
- holds something already (the root of a synced folder, say) gets an `Engramory` folder
205
- made inside it for the memory. Choosing only fills the path in; *Move it there* moves.
206
-
207
- - **All of it moves, and the old place is cleared.** It is copied to the new place first,
208
- each file checked, and only then switched to; the old place is then renamed aside,
209
- compared file by file with the new one, and removed. What was written to the old place
210
- while it moved is added to the new one; a file changed in both places keeps the new
211
- place's version, with the old place's beside it as `<name>.old-<id>` and a line for it
212
- at the end of the index. Nothing in the new place is written over.
213
- - **Cut short, nothing is lost.** Each step is written down first: dsh closed before the
214
- switch, the move is undone when it opens again and the memory stays where it was;
215
- closed after, the move is finished when it opens again. An error after the switch (a
216
- file in the old place held open by another program, say) leaves the memory moved: the
217
- page says so, and that the old place is not cleared yet, which dsh carries on with every
218
- minute.
219
- - **Every dsh on this computer moves with it.** The place is kept in
220
- `.engramory-memory.json` in dsh's home folder, which the desktop app, the command line
221
- and `dsh web` all follow (their plugin configs are their own; the global store is
222
- shared). Do not delete that file: without it the store is looked for at its default
223
- place, and the memory moved elsewhere is not found.
224
- - **For the few seconds it takes, the AI cannot save memory** and is told to try again
225
- shortly; after the move, a save it makes to the old place is refused with the new one
226
- named.
227
- - **It cannot go** on a network path, a whole drive, your home folder or dsh's (or a folder
228
- holding either), anywhere else in dsh's home folder, a folder named `.engramory-memory`
229
- (a project would read it as its own), or inside the store itself. A store holding a
230
- folder link, or anything that is not a plain file, is not moved: sort it out by hand.
231
- With `indexPath` set, there is no move.
232
- - **Readers** (`claude-reader`, `codex-reader` and the others, see one writer, many
233
- readers above) read the new place once installed again with it.
234
- - **Only dsh's own writes are held off.** A shell, an editor or another AI tool writing to
235
- the store in those few seconds is beyond the plugin, and what it writes may be missed.
236
- A network drive mapped to a letter cannot be told apart, and there dsh may stall. Only
237
- file contents are copied: NTFS alternate data streams are not, and hard links become
238
- separate files.
239
-
240
- ## Configuration
241
-
242
- Settings the page does not cover go in your profile's `cordis.patch.yml`. Patch the
243
- EXISTING row by id; a second `- insert:` adds another engramory row and leaves the old
244
- caps in force. A patch replaces the row's whole `config`, so list every key you keep:
245
-
246
- ```yaml
247
- - id: engramory
248
- config:
249
- indexName: MEMORY.md
250
- maxLines: 200
251
- maxBytes: 25600
252
- ```
253
-
254
- | Field | Default | Meaning |
255
- |---|---|---|
256
- | `indexName` | `MEMORY.md` | The file name treated as the index. The cap matches it case-insensitively; sending the index needs the exact name on a case-sensitive filesystem (Linux, say). |
257
- | `maxLines` | `200` | Line cap for the index. |
258
- | `maxBytes` | `25600` | UTF-8 byte cap for the index (25 KB). |
259
- | `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. |
260
- | `registerSkill` | `true` | `false` skips the built-in rules; the cap and the index sent along stay. |
261
- | `injectIndex` | `true` | `false` stops sending the index; the AI reads it instead. |
262
- | `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. |
263
- | `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. |
264
- | `companion` | `false` | `true` turns companion mode on. |
265
- | `audience` | `private` | With companion mode on, `social` turns social mode on. |
266
- | `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. |
267
-
268
- ## How the cap decides
269
-
270
- | Case | Decision |
271
- |---|---|
272
- | The index ends within the caps | allow |
273
- | The write grows the index past a cap | **deny**, with the numbers and what to compact |
274
- | 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) |
275
- | 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 |
276
- | A partial edit whose result cannot be worked out (arguments missing or not recognised) | deny on an over-cap index, else allow |
277
- | 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 |
278
- | 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 |
279
- | Reads, writes to other files, unknown tools or arguments | allow; reads are never blocked, even over the cap |
280
-
281
- Lines and bytes are judged apart: only a dimension that is over its cap AND grew is
282
- refused, so a write with fewer bytes but lines grown past the cap is still refused.
283
- The line count ignores a trailing newline, so an index exactly at the cap stays
284
- writable. This table is pinned by `node --test` in CI.
285
-
286
- ## Known limits
287
-
288
- - **Only dsh's file tools are capped:** `write`, `edit`, and the `str_replace_editor`
289
- some versions and presets carry; a tool of the same name from another plugin is
290
- judged the same way. Not `apply_patch`, which dsh offers from 0.2.2-alpha.3 and leaves
291
- off by default: its paths are in the patch text, which the cap does not read (it is
292
- still kept off a store in a stranger's conversation in social mode, and while the store
293
- moves). Shell tools, MCP file tools and external
294
- editors go past it: run
295
- `engramory_check.py` after editing the index and `engramory_doctor.py` now and then.
296
- - **The global store is found where the memory page put it.** Moved there by hand, it
297
- is not (move it back and use the memory page, or set `indexPath`); for a project store
298
- that links out of the project, set `indexPath`. A project's root is found by
299
- its `.git` only, and a project store created mid-session can take ten seconds to appear.
300
- - **Social mode knows you by what dsh's window sends.** Apart from a bridge's owner
301
- messages, only what you type in dsh's own window (and its Continue generating) is
302
- yours, and not when the browser's time zone cannot be read. A kind of
303
- message a later dsh adds counts as someone else's until this plugin knows it: your
304
- conversation may lose the memory, never the other way round.
305
- - **What the memory page opens is checked by path.** dsh's opener resolves the path once
306
- more before the desktop opens it, so a process changing the store's files at that
307
- moment could redirect what opens (as with dsh's own opener for any workspace file).
308
- - **Experimental:** companion mode, social mode, the settings and memory pages, and moving
309
- the store may change in a minor version.
310
-
311
- ## Feedback
312
-
313
- For a problem or an idea, [open an issue on GitHub](https://github.com/tinqiao-oss/engramory/issues/new)
314
- or email engramory@agent.qq.com. Emails are sorted with the help of an AI assistant, and issues
315
- are public: do not paste your memory notes into either.
316
-
317
- ## Versions
318
-
319
- This package carries Engramory's version: `dsh-engramory@X.Y.Z` is the repo's
320
- `vX.Y.Z`. The cap's decisions (the table above) and the settings outside the
321
- experimental features change incompatibly only in a major version. See Engramory's
322
- [Versioning](https://github.com/tinqiao-oss/engramory/blob/master/README.en.md#versioning); history is in the
323
- [CHANGELOG](https://github.com/tinqiao-oss/engramory/blob/master/CHANGELOG.md).
324
-
325
- ## License
326
-
327
- 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 comes along by itself.** The index, `MEMORY.md`, lists the notes
17
+ by name. The plugin brings it into the conversation as a message, so the AI knows
18
+ what it has saved without reading a file first, and opens a note when it needs the
19
+ detail. It is sent again only when it changes (a write, another project, a
20
+ compacted conversation): a write shows up on the next request, and a long
21
+ conversation does not fill up with copies of it. Whatever is past the cap is left out,
22
+ and the AI is told to compact.
23
+ - **The index has a hard cap.** 200 lines / 25 KB by default. When the AI writes the
24
+ index with dsh's file tools and the plugin can work out the result, a write that
25
+ would grow it past the cap is refused before it happens, and the AI is told to
26
+ compact; compaction still passes. Details in [How the cap decides](#how-the-cap-decides).
27
+ - **The rules come with it.** What to save, how, and when to clean up: the rules
28
+ (a skill) are registered by the plugin, with no files to install.
29
+ - **A reminder to save before dsh compacts.** When a conversation grows long, dsh
30
+ compacts what came before into a summary, which need not keep what is worth
31
+ remembering later. As a conversation nears that point, the plugin reminds the AI to
32
+ save that first; the AI is reminded, not you.
33
+ - **A Memory page in the sidebar.** Read-only; it lists the notes by name and opens
34
+ one in your computer's default app, with a check-up that flags broken links in the
35
+ index and notes left out of it.
36
+
37
+ ## Install
38
+
39
+ Needs Node.js 22.12+ (what dsh itself needs) and `pnpm` on PATH (dsh's plugin command uses
40
+ it). In dsh's desktop app you can also search for `dsh-engramory` on the Plugins page.
41
+
42
+ ```sh
43
+ dsh plugin --profile <name> add dsh-engramory
44
+ ```
45
+
46
+ To uninstall, use `remove` instead of `add`.
47
+
48
+ **Name the version to upgrade**, as in `dsh plugin --profile <name> add
49
+ dsh-engramory@2.0.0`: by name alone, pnpm 11 (the desktop app's own included) by default
50
+ installs only a version published at least 24 hours ago. From dsh 0.2.2 the desktop
51
+ app's Plugins page has an *Update* for *Engramory memory*; before that there is none:
52
+ uninstall it, then search for `dsh-engramory@<version>` and install that. Restart dsh
53
+ when it says so (in the desktop app, quit from the tray and open it again). Your memory
54
+ and settings stay. *Check for updates* at the foot of the memory page finds the latest
55
+ version and lists the steps.
56
+
57
+ Compatible dsh releases are listed in
58
+ `dsh.compatibility.dshReleases` in [`package.json`](https://github.com/tinqiao-oss/engramory/blob/master/adapters/dsh/plugin/package.json); an unlisted release
59
+ is unverified. `engines.dsh` gives only a floor (`>=0.2.1-alpha.5`; dsh 0.1 is not
60
+ supported from 2.0), so a newer dsh does not refuse the install; it is just not verified
61
+ yet.
62
+
63
+ **Where the memory lives:**
64
+
65
+ - **The global store**, by default `~/.dsh/.engramory-memory/` (under `$DSH_HOME` when it
66
+ is set); the memory page can move it to another folder (see
67
+ [Moving the store](#moving-the-store)). With the plugin alone this is the only store;
68
+ the AI creates it on its first save.
69
+ - **A project store** (optional), `.engramory-memory/` in a project's root, is created
70
+ by you only: run `python tools/engramory_init.py dsh --project-root <project>` from
71
+ the Engramory repo, which also git-ignores it. Where one exists, what holds only in
72
+ that project goes there; everything else stays in the global store.
73
+
74
+ Only one AI may write a store; two writers overwrite each other. To share it, let the
75
+ 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
76
+ the store must be git-ignored; a dedicated private repo for the store is fine.
77
+
78
+ **Without the plugin:** `python tools/engramory_init.py dsh --install-skill` writes the
79
+ rules into `$DSH_HOME/AGENTS.md`, installs the skill in `$DSH_HOME/skills/engramory/`
80
+ (`$DSH_HOME` defaults to `~/.dsh`) and creates the global store. The AI still keeps memory, but reads the index itself, and
81
+ the cap holds only if it runs `engramory_check.py` after each write.
82
+
83
+ ## Companion mode (大肥鱼模式)
84
+
85
+ For a character you chat with: the community's 大肥鱼, or any persona. Turn on the
86
+ companion switch on the settings page, or set `companion: true`.
87
+
88
+ ![The memory page in companion mode](https://raw.githubusercontent.com/tinqiao-oss/engramory/master/adapters/dsh/plugin/screenshots/companion-mode.png)
89
+
90
+ - **Three more types for the character's own life** ([SKILL.md §2.2](https://github.com/tinqiao-oss/engramory/blob/master/SKILL.md)):
91
+ `moment`, something you shared, with its date, folded into a monthly archive when
92
+ the index fills; `upcoming`, something coming up in your life, asked about once its
93
+ date passes and rewritten as a moment once you say how it went; `self`, a change in
94
+ the character itself, such as a nickname. A moment or self note is deleted only when
95
+ you ask it to forget.
96
+ - **Recall in character.** Even a greeting may call for recall, and what it remembered,
97
+ or failed to save, is told in the character's voice, without naming files or tools.
98
+ - **The persona preset needs the file tools.** The memory arrives even under a preset
99
+ that turns optional context off (dsh's `minimal`, for one). To save notes, though, the
100
+ preset needs dsh's file tools and the skill tool; a preset with only a shell reads the
101
+ memory, and its writes go past the cap.
102
+
103
+ ## Bridges and other people's accounts
104
+
105
+ The memory goes to every conversation, and every profile under one dsh home shares the
106
+ global store. A bridge plugin that brings other people's messages in from QQ, WeChat,
107
+ Douyin or Bilibili gives their conversations your memory too: run such a character under
108
+ a dsh home of its own (`DSH_HOME`), or without Engramory in its profile — another
109
+ profile in the same home is not enough. Their conversations then get neither your memory
110
+ nor its rules; the store is plain files, though, which a shell tool can read like any
111
+ file the account can, so full isolation still takes filesystem permissions or a
112
+ sandbox.
113
+
114
+ Social mode (`audience: social`), which until 2.0 tried to tell your own conversations
115
+ apart within one profile, was removed: every review found a way past it. A profile still
116
+ set to it gives no conversation any memory (no index, no rules), and the settings page
117
+ says so; one save there takes the setting out, and the memory is back. The cap holds
118
+ either way.
119
+
120
+ ## Settings page and memory page
121
+
122
+ ![The settings page](https://raw.githubusercontent.com/tinqiao-oss/engramory/master/adapters/dsh/plugin/screenshots/settings-page.png)
123
+
124
+ - **Settings page:** on dsh's *Plugins* page, open *Engramory memory* to set companion
125
+ mode and the index cap. Saving goes through dsh's own profile editor, which writes your
126
+ profile's `cordis.patch.yml` and reloads the plugin. Only you, signed in, can call it.
127
+ - **Memory page:** *Memory* in the sidebar. A banner at the top, the plugin's version
128
+ beside its title, says how many notes, stores and archived files are listed and when
129
+ they were read, with the companion mode switch, which saves as you flip it. Below it,
130
+ tabs by note type and a filter by name, over the global store and each workspace's
131
+ project store (with an absolute `indexPath`, that store alone; with a relative one,
132
+ none). Each note is a row: a mark for its type, its name, its type and size; a plan's
133
+ row gives its day and how far off it is (a passed date is an outcome to confirm, as a
134
+ reminder: nothing is archived), and a note past 12 KB or one the index leaves out is
135
+ marked. Beside each store's name: its index fill as a bar (to the nearer of its two
136
+ caps), *Open the folder*, and for the global store *Change location* (see
137
+ [Moving the store](#moving-the-store)). What its check-up finds is listed under
138
+ it: the index's links to files that are not there, the notes not in the index (recall
139
+ starts from the index, so the AI will not find them unless another note links to
140
+ them), notes with no type, notes past 12 KB, an index over the cap; *Copy tidy-up
141
+ instructions* copies a request for the AI to paste into a conversation, and the plugin
142
+ itself changes no file. The check-up goes by file names and the index's links alone,
143
+ never through a symbolic link, and is skipped when the index is over the cap, there is
144
+ too much to check, or a file cannot be read; `engramory_doctor.py` still does the full
145
+ check. Where the listing was cut short or a store could not be read, the page says so,
146
+ rather than counting that as nothing. Read-only, never a note's text; a name and *Open
147
+ the folder* open on the machine dsh runs on; a machine with no desktop (a headless
148
+ server, a session over SSH) shows neither. A short *How to use
149
+ it* follows, open while there is no memory yet. At the foot, the plugin's version and
150
+ *Check for updates*: only when clicked, it asks npm (npmmirror when npm cannot be
151
+ reached) for the latest version number, with nothing from your memory, and lists the
152
+ steps that upgrade to a newer one, the version named. The plugin goes online at no other
153
+ time. Below that, where to send feedback: a new GitHub issue (its body pre-filled with
154
+ the plugin's version and the OS family, no path and no note), or an email, with a button
155
+ that copies the address.
156
+
157
+ ## Moving the store
158
+
159
+ *Change location*, at the top right of the memory page's global memory (beside *No memory yet* before
160
+ there is any), moves the global store to another folder: a synced one, say, or a private
161
+ git repository. Click *Choose folder…* to pick it in the system's own window, or type the
162
+ path, then click *Move it there*:
163
+
164
+ - **Choose folder** opens dsh's own chooser, on the screen of the computer dsh runs on.
165
+ Where dsh takes it that you are not at that computer (dsh on a remote server, say), there
166
+ is no such button and the path is typed; dsh started locally and opened from elsewhere
167
+ through an ssh tunnel still takes you to be local, and opens it on that computer's screen. A folder that
168
+ holds something already (the root of a synced folder, say) gets an `Engramory` folder
169
+ made inside it for the memory. Choosing only fills the path in; *Move it there* moves.
170
+
171
+ - **Copied over, the old store kept as a backup.** It is copied into a folder beside the
172
+ new place, each file checked, renamed to the new place and switched to; the old store is
173
+ renamed `<name>.backup-<date-time>` beside where it was, for you to delete once the new
174
+ place looks right. Where a file in it is held open by another program and it cannot be
175
+ renamed, it stays where it was as the backup, and the page says so. The plugin deletes
176
+ nothing.
177
+ - **A failure loses nothing.** One before the switch (too many files, a folder link in the
178
+ store) takes the copy away, and the memory stays where it was; the switch either happens
179
+ or does not. dsh closed partway may leave an `.engramory-memory-moving-<id>` folder beside
180
+ the new place: delete it.
181
+ - **Every dsh on this computer moves with it.** The place is kept in
182
+ `.engramory-memory.json` in dsh's home folder, which the desktop app, the command line
183
+ and `dsh web` all follow (their plugin configs are their own; the global store is
184
+ shared). Do not delete that file: without it the store is looked for at its default
185
+ place, and the memory moved elsewhere is not found.
186
+ - **For the few seconds it takes, the AI cannot save memory** and is told to try again
187
+ shortly; after the move, a save it makes to the old place is refused with the new one
188
+ named.
189
+ - **It cannot go** on a network path, a whole drive, your home folder or dsh's (or a folder
190
+ holding either), anywhere else in dsh's home folder, a folder named `.engramory-memory`
191
+ (a project would read it as its own), or inside the store itself. A store holding a
192
+ folder link, or anything that is not a plain file, is not moved: sort it out by hand.
193
+ With `indexPath` set, there is no move.
194
+ - **Readers** (`claude-reader`, `codex-reader` and the others, see one writer, many
195
+ readers above) read the new place once installed again with it.
196
+ - **Only this dsh's own writes are held off.** What another dsh open at the same time (the
197
+ desktop app while you use the command line, say), a shell, an editor or another AI tool
198
+ writes to the old store in those few seconds stays in the backup only, not in the new
199
+ place: close them first.
200
+ A network drive mapped to a letter cannot be told apart, and there dsh may stall. Only
201
+ file contents are copied: NTFS alternate data streams are not, and hard links become
202
+ separate files.
203
+
204
+ ## Configuration
205
+
206
+ Settings the page does not cover go in your profile's `cordis.patch.yml`. Patch the
207
+ EXISTING row by id; a second `- insert:` adds another engramory row and leaves the old
208
+ caps in force. A patch replaces the row's whole `config`, so list every key you keep:
209
+
210
+ ```yaml
211
+ - id: engramory
212
+ config:
213
+ indexName: MEMORY.md
214
+ maxLines: 200
215
+ maxBytes: 25600
216
+ ```
217
+
218
+ | Field | Default | Meaning |
219
+ |---|---|---|
220
+ | `indexName` | `MEMORY.md` | The file name treated as the index. The cap matches it case-insensitively; sending the index needs the exact name on a case-sensitive filesystem (Linux, say). |
221
+ | `maxLines` | `200` | Line cap for the index. |
222
+ | `maxBytes` | `25600` | UTF-8 byte cap for the index (25 KB). |
223
+ | `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. |
224
+ | `registerSkill` | `true` | `false` skips the built-in rules; the cap and the index sent along stay. |
225
+ | `injectIndex` | `true` | `false` stops sending the index; the AI reads it instead. |
226
+ | `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. |
227
+ | `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. |
228
+ | `companion` | `false` | `true` turns companion mode on. |
229
+ | `skill` | built-in | Your own markdown in place of the built-in rules; it must then say where the store is. |
230
+
231
+ ## How the cap decides
232
+
233
+ | Case | Decision |
234
+ |---|---|
235
+ | The index ends within the caps | allow |
236
+ | The write grows the index past a cap | **deny**, with the numbers and what to compact |
237
+ | 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) |
238
+ | 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 |
239
+ | A partial edit whose result cannot be worked out (arguments missing or not recognised) | deny on an over-cap index, else allow |
240
+ | 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 |
241
+ | 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 |
242
+ | Reads, writes to other files, unknown tools or arguments | allow; reads are never blocked, even over the cap |
243
+
244
+ Lines and bytes are judged apart: only a dimension that is over its cap AND grew is
245
+ refused, so a write with fewer bytes but lines grown past the cap is still refused.
246
+ The line count ignores a trailing newline, so an index exactly at the cap stays
247
+ writable. This table is pinned by `node --test` in CI.
248
+
249
+ ## Known limits
250
+
251
+ - **Only dsh's file tools are capped:** `write`, `edit`, and the `str_replace_editor`
252
+ some versions and presets carry; a tool of the same name from another plugin is
253
+ judged the same way. Not `apply_patch`, which dsh offers from 0.2.2-alpha.3 and leaves
254
+ off by default: its paths are in the patch text, which the cap does not read (it is
255
+ still kept off a store while the store moves). Shell tools, MCP file tools and external
256
+ editors go past it: run
257
+ `engramory_check.py` after editing the index and `engramory_doctor.py` now and then.
258
+ - **The global store is found where the memory page put it.** Moved there by hand, it
259
+ is not (move it back and use the memory page, or set `indexPath`); for a project store
260
+ that links out of the project, set `indexPath`. A project's root is found by
261
+ its `.git` only, and a project store created mid-session can take ten seconds to appear.
262
+ - **What the memory page opens is checked by path.** dsh's opener resolves the path once
263
+ more before the desktop opens it, so a process changing the store's files at that
264
+ moment could redirect what opens (as with dsh's own opener for any workspace file).
265
+ - **Experimental:** companion mode, the settings and memory pages, and moving the store may
266
+ change in a minor version.
267
+
268
+ ## Feedback
269
+
270
+ For a problem or an idea, [open an issue on GitHub](https://github.com/tinqiao-oss/engramory/issues/new)
271
+ or email engramory@agent.qq.com. Emails are sorted with the help of an AI assistant, and issues
272
+ are public: do not paste your memory notes into either.
273
+
274
+ ## Versions
275
+
276
+ This package carries Engramory's version: `dsh-engramory@X.Y.Z` is the repo's
277
+ `vX.Y.Z`. The cap's decisions (the table above) and the settings outside the
278
+ experimental features change incompatibly only in a major version. See Engramory's
279
+ [Versioning](https://github.com/tinqiao-oss/engramory/blob/master/README.en.md#versioning); history is in the
280
+ [CHANGELOG](https://github.com/tinqiao-oss/engramory/blob/master/CHANGELOG.md).
281
+
282
+ ## License
283
+
284
+ MIT — see the [Engramory repository](https://github.com/tinqiao-oss/engramory).