dsh-flymemory

English | 中文

Long-term memory for DeepSeek Harness.

This is a plugin (a DSH bundle) that runs FlyMemory as a local MCP service and plugs it into the harness. You end up with 15 memory tools, plus a pair of hooks that quietly record what you've been working on and pull the relevant bits back when they matter — so you stop re-explaining the same context every session.

Everything stays on your machine. The service listens on 127.0.0.1:8791, the library is a single file under your DSH home, and nothing is sent anywhere.

DSH session ──┬── mcp__flymemory__*   15 tools the model can call
              └── hooks               recall before a turn, store after it
                        │
                        ▼
              FlyMemory service on 127.0.0.1:8791
                        │
                        ▼
              $DSH_HOME/flymemory-data/flymemory_v3.pkl

What you get

Fifteen tools, all under the mcp__flymemory__ prefix:

And two hooks that work on their own:

• On every prompt — the prompt is stored, and memories that match it get appended to the turn. No model call, just local search.

• On session start — a recovery pack of recent activity, so a fresh session isn't starting from nothing.

Both hooks are silent when the service is down, and neither can block a turn.

Related MCP server: Lumena MCP Server

Requirements

• DeepSeek Harness with @deepseek-ai/dsh-mcp-client available. Built and tested against 0.2.0-rc.2 and 44.7.0.

• Node 20+ (the add-on and its CLI).

• Python 3.10+ with the engine's dependencies:

  pip install torch sentence-transformers "mcp>=1.30,<2" numpy

  The plugin finds the interpreter for you: it checks FLYMEMORY_PYTHON, the usual install locations, then PATH, and it verifies that sentence_transformers actually imports before picking one. On a machine with several Pythons that saves you the "why won't it start" half hour.

  The first run downloads the multilingual embedding model (~470 MB) into the HuggingFace cache. After that it works offline.

Install

Point plugin_manager at this directory (absolute path):

plugin_manager(action: "install_bundle", target: "/absolute/path/to/dsh-flymemory")

Or use the Plugins page in the Web sidebar and pick the folder. The harness reloads, two rows come up (flymemory, flymemory-mcp), and the tools appear.

Check it:

node bin/flymemory.mjs status     # what it resolved, and what's live
node bin/flymemory.mjs doctor     # interpreter, dependencies, endpoint

Then ask the model to remember something and search for it. If the tools don't show up, doctor usually says why.

Removing it is the same in reverse:

plugin_manager(action: "remove_bundle", target: "dsh-flymemory")

Your memory file is not deleted — remove it by hand if you want it gone.

How it runs

The bundle inserts two rows:

The hooks used to ride DSH's Claude-Code hook bridge. Builds from 44.7 onwards no longer ship that package, so the same logic now runs on the plugin's own agent/pre-step listener and the bundle declares no hook-bridge dependency.

When the harness starts, the first row checks 127.0.0.1:8791. If a FlyMemory service is already answering there, it's reused — two harness windows share one engine and one library. If the port is free, the bundled engine starts in the background and the row waits for it before letting the next row connect. If something else owns the port, the plugin says so and leaves it alone; it never kills a process it didn't start.

Cold starts are slow: the engine imports torch before it can listen, which takes 15–20 seconds. The row waits up to 25 seconds by default, and the mcp-client reconnects on its own if it has to.

If the engine can't start at all — no interpreter, missing dependency, port conflict — the harness still boots. You just don't get the tools, and the reason is in the log.

Settings

Environment variables, read before the harness starts:

Anything else goes on the row itself, in your profile's cordis.patch.yml. A patch entry replaces the whole config, so write out everything you need:

- id: flymemory
  name: 'dsh-flymemory'
  config:
    port: 8791
    dataDir: 'D:\dsh-memory'
    libraryPath: 'D:\dsh-memory\my-lib.pkl'
    pythonExe: 'C:\Python313\python.exe'
    device: cpu
    readinessTimeoutMs: 25000   # 0 = don't wait, let the tools show up later
    shutdownOnDispose: true     # stop the engine this activation started
    nativeHooks: true           # recall/capture on every typed prompt
    hookTimeoutMs: 6000         # budget per hook request
    writeHooksConfig: true      # also write hooks.json for clients outside DSH
    seedFromUpstream: false     # don't import another library implicitly
    upstreamLibrary: ''         # set both to import one, once
    autostart: true

The rest of the options are documented in resolveOptions() in lib/index.js. Unknown keys are ignored.

Where your memory lives

$DSH_HOME/flymemory-data/flymemory_v3.pkl — one file, plain data, easy to back up or delete. Alongside it:

• hooks.json — regenerated on every activation; describes the two hooks

• state.json — what the last activation resolved (endpoint, library, interpreter, how the service was obtained); status and doctor read it, so they report an override instead of the defaults

• engine.log — stdout/stderr of the engine process

• server.log — the engine's own log

• server.pid — so flymemory stop knows what to kill

To run the service on its own, without the harness:

node bin/flymemory.mjs start
node bin/flymemory.mjs stop
node bin/flymemory.mjs log -n 40

After installing the bundle, the same CLI is linked into the profile at <profile>/node_modules/.bin/dsh-flymemory.

About the hooks

They're on by default, because automatic memory is the whole point of the thing. They run inside this plugin on agent/pre-step — no hook bridge package needed. Worth knowing exactly what that means:

• Only messages you actually typed are stored and recalled. The harness tags a typed prompt source.kind === "user"; peer deliveries, system reminders, automation prompts and model-change notices carry other kinds and are ignored. A delegated agent gets one recall at task start, then nothing more.

• Credential-shaped text never gets stored, and automation/heartbeat prompts are skipped before they reach the service.

• Recalled memories are appended to the turn, capped at about 2.5 KB, with a header saying they are data rather than instructions.

• A second request pulls the top two entries of compartment="lessons" and injects them on their own, so pitfalls come back every turn instead of competing with ordinary recall. Store one with flymemory_remember and compartment="lessons", starting the text with the tool or environment names that should bring it back — the keyword channel is what finds it.

If you'd rather have the tools and no automation, turn the hooks off on the row (a patch entry replaces the whole config, so restate what you need):

- id: flymemory
  name: 'dsh-flymemory'
  config:
    port: 8791
    nativeHooks: false

Importing a library you already have

Nothing is imported unless you ask. If you have a FlyMemory library from somewhere else and want to move it in, point the plugin at it once:

- id: flymemory
  name: 'dsh-flymemory'
  config:
    port: 8791
    upstreamLibrary: 'D:\path\to\flymemory_v3.pkl'
    seedFromUpstream: true

On the next activation the file is copied into place if the target doesn't exist yet. The original is left alone. The format is the same in both directions, so you can move it back out later.

Sharing a service you already run

If a FlyMemory service is already running on this machine and you want DSH to share its memory rather than keep its own, override both rows in your profile patch:

- id: flymemory
  name: 'dsh-flymemory'
  config:
    port: 8765
    libraryPath: 'D:\path\to\flymemory_v3.pkl'
- id: flymemory-mcp
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: flymemory
    transport: streamable-http
    url: 'http://127.0.0.1:8765/mcp'

port is where the plugin looks for the existing service; libraryPath is the file it serves if it ever has to start the engine itself, so both routes lead to the same memory. Leave the hooks row alone — it follows the endpoint the plugin resolved. node bin/flymemory.mjs status prints "from hooks.json" when an override like this is in effect, so you can tell it apart from the defaults.

The supervisor writes <dataDir>/hooks.json on every activation from the config it resolved, so the hook scripts always post to whatever endpoint the plugin actually uses. That file is also how status and doctor discover an override.

Working on it

node --check lib/index.js    # syntax
npm test                     # unit tests, no Python needed, ~0.3 s
node tests/engine_smoke.mjs  # end-to-end against the real engine (needs torch)
python tests/http_smoke.py   # protocol check against a running service

npm test covers the parts that are easy to get wrong: port and library defaults, config precedence, the generated hook file, endpoint probing. The engine smoke test runs apply() in a throwaway directory against a real Python engine — it needs torch and sentence-transformers, and prints SKIP if they aren't there. CI runs the syntax check and the unit tests on Linux, macOS and Windows across Node 20, 22 and 24.

lib/index.js        Host half: port probing, engine supervision, hook config
bin/flymemory.mjs   CLI built on the same helpers
cordis.patch.yml    the two rows this bundle inserts
python/             vendored FlyMemory engine (server, hooks, engine package)
locale/{en,zh}.json title and description for the Plugins page
tests/              unit tests, engine smoke test, protocol smoke test

Rough edges

• The first start takes 15–20 seconds. That's torch loading. Set readinessTimeoutMs: 0 if you'd rather the harness start immediately and have the tools appear a few seconds later.

• The Python dependencies are heavy. The plugin won't install them for you; doctor tells you what's missing.

• DSH has no PreCompact hook, so the recovery pack runs at session start rather than right after a compaction.

• Tool names are long. mcp__flymemory__flymemory_recall is what the mcp-client naming rule produces — mcp__<server>__<tool> — and it's stable, just not pretty.

• One engine per port. Two harnesses share it; a third instance needs its own port and its own library, set explicitly.

• Recall gets slower as the library grows. Upstream measured ~11 ms per query at about 1,400 entries on CPU.

License

MIT. See LICENSE.

The bundled FlyMemory engine is MIT as well, Copyright (c) 2026 Junrong Du. THIRD_PARTY_NOTICES.md lists exactly which files were copied, which were adapted, and why.