Project-scoped cross-session memory: seven-layer SQLite store (soul/user/project/fact/lesson/rules/topic) on node:sqlite, cache-friendly first-message injection plus per-message keyword hits, memory_remember/search/find_similar/read/update/project tools, and idle-window consolidation ("dream") with peak-hour suppression. Prompt texts ship as per-language data files — the framework supports multilingual users.
Install
# from npm (prebuilt)
dsh plugin --profile web add meow-memory
# from GitHub (first run asks for allowBuilds approval — follow the hint, retry)
dsh plugin --profile web add github:Phant0Meow/dsh-meow-memory
Any plugin you install runs third-party code with your own permissions — it can read your files, use your credentials, and reach the network, and tool approvals don’t sandbox it. GitHub-sourced plugins also run build scripts at install time — pnpm blocks those until you allow them, so an install can stop with ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED or ERR_PNPM_IGNORED_BUILDS; dsh prints the exact key to add under allowBuilds in your profile’s pnpm-workspace.yaml, and the install works on the next run. Allowing a build is a trust decision: only install sources you trust, and pin a commit (github:owner/repo#sha).
README
| 中文 | English | Português (BR) | MIT License |
|---|
Cross-session memory for DeepSeek Harness (DSH).
Version 0.31.0 | Changelog: CHANGELOG.md | Supports dsh 0.1.5
✨ Features
- Seven memory layers:
soul(the AI itself) /user(user basics & preferences) /project(per-project info withsubcategory) /fact(atomic facts) /lesson(mistakes & corrections) /topic(ongoing discussion arcs with a goal sentence) /rules(design principles & behavioral rules). One SQLite table per layer, UUIDs are time-prefixed so id order == creation order. - First-turn injection (long-term memory block): before the first user message, soul / user / design principles / memory guide are injected. The memory is inserted as an independent plugin snapshot directly before the real user message; the user's prompt is never rewritten, and no keyword hits run on the first turn (hits start from the second message).
- Per-message keyword hits: from the second user message on, every real user message is matched against fact/lesson/rules/topic (scope = global + current-project anchor) and the top-2 hits are injected. Matching is based on entry keywords, not full text.
- Current-project anchor: any
memory_remember/search/update/projectcall with aprojectparameter anchors the session's current project; unanchored sessions only hit global entries (casual chat stays unaffected). - Cache-friendly by design: the static
meow-memory:guidesection is registered in the system prompt once — constant text, so it cannot break the provider's KV cache. - Post-compaction re-injection: after a session is compacted, the next turn automatically re-injects the long-term snapshot plus the project overviews this session fetched via
memory_project, plus the entries this session wrote or updated — so the AI never suddenly goes amnesiac after compaction. - Three things on top of the layers: writes dedup and merge automatically; displayed timestamps are always
updated_at; global information uses the global marker (distinct from leaving the field blank). - Per-window dream: a window becomes dream-eligible once idle ≥ 3 hours, and its own main agent consolidates in rounds (atomic memories / topic / project summary); peak-hour suppression (09:00–12:00 and 14:00–18:00 in the configured
timeZone, default Asia/Shanghai — the API's peak-tariff hours) prevents triggering. Typing/dreamconsolidates immediately on demand. - Reflection: after ≥7 consecutive tool steps within one task the plugin asks the model whether anything since the last consolidation is worth remembering. A turn whose last tool is a
memory_*tool counts as already consolidated (no re-reflection). - External memory trust gate: a workspace-carried
.dsh-meowthat was not created on this machine (e.g. a cloned external repo) is paused by default — one notice on the first round, then/meow-trustre-enables instantly; libraries created locally and workspaces opened before the upgrade are trusted automatically, so normal use never notices. - Client UI: injected text collapses into a slim bar, reflection/dream turns collapse into one expandable card, and the session list shows dream state icons (🌙 consolidated / breathing moon in progress / muted-gray slashed moon skipped).
- No separately installed runtime dependencies:
node:sqlite+ an esbuild bundle (lib/index.js); the DSH Host resolves theschemasteryanddsh-llmpeers. No native modules.
📦 Install
One-command install (recommended)
dsh plugin --profile web add github:Phant0Meow/dsh-meow-memory
One command and it works: the package compiles itself on install (it ships a prepare script), mounts automatically, and new sessions load the plugin after you restart dsh web.
pnpm ≥10 blocks install-time build scripts by default: the first
addmay fail and mentionallowBuilds. Add the keys it prints to the profile'spnpm-workspace.yamland run it again.
Via npm (published package)
# 1. Install into the profile's node_modules (the loader resolves plugins there)
cd $DSH_HOME/profiles/web # default home: ~/.dsh/profiles/web
npm install meow-memory
# 2. Add the package to the profile's assembly bundles in package.json (recommended since v0.9.0):
# "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "meow-memory"] } }
# (the package ships a dsh.bundle.patch; bundle assembly inserts it. Profile-patch
# `insert` entries address existing ids — a new plugin not in the tree reports
# "entry not found", so new plugins go through the bundles array.)
# 3. Restart dsh web. New sessions pick up the plugin automatically.
Remove
dsh plugin --profile web remove meow-memory
PT-BR fork
For a build packaged for Brazilian Portuguese, see coutogilson's fork:
dsh plugin --profile web add github:coutogilson/dsh-meow-memory
By hand (any DSH install, no npm needed)
Copy (or symlink) this package into the profile's
node_modules:mkdir -p ~/.dsh/profiles/web/node_modules ln -s /path/to/meow-memory ~/.dsh/profiles/web/node_modules/meow-memory(On Windows:
New-Item -ItemType Junction ...— NTFS junction, no admin needed.)Add
meow-memoryto the profilepackage.json'sdsh.profile.bundles(same as above).Restart
dsh web. New sessions pick up the plugin automatically.
🔌 Compatibility
Supports dsh 0.1.5 (including the latest 0.1.5-rc.1) and stays backward compatible with older releases — upgrading dsh needs no change to this plugin or its configuration.
The plugin never hardcodes a version: it probes host capabilities at runtime, so new and old releases each take their correct branch. Both generations are verified — on 0.1.5-rc.1 first-turn injection, memory tool calls, and client rendering all work; on 0.1.1-rc.2 behavior is unchanged from previous releases.
⚙️ Configuration
All fields are optional (profile patch or cordis.patch.yml). You don't have to hand-edit files: the DSH settings page has a dedicated "喵记忆" tab for this plugin (peer of General/Models/Plugins) where every option below is editable in place, saved per-field with one-click restore-to-default (restoring means the plugin's built-in factory default, not the patch baseline); reload/restart the meow-memory plugin after saving for changes to take effect.
- id: meow-memory
name: 'meow-memory'
config:
enabled: true # master switch
projectDir: '.dsh-meow' # memory directory, relative to the workspace
promptLang: 'zh' # ⚠️ set this on first use (see note below)
hitTopK: 2 # max keyword-hit entries injected per user message
dream:
enabled: true
idleMinutes: 180 # window is dream-eligible after ≥180 min (3 h) idle
Every field, its type and its default are in docs/configuration-reference.md, including titleMax / autoMigrate / homeDir / disabledWorkspaces / backup / delegate.
⚠️ Set
promptLangexplicitly on first use. It decides the language of injected/reflection/dream prompts and of tool descriptions, and it also shapes the language the model writes memory entries in — keywords are extracted in the entry's language.zh/en/pt-brship built in. The value is the subdirectory name undersrc/prompts/and is matched verbatim: a name that does not exist (e.g.pt) raises nothing and silently falls back to the Chinese pack. See docs/configuration-reference.md.
UI language
The plugin's UI copy follows DSH's Settings → General → Language (built in: 中文 / English / Português (Brasil)) and is a separate layer from promptLang; the two do not interfere. See docs/configuration-reference.md.
🧠 How it works
First user message (turn 1) Every message from turn 2 idle ≥3h, not peak
┌────────────────────┐ ┌────────────────────┐ ┌──────────────────────┐
│ ===== 长期记忆 ===== │ │ 可能相关的记忆,仅供 │ │ per-window dream: │
│ 【关于你】(soul) │ │ 参考:keyword hits │ │ three rounds (atomic/ │
│ 【关于user】 │ │ top-2 (global + │ │ topic, summary), 7+ │
│ 【设计原则】(rules) │ │ current-project │ │ extracted, updated_at │
│ 【记忆导引】 │ │ anchor) │ │ stamped at T │
└────────────────────┘ └────────────────────┘ └──────────────────────┘
independent snapshot message seen ids recorded
↓ pristine user prompt per session (sessions/<id>.json)
injected once per compaction signal → seen released
session, no hits on turn 1
Tools
| Tool | Purpose |
|---|---|
memory_remember |
Write one memory (content/project/keywords/importance required; dedups and merges) |
memory_search |
Keyword search (BM25 × recency; level/project/status/days filters) |
memory_project |
Fetch a project's whole-project injection paragraph (project parameter required) |
memory_find_similar |
Duplicate & conflict detection |
memory_read |
Read one entry's complete metadata by id |
memory_update |
Correct status / importance / goal / keywords |
memory_dream |
Manually trigger this window's consolidation |
memory_home |
Inspect / switch the global data directory |
There is also the /dream command: type /dream in the composer to consolidate this window right away, immune to peak-hour suppression.
Parameters, returns and side effects are in docs/tool-reference.md (including memory_project's anchoring side effect and memory_home's three preset directory markers).
🛠 Development
npm install
npm run build # esbuild bundle → lib/index.js (Host peers stay external)
npm run test # 228 logic tests: db / bm25 / migrate / inject / reflect / dream / tools / apply
The @deepseek-ai/* packages live in the dsh-meow pnpm workspace, not in this package's
node_modules. On Windows, npm run link-workspace (or scripts/link-workspace.ps1)
creates junction mirrors of the workspace packages so esbuild can resolve them;
build.mjs uses nodePaths to pick them up. Building does not require the optional
dsh-llm peer. To run tests directly with Node, link @deepseek-ai/dsh-llm from a
matching DSH workspace; normal plugin loading resolves it through the DSH profile
loader. Do not restore it as a devDependency: file: / link: installs can introduce
a second copy of a Host core package into the profile (#84).
node tests/build-host-peers.mjs checks a clean build without Host peers (#87).
node tests/host-peers.mjs /path/to/node_modules/@deepseek-ai/dsh uses an independently
installed official DSH to check real Host loading and message contracts in an isolated
profile, without model calls.
📚 Documentation
| To learn about | Read |
|---|---|
| The seven tools: parameters, returns and side effects | docs/tool-reference.md |
| Every configuration field, type and default | docs/configuration-reference.md |
| Why it is designed this way (cache, hits, dream, pitfalls) | docs/design-notes.md |
| Install failures, poor search results, how to read errors | docs/troubleshooting.md |
| Version history | CHANGELOG.md |
| Adding a UI language | src/i18n/README.md |
| Adding a prompt language pack | src/prompts/README.md |
🙏 Acknowledgments
Thanks to every contributor who made meow-memory better:
- daveycodez — English language pack & tokenizer (PR #6, shipped in v0.22.0)
- chenmzh — isolated memory injections into independent plugin snapshot messages, fixing session title pollution (PR #10)
- cuddly-guacamole — dual-version Session events compatibility for dsh 0.1.2-alpha.4 (PR #11)
- coutogilson — Brazilian Portuguese prompt pack (
src/prompts/pt-br/) and the UI copy layer that follows the DSH locale
📄 License
MIT — see LICENSE.
Links
More in this category
vectorize-io/hindsight#coding-agents★ 60916
Hindsight, agent memory that learns: long-term project memory with auto recall and retain, knowledge pages, deep reflection, and per-repo memory banks.
volcengine/OpenViking#examples/dsh-memory-plugin★ 42209
OpenViking memory and context bundle for DeepSeek Harness: pre-step auto-recall and profile injection, session capture, `viking://` URI guarding, and recall/write memory tools backed by an OpenViking server.
MemTensor/MemOS#memos-local-plugin★ 12392
Local-first memory plugin for DeepSeek Harness: layered L1/L2/L3 memory with automatic capture, manual memos_* retrieval tools, and a built-in memory viewer.
agentscope-ai/ReMe#dsh★ 3799
Connects DeepSeek Harness to ReMe's local-first, self-evolving personal knowledge base: automatically captures completed main-agent conversations as user-owned Markdown memory, searches conversations and source material through reme_search with BM25, optional embeddings, and wikilink expansion, and schedules daily memory consolidation.
zilliztech/memsearch#MemSearch★ 2873
Shared Markdown memory for DSH and other coding agents, with automatic capture, pre-step context injection, searchable recall, and memory-to-skill self-evolution through a review panel.
vshulcz/deja-vu#extensions/dsh★ 1544
Cross-session memory and context recovery across forty-five other coding agents (45+) on this machine, reading session files they already wrote before install (Claude Code, Codex, Cursor, Windsurf, Trae, Antigravity, VS Code Copilot Chat, opencode, OpenClaw, Hermes, Kimi, Qoder, Cline, Zed, Magpie and more): six tools (deja_recall, deja_session, deja_blame, deja_fix, deja_how, deja_remember), a /deja command, and optional automatic recall injected into runtime context. Local BM25 CLI/MCP index, no LLM, no embeddings, no network (dsh plugin --profile web add dsh-deja).
Community comments
Comments are public GitHub Discussions. Loading them connects to GitHub and Giscus; a GitHub account is required to post.