Skip to main content

engramory

165Stars12Forks2Issues0Watchers

Inject Engramory memory discipline

Categories◆ Memory
Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki
Language
Python
License
MIT
Branch
master
agent-memoryai-agentsclaude-codecodexdeepseek-harnessdsh-pluginknowledge-basellm-memory

Install

cmdweb profile
$ dsh plugin --profile web add dsh-engramory

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin tinqiao-oss/engramory for me: review the repository at https://github.com/tinqiao-oss/engramory first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

One-Line Pitch

engramory brings Engramory's memory discipline to DSH: always load a resident rule in the host with "index no more than 200 lines / 25 KB", and make this limit a hard stop that actually rejects (once a rejection reason is returned, subsequent listeners cannot overturn it), while registering a same-named skill with the host to ensure the protocol comes with the plugin.

Core Capabilities

  • Takes the 200 line / 25 KB dual-dimension limit from MEMORY.md as a synchronous rejection rule and embeds it into DSH's pre-write guard; writes that exceed cap and continue to grow are blocked directly
  • Progressive compression always passes: exceeded-cap indexes that are reduced are allowed to write, 210 → 205 → 198 such gradual shrinking can proceed all the way
  • Smart judgment of "read-only vs rewrite": read, view, ls and any unrecognized tools are always allowed; exceeded-cap indexes must still be readable, otherwise compression cannot proceed
  • Automatically simulates reducible partial edits (edit / str_replace with old_str/new_str), rejecting based on simulation results rather than parameter size
  • Full file overwrite and str_replace_editor's create / str_replace / insert commands are all covered; unsimulated partial writes on exceeded-cap indexes are rejected with guidance to use full file overwrite
  • Index filename matches case-insensitively (memory.md equals MEMORY.md on Windows/macOS), but only checks basename, not affecting unrelated files in other same-named directories

Technical Implementation

  • Language: JavaScript (ESM)
  • Key Dependencies: Zero dependencies (only uses node:fs's readFileSync, node:path's basename); declares interface dependency on @deepseek-ai/dsh-tools >=0.0.1-rc.1 through peerDependencies
  • Architecture Pattern: Injects cordis.patch.yml into the profile's plugin tree via dsh.bundle, inserting a line of id: engramory config (with indexName / maxLines / maxBytes defaults); at runtime registers a synchronous pre-write guard via ctx.tools.guard(), and optionally contributes a same-named skill via ctx.skills.register() with source: 'runtime'
  • Entry File: adapters/dsh/plugin/index.js

Use Cases

You run long tasks in DSH and want to use a lightweight local file memory bank (one MEMORY.md index + multiple detail notes) to remember key facts across sessions, but worry about the index getting out of control—the part exceeding the loading window gets silently dropped and can never be recalled. After installing this plugin, out-of-bounds writes are directly rejected, prompting you to compress according to the spec, while normal reads still work. If you only use DSH but other hosts (like Claude Code) already have sufficient native caps, this plugin's role is upgrading the weak guarantee of "rules + model running check tool itself" into a strong guarantee of "tool calls get blocked at the tool layer".

Prerequisites & Compatibility

DependencyMinimum VersionDescription
Node>=18Explicitly declared in adapters/dsh/plugin/package.json#engines.node
DSH Host (@deepseek-ai/dsh-tools)>=0.0.1-rc.1peerDependencies in package.json; runtime requires exposing ctx.tools.guard() and optional ctx.skills.register()
Operating SystemCross-platformNo os restrictions, no native modules; pure ESM, only uses node built-ins fs / path
Native ModulesNoneNo node-gyp, no system C library dependency, runs on all three major OSes
Memory Bank Itself—Plugin doesn't create MEMORY.md or generate AGENTS.md resident rules; run python tools/engramory_init.py dsh --install-skill separately

Installation

dsh plugin --profile web add github:tinqiao-oss/engramory

Configuration Options

The DSH profile's patch layer inserts a line of id: engramory when the plugin loads; its config field is the table below; to customize, override the entire block in your profile with - id: engramory and list all keys you want to keep (patch replaces the whole block rather than merging).

ConfigTypeDescriptionDefault
indexNamestringFile name treated as index (only basename, case-insensitive); guard only applies to it; empty string or non-string falls back to defaultMEMORY.md
maxLinesintegerHard line limit; non-finite or non-positive integer falls back to default200
maxBytesintegerHard UTF-8 byte limit (25 KB); non-finite or non-positive integer falls back to default25600
registerSkillbooleanWhen false, only installs guard, no runtime skill registration (for profiles where host doesn't mount skill registry)true
skillstringCustom skill body markdown; empty uses plugin's built-in slim protocol (includes Recall / Write / Sync / index cap rules)Built-in markdown

FAQ

Q: Does installing this plugin automatically generate my memory bank?

A: No. The plugin only enforces the 200 line / 25 KB limit as a hard stop and registers a skill named engramory with the host; the memory bank and rule files need to be created separately by running python tools/engramory_init.py dsh --install-skill from the Engramory repository.

Q: Can I still compress after the index exceeds the cap?

A: Yes, and you must be able to. The rule is: reject only if the write causes the index to exceed the limit and is larger than the current file—a 210-line index being compressed to 205, then to 198, will all pass; progressive compression is always feasible and won't lock you out.

Q: What do I do when I see a rejection prompt?

A: The rejection reason directly tells you the current line count / byte count and the limit. Split long lines into "one-sentence summary + link", merge duplicate entries, archive cold notes, then use full file overwrite (write or str_replace_editor's create) to compress in one go; the next full file write will pass.

Q: Where do I go to adjust the cap size?

A: Don't add another - insert: in the original profile—that creates two engramory lines and the original caps still take effect. The correct approach is to override that line's config in your profile's own patch layer with - id: engramory, and list all keys you want to keep (patch replaces the whole block).

Q: Does it include native modules?

A: No. The plugin is pure ESM, only uses node:fs and node:path two built-in modules, no node-gyp, doesn't care about Node ABI, runs on all three major operating systems.

Q: Will reading MEMORY.md be blocked?

A: No. The guard only makes decisions on tools known to modify files (write/edit/str_replace etc.); read, view, ls and any unrecognized tools are always allowed—this is by design: exceeded-cap indexes must still be readable, otherwise you'd be stuck in a deadlock of "wanting to compress but can't see the content".

Q: Why does dsh plugin add fail to install on dsh 0.1.0-rc.6?

A: This is an upstream dsh preview packaging issue: the dsh plugin command uses unbundled pnpm, and the dependency @deepseek-ai/dsh-type-meta cannot be found on the registry. Before the fix is released, the plugin's decision table is still guarded by the 21 node --test test cases in the repository, credibility unaffected.

Learning Curve

Beginner — installation is one command; cordis.patch.yml has already injected reasonable default caps into the profile, ordinary users basically don't need to change configuration; only advanced users who want to "change index filename" or "relax the cap" need to touch the patch.

Known Issues & Limitations

  • For partial writes like insert where the result cannot be还原 from parameters, if they jump from "not exceeding cap" to "exceeding cap" in one go, the current guard won't catch it immediately; the next full file overwrite will be blocked, or caught by external engramory_check.py. Partial writes that cannot be simulated on already exceeded-cap indexes will definitely be blocked.
  • The guard's tool whitelist covers dsh's documented tool-fs contracts (write/edit use file_path, str_replace_editor uses path); unknown tools are always allowed; this is a discipline guardrail rather than a security boundary—the cost of wrongly blocking read is far higher than missing one write.
  • DSH is still developer preview, host plugin APIs may change; this plugin only touches ctx.tools.guard() and ctx.skills.register() two surfaces, migration cost is deliberately kept minimal.
  • Third-party plugins installed via dsh plugin command to profiles are not yet usable on dsh 0.1.0-rc.6 (upstream packaging issue, not a plugin defect), during this period can only mount the plugin body directly at source code level.
  • The plugin won't create MEMORY.md or rule files for you—the memory bank itself needs to be initialized separately according to the Engramory protocol.

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/tinqiao-oss/engramory)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory