Introduction

The conversational context in DeepSeek Harness (DSH) is usually lost when a session ends, making it difficult to support long-term memory or cross-session knowledge accumulation. The dsh-local-vector-memory plugin addresses the agent’s runtime dependency on long-term context through local embedding vectorization, single-file SQLite storage, and automatic recall mechanisms. It does not require setting up a complex database environment and can run directly using the built-in capabilities of Node.js >= 22.5.

Core Capabilities

The plugin mainly includes the following functional modules:

  1. Local Vectorization and Storage: Uses the built-in node:sqlite in Node.js >= 22.5, together with a local embedding service to vectorize text and store it in a single-file SQLite database.
  2. Automatic Recall Injection: Before each agent inference step, retrieves the top-K related memories and injects them into the context (using the <local-memory> tag). Supports LRU deduplication within a session.
  3. Cloud Extraction: Supports invoking the DeepSeek cloud deepseek-v4-pro model at session end to automatically extract memories (optional; by default, automatic clue-based capture is used).
  4. Conflict-Aware Memory: During writes, detects conflicts with existing memories or outdated entries (similarity >= 0.86 but not a complete duplicate) and prompts the user to use memory_update to update the old memory.
  5. Trash Mechanism: memory_forget performs a soft delete by default, and memory_restore can restore memories; permanent deletion requires the purge=true parameter.
  6. Online Backup: Uses SQLite VACUUM INTO to generate a consistent snapshot, retaining the latest 5 backups by default.
  7. Low-Value Filtering: Versions v0.3.4+ automatically intercept low-value content before persistence, such as transient states, pure progress updates, and one-time parameters.
  8. Fault Tolerance and Fallback: Supports HTTP batch vectorization (automatically falls back to item-by-item processing on failure); if the embedding service is unavailable, it degrades to Chinese- and English-language keyword matching.

Installation and Enablement

The installation command is shown below, specifying the web profile:

dsh plugin --profile web add dsh-local-vector-memory

After installation, dsh.profile.bundles is appended automatically, and restarting the DSH Web service makes it effective.

Tools

The plugin provides the following tools for invocation:

  • memory_add: Writes a long-term memory (automatic deduplication + conflict detection).
  • memory_search: Vector search (supports tag filtering; automatically falls back to keyword search if embedding fails).
  • memory_list: Browses memories (supports tag/source filtering; includeDeleted=true views the trash).
  • memory_update: Updates text/tags by id (automatic re-vectorization).
  • memory_forget: Deletes by id (soft delete by default; purge=true permanently deletes).
  • memory_restore: Restores soft-deleted memories.
  • memory_backup: Performs an online SQLite backup to ~/.dsh/backups/memory.
  • memory_stats: Database status + soft delete count + service address.
  • memory_reindex: Adds vectors to un-vectorized entries in batch.
  • memory_extract: Invokes an extraction model to distill memories from a text snippet for storage (short text only, recommended ≤2000 characters).
  • memory_merge: Merges duplicated or same-topic memories (retains one entry and soft-deletes the rest).
  • memory_health: Health report (entry count / soft deletes / un-vectorized entries / pin distribution + duplicate pair detection).

Configuration and Dependencies

Environment Requirements

  • DSH: The web profile must be used.
  • Node.js: Version >= 22.5 is required (with built-in node:sqlite).
  • Local Embedding Service: An OpenAI-compatible local embedding service is required (Qwen3-Embedding-0.6B + llama-server is recommended).
  • Cloud Extraction (Optional): The official DeepSeek cloud API (deepseek-v4-pro) is required for memory extraction; by default, automatic clue-based capture is used.

API Key Security

⚠️ Do not write the API key into any files that will be committed. The key should be stored only locally; three formats are supported:

extractionApiKey: "${DEEPSEEK_API_KEY}"        # 1. 环境变量
extractionApiKey: "dsh:DEEPSEEK_API_KEY"       # 2. DSH 凭据库(~/.dsh/.credentials.yaml)
extractionApiKey: "local-no-auth"              # 3. 明文占位(仅限免认证的本地服务)

Configuration Override

The default configuration is in lib/config.mjs. It can be overridden via ~/.dsh/profiles/web/cordis.patch.yml. Note that DSH patches use whole-section replacement rather than deep merging, so it is recommended to write only the fields that need to be changed.

Notes

  • Patch Mechanism: DSH patches use whole-section replacement rather than deep merging; pay attention to the scope of overrides when changing configuration.
  • Low-Value Interception: Versions v0.3.4+ automatically intercept low-value content before persistence, such as transient states, pure progress updates, and one-time parameters, to avoid diluting retrieval quality.
  • Pre-Installation Check: The plugin runs with the permissions of the current DSH process; source code and license should be reviewed before installation.