Clearailhc/clearai-dsh: an ontology-first preset that makes a research agent earn its edges

A task loop tracks completion, this one tracks grounds

The clearest statement of the design is a two-column table in the README comparing a standard agent task loop with what it calls the epistemic loop. A task loop asks what to do next and completes when the model says so. This one asks what is known and on what grounds, computes completion from delivered evidence, separates the verdict from the doer above a support level so the agent cannot judge its own work, and keeps failures instead of deleting them.

That last row is the philosophical commitment. The README puts it as an ontology versus a chat transcript: what accumulates is a growing structure where every edge was earned, rather than a record of what was said. The supporting claim about other systems is stated bluntly, that knowledge graphs typically pile up edges by extraction and assertion, whereas here every edge has to be earned through the loop.

The instrument inside the loop is a five-level axis, L0 to L4, with a pre-registered threshold drawn as a dashed line. Observations are plotted with error bars: the supported one filled, the inconclusive one a dashed circle, the refuted one left in place with a slash through it, nothing deleted. In the domain ontology that emerges, dark nodes are concepts, light ones value forms, emerald ones instances, and the loop's first fact becomes the graph's opening node.

Two design constraints are worth noting because they are enforced rather than advised. State is derived from the session record with no second store, so there is nothing to drift out of sync, and the tools the model holds contain no field in which it could declare a step complete. A goal finishes only after independent evaluation. The README is also explicit that the project does not claim recursive self-improvement, offering instead the epistemic substrate such a system would need.

What the plugin adds and what it leaves to the host

The scope boundary is stated in the README and it is a narrow one. ClearAI does only what the host cannot, namely the epistemic contract, the domain ontology and presentation. Goal continuation, subagents, asking the user, deliverable cards and file history all come from DSH itself.

That framing matters because it makes the install requirements concrete rather than aspirational. The host is the DeepSeek Harness, and the package declares its own compatibility floor in the manifest:

"engines": {
    "node": ">=22",
    "dsh": ">=0.1.7-alpha.1"
}

The README explains why that particular floor exists, saying that generation of the host introduced the composition declaration line this preset rides on, and that it has been verified against two host release candidates. A plugin pinned to an alpha of its host is normal this early in a plugin ecosystem, but it does mean the version numbers on both sides are moving.

The dependency list is worth a second look. The manifest declares exactly one runtime dependency, `zod` at `^4.6.1`, which is what you would expect from a package whose whole job is validating structured input at the boundary. Three other DeepSeek Harness packages appear in the manifest under a client injection block alongside a platform declaration of `web`, which are host-provided modules rather than things the package installs for itself. The client-side surface is a session controller, a right sidebar and a locale handler, which lines up with a tool that has to render a graph and speak the user's language.

The repository is not archived, the last push was on 2026-10-03, and there are only three open issues. That is a low number for a project of this size, and the changelog explains part of why: most of what used to be reported as issues was fixed at the mechanism level rather than papered over.

The changelog admits the dead ends, which is the best evidence in the repository

The three releases in the repository metadata form an unusually useful narrative, because each one is written around what was actually broken rather than around what was added.

Version 0.3.0 starts from three symptoms a user hit in a real session and traces each to a line of code. A close operation failed and took a long time, traced to the host being accessed half as a property, where a transient fiber drop throws and takes a finished evaluation with it. Propositions came out obscure, traced to the notion that a support level was only the maximum of the supporting evidence, so skipping a level cost nothing. And a well-built ontology still missed entities that had been found, traced to nodes and edges coming only from promotion after a whole goal was independently adjudicated. The fix in each case was to replace advice with a countable mechanism, verified in two real headless long runs.

Version 0.3.1 is the release that reads most like an honest post-mortem, and it is about two knots that could not be untied. A plan set to blocked could never be unblocked: the clearing event reset the consecutive-block count but left the plan's blocked flag in place, so all three documented ways out were unreachable and the inbox entry waiting on a human became a dead end. The second was a naming bug, where two blocking codes used underscores and violated the host's own lower-kebab-case contract, so the host refused to accept them and the session stayed active calling a goal that had already finished. The fix was renaming them, and the note adds that the test double was changed to throw on the same rule as the host, on the reasoning that otherwise you are only testing the double.

The same release also acknowledges a check that still fails: one of forty-five package verification checks, the one that runs `npm pack` in a sandbox and hits a read-only cache. Saying which check is still red is more useful than a green badge would be.

The ontology is JSON files, and that is the point

Version 0.4.0 rewrote the ontology storage from something else into a plain file tree, and the release notes are specific about the shape: JSON files under a `clear/ontology/` directory split into concepts, relations and entities, where a child placed in a directory of the same name encodes nesting, and nesting of a concept means an is-a relation while nesting of an entity means composition. The model writes these with its native file tools and the system writes a `SCHEMA.json` describing the format.

Three checks guard it. A single file is validated at write time and rejected if it fails, files are validated across each other at read time in a mode that flags rather than blocks and lists problems on the card and under the graph, and promotion triggers a full validation that refuses to promote on failure. The read-time choice is the interesting one: surfacing a problem without stopping the session matches the project's stated stance that conflicts should be reported and the decision to retract or keep belongs to a human.

Facts accumulate as files too, one per fact, each carrying a fingerprint of the definitions it was built on. If a definition changes, the fact is marked as having a changed definition and moves to a pending list, and an index file is rendered from all of them. That is a real advantage over a graph store you can only query through the tool: the output is greppable, diffable and reviewable, and it survives the tool.

The same release added full bilingual support, where the language follows what the person writes rather than the session default, covering tool results, cards, prompts, tool descriptions and the files the system writes under `clear/`. The state version went to 16, and older sessions are not migrated, which is worth knowing before you update mid-project. Version 0.4.0 also deleted the earlier documentation and replaced three fictional case studies with two real recorded ones, with the raw runs and both language sets of screenshots kept in the docs folder. A project removing its invented examples and publishing its actual runs has already told you something about how much to trust the rest of it.

Packaging details worth checking before you trust the tree

Installing is one command, and the README is emphatic that it installs a prebuilt package from the npm registry with nothing compiled locally, so there is no build permission to approve:

dsh plugin --profile web add [email protected]

The same instructions appear for the in-app plugin manager on the sidebar, with a note that the settings page list is read-only and installing happens on the sidebar. Pick ClearAI in the preset picker after restarting the web host.

The README then explains, at length, why the version in that command is pinned. pnpm 11 and later hold back newly published versions, with a default minimum release age of 1440 minutes, and because that built-in default is non-strict, a bare package name silently resolves to the newest version older than a day, which right after a release is the previous one. The host's plugin manager forwards your spec to pnpm unchanged and does not compare what landed against what you asked for, so the downgrade is reported as success. Its preview card does not help either, because it reads the package with a view command that ignores the age policy. The alternative offered is a one-time exemption in the workspace file:

minimumReleaseAgeExclude:
  - clearai-dsh

That is a long explanation for a short command, and it is worth reading because the same trap applies to any plugin you install into that host today.

Now the part that needs a second look. The manifest's published file list includes `lib`, `presets`, `bin`, `locale`, a patch file at the root and the brand assets, and its exports map and bundle declaration both reference paths under `presets/` and `./lib/`. The repository root listing, by contrast, shows `preset/` in the singular and contains no `lib/`, no `bin/` and no root patch file. Both facts can hold at once if `lib` is generated during packaging by the build script and if the presets directory is created or renamed as part of that process, and the manifest does ship a build and a verify script under `tools/` that would do exactly that. But if you want to read what this plugin actually does, the generated directory is the part you cannot see on GitHub. Read `docs/` and the changelog instead.

One smaller inconsistency in the same category: the root carries `package-lock.json`, while every install instruction is pnpm-based. The lock file tells you how the development environment was set up, not how the plugin is consumed.

What the README does not settle

This README is unusually long for a plugin readme and unusually argumentative about design, which makes the gaps easier to spot. It has no troubleshooting section. It does not say what happens to an ontology when the domain of a project turns out to be wrong, only that facts carry definition fingerprints and get flagged when those change. It does not explain how independent evaluation is scheduled or what it costs, only that above a support level the doer cannot be the judge.

It also does not say much about the graph itself. The rendering is described through screenshots and diagrams rather than through a description of the layout, the interaction model, or whether anything is queryable once written. For a tool whose output is a knowledge structure you are meant to keep, that is the part you would want described most and is described least. The upside is that the structure is files, so you can read it with any tool, including a text editor, which is the real answer to the question the README does not ask.

One more note on expectations. The README's single social-proof element is a weekly trends badge rather than adoption numbers, use cases, or testimonials, which measures attention rather than sustained use. For a project at 1,299 stars, three open issues and a 0.4.0 version number, that is a reasonable thing to weigh. The engineering decisions are better evidenced than the popularity: a broken mechanism named and fixed rather than worked around, a failing check left visible, fictional case studies deleted in favour of recorded runs, and a state store the model cannot lie to because it has no field to lie in.

Editorial conclusion

What makes clearai-dsh worth reading is that it treats a failed hypothesis as data rather than noise, refuses to let the model mark its own work complete, and writes the result out as plain JSON files you can read without the tool. The counterweight is that this is a preset for a host that is itself at release candidate stage, published at version 0.4.0 with a dependency on `0.1.7-alpha.1`, so the compatibility surface moves under you. The documentation is honest to its own cost, having deleted an earlier set of fictional case studies in favour of two recorded real runs. Start by installing the pinned version, reading the 0.3.1 notes for what dead ends the author already hit, and looking at `clear/ontology/` after a session to judge whether the loop earned its graph.

Frequently asked questions

Official sources

1. Clearailhc/clearai-dsh on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases