dsh-engramory 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Beijing Tinqiao Technology Co., Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# dsh-engramory
+
+Curated, file-based long-term memory for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) —
+plain markdown notes you can read and `git log`, one store shared across every host you
+use, and an index cap that is a **real refusal** rather than a request.
+
+Part of [Engramory](https://github.com/tinqiao-oss/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. Outside Claude Code, this is the only host where that is true.
+
+**The protocol arrives with the plugin.** `ctx.skills.register()` contributes the skill at
+runtime, so 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
+
+```sh
+dsh plugin --profile <name> add dsh-engramory
+```
+
+Then mount it in that profile's `cordis.patch.yml`:
+
+```yaml
+- id: engramory
+  name: dsh-engramory
+  config:
+    indexName: MEMORY.md   # optional
+```
+
+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. 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). |
+| `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` to the index, within caps | allow |
+| `write` to the index, over either cap | **deny**, naming the numbers and what to compact |
+| Partial edit of an index that is already over cap | **deny** — do not grow a breach |
+| Partial edit of a healthy index | allow |
+| Any write to any other file | allow — not the guard's business |
+| Missing/unreadable index, malformed arguments | allow — a guard must never block work by accident |
+
+The line count ignores a trailing newline, matching `hooks/engramory_index_guard.py`, so
+an index sitting exactly at the cap stays writable.
+
+## Known limits
+
+- **An edit that crosses the cap from under it is not caught.** A partial write does not
+  carry the resulting text, and a synchronous guard has no business reconstructing it.
+  The breach is caught by the next whole-file write, or by `engramory_check.py`. What is
+  guaranteed here is that an already-over index cannot be grown further.
+- **Not yet verified end to end inside dsh.** The guard's decision table is covered by
+  `node --test` (13 cases, run in Engramory's CI), and the wiring for the AGENTS.md block
+  and skill discovery was dogfooded against a live `deepseek-v4-flash` session. But
+  installing a *third-party plugin* into a profile currently fails on dsh 0.1.0-rc.6:
+  `dsh plugin` shells out to `pnpm` (not bundled), and a direct `pnpm add` then dies on
+  `ERR_PNPM_FETCH_404` for `@deepseek-ai/dsh-type-meta`, a package the published tree
+  depends on but which is not on the registry. That is a preview-packaging problem
+  upstream, not a plugin defect; this note goes away once a profile install resolves.
+- dsh is a developer preview and its plugin API can change. This plugin deliberately
+  touches only `ctx.tools.guard()` and `ctx.skills.register()` so it stays cheap to fix.
+
+## License
+
+MIT — see the [Engramory repository](https://github.com/tinqiao-oss/engramory).

package/index.js

@@ -0,0 +1,204 @@
+/**
+ * dsh-engramory — the Engramory memory discipline as a DeepSeek Harness plugin.
+ *
+ * Two things the always-on AGENTS.md block cannot do on its own:
+ *
+ *   1. A DETERMINISTIC index cap. dsh's `ctx.tools.guard()` is a synchronous,
+ *      monotonic refusal — once a guard returns a reason, no later waterfall
+ *      listener can turn it back into an allow. That makes it a stronger seam than
+ *      most hosts expose, and it is why the 200-line / 25 KB limit can be enforced
+ *      here rather than merely asked for. Everywhere except Claude Code, Engramory's
+ *      cap degrades to "rules plus a checker the agent has to remember to run".
+ *   2. Skill delivery that does not depend on install paths. Registering at runtime
+ *      sidesteps the five-root scan entirely, so the protocol is present because the
+ *      plugin is loaded, not because a directory happened to be right.
+ *
+ * Zero dependencies, no build step: plain ESM, node: builtins only.
+ */
+import { readFileSync } from 'node:fs'
+import { basename } from 'node:path'
+
+export const name = 'engramory'
+
+// `tools` carries the cap and is required. `skills` is optional so the plugin still
+// loads (and still caps) on a profile that mounts no skill registry.
+export const inject = { required: ['tools'], optional: ['skills'] }
+
+/** Mirrors hooks/engramory_index_guard.py — the caps are the protocol's, not this port's. */
+const DEFAULT_MAX_LINES = 200
+const DEFAULT_MAX_BYTES = 25600
+
+/** Tools that replace a file wholesale, so `arguments.content` IS the post-write text. */
+const WHOLE_FILE_WRITES = new Set(['write'])
+
+export function apply(ctx, config = {}) {
+  const settings = {
+    indexName: config.indexName ?? 'MEMORY.md',
+    maxLines: positive(config.maxLines, DEFAULT_MAX_LINES),
+    maxBytes: positive(config.maxBytes, DEFAULT_MAX_BYTES),
+  }
+
+  ctx.tools.guard((exec) => refuseOversizedIndex(exec, settings))
+
+  if (ctx.skills && config.registerSkill !== false) {
+    const skill = config.skill ?? builtinSkillBody()
+    ctx.skills.register({
+      name: 'engramory',
+      description:
+        'Curated file-based long-term memory: recall through MEMORY.md at the start of ' +
+        'a task, save durable user/feedback/project/reference facts, and sync before ' +
+        'compacting or opening a fresh thread.',
+      whenToUse:
+        'Starting or resuming work, learning something durable worth a future session, ' +
+        'or approaching a compact/clear/new-thread boundary.',
+      source: 'runtime',
+      content: skill,
+    })
+  }
+}
+
+/**
+ * The cap itself. Returning a string denies the call; `undefined` lets it through.
+ *
+ * Guards are synchronous by contract, so this stays cheap: one basename comparison
+ * rejects the overwhelming majority of calls before anything is measured, and the
+ * only I/O is a single read of the index on a partial write.
+ */
+function refuseOversizedIndex(exec, settings) {
+  const args = exec?.arguments
+  if (!args || typeof args !== 'object') return undefined
+
+  const filePath = args.file_path
+  if (typeof filePath !== 'string' || basename(filePath) !== settings.indexName) {
+    return undefined
+  }
+
+  if (WHOLE_FILE_WRITES.has(exec.name)) {
+    if (typeof args.content !== 'string') return undefined
+    return verdictFor(args.content, filePath, settings)
+  }
+
+  // A partial write (an edit / replace) does not carry the resulting text, and a
+  // guard must not do expensive work to reconstruct it. The honest, cheap rule: if
+  // the index is ALREADY over, refuse to grow it further. An edit that crosses the
+  // line from under it still gets through here — engramory_check.py is the backstop,
+  // and the next whole-file write is caught exactly.
+  const current = readIfPossible(filePath)
+  if (current === undefined) return undefined
+  const breach = measure(current, settings)
+  if (!breach) return undefined
+  return (
+    `${settings.indexName} is already over the Engramory cap (${breach}). ` +
+    `Editing it further would push it deeper past the limit. Compact it first: ` +
+    `pointer-ify over-long lines, merge duplicates, and archive cold notes — the ` +
+    `index is a table of contents, and anything past the cap silently stops being ` +
+    `recalled.`
+  )
+}
+
+function verdictFor(text, filePath, settings) {
+  const breach = measure(text, settings)
+  if (!breach) return undefined
+  return (
+    `This write would put ${basename(filePath)} over the Engramory index cap ` +
+    `(${breach}). The index is loaded every session and the host only reads so far, ` +
+    `so anything past the cap silently stops being recalled. Compact before writing: ` +
+    `move detail into the linked note files, merge duplicates, archive cold notes, ` +
+    `and keep every line to "one short hook + link".`
+  )
+}
+
+/** Returns a human-readable breach description, or `null` when the text is within caps. */
+function measure(text, { maxLines, maxBytes }) {
+  const lines = countLines(text)
+  const bytes = Buffer.byteLength(text, 'utf8')
+  const over = []
+  if (lines > maxLines) over.push(`${lines} lines > ${maxLines}`)
+  if (bytes > maxBytes) over.push(`${bytes} bytes > ${maxBytes}`)
+  return over.length ? over.join(', ') : null
+}
+
+/** Trailing-newline-insensitive, matching how the Python guard counts. */
+function countLines(text) {
+  if (!text) return 0
+  return text.split('\n').length - (text.endsWith('\n') ? 1 : 0)
+}
+
+/**
+ * A missing or unreadable index is not a breach: the guard's job is to stop an
+ * oversized index, never to block work because a path could not be read.
+ */
+function readIfPossible(filePath) {
+  try {
+    return readFileSync(filePath, 'utf8')
+  } catch {
+    return undefined
+  }
+}
+
+function positive(value, fallback) {
+  return Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback
+}
+
+/**
+ * The always-on block states the discipline; this is the on-demand detail the model
+ * pulls when it is actually about to recall, write, or sync. Kept deliberately short —
+ * the full protocol is SKILL.md in the Engramory repo, and a skill body that has to be
+ * read before it is useful is a skill that will not be read.
+ */
+function builtinSkillBody() {
+  return [
+    '# Engramory — curated file-based memory',
+    '',
+    'One canonical store: `MEMORY.md` is an index of pointers, one line per memory;',
+    'each fact lives in its own small markdown file beside it. Never put content in',
+    'the index, and never keep a second parallel store for handoffs.',
+    '',
+    '## Recall',
+    '',
+    'At the start of a task, read the index and open only the notes whose hooks look',
+    'relevant. Treat what you recall as background that may be stale: re-verify any',
+    'file, flag, or version against the repo before acting on it.',
+    '',
+    '## Write',
+    '',
+    'Before writing, confirm the fact is not already in the repo, git history, or the',
+    'instruction files, and that it is not a secret value. Search the index and update',
+    'an existing note rather than adding a near-duplicate. A new note is one atomic',
+    'fact with frontmatter:',
+    '',
+    '```markdown',
+    '---',
+    'name: <kebab-case-slug>',
+    'description: <one sharp line — this is what future-you reads to decide to open it>',
+    'type: user | feedback | project | reference',
+    'scope: global | repo        # optional: does this still hold in another repo?',
+    'created: YYYY-MM-DD',
+    'updated: YYYY-MM-DD',
+    '---',
+    '```',
+    '',
+    '`feedback` and `project` notes MUST carry a `**Why:**` line and a',
+    '`**How to apply:**` line. Add exactly one pointer line to the index, and delete',
+    'memories that turn out to be wrong.',
+    '',
+    'Store settled facts, never current state: "2.0 shipped on 2026-01-15" is durable;',
+    '"the current version is X", the tip commit, or a passing test count will rot —',
+    'record where to read those instead.',
+    '',
+    '## Sync',
+    '',
+    'Before a deliberate compact, clear, or new thread: scan the task, dedup and update,',
+    'refresh project state, promote only reusable feedback, retire completed transient',
+    'state, then report what was added, updated, archived, and skipped.',
+    '',
+    '## The cap is enforced here',
+    '',
+    'This host denies a write that would push the index past 200 lines / 25 KB. That is',
+    'a real refusal, not a warning: compact first — the index is loaded every session,',
+    'and anything past the cap silently stops being recalled.',
+    '',
+    'Never write credentials, keys, tokens, or cookies into memory — record only where',
+    'the secret lives.',
+  ].join('\n')
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "dsh-engramory",
+  "version": "0.1.0",
+  "description": "Curated file-based long-term memory for DeepSeek Harness — human-readable markdown notes, one git-versioned store shared across hosts, and a deterministic index cap enforced by ctx.tools.guard()",
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "dsh",
+    "memory",
+    "agent-memory",
+    "long-term-memory",
+    "engramory",
+    "markdown"
+  ],
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tinqiao-oss/engramory.git",
+    "directory": "adapters/dsh/plugin"
+  },
+  "homepage": "https://github.com/tinqiao-oss/engramory/tree/master/adapters/dsh#readme",
+  "bugs": {
+    "url": "https://github.com/tinqiao-oss/engramory/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-tools": ">=0.0.1-rc.1"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-tools": {
+      "optional": false
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}