dsh-engramory 0.2.1 → 0.2.3
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.
- package/README.md +124 -117
- package/README.zh-CN.md +111 -0
- package/index.js +438 -327
- package/package.json +56 -56
package/README.md
CHANGED
|
@@ -1,117 +1,124 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
the
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
|
72
|
-
|
|
73
|
-
| `
|
|
74
|
-
| `
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
|
79
|
-
|
|
80
|
-
|
|
|
81
|
-
|
|
|
82
|
-
|
|
|
83
|
-
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
- **
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
1
|
+
[English](README.md) | [简体中文](README.zh-CN.md)
|
|
2
|
+
|
|
3
|
+
# dsh-engramory
|
|
4
|
+
|
|
5
|
+
[](https://unstone.github.io/dsh-xray/registry.html#tinqiao-oss__engramory)
|
|
6
|
+
|
|
7
|
+
<sub>`C2` is the level `manifest.bundle.patch` puts every mountable dsh plugin at (74.6% of the scanned ecosystem); it is the only flag on this card — no `exec`, `eval`, install script, outbound domain, or environment read.</sub>
|
|
8
|
+
|
|
9
|
+
Curated, file-based long-term memory for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) —
|
|
10
|
+
plain markdown notes you can open with anything, one store shared across every host you
|
|
11
|
+
use, and an index cap that is a **real refusal** rather than a request. (If the store
|
|
12
|
+
lives inside a project's git repo it must be git-ignored — memories carry machine-local
|
|
13
|
+
detail; see SKILL.md §1. A *dedicated private* repo for the store itself is fine.)
|
|
14
|
+
|
|
15
|
+
Part of [Engramory](https://github.com/tinqiao-oss/engramory).
|
|
16
|
+
|
|
17
|
+
## Why a plugin, when an `AGENTS.md` block already works
|
|
18
|
+
|
|
19
|
+
The block does carry the discipline, and for recall that is enough. Two things it cannot
|
|
20
|
+
do:
|
|
21
|
+
|
|
22
|
+
**The cap becomes deterministic.** Engramory keeps its index under 200 lines / 25 KB
|
|
23
|
+
because the index loads every session and everything past the cap silently stops being
|
|
24
|
+
recalled. On most hosts that limit is rules plus a checker the agent has to remember to
|
|
25
|
+
run. dsh exposes `ctx.tools.guard()` — a synchronous, **monotonic** refusal: once a guard
|
|
26
|
+
returns a reason, no later listener can turn it back into an allow. So here the limit is
|
|
27
|
+
enforced, not requested. Use **0.2.1 or later**: 0.2.0 shipped before profile installs
|
|
28
|
+
worked upstream and carried an `inject` declaration this Cordis does not accept — it
|
|
29
|
+
installed but never activated (issue #8). Outside Claude Code, dsh is the first host with
|
|
30
|
+
the shim actually written (a few others expose equivalent pre-write seams — see
|
|
31
|
+
PORTING.md — but have no shim yet).
|
|
32
|
+
|
|
33
|
+
**The protocol arrives with the plugin.** The skill is registered at runtime through
|
|
34
|
+
dsh's skill registry — via a reactive `ctx.inject(['skills'], …)` child, so a profile
|
|
35
|
+
without a registry still gets the cap and one whose registry activates late still gets
|
|
36
|
+
the skill — which means it does not depend on landing files in one of the five skill
|
|
37
|
+
roots dsh scans, a path that is easy to get subtly wrong and fails silently when you do.
|
|
38
|
+
|
|
39
|
+
## Install
|
|
40
|
+
|
|
41
|
+
```sh
|
|
42
|
+
dsh plugin --profile <name> add dsh-engramory
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
That is the whole install. The package ships a `dsh.bundle` manifest pointing at its own
|
|
46
|
+
`cordis.patch.yml`, so the row is inserted into the profile's plugin tree for you — no
|
|
47
|
+
hand-editing. To change a default, patch the EXISTING row by id in your profile's own
|
|
48
|
+
patch layer — do **not** use a second `- insert:` (insert always appends, so you would
|
|
49
|
+
end up with two engramory rows and the original caps still enforced):
|
|
50
|
+
|
|
51
|
+
```yaml
|
|
52
|
+
- id: engramory
|
|
53
|
+
config:
|
|
54
|
+
indexName: MEMORY.md
|
|
55
|
+
maxLines: 200
|
|
56
|
+
maxBytes: 25600
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
A patch replaces the targeted row's whole `config`, so list every key you mean to keep.
|
|
60
|
+
|
|
61
|
+
For the store itself and the always-on block, use the installer in the Engramory repo
|
|
62
|
+
(`python tools/engramory_init.py dsh --install-skill`). This plugin enforces the cap and
|
|
63
|
+
supplies the protocol; it does not create the store.
|
|
64
|
+
|
|
65
|
+
## Configuration
|
|
66
|
+
|
|
67
|
+
| Field | Default | Meaning |
|
|
68
|
+
|---|---|---|
|
|
69
|
+
| `indexName` | `MEMORY.md` | Basename treated as the memory index (case-insensitive; both `file_path` and `str_replace_editor`'s `path` are checked). An empty or non-string value falls back to the default. Nothing else is inspected. |
|
|
70
|
+
| `maxLines` | `200` | Hard line cap. Non-positive or non-finite values fall back to the default. |
|
|
71
|
+
| `maxBytes` | `25600` | Hard UTF-8 byte cap (25 KB). |
|
|
72
|
+
| `indexPath` | unset | Absolute path of the ONE index to guard. 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 (symlinks and `..` resolved; case-folded on Windows only), and a path that does not exist yet still has its first write guarded. |
|
|
73
|
+
| `registerSkill` | `true` | Set `false` to keep the cap but skip the runtime skill. |
|
|
74
|
+
| `skill` | built-in | Replace the skill body with your own markdown. |
|
|
75
|
+
|
|
76
|
+
## What the guard actually does
|
|
77
|
+
|
|
78
|
+
| Call | Decision |
|
|
79
|
+
|---|---|
|
|
80
|
+
| `write` (or `str_replace_editor` `create`) ending within caps | allow |
|
|
81
|
+
| `write`/`create` that GROWS the index past a cap | **deny**, naming the numbers and what to compact |
|
|
82
|
+
| `write`/`create` that SHRINKS or keeps an over-cap index | allow — incremental compaction (210 → 205 → 198) must stay possible |
|
|
83
|
+
| Edit carrying `old_str`/`new_str`: result simulated | judged by the RESULT, same grow/shrink rule as a write |
|
|
84
|
+
| Unsimulable partial (e.g. `insert`) on an over-cap index | **deny**, telling the agent a shrinking whole-file write passes |
|
|
85
|
+
| Unsimulable partial on a healthy index | allow |
|
|
86
|
+
| `read`, `view`, or any unknown tool | allow — recall must never be blocked, even over cap |
|
|
87
|
+
| Any write to any other file | allow — not the guard's business |
|
|
88
|
+
| 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 |
|
|
89
|
+
| Missing/unreadable index on a partial edit | allow — a guard must never block work over a path it cannot read |
|
|
90
|
+
| Malformed execution (no arguments, non-string path/content) | allow — not recognisably a write |
|
|
91
|
+
|
|
92
|
+
The deny rule mirrors `hooks/engramory_index_guard.py` exactly: refuse only a result
|
|
93
|
+
that is over a cap AND grew past the current file. The line count ignores a trailing
|
|
94
|
+
newline, so an index sitting exactly at the cap stays writable.
|
|
95
|
+
|
|
96
|
+
## Known limits
|
|
97
|
+
|
|
98
|
+
- **An unsimulable partial that crosses the cap from under it is not caught.** `insert`
|
|
99
|
+
and friends do not carry the resulting text. The breach is caught by the next
|
|
100
|
+
whole-file write, or by `engramory_check.py`. What is guaranteed: an already-over
|
|
101
|
+
index cannot be grown further, and a shrinking write always passes.
|
|
102
|
+
- **The tool roster follows dsh's documented tool-fs contract** (`write`/`edit` with
|
|
103
|
+
`file_path`, `str_replace_editor` with `path`) and is deliberately conservative:
|
|
104
|
+
unknown tools pass.
|
|
105
|
+
- **0.2.0 never activated; 0.2.1 is the first version that runs.** While the rc.6
|
|
106
|
+
preview bug blocked all third-party profile installs upstream, the only coverage a
|
|
107
|
+
plugin could have was mocks — and 0.2.0's mock hid two activation bugs: an
|
|
108
|
+
older-Cordis `{ required, optional }` inject shape (read as waiting for services
|
|
109
|
+
literally named `required`/`optional`, pending forever) and a bare `ctx.skills` read
|
|
110
|
+
of an undeclared service (throws under Cordis' reflective context). The first field
|
|
111
|
+
install caught both the moment installs became possible (issue #8). 0.2.1 fixes them,
|
|
112
|
+
verified end to end on a live dsh 0.1.0-rc.7 web profile (0.2.0 reproduces the boot
|
|
113
|
+
failure byte for byte; 0.2.1 boots and serves) and against the vendored
|
|
114
|
+
`@deepseek-ai/cordis` resolver (activation with, without, and with a late-mounted
|
|
115
|
+
skill registry). The test mock now mirrors the reflective-context access rules, and
|
|
116
|
+
the guard's decision table stays covered by `node --test` (28 cases, run in
|
|
117
|
+
Engramory's CI).
|
|
118
|
+
- dsh is a developer preview and its plugin API can change. This plugin deliberately
|
|
119
|
+
touches only `ctx.tools.guard()` and a reactive `ctx.inject(['skills'], …)` child
|
|
120
|
+
that registers the skill, so it stays cheap to fix.
|
|
121
|
+
|
|
122
|
+
## License
|
|
123
|
+
|
|
124
|
+
MIT — see the [Engramory repository](https://github.com/tinqiao-oss/engramory).
|
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
[English](README.md) | **简体中文**
|
|
2
|
+
|
|
3
|
+
# dsh-engramory
|
|
4
|
+
|
|
5
|
+
[](https://unstone.github.io/dsh-xray/registry.html#tinqiao-oss__engramory)
|
|
6
|
+
|
|
7
|
+
<sub>`C2` 是 `manifest.bundle.patch` 给每个可挂载 dsh 插件定的档位(被扫描生态里 74.6% 都在这一档);它是这张卡片上**唯一**的标记 —— 没有 `exec`、没有 `eval`、没有安装脚本、没有外连域名、不读环境变量。</sub>
|
|
8
|
+
|
|
9
|
+
给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 用的**策展式、文件式**长期记忆 ——
|
|
10
|
+
纯 markdown 笔记,随便什么工具都能打开;一个记忆库被你用的所有宿主共用;索引上限是一次
|
|
11
|
+
**真正的拒绝**,而不是一句请求。(记忆库若位于某个项目的 git 仓库内,必须 git-ignore ——
|
|
12
|
+
记忆里带着本机独有的细节,见 SKILL.md §1。给记忆库单独开一个*私有仓*则完全可以。)
|
|
13
|
+
|
|
14
|
+
隶属于 [Engramory](https://github.com/tinqiao-oss/engramory)。
|
|
15
|
+
|
|
16
|
+
## 已经有 `AGENTS.md` 常驻块了,为什么还要插件
|
|
17
|
+
|
|
18
|
+
那个常驻块确实承载了纪律,单论召回也够用了。但有两件事它做不到:
|
|
19
|
+
|
|
20
|
+
**上限从此是确定性的。** Engramory 把索引控制在 200 行 / 25 KB 以内,是因为索引每次会话
|
|
21
|
+
都要加载,超出的部分会**悄无声息地不再被召回**。在多数宿主上,这个限制只是"规则 + 一个
|
|
22
|
+
要靠 agent 自己记得去跑的校验器"。而 dsh 暴露了 `ctx.tools.guard()` —— 一个同步的、
|
|
23
|
+
**单调**的否决:守卫一旦返回理由,后面任何监听器都无法把它翻回放行。所以在这里,上限是被
|
|
24
|
+
**强制执行**的,不是被请求的。请用 **0.2.1 或更高版本**:0.2.0 发布时上游的 profile 安装还
|
|
25
|
+
没打通,而且它的 `inject` 声明是这版 Cordis 不接受的写法 —— 装得上,但**永远激活不了**
|
|
26
|
+
(issue #8)。在 Claude Code 之外,dsh 是第一个真正把这层垫片写出来的宿主(另有几个宿主
|
|
27
|
+
同样暴露了等价的写前接缝,见 PORTING.md,但还没有垫片实现)。
|
|
28
|
+
|
|
29
|
+
**协议随插件一起到达。** skill 是在运行时通过 dsh 的 skill 注册表注册的 —— 走一个响应式的
|
|
30
|
+
`ctx.inject(['skills'], …)` 子上下文,所以没有注册表的 profile 照样拿到上限,而注册表晚一步
|
|
31
|
+
挂载的 profile 也照样拿得到 skill。这意味着它**不依赖**把文件放进 dsh 扫描的那五个 skill 根
|
|
32
|
+
目录之一 —— 那条路很容易在细微处放错,而一旦放错就是**静默失败**。
|
|
33
|
+
|
|
34
|
+
## 安装
|
|
35
|
+
|
|
36
|
+
```sh
|
|
37
|
+
dsh plugin --profile <名字> add dsh-engramory
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
装到这里就完了。这个包自带 `dsh.bundle` manifest 指向它自己的 `cordis.patch.yml`,所以那一行
|
|
41
|
+
会被自动插进 profile 的插件树里 —— 不需要手改配置。要改默认值,请在你自己 profile 的 patch
|
|
42
|
+
层里**按 id 修改那一行已存在的配置**,**不要**再写一个 `- insert:`(insert 永远是追加,你会得到
|
|
43
|
+
两行 engramory,而原来那行的上限依旧在生效):
|
|
44
|
+
|
|
45
|
+
```yaml
|
|
46
|
+
- id: engramory
|
|
47
|
+
config:
|
|
48
|
+
indexName: MEMORY.md
|
|
49
|
+
maxLines: 200
|
|
50
|
+
maxBytes: 25600
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
一次 patch 会**整体替换**目标行的 `config`,所以你想保留的键要逐个列全。
|
|
54
|
+
|
|
55
|
+
记忆库本身和常驻块,请用 Engramory 仓库里的安装器
|
|
56
|
+
(`python tools/engramory_init.py dsh --install-skill`)。本插件负责强制上限、提供协议;
|
|
57
|
+
**它不创建记忆库**。
|
|
58
|
+
|
|
59
|
+
## 配置
|
|
60
|
+
|
|
61
|
+
| 字段 | 默认值 | 含义 |
|
|
62
|
+
|---|---|---|
|
|
63
|
+
| `indexName` | `MEMORY.md` | 被当作记忆索引的文件名(不区分大小写;`file_path` 与 `str_replace_editor` 的 `path` 都会检查)。空值或非字符串会回退到默认值。除此之外不检查任何东西。 |
|
|
64
|
+
| `maxLines` | `200` | 硬性行数上限。非正数或非有限值回退到默认值。 |
|
|
65
|
+
| `maxBytes` | `25600` | 硬性 UTF-8 字节上限(25 KB)。 |
|
|
66
|
+
| `indexPath` | 未设置 | 要守护的**那一个**索引的绝对路径。不设它时,守卫只按文件名匹配,于是**别的项目里一个无关的 `MEMORY.md` 也会被拦**;设了它就只有这个确切的文件会被守。比较走的是身份而非拼写(symlink 与 `..` 都会解析;仅在 Windows 上折叠大小写),而且即使文件尚不存在,它的第一次写入照样受守护。 |
|
|
67
|
+
| `registerSkill` | `true` | 设为 `false` 则保留上限、但跳过运行时 skill。 |
|
|
68
|
+
| `skill` | 内置 | 用你自己的 markdown 替换 skill 正文。 |
|
|
69
|
+
|
|
70
|
+
## 守卫到底做了什么
|
|
71
|
+
|
|
72
|
+
| 调用 | 判决 |
|
|
73
|
+
|---|---|
|
|
74
|
+
| `write`(或 `str_replace_editor` 的 `create`)且结果在上限内 | 放行 |
|
|
75
|
+
| `write`/`create` 会让索引**增长**并越过上限 | **拒绝**,并报出具体数字和该压缩什么 |
|
|
76
|
+
| `write`/`create` 让一个已超限的索引**缩小或持平** | 放行 —— 增量压缩(210 → 205 → 198)必须走得通 |
|
|
77
|
+
| 带 `old_str`/`new_str` 的 edit:结果可模拟 | 按**结果**判定,增长/缩小规则与整文件写入相同 |
|
|
78
|
+
| 无法模拟的部分写入(如 `insert`)落在已超限的索引上 | **拒绝**,并告诉 agent:缩小的整文件写入是放行的 |
|
|
79
|
+
| 无法模拟的部分写入落在健康的索引上 | 放行 |
|
|
80
|
+
| `read`、`view`,以及任何未知工具 | 放行 —— 哪怕已超限,召回也绝不能被挡住 |
|
|
81
|
+
| 对任何其他文件的写入 | 放行 —— 不关守卫的事 |
|
|
82
|
+
| 整文件写入时当前索引缺失/读不到 | 视为**空**(与 Python 版守卫一致)—— 上限内的写入放行,而首次就超限的写入被拒 |
|
|
83
|
+
| 部分编辑时索引缺失/读不到 | 放行 —— 守卫绝不能因为一个自己读不了的路径而挡住工作 |
|
|
84
|
+
| 畸形的执行(没有 arguments、路径/内容不是字符串) | 放行 —— 它压根不像一次写入 |
|
|
85
|
+
|
|
86
|
+
拒绝规则与 `hooks/engramory_index_guard.py` **完全一致**:只拒绝那种结果既超过上限、
|
|
87
|
+
又比当前文件更大的写入。行数统计忽略结尾换行,所以一个正好卡在上限的索引仍然可写。
|
|
88
|
+
|
|
89
|
+
## 已知限制
|
|
90
|
+
|
|
91
|
+
- **从上限之下一跃越过上限的、无法模拟的部分写入,抓不住。** `insert` 这类调用并不携带
|
|
92
|
+
写入后的文本。这种越界会由下一次整文件写入、或 `engramory_check.py` 抓到。能保证的是:
|
|
93
|
+
一个**已经超限**的索引不会被继续撑大,而缩小的写入永远放行。
|
|
94
|
+
- **工具名单遵循 dsh 文档化的 tool-fs 契约**(`write`/`edit` 用 `file_path`,
|
|
95
|
+
`str_replace_editor` 用 `path`),并且刻意保守:未知工具一律放行。
|
|
96
|
+
- **0.2.0 从未激活成功;0.2.1 才是第一个真正跑得起来的版本。** 在 rc.6 预览版那个 bug
|
|
97
|
+
堵住上游所有第三方 profile 安装期间,插件能有的覆盖只有 mock —— 而 0.2.0 的 mock 恰好
|
|
98
|
+
掩盖了两个激活期 bug:一个是旧版 Cordis 的 `{ required, optional }` inject 写法(被解读成
|
|
99
|
+
在等待名字就叫 `required`/`optional` 的服务,于是永远 pending),另一个是裸读未声明的
|
|
100
|
+
`ctx.skills`(在 Cordis 的反射式上下文下会直接抛错)。安装一旦成为可能,**首个真实安装
|
|
101
|
+
当场把两个都暴露了**(issue #8)。0.2.1 修掉了它们,并在一个真跑着的 dsh 0.1.0-rc.7 web
|
|
102
|
+
profile 上端到端验证过(0.2.0 逐字节复现启动失败;0.2.1 能启动并提供服务),也对着 dsh
|
|
103
|
+
内置的 `@deepseek-ai/cordis` 解析器验过(注册表存在、不存在、以及晚挂载三种情况下的激活)。
|
|
104
|
+
测试用的 mock 现在会照着反射式上下文的访问规则来,守卫的判决表则由 `node --test`
|
|
105
|
+
持续覆盖(28 个用例,在 Engramory 的 CI 里跑)。
|
|
106
|
+
- dsh 目前是开发者预览版,插件 API 可能变化。本插件刻意只碰 `ctx.tools.guard()` 和一个
|
|
107
|
+
注册 skill 的响应式 `ctx.inject(['skills'], …)` 子上下文,所以要跟着改也很便宜。
|
|
108
|
+
|
|
109
|
+
## 许可
|
|
110
|
+
|
|
111
|
+
MIT —— 见 [Engramory 仓库](https://github.com/tinqiao-oss/engramory)。
|