dsh-memoryos

dsh-memoryos

English | 中文用户：查看通俗版说明

Evidence-first long-term project memory for DeepSeek Harness (DSH), powered by
MemoryOS.

dsh-memoryos is a plain-JavaScript DSH Bundle. It adds scoped project-memory
tools and exact Provider-usage collection without moving MemoryOS persistence,
retrieval, truth resolution, or context compilation into the Agent process.

Compatibility is intentionally pinned to DeepSeek Harness 0.1.0-rc.5 at
commit 47f943859bef60e4160492346772ded9b24f765a. DSH is a developer preview;
re-run Loader and contract acceptance before upgrading it.

Why this plugin

• A true no_memory arm exposes zero MemoryOS tool schemas while retaining the
  same model-invisible usage collector.
• Users can type “关闭 OS”, “开启 OS”, or ask whether MemoryOS is active; the
  model calls a dedicated control tool and the choice survives DSH restarts.
• Full, compact, progressive, explain, and delta context modes share one
  repository-scoped MemoryOS service.
• An explicit write profile can capture atomic, source-backed decisions across
  sessions and resolve updates with supersede, keep_both, or reject.
• Provider-exact input/output/cache usage stays separate from estimated
  MemoryOS component attribution.
• Defaults remain read-only. Evaluation writes and controlled context eviction
  require explicit opt-in.

Evidence-first differentiation

Many DSH memory plugins already have useful unit, integration, smoke, or package
verification. dsh-memoryos does not claim that having tests is unique. Its
focus is a stricter layer of controlled real-Agent evidence around the memory
claims themselves:

• a true no_memory baseline with zero model-visible MemoryOS schemas;
• normal development conversations where the Agent must write memory through
  the plugin rather than controller-side seeding or repair;
• hard restarts of the Agent/MCP/MemoryOS process chain followed by fresh-session
  recall from persistent storage;
• wrong-scope negative controls that must recover none of the target canaries;
• Current Truth update tests where a newer fact supersedes an older fact and a
  fresh session receives only the active truth;
• controlled context-eviction A/B tests proving the original turn is absent from
  retained history before comparing no_memory with MemoryOS recall;
• Provider-exact input/output/cache usage recorded separately from estimated
  MemoryOS schema and visible-memory attribution;
• explicit claim boundaries: a passing memory mechanism is not relabeled as a
  generalized coding-success or token-efficiency improvement without matching
  evidence.

The goal is not to win by feature count. It is to make each memory claim
reproducible, falsifiable, and scoped to the evidence that actually passed.

Install

1. Run MemoryOS

This Bundle is the DSH adapter, not the database. Start MemoryOS 2.3 locally and
keep its bearer token private. From a MemoryOS source checkout:

python -m memoryos --data-dir ./data serve --port 8000 --no-open

2. Install the DSH Bundle

Use a release tag for reproducibility:

dsh plugin --profile memoryos add github:tianhao8687/dsh-memoryos#v0.2.0
dsh --profile memoryos --dump-config

For higher-assurance deployments, replace the tag with the exact audited commit
SHA. Git installs execute package lifecycle code; review and pin third-party
plugins before installation.

3. Launch with bounded read-only memory

$env:MEMORYOS_BASE_URL = 'http://127.0.0.1:8000'
$env:MEMORYOS_AUTH_TOKEN = '<local-memoryos-token>'
$env:MEMORYOS_CONDITION = 'msc_context_only'
$env:MEMORYOS_BUDGET_TOKENS = '512'
$env:MEMORYOS_MAX_CONTEXT_CALLS = '1'
$env:MEMORYOS_RESPONSE_FORMAT = 'deepseek-compact'
dsh --profile memoryos

An intentionally installed profile starts with MemoryOS on unless its persisted
state says otherwise. After the first successful context fetch, the Agent tells
the user once that MemoryOS has started working and that it can be turned off or
on in chat.

The Bundle never selects or rewrites agent-default-model. Configure the model
and Provider in DSH. It does not read DEEPSEEK_API_KEY; DSH owns that secret.

Modes

Condition	Model-visible memory surface	Intended use
no_memory	None	Matched baseline; usage collection only
legacy_full	Full legacy context	Compatibility experiments
msc_full	Minimum Sufficient Context in one response	General resolved project context
msc_progressive	Compact index plus selective explain	Evidence-heavy or multi-record work
msc_context_only	One argument-free compact context call	Bounded DeepSeek coding sessions
msc_delta / msc_delta_core	Full context followed by delta	Long sessions with changing context

The optional cross-session-write tool profile adds memory_propose and
memory_confirm. Every proposal needs one stable semantic key, one independently
updateable fact, and a conversation excerpt. The repository scope is fixed by
the controller. Keep the default read-only profile for ordinary use unless
the write policy has been reviewed.

Turn MemoryOS on or off in chat

No desktop shortcut or shell command is required. Speak to the Agent normally:

关闭 OS
开启 OS
OS 现在开着吗？

The model must call memoryos_control; the plugin does not merely match and
pretend to obey the text. A normal disable persists the choice and dynamically
removes every MemoryOS context, explain, and write schema. One small control
schema remains so a later “开启 OS” can work. Re-enabling first checks the local
MemoryOS health endpoint and only restores the memory tools if it succeeds.

The strict MEMORYOS_CONDITION=no_memory evaluation arm is different: the
entire component is absent, so it has zero MemoryOS schemas, including no
control tool. Restart that baseline with another condition to enable memory.

Architecture

Cordis component	Mounted when	Model-visible effect
dsh-memoryos/usage	Always	None; records attempts and Provider usage
dsh-memoryos	Any condition except strict no_memory	Always exposes control; dynamically exposes the selected memory tools while on
dsh-memoryos/resume	A resume session id is configured	Replaces the headless runner for controlled continuation

The Bundle communicates only with the configured loopback MemoryOS HTTP
service. SQLite, migrations, retrieval, Current Truth, conflict relations, and
Context Compiler logic remain in MemoryOS. See architecture and coupling.

Model experience

What the model sees

In ordinary off mode, the model receives only memoryos_control, not memory
context or write tools. In strict no_memory, it receives no MemoryOS schema at
all. When enabled, DSH sends the selected schemas; retrieved context becomes
visible only after the model calls a memory tool.

Token effect

Input tokens normally increase because schemas, tool results, and an additional
model turn are real input. Compact mode bounds this overhead; it does not claim
zero cost. Ordinary off mode still sends the small control schema; use strict
no_memory when an A/B arm must have zero MemoryOS schema tokens. In the latest
update/eviction campaign, the three write sessions
recorded 1,794 / 7,779 / 103,687 total schema-estimate / visible-memory-estimate
/ Provider-exact input tokens.

KV-cache effect

Enabling a tool changes the Provider-visible request and therefore its cache
key. The usage collector itself contributes no prompt text or tool schema.

Tested outcomes

• Packaged installation against the locked DSH RC5 profile: 27/27 contract and
  real Loader/HMR tests passed offline, including persistent natural-language
  control, strict zero-schema baseline, and dynamic tool removal/restoration.
• Full plugin acceptance: 14/14 hidden validations passed; 13/14 strict mode
  protocols passed.
• Memory Update: PostgreSQL 17 was superseded by 18; a fresh session returned
  only 18.
• Context Eviction A/B: after the original turn was proven absent from active
  history, no_memory answered “unknown” and MemoryOS recovered Glacier-47.
• Cross-session v1 remains a strict 2/3 campaign, despite all recall, baseline,
  and wrong-scope isolation arms passing. It is not relabeled as 3/3.
• Coding evaluations show useful single-task efficiency signals but do not yet
  prove generalized repair-success improvement.

Read tests, failures, fixes, and claim boundaries.

Configuration

Environment variable	Default	Meaning
MEMORYOS_ENABLED	1	Initial state only when no persisted control state exists; 0 starts in ordinary off mode
MEMORYOS_CONTROL_ENABLED	1	Expose the model-callable on/off/status control tool outside strict no_memory
MEMORYOS_ONBOARDING_NOTICE	1	Ask the Agent to relay the first-success notice once
MEMORYOS_STATE_FILE	OS config directory	Optional per-profile path for persistent switch/onboarding state
MEMORYOS_BASE_URL	http://127.0.0.1:8000	Local MemoryOS endpoint
MEMORYOS_AUTH_TOKEN	none	Local MemoryOS bearer token
MEMORYOS_CONDITION	msc_progressive	Context-delivery condition
MEMORYOS_BUDGET_TOKENS	6000	MemoryOS response budget
MEMORYOS_MAX_CONTEXT_CALLS	unlimited	Per-session context-call ceiling; 0 means unlimited
MEMORYOS_RESPONSE_FORMAT	json	json, deepseek-compact, or progressive compact mode
MEMORYOS_TOOL_PROFILE	read-only	read-only or explicit cross-session-write
MEMORYOS_REPOSITORY	none	Fixed repository scope; required for writes
MEMORYOS_TASK	none	Controller-owned task description
MEMORYOS_TIMEOUT_MS	30000	Local MemoryOS request timeout

Usage-ledger and controlled-eviction variables are evaluation infrastructure;
see cordis.patch.yml and the architecture document before
enabling them.

Verify and remove

node --test tests/contract.test.mjs tests/loader-composition.test.mjs
dsh --profile memoryos --dump-config
dsh plugin --profile memoryos remove dsh-memoryos

The Loader/HMR test runs automatically when DSH_TEST_PROFILE_DIR points to an
installed RC5 profile. Local contributor scripts pack a tarball before install;
a direct directory install becomes a link: dependency and is unsupported.

Known limitations

• Process-wide enablement means concurrent enabled and disabled Agents should
  use separate DSH launches.
• The switch controls subsequent requests. Memory already copied into the
  current chat transcript cannot be retracted; start a new Session when a fully
  clean context is required.
• The default state path is shared by local launches. Set a distinct
  MEMORYOS_STATE_FILE for profiles that need independent switch state.
• The plugin is intentionally coupled to RC5 Cordis lifecycle and event surfaces.
• Profiles without headless-runner can emit a non-fatal missing-entry warning
  for the optional resume overlay during --dump-config; memory tools, usage
  collection, and Loader/HMR composition still pass. The overlay is only needed
  for controlled continuation benchmarks.
• The controlled history-eviction hook is evaluation-only.
• Memory guidance remains evidence, not authority; verify code-related facts in
  the checkout and run tests.

See SECURITY.md, CONTRIBUTING.md, and the
MIT license.