Hypha
Hypha is an open-source TypeScript framework for building governed, durable, and reusable domain agents. It combines an Agent Core for reasoning and planning with a Production Harness for event-driven execution, policy, recovery, and audit. It is for developers creating production-grade agent products that require control, reliability, and reuse.
✨ Key features
- Agent Core with ReAct, planning, tool selection, and memory access.
- Production Harness with FSM control, policy, approvals, and checkpoints.
- DomainPack declares tasks, workflows, capabilities, and policies.
- Cache & Reuse Plane with typed semantic cache trees.
- Event-sourced execution with replay, audit, and recovery.
- Adapters for memory, tools, MCP, and execution environments.
🎯 Use cases
- Build coding, finance, legal, or research agents with shared runtime.
- Implement governed agent workflows requiring human approval and audit.
- Reuse validated reasoning and tool results across agent runs.
- Deploy durable agents with recovery and replay capabilities.
📦 Installation
🧰 Requirements: Node.js 22 or newer, npm, MongoDB and Redis for the bundled API server, and at least one configured model provider or local model endpoint.
git clone https://github.com/CodeSoul-co/Hypha.git
cd Hypha
npm ci
cp .env.example .env
For a disposable local MongoDB and Redis environment, you may use containers:
docker run -d --name hypha-mongodb -p 27017:27017 mongo:8
docker run -d --name hypha-redis -p 6379:6379 redis:7-alpine
You can instead set MONGODB_URI and REDIS_URL to self-hosted or managed services.
🚀 Usage
# Configure .env with identity and model provider
HYPHA_OWNER_EMAIL=owner@example.com
HYPHA_OWNER_PASSWORD=replace-with-a-private-password
JWT_SECRET=replace-with-at-least-32-random-characters
HYPHA_LLM_DEFAULT_PROVIDER=openai
HYPHA_LLM_DEFAULT_MODEL=gpt-4o-mini
OPENAI_API_KEY=your-provider-key
Then run the API server or CLI (example not fully provided in README).
❓ FAQ
What is the relationship between Agent Core and Production Harness?
Agent Core handles reasoning, planning, and tool selection, while Production Harness turns those decisions into bounded, event-backed execution with FSM control, policy, and recovery.
How does caching work in Hypha?
Hypha has multiple cache layers (Serving, Thinking, WorkCache, Tool, Memory, Prefix) that reuse validated work but never become authority; cache hits cannot authorize side effects or replace Event and Artifact evidence.
What are DomainPacks?
DomainPacks declare product-specific tasks, workflows, capabilities, prompts, memory, policy, and output contracts, which are compiled into the shared Core and Harness.
What are the system requirements?
Node.js 22 or newer, npm, MongoDB and Redis for the bundled API server, and at least one configured model provider or local model endpoint.
📊 Repository
🤖 Overview, features, install steps and FAQ were generated from the project's README on Sep 4, 2026. Always check the original source before running commands.