Skip to main content
M

dsh-server-memory (plugins)

methpia/dsh-server-memory/plugins

Self-hosted project memory for DSH: a compact prompt index, search and save tools, and up to one consolidation per day written back to your own memoryd service, which runs on your laptop, a LAN box or a cloud server and never calls an LLM itself.

Install

dsh plugin --profile web add github:methpia/dsh-server-memory

This plugin lives in the plugins subdirectory of the repository.

README

dsh-server-memory

ci

Project-scoped long-term memory for DeepSeek Harness (DSH), self-hosted, with a zero-LLM daily path.

中文文档 · User guide · Public deployment · Design (EN) · 设计文档 · Security · Contributing


Why this exists

Agent memory products usually run an LLM on every write: extract facts, merge observations, refresh pages. That is precise and expensive. A single session write-back of a 3.5 MB transcript turned into 2381 extraction units and ¥9.91 in one day — roughly 20× the cost of the actual work conversation.

This project takes the opposite trade-off:

Typical memory backenddsh-server-memory
Cost per sessionLLM calls on every write and on every session start0
When memory is writtencontinuously, automaticallyonce a day, by the agent's own model
Where memory livestheir cloudyour machine (SQLite file)
Recallsemantic + rerank + graphFTS5 keyword search over Chinese bigrams
Precisionentity resolution, contradiction trackingflat summary lines

Roughly: ¥7/day → ~¥0.05/day, at the cost of recall precision. If you want maximum precision and do not care about cost, use a full-blown backend instead — this one is for people who want memory to be cheap, private and predictable.

Architecture

┌─ DSH host (any OS) ─────────────────────────┐
│  dsh-server-memory plugin (ESM, zero npm deps)     │
│   ├─ systemPrompt.section: ≤900-char index  │
│   ├─ background cache: poll /api/context    │
│   ├─ tools: memory_search / save /          │
│   │         projects / forget / consolidate │
│   └─ reads local transcripts → digest       │
└──────────────────┬──────────────────────────┘
                   │ HTTP + bearer token
┌──────────────────▼──────────────────────────┐
│  memoryd (Python 3.9 stdlib, single file)   │
│   ├─ SQLite (WAL) + FTS5 (Chinese bigrams)  │
│   └─ REST: context / search / notes /       │
│            items / projects / watermark     │
└─────────────────────────────────────────────┘

The server never calls an LLM. It stores text, indexes it, and answers queries. All summarisation happens once a day in the agent, driven by a per-project watermark.

Layout

PathWhat
plugins/The DSH plugin (ESM, no dependencies) — prompt index, tools, settings page, transcript digest
workbuddy/WorkBuddy adapter: stdio MCP server (incl. consolidation), two hooks, installer, its own tests
server/memoryd.py (Python 3.9 stdlib), launchd/systemd units, backup script, tests
scripts/smoke.mjs16-check end-to-end test against a running service
scripts/projects.mjsSet project labels/aliases, resolve a phrase to a project
docs/WORKBUDDY.mdWorkBuddy setup, consolidation and the keyword→project rules
DESIGN.mdFull design: data model, API, consolidation protocol, cost model, incidents

This repo is a client + server pair. The plugin does nothing on its own — it needs a memoryd service you run. If you are installing this for the first time, follow the user guide instead of the condensed steps below; it covers the two-machine case, token distribution and the mistakes people actually hit.

Quick start

1. Server

git clone https://github.com/methpia/dsh-server-memory.git dsh-memory && cd dsh-memory/server
python3 memoryd.py --init-config      # writes ~/.config/dsh-memory/config.json + a random token
python3 memoryd.py --check            # sanity-check the database and schema
python3 memoryd.py                    # foreground; defaults to 127.0.0.1:8788
curl -s http://127.0.0.1:8788/health

--init-config prints the token once. Store it in a file (chmod 600) and hand that path to the plugin, or pass it via DSH_MEMORY_TOKEN.

Keep it running:

# macOS
cp launchd/com.local.memoryd.plist ~/Library/LaunchAgents/    # edit the /Users/you paths first
launchctl load ~/Library/LaunchAgents/com.local.memoryd.plist

# Linux (systemd user unit)
cp systemd/dsh-memory.service ~/.config/systemd/user/
systemctl --user daemon-reload && systemctl --user enable --now dsh-memory

Remote access, two options:

  • Private (recommended): keep the service on 127.0.0.1 and put it on your tailnet.
  • Public VPS: bind 0.0.0.0 with TLS enabled (tls_cert / tls_key), or keep it on loopback behind nginx/Caddy. See public deployment — a plain-HTTP public port is not supported.
tailscale serve --bg --https=8443 http://127.0.0.1:8788
# plugin serverUrl becomes https://<machine>.<tailnet>.ts.net:8443

2. Plugin

mkdir -p ~/.config/dsh-memory
printf '%s' '<token>' > ~/.config/dsh-memory/token && chmod 600 ~/.config/dsh-memory/token

Install in DSH, one of:

  1. Plugin market — search for dsh-server-memory once listed (the entry file is docs/marketplace-entry.yml);
  2. Local checkout — plugin_manager → install_bundle with target set to the absolute path of plugins/;
  3. Manual — merge the insert row from plugins/cordis.patch.yml into your profile patch.

Override the endpoint in your profile patch (keyed by id):

- id: dsh-server-memory
  config:
    serverUrl: http://127.0.0.1:8788
    tokenFile: ~/.config/dsh-memory/token
    defaultProject: default
    projectMap:
      D:\projects: workbuddy-tasks

After a restart you should see ## 项目记忆 (<project>) in the system prompt and four memory_* tools.

Settings page. Settings → Built-in plugins → Project memory gives you connection fields (service URL, token file, default project), index/consolidation budgets, a connection test, a project list, and inline label/alias editing. Saving settings persists through the host config editor (the plugin restarts); project edits apply immediately. The bearer token stays on the host and never reaches the browser.

3. WorkBuddy (optional)

WorkBuddy creates a fresh dated working directory for every conversation, so a project cannot be inferred from cwd. Instead, projects are addressed by name or alias: 车易到 resolves to the cheyidao project.

# 1. give projects names/aliases (stored on the server)
node scripts/projects.mjs set cheyidao --label 车易到 --aliases 车易到,cheyidao,汽修管理

# 2. preview and then wire the adapter into ~/.workbuddy
node workbuddy/install.mjs --url http://192.168.5.5:8788 --token-file ~/.config/dsh-memory/token
node workbuddy/install.mjs --apply --url http://192.168.5.5:8788 --token-file ~/.config/dsh-memory/token

The installer backs up mcp.json / settings.json, adds one stdio MCP server and two Claude-style hooks, and leaves Hindsight alone unless you pass --remove-hindsight. Restart WorkBuddy afterwards. Manual consolidation is the primary path (say “整理记忆” → memory_consolidate); the prompt hook adds a once-a-day hint when the window is due. Details, verification steps and limitations: docs/WORKBUDDY.md.

4. Verify

python3 -m unittest discover -s server/tests -v        # 47 checks, Python 3.9+
cd plugins && node --test --experimental-test-isolation=none "tests/*.test.js"      # 98 checks, Node 22.15+/24
cd workbuddy && node --test --experimental-test-isolation=none "tests/*.test.js"  # 19 checks
node scripts/smoke.mjs --url http://127.0.0.1:8788 --token-file ~/.config/dsh-memory/token   # 16 e2e checks

How memory is written

  1. Nothing is written during normal work. The plugin only reads.
  2. memory_save writes when you ask ("remember this").
  3. Once a day, on the first prompt, the plugin claims a consolidation slot (POST /api/watermark/claim). If claimed, it reads your local transcripts since the watermark, builds a bounded digest (≤8000 chars, ≤120 entries), and the agent's own model turns it into 5–15 lines tagged [决策] [偏好] [风险] [经验].
  4. Those lines go back through memory_save, and the watermark advances only to what was actually consumed — a long backlog is processed over several days, never all at once.

HTTP API

All endpoints except /health require Authorization: Bearer <token>.

MethodPathPurpose
GET/healthliveness, schema version, counts
GET/api/context?project=&max_chars=prompt index rows
GET/api/search?project=&q=FTS5 search (Chinese bigrams)
POST/api/notesbatch write consolidated notes
POST/api/itemssingle manual memory
DELETE/api/items/{id}delete one memory
GET/POST/api/watermarkread / advance the watermark
POST/api/watermark/claimatomic "may I consolidate now?"
GET/api/projectsproject list with labels, aliases and counts
POST/api/projectscreate a project or set its label/aliases
GET/api/resolve?q=resolve conversation text to a project (aliases)

Text is capped at 4000 characters per item. Never submit a whole session transcript — see DESIGN.md §2.1.

Security

The service holds your entire long-term memory and a bearer token. Defaults are conservative: bind 127.0.0.1, fails closed on a missing token, chmod 600 on the token file. For a public host, enable TLS (tls_cert/tls_key) or terminate it at a proxy — there is exactly one shared token, so HTTP on a public port means anyone on the path can read every memory. Read SECURITY.md before exposing it beyond your own machine.

Known limitations

  • Keyword recall only. No embeddings, so paraphrase-level matching is weak; the compact prompt index compensates.
  • No entity resolution or contradiction tracking. Duplicates are avoided by the summariser's instructions, not by code.
  • Chinese-first. The bigram index works for CJK and Latin text, but the summariser prompt is written in Chinese.
  • Not a code-intelligence backend. No git history mining, no page taxonomy.

License

MIT — see LICENSE.

Related plugins