convez.ai
MCP Server
basidiocarp

hyphae

basidiocarp/hyphae

Ver no GitHub
InicialPluginScore · de 0 a 100

Persistent memory and RAG for AI coding agents. Episodic memories with decay + durable concept graphs. MCP server + CLI. Rust.

Instalação

$npx convez-ai basidiocarp/hyphae

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
50%
Último commit
há 4 meses
Versão
v0.19.0
Issues abertas
10
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

Hyphae

Persistent memory for AI coding agents. Single binary, zero runtime dependencies, MCP-native, and designed to keep useful context alive after the window compacts.

Named after fungal hyphae, the branching filaments that connect and distribute nutrients through the organism.

Part of the Basidiocarp ecosystem.


The Problem

AI agents forget everything between sessions. Architecture decisions, resolved bugs, project conventions, and prior corrections vanish when the transcript compacts or the session ends.

The Solution

Hyphae gives agents two memory models that do different jobs. Memories handle the day-to-day flow of decisions, errors, and notes with decay; memoirs keep the durable concept graph that should not disappear. On top of that, Hyphae adds hybrid retrieval, document indexing, and session tracking.


The Ecosystem

ToolPurpose
hyphaePersistent agent memory
canopyMulti-agent coordination runtime
capWeb dashboard for the ecosystem
cortinaLifecycle signal capture and session attribution
lamellaSkills, hooks, and plugins for coding agents
myceliumToken-optimized command output
rhizomeCode intelligence via tree-sitter and LSP
sporeShared transport and editor primitives
stipeEcosystem installer and manager
volvaExecution-host runtime layer

Boundary: hyphae owns memory, retrieval, and session records. It does not own shell filtering, code intelligence, hook capture, UI, or installation. hyphae-core stays domain-only: types, traits, and embedder abstractions, with transport, operator, and persistence concerns living in sibling crates.


Quick Start

# Quick install: smaller binary without local embeddings
curl -fsSL https://raw.githubusercontent.com/basidiocarp/hyphae/main/install.sh | sh

# Quick install: prebuilt binary with embeddings enabled
curl -fsSL https://raw.githubusercontent.com/basidiocarp/hyphae/main/install.sh | sh -s -- --embeddings

# Recommended: full ecosystem setup
stipe init

# Alternative: hyphae-only setup
hyphae init
# Build from source
cargo install --path crates/hyphae-cli

# Smaller build without embeddings
cargo build --release --no-default-features

# Full build with embeddings
cargo build --release

Prebuilt release archives now ship both variants:

  • hyphae-<target>.tar.gz or .zip: slim build without local embeddings
  • hyphae-<target>-embeddings.tar.gz or .zip: default build with embeddings

How It Works

Agent                   Hyphae                         Stored state
─────                   ──────                         ────────────
store memory      ─►    episodic memory         ─►    decaying memories
store concept     ─►    memoir graph            ─►    permanent concepts
query context     ─►    hybrid retrieval        ─►    ranked recall
end session       ─►    session lifecycle       ─►    outcomes and lessons
  1. Store episodic memories: capture decisions, errors, preferences, and session notes with importance-aware decay.
  2. Build memoirs: link durable concepts into permanent knowledge graphs.
  3. Index documents: chunk files, embed them, and store them for hybrid RAG retrieval.
  4. Track sessions: record task context, outcomes, files changed, and feedback signals.
  5. Recall useful context: blend BM25 and vector search into ranked results for agents and UIs.

Memory Models

ModelBehaviorBest for
MemoriesDecay-based episodic storageDecisions, errors, preferences, work notes
MemoirsPermanent semantic graphConcepts, relationships, architecture, domain knowledge

Hybrid Search Stack

LayerTechnologyPurpose
StorageSQLiteMemories, memoirs, embeddings, session state
Full-textFTS5Keyword recall with BM25 scoring
Vectorsqlite-vecSemantic recall over embeddings
Blend30% FTS plus 70% vectorKeyword precision plus semantic similarity

What Hyphae Owns

  • Episodic memory storage and decay
  • Permanent knowledge memoirs
  • Hybrid document and memory retrieval
  • Session lifecycle records and outcome signals
  • Training-data export and lesson extraction

What Hyphae Does Not Own

  • Shell output filtering: handled by mycelium
  • Code intelligence and symbol graphs: handled by rhizome
  • Hook capture and session intake: handled by cortina
  • UI and operator dashboards: handled by cap

Key Features

  • Dual memory model: combines decay-based episodic memory with permanent semantic memoirs.
  • RAG pipeline: ingests files, chunks them, embeds them, and serves them back through hybrid search.
  • Structured sessions: records session start, end, context, and feedback signals.
  • Lesson extraction: mines corrections and resolutions into reusable patterns.
  • Local-first storage: runs from a single SQLite database with no cloud dependency.

Architecture

hyphae (single binary)
├── hyphae-core    domain types, traits, embedder logic only
├── hyphae-ingest  file readers and chunking
├── hyphae-store   SQLite, FTS5, sqlite-vec
├── hyphae-mcp     MCP server and tool handlers
└── hyphae-cli     CLI commands and operator surfaces

Versioned payloads stay explicit at the boundary. MCP tools that cross repo or host boundaries use schema/version fields instead of ad hoc shapes, and shared contract updates should land with their schema or fixture changes.

hyphae session start --project demo --task "refactor auth flow"
hyphae session end --id <session_id> --summary "completed refactor"
hyphae feedback signal --session-id <session_id> --type correction --value -1
hyphae session context --project demo
hyphae bench-retrieval          # Benchmark retrieval quality using fixture-driven tests

Performance

OperationLatency
Store34 us
FTS search47 us
Hybrid search951 us
Batch decay (1000)5.8 ms

Logging

Hyphae reads HYPHAE_LOG first, then falls back to RUST_LOG. If neither is set, it defaults to warn.

HYPHAE_LOG=debug hyphae doctor
HYPHAE_LOG=debug hyphae serve

hyphae serve keeps stdout reserved for newline-delimited MCP JSON-RPC responses. Logs go to stderr so they do not corrupt the MCP transport.


Documentation

Supply Chain

Embedding support pulls an ML dependency chain. The table below documents what each component does and when its artifacts arrive.

ComponentVersionWhat it doesWhen artifacts are fetched
fastembed4.xRuns embedding models locallyBuild time
ort2.0.0-rc.9Rust bindings for ONNX RuntimeBuild time
ort-sys2.0.0-rc.9Native FFI layer for ORTBuild time
ORT binarymatches ort-sysPrebuilt ONNX Runtime native libraryBuild time (via ort-download-binaries feature)
Embedding modelall-MiniLM-L6-v2Sentence embedding weightsFirst use (downloaded from Hugging Face)

The ort-download-binaries feature (enabled in [workspace.dependencies]) causes ort-sys to download a prebuilt ORT native library from the ort GitHub releases page during the Rust build. The embedding model weights are downloaded from Hugging Face on first use by fastembed.

To disable all binary downloads, build without default features:

cargo build --release --no-default-features

This produces a slim binary that uses FTS5 search only; no native library or model weights are downloaded. Hybrid vector search is unavailable in this mode.

Pinning: the Cargo.lock fixes all crate versions including ort-sys. The ORT native binary version is determined by ort-sys; update ort-sys deliberately and verify the new binary hash in the published ort-sys source before accepting the upgrade.


Development

cargo build --release
cargo nextest run
cargo test
cargo clippy
cargo fmt
  • Prefer cargo nextest run for the normal test loop.
  • The workspace profile.dev is tuned for faster iteration with line-tables-only debug info.
  • If you add criterion here, start with the retrieval hot paths in hyphae-store rather than broad repo-wide benches.
  • Use whole-command timing for end-to-end investigation, for example time cargo run -p hyphae-cli -- doctor.

License

MIT

Ver o original no GitHub

Bom para

Relacionados