dsh-bmpp
Basic Memory Policy Plugin：DeepSeek Harness (DSH) 的机械式、可验证记忆策略层
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:rafa-elricardo/bmpp#9ef147b79a2bf659ac22e7dc1a1b0b64c5fd4cbdBmpp 以 dsh-bmpp 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
A native DeepSeek Harness (DSH) plugin that moves the mechanically checkable part of an agent's memory policy into the runtime, while leaving every semantic decision to the model.
Status: experimental / alpha. BMPP works and is covered by an automated test suite, but its API and configuration model may still change between releases. It is not a production-hardened product and it is not affiliated with or endorsed by the DeepSeek project.
An agent that uses a memory system has a policy for it: search before you write, do not duplicate an existing note, do not trust a recalled value without checking the live system. Some of that policy can only be judged by a model — whether a memory is worth keeping, whether a note already covers it, whether a recalled fact is still true. BMPP does not touch that part. It leaves semantic judgement where it belongs and never reads note content or user text.
The rest of the policy is mechanical: did a memory search actually complete before this write? did that search fail? is this the same write twice in one turn? Those questions are answered by events the runtime already emits, so BMPP decides them deterministically and enforces them.
BMPP sits between the model and the
mcp__basic-memory__* tools. When the model tries
to change memory, BMPP checks the preconditions and either lets the call through or blocks it with an
explanation the model can act on.
Scope: BMPP governs only the mcp__basic-memory__* namespace. It does not block bash, edit,
write, the filesystem, or any other tool, and it is not a general agent-security policy.
Every turn has a classification, and BMPP's gate is a function of it.
| Classification | Meaning | Effect on memory writes | Effect on reads |
|---|---|---|---|
unknown | the model has not declared anything yet | blocked | allowed |
simple | the model declared the turn trivial | allowed, no lookup required | allowed |
complex | the model declared the turn needs memory | allowed only after a successful lookup in the same turn | allowed |
The model declares the classification with BMPP's own control tool, bmpp__classify:
{"task": "complex"}
It may be called at any point in the turn — it does not have to be the first call — and a turn that
never declares anything stays unknown, which permits reads and blocks writes.
Recall. For a complex turn BMPP watches the memory search tools
(search_notes, search, build_context). A search that completes successfully satisfies the
recall precondition; a search that fails leaves the gate closed and the model is told to retry. BMPP
does not parse the search results — it reads the structured error flag the runtime already provides,
so an honest empty result still counts as a completed lookup.
The mutation gate. A memory write is checked against, in order:
unknown → blocked);Every decision carries a stable reason code (CLASSIFICATION_REQUIRED,
CREATE_REQUIRES_SEARCH, MEMORY_LOOKUP_REQUIRED, MEMORY_LOOKUP_FAILED,
MEMORY_LOOKUP_PENDING_IN_BATCH, OVERWRITE_REQUIRES_READ, …) so a blocked call is explained rather
than swallowed.
Turn lifecycle. BMPP's state is per session and per turn. When the Harness turn advances, the previous turn's classification and recall state are discarded, so authority earned in one turn is never reused in the next. Sessions BMPP has not judged are not affected at all.
mode decides whether the verdict is applied or merely recorded.
| Mode | Decides | Applies | Can deny or ask? |
|---|---|---|---|
off | no | no | no — registers nothing |
audit | yes | no | never — every call proceeds, and the denial it wanted is recorded |
enforce | yes | yes | yes — the only mode that blocks |
audit never blocks, whatever the profile says. It is the safe first step: you get the complete
evidence of what BMPP would have done, with no behaviour change.
profile decides how rigorous the policy is. It never changes mode.
| Profile | Effect |
|---|---|
compat | secondary guards warn; destructive operations go through the normal gate |
strict | secondary guards deny; destructive operations ask for approval instead of denying outright |
Only three options differ between the profiles. Everything else — including when unknown blocks
writes and when a create requires a search — is identical in both.
Defaults: mode: audit + profile: compat.
BMPP 0.1.0 → DSH >= 0.1.5-rc.2 < 0.2.0
| Range | >=0.1.5-rc.2 <0.2.0 |
| Verified | 0.1.5-rc.2, 0.1.6-alpha.1 |
Compatibility is declared as an explicit envelope in package.json (dsh.compatibility) and
src/version.ts. At load, BMPP detects the running Harness version and classifies it:
The verified list is evidence, not a second barrier — adding a version to it changes no
behaviour, only the reported status. BMPP also probes the injected tools service for the exact
methods it programs against, so a Harness that changed its tool-registry surface fails loudly at load
instead of mis-enforcing later.
See docs/COMPATIBILITY.md for the full strategy.
BMPP is a DSH bundle (a package whose package.json declares dsh.bundle.patch), and it can
also be loaded without installing anything.
A --patch overlay contributes configuration only, so an uninstalled checkout can be loaded by
absolute path — nothing is written into a profile:
dsh --profile bmpp-dev --patch /absolute/path/to/bmpp/overlay.dev.cordis.yml "<task>"
The overlay is machine-local and gitignored. examples/ holds distributable configuration snippets.
# from a local checkout or a packed tarball
pnpm run build && pnpm pack
dsh plugin --profile <profile> add ./dsh-bmpp-0.1.0.tgz
dsh plugin add runs pnpm inside the profile, links the package and appends the bundle to the
profile's ordered bundle list. BMPP is not yet published to a package registry, so a local path
or tarball is how you install it today.
Mechanism, alternatives and the reasoning behind the bundle form: docs/DISTRIBUTION.md.
Two independent dimensions, configured in one row. There is no strict boolean and no second way to
set the same thing.
- insert:
- id: bmpp
name: 'dsh-bmpp'
config:
mode: audit # off | audit | enforce
profile: compat # compat | strict
The schema rejects unknown keys and invalid values at load, so a typo fails the boot rather than silently disabling a guard.
examples/ contains a ready snippet per combination: config.off.yml, config.audit.yml,
config.enforce.yml, config.strict.yml.
A turn that never classifies → writes are blocked, reads are not.
model: mcp__basic-memory__read_note { identifier: "some-note" }
→ allowed (reads are never blocked)
model: mcp__basic-memory__write_note { title: "New note", … }
→ denied CLASSIFICATION_REQUIRED
→ "this turn has not been classified … call bmpp__classify first"
A simple turn → writes are allowed with no lookup.
model: bmpp__classify { task: "simple" }
→ allowed ALLOW_CONTROL
model: mcp__basic-memory__write_note { title: "New note", … }
→ allowed ALLOW_SIMPLE
A complex turn that writes without searching → blocked.
model: bmpp__classify { task: "complex" }
→ allowed ALLOW_CONTROL
model: mcp__basic-memory__write_note { title: "New note", … }
→ denied CREATE_REQUIRES_SEARCH
→ "creating a note requires searching for the subject first … Search, then retry."
A complex turn that searches first → the write is allowed.
model: bmpp__classify { task: "complex" }
→ allowed ALLOW_CONTROL
model: mcp__basic-memory__search_notes { query: "…" }
→ allowed ALLOW_READ_ONLY
→ recall settled: succeeded
model: mcp__basic-memory__write_note { title: "New note", … }
→ allowed ALLOW_RECALL_OK
In
mode: auditevery one of the "denied" lines above is recorded as a denial and still allowed. Real blocking requiresmode: enforce.
BMPP is a Cordis plugin registered through the Harness's public plugin API. It consumes the Harness as a dependency and never forks it.
| Piece | Role |
|---|---|
src/state.ts | the pure policy state machine: decide() returns the verdict, the reason and a decision event. mode and profile are deliberately absent from its inputs, so the machine cannot be influenced by enforcement settings. |
src/gate.ts | the integration layer: subscribes to tools/pre-execute and tools/result, resolves the current turn, applies mode/profile after the verdict, and registers the bmpp__classify control tool. |
src/config.ts | the validated mode × profile model and the tool-class lists. |
src/version.ts | BMPP's own version line and the Harness compatibility envelope, detection and classification. |
src/audit-sink.ts, src/audit-store.ts | the audit record schema and the durable sidecar store. |
src/index.ts | the Cordis entry point: configuration validation, the load-time surface probe, the compatibility decision, and mounting. |
Tool interception. BMPP classifies a call by the tool name it already receives. Calls outside the
memory namespace are delegated untouched; reads are allowed; writes and destructive operations are
gated. It inspects tool arguments only as far as a guard needs (a target path and an overwrite
flag), and never the note content.
Turn lifecycle. The current Harness turn is read from the sessionProjections service when the
host provides one, and from an internal counter otherwise. Advancing the turn discards the previous
turn's classification and recall state.
Host version detection. The Harness exposes no version service on its context, so BMPP reads the
version from the application manifest of the process hosting it — the running entry point's own
package.json — and falls back to a Harness identity package resolved from that entry. Anchoring on
the entry point matters: resolving from BMPP's own module would read BMPP's own pinned dependency
and report the development dependency as the host version.
No value imports from the Harness. Every @deepseek-ai/* import in emitted code is a type import
and is erased at compile time; runtime access goes through the injected context. A test asserts this
against the built output, which is what makes BMPP genuinely standalone rather than a fragment of the
Harness monorepo.
BMPP records every decision — the verdict, its reason code, the tool class, the policy state, the enforcement outcome, the turn and the classification. It records metadata only: no tool arguments, no note content, no user text.
The audit is not written to the DSH session event log. It lives in a storage sidecar: a
plugin-owned domain (bmpp_audit, version 1, per-record layout) opened through the Harness's public
storageDomain service, which stores it under $DSH_HOME/storages/bmpp_audit/.
This matters for a concrete reason. A session event type the Harness does not know is
required-on-read: a reader meeting an unrecognized event must refuse to reconstruct the session
rather than silently skip it, and the public Session.append API offers no way for a plugin to mark
its own event type as safe to omit. Writing a plugin-invented type into the session log therefore
made every audited session unobservable and unresumable. Keeping the audit in its own domain leaves
the session log interpretable by any Harness build, and keeps the audit durable and queryable.
Storage is an optional dependency. If a composition mounts no storage service, BMPP still enforces every rule and reports the records it could not persist; a logging outage never becomes a policy outage, and a failed audit never turns an allow into a deny.
Honest, current-state limitations:
mcp__basic-memory__* and nothing else.ok or failed. Basic Memory advertises no output schema for its search
tools, so an empty but successful search is indistinguishable from a populated one. BMPP refuses
to parse result text to guess; RECALL_EMPTY stays modelled but is unreachable.tools/emit-policy-stream.mts and
tools/bmpp_verify.py were written against an earlier design in which the audit was a
bmpp/policy session event. Since the audit moved to the storage sidecar, that layer reads no
events and verifies nothing. The TypeScript suites are the authoritative verification today.pnpm install
pnpm run typecheck
pnpm test
pnpm run build # emits lib/, which is never committed
Requires Node.js ^22.19.0 || >=24.0.0 and pnpm. pnpm test also builds the project, because one
suite inspects the emitted JavaScript to prove the plugin imports no Harness value.
See CONTRIBUTING.md for how to propose changes.
BMPP is developed using AI-assisted workflows, including LLM-assisted implementation, testing, debugging and documentation, in an iterative ("vibe coding") style. This is stated plainly because it is true and because it is relevant to how you should evaluate the project.
It is not offered as a quality guarantee in either direction. What the project relies on instead is verifiable behaviour: a test suite that exercises the real tool registry, a compatibility envelope that fails loudly rather than silently mis-enforcing, and the documented limitations above. Treat the tests, not the prose, as the claim.
See SECURITY.md for how to report a vulnerability. Please do not open a public issue for a security problem.
See CONTRIBUTING.md. Contributions are welcome, including issues about behaviour you think the policy gets wrong.
MIT — see LICENSE.
BMPP is an independent third-party plugin. It is not part of the DeepSeek Harness repository, and it is not affiliated with or endorsed by the DeepSeek project.
Uma versão em português deste README está em README.pt-BR.md.