tinqiao-oss/engramory#plugin

English | 简体中文

dsh-engramory

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.

Curated, file-based long-term memory for DeepSeek Harness — plain markdown notes you can open with anything, one store shared across every host you use, and an index cap that is a real refusal rather than a request. (If the store lives inside a project's git repo it must be git-ignored — memories carry machine-local detail; see SKILL.md §1. A dedicated private repo for the store itself is fine.)

Part of Engramory.

Why a plugin, when an AGENTS.md block already works

The block does carry the discipline, and for recall that is enough. Two things it cannot do:

The cap becomes deterministic. Engramory keeps its index under 200 lines / 25 KB because the index loads every session and everything past the cap silently stops being recalled. On most hosts that limit is rules plus a checker the agent has to remember to run. dsh exposes ctx.tools.guard() — a synchronous, monotonic refusal: once a guard returns a reason, no later listener can turn it back into an allow. So here the limit is enforced, not requested. Use 0.2.1 or later: 0.2.0 shipped before profile installs worked upstream and carried an inject declaration this Cordis does not accept — it installed but never activated (issue #8). Outside Claude Code, dsh is the first host with the shim actually written (a few others expose equivalent pre-write seams — see PORTING.md — but have no shim yet).

The protocol arrives with the plugin. The skill is registered at runtime through dsh's skill registry — via a reactive ctx.inject(['skills'], …) child, so a profile without a registry still gets the cap and one whose registry activates late still gets the skill — which means it does not depend on landing files in one of the five skill roots dsh scans, a path that is easy to get subtly wrong and fails silently when you do.

Install

dsh plugin --profile <name> add dsh-engramory

That is the whole install. The package ships a dsh.bundle manifest pointing at its own cordis.patch.yml, so the row is inserted into the profile's plugin tree for you — no hand-editing. To change a default, patch the EXISTING row by id in your profile's own patch layer — do not use a second - insert: (insert always appends, so you would end up with two engramory rows and the original caps still enforced):

- id: engramory
  config:
    indexName: MEMORY.md
    maxLines: 200
    maxBytes: 25600

A patch replaces the targeted row's whole config, so list every key you mean to keep.

For the store itself and the always-on block, use the installer in the Engramory repo (python tools/engramory_init.py dsh --install-skill). This plugin enforces the cap and supplies the protocol; it does not create the store.

Configuration

Field	Default	Meaning
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.
maxLines	200	Hard line cap. Non-positive or non-finite values fall back to the default.
maxBytes	25600	Hard UTF-8 byte cap (25 KB).
indexPath	unset	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.
registerSkill	true	Set false to keep the cap but skip the runtime skill.
skill	built-in	Replace the skill body with your own markdown.

What the guard actually does

Call	Decision
write (or str_replace_editor create) ending within caps	allow
write/create that GROWS the index past a cap	deny, naming the numbers and what to compact
write/create that SHRINKS or keeps an over-cap index	allow — incremental compaction (210 → 205 → 198) must stay possible
Edit carrying old_str/new_str: result simulated	judged by the RESULT, same grow/shrink rule as a write
Unsimulable partial (e.g. insert) on an over-cap index	deny, telling the agent a shrinking whole-file write passes
Unsimulable partial on a healthy index	allow
read, view, or any unknown tool	allow — recall must never be blocked, even over cap
Any write to any other file	allow — not the guard's business
Missing/unreadable current index on a whole-file write	treated as EMPTY (mirrors the Python guard) — a within-caps write passes, an over-cap first write is refused
Missing/unreadable index on a partial edit	allow — a guard must never block work over a path it cannot read
Malformed execution (no arguments, non-string path/content)	allow — not recognisably a write

The deny rule mirrors hooks/engramory_index_guard.py exactly: refuse only a result that is over a cap AND grew past the current file. The line count ignores a trailing newline, so an index sitting exactly at the cap stays writable.

Known limits

• An unsimulable partial that crosses the cap from under it is not caught. insert and friends do not carry the resulting text. The breach is caught by the next whole-file write, or by engramory_check.py. What is guaranteed: an already-over index cannot be grown further, and a shrinking write always passes.
• The tool roster follows dsh's documented tool-fs contract (write/edit with file_path, str_replace_editor with path) and is deliberately conservative: unknown tools pass.
• 0.2.0 never activated; 0.2.1 is the first version that runs. While the rc.6 preview bug blocked all third-party profile installs upstream, the only coverage a plugin could have was mocks — and 0.2.0's mock hid two activation bugs: an older-Cordis { required, optional } inject shape (read as waiting for services literally named required/optional, pending forever) and a bare ctx.skills read of an undeclared service (throws under Cordis' reflective context). The first field install caught both the moment installs became possible (issue #8). 0.2.1 fixes them, verified end to end on a live dsh 0.1.0-rc.7 web profile (0.2.0 reproduces the boot failure byte for byte; 0.2.1 boots and serves) and against the vendored @deepseek-ai/cordis resolver (activation with, without, and with a late-mounted skill registry). The test mock now mirrors the reflective-context access rules, and the guard's decision table stays covered by node --test (28 cases, run in Engramory's CI).
• Checked against the dsh you are likely running, not only the one it was written on. tests/dsh_e2e/run.py in the Engramory repo installs a dsh release into a throwaway prefix, adds this plugin with dsh plugin add, and drives one headless task against a scripted stand-in for the DeepSeek API: a 260-line write and an edit past the cap must come back refused by this guard with nothing reaching the disk, a small write must land byte for byte, the skill must be advertised, every tool dsh offers must already be classified (a new one could write past the cap), and removal must leave a profile that still boots. The releases it passed on are listed in package.json under dsh.compatibility.dshReleases; a unit test rejects a compatible there without a recorded run of the same plugin version and code.
• dsh is a developer preview and its plugin API can change. This plugin deliberately touches only ctx.tools.guard() and a reactive ctx.inject(['skills'], …) child that registers the skill, so it stays cheap to fix.

License

MIT — see the Engramory repository.