Crate hirn

Expand description

§hirn — A Brain for Large Language Models

hirn /hɪʁn/ (German: brain) — a cognitive memory database engine for LLM systems, written in Rust.

hirn is a purpose-built database engine for cognitive memory. Not a wrapper around a vector database. Not an agent framework. A production-grade memory engine implementing neuroscience-grounded layered memory — working, episodic, and semantic — with graph-based associations, spreading activation, Hebbian self-organization, and narrative consolidation.

Ship it how you need it:

hirn — embed as a library. LanceDB-backed, zero network overhead. Like SQLite for memory.
hirnd — run as a standalone daemon with gRPC + HTTP + MCP.

§Quick Start

The easiest way to get started is HirnMemory — zero-config, auto-detects embedding providers from environment variables:

use hirn::prelude::*;

#[tokio::main]
async fn main() -> HirnResult<()> {
    let memory = HirnMemory::open("./brain").await?;
    memory.remember("User prefers dark mode").await?;
    let ctx = memory.think("What are the user's preferences?", 2048).await?;
    println!("{}", ctx.context);
    Ok(())
}

§Tokenizers

Tokenizer implementations are provider-owned and resolved through hirn_engine::ProviderRegistry. The tiktoken feature is enabled by default; enable hf-tokenizer for local HuggingFace tokenizers. When no model-backed tokenizer is available, hirn falls back to EstimatingTokenizer.

For fine-grained control, use Hirn directly with a PhysicalStore:

use hirn::prelude::*;
use hirn_storage::{HirnDb, HirnDbConfig};

#[tokio::main]
async fn main() -> HirnResult<()> {
    // Open LanceDB storage
    let config = HirnDbConfig::local("./brain/lance");
    let storage = HirnDb::open(config).await.unwrap().store_arc();

    // Open the database
    let brain = Hirn::open("./brain", storage).await.unwrap();

    // Register an agent
    let agent = AgentId::new("my_agent").unwrap();
    brain.register_agent(&agent, "My Agent").await.unwrap();

    // Get an agent-scoped context
    let ctx = brain.as_agent(&agent).await.unwrap();

    // Remember an experience (episodic memory)
    let episode = EpisodicRecord::builder()
        .content("Benchmark: HNSW with PQ outperforms brute-force by 40x")
        .event_type(EventType::Experiment)
        .agent_id(agent.clone())
        .importance(0.85)
        .embedding(vec![0.1; 768])
        .build()
        .unwrap();
    let id = ctx.remember(episode).await.unwrap();

    // Recall with spreading activation
    let results = brain
        .recall_view()
        .query(vec![0.1; 768])
        .activation(ActivationMode::Spreading)
        .limit(10)
        .execute()
        .await
        .unwrap();

    // Think — assemble optimal LLM context under token budget
    let context = brain
        .recall_view()
        .think(vec![0.1; 768])
        .budget(4096)
        .execute()
        .await
        .unwrap();

    // Or use HirnQL directly
    let result = brain.ql().execute(
        r#"RECALL episodic ABOUT "vector database" LIMIT 5"#
    ).await.unwrap();
    Ok(())
}

§Architecture

hirn implements three memory layers inspired by neuroscience:

Layer	Brain Analog	Purpose
Working	Prefrontal cortex	Token-bounded scratchpad for active reasoning
Episodic	Hippocampus	Time-anchored experiences and events
Semantic	Neocortex	Consolidated knowledge and stable facts

All memories exist as nodes in a typed property graph with spreading activation, Hebbian co-retrieval learning, causal reasoning, and namespace-based multi-agent isolation.

§Module Organization

prelude — Common imports for most use cases
agent — Multi-agent context and namespace isolation
episodic — Episodic memory records and builders
semantic — Semantic knowledge records and builders
working — Working memory entries and builders
graph — Property graph with typed edges
activation — Spreading activation with lateral inhibition
causal — Causal chain extraction and counterfactual reasoning
consolidation — Episodic → semantic consolidation engine
scoring — Composite relevance scoring
hebbian — Hebbian edge weight learning
ql — HirnQL query language parser and executor
provenance — Provenance tracking and audit trail
security — Anomaly detection and quarantine
vector — HNSW vector index (advanced)

Re-exports§

pub use memory::HirnMemory;
pub use memory::MemoryRecallBuilder;
pub use memory::MemoryThinkBuilder;

Modules§

activation: Spreading activation with lateral inhibition.
agent: Multi-agent context, namespace isolation, and team management.
causal: Causal chain extraction and counterfactual reasoning.
consolidation: Episodic → semantic consolidation engine.
content: Multi-modal content payloads and composite embedding helpers.
episodic: Episodic memory — the hippocampus.
graph: Property graph with typed, weighted edges.
hebbian: Hebbian edge weight learning.
memory: HirnMemory — zero-config, high-level memory API.
metadata: Metadata key-value storage.
prelude: Common imports for most hirn use cases.
procedural: Procedural memory — the basal ganglia / cerebellum.
provenance: Provenance tracking and audit trail.
ql: HirnQL — the cognitive memory query language.
query: Recall and think builder APIs.
record: Memory record types spanning all layers.
resource: First-class resource memory types: resources, artifacts, hydration, and governance.
scoring: Composite relevance scoring.
security: Memory security: anomaly detection and quarantine.
semantic: Semantic memory — the neocortex.
working: Working memory — the prefrontal cortex.

Structs§

AgentContext: Agent-scoped database context enforcing namespace isolation.
CharEstimateCounter: Character-estimate fallback: ceil(len / 4). Always available, zero dependencies.
ChatMessage: Chat message for LLM generation.
ConflictResolutionPolicy
ConflictResolutionPolicyOverrides
DbStats: Database statistics.
DefaultsConfig: Which provider name to use as default for each category.
EmbedderCircuitBreakerRuntimeConfig
EmbedderConfig: Configuration for a single embedder provider.
EmbedderPersistentCacheRuntimeConfig
EmbedderRetryConfig
EmbedderRuntimeConfig
Embedding: A single embedding result with its source model identifier.
EstimatingTokenizer: Character-estimate tokenizer: ceil(len / 4). Zero dependencies, always available.
ExtractedEntity: An entity extracted from unstructured text.
ExtractedRelation: A relation between two extracted entities.
HirnConfig: Database configuration with production-ready defaults.
HirnDB: The main database handle.
IntegrityIssue: A specific integrity issue found in the database.
IntegrityReport: Result of a database integrity check.
LayerCounts: Layer counts.
LlmChunk: A single chunk from a streaming LLM response.
LlmConfig: Configuration for a single LLM provider.
LlmOptions: Options for LLM generation requests.
LlmResponse: Full response from the LLM provider.
MemoryId: Time-sortable, globally unique memory identifier wrapping a ULID.
NoopReranker: Identity reranker — returns all documents in original order.
ProviderConfig: Top-level provider configuration, TOML-deserializable.
ProviderDefaults: Names of the default providers in each category.
ProviderRegistry: Central registry for AI providers, supporting runtime hot-swap.
ProvidersSection: The [providers] section: maps category → name → config.
RepairReport: Result of a repair operation.
RerankResult: Result of a reranking operation on a single document.
RerankerConfig: Configuration for a single reranker provider.
RevisionId: Immutable identifier for a specific revision of a logical memory.
SemanticRevisionIntegrityIssue: A specific semantic revision integrity issue.
SemanticRevisionIntegrityReport: Result of validating semantic revision chains and the runtime head cache.
SemanticRevisionRepairReport: Result of repairing the semantic revision head cache.
Timestamp: Nanosecond-precision timestamp backed by chrono::DateTime<Utc>.
TokenUsage: Token usage reported by the provider.
TokenizerConfig: Configuration for a single tokenizer provider.

Enums§

ApiKeySource: How an API key is specified in the TOML config.
HirnError: Errors emitted by the hirn library.
IssueKind: Categories of integrity issues.
MemoryEvent: An event emitted when the database state changes.
RecallSnapshot: Snapshot target for revision-aware recall.
ResponseFormat: Desired response format from the LLM.
SemanticRevisionIssueKind: Categories of semantic revision integrity issues.
StoreError: Internal storage error conversions.

Traits§

Embedder: Pluggable embedding provider (F-39).
EntityExtractor: Entity and relation extraction from unstructured text (F-41).
LlmProvider: Pluggable LLM provider for structured extraction and generation (F-41, §12).
Reranker: Two-stage reranker (§12.4.2): cross-encoder precision after bi-encoder recall.
TokenCounter: Pluggable token counter (§11.5).
Tokenizer: Pluggable tokenizer providing encode, decode, truncate, and count operations.

Functions§

inspected_result_to_json
trace_result_to_json
traced_result_to_json

Type Aliases§

Hirn: The database handle. Open a Hirn to start working with cognitive memory.
HirnResult: Result type alias for hirn operations.
LlmStream: Stream of LLM chunks.

Crate hirn

Crate hirn Copy item path

§hirn — A Brain for Large Language Models

§Quick Start

§Tokenizers

§Architecture

§Module Organization

Re-exports§

Modules§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Crate hirn