# HyphaeDB

## Docs

- [Introduction](https://docs.hyphaedb.com/introduction.md): HyphaeDB is agent-native memory infrastructure: a database where stored knowledge propagates to the agents that need it instead of waiting to be queried.
- [Quickstart](https://docs.hyphaedb.com/quickstart.md): Bring up HyphaeDB with Docker Compose, create your first credential as you boot, then store and recall your first memory.
- [Propagation in five minutes](https://docs.hyphaedb.com/propagation-quickstart.md): Watch a memory travel from one agent to another with no query in between — the store-don't-broadcast thesis, running end to end between two agents.
- [Gossip propagation](https://docs.hyphaedb.com/concepts/gossip-propagation.md): How a stored memory diff flows through the mesh to the agents that need it, instead of waiting to be queried.
- [The energy model](https://docs.hyphaedb.com/concepts/energy-model.md): The propagation budget — how far a memory diff can travel, and why high-value knowledge travels farther than routine work.
- [The HNSW mesh](https://docs.hyphaedb.com/concepts/hnsw-mesh.md): The hierarchical graph that is both HyphaeDB's vector index for recall and the topology that gossip walks.
- [Positioning and beacons](https://docs.hyphaedb.com/concepts/positioning-and-beacons.md): How agents take up a position in the mesh that drifts with their work, and how beacons let you plant a listening post at a topic and receive it from anywhere.
- [Layer promotion](https://docs.hyphaedb.com/concepts/layer-promotion.md): How knowledge earns its way up the mesh hierarchy as it proves useful — and how contradictions push it back down.
- [Contradiction detection](https://docs.hyphaedb.com/concepts/contradiction-detection.md): How HyphaeDB decides two memories genuinely disagree — geometry proposes, an explicit classifier disposes — and how a confirmed contradiction gates promotion, decays trust, and propagates.
- [Trust and provenance](https://docs.hyphaedb.com/concepts/trust-and-provenance.md): The adversarial-resilience layer — authenticated provenance, per-agent trust, and why one cannot substitute for the other.
- [Run with Docker Compose](https://docs.hyphaedb.com/operations/docker-compose.md): Stand up a local HyphaeDB mesh — hyphae-server, PostgreSQL with pgvector, and an optional embedding sidecar — with a single compose file.
- [Configuration](https://docs.hyphaedb.com/operations/configuration.md): Configure HyphaeDB through environment variables and a config file, and understand which settings are fixed for the process lifetime versus reloadable at runtime.
- [Deployment](https://docs.hyphaedb.com/operations/deployment.md): Deploy HyphaeDB as a single-container service with an external PostgreSQL — run modes, persistent volumes, Kubernetes probes, and the production posture.
- [Deployment and operations](https://docs.hyphaedb.com/operations/deployment-operations.md): How a hyphae-server process is packaged, sized, started, drained, and operated — the single-container topology, resource model, graceful shutdown, and config reload stance.
- [Durability and disaster recovery](https://docs.hyphaedb.com/operations/durability-and-dr.md): How HyphaeDB backs up each tier, snapshots the in-memory mesh, and rehydrates within a bounded budget — keeping PostgreSQL as the single source of truth.
- [High availability](https://docs.hyphaedb.com/operations/high-availability.md): How HyphaeDB survives process and host failure — active-passive, single-writer, fenced failover with a Postgres-backed lease and bounded RPO and RTO.
- [Authorization](https://docs.hyphaedb.com/operations/authorization.md): How callers authenticate — a data-plane API key or a console OIDC session — and how HyphaeDB enforces RBAC inside storage query scoping, so out-of-scope data is unreachable rather than filtered after the fact.
- [Audit log & security events](https://docs.hyphaedb.com/operations/audit-log.md): HyphaeDB's tamper-evident, hash-chained audit log — what it records, the action taxonomy, the synchronous fail-closed contract, and the one bounded metric it contributes.
- [Admin control plane](https://docs.hyphaedb.com/operations/admin-control-plane.md): The operator surface over /admin/api — the OIDC-authenticated control plane for identity lifecycle and data lifecycle, distinct from the /v1 data plane, and the "Mycelium" web console that drives it.
- [Data lifecycle](https://docs.hyphaedb.com/operations/data-lifecycle.md): How HyphaeDB bounds unbounded growth and makes deletion complete — retention GC, in-memory eviction, propagating tombstones, compliant erasure, and re-embed migration.
- [Observability & metrics](https://docs.hyphaedb.com/operations/observability.md): How to scrape HyphaeDB's metrics, the LIVE-vs-RESERVED naming contract enforced in CI, the bounded-label cardinality discipline, and a catalog of the hyphae.* metrics by subsystem.
- [Topology Observatory](https://docs.hyphaedb.com/operations/topology-observatory.md): Watch memories propagate across the mesh in real time — a tenant-scoped, read-only operator stream of every hop a MemoryDiff takes, with a bounded scrub-back window and a live tail.
- [API versioning](https://docs.hyphaedb.com/operations/api-versioning.md): How HyphaeDB versions its wire contract — semantic versioning split on the proto package boundary, bidirectional compatibility, capability negotiation, and deprecation signaling.
- [Extending HyphaeDB](https://docs.hyphaedb.com/extending.md): How HyphaeDB is extended today — a set of trait seams, each with a concrete implementation chosen at startup, so you can swap the embedder, storage, auth, secrets, rate limiter, and more without forking the core.
- [Recipes](https://docs.hyphaedb.com/recipes/overview.md): Short, goal-first guides for common HyphaeDB tasks — each one a concrete objective, the steps to reach it, and where to go deeper.
- [Recipe: connect HyphaeDB to Claude Code](https://docs.hyphaedb.com/recipes/mcp-claude-code.md): Wire HyphaeDB in as an MCP server so Claude Code (or any MCP host) can store and recall memory as tool calls.
- [Recipe: route knowledge with beacons](https://docs.hyphaedb.com/recipes/route-with-beacons.md): Give an agent a standing interest so relevant memories gossip to it, even ones stored long after the agent went quiet.
- [Recipe: tune how far a memory travels](https://docs.hyphaedb.com/recipes/tune-propagation-distance.md): Use salience and cell type to control a memory's propagation reach — from a local note to a decision that reaches the whole mesh.
- [Recipe: watch a memory propagate](https://docs.hyphaedb.com/recipes/watch-propagation.md): Stream propagation hop-by-hop from the Topology Observatory, or pull a snapshot of the recent window, to see exactly where a memory went and why it stopped.
- [Recipe: erase data with a certificate](https://docs.hyphaedb.com/recipes/erase-with-certificate.md): Run a compliant, audited bulk erasure by scope and keep the erasure certificate as a non-repudiable receipt.
- [Python SDK](https://docs.hyphaedb.com/sdks/python.md): Async gRPC client for HyphaeDB — connect, store and recall memory, and consume the live gossip inbox from Python.
- [TypeScript SDK](https://docs.hyphaedb.com/sdks/typescript.md): Async gRPC client for HyphaeDB — connect, store and recall memory, and consume the live gossip inbox from Node.js.
- [Go SDK](https://docs.hyphaedb.com/sdks/go.md): The Go SDK is planned. Until it ships, use the HyphaeDB gRPC service directly from Go with a generated client.
- [Rust SDK](https://docs.hyphaedb.com/sdks/rust.md): Async gRPC client for HyphaeDB — connect, store and recall memory, and consume the live gossip inbox from Rust.
- [API reference overview](https://docs.hyphaedb.com/api-reference/overview.md): The HyphaeDB REST API — the HTTP fallback surface, its authentication, error envelope, and conventions. Endpoint pages in this section are generated from OpenAPI.
- [Store a knowledge cell](https://docs.hyphaedb.com/api-reference/memory/store-a-knowledge-cell.md): Store a single cell of knowledge and return its node id. Validation, quota, and authorization run inside the facade. `source_agent` and `tenant_id` are stamped from the authenticated principal and cannot be set by the client.
- [Recall similar cells (layer L0)](https://docs.hyphaedb.com/api-reference/memory/recall-similar-cells-layer-l0.md): Layer-L0 similarity recall. Returns a JSON array of fully hydrated knowledge nodes in rank order (nearest-first). No score is on the wire — the array order conveys the rank.
- [Query cells against an explicit layer](https://docs.hyphaedb.com/api-reference/memory/query-cells-against-an-explicit-layer.md): Like recall, but against an explicit semantic layer (L0/L1/L2). Returns a JSON array of fully hydrated knowledge nodes in rank order.
- [Drain the caller's inbox (unary work-cycle pull)](https://docs.hyphaedb.com/api-reference/inbox/drain-the-callers-inbox-unary-work-cycle-pull.md): Drain the calling agent's own inbox without holding a stream open — the work-cycle pull for a non-resident agent (serverless, cron, orchestrated node).
- [Open a session](https://docs.hyphaedb.com/api-reference/sessions/open-a-session.md): Open a working session in the given project and return its session id.
- [Close a session](https://docs.hyphaedb.com/api-reference/sessions/close-a-session.md): Close the session identified by the path id.
- [List this caller's beacons](https://docs.hyphaedb.com/api-reference/beacons/list-this-callers-beacons.md): List the node ids of the beacons placed by the authenticated caller.
- [Place an interest beacon](https://docs.hyphaedb.com/api-reference/beacons/place-an-interest-beacon.md): Place a standing interest beacon, returning the node id of the beacon node.
- [List scenes in scope](https://docs.hyphaedb.com/api-reference/scenes/list-scenes-in-scope.md): List the scenes in the caller's read scope with opaque cursor pagination (FR-13). Returns a `SceneList` envelope: omit `cursor` for the first page, then pass the prior page's `next_cursor` back as `cursor` to fetch the next page. A `null` `next_cursor` marks the last page.
- [Fetch one scene](https://docs.hyphaedb.com/api-reference/scenes/fetch-one-scene.md): Fetch a single scene by id. An absent or out-of-scope scene returns 404 (out-of-scope is indistinguishable from absent, by design).
- [Consolidate a scene](https://docs.hyphaedb.com/api-reference/scenes/consolidate-a-scene.md): Trigger consolidation of a scene (a gRPC/REST-only operation, not an MCP tool). Returns a report of how many cells were superseded and promoted.
- [Liveness probe](https://docs.hyphaedb.com/api-reference/health/liveness-probe.md): Unauthenticated liveness probe (a load-balancer health check). Returns the plain-text body `ok`.
- [Readiness probe](https://docs.hyphaedb.com/api-reference/health/readiness-probe.md): Unauthenticated readiness probe. Returns `200 ready` while serving; `503 draining` once a graceful shutdown has begun, so a load balancer removes the pod from rotation before the drain (deployment-operations.md §7.4). Liveness (`/healthz`) stays 200 throughout.
- [MCP tools overview](https://docs.hyphaedb.com/mcp/overview.md): How HyphaeDB exposes its memory engine to MCP agents as 11 JSON-RPC tools over stdio and HTTP.
- [ACP clients (Zed and friends)](https://docs.hyphaedb.com/mcp/acp-clients.md): Two ways to reach HyphaeDB from an Agent Client Protocol editor: through the MCP surface an ACP agent already speaks, or by running HyphaeDB itself as an ACP memory agent.
- [store](https://docs.hyphaedb.com/mcp/tools/store.md): Store a memory cell over MCP; the server embeds it, stamps the authenticated source agent, and gossips it.
- [recall](https://docs.hyphaedb.com/mcp/tools/recall.md): Recall the k nearest memory cells to a query at layer L0 over MCP; returns distance-ranked node ids.
- [start_session](https://docs.hyphaedb.com/mcp/tools/start-session.md): Open an agent working session in a project over MCP; returns the session id.
- [end_session](https://docs.hyphaedb.com/mcp/tools/end-session.md): Close an agent session by id over MCP.
- [place_beacon](https://docs.hyphaedb.com/mcp/tools/place-beacon.md): Place a standing interest beacon over MCP so matching diffs gossip to you; returns the beacon node id.
- [list_beacons](https://docs.hyphaedb.com/mcp/tools/list-beacons.md): List the beacon node ids the calling agent owns, over MCP.
- [inbox](https://docs.hyphaedb.com/mcp/tools/inbox.md): Drain the memory diffs gossiped to the calling agent since a timestamp, over MCP.
- [query](https://docs.hyphaedb.com/mcp/tools/query.md): Layered vector query over MCP against an explicit semantic layer (L0/L1/L2); returns scored node ids.
- [get_scene](https://docs.hyphaedb.com/mcp/tools/get-scene.md): Fetch one scene by id over MCP; returns the scene or null.
- [list_scenes](https://docs.hyphaedb.com/mcp/tools/list-scenes.md): List the scenes visible within the calling agent's read scope, over MCP.
- [pull_inbox](https://docs.hyphaedb.com/mcp/tools/pull-inbox.md): Drain the calling agent's inbox one page at a time against a server-owned acknowledgement cursor, over MCP.
- [gRPC overview](https://docs.hyphaedb.com/grpc/overview.md): The Hyphae gRPC service — eleven unary RPCs plus a bidirectional inbox stream over the same application core as REST and MCP.
- [A2A overview](https://docs.hyphaedb.com/a2a/overview.md): HyphaeDB's Agent2Agent surface — enablement, the standard agent card, versioning, and authentication for reaching shared memory over A2A.
- [A2A memory skills](https://docs.hyphaedb.com/a2a/memory-skills.md): The four A2A skills — remember, recall, query, share — dispatched by a deterministic grammar over message:send, and what completes a share task.
- [A2A tasks & streaming](https://docs.hyphaedb.com/a2a/tasks-and-streaming.md): Reading and canceling A2A tasks, SSE streaming over message:stream and tasks/{id}:subscribe, and push-notification-config storage.

## OpenAPI Specs

- [openapi](https://docs.hyphaedb.com/api-reference/openapi.json)