Skip to content
HEBBS

Architecture Overview

HEBBS is a single-binary cognitive memory engine that provides AI agents with persistent, multi-modal recall. This page describes the high-level architecture, component responsibilities, and data flow.

Component Diagram

Section titled “Component Diagram”

The HEBBS server is composed of six major subsystems:

┌─────────────────────────────────────────────────────────┐
│                     gRPC Server                         │
│               (tonic, request routing)                  │
├─────────────────────────────────────────────────────────┤
│                     Core Engine                         │
│        (operation dispatch, entity isolation)            │
├────────────┬────────────┬────────────┬──────────────────┤
│   HNSW     │  Temporal  │   Graph    │    Embedding     │
│   Index    │  B-tree    │  Adjacency │    Engine        │
│            │  Index     │  Index     │  (ONNX Runtime)  │
├────────────┴────────────┴────────────┴──────────────────┤
│                   Storage Layer                         │
│          (RocksDB, column families, WAL)                │
├─────────────────────────────────────────────────────────┤
│               Reflection Pipeline                       │
│    (cluster → propose → validate → consolidate)         │
└─────────────────────────────────────────────────────────┘

Subsystem Responsibilities

Section titled “Subsystem Responsibilities”
SubsystemPurpose
gRPC ServerAccepts client connections, deserializes requests, routes to the core engine. Built on tonic.
Core EngineOrchestrates operations across indexes and storage. Enforces entity isolation and operation semantics.
HNSW IndexApproximate nearest neighbor search for similarity-based recall. O(log n) query complexity. Vectors are stored as int8 with Walsh-Hadamard rotation for ~3x memory reduction; full-precision f32 vectors are kept on disk for two-tier reranking.
Temporal B-treeTime-ordered index for temporal recall. O(log n) range queries.
Graph AdjacencyEdge-based index for causal and relational recall. O(k) traversal with bounded depth.
Embedding EngineConverts text to 768-dimensional vectors using ONNX Runtime with EmbeddingGemma-300M.
Storage LayerPersistent storage via embedded RocksDB. Column families for memories, edges, indexes, and metadata.
Reflection PipelineBackground process that autonomously handles reflection (insight generation), contradiction resolution, and proposition extraction via LLM.

Data Flow: Remember

Section titled “Data Flow: Remember”

When a client calls remember:

  1. Server receives the gRPC request and validates inputs at the boundary.
  2. Core Engine assigns an ID, timestamps the memory, and prepares a WriteBatch.
  3. Embedding Engine generates a 768-dimensional vector from the memory content.
  4. Indexes — the HNSW index inserts the vector, the temporal B-tree inserts the timestamp, and the graph index inserts any edges. All updates are added to the WriteBatch.
  5. Storage atomically commits the WriteBatch to RocksDB, ensuring crash consistency.
  6. Server returns the stored memory with its assigned ID.

Total latency budget: < 5ms p99 (excluding embedding, which is amortized via batching).

Data Flow: Recall

Section titled “Data Flow: Recall”

When a client calls recall:

  1. Server receives the gRPC request.
  2. Core Engine routes to the appropriate index based on the recall strategy.
  3. Index query — similarity queries HNSW, temporal queries the B-tree, causal traverses the graph, analogical combines HNSW with cross-entity graph traversal.
  4. Reranking — for similarity queries, HNSW returns 2x candidates using fast int8 distances, then loads f32 vectors from disk and recomputes exact distances for final ranking.
  5. Storage fetches full memory records for the top-k results.
  6. Server returns ranked results with relevance scores.

Total latency budget: < 10ms p99 for similarity recall at 10M memories.

Design Principles

Section titled “Design Principles”
  • Single binary — no external database dependencies. RocksDB is embedded.
  • Entity isolation — memories are partitioned by entity. No cross-entity leakage.
  • Atomic multi-index updates — all index and storage writes happen in a single RocksDB WriteBatch for crash consistency.
  • Hot path sanctity — no network calls, no unbounded computation, no locks on the read path.
  • Background autonomy — LLM calls are used for reflection, contradiction resolution, and proposition extraction, all running autonomously in the background. LLM calls never happen on the hot path.

Next Steps

Section titled “Next Steps”