Foreword

DeepSeek Harness is in developer preview. When building agents with long-term memory capabilities, existing solutions often rely on MCP bridging, and this “thin wrapper” model has limitations in terms of performance and flexibility. XMemo is a native DeepSeek Harness plugin, implemented directly on top of the Cordis architecture and communicating directly with the MemoryOS REST API rather than through an intermediate forwarding layer.

What It Is

This is a native plugin that provides local-first + cloud memory capabilities for DeepSeek Harness (dsh).

  • Name: xmemo
  • Maintainer: yonro
  • License: MIT
  • Core value: Native local-first + cloud memory for dsh.
  • Backend: MemoryOS REST API (https://xmemo.dev)

Core Features

The plugin implements the following features:
* Native Cordis plugin: Direct implementation rather than a thin MCP bridge.
* Hybrid storage: Local JSON hybrid storage combined with an offline persistent write queue.
* Focused recall: Merges local token overlap matching with cloud recall, with graceful fail-closed behavior on bucket/scope mismatches.
* Persistent results: Records decisions, preferences, facts, timeline events, TODOs, and decisions.
* Work continuity: Provides active task status and restart snapshots so that sessions can be resumed rather than replaying history.
* Offline resilience: Each write is persisted locally first, with safe (idempotent) cloud replay; uncertain writes wait for explicit approval.
* Recoverable deletion: xmemo_forget defaults to soft deletion.
* Tool compatibility: Includes 16 tools and is compatible with the names and architecture of xmemo-cindy-plugin.

Installation and Enablement

Installing the plugin requires specifying a profile name.

  1. Install via npm:
    dsh plugin --profile <name> add dsh-xmemo
  1. Install via GitHub:
    dsh plugin --profile <name> add github:yonro/xmemo-deepseek-plugin
  1. Install via local path:
    dsh plugin --profile <name> add ./xmemo-deepseek-plugin

Note: Installing from Git or a local path pulls the source code rather than the built lib/ directory. Because pnpm blocks the prepare script during the first add (a script that builds the plugin), you need to add the plugin to the profile’s pnpm-workspace.yaml and then rerun add:

allowBuilds:
  dsh-xmemo: true

After installation is complete, verify that the configuration has been loaded:

dsh --profile <name> --dump-config   # 查找 "# == dsh-xmemo"

Configuration and Authentication

The plugin supports two authentication methods, resolved in order of priority:

  1. OAuth 2.1 + PKCE (Recommended)

    • Connect in the Web GUI plugin card, or trigger it programmatically.
    • Write a connect:<anything> value to the XMEMO_OAUTH_ACTION credential.
    • The plugin creates a new public OAuth client through dynamic client registration (POST /oauth/register) and listens on a local port to handle the redirect.
    • After successful authentication, the access token and refresh token are stored under the XMEMO_OAUTH credential reference and are refreshed automatically.

  2. Static API key (Compatibility mode)

    • Set XMEMO_KEY through the dsh credential seam.
    • Supports environment variables, $DSH_HOME/.credentials.yaml, or <project>/.env.
    • The authentication header uses X-API-Key (the primary authentication header for MemoryOS).

Configuration items are located in the plugin’s cordis.patch.yml and can be overridden:
* mode: hybrid (default, local-first + cloud sync), local-only (local only), cloud-only (cloud only).
* apiKeyCredential: defaults to XMEMO_KEY.
* apiBaseUrl: defaults to https://xmemo.dev.

Typical Usage

  • Connect an account: Set up an XMemo account or API key.
  • Verify status: Use dsh --profile <name> --dump-config to check whether the plugin has been loaded.
  • Trigger login: Write connect:<any value> into the credential to trigger the OAuth flow.
  • Set the key: Set XMEMO_KEY via an environment variable or .credentials.yaml.

Use Cases and Cautions

  • Use cases: Developers who need to deeply integrate memory capabilities into DeepSeek Harness workflows.
  • Cautions:
    • DeepSeek Harness itself is in developer preview.
    • This plugin has not yet been validated in broad multi-user usage scenarios.
    • DeepSeek Harness does not have native OAuth primitives, so this plugin implements the full OAuth 2.1 + PKCE flow by itself.

Summary

Through its native Cordis implementation, the XMemo plugin provides local-first memory storage, an offline write queue, and real OAuth 2.1 authentication capabilities. For developers who want to build persistent, recoverable agents in DeepSeek Harness, this is a viable solution that communicates directly with MemoryOS.