dsh-memory-vault

Persistent OKF memory for DeepSeek Harness (DSH): a Python MCP server (SQLite FTS5 + Markdown), two Cordis plugins (memory-mcp, memory-auto) that expose it to the agent as tools and commands, and a vault starter with templates and a type registry.

One lap per session: the agent recalls what the vault already knows, works, the checkpoints capture what happened, and the digest commits the durable state back — so the next lap starts from a richer record. Markdown stays the source of truth; SQLite FTS5 is an index derived from it.

What an install gives you

Install

# 1. install both plugins (npm, prebuilt — no build approvals, no repo clone)
dsh plugin --profile web add @luisarg/memory-mcp@0.1.7 @luisarg/memory-auto@0.1.7

# 2. launch — first boot installs the vault server under $DSH_HOME (~/.dsh by
#    default) and the vault starter at ~/.memories, automatically
dsh web

# verify
dsh --profile web --dump-config | grep -A8 memory

The version is pinned because pnpm's default minimumReleaseAge (3 days) would otherwise resolve an older release. The bundled Python server is refreshed on every boot; the vault is never overwritten — it copies only what is missing, so your entries survive upgrades.

Upgrading from 0.1.5: the default vault moved from $DSH_HOME/memory-vault to ~/.memories (the central zone in docs/central-zone.md). Entries written by 0.1.5 therefore stay in the old directory until you move them (rsync -a --ignore-existing ~/.dsh/memory-vault/projects/ ~/.memories/projects/) or point DSH_MEMORY_PATH back at it.

Developers (local checkout instead of npm):

dsh plugin --profile demo add ./packages/memory-mcp ./packages/memory-auto

Offline: pnpm --filter @luisarg/memory-mcp pack and add the .tgz files. Installing the repo root from GitHub is not supported (the root has no dsh.bundle; pnpm lacks git subdirectory specs) — use npm or the tarball.

Releases are published by CI: pushing a v<version> tag builds, tests, validates the tarballs and publishes both packages to npm with a provenance attestation, authenticated by GitHub OIDC — no publish token exists in this repository or on the maintainer's machine. What runs before an artifact ships is in docs/releasing.md.

Components

Use it

Ask in the chat

The agent reaches the vault through MCP tools (mcp__memory__* — the server is named memory); you do not call them yourself:

Bundled skills

Both plugins also ship the commands that drive those tools, so a fresh install gets them without copying anything into a skill directory:

They register at DSH's bundled rank, the weakest in the local discovery table, so a skill of the same name in ~/.agents/skills, ~/.dsh/skills or a project's .agents/skills still wins — these are defaults, not a takeover. To override one, copy its SKILL.md out of packages/*/skills/ into your skill root and edit it: the file is the single source of its own name, description and usage guidance, so it works in both places.

Automatic capture

memory-auto triggers digests on git commits, compactions, idle sessions and session end. Digests log as [memory-auto] … lines in the harness console, and the entries land under <vault>/projects/<project>/<type>/ (Markdown) plus the SQLite FTS5 index. The extraction runs in-process through ctx.llm — the credentials DSH is already configured with — so there is no external CLI and no stored key. Set enabled: false in the plugin config to turn it off.

Configuration

DSH does not chdir: the launch directory is irrelevant and paths are absolute. They resolve in this order:

1. Env vars (override everything): DSH_MEMORY_PATH, DSH_MEMORY_SERVER_DIR.
2. Defaults: the vault at ~/.memories (the OS home — DSH_HOME does not move it) and the server at $DSH_HOME/memory-vault-server (~/.dsh when $DSH_HOME is unset).
3. Profile patch (cordis.patch.yml) or --patch overlay with explicit values.

Plugin-level config (patch layer): provider (deepseek-official), model (deepseek-v4-flash), maxTokens, minTranscriptChars, enabled.

The vault starter is an OKF bundle: templates/ (one per entry type), type-registry.yaml (source of truth for types) and tag-vocabulary.json (tag normalization). Runtime data (projects/, raw/, logs/, memory.db) is created by the server on first use and excluded from git.

Runtime for the server: uv on PATH is recommended but not required. The bundled launcher.mjs runs the server with uv run when uv is present, and otherwise falls back to a pip-managed venv (python3 -m venv + pip install -r requirements.txt; the first boot needs network). Both packages are self-contained: they ship the Python server and the vault starter.

Operations

# composed config shows both bundles with the resolved paths
dsh --profile web --dump-config | grep -A8 memory

# what the vault holds (default vault: ~/.memories)
ls ~/.memories/projects/               # per-project OKF entries
grep -i "digest" ~/.memories/log.md    # digest markers

# talk to the vault MCP server directly (standalone smoke test)
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"cli","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ping","arguments":{}}}' \
  | MEMORY_PATH=$HOME/.memories uv run --directory memory-vault-server python server.py

# a second harness instance on another port (testing without touching your main session)
pnpm dsh web --port 3090

Troubleshooting pnpm

• unable to open database file → the pnpm store is not writable (sandboxed environment). Use --store-dir ./.pnpm-store on every pnpm install and on dsh plugin --profile X --store-dir ./.pnpm-store add ....
• dsh: pnpm failed when installing from GitHub → only applies to packages with a prepare script; copy the printed key into the profile's pnpm-workspace.yaml (allowBuilds). The subpackages of this monorepo cannot be installed with github:... at all — use npm or a tarball.

Second MCP client: opencode

The vault is a plain stdio MCP server, so any MCP client can use the same server and the same vault (see docs/central-zone.md for the shared-vault layout). For opencode, ~/.config/opencode/opencode.json:

"mcp": {
  "memory-server": {
    "type": "local",
    "command": ["uv", "run", "--directory", "<repo>/memory-vault-server", "python", "server.py"],
    "enabled": true,
    "environment": { "MEMORY_PATH": "<absolute path to your vault>" }
  }
}

The key must be environment — env is silently ignored and the server falls back to the default vault. The plugin skills are a DSH feature and do not travel over MCP: an opencode user who wants the same commands copies the SKILL.md files into a directory opencode reads (~/.config/opencode/skills/<name>/SKILL.md), renaming the tool prefix from mcp__memory__* to memory-server_*.

Development

pnpm install
pnpm -r build

# run the harness against the checkout, with an overlay (paths relative to the repo cwd)
dsh web --patch ./examples/dev-memory.cordis.yml

packages/memory-mcp/          # cordis bundle: MCP stdio client (+ brain, checkpoint skills)
packages/memory-auto/         # cordis bundle: automatic session digest (+ checkpoint-auto skill)
memory-vault-server/          # Python MCP server (SQLite + Markdown OKF)
memory-vault/                 # vault starter (templates + type registry)
scripts/digest_session.py     # optional standalone digest CLI (not used by the plugins)
examples/dev-memory.cordis.yml       # memory-mcp
examples/dev-memory-auto.cordis.yml  # memory-mcp + memory-auto

pnpm -r build runs each package's build; pnpm bundle copies the server and the vault starter into the packages, so a release tarball is self-contained. CI runs lint, build and the test suites on every push (pnpm lint && pnpm -r build && pnpm -r test).

Docs

• docs/ — architecture, diagrams, the central zone, releasing
• Releasing & version tags — which commit each v* tag maps to
• Your first plugin
• Build a tool
• Plugin configuration
• Package and install