MemOS Cloud DeepSeek Harness Plugin (Lifecycle)
Official plugin maintained by MemTensor.
English | 中文
A lifecycle bundle for DeepSeek Harness that recalls relevant memories from MemOS Cloud before the model starts the current turn and adds the completed user/assistant turn back to MemOS Cloud afterward.
Features
- Recall: before the first model step of every user turn →
/search/memory
- Add: after that turn ends with
completed → /add/message
- Deterministic filters: user, public, knowledge-base, metadata, tags, and static or preset-based agent isolation
- Lifecycle-native: memory is automatic; the model does not decide whether to call a memory tool
- Fail-open: MemOS errors never interrupt the Harness turn
- Safe capture: excludes system prompts, reasoning, attachments, and plugin context; tool calls/results are included only when
includeToolMemory is enabled
- Uses Token auth (
Authorization: Token <MEMOS_API_KEY>)
Install
The following commands install the plugin into DeepSeek Harness's default web profile.
Option A — NPM (Recommended)
dsh plugin --profile web add @memtensor/memos-cloud-dsh-plugin@latest
If DSH is not installed globally:
npx @deepseek-ai/dsh plugin --profile web add @memtensor/memos-cloud-dsh-plugin@latest
Option B — Package from Source
Run from the monorepo repository root. Install the workspace dependencies, then create the versioned .tgz; packaging does not add the plugin to DSH.
pnpm install --frozen-lockfile
pnpm pack:dsh
dsh plugin --profile web add ".\packages\dsh\artifacts\memtensor-memos-cloud-dsh-plugin-$(node -p "require('./packages/dsh/package.json').version").tgz"
If DSH is not installed globally:
npx @deepseek-ai/dsh plugin --profile web add ".\packages\dsh\artifacts\memtensor-memos-cloud-dsh-plugin-$(node -p "require('./packages/dsh/package.json').version").tgz"
The install command derives the tarball filename from packages/dsh/package.json, so it remains valid after a version change. lib/ is build output; the installable package is the .tgz file under artifacts/.
Remove
dsh plugin --profile web remove @memtensor/memos-cloud-dsh-plugin
If DSH is not installed globally:
npx @deepseek-ai/dsh plugin --profile web remove @memtensor/memos-cloud-dsh-plugin
Start or Restart DSH Web
After installing or removing the plugin, restart DSH Web to reload the web profile. If it is already running, press Ctrl+C in its terminal, then start it again:
npx @deepseek-ai/dsh web
Configuration
1. API Key and User ID via .env (Recommended)
Create a MemOS API key at MemOS Dashboard.
Create or edit ~/.dsh/.env in the DSH configuration directory:
MEMOS_API_KEY=mpg-your-key
MEMOS_USER_ID=your-stable-user-id
Use a stable, distinct MEMOS_USER_ID for each user's memories. The plugin uses this same ID for both recall and add. If it is omitted, the default is deepseek-harness-user.
DSH reads ~/.dsh/.env by default. It also reads .env from the directory where you run the dsh command, which takes precedence.
Restart DSH after changing .env; its environment values are loaded at startup.
Alternatively, store the API key in ~/.dsh/.credentials.yaml under refs. Add it to the existing mapping and preserve other credentials and records:
version: 1
refs:
MEMOS_API_KEY: mpg-your-key
records: {}
Configure the user ID using either MEMOS_USER_ID in .env or memos-cloud.userId in settings.yaml, described below.
2. Plugin Settings
DSH plugin settings file: ~/.dsh/settings.yaml
Minimal config
memos-cloud:
apiKeyEnv: MEMOS_API_KEY
Keep the API key and user ID in .env as shown above; configure ordinary plugin options such as baseURL, recall, and add in settings.yaml.
Configuration precedence
For an option with multiple supported sources, precedence is, highest first: values entered directly in settings.yaml → inherited process environment → credentials in ~/.dsh/.credentials.yaml → launch-directory .env → ~/.dsh/.env → plugin defaults.
The credentials file applies only to the API key. Set apiKeyEnv to the credential name (default: MEMOS_API_KEY), and store the actual key in .env or .credentials.yaml.
Optional config
apiKeyEnv (default: MEMOS_API_KEY; Harness credential reference)baseURL (default: https://memos.memtensor.cn/api/openmem/v1; MemOS API root)userId (default: MEMOS_USER_ID, then deepseek-harness-user; stable shared read/write user namespace)recallEnabled (default: true; search before the first model step of each user turn)addEnabled (default: true; add after the current turn ends with completed)includeAssistant (default: true; include assistant text in add)includeSubagents (default: false; process sessions with origin: subagent)multiAgentMode (default: false; use the stable DSH agentPreset as agent_id, falling back to agentId when no preset exists)queryPrefix (default: empty; text prepended to every recall query)recallGlobal (default: false; omit conversation_id and search the user's memories globally)memoryLimitNumber (default: 6; factual result limit, 1..25)preferenceLimitNumber (default: 6; preference result limit, 1..25)includePreference (default: true; recall preference memories)includeToolMemory (default: false; recall tool memories and add correlated tool calls/results)toolMemoryLimitNumber (default: 6; tool-memory result limit, 1..25)relativity (default: 0.45; semantic threshold, 0..1)filter (optional; ordinary or per-source deterministic filter)knowledgebaseIds (default: []; KB IDs to search; all cannot be mixed with concrete IDs)tags (default: [deepseek-harness]; tags for add)info (default: {}; non-blank string metadata)agentId (optional; add and constrain the user search branch)
How It Works
- Recall (
agent/pre-step): on the first model step of each direct user turn, the plugin calls /search/memory and inserts the results before the user message.
- Add (
turn/end): after a turn ends with completed, the plugin sends the user text, optional assistant text, and—when enabled—correlated tool calls/results to /add/message.
- MemOS failures do not interrupt the Harness turn. Subagent sessions are excluded unless
includeSubagents is enabled.
Shared MemOS API behavior
The private workspace core is also used by the OpenClaw adapter. DSH therefore uses the same Authorization: Token client, request validation, filter construction, timeout handling, retry bounds, safe serialization, response validation, and MemOS tool-message wire types. Search can request factual memories with memoryLimitNumber, preferences with includePreference and preferenceLimitNumber, and tool memories with includeToolMemory and toolMemoryLimitNumber. The response projector keeps these categories separate before DSH inserts the resulting untrusted JSON context.
knowledgebaseIds and filter constrain /search/memory. tags, info, agentId, appId, allowKnowledgebaseIds, asyncMode, and allowPublic are applied to /add/message when configured. maxQueryChars, maxRecallChars, maxItemChars, and maxMessageChars bound text before it crosses the MemOS or host boundary. searchRetries and addRetries remain independently configurable because recall and write failures have different host impact.
DSH adapter boundary
The shared core does not contain DSH lifecycle code. This package alone owns the Cordis credential/settings services, agent/pre-step and turn/end subscriptions, session-to-conversation mapping, DSH message/tool conversion, preset-based agent attribution, capture policy, prompt insertion, and serialized write queue. OpenClaw-only configuration UI, per-agent overrides, and model-based second-pass recall filtering are not implied by the shared MemOS API layer.
When multiAgentMode is enabled, both search and add use session.header.agentPreset as agent_id. DSH deployments such as the headless profile may create sessions without a preset; those sessions use the explicitly configured agentId, or omit agent_id when no fallback is configured. A subagent joined to its parent's preset shares that preset-level memory partition while keeping its own conversation_id.
Because the preset selects agent_id per Session, do not also set a fixed agent_id inside filter when multiAgentMode is enabled; configuration validation rejects that conflicting combination.
Compatibility
- DeepSeek Harness: tested with
0.1.2-rc.1 and 0.1.0-rc.6
- Node.js:
^22.19.0 || >=24.0.0
- MemOS Cloud API:
/api/openmem/v1
Harness is a developer preview. Re-run the full tests and a live smoke after upgrading it.
Security and Privacy
- Recall JSON escapes
< and is labeled untrusted, read-only background data.
- Instructions, permission claims, and tool requests inside memory are never executed by the plugin.
- The plugin never uploads cwd, full configuration, system prompts, reasoning, plugin-injected context, or attachment bytes. Tool arguments and textual results are uploaded only when
includeToolMemory is enabled; non-text results use an omission marker, and an over-budget argument omits its whole correlated tool pair instead of emitting invalid JSON.
- Original DSH message IDs and event timestamps are preserved.
- Public writes remain disabled unless
allowPublic is explicitly enabled.
- Warnings omit API keys, authorization headers, and request bodies.
