Local DeepSeek Harness deployment

English · 简体中文

These overlays load the built plugin through DeepSeek Harness without modifying the Harness repository. They are development artifacts, not an installer.

Required environment

Set these values in the plugin checkout's .env (loaded by the launcher), in the launcher's inherited environment, or in the Harness-home .env:

PASSIVE_MEMORY_DB_PATH=C:/absolute/path/passive-memory.db
PASSIVE_MEMORY_USER_SCOPE=one-stable-user-id
PASSIVE_MEMORY_AGENT_SCOPE=one-stable-agent-id
PASSIVE_MEMORY_WORKSPACE_SCOPE=one-stable-workspace-id

The scope values are retrieval isolation identifiers, not display names. Keep them stable across sessions that should share memory. Use different values for sessions that must not retrieve one another's evidence.

The hybrid overlay additionally requires every PASSIVE_MEMORY_EMBEDDING_* variable from .env.example. Do not place a key in any deployment YAML file. The plugin checkout's .env.local is used only by its development scripts; DSH does not discover that file automatically.

The ordinary episode overlay needs no additional model setting. It inherits the model already selected in DSH: native episodes use their last recorded assistant model, while external imports and user-only tails use the current Harness default. Standard DSH web already mounts llm-deepseek, the model settings surface, and agentDefaultModel; configuring DeepSeek for ordinary chat therefore configures episode compression too. The plugin does not own another API key. Enabling compression makes bounded background model calls and can incur the cost of that existing route.

To dedicate a different model to compression, set both PASSIVE_MEMORY_EPISODE_PROVIDER and PASSIVE_MEMORY_EPISODE_MODEL. Leaving both empty preserves inheritance; setting only one is rejected.

For a NewAPI/OpenAI-compatible endpoint, the convenience overlay passive-memory.episodes-newapi.cordis.yml also configures the built-in llm-pi-ai adapter. Set:

PASSIVE_MEMORY_LLM_BASE_URL=https://your-newapi.example/v1
PASSIVE_MEMORY_LLM_API_KEY=your-key
PASSIVE_MEMORY_EPISODE_MODEL=deepseek-v4-flash

The URL should be the OpenAI-compatible prefix whose chat endpoint is /chat/completions. The key remains an environment value; the YAML stores only its variable name. This overlay fixes the provider route id to passive-memory-newapi, so it does not need PASSIVE_MEMORY_EPISODE_PROVIDER.

Build and load

Copy .env.example to .env, fill the required non-secret paths/scopes, and build the plugin. The launcher renders the selected overlay with an absolute file:/// module specifier before passing it to Harness; this is necessary because Cordis resolves plugin module names from the active Harness profile, not from the source overlay's directory.

npm run build
npm run start:harness

With the default sibling checkout layout, this starts the episodes overlay. An explicit Harness checkout, overlay mode, and additional dsh web options may be supplied as follows:

npm run start:harness -- C:/absolute/path/deepseek-harness lexical --dump-config

The source overlays contain an intentional __PASSIVE_MEMORY_PLUGIN_SPECIFIER__ placeholder and should be launched through this script rather than passed directly to dsh --patch.

The lexical overlay performs no outbound memory request. To explicitly enable Gemini/OpenAI-compatible semantic retrieval, use passive-memory.hybrid.cordis.yml instead. That overlay sends eligible evidence text during bounded background cache-maintenance passes and sends each accepted direct prompt as an embedding query. New evidence remains immediately available to lexical recall and becomes semantic-searchable after a successful pass.

Use passive-memory.episodes.cordis.yml to retain local lexical recall while also creating traceable L1 summaries. External imported collections may be compressed immediately. A live session's open tail waits six hours by default; size, idle-gap, explicit, or compaction boundaries do not need that delay. This overlay also enables L1 clue recall and the native memory_expand and memory_search_raw tools. The package defaults remain off; select lexical when only automatic L0 excerpts are desired. See docs/neighborhood-memory-expansion-v0.1.md.

Use passive-memory.episodes-newapi.cordis.yml instead when the provider route does not already exist in DSH.

passive-memory.behavior-test.cordis.yml is a real-model validation overlay, not a normal deployment mode. It disables background compression, expects an isolated DSH_HOME and database, and points the credential provider at the operator-approved PASSIVE_MEMORY_TEST_CREDENTIALS_PATH. Seed only controlled synthetic L0/L1 with npm run validate:active-memory:seed; inspect content-free results with npm run validate:active-memory:inspect. The launcher accepts behavior-test as the overlay mode.

The supplied hybrid overlay uses lexical-fallback: a transient external query embedding failure keeps local lexical recall available and is recorded without the provider's response text. Set semanticFailurePolicy: fail-request when a deployment must reject any request whose semantic leg cannot run.

Background document failures retry from semanticMaintenanceRetryBaseMs with doubling delay capped by semanticMaintenanceRetryMaxMs. A success resets the failure streak and restores semanticMaintenanceIntervalMs. Operational state is available through ctx.passiveMemory.embeddingMaintenanceStatus().

Inspect the composed DSH tree without booting the application:

npm run start:harness -- C:/absolute/path/deepseek-harness lexical --dump-config

The local database is schema-versioned and migrates versions 2 through 6 to version 7 in place. A v5 L1 route retains its original fixed-model meaning; v6 episodes are backfilled into the rebuildable L1 clue index. Back up any material database before testing a newer prerelease.