{"id":47029481,"url":"https://github.com/basidiocarp/hyphae","last_synced_at":"2026-06-15T22:00:51.524Z","repository":{"id":343584557,"uuid":"1178167019","full_name":"basidiocarp/hyphae","owner":"basidiocarp","description":"Persistent memory and RAG for AI coding agents. Episodic memories with decay + durable concept graphs. MCP server + CLI. Rust.","archived":false,"fork":false,"pushed_at":"2026-06-05T21:16:48.000Z","size":2280,"stargazers_count":1,"open_issues_count":9,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-05T23:08:00.493Z","etag":null,"topics":["ai-agents","claude-code","developer-tools","llm","mcp","memory","rag","rust"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/basidiocarp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-10T18:55:12.000Z","updated_at":"2026-06-05T21:16:52.000Z","dependencies_parsed_at":"2026-04-17T21:02:19.922Z","dependency_job_id":null,"html_url":"https://github.com/basidiocarp/hyphae","commit_stats":null,"previous_names":["basidiocarp/hyphae"],"tags_count":60,"template":false,"template_full_name":null,"purl":"pkg:github/basidiocarp/hyphae","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basidiocarp%2Fhyphae","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basidiocarp%2Fhyphae/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basidiocarp%2Fhyphae/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basidiocarp%2Fhyphae/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/basidiocarp","download_url":"https://codeload.github.com/basidiocarp/hyphae/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basidiocarp%2Fhyphae/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34381762,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude-code","developer-tools","llm","mcp","memory","rag","rust"],"created_at":"2026-03-11T23:39:47.820Z","updated_at":"2026-06-15T22:00:51.518Z","avatar_url":"https://github.com/basidiocarp.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hyphae\n\nPersistent memory for AI coding agents. Single binary, zero runtime\ndependencies, MCP-native, and designed to keep useful context alive after the\nwindow compacts.\n\nNamed after fungal hyphae, the branching filaments that connect and distribute\nnutrients through the organism.\n\nPart of the [Basidiocarp ecosystem](https://github.com/basidiocarp).\n\n---\n\n## The Problem\n\nAI agents forget everything between sessions. Architecture decisions, resolved\nbugs, project conventions, and prior corrections vanish when the transcript\ncompacts or the session ends.\n\n## The Solution\n\nHyphae gives agents two memory models that do different jobs. Memories handle\nthe day-to-day flow of decisions, errors, and notes with decay; memoirs keep\nthe durable concept graph that should not disappear. On top of that, Hyphae\nadds hybrid retrieval, document indexing, and session tracking.\n\n---\n\n## The Ecosystem\n\n| Tool | Purpose |\n|------|---------|\n| **[hyphae](https://github.com/basidiocarp/hyphae)** | Persistent agent memory |\n| **[canopy](https://github.com/basidiocarp/canopy)** | Multi-agent coordination runtime |\n| **[cap](https://github.com/basidiocarp/cap)** | Web dashboard for the ecosystem |\n| **[cortina](https://github.com/basidiocarp/cortina)** | Lifecycle signal capture and session attribution |\n| **[lamella](https://github.com/basidiocarp/lamella)** | Skills, hooks, and plugins for coding agents |\n| **[mycelium](https://github.com/basidiocarp/mycelium)** | Token-optimized command output |\n| **[rhizome](https://github.com/basidiocarp/rhizome)** | Code intelligence via tree-sitter and LSP |\n| **[spore](https://github.com/basidiocarp/spore)** | Shared transport and editor primitives |\n| **[stipe](https://github.com/basidiocarp/stipe)** | Ecosystem installer and manager |\n| **[volva](https://github.com/basidiocarp/volva)** | Execution-host runtime layer |\n\n\u003e **Boundary:** `hyphae` owns memory, retrieval, and session records. It does\n\u003e not own shell filtering, code intelligence, hook capture, UI, or installation.\n\u003e `hyphae-core` stays domain-only: types, traits, and embedder abstractions,\n\u003e with transport, operator, and persistence concerns living in sibling crates.\n\n---\n\n## Quick Start\n\n```bash\n# Quick install: smaller binary without local embeddings\ncurl -fsSL https://raw.githubusercontent.com/basidiocarp/hyphae/main/install.sh | sh\n\n# Quick install: prebuilt binary with embeddings enabled\ncurl -fsSL https://raw.githubusercontent.com/basidiocarp/hyphae/main/install.sh | sh -s -- --embeddings\n\n# Recommended: full ecosystem setup\nstipe init\n\n# Alternative: hyphae-only setup\nhyphae init\n```\n\n```bash\n# Build from source\ncargo install --path crates/hyphae-cli\n\n# Smaller build without embeddings\ncargo build --release --no-default-features\n\n# Full build with embeddings\ncargo build --release\n```\n\nPrebuilt release archives now ship both variants:\n- `hyphae-\u003ctarget\u003e.tar.gz` or `.zip`: slim build without local embeddings\n- `hyphae-\u003ctarget\u003e-embeddings.tar.gz` or `.zip`: default build with embeddings\n\n---\n\n## How It Works\n\n```text\nAgent                   Hyphae                         Stored state\n─────                   ──────                         ────────────\nstore memory      ─►    episodic memory         ─►    decaying memories\nstore concept     ─►    memoir graph            ─►    permanent concepts\nquery context     ─►    hybrid retrieval        ─►    ranked recall\nend session       ─►    session lifecycle       ─►    outcomes and lessons\n```\n\n1. Store episodic memories: capture decisions, errors, preferences, and session notes with importance-aware decay.\n2. Build memoirs: link durable concepts into permanent knowledge graphs.\n3. Index documents: chunk files, embed them, and store them for hybrid RAG retrieval.\n4. Track sessions: record task context, outcomes, files changed, and feedback signals.\n5. Recall useful context: blend BM25 and vector search into ranked results for agents and UIs.\n\n---\n\n## Memory Models\n\n| Model | Behavior | Best for |\n|-------|----------|----------|\n| Memories | Decay-based episodic storage | Decisions, errors, preferences, work notes |\n| Memoirs | Permanent semantic graph | Concepts, relationships, architecture, domain knowledge |\n\n## Hybrid Search Stack\n\n| Layer | Technology | Purpose |\n|-------|------------|---------|\n| Storage | SQLite | Memories, memoirs, embeddings, session state |\n| Full-text | FTS5 | Keyword recall with BM25 scoring |\n| Vector | sqlite-vec | Semantic recall over embeddings |\n| Blend | 30% FTS plus 70% vector | Keyword precision plus semantic similarity |\n\n---\n\n## What Hyphae Owns\n\n- Episodic memory storage and decay\n- Permanent knowledge memoirs\n- Hybrid document and memory retrieval\n- Session lifecycle records and outcome signals\n- Training-data export and lesson extraction\n\n## What Hyphae Does Not Own\n\n- Shell output filtering: handled by `mycelium`\n- Code intelligence and symbol graphs: handled by `rhizome`\n- Hook capture and session intake: handled by `cortina`\n- UI and operator dashboards: handled by `cap`\n\n---\n\n## Key Features\n\n- Dual memory model: combines decay-based episodic memory with permanent semantic memoirs.\n- RAG pipeline: ingests files, chunks them, embeds them, and serves them back through hybrid search.\n- Structured sessions: records session start, end, context, and feedback signals.\n- Lesson extraction: mines corrections and resolutions into reusable patterns.\n- Local-first storage: runs from a single SQLite database with no cloud dependency.\n\n---\n\n## Architecture\n\n```text\nhyphae (single binary)\n├── hyphae-core    domain types, traits, embedder logic only\n├── hyphae-ingest  file readers and chunking\n├── hyphae-store   SQLite, FTS5, sqlite-vec\n├── hyphae-mcp     MCP server and tool handlers\n└── hyphae-cli     CLI commands and operator surfaces\n```\n\nVersioned payloads stay explicit at the boundary. MCP tools that cross repo or\nhost boundaries use schema/version fields instead of ad hoc shapes, and shared\ncontract updates should land with their schema or fixture changes.\n\n```bash\nhyphae session start --project demo --task \"refactor auth flow\"\nhyphae session end --id \u003csession_id\u003e --summary \"completed refactor\"\nhyphae feedback signal --session-id \u003csession_id\u003e --type correction --value -1\nhyphae session context --project demo\nhyphae bench-retrieval          # Benchmark retrieval quality using fixture-driven tests\n```\n\n---\n\n## Performance\n\n| Operation | Latency |\n|-----------|---------|\n| Store | 34 us |\n| FTS search | 47 us |\n| Hybrid search | 951 us |\n| Batch decay (1000) | 5.8 ms |\n\n## Logging\n\nHyphae reads `HYPHAE_LOG` first, then falls back to `RUST_LOG`. If neither is\nset, it defaults to `warn`.\n\n```bash\nHYPHAE_LOG=debug hyphae doctor\nHYPHAE_LOG=debug hyphae serve\n```\n\n`hyphae serve` keeps stdout reserved for newline-delimited MCP JSON-RPC\nresponses. Logs go to stderr so they do not corrupt the MCP transport.\n\n---\n\n## Documentation\n\n- [docs/README.md](docs/README.md): docs index and reading order\n- [docs/guide.md](docs/guide.md): quickstart, concepts, and configuration\n- [docs/features.md](docs/features.md): feature overview and behavior\n- [docs/cli-reference.md](docs/cli-reference.md): CLI commands and examples\n- [docs/mcp-tools.md](docs/mcp-tools.md): MCP tool reference\n- [docs/architecture.md](docs/architecture.md): internals, schema, and search pipeline\n- [docs/setup-by-tool.md](docs/setup-by-tool.md): per-editor setup instructions\n- [docs/troubleshooting.md](docs/troubleshooting.md): common issues and fixes\n- [docs/feedback-loop-design.md](docs/feedback-loop-design.md): closed-loop learning design notes\n- [docs/training-data.md](docs/training-data.md): export formats and training data guidance\n\n## Supply Chain\n\nEmbedding support pulls an ML dependency chain. The table below documents what\neach component does and when its artifacts arrive.\n\n| Component | Version | What it does | When artifacts are fetched |\n|-----------|---------|--------------|---------------------------|\n| `fastembed` | 4.x | Runs embedding models locally | Build time |\n| `ort` | 2.0.0-rc.9 | Rust bindings for ONNX Runtime | Build time |\n| `ort-sys` | 2.0.0-rc.9 | Native FFI layer for ORT | Build time |\n| ORT binary | matches ort-sys | Prebuilt ONNX Runtime native library | Build time (via `ort-download-binaries` feature) |\n| Embedding model | all-MiniLM-L6-v2 | Sentence embedding weights | First use (downloaded from Hugging Face) |\n\nThe `ort-download-binaries` feature (enabled in `[workspace.dependencies]`) causes\n`ort-sys` to download a prebuilt ORT native library from the `ort` GitHub releases\npage during the Rust build. The embedding model weights are downloaded from Hugging\nFace on first use by `fastembed`.\n\n**To disable all binary downloads**, build without default features:\n\n```bash\ncargo build --release --no-default-features\n```\n\nThis produces a slim binary that uses FTS5 search only; no native library or model\nweights are downloaded. Hybrid vector search is unavailable in this mode.\n\n**Pinning**: the `Cargo.lock` fixes all crate versions including `ort-sys`. The ORT\nnative binary version is determined by `ort-sys`; update `ort-sys` deliberately and\nverify the new binary hash in the published `ort-sys` source before accepting the\nupgrade.\n\n---\n\n## Development\n\n```bash\ncargo build --release\ncargo nextest run\ncargo test\ncargo clippy\ncargo fmt\n```\n\n- Prefer `cargo nextest run` for the normal test loop.\n- The workspace `profile.dev` is tuned for faster iteration with line-tables-only\n  debug info.\n- If you add `criterion` here, start with the retrieval hot paths in\n  `hyphae-store` rather than broad repo-wide benches.\n- Use whole-command timing for end-to-end investigation, for example\n  `time cargo run -p hyphae-cli -- doctor`.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasidiocarp%2Fhyphae","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbasidiocarp%2Fhyphae","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasidiocarp%2Fhyphae/lists"}