Types Reference

All types are importable from hebbs or hebbs.types. They are implemented as frozen or mutable Python dataclasses with full type annotation support.

Memory

The core data type representing a stored memory.

Field	Type	Description
id	bytes	16-byte unique memory identifier
content	str	The memory text
importance	float	Importance score (0.0—1.0)
context	dict[str, Any]	Structured key-value metadata (used by analogical recall for structural matching)
entity_id	str | None	Entity scope. None if stored without an entity.
created_at	int	Creation timestamp in microseconds
updated_at	int	Last modification timestamp in microseconds
last_accessed_at	int	Last access timestamp in microseconds
access_count	int	How many times this memory has been recalled (Hebbian reinforcement)
decay_score	float	Current decay score (importance adjusted by time decay)
kind	MemoryKind	Memory classification (episode, insight, revision)
embedding	list[float]	The embedding vector (empty unless explicitly requested)

MemoryKind

Enum classifying the type of memory.

Variant	Value	Description
EPISODE	"episode"	A stored event or observation — the default kind
INSIGHT	"insight"	Generated by the reflection pipeline from clusters of episodes
REVISION	"revision"	Created by revise() — supersedes a previous memory
UNSPECIFIED	"unspecified"	Unknown or not set

Edge

A directed relationship between two memories. Used with remember() to create graph edges.

Field	Type	Description
target_id	bytes	16-byte ID of the target memory
edge_type	EdgeType	Relationship classification
confidence	float | None	Strength of the relationship (0.0—1.0). Default: None (engine default).

from hebbs import Edge, EdgeType

edge = Edge(target_id=mem.id, edge_type=EdgeType.FOLLOWED_BY, confidence=0.95)

EdgeType

Enum for relationship types between memories. Used in Edge and for filtering causal recall via RecallStrategyConfig.edge_types.

Variant	Value	Description
CAUSED_BY	"caused_by"	Target caused this memory
RELATED_TO	"related_to"	General semantic relationship
FOLLOWED_BY	"followed_by"	This memory followed the target chronologically
REVISED_FROM	"revised_from"	Revision lineage (set automatically by revise())
INSIGHT_FROM	"insight_from"	Insight derived from source memories (set by reflect())
UNSPECIFIED	"unspecified"	Unknown or not set

RecallStrategy

Enum for the four recall strategies.

Variant	Value	Description
SIMILARITY	"similarity"	Semantic vector similarity (HNSW index)
TEMPORAL	"temporal"	Time-proximity ordering (B-tree index)
CAUSAL	"causal"	Graph traversal following causal edges
ANALOGICAL	"analogical"	Cross-domain pattern matching (blends embedding + structural similarity)

RecallStrategyConfig

Per-strategy configuration for advanced recall tuning. See Client Reference for the full parameter table and usage examples.

Field	Type	Default	Description
strategy	str	(required)	Strategy name
entity_id	str | None	None	Override entity scope for this strategy
top_k	int | None	None	Per-strategy result limit
ef_search	int | None	50	HNSW candidate count (similarity)
time_range	tuple[int, int] | None	None	(start_us, end_us) bounds (temporal)
seed_memory_id	bytes | None	None	Graph traversal start node (causal)
edge_types	list[EdgeType] | None	None	Restrict traversal edges (causal)
max_depth	int | None	5	Max hops (causal, hard cap: 10)
analogical_alpha	float | None	0.5	Structural vs. embedding blend (analogical)

ScoringWeights

Override composite scoring weights for recall() and prime(). Can be passed as a ScoringWeights dataclass or a plain dict.

Field	Type	Default	Description
w_relevance	float	0.5	Weight for semantic relevance (cosine similarity)
w_recency	float	0.2	Weight for temporal recency
w_importance	float	0.2	Weight for stored importance value
w_reinforcement	float	0.1	Weight for recall frequency (Hebbian reinforcement)
max_age_us	int | None	None	Max age for recency decay (microseconds). Server default: 30 days.
reinforcement_cap	int | None	None	Cap for reinforcement scaling. Server default: 100.

from hebbs import ScoringWeights

# Dataclass
weights = ScoringWeights(w_relevance=0.8, w_recency=0.1, w_importance=0.05, w_reinforcement=0.05)

# Or as a dict
weights = {"w_relevance": 0.8, "w_recency": 0.1, "w_importance": 0.05, "w_reinforcement": 0.05}

StrategyDetail

Per-strategy metadata for a recall result. Each strategy populates different fields.

Field	Type	Description
strategy	str	Strategy name: "similarity", "temporal", "causal", "analogical"
relevance	float	Raw relevance score for this strategy
distance	float | None	HNSW distance (similarity only)
timestamp	int | None	Memory timestamp in microseconds (temporal only)
rank	int | None	Ordering rank in temporal results (temporal only)
depth	int | None	Graph traversal depth from seed (causal only)
embedding_similarity	float | None	Embedding similarity component (analogical only)
structural_similarity	float | None	Structural similarity component (analogical only)

RecallResult

A single memory returned from a recall query, with composite score and strategy details.

Field	Type	Description
memory	Memory	The recalled memory
score	float	Composite score (weighted blend of relevance, recency, importance, reinforcement)
strategy_details	list[StrategyDetail]	Per-strategy metadata. A memory found by multiple strategies has multiple entries.

StrategyError

Reports a per-strategy error when one strategy fails but others succeed.

Field	Type	Description
strategy	str	Strategy that failed
message	str	Error message

RecallOutput

The complete response from a recall() call.

Field	Type	Description
results	list[RecallResult]	Ranked list of recalled memories (sorted by composite score)
strategy_errors	list[StrategyError]	Errors from individual strategies, if any (partial success is possible)

PrimeOutput

Response from a prime() call.

Field	Type	Description
results	list[RecallResult]	Blended temporal + similarity results
temporal_count	int	Number of results from the temporal component
similarity_count	int	Number of results from the similarity component

ForgetResult

Response from a forget() call.

Field	Type	Description
forgotten_count	int	Number of memories erased
cascade_count	int	Number of related records (edges, snapshots) cascade-deleted
tombstone_count	int	Number of tombstone records created for audit
truncated	bool	Whether the result set was truncated (large entity deletions)

ReflectResult

Response from a reflect() call.

Field	Type	Description
insights_created	int	Number of new insight memories generated
clusters_found	int	Number of memory clusters identified
clusters_processed	int	Number of clusters processed by the LLM pipeline
memories_processed	int	Total number of source memories analyzed

SubscribePush

A push notification received on a subscription stream.

Field	Type	Description
subscription_id	int	ID of the subscription that generated this push
memory	Memory	The surfaced memory
confidence	float	Confidence score for this push (0.0—1.0)
push_timestamp_us	int	Server timestamp when the push was generated (microseconds)
sequence_number	int	Monotonically increasing sequence for ordering

HealthStatus

Server health information returned by health().

Field	Type	Description
serving	bool	Whether the server is serving requests
version	str	Server version string (e.g. "0.1.0")
memory_count	int	Total memories stored across all entities
uptime_seconds	int	Server uptime in seconds

Exception Hierarchy

All exceptions inherit from HebbsError and are importable from hebbs or hebbs.exceptions.

Exception	gRPC Code	Description
HebbsError	—	Base exception
HebbsConnectionError	—	Failed to connect to the server
HebbsAuthenticationError	UNAUTHENTICATED	Missing or invalid API key
HebbsPermissionDeniedError	PERMISSION_DENIED	Insufficient permissions
HebbsNotFoundError	NOT_FOUND	Memory or resource not found
HebbsInvalidArgumentError	INVALID_ARGUMENT	Malformed request
HebbsTimeoutError	DEADLINE_EXCEEDED	Operation timed out
HebbsUnavailableError	UNAVAILABLE	Server temporarily unavailable
HebbsInternalError	INTERNAL	Internal server error