XMemo for DeepSeek Harness

Native local-first + cloud memory for dsh.

Hybrid local storage with an offline durable write queue, plus real OAuth 2.1 login — reimplemented as an ordinary Cordis plugin instead of a thin MCP bridge.

Quick start · Auth · Config · Web GUI card · Tools · Capabilities · Limitations

A native DeepSeek Harness (dsh) plugin: hybrid local + XMemo cloud memory, with offline durable write queuing, active state, timeline, TODOs, decisions, and restart snapshots — the same tool surface as xmemo-cindy-plugin, reimplemented as an ordinary Cordis plugin instead of going through Cindy's host-specific plugin protocol.

This plugin talks directly to the MemoryOS REST API (the actual backend behind XMemo) and keeps its own local store, rather than going through XMemo's hosted MCP server (https://xmemo.dev/mcp) — dsh can also reach XMemo the MCP way via the harness's own @deepseek-ai/dsh-mcp-client bridge, but this repo is the deeper, native alternative. Endpoint paths, request/response field names, and the auth header were verified against the MemoryOS source, not guessed from another client — including live, end-to-end verification of the OAuth flow against production xmemo.dev.

[!NOTE] DeepSeek Harness itself is a developer preview. This plugin has been exercised locally against production xmemo.dev (unit tests, a live web GUI session, and a real OAuth registration + authorize round trip) but has not seen broad multi-user usage yet.

At a glance

What it adds

• Focused recall — local token-overlap matches merged with cloud recall, fail-closed on any bucket/scope mismatch.
• Durable outcomes — remember decisions, preferences, and facts; record timeline events; track TODOs and decisions.
• Working continuity — active task state and restart snapshots so a session can resume instead of replaying history.
• Offline resilience — every write lands locally first; safe (idempotent) writes replay to the cloud automatically, uncertain ones wait for explicit approval.
• Real account login — OAuth 2.1 + PKCE against XMemo's actual authorization server, not just a pasted API key.
• Recoverable deletion — xmemo_forget defaults to a soft, recoverable delete.

Quick start

dsh plugin --profile <name> add dsh-xmemo
# or, to track main instead of the latest npm release:
dsh plugin --profile <name> add github:yonro/xmemo-deepseek-plugin
# or, from a local checkout:
dsh plugin --profile <name> add ./xmemo-deepseek-plugin

A git install fetches source, not the built lib/, so pnpm blocks this package's prepare script (which builds both halves — see Development) on the first add and prints the exact key to allow. Add it to the profile's pnpm-workspace.yaml and re-run add:

allowBuilds:
  dsh-xmemo: true

Connect an XMemo account or set an API key (see Auth below), then verify the row loaded:

dsh --profile <name> --dump-config   # look for "# == dsh-xmemo"

Auth

Two methods, resolved in this order on every request (src/auth.ts) — never both at once:

1. OAuth 2.1 + PKCE (recommended). Connect from the web GUI's plugin card (see Web GUI card) or trigger it programmatically by writing a connect:<anything> value to the XMEMO_OAUTH_ACTION credential — src/oauth.ts listens for this via the seam-wide credentials/updated event. Connecting: registers a fresh public OAuth client through MemoryOS's Dynamic Client Registration (POST /oauth/register, one per connect attempt — cheap, and avoids caching a client_id with its own staleness edge cases), opens your default browser to /oauth/authorize with a PKCE challenge, and runs a temporary 127.0.0.1:<ephemeral-port> HTTP listener as the redirect target — the same loopback-native-app pattern MemoryOS documents for Cindy's desktop OAuth flow (verified live against production xmemo.dev: DCR accepts a brand-new client's loopback redirect_uri, and /oauth/authorize accepts that client_id + PKCE + explicit resource end to end). The resulting access/refresh token pair is stored under the XMEMO_OAUTH credential reference and refreshed automatically (with rotation — a used refresh token is never replayed) a minute before it expires. Disconnect the same way with a disconnect:<anything> value, which also revokes both tokens server-side.
2. Static API key (fallback). Set the XMEMO_KEY credential through dsh's own credential seam — any of an environment variable (XMEMO_KEY=... dsh --profile <name>), $DSH_HOME/.credentials.yaml (XMEMO_KEY: ...), or <project>/.env / $DSH_HOME/.env. Sent as the X-API-Key header (MemoryOS's primary auth header — Authorization: Bearer is only its fallback; see auth/api_key.py). The credential reference name is configurable (apiKeyCredential in cordis.patch.yml) if you'd rather not use XMEMO_KEY.

Unlike Cindy, whose host runs the OAuth dance generically for any plugin that declares an "OAuth credential source," dsh has no such primitive (see Known Limitations) — this plugin runs the whole flow itself in src/oauth.ts, with no deepseek-harness changes required.

Config

Set in this bundle's cordis.patch.yml, or override per-profile/home cordis.patch.yml:

mode is resolved per tool call (src/mode.ts, mirroring how src/auth.ts resolves the API key) rather than read once at boot: a hybrid/local-only/cloud-only value stored under the XMEMO_MODE credential reference wins over the cordis.patch.yml default, so a change saved through the web GUI's mode selector reaches the very next tool call without a restart.

Tools

xmemo_status, xmemo_update_state, xmemo_record_event, xmemo_list_timeline, xmemo_remember, xmemo_recall, xmemo_forget, xmemo_create_todo, xmemo_list_todos, xmemo_complete_todo, xmemo_create_decision, xmemo_list_decisions, xmemo_resolve_decision, xmemo_save_progress, xmemo_restore_progress, xmemo_sync — same names, schemas, and behavior as xmemo-cindy-plugin's tool surface.

Skill instructions (when to call which tool) are intentionally not part of this package — reuse xmemo-claude-plugin/skills/*/SKILL.md as-is by dropping them into a project's .agents/skills/; dsh's skill-filesystem provider discovers the same frontmatter format from that directory.

Web GUI card

The dsh --profile web GUI's Settings → 插件配置 (Plugin Config) panel shows an "XMemo" card alongside the first-party Bash/Agent-loop/Web-search cards, via a browser bundle this same package ships (src/client/, built to lib/client.js, declared through the dsh.client manifest field in package.json — no changes to deepseek-harness itself are needed; dsh-client-modules scans every loaded plugin's package.json for that field, not just first-party ones).

Three controls are genuinely live:

• XMemo account login (recommended, shown first) — Connect/Disconnect buttons driving the OAuth flow described in Auth. Its status badge names whichever method is actually in effect — 已连接 · OAuth/Connected · OAuth or 已连接 · API Key/Connected · API key — mirroring auth.ts's own "OAuth first, API key fallback" precedence exactly, and only falls back to 未连接/Not connected when neither is configured, so a working API-key setup never reads as broken just because OAuth hasn't been connected. When both happen to be configured at once, a short note under the button says so and states that OAuth is the one actually being used. Since this card has no direct RPC into host-side code (the same credentials.*-only constraint below), the buttons relay through the write-only XMEMO_OAUTH_ACTION signal credential rather than calling anything directly, then poll credentials.describe('XMEMO_OAUTH') (every 2s, up to ~5.5 minutes) to detect when the browser login completes.
• API key (compatibility fallback) — reflects and can change the actual stored key via real credentials.describe/credentials.set calls, including correctly showing it as read-only when XMEMO_KEY is supplied by the launch environment rather than the credentials store.
• Memory mode — a real <select> (hybrid / local-only / cloud-only) with an explicit Save button, saved under the XMEMO_MODE credential reference and picked up by src/mode.ts on the very next tool call. Unlike the API key field, the select can't show which value is currently stored — credentials.describe deliberately never exposes a credential's value, only whether it's configured (see Known Limitations) — so it always starts from the hybrid default and a "customized"/"default" badge stands in for the value itself, the same way the API key field's "configured" badge never reveals the secret.

The other five config fields (apiBaseUrl/defaultScope/agentId/requestTimeoutMs/ longRequestTimeoutMs) aren't shown in the card at all — their defaults are fine for the vast majority of setups; override them via cordis.patch.yml (see Config) if needed.

Build with npm run build:client (separate from the host build — needs its own tsconfig.client.json and scripts/build-client.mjs, since the host and browser halves target different runtimes).

Architecture notes

Ported from xmemo-cindy-plugin/plugins/xmemo-memory/main.js's business logic:

• src/http.ts — request/error handling (AUTH_REQUIRED, RATE_LIMITED, XMEMO_SERVER_ERROR, …). One structural change from upstream: Cindy's host injected Authorization based on request hostname; this plugin resolves and attaches the auth header itself (src/auth.ts, src/oauth.ts).
• src/store.ts — the local JSON store (schema, prune limits, quota guard, corrupt-file → backup fallback, write-temp-then-rename atomicity).
• src/outbox.ts — the durable write queue: staged → sent | pending | held | failed, idempotent ops auto-retry (5 attempts), non-idempotent ops go straight to held and need an explicit xmemo_sync {action: 'push', include_held: true}, local-id → cloud-id dependency resolution for writes that target an entity that hasn't synced yet (e.g. completing a TODO offline).
• src/recall.ts — local token-overlap scoring merged with cloud recall, including the fail-closed bucket/scope filter (compactCloudRecallItems): a cloud item that doesn't exactly match the request is dropped, and any single violation suppresses all opaque cloud text in that response.
• src/redact.ts — the 7-category credential-like-text redaction, ported verbatim.
• src/oauth.ts — the whole OAuth 2.1 + PKCE client: Dynamic Client Registration, an ephemeral loopback HTTP listener as the redirect target, token exchange/refresh with rotation, and revoke.

One acknowledged divergence: main.js's store is one dynamic JSON blob, so it can replay a queued write generically. This port's store is typed per entity kind, so a replayed write (via xmemo_sync, possibly in a later process) only generically patches cloud_id + sync_status; richer field back-fill happens only on the first attempt, made synchronously inside the same tool call. See the comment at the top of src/outbox.ts.

Capabilities and boundaries

Known Limitations

• No central plugin marketplace exists for dsh by design. Discovery is just the dsh-plugin GitHub topic ("Contribute to the ecosystem" in CONTRIBUTING.md), which this repo is tagged with; there's no submission, review, or PR-based listing process to opt into beyond that.
• OAuth connect needs a desktop with a browser. The flow opens a system browser and waits on a loopback listener for its redirect; a headless dsh instance (no desktop session to open a browser in) can't complete it — use the static API key there instead.
• XMEMO_OAUTH and XMEMO_OAUTH_ACTION appear in $DSH_HOME/.credentials.yaml and the Models page's credentials list, alongside XMEMO_MODE — an accepted tradeoff of reusing the one channel that's actually open to an out-of-tree plugin (see the web GUI card limitation below). XMEMO_OAUTH holds the access/refresh token pair as an opaque JSON blob; XMEMO_OAUTH_ACTION is a transient write-only signal, never holding anything meaningful at rest; XMEMO_MODE isn't a secret at all.
• A fresh OAuth client is registered on every connect attempt rather than cached — Dynamic Client Registration exists precisely for this kind of ad hoc self-registration, and skipping the cache avoids persisting a fourth credential ref with its own staleness edge cases. Each registered client is a self-verifying signed token MemoryOS never has to store server-side, so this has no accumulating cost.
• No encryption at rest. Same as upstream — the Cindy host's storage encryption, if any, was opaque to the plugin; this port is honest that there isn't one.
• Single in-process store lock. Concurrent dsh processes writing to the same store directory are not coordinated; run one instance per store directory.
• PII redaction is not implemented, matching upstream: xmemo-cindy-plugin's tool descriptions claim email/phone redaction, but no such code exists in main.js either — it's server-side or aspirational. This port's tool descriptions say only what the code does.
• Replayed writes only back-fill cloud_id, not richer response fields — see Architecture notes.
• The web GUI card can only edit OAuth login, apiKeyCredential, and mode; the other five config fields aren't editable from the browser at all. The harness's generic settings-persistence pipeline (ctx.settingsScope) is gated by a hardcoded namespace allowlist in deepseek-harness's own packages/host/apiproxy/src/api-proxy.ts (WEB_SETTINGS_NAMESPACES) that an out-of-tree plugin cannot extend from its own package (the source comment there calls generalizing it "deferred work"). Only the ungated credentials.* RPC is open to third-party plugins today — the same channel apiKeyCredential already used for its API key — so mode and OAuth both piggyback on it too (XMEMO_MODE, XMEMO_OAUTH/XMEMO_OAUTH_ACTION), and the remaining five config fields have no open channel to bind to at all.
• The mode selector can't show the currently saved value, only whether one has been saved. credentials.describe reports configured/writable but never a credential's value — correct for secrets, but it means the mode select can't be pre-filled with the true stored mode the way Cindy's /kv-backed selector can. The select always starts from the hybrid default; saving always overwrites blindly, same as the API key field already does.

Security and privacy

• Credentials never reach plugin memory as browser-readable state. The web GUI card only ever sees configured/writable booleans (credentials.describe) — it can change the API key, OAuth tokens, and mode, but never read their values back.
• OAuth tokens are stored, not logged. The access/refresh token pair lives under the XMEMO_OAUTH credential reference; refresh tokens rotate on every use, and a reused (already-consumed) refresh token is rejected server-side rather than silently accepted.
• Obvious credential-like text is redacted before memory and timeline writes (src/redact.ts, 7 categories, ported verbatim from upstream) — a safeguard, not a substitute for keeping secrets out of prompts.
• Local memory is private but not encrypted by this plugin — protect the device and do not store secrets in memory content.
• Deletion is recoverable by default. xmemo_forget soft-deletes unless a caller explicitly requests a hard, permanent delete.
• This repository contains no production credentials, tokens, or private memory — only credential reference names (e.g. XMEMO_KEY), never values.

Canonical service policies: Privacy policy · Terms of service · Support

Development

npm install
npm run build         # tsc -> lib/ (host half)
npm run build:client   # tsc --emitDeclarationOnly + esbuild -> lib/client.js (browser half)
npm run typecheck
npm test               # node --test over tests/*.spec.ts

Releasing

Bump version in package.json, commit, then tag and push:

git tag -a v0.1.1 -m "v0.1.1"
git push origin v0.1.1

.github/workflows/publish.yml picks up any v*.*.* tag, rejects it if it doesn't match package.json's version, runs typecheck/test/build, publishes to npm with provenance using the NPM_TOKEN repository secret, and creates a matching GitHub Release. workflow_dispatch (with a version input) works the same way for a manual re-run from a commit already tagged that way.

Agent-readable metadata

Links

• Product: https://xmemo.dev
• Account & API keys: https://xmemo.dev/me#api-keys
• Documentation: https://xmemo.dev/product/docs
• Support: https://xmemo.dev/support
• DeepSeek Harness: https://github.com/deepseek-ai/deepseek-harness
• Sibling plugins: Cindy · Claude · Codex · Hermes Agent · OpenClaw

License

MIT © 2026 Yonro