deepddw

# 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.*