dsh-memory README

The project's README from github.com/seriousz158/dsh-memory. As one markdown file: README.md.

dsh-memory

dsh-memory is a local, Git-backed long-term-memory plugin for DeepSeek Harness (DSH).

It adds one persistent setting, a safe settings-page workflow for clearing memories, and an optional idle-session synchronizer. The host plugin injects memory guidance only when memory.enabled is true; the UI plugin lets a user inspect the repository state, toggle the setting, and clear learned memory through a deliberate two-step confirmation.

What it does

Capabilities

This README describes stable user-facing behavior. Release-by-release implementation details are intentionally kept out of this page; see CHANGELOG.md and the GitHub releases for historical changes.

Local Git-backed memory

Safe synchronization and recovery

Read path

DSH settings integration

The settings UI provides the memory toggle, repository status, recent-sync state, preview actions, rollback, and deliberate clear confirmation. It does not expose the filesystem root or execute Git directly.

Compatibility

v0.9.2 keeps the DSH 0.1.0-rc.6 peer-compatibility range and has been tested and locally integrated with a consistently pinned 0.1.0-rc.7 graph:

Component Supported version
DSH runtime peer range @deepseek-ai/dsh@^0.1.0-rc.6 (rc.6 and rc.7)
Recommended/tested runtime 0.1.0-rc.7
Clean-room development test graph DSH client packages 0.1.0-rc.7
Node.js 22.x
Python 3.11.x
Git a local executable available on PATH
Operating system macOS is the supported/tested integration target

The package uses DSH's Cordis loader interfaces. The rc.7 graph is the reproducible development and integration baseline because the registry's rc.6 transitive peer graph cannot be installed by plain npm ci; this does not change the host/UI packages' declared rc.6 runtime peer range. DSH rc.8 and later releases are unverified until they pass this repository's test suite.

Install

The repository root is also a public DSH bundle named dsh-git-memory. It contains the host plugin, the settings-page client bundle, and its dsh.bundle patch, so one install activates both halves:

# GitHub source install (works before or without an npm publication)
dsh plugin --profile web add github:seriousz158/dsh-memory

This project is distributed through GitHub source installs and GitHub Releases. It is not published to npm.

Restart the selected DSH profile after installing. The bundle does not include any memory data, session logs, credentials, or the local .dsh directory.

Source checkout (development / local integration)

Clone the repository and install its reproducible development/runtime dependencies:

git clone https://github.com/seriousz158/dsh-memory.git
cd dsh-memory
# Use the pinned runtime that this v0.8.4 integration was tested with.
npm install --global @deepseek-ai/[email protected]
dsh --version
npm ci --ignore-scripts

The two workspace implementation packages remain private; only the root dsh-git-memory bundle is publishable. This keeps the internal host/UI package names stable while avoiding the already-occupied unscoped dsh-memory npm name.

Install the two local packages into your DSH profile. The installer defaults to ~/.dsh. If you use a non-default DSH or memory path, keep the same values in the environment that installs, starts, validates, and synchronizes DSH:

./integrations/dsh/install.sh

# Example for a non-default DSH home and memory repository:
export DSH_HOME="$HOME/.config/dsh"
export DSH_MEMORY_ROOT="$HOME/Documents/dsh-memory-data"
./integrations/dsh/install.sh
# Start DSH from this configured environment as well.

The installer creates only these DSH-profile links and the two required Cordis entries:

<DSH_HOME>/profiles/node_modules/dsh-memory
<DSH_HOME>/profiles/node_modules/dsh-memory-ui

It also initializes a missing memory root as a private local Git repository. For an existing complete memory repository, it verifies the layout and restores owner-only permissions; it does not delete or rewrite learned memory, session history, credentials, other plugins, or unrelated cordis.patch.yml entries. See installation details before using a custom memory root.

Restart the DSH host after installation. In DSH Settings, find 长期记忆 and leave the switch on to enable recall for the next model call.

Storage layout

By default the host uses:

<DSH_HOME>/storages/memory

with DSH_HOME defaulting to ~/.dsh. An operator can set DSH_MEMORY_ROOT to a different local absolute path. It must be present for the installer, every DSH host launch, explicit initializer run, and optional synchronizer run; a one-time installation assignment does not configure future LaunchAgent jobs. The web UI cannot submit or change a filesystem path.

The initialized repository contains:

summary.md      short, stable navigation and preferences
handbook/       reusable knowledge
rollouts/       per-session extraction results
archive/        superseded entries
scripts/        transcript filter helper
.last-sync      optional synchronizer watermark

Settings and API

The only persisted setting is:

memory:
  enabled: true

The local UI talks only to the fixed memory remote service:

memory.getSettings()
memory.setEnabled({ enabled: boolean })
memory.status()
memory.legacyRecords()
memory.migrateLegacy({ dryRun: boolean })
memory.clear({ confirmation: "DELETE_MEMORY" })

status() reports metadata such as empty, dataFileCount, targetDirty, and recoverable; it never returns the memory body. Full request/response contracts and stable error codes are in docs/api.md.

Clear memory safely

The settings UI intentionally requires two acknowledgements:

  1. Click 删除记忆, read the affected paths, then click 继续.
  2. Enter exactly 删除记忆, then click the final confirmation.

The clear operation is designed for recoverable day-to-day resets, not guaranteed privacy erasure. Before it changes any target memory path, it preserves a recovery point: for a clean repository this is the existing pre-clear HEAD, while dirty target paths are captured in a dedicated checkpoint commit. The clear commit is then created directly on that recovery point. The operation leaves .git, README.md, helper scripts, directory structure, and .last-sync intact so future sessions can learn again without reprocessing historical logs.

Use Git history inside the local memory repository to recover a checkpoint. For privacy-sensitive deletion requirements, remove relevant local backups and follow your organization's retention policy; Git history alone is not a secure-erasure mechanism.

Optional idle-session sync

The optional synchronizer is separate from the settings UI:

./integrations/dsh/dsh-memory-sync

It skips work when memory.enabled is false, and it skips active sessions. It needs a user-installed dsh executable (or an explicitly selected DSH_BIN), rather than invoking npx --yes. It defaults to workspace-write; wider privileges are never a repository default. The LaunchAgent template explicitly sets the default DSH and memory paths; edit both assignments before loading it when your installation is custom.

The session filter redacts common credential shapes and home-directory prefixes before a transcript reaches the memory-extraction model. This is defense in depth, not a promise that every secret format is detectable. Review privacy and recovery before enabling unattended sync.

Development

Run the full, local-only suite:

npm ci --ignore-scripts
npm test

Tests use temporary Git repositories and synthetic fixtures. They must not require a DSH account, start Chrome, launch a LaunchAgent, read the current user's memory/session folders, or make a paid model request.

Before opening an issue or pull request, run:

npm test
zsh tools/secret-scan.sh

See CONTRIBUTING.md, SECURITY.md, and the release checklist.

Privacy promise

This repository contains code, tests, templates, and examples only. It must never contain any real DSH memory, session log, credential file, browser profile, or user-specific DSH configuration. If you believe sensitive data was committed, treat it as exposed, rotate affected credentials, and follow SECURITY.md.

License

MIT © 2026 seriousz158.

dsh-memory (seriousz158/dsh-memory)

Searching Database…

179 ·GitHub
Dsh-memory
What is this?dsh-memory is a local, Git-backed long-term-memory plugin for DeepSeek Harness (DSH). It injects memory into the model's context and gives you a settings-page UI to inspect, toggle, and clear that memory.
Is this one plugin or two separate pieces?It ships as a single public DSH bundle called dsh-git-memory that bundles a host plugin (injects memory into model calls) and a UI plugin (settings page), so one install activates both halves.
How do I install it into my DSH profile?Install the dsh-git-memory bundle from a GitHub source checkout or a GitHub Release (it is not published to npm), run the installer which links into ~/.dsh and adds Cordis entries, then restart the DSH profile and enable the switch in DSH Settings under 'Long-term memory'.
What do I need on my machine before installing this?Node.js 22.x, Python 3.11.x, and a local git executable on PATH; it targets the DSH runtime peer range ^0.1.0-rc.6 and is tested against rc.7.
Does it run on Windows or Linux as well?No, macOS is explicitly the only supported and tested integration target; DSH rc.8 and later releases are also unverified until they pass this repo's test suite.
Does my memory data ever leave my machine?No. Memory lives only in a local Git repository with no hosted service or cloud vector database, and the source repository itself is required to never contain real memory, session logs, or credentials.
How does the plugin find relevant memories for a model call?memory.search() and memory.context() do hybrid retrieval: a derived SQLite FTS5 index (trigram plus CJK-bigram/word terms) is fused with lexical scoring and exact-substring precedence, falling back to a plain scan if the index is missing, stale, or corrupt.
How do I clear memory without losing everything by accident?The settings UI requires two deliberate acknowledgements (click to confirm, then type the exact delete phrase) and always creates a Git recovery checkpoint before touching summary.md, handbook/, rollouts/, or archive/, so you can recover via Git history; it is a recoverable reset, not a secure-erasure guarantee.
What does the optional idle-session sync do?A headless synchronizer can process only idle local session logs in a private, isolated workspace, defaulting to workspace-write permissions; it never installs DSH itself and forwards only an allowlisted set of environment variables.
Is memory data readable by anything other than the model?The UI only talks to a fixed local memory status endpoint and can report metadata like file counts and dirty/recoverable state, but it never returns the actual memory content or lets the web UI change the filesystem path.
What are similar projects?EverOS, MemOS, DSH-taskboard, DSH-Plugins-Marketplace, dsh-routing-suite, awesome-deepseek-harness, Minke, dsh-our-free-model
Which topics is it in?cordis, long-term-memory, full-text-search, dsh, dsh-plugin, memory, deepseek-harness, git, sqlite, local-first, plugin, agent
Creator
seriousz158
Size
0.6 MB
Stars
179
Updated
CommitOct 10Releasev0.10.0Oct 10
Age
2mo
Commits · 90 Days