API Overview
API Access
Section titled “API Access”HEBBS exposes two API surfaces for the same operations:
| Protocol | Port | Use Case |
|---|---|---|
| gRPC | 6380 | Low-latency, streaming, typed clients |
| REST | 6381 | HTTP, curl, browser, webhooks |
Both APIs share the same underlying engine and behavior. Choose gRPC for production agents and low latency; choose REST for scripting, debugging, or integration with HTTP-only systems.
Authentication
Section titled “Authentication”All API requests require a Bearer token when auth is enabled (the default). The server prints a bootstrap API key on first start. Pass it as:
- REST:
Authorization: Bearer $HEBBS_API_KEYheader - gRPC:
authorization: Bearer $HEBBS_API_KEYmetadata
See REST Endpoints — Authentication for details.
Operations
Section titled “Operations”HEBBS defines exactly 9 operations, grouped into three categories:
| Operation | Description | Link |
|---|---|---|
| remember | Store a new memory with content, importance, context, and optional edges | remember |
| revise | Update a memory’s content, importance, or context while preserving history | revise |
| forget | Delete memories by entity, by IDs, or by criteria for GDPR compliance | forget |
| Operation | Description | Link |
|---|---|---|
| recall | Retrieve memories using one or more recall strategies (similarity, temporal, causal, analogical) | recall |
| prime | Pre-load session context by entity, blending temporal and similarity recall | prime |
| subscribe | Stream relevant memories in real-time as new text arrives (bidirectional streaming) | subscribe |
Consolidation
Section titled “Consolidation”| Operation | Description | Link |
|---|---|---|
| reflect_policy | Configure automatic background reflection triggers | reflect_policy |
| reflect | Manually trigger the reflection pipeline to consolidate memories into insights | reflect |
| insights | Query consolidated knowledge produced by the reflection pipeline | insights |
Exploration
Section titled “Exploration”| Operation | Description | Link |
|---|---|---|
| list | Browse memories with pagination, filter by entity or kind | REST Endpoints |
| edges | Get all outgoing and incoming graph edges for a memory | REST Endpoints |
| graph | Query a subgraph around a center node with depth control | REST Endpoints |
| entities | List all entity IDs with at least one memory | REST Endpoints |
| batch | Bulk-retrieve memories by IDs in a single request | REST Endpoints |
These endpoints power custom dashboards and graph visualizations. See the Custom Dashboard cookbook for a complete walkthrough.
Reference
Section titled “Reference”- Protobuf Schema — Complete gRPC service definitions
- REST Endpoints — Full HTTP API reference
- Error Codes — gRPC status codes, HTTP status codes, and HEBBS error taxonomy