jev-lcm-dsh-compaction

Jev-LCM Compaction Plugin for DeepSeek Harness

Jev-LCM Compaction Plugin for DeepSeek Harness is an experimental dsh-plugin bundle that puts Jev scoring before a DSH compaction pass and keeps a local SQLite evidence surface beside it. It exists in response to the failure modes reported in hermes-agent PR #116246: Jev-only compaction missed assistant-text identifiers, saturated its state budget, and eventually met a growing text floor. This checkout does not claim live provider success, production parity, published npm availability, or full LCM equivalence.

What problem does hermes-agent PR 116246 identify?

PR #116246 evaluated Jev-only compaction against a production path and rejected it as a drop-in replacement. Its reported findings were:

The numbers in the first column belong to the cited PR. They are not fresh measurements from this repository.

What does this plugin do?

• Ingests raw material into the package's SQLite archive before Jev scoring.
• Scores matched tool-result pairs and selected assistant-text anchors.
• Leaves raw rows unchanged. The archive owns raw evidence; Jev never rewrites it.
• Uses calibration rather than the rejected fixed 0.5 default.
• Batches scoring and marks candidates beyond the state cap jev_unscored.
• Accepts TYPESAFE_API_KEY, OPENROUTER_API_KEY, or both, with automatic fallback in auto mode, or runs entirely locally against a Laya server with no key at all, or, as an explicit opt-in, tries the local server first and keeps the hosted providers behind it as a fallback.
• Accepts Cloudflare Clef as a fourth provider surface, either as jev_provider: clef or as a named member of jev_fallback_order. It needs CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN, and clef-flash is a checkpoint on that one provider rather than a separate one.
• Exposes lcm_grep, lcm_expand, lcm_nodes, jev_stats, jev_providers, jev_scores, jev_anchors, and jev_calibrate as session-scoped tools.
• Keeps ordinary host condensation available when Jev is disabled or fails.

The archive and tools are package behavior. They do not establish that every DSH host prompt consumes the assembled hints exactly as Hermes LCM does.

How does the DeepSeek Harness context engine pipeline work?

new turn
   |
   v
archive raw messages and tool material
   |
   v
extract assistant-text anchors
   |
   v
batch Jev candidates
   |       T0..T4 state shaping and provider fallback
   v
rank calls, results, and anchors
   |
   v
native DSH compaction plus bounded evidence hints
   |
   v
active-session tools: lcm_grep, lcm_expand, lcm_nodes

Jev is a ranking layer. It does not summarize or mutate raw rows. Candidate actions are keep, truncate, defer/drop, or unscored. A candidate at or above the live threshold is eligible for protected inclusion, subject to the engine's hint budget and the host's own prompt budget. A truncated candidate keeps a bounded head and a pointer to the raw row. Deferred and unscored material remains in the local archive when storage is healthy.

The shrink ladder starts with full state, then shortens tool inputs and result bodies, and ends with folded old messages. If the hard cap still does not fit, the remainder is marked jev_unscored rather than assigned a fabricated score. Calibration begins with keep_threshold, then uses the configured rolling keep-rate quantile after the minimum sample count. DSH's native BasicCompactionEngine remains the host compaction path; this package is not a full TypeScript port of Hermes LCM.

Can I use TypeSafe, OpenRouter, or both with this plugin?

Yes at the configuration and adapter level. The repository accepts either key alone or both. In auto mode it filters the configured order to providers with present keys, tries the first available provider, and can try the next provider for configured transport, timeout, authentication, rate-limit, or server failures. A typical sanitized fallback line is:

jev_provider_fallback from=typesafe to=openrouter reason=429

Key values are never printed. Jev provider fallback covers configured transport, timeout, authentication, rate-limit, and server failures only. The current OpenRouter adapter targets the repository's /alpha/decisions path. Verify that endpoint against the provider you intend to use before sending real conversation data. No live provider success claim is made here.

How does Jev-LCM compare with Jev-alone and LCM-alone?

This is an architecture comparison, not a benchmark result. DSH's archive is not claimed to be equivalent to Hermes LCM's SQLite DAG.

What changed after PR #116246?

The project follows the PR's conclusion that a summary path is still required. FIX-1 adds threshold calibration. FIX-2 reaches assistant-text anchors. FIX-3 keeps host compaction primary. FIX-4 adds the hard-capped shrink ladder. FIX-5 batches requests. FIX-6 exposes provider, threshold, unscored, freed-space, and recall fields. The provider chain accepts TypeSafe and OpenRouter credentials with fallback. These are implementation targets and local behaviors, not proof of production parity with the PR's reference path.

How do I discover and install the plugin into DSH?

DeepSeek Harness is developer-preview software. Confirm the CLI and profile before changing a real installation:

dsh --help
dsh plugin --help
dsh plugin --profile web list

For a source checkout, use the repository's pinned toolchain:

git clone https://github.com/bojansandhaus/jev-lcm-dsh-compaction.git
cd jev-lcm-dsh-compaction
npm install
npm run build
npm test
npm pack

The local test result and the package archive are not proof of a fresh installation. Registry publication is not asserted. In a disposable DSH profile, install the checkout or reviewed package with the host's plugin command. The documented form is:

dsh plugin --profile web add github:bojansandhaus/jev-lcm-dsh-compaction
dsh --profile web --dump-config

The verified CLI uses dsh --profile web --dump-config. Plugin management requires an explicit profile. A config dump shows composition only. It does not prove runtime loader mounting, a committed compaction, live provider access, or prompt parity.

Enable one compaction owner only. The bundle patch disables the native compaction-basic row and inserts jev-lcm-compaction. Do not load this package beside another bundle that replaces the same row.

What configuration does the DSH bundle expose?

The bundle schema in src/index.ts currently exposes these DSH-level values:

The engine defaults in src/settings.ts include jev_provider: api_only with api_provider: auto, TypeSafe base https://api.typesafe.ai/v1, OpenRouter base https://openrouter.ai/api, TypeSafe path /systemone, OpenRouter model ~typesafe/jev-latest, Laya base http://127.0.0.1:8000 with path /v1/systemone, a 0.15 fallback threshold, a 0.40 threshold cap, a 0.10 minimum keep rate, a 500-sample calibration window, a 50-sample calibration minimum, a three-turn batch window, a 300-candidate batch cap, a 25,000-token state cap, and a 30,000-token request cap. jev_provider also accepts the DOGA fork's laya_local and laya_with_jev_fallback as aliases for laya and laya_then_hosted, resolved to the canonical value at configuration time. See docs/reference.md for the complete table and validation rules.

Provider environment variables are:

export TYPESAFE_API_KEY='set-through-your-secret-manager'
# or:
export OPENROUTER_API_KEY='set-through-your-secret-manager'
# or Clef on Cloudflare Workers AI (needs both values; the account id is
# configuration, the token is the credential):
export CLOUDFLARE_ACCOUNT_ID='0123456789abcdef0123456789abcdef'
export CLOUDFLARE_API_TOKEN='set-through-your-secret-manager'
# with several keys, leave jev_provider at auto for fallback
# or run locally with no key: start laya-serve and set jev_provider to laya
#   (the DOGA fork's name for this mode is laya_local)
# or lead with the local server and fall back to a hosted key:
#   jev_provider: local_with_api_fallback   # DOGA fork name: laya_with_jev_fallback
#   (needs at least one hosted key; a failed local attempt then sends the
#    state to that hosted API, and three consecutive local failures suppress
#    the remote leg until a local call succeeds)

Do not put real credentials in a profile file, patch, issue, test fixture, or log. The example values above are placeholders, not credentials.

Can I use Cloudflare Clef as a provider?

Yes, as a fourth provider surface alongside TypeSafe, OpenRouter, and a local decision model. Clef is Cloudflare's typed decision model, served on Workers AI, so no Worker, GPU, or self-hosted deployment is involved: the adapter calls Cloudflare's per-account endpoint directly.

export CLOUDFLARE_ACCOUNT_ID='0123456789abcdef0123456789abcdef'
export CLOUDFLARE_API_TOKEN='set-through-your-secret-manager'
# choose the checkpoint; `clef` is the default
export JEV_CLEF_MODEL='clef'   # or 'clef-flash'

The account id is configuration rather than a secret, but it appears in the request URL. The token needs Account > Workers AI > Read and is sent as a bearer token in the Authorization header. Both are checked before any request is sent, and a missing one fails by naming the variable.

What category of model is this?

These are System One decision models, also written "typed decision models". That is TypeSafe's own term for the category, coined alongside Jev, and it describes a model that returns typed values with a probability for each rather than prose: a Choice picks one option from a list you define, a Score places content on an ordered scale, and a Noul answers yes or no with a number from 0 to 1. The reference for the category is https://systemonemodels.org/guides/what-is-a-system-one-model/

The members this repository names, and where each one runs:

Jev is one vendor's member of this category, not the category itself, so this documentation names the category System One rather than after any single vendor.

Which four modes are there, and what do they mean?

Configuration exposes exactly four decision modes. Each names which side leads and whether the other side is a fallback.

The mode does not name which hosted provider, because that is a separate setting. api_provider picks it: typesafe, openrouter, clef, or auto to take the usable members of jev_fallback_order in order. So api_only with api_provider: clef is Clef alone, and api_with_local_fallback with api_provider: clef is Clef first with the local model behind it.

A mode that promises a fallback but has no usable provider on the other side fails at load, naming the missing environment variables. A pinned api_provider that cannot authenticate is a load error too, because naming it asserted something about the deployment. auto with nothing usable is not an error: ranking is simply disabled and host compaction continues.

Earlier mode names keep working:

Two of those carry a provider pin that the mode name used to imply: clef, clef_api, and clef_with_local_fallback still select Clef, unless you set api_provider yourself. auto keeps its old meaning of choosing among keyed hosted providers, and it only gains a local hop when you have pointed the local slot at a real engine, so a hosted-only profile routes exactly as it did.

Can the local model be something other than Laya?

Yes, by configuration alone. The local side is Laya or other pre-deterministic routing models: local_model is the checkpoint or engine name sent to the local server, and it is deliberately not an allowlist, so a pre-deterministic routing model released tomorrow works without a code change:

jev_provider: local_only
local_model: your-local-engine   # the checkpoint or engine name your local server serves

The name is validated only for being non-empty and safe inside a URL path segment or a JSON string. Pointing the local slot at a different engine is a URL change: a self-hosted engine server such as chaitin/Decis publishes pre-deterministic routing models behind one Jev-compatible /v1/systemone endpoint with one image per engine, where swapping base_url is the whole migration.

laya_model is superseded by local_model and still read when local_model is left at its default, so an existing profile keeps working. local_model wins whenever it is set explicitly.

No local model other than the default has been called live from this repository: no engine server is running here, so the interchangeability above is a contract claim from those projects' published documentation, not a measurement.

Privacy matters more here than in the other adapters. This plugin ranks conversation content before a compaction pass, so a hosted review sends the reviewed state off the machine on every call, not only when a fallback is reached. The local modes are the only ones that keep it on the machine. Failure logs record the provider and the exception category only, never the state, candidate text, answers, or a credential.

Which commands and tools are available?

The plugin registers these session-scoped tools through Cordis:

• lcm_grep: search archived evidence in the active session.
• lcm_expand: expand an archived row by store id.
• lcm_nodes: inspect archive node status.
• jev_stats: read counters and threshold state.
• jev_providers: inspect provider order, environment-variable presence, cooldowns, and sanitized errors.
• jev_scores: inspect candidate ids, scores, actions, and jev_unscored state.
• jev_anchors: inspect anchor candidates.
• jev_calibrate: read the live threshold and calibration state, or pass dry_run for one synthetic probe per configured provider with latency and status.

The exact DSH command used to invoke a tool depends on the host CLI. The source registration is in src/index.ts. Treat a tool result as session-scoped evidence, not as proof that the host committed a compaction.

What does observability show?

jev_stats can expose candidate totals, keep counts, anchor counts, unscored counts, Jev calls, fallback counts, current and calibrated thresholds, the last provider, LCM node counts, text-floor estimates, freed-per-compaction, and the unevaluated recall field. jev_providers reports provider order and names of present environment variables, never key values. Three consecutive compactions below 20 percent freed space produce a warning in the metrics implementation, and a suppressed local fallback produces one laya_fallback_suppressed warning with the count, the limit, and the failure category. No log line on the scoring path carries a request, a state, candidate text, or an answer.

The local tests cover deterministic calibration, provider fallback, exact spans, overflow handling, concurrency, and Cordis loader composition. They do not verify fresh installation, live provider quality, real billing, production latency, sustained sessions, or comparative recall.

Why use this design for Jev compaction for DSH?

The boundaries stay visible. The archive keeps raw evidence. Native DSH remains responsible for host compaction. Jev ranks candidates and can stand down when its provider is unavailable. That gives operators a recoverable evidence surface without pretending that this package delivers Lossless Context Management for DeepSeek Harness with full Hermes LCM semantics.

Is this compatible with my DSH installation?

The package declares Node >=22.19.0, Cordis 4.0.2, and DSH 0.1.6-alpha.2 peer packages. DeepSeek Harness is developer-preview software, so compatibility-breaking changes are expected. Pin the DSH range used by your test suite. The repository has local build and test coverage against its installed dependencies. Verified on 2026-09-21: a disposable DSH profile loaded the bundle through the host loader (tests/loader.test.ts), the packaged archive installed from a tarball, and both provider surfaces answered live scoring requests with synthetic text only (see docs/verification.md). Tested against Node >=22.19.0, Cordis 4.0.2, and DSH 0.1.6-alpha.2; pin that range, because the harness is in developer preview and may change its interfaces.

What are the DSH plugin conventions?

package.json declares the dsh.bundle.patch manifest and points it at cordis.patch.yml. The patch disables compaction-basic and inserts a distinct jev-lcm-compaction row. src/index.ts exports apply(ctx, config), declares llm, tokenMeter, sessions, and tools injection, registers the engine's tools, and uses the Cordis lifecycle. The example patch is examples/cordis.patch.yml. Keep its row unique in a profile.

Who created the ideas behind this project?

• Tamara Tran, fast-jev-compaction, MIT: state shaping and keep/truncate/drop lineage.
• TheEpTic, hermes-jev-compact, MIT: Hermes integration lineage.
• Stephen Schoettler, hermes-lcm, MIT: SQLite, DAG, active-context, and recall lineage.
• Bojan Sandhaus, jev-decisions, MIT: Decisions-shaped context and documentation lineage.
• TypeSafe: Jev model and Decisions API lineage.
• OpenRouter: alternate provider surface used by the adapter.
• Cloudflare Clef: typed decision model served on Workers AI, used as a fourth provider surface.
• Ehrlich and Blackman, Voltropy PBC: LCM paper lineage.
• DeepSeek Harness and Cordis: DSH host and plugin lifecycle.
• Hermes maintainers and PR #116246: evaluation findings and the reason for this pre-pass design.

This repository is an independent community integration. It does not claim authorship of those projects.

Frequently asked questions

What happens if Jev is down?

The provider chain records a sanitized failure and the engine can continue without Jev scores. Native host compaction remains available; raw archive behavior depends on the local store being healthy.

Does the plugin store more data?

Yes. It maintains a local SQLite archive and metadata for recovery. The archive is not encrypted by this package. Set a private databasePath and exclude it from source control.

Can I use OpenRouter?

Yes. Set OPENROUTER_API_KEY and choose jev_provider: openrouter, or leave auto enabled. Verify the adapter endpoint and model contract before sending production data.

Can I use both keys at once?

Yes. With auto and fallback enabled, the configured order selects the first available provider and can try the next provider on configured failures.

Can I run it locally with Laya instead of a hosted provider?

Yes. You either point the plugin at TypeSafe or OpenRouter with a key, or you run Laya on your own machine with no key at all. Laya is not a hosted Jev endpoint; it is a separate local model, and the laya-serve server it ships publishes POST /v1/systemone in the same Decisions contract as TypeSafe, so the local route replaces the hosted pair for that profile rather than joining it.

python -m pip install laya
laya-serve              # LAYA_HOST, LAYA_PORT, LAYA_DEVICE, LAYA_THREADS, LAYA_MODELS, LAYA_API_KEY

- id: jev-lcm-compaction
  name: '@bojansandhaus/jev-lcm-dsh-compaction'
  config:
    jev:
      jev_provider: laya
      laya_base_url: http://127.0.0.1:8000
      laya_model: english
      request_timeout_s: 120

The defaults are laya_base_url http://127.0.0.1:8000, laya_endpoint_path /v1/systemone, and laya_model convaiinnovations/laya,