Struct HirnDB 

pub struct HirnDB { /* private fields */ }

The main database handle.

Implementations

impl HirnDB

pub async fn remember_bypass_admission( &self, record: EpisodicRecord, ) -> HirnResult<MemoryId>

Store an episodic record bypassing admission control.

Useful for data migration, admin writes, or replaying events.

pub async fn record_episode_access(&self, id: MemoryId) -> HirnResult<()>

Update access stats for a single episodic record. Called periodically or on important reads (e.g., from recall).

pub fn start_decay_task(self: &Arc<Self>, interval: Duration) -> JoinHandle<()>

Start a background task that periodically runs decay + TTL purge.

Returns a JoinHandle that can be awaited on shutdown. The task runs at interval cadence and stops when the returned handle is aborted or the runtime shuts down.

impl HirnDB

pub fn subscribe(&self) -> Receiver<MemoryEvent>

Subscribe to real-time memory events.

Returns a tokio::sync::broadcast::Receiver<MemoryEvent> that yields events whenever the database state changes (create, archive, consolidate, etc.). The broadcast ring buffer is lock-free; lagging subscribers receive a tokio::sync::broadcast::error::RecvError::Lagged error and skip missed events rather than blocking the write path.

pub async fn register_agent( &self, agent_id: &AgentId, display_name: impl Into<String>, ) -> HirnResult<()>

Register a new agent. Creates private namespace private:{agent_id}.

pub async fn list_agents(&self) -> HirnResult<Vec<AgentRecord>>

List all registered agents.

pub async fn get_agent(&self, agent_id: &AgentId) -> HirnResult<AgentRecord>

Get a registered agent.

pub async fn update_agent(&self, agent: &AgentRecord) -> HirnResult<()>

Update a registered agent record.

pub async fn deregister_agent(&self, agent_id: &AgentId) -> HirnResult<()>

Deregister an agent and delete its private namespace.

pub async fn create_team_namespace( &self, name: &str, agent_ids: Vec<AgentId>, ) -> HirnResult<()>

Create a team namespace with the given agent members.

pub async fn add_agent_to_team( &self, agent_id: &AgentId, team_name: &str, ) -> HirnResult<()>

Add an agent to a team namespace.

pub async fn remove_agent_from_team( &self, agent_id: &AgentId, team_name: &str, ) -> HirnResult<()>

Remove an agent from a team namespace.

pub async fn ensure_agent(&self, agent_id: &AgentId) -> HirnResult<()>

Register an agent if not already registered. Returns Ok(()) in either case.

pub async fn as_agent(&self, agent_id: &AgentId) -> HirnResult<AgentContext<'_>>

Create an agent-scoped context for namespace-isolated operations.

impl HirnDB

pub async fn batch_recall<'a>( &'a self, builders: Vec<RecallBuilder<'a>>, ) -> Vec<HirnResult<Vec<RecallResult>>>

Execute multiple recall queries concurrently. Returns per-query results.

pub fn embedding_dims(&self) -> usize

Get the configured embedding dimensions.

impl HirnDB

pub fn episodic(&self) -> EpisodicView<'_>

Access episodic memory operations.

pub fn semantic(&self) -> SemanticView<'_>

Access semantic memory operations.

pub fn procedural(&self) -> ProceduralView<'_>

Access procedural memory operations.

pub fn working(&self) -> WorkingView<'_>

Access working memory operations.

pub fn graph_view(&self) -> GraphView<'_>

Access graph operations.

pub fn recall_view(&self) -> RecallView<'_>

Access recall, think and trace operations.

pub fn namespaces(&self) -> NamespaceView<'_>

Access namespace management operations.

pub fn policy(&self) -> PolicyView<'_>

Access Cedar policy operations.

pub fn admin(&self) -> AdminView<'_>

Access administrative operations (stats, compaction, maintenance).

pub fn ql(&self) -> QueryView<'_>

Access HirnQL query execution operations.

pub fn causal(&self) -> CausalView<'_>

Access causal reasoning operations (contradictions, quarantine, ABA).

impl HirnDB

pub async fn open( path: impl AsRef<Path>, storage: Arc<dyn PhysicalStore>, ) -> HirnResult<Self>

Open or create a database at the given path with the given storage backend.

pub async fn open_with_config( config: HirnConfig, storage: Arc<dyn PhysicalStore>, ) -> HirnResult<Self>

Open or create a database with the given configuration and storage backend.

All data is stored exclusively in LanceDB via the PhysicalStore. On startup, the in-memory namespace index is rebuilt from stored records.

pub const fn config(&self) -> &HirnConfig

Get the config.

pub fn tier_policy(&self) -> TierPolicy

Get a snapshot of the current tier policy.

pub fn set_tier_policy(&self, policy: TierPolicy)

Update the tier policy at runtime (used by SET TIER_POLICY).

pub fn path(&self) -> &Path

Get the database file path.

pub fn session(&self) -> &SessionContext

Get the DataFusion SessionContext with scoring UDFs and HirnSessionExt pre-registered.

pub fn query_pipeline(&self) -> &QueryPipeline

Get the 7-stage query pipeline (stages 1–4 in hirn-query).

pub fn plan_cache(&self) -> &Arc<PlanCache>

Get the shared plan cache.

pub fn reconsolidation_tracker(&self) -> &ReconsolidationTracker

Get the reconsolidation tracker.

pub fn set_embedder(&self, embedder: Arc<dyn Embedder>)

Set a custom embedding provider (F-39).

When set, RECALL, REMEMBER, and UPSERT SEMANTIC will use this embedder instead of the built-in pseudo-embedding hash. The provider is wrapped in the default multimodal router so multi_content and composite auto-embedding use the same configured runtime wrappers. Also updates the HirnSessionExt in the DataFusion SessionContext so that operators (e.g. RpeScoreExec, ProspectiveIndexingExec) can access the embedder at execution time.

pub fn set_multimodal_embedder(&self, embedder: Arc<MultiModalEmbedder>)

Set a modality-aware embedding provider chain.

Each configured underlying embedder is wrapped through the standard retry/cache/circuit-breaker/batching pipeline before being installed.

pub fn set_multivec_embedder(&self, embedder: Arc<dyn Embedder>)

Set a multivector (ColBERT-style) embedder for late interaction search.

When set and config.multivector_enabled is true, recall queries will additionally compute MaxSim scores from token-level embeddings.

pub fn set_tokenizer(&self, tokenizer: Arc<dyn Tokenizer>)

Set the tokenizer used for token-aware budgeting paths.

pub fn tokenizer(&self) -> Arc<dyn Tokenizer>

Get the tokenizer used by this database instance.

pub fn pending_embed_count(&self) -> usize

Number of memory IDs awaiting background embed retry.

pub async fn retry_pending_embeds(&self) -> (usize, usize)

Retry embedding for records that were stored without embeddings due to provider failure. Call this after the embed provider recovers.

Returns (succeeded, failed) counts. Failed items are requeued up to max_attempts (default 3) with exponential backoff.

pub fn set_reranker(&self, reranker: Arc<dyn Reranker>)

Set a reranker for post-retrieval relevance reordering.

When set and query_text is provided, recall results are reranked after composite scoring. Use with CohereReranker, LlmReranker, or any custom Reranker implementation.

pub async fn ensure_fts_indexes(&self) -> HirnResult<()>

Ensure FTS indexes exist on all LanceDB datasets.

Creates full-text search indexes on the text columns of each dataset (episodic → content, semantic → description, procedural → description). Idempotent: only runs once per HirnDB instance. Subsequent calls are no-ops.

pub fn fts_initialized(&self) -> bool

Check whether FTS indexes have been created.

pub async fn create_vector_indexes( &self, index_type: IndexType, params: Option<IndexParams>, ) -> HirnResult<()>

Create vector indexes on all embedding columns (episodic, semantic, procedural).

Skips datasets that don’t exist or have no rows. Uses replace: false so existing indexes are kept.

pub async fn rebuild_vector_indexes( &self, index_type: IndexType, params: Option<IndexParams>, ) -> HirnResult<()>

Rebuild vector indexes on all embedding columns (episodic, semantic, procedural).

Same as create_vector_indexes but with replace: true, so any existing vector index is dropped and recreated.

pub fn prefetch_stats(&self) -> PrefetchStats

Get a snapshot of prefetch statistics.

pub fn index_advisor(&self) -> &IndexAdvisor

Get a reference to the index advisor for query pattern analysis.

pub fn set_event_log(&self, log: Arc<EventLog>)

Enable event sourcing by attaching an EventLog.

Once set, every mutation (remember, archive, store_semantic, etc.) will be appended to the durable event log in addition to the in-memory broadcast channel.

pub fn event_log(&self) -> Option<Arc<EventLog>>

Get a reference to the event log, if event sourcing is enabled.

pub fn persistent_graph(&self) -> &PersistentGraph

Get a reference to the persistent graph (cold tier).

pub fn graph_store(&self) -> &dyn GraphStore

Get a unified graph store reference.

Returns the CachedGraphStore as &dyn GraphStore — reads use the hot tier (sub-ms), writes are write-through to both tiers.

pub fn cached_graph(&self) -> &CachedGraphStore

Get a reference to the two-tier cached graph store.

pub fn set_admission_pipeline(&mut self, pipeline: AdmissionPipeline)

Set the admission control pipeline.

When configured, remember() runs candidates through the pipeline before materializing them. Rejected candidates return an error.

pub fn setup_default_admission_pipeline(&mut self)

Build and set the default admission pipeline from config.

Default order: [SurpriseGate, DuplicateDetector, TokenBudgetGate, RateLimiter]. Only sets the pipeline if config.admission_enabled is true.

pub fn admission_pipeline(&self) -> Option<&AdmissionPipeline>

Get a reference to the admission pipeline, if configured.

pub fn set_policy_engine(&mut self, engine: PolicyEngine)

Set the Cedar policy engine for fine-grained authorization.

When set, enforce() evaluates every operation against loaded Cedar policies. When unset, all operations are allowed (embedded mode).

pub fn policy_engine(&self) -> Option<&PolicyEngine>

Get a reference to the policy engine, if configured.

pub fn storage_backend(&self) -> &dyn PhysicalStore

Get the storage backend.

pub fn storage_arc(&self) -> Arc<dyn PhysicalStore>

Get a cloned Arc to the underlying storage backend.

Use this when a long-lived (possibly 'static) reference to the storage is needed (e.g. fire-and-forget background tasks).

pub async fn apply_resource_retention_policy( &self, policy: &ResourceRetentionPolicy, ) -> HirnResult<ResourceRetentionApplyResult>

Apply a specific resource retention policy to active resource heads.

pub async fn apply_configured_resource_retention( &self, ) -> HirnResult<ResourceRetentionApplyResult>

Apply the configured resource retention policy from HirnConfig.

pub fn embedder(&self) -> Option<Arc<dyn Embedder>>

Get the configured embedder, if any.

pub async fn embed_text(&self, text: &str) -> HirnResult<Vec<f32>>

Embed a single text using the configured embedder, falling back to pseudo-embedding when no real model is available.

pub async fn embed_content( &self, content: &MemoryContent, ) -> HirnResult<Vec<f32>>

Embed a MemoryContent value using the text representation for each modality. Images use their description, code uses source, audio uses transcript, structured uses JSON serialization.

pub async fn fetch_resource( &self, actor_id: &AgentId, resource_id: ResourceId, hydration_mode: HydrationMode, ) -> HirnResult<Option<HydratedResource>>

Fetch a resource with actor-scoped metadata/preview/full hydration semantics. MetadataOnly and Preview require Recall; Full additionally requires RecallRawText for the resource namespace.

pub async fn load_resource_blob( &self, actor_id: &AgentId, id: MemoryId, blob_index: u32, ) -> HirnResult<Vec<u8>>

Load resource-backed blob data for an episodic memory record slot.

pub async fn hydrate_content_resources( &self, actor_id: &AgentId, namespace: Namespace, content: &MemoryContent, evidence_links: &[EvidenceLink], ) -> HirnResult<MemoryContent>

Hydrate a MemoryContent by restoring binary payloads referenced through evidence links. Raw hydration is explicit and requires RecallRawText permission for the namespace.

pub async fn get_episode_with_resources( &self, actor_id: &AgentId, id: MemoryId, ) -> HirnResult<EpisodicRecord>

Retrieve an episodic record with all resource-backed payloads hydrated. Full hydration is explicit and requires RecallRawText permission.

pub async fn close(&self) -> HirnResult<()>

Explicitly flush all pending buffers (Hebbian, episodic access, semantic access) and prepare the database for shutdown.

This drains the Hebbian weight buffer, flushes access-count deltas, completes pending offline scheduler jobs, and returns cleanly. Prefer calling this before dropping the last Arc<HirnDB> reference; if omitted, Drop runs a best-effort synchronous flush on a helper thread (F-125 fix).

impl HirnDB

pub fn watch(&self, filter: WatchFilter) -> HirnResult<WatchSubscription>

Create a watch subscription with the given filter.

Requires an active EventLog (returns error otherwise).

Trait Implementations

impl Drop for HirnDB

F-S1: Flush remaining Hebbian buffer on drop to ensure weight updates are persisted even if the caller doesn’t explicitly flush.

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.