# Hypha keeps the cache fast and forbids it from being true

> Hypha splits an agent system into an Agent Core for reasoning and a Production Harness for bounded, event-backed execution, and pushes product behaviour into a compiled DomainPack. Its most distinctive rule is that the Cache and Reuse Plane may accelerate execution but can never become authority or replace event, artifact, receipt or checkpoint evidence.

**CodeSoul-co/Hypha** — Harness-oriented agent system framework for production-grade LLM agent applications

- Repository: https://github.com/CodeSoul-co/Hypha
- Website: https://codesoul-co.github.io/Hypha/
- Stars: 447 · Forks: 126
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/codesoul-co-hypha

## Two layers, and product behaviour lives outside the runtime

The framework is built from two cooperating layers rather than one agent loop. The Agent Core owns reasoning and ReAct, planning, tool selection, Memory access, and model and context orchestration. The Production Harness owns everything about making that reasoning survive contact with reality: FSM execution, Event and checkpoint control, policy and approval, continuation, recovery, audit and replay. The split matters because the two halves have different failure modes, and a Core that reasons well but cannot be resumed is not a production component. The third piece is the DomainPack, and it is where the design bet shows. Product-specific behaviour is declared there rather than hard-coded into the runtime, and a DomainPack compiles tasks, workflows, capabilities, prompts, Memory, policy, evaluation and output contracts into the shared Core plus Harness. The consequence is that one runtime can serve a coding agent, a finance agent, a legal agent or a research agent by swapping the DomainPack, the capability bindings, the policies, the evaluation contracts and the domain state.

## The cache is allowed to be fast and forbidden to be true

This is the sentence that explains the rest of the design. The Cache and Reuse Plane spans reasoning, tools, Memory, execution and inference, and it reuses validated work across all of them, but it is explicitly a disposable projection. Cache state can accelerate execution, and it can never become authority, and it can never replace Event, Artifact, receipt or checkpoint evidence. The same constraint is restated structurally: a cache tree is a lookup structure, while Event and Artifact evidence remain the source of truth. That is a stronger position than most caching layers take, and it is the reason the framework can sit underneath an auditable agent. A cached answer that has been invalidated is just a slower fresh computation. A cached answer that has quietly become the record of what was decided is a correctness bug with no recovery path. Six layers exist precisely because that guarantee is per layer, and a single response cache could not make the same promise about a reasoning subgraph or a KV prefix. The same reasoning is why the framework treats reuse as something you must earn rather than something you inherit. Reusing a reasoning subgraph is only safe when you know which strategy version, which prompt blocks and which tool schema produced it, and a cache keyed on the request text alone cannot tell you. Reusing a tool result is only safe when you know the capability revision, the policy in force and what the external state looked like at the time. Reusing a memory projection is only safe when you know which mutation generation and which source revision it came from. Each of those facts has to travel with the entry, which is why the validity columns in the layer table are longer than the reusable-unit column.

## Six cache layers because six things expire differently

Cache here is a control plane, not one feature, and the table below is really a statement about invalidation requirements. The Serving Cache holds an exact normalized model response, and its validity depends on model and provider identity, the normalized request, scope, a TTL and response validity. The Thinking Cache holds a reasoning node, a path or a reusable subgraph, which additionally invalidates on the reasoning strategy version, prompt blocks, the tool schema and inference parameters. WorkCache holds event-derived typed agent work, keyed to source-event provenance, dependency and revision closure, scope, validity state and future demand. The Tool and Execution Cache is restricted to eligible read-only results or deterministic ones, and it depends on capability revision, Policy, external-state evidence, an environment snapshot, idempotency and scope. The Memory and Context Cache holds search results and assembled projections, invalidated by memory scope, mutation generation, source revision, provenance and context policy. The Prefix and KV Cache holds prompt-prefix blocks, provider prefixes and backend KV segments, scoped to model and backend, Agent, Session and Domain, prompt dependencies and prefix revision.

## A cache tree lets you insert and invalidate one leaf at a time

The physical structure is described in three parts and each part has a job. A typed root partitions reusable artifacts, so different kinds of cached thing do not share a namespace by accident. Compact parent nodes sit above the leaves and route lookups by hash prefix, which is what keeps the tree from degenerating into a linear scan. Full logical keys live at the leaves, where the precise identity of the artifact is recorded. The payoff is symmetric. A new leaf can be inserted without rebuilding unrelated branches, and a stale leaf can be invalidated locally rather than by dropping a whole layer. Both properties are what you need in production, where new work arrives continuously and where invalidating everything because one prefix changed is how a cache turns into an outage. The important qualifier is that none of this changes where truth lives: the tree optimises lookup, while Event and Artifact evidence stay authoritative. Physical locality is a performance decision and nothing more, which is why it is safe to let different layers use different tree shapes.

## WorkCache extends the lookup pattern into four semantic trees

For agent execution specifically, WorkCache turns the same structure into semantic trees rather than generic keyed trees, and the naming is doing real work. `PlanTree` reuses plans, plan branches and reusable planning artifacts, which is where a partially explored plan gets reused instead of re-derived. `ComputationTree` holds reasoning and computation nodes plus derived work, and the README identifies it as the natural backing plane for the Thinking Cache, which is the link between the raw cache layer and the semantic view of it. `ToolTree` holds eligible tool-call results together with their provenance and validity metadata, so a reused tool answer carries the evidence that made it eligible in the first place. `ObservationTree` holds reusable observations tied to source evidence. The visible copy of the README stops partway through that row, so the remaining rows of the semantic tree table, and anything the rest of the document covered after the cache chapters, cannot be confirmed from what is shown. The through-line across the four is that reuse always ships with its own validity metadata rather than as a bare value.

## Sixteen build targets and two separate test runners

The manifest shows the shape of the codebase. The root package is private, version 1.0.1, and its workspaces are `packages/*` and `apps/*`, with the server entry point at `dist/apps/server/app.js` and only `dist` plus the README shipped in the published files. Building the packages is one TypeScript project reference invocation naming sixteen targets: core, storage, inference, fsm, kernel, harness, models, serving-cache, workcache, memory, tools, mcp, skills, domain, adapters-local and testing. Server and CLI build separately, and the CLI step ends by running `scripts/make-cli-executable.mjs`, which is a detail that only matters if you are packaging the binary. Two test runners coexist rather than one: Jest for unit tests, invoked through `node --experimental-vm-modules` with project selection and open handle detection, and Vitest for the acceptance side, with a dedicated `vitest.execution-acceptance.config.ts` alongside the main `vitest.config.ts`. The test script chains unit, packages and integration. There is also a documentation generator, an audit script and a release check that builds every workspace before publishing.

## config.yaml holds safe defaults and .env holds what you must not commit

Configuration is split in two on purpose, and the comments in `.env.example` state the reason: `config.yaml` defines typed structure and safe local defaults, while `.env` should hold deployment specific URLs, credentials and local paths. The overlap protection is explicit too. An optional user-owned YAML file is merged over the tracked `config.yaml` template so that framework updates do not overwrite product settings, and six path variables point at that file and its siblings for agent config, tool config, workflows, prompt templates and the prompt registry. Local defaults are visible and deliberately obvious: host on all interfaces, port 3000, an API prefix of `/api/v1`, a storage deployment and profile both set to local, and an owner block with a placeholder email, username, password and display name. Two of those are a security decision rather than a convenience one. The JWT secret ships as a change-me local value and the owner password is a literal local string, so both must be replaced before anything but your own machine can reach the server. Storage is configured in blocks, MongoDB for documents and Redis for messaging, cache and streams, where an empty URI means local host and port and a `rediss://` URL means a managed TLS provider. The canonical Memory runtime defaults to MongoDB plus Redis, while external profiles use MongoDB for durable mappings and operation evidence and do not require Redis. Two fallback variables are also recognised at runtime for the Redis connection, `KV_URL` and `RENDER_REDIS_URL`, and the presence of a `render.yaml` at the top of the tree explains the second of them. Beyond the two configuration files, the tree is conventional: `packages/` and `apps/` hold the code, `configs/` and `config.yaml` the tracked structure, `docs/` and `website/` the published guide, `scripts/` the build and audit tooling, `examples/` two worked cases, an MCP example and a release agent, and `UPGRADING.md` and `CHANGELOG.md` the version history. There is a brand policy document too, which is unusual for a framework and suggests the package names and presentation are treated as an asset.

## Conclusion

Adopt Hypha when you are building the same agent product more than once, because the argument for it is reuse: one Core plus Harness, many DomainPacks, and a cache that spans reasoning, tools, memory, execution and inference without any of those becoming the record of what happened. Do not adopt it for a single agent, since the harness machinery, sixteen build targets and the typed configuration surface are real overhead on top of a ReAct loop. Three things to check before committing. That your domain really belongs in a declarative DomainPack rather than in runtime code, because the framework's central bet is that it does. That your cache invalidation requirements fit the six defined layers, since an exact response and a KV prefix do not expire alike. And that the shipped defaults are treated as local placeholders, in particular the JWT secret and the owner password, which are set to obviously local values and must be replaced before the server is reachable by anyone else.

## FAQ

### What is Hypha?

An Apache-2.0 TypeScript framework built from two layers, an Agent Core for reasoning, planning, tool selection and memory access, and a Production Harness for FSM execution, policy and approval, checkpoints, recovery, replay and audit. The public release is v1.0.1, published as 15 aligned packages named @codesoul-co/hypha-*.

### What does a DomainPack do in Hypha?

It declares the product-specific parts outside the runtime. A DomainPack compiles tasks, workflows, capabilities, prompts, Memory, policy, evaluation and output contracts into the shared Core and Harness, which is how one runtime can serve a coding, finance, legal or research agent by swapping the pack, the capability bindings and the policies.

### Why does Hypha treat its cache as disposable?

Because a cache must never be the record. The Cache and Reuse Plane can accelerate reasoning, tools, Memory, execution and inference, but it can never become authority or replace Event, Artifact, receipt or checkpoint evidence. The physical cache tree is described purely as a lookup structure for the same reason.

### What do I need to configure before running Hypha locally?

config.yaml already carries typed structure and safe local defaults, so .env only needs deployment specific values. Storage is configured per service: MongoDB for documents and Redis for messaging, cache and streams, where an empty URI means local host and port. Replace the placeholder JWT secret and owner credentials before the server is reachable by anyone else.

### How many cache layers does Hypha define?

Six: a Serving Cache for exact normalized responses, a Thinking Cache for reasoning nodes and reusable subgraphs, WorkCache for event-derived typed work, a Tool and Execution Cache restricted to eligible read-only or deterministic results, a Memory and Context Cache for projections, and a Prefix and KV Cache for prompt prefixes and backend KV segments. Each carries its own validity boundary.

## Sources

- [CodeSoul-co/Hypha on GitHub](https://github.com/CodeSoul-co/Hypha)
- [License: Apache-2.0](https://github.com/CodeSoul-co/Hypha/blob/main/LICENSE)
- [Project website](https://codesoul-co.github.io/Hypha/)
- [README](https://github.com/CodeSoul-co/Hypha/blob/main/README.md)
- [Releases](https://github.com/CodeSoul-co/Hypha/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/codesoul-co-hypha