Data that can prove itself.

Hyphae is a local-first data engine written in Rust. One process owns one data directory and exposes relational SQL, native structures, lexical search, and vector search over a shared transaction, WAL, MVCC, recovery, and proof substrate. The engine runs offline and does not embed PostgreSQL, Valkey, OpenSearch, a cloud service, an embedding provider, or an LLM.

Development line: Hyphae Native is the active architecture on dev. G0 through G6 are closed for their versioned, bounded profiles; G7 and G8 remain open. The native gate status is the current status authority; temporary workflow artifacts alone do not close a gate.

Published stable release: v0.2.1 is still the version available from crates.io and GitHub Releases. It is the compatibility baseline, not a description of the current dev architecture. Its publication receipt remains available at docs/release/receipts/0.2.1.md.

The target release for the native line is 1.0.0. The remaining G7 performance and G8 release gates must close before main receives the native line and replaces 0.2.1.

What Hyphae does

• Executes bounded SQL DDL, DML, prepared queries, secondary-index reads, and transactions over a Hyphae-owned relational engine.
• Provides native strings, counters, hashes, lists, sets, sorted sets, streams, TTL, scans, algebra, and atomic structure batches.
• Owns lexical, exact-vector, incremental ANN, filtered, faceted, metric, and same-snapshot hybrid search without an external search engine.
• Commits SQL, structure, and search mutations under one catalog, WAL, MVCC root set, commit sequence, scheduler, and stable object-ID namespace.
• Exposes one embedded Rust facade, local UDS/named-pipe protocol, CLI, optional loopback HTTP /v2, and typed Python and TypeScript SDKs.
• Creates Native checkpoints, proofs, witnesses, backups, restores, vacuum generations, and complete doctor reports with bounded failure behavior.
• Imports format-2 state offline into a separate pending Native directory, verifies equivalence, and requires explicit promotion.

See the Native capability matrix, including surface differences, boundaries, and deliberate non-capabilities. The published 0.2.1 matrix remains separate.

Install

Install the latest published compatibility binary:

cargo install hyphae-cli --version 0.2.1 --locked
hyphae version --json

Embed the latest published engine with an exact product-version requirement:

cargo add hyphae-engine@=0.2.1

Native archives, checksums, SBOMs, provenance, signatures, and attestations for 0.2.1 are attached to its GitHub release.

Published 0.2.1 compatibility flow

cargo build --release --locked -p hyphae-cli
export HYPHAE_DATA_DIR="$PWD/hyphae-data"

./target/release/hyphae version --json
./target/release/hyphae put \
  --key alpha --json '{"group":"x","score":10}'
./target/release/hyphae query \
  --field group --equals '"x"' --sort score \
  --proof-out result.hyproof
./target/release/hyphae backup --out ./hyphae-backup
./target/release/hyphae backup-verify --backup ./hyphae-backup
./target/release/hyphae doctor

These commands describe the published format-2 compatibility release, not the Native dev command surface. The query response names the snapshot and anchor needed by hyphae verify. The quickstart covers Windows syntax, compaction, restore, offline proof verification, the optional server, and clients.

Architecture

application
  ├─ embedded Rust facade ────────────────────────────────┐
  ├─ local CLI                                            │
  ├─ UDS / named-pipe clients (Rust / Python / TypeScript)│
  └─ optional loopback HTTP /v2 ──────────────────────────┤
                                                          ▼
                     Native product and transaction authority
                         │              │              │
                        SQL         structures       search
                         └──────────────┬──────────────┘
                                        ▼
                      catalog / WAL / MVCC / pages / blobs
                              checkpoints / backup / proofs

One operating-system lock gives one product instance exclusive ownership of a Native data directory. See the Native architecture and versioned Native specifications.

Public surfaces

Surface	Purpose
hyphae binary	Native local operations, administration, migration, server, and verifier
hyphae-native-product	Curated embedded Native product facade
Native local protocol	Primary UDS/named-pipe multi-client transport
HTTP /v2	Optional loopback-first Native edge
@celiums/hyphae	TypeScript Native local-protocol and HTTP client
hyphae-sdk	Python Native local-protocol and HTTP client
/v1 compatibility	Separately retained published format-2 HTTP product

OpenAPI 3.1 and JSON Schema 2020-12 under contracts/ are the canonical wire contracts. Native uses hyphae-v2.yaml and native-v2.schema.json; the published format-2 product retains hyphae-v1.yaml.

Rust crates

The Native line is organized around hyphae-native-product (embedded facade), hyphae-native-runtime (SQL, structures, search, transactions, and scheduling), hyphae-native-protocol/hyphae-native-daemon (local transport), and the owned hyphae-native-{types,catalog,pages,blobs,wal,mvcc,btree,records,manifest,ann} storage and execution primitives. hyphae-cli builds the single product binary.

The following crates are the published format-2 compatibility libraries at 0.2.1; their crates.io pages do not describe the unpublished Native facade:

Crate	Purpose	Documentation
hyphae-engine	Recommended embeddable facade	docs.rs
hyphae-storage	Durable log, recovery, snapshots, and backups	docs.rs
hyphae-query	Deterministic structured query	docs.rs
hyphae-retrieval	Deterministic exact, lexical, and hybrid retrieval	docs.rs
hyphae-contracts	Versioned /v1 models and embedded schemas	docs.rs
hyphae-client	Bounded async Rust HTTP client	docs.rs
hyphae-server	Loopback-first /v1 server	docs.rs
hyphae-core	Product and compatibility constants	docs.rs
hyphae-cli	Single hyphae binary, verifier, and MCP adapter	docs.rs
hyphae-pliegors	Optional PliegoRS public-contract adapter	docs.rs

Documentation

Start at the documentation index. Key guides:

• Native capabilities and limits
• Native development quickstart
• Published 0.2.1 compatibility guide
• CLI reference
• Configuration
• Native product contract
• Native HTTP API v2
• Native local protocol
• Operations and troubleshooting
• Security model
• Native local ecosystem target
• Microsecond-first target
• Release verification
• 0.2.1 publication receipt
• crates.io release procedure

Product boundary

Hyphae Native is a local, single-node data ecosystem with Hyphae-owned SQL, structures, lexical search, and ANN under one durable authority. G0 through G6 are closed for their bounded contracts; G7 and G8 still prevent a 1.0.0 release claim.

Hyphae is not Mycelium, Hyphae Network, Celiums Network, an AI cognition runtime, a hosted SaaS, or a framework-specific data layer. The published 0.2.1 release does not include the native SQL/structures/search architecture now present on dev. Replication, clustering, built-in TLS, at-rest encryption, multitenancy, billing, a control plane, an embedding model, and an LLM are also outside Native 1.0.

Hosted, distributed, and model-driven programs remain later phases. Applications still own process supervision, remote TLS termination, filesystem permissions, backup media policy, and optional embedding providers. Semantic providers can supply vectors to the Rust APIs but never become a core dependency or source of authority.

Repository map

• crates/: Native product/runtime/storage/protocol crates, retained format-2 libraries, public contracts, clients, servers, and the single CLI.
• contracts/: canonical OpenAPI and JSON Schemas.
• sdks/: TypeScript and Python clients/models.
• mcp/: MCP adapter guide; implementation is in the single binary.
• integrations/: optional PliegoRS, Astro, Next, and Vite adapters.
• examples/: maintained embedded, HTTP, and MCP examples.
• docs/: product, architecture, operations, security, normative formats, ADRs, and release gates.
• packaging/: deterministic multiplatform archives and release verification.
• compatibility/: immutable historical on-disk fixtures.

Development

The repository pins its toolchain and enforces format, Clippy, tests, rustdoc, contracts, documentation, dependency policy, secret scanning, cross-platform packages, fuzzing, and recovery stress.

cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
cargo test --workspace --all-features --locked
cargo doc --workspace --all-features --no-deps --locked
python tools/check_documentation.py --binary target/debug/hyphae

See CONTRIBUTING.md and the development guide.

Historical source

Historical repositories are frozen inputs, not this repository's history. No historical source may enter this tree without an audited entry in the porting ledger. Hyphae Network is not modified by this project.

License

Apache License 2.0. See LICENSE, NOTICE, and THIRD_PARTY_NOTICES.md. The Hyphae name and visual identity are covered separately by TRADEMARKS.md.