Content
# deepDDW — Memory & Knowledge Base for DeepSeek Harness, Reachable from Any Device on Your LAN
[](LICENSE)
[](https://github.com/0xsline/awesome-deepseek-harness#memory--knowledge)
[](https://github.com/ccch713/deepddw/actions/workflows/ci.yml)
> **English** · [简体中文](README.zh-CN.md)
**deepDDW gives DeepSeek Harness (DSH) the three pieces it's missing — memory, a knowledge base, and document search — and makes all of it reachable from *any* device on your LAN. No app install. No DSH source changes.**
- 🧠 **Memory** — cross-session long-term memory, write/search via DSH's official MCP interface
- 📚 **Knowledge base** — ingest & search your docs (industry docs, SOPs, research notes) anytime
- 🌐 **LAN-wide multi-device** — deploy once; phones, laptops and tablets on the same network all use the same DSH workbench
**Try it in 60 seconds:**
```bash
npm i -g @deepseek-ai/dsh # 1. install official DSH on the server
git clone https://github.com/ccch713/deepddw.git && cd deepddw
./install.sh --with-dsh # 2. install deepDDW
./install.sh --port 8600 # 3. start
# 4. from any device on your LAN: open http://<server-ip>:8600/ (phone: scan the QR to auto-pair)
```
> 📸 *Screenshot: phone / tablet accessing the workbench (coming soon).*
**Status**: v0.6.0 · MIT · CI (pytest + ruff) ✅ · DSH for Teams — multi-user, LAN multi-device, memory & KB with team distillation · migration import/export, scope promote, incognito, retrieval health · [Listed in awesome-deepseek-harness](https://github.com/0xsline/awesome-deepseek-harness#memory--knowledge) · Roadmap below
> ## ⚠️ IMPORTANT — Read Before Installing
>
> deepDDW implements **its own memory and knowledge-base isolation**. To avoid conflicts or memory confusion, **before installing**:
>
> 1. **Back up** your existing memory and knowledge-base contents (wherever they live in your DSH setup);
> 2. **Uninstall/disable** any other memory or knowledge-base plugins you have installed;
> 3. Only then install deepDDW and let it own the memory & knowledge-base stack.
>
> Running deepDDW alongside other memory/KB plugins may cause **data conflicts or memory mixing** between namespaces. You have been warned. ⚠️
---
## Why deepDDW?
Most DSH extensions give you memory *alone*. deepDDW is a **complete workstation** — memory + knowledge base + document search + **LAN-wide multi-device access**:
| Official DSH limitation | deepDDW solution |
|------------------------|------------------|
| 🔒 **Local-only access** | ✅ **LAN-wide access**: deploy once on a server; desktops, laptops, phones and tablets on the same network all connect |
| 🧠 **No memory** | ✅ Long-term memory write/search — conversation experience is accumulated |
| 📚 **No knowledge base** | ✅ Knowledge base search/ingest — industry docs, SOPs, research notes, callable anytime |
**In one sentence**: turn a "personal toy" into a tool a small team can actually use — **fully packaged, easy to deploy, low maintenance, ready for small businesses** (up to ~20 people) for their daily AI workflow.
deepDDW distills lessons from real-world enterprise deployments into the DSH ecosystem as open source (MIT).
---
## How It Works (Technical Path)
```
📱 Phone / 💻 Desktop / 📱 Tablet / 🖥️ Laptop — any device on the LAN
│ (browser access, no App install)
▼
deepDDW Gateway (one server on the LAN)
├─ /dsh/* proxy → DSH engine (official UI, model config & chat untouched)
├─ /api/* proxy → DSH RPC/API
└─ /api/v1/* deepDDW capabilities: Knowledge Base / Memory / Docs / LLM config
│
│ DSH official MCP client (streamable-http)
▼
deepDDW MCP tools (auto-invoked by the model)
├─ mcp__deepddw__ddw_kb_search knowledge base search
├─ mcp__deepddw__ddw_memory_put write memory
├─ mcp__deepddw__ddw_memory_search search memory
└─ mcp__deepddw__ddw_docs_portal_search document search
```
**Integration = DSH standard MCP**: DSH natively supports MCP clients; deepDDW exposes a standard `streamable-http` endpoint — **zero intrusion, zero changes to DSH source**. The UI, settings and model configuration all remain official.
---
## Why Does It Work on Your LAN?
The official DSH listens on `localhost` only (for security), so phones/tablets cannot connect. deepDDW solves this with **gateway proxying**:
- **DSH stays bound to localhost** (official security design preserved)
- **deepDDW gateway listens on the LAN**, any device opens `http://<server-ip>:8600/` to reach the original DSH workbench
- All data stays on **your** server — never leaves the LAN
**Deploy once, the whole family/team can use it** — a capability the official DSH does not provide.
---
## Quick Start
```bash
# 1. Install DSH (official) on the server
npm i -g @deepseek-ai/dsh
# 2. Install deepDDW (packaged, one command)
git clone https://github.com/ccch713/deepddw.git
cd deepddw && ./install.sh --with-dsh
# 3. Start
./install.sh --port 8600
# 4. Open from any device on the LAN:
# http://<server-ip>:8600/ → original DSH workbench
# Phones/tablets: "Add to Home Screen" for an App-like experience
# 5. Add your API Key in DSH Settings → Models
# 6. In chat, ask the model to "search the knowledge base" or "remember ..."
# → it auto-invokes the mcp__deepddw__* tools
```
**Requirements**: one ordinary computer/server (**8 GB RAM minimum, 16 GB+ recommended**), Python 3.11+, no GPU needed (LLM via cloud API or local Ollama).
### Windows (standalone exe)
A Windows build is produced automatically by the `windows-build` workflow — download `deepddw-windows.zip` from the latest **Actions → Artifacts**:
```bash
# 1. Unzip anywhere (no Python/Node needed on the target machine)
deepddw-windows/deepddw.exe
# 2. Optional: point data/config at a custom location
set DDW_DATA_DIR=%USERPROFILE%\.deepddw
set DDW_ACCESS_TOKEN=<your-token>
# 3. Start (listens on 0.0.0.0:8500) → open http://<host>:8500/health
deepddw.exe
```
Upgrades are cheap: replace the whole folder with a newer zip — your data (under `%USERPROFILE%\.deepddw`) is untouched. See [`docs/windows-packaging.md`](docs/windows-packaging.md) for the full evaluation (PyInstaller one-dir + CI auto-build) and the manual build steps.
---
## Multi-Device on LAN (0.2.0)
deepDDW is built for **up to 20 devices on your LAN** sharing one gateway:
- **Device identity** — each browser persists a `device_id` (localStorage) and can set a friendly name on the launcher; reconnects keep the same identity.
- **Online status** — devices register/heartbeat to the gateway; `/api/v1/status` (Token-protected) shows who is online, active WebSockets, request counts, DB size and version. The launcher renders a live status card for admins.
- **Rate limiting** — sliding-window per Token + per IP (default 60 req/min/token, global cap → 503 overload protection); configurable via `config/deployment.yaml` → `security.rate_limit.*` or `DDW_RATE_LIMIT_*` env.
- **SQLite concurrency** — WAL + `busy_timeout=5000` + `synchronous=NORMAL` on every connection, plus a process-wide write lock for cross-table transactions (20 concurrent writers verified, no `database is locked`).
```
POST /api/v1/device/register # register / rename this device (idempotent)
POST /api/v1/device/heartbeat # keep-alive
GET /api/v1/status # status panel (token required)
```
**Also in 0.2.0:**
- **Workspace isolation** — devices pick a workspace (default `shared`); memory/logs and MCP memory tools are scoped per workspace, docs filtered by slug prefix. Legacy clients are unaffected.
- **Session resume across devices** — recent session summaries (up to 5) with a "continue" button: pick up a conversation on your phone where you left off on desktop.
- **One-click backup / restore** — backup via API (downloadable); restore validates the SQLite file (header + integrity check) and keeps a `.pre-restore` safety copy before replacing the main DB.
- **Optional TLS** — one-command self-signed cert (`scripts/gen_self_signed_cert.sh`, 1-year), enabled via `security.tls.*`; HTTP unchanged when off. For external access prefer a Caddy/Nginx reverse proxy (see `docs/tls.md`).
- **Version / upgrade check** — `/api/v1/version` reports `latest_version` / `update_available` (GitHub releases, 1h cache, offline-degraded); the launcher shows an upgrade banner.
---
## Security & Privacy
| Capability | Description |
|-----------|-------------|
| 🔐 Local-only data | Knowledge base & memory stay on your server, never leave the LAN |
| 🏠 LAN password-free | Optional (opt-in): LAN requests skip the token — **OFF by default** (set `DDW_LAN_BYPASS=1` to enable; trusted LANs only) |
| 🌐 External access | Optional Token gate (short-code supported); unauthorized → 401 |
| 🛡️ DSH secure binding | DSH stays on localhost; gateway exposes it — official security design preserved |
---
## Tech Stack & License
| Component | Description | License |
|-----------|-------------|---------|
| DSH engine | Official DeepSeek Harness (source untouched) | MIT |
| deepDDW gateway | FastAPI + SQLite + MCP dual-protocol | MIT |
| Memory / Knowledge base | SQLite storage (agentmemory / vectors optional) | MIT |
| Search | Optional SearXNG | AGPL-3.0 (server-side HTTP, exemption assessed) |
**deepDDW itself: MIT License** — free to use, modify, and commercially deploy; keep the copyright notice.
See [`NOTICE`](NOTICE) for full third-party attribution.
---
## Ecosystem & Feedback
- **Extend with official DSH plugins**: deepDDW keeps DSH's native plugin mechanism intact. Install official plugins straight from the npm registry via the DSH official command — the only channel we recommend, to avoid supply-chain poisoning:
```bash
dsh plugin --profile web add <npm-package> # official npm registry only
```
See [`SECURITY.md`](SECURITY.md) for our third-party plugin disclaimer and what deepDDW guarantees (memory & knowledge base only; no data theft/exploitation/sale).
- **Knowledge distillation**: use whatever **distillation skill / workflow** you prefer — the methodology is yours; deepDDW provides the complete pipeline "distilled output → searchable knowledge base → model-usable". More plugins and tools are on the way.
- **Memory / knowledge migration**: knowledge base uses standard SQLite; memory is organized by namespace/key/value — import from other agents or tools.
- **Feedback**: we'd love to hear how you use it; stronger open-source tools are coming in future releases.
---
## Commercial & Support
**deepDDW is free and fully featured forever.** The paid tiers exist for exactly two things: *convenience* (hosting, zero-ops) and *enterprise collaboration* (permissions, audit, compliance). Every core capability ships in the open-source build — there are no feature gates and no "Pro-only" paywalls, period.
| Tier | Price | Best for | What you get |
| --- | --- | --- | --- |
| **Open Source** | Free forever | Individual developers, self-hosters | MIT licensed, full features, no feature gates |
| **Pro Cloud** | ¥19/mo or ¥199/yr | People who'd rather not run it | Cloud-hosted memory & knowledge base, zero ops, managed multi-device sync, daily backups |
| **Founder License** (lifetime) | ¥499, one-time | Early supporters | Lifetime Pro. **Capped at the first 100 licenses — once they're gone, they're gone** |
| **Enterprise** | From ¥9,800/yr | Teams and companies | Multi-user & permissions, SSO, audit logs, private-deployment support (remote), commercial license letter, 24h priority response |
- Enterprise on-site deployment & implementation: ¥3,000 per engagement.
- VAT invoices available for corporate purchases.
- Sales & support: [GitHub Issues](https://github.com/ccch713/deepddw/issues).
### Pro Cloud — skip the ops
Everything you'd get from self-hosting, running in the cloud: hosted memory and knowledge base, managed multi-device sync, automatic daily backups. ¥19/month, or ¥199/year (works out to about ¥16.6/mo). Built for people who want the full deepDDW experience without owning a server.
### Founder License — lifetime, 100 seats only
Pay ¥499 once, keep Pro for life. A permanent thank-you to early supporters — **100 seats, first come first served, never restocked.** When the last seat sells, this tier is retired for good. No second wave.
### Enterprise — built for teams
User management and permissions, SSO, audit logs, remote private-deployment support, and a formal commercial license letter — the document your procurement and legal teams actually need. 24-hour priority response included. On-site deployment and implementation available at ¥3,000 per engagement.
### Sponsor — buy the author a coffee
Don't need any of the paid tiers? Totally fine — deepDDW stays free either way. Star the repo — it means a lot.
---
## Roadmap
Only items actually planned or already delivered are listed here.
**Delivered:**
- [x] **Multi-device on LAN (0.2.0)** — device identity/online registry, status panel, rate limiting, SQLite WAL concurrency (up to 20 devices)
- [x] **Workspace isolation (P1-1)** — per-workspace memory/knowledge scoping at the gateway (default `shared`, backward compatible)
- [x] **Session resume across devices (P1-3)** — "recent sessions" summaries (up to 5) with a continue button
- [x] **Optional TLS (P1-2)** — one-command self-signed cert; external access via Caddy/Nginx reverse proxy (see `docs/tls.md`)
- [x] **Backup / restore API (P2-1)** — one-click backup, downloadable; validated restore with `.pre-restore` safety copy
- [x] **Load-test report (P2-2)** — 5/10/20 devices: 0% errors, P95 ≤ 126 ms, no `database is locked` (see `docs/load-report.md`)
- [x] **Version / upgrade check (P2-3)** — `/api/v1/version` probes the latest release (1h cache); launcher shows upgrade banner
- [x] **Docker one-click deployment** — `docker compose -f deepddw-compose.yml up -d --build` (verified on a real macOS arm64 host: core + SearXNG containers up, health/MCP/chat end-to-end green)
- [x] **Session → document auto-ingest** — conversations saved to the knowledge base via `ddw.docs.save` / `ddw.session.docs` MCP tools + REST API, searchable and traceable per session
- [x] **Vector search enhancement** — hybrid retrieval (SQLite FTS5/LIKE + LanceDB, RRF fusion; optional, degrades to keyword-only when LanceDB is absent)
- [x] **Windows packaging** — PyInstaller one-dir build via the `windows-build` CI workflow, distributed as an Actions artifact, verified in release v0.1.0 (see `docs/windows-packaging.md`)
- [x] **Reflection & consolidation (LLM polish)** — daily reflection follows a style guide (auto/professional/casual), enforces a progress/issues/tomorrow structure and avoids repeating the previous day; consolidation skips logging when the LLM judges the conversation valueless
- [x] **Memory search quality** — results ranked by relevance score (hit-count × layer weight: user > notes > reflection > logs, plus freshness) instead of insertion order; keyword-expansion cache expiry tested
---
*deepDDW — enterprise-grade capability, open-sourced for everyone.*
Connection Info
You Might Also Like
No recommendations available