Hypha: a TypeScript Agent Core with a Production Harness for governed agents

The problem Hypha targets: agent logic that cannot be audited or resumed

Most TypeScript agent codebases start as a loop around a model call. That loop is fine until a tool writes to an external system, a run takes twenty minutes, or someone asks why the agent chose a particular action last Tuesday. Hypha's answer is to split the system in two. The Agent Core handles reasoning and ReAct, planning, tool selection, Memory access, and model/context orchestration. The Production Harness takes those decisions and executes them under FSM control with events, checkpoints, policy and approval, recovery, replay, and audit. The README frames the goal as "bounded, event-backed execution", which is a different promise from a framework that only helps you compose prompts. The audience is a team building a domain agent (coding, finance, legal, research) that has to survive restarts and answer questions about its own history. If your agent is a one-shot summarizer, this is more machinery than the problem needs.

DomainPack, Agent Core, Harness: how a task actually flows

Product-specific behavior lives in a DomainPack, not in the runtime. According to the README, a DomainPack declares tasks, workflows, capabilities, prompts, Memory, policy, evaluation, and output contracts, and those declarations are compiled into the shared Core and Harness. That is the central design bet: one runtime, many products, with the differences expressed as configuration and code in the pack rather than branches inside the engine.

The second layer is the Cache & Reuse Plane, which the README describes as a disposable projection. It can accelerate execution but "can never become authority or replace Event, Artifact, receipt, or checkpoint evidence." Six cache layers are named with different validity boundaries: Serving Cache for exact normalized model responses, Thinking Cache for reasoning nodes and subgraphs, WorkCache for event-derived typed agent work, Tool/Execution Cache for read-only or deterministic results, Memory/Context Cache for search and assembled context, and Prefix/KV Cache for prompt prefixes and backend KV segments. The repository layout matches this: packages/serving-cache, packages/workcache, packages/memory, packages/harness, packages/fsm, packages/kernel and others are built together by the build:packages script. The practical consequence is that a stale cache entry degrades speed, not correctness, because the event log remains the record.

Typed cache trees and semantic trees for agent execution

The cache is not a single key-value store. The README describes a cache tree with a typed root that partitions reusable artifacts, compact parent nodes that route lookups by hash prefix, and full logical keys at the leaves. New leaves are inserted without rebuilding unrelated branches, and stale leaves are invalidated locally. WorkCache extends the same lookup pattern into semantic cache trees, with PlanTree listed as reusing plans. The diagram in docs/readme/cache-tree-management.png shows the artifact-type root, hash-prefix parents and full-key leaves.

The trade-off is explicit in the design: you now have six invalidation policies to reason about. A tool result cached under one capability revision may be wrong after that capability changes, and the README ties Tool/Execution Cache validity to capability revision, policy, external-state evidence, workspace snapshot, idempotency and scope. That is a lot of surface area, and the README does not document a single global switch to turn reuse off. If your team cannot maintain those boundaries, the cache layers will be a source of confusing behavior rather than speed.

Installing Hypha and running the server

Hypha is distributed as 15 packages named @codesoul-co/hypha-* on npm, with v1.0.1 as the current public release. The root package.json is private and defines npm workspaces over packages/* and apps/*, so the repository itself is the build target. Start by installing dependencies at the root.

npm install

The environment file defines the deployment surface. Copy .env.example to .env and fill in what you need; config.yaml holds typed structure and safe local defaults, while .env carries deployment-specific URLs, credentials and local paths.

cp .env.example .env

Two storage backends are configured by default: MongoDB for documents (MONGODB_HOST=localhost, MONGODB_PORT=27017, MONGODB_DATABASE=hypha) and Redis for messaging, cache and stream storage (REDIS_HOST=localhost, REDIS_PORT=6379, REDIS_KEY_PREFIX=hypha:). The server listens on PORT=3000 with HYPHA_API_PREFIX=/api/v1. For development, the dev script builds the packages first and then starts the server through ts-node with dotenv.

npm run dev

For a production-style run, build everything and start the compiled entry point.

npm run build
npm start

The build script compiles the packages, the server and the CLI in sequence. The README points to examples/mcp/ and examples/release-agent/ as example material, and the release notes note that the versioned user guide includes a complete composition example. The repository does not document a single command that scaffolds a new DomainPack, so expect to assemble one from those examples.

Where Hypha is the wrong choice

The harness assumes infrastructure. MongoDB and Redis are both configured in .env.example, and the Memory runtime comment states that native-default uses MongoDB plus Redis, while external profiles use MongoDB for durable mappings and operation evidence and do not require Redis. Either way, MongoDB is in the picture. If you wanted an in-process agent with no database, this is not that.

Second, the DomainPack boundary is a real cost. Declaring tasks, workflows, capabilities, prompts, Memory, policy, evaluation and output contracts is more work than writing a system prompt and a tool list. Teams that change their agent's behavior weekly will feel that friction, because the README describes compilation into the runtime rather than runtime reconfiguration. Third, the README does not document rollback. It documents checkpoints, recovery and replay, but a reader looking for an explicit rollback procedure will not find one in the README. Treat that as a question to answer before you depend on recovery in production.

How Hypha differs from LangGraph and Mastra

LangGraph models an agent as a graph of nodes and edges with a checkpointer for state persistence, and it is the closest comparison for the execution-control layer. The difference is where the product definition lives. In LangGraph, the graph is the program; you write the nodes. In Hypha, the runtime is fixed and the product is declared in a DomainPack that compiles into it, with a separate Cache & Reuse Plane that LangGraph does not describe as a first-class layer. Hypha also names evaluation and output contracts as DomainPack contents, which in LangGraph would typically be external tooling.

Mastra is a TypeScript agent framework with its own workflow and memory primitives and a more integrated developer experience. Hypha's README makes a narrower claim: bounded, event-backed execution with FSM control, policy and approval, checkpoints, recovery, replay and audit. If you want the shortest path from idea to working TypeScript agent, Mastra is likely less ceremony. If you need to argue to an auditor that a specific run can be reconstructed from evidence, Hypha's event-first framing is the more direct fit.

Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-09-04. The most recent release is v1.0.1 from 2026-08-14, with v1.0.0 the same day. Those dates are recent enough that the project is being worked on, but the release history is short: two 1.0.x releases within a few hours of each other, and nothing before that in the release list.

The licence is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. That is a permissive choice, and it means you can ship Hypha inside a closed product. It does not settle questions about the licences of your own dependencies or of any model provider you connect, which are separate matters and not addressed here.

Upgrade cost is where the package layout matters. The root build compiles 15 packages in one command, and the repository ships UPGRADING.md at the top level. That file is the place to look before moving between 1.0.x versions, because the packages are versioned together and a change in the harness or cache layers can affect DomainPack contracts. The CHANGELOG.md at the root is the other file to read first.

Editorial conclusion

Adopt Hypha if you need a governed, replayable runtime under a TypeScript agent product and you are willing to write a DomainPack rather than prompt your way through. Do not adopt it if you want a hosted chat product or a single-file agent loop: the harness, MongoDB and Redis expectations assume a service you operate. Before committing, verify the semantics of checkpoint recovery in the versioned user guide, confirm which cache layers your deployment actually enables, and read UPGRADING.md for the migration path between the 1.0.x packages.

Frequently asked questions

Official sources

1. CodeSoul-co/Hypha on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases