Skip to main content

Crate engramai

Crate engramai 

Source
Expand description

§IronClaw-Engram: Neuroscience-Grounded Memory for IronClaw Agents

IronClaw-Engram is a Rust port of Engram, a memory system for AI agents based on cognitive science models, optimized for integration with IronClaw.

§Core Cognitive Models

  • ACT-R Activation: Retrieval based on frequency, recency, and spreading activation
  • Memory Chain Model: Dual-trace consolidation (hippocampus → neocortex)
  • Ebbinghaus Forgetting: Exponential decay with spaced repetition
  • Hebbian Learning: Co-activation forms associative links
  • STDP: Temporal patterns infer causal relationships
  • LLM Extraction: Optional fact extraction via Anthropic/Ollama before storage

§Quick Start

use engramai::{Memory, MemoryType};

let mut mem = Memory::new("./agent.db", None)?;

// Store memories
mem.add(
    "potato prefers action over discussion",
    MemoryType::Relational,
    Some(0.7),
    None,
    None,
)?;

// Recall with ACT-R activation
let results = mem.recall("what does potato prefer?", 5, None, None)?;
for r in results {
    println!("[{}] {}", r.confidence_label, r.record.content);
}

// Consolidate (run "sleep" cycle)
mem.consolidate(1.0)?;

§LLM-Based Extraction

Optionally extract structured facts from raw text before storage:

use engramai::{Memory, MemoryType, OllamaExtractor, AnthropicExtractor};

let mut mem = Memory::new("./agent.db", None)?;

// Use Ollama for local extraction
mem.set_extractor(Box::new(OllamaExtractor::new("llama3.2:3b")));

// Or use Anthropic Claude (Haiku recommended for cost)
// mem.set_extractor(Box::new(AnthropicExtractor::new("sk-ant-...", false)));

// Now add() extracts facts via LLM before storing
mem.add(
    "我昨天和小明一起吃了火锅，很好吃。他说下周要去上海出差。",
    MemoryType::Episodic,
    None,
    None,
    None,
)?;
// Stores extracted facts like:
// - "User ate hotpot yesterday with Xiaoming" (episodic, 0.5)
// - "User found the hotpot delicious" (emotional, 0.6)
// - "Xiaoming will travel to Shanghai for business next week" (factual, 0.7)

§Configuration Presets

use engramai::MemoryConfig;

// Chatbot: slow decay, high replay
let config = MemoryConfig::chatbot();

// Task agent: fast decay, low replay
let config = MemoryConfig::task_agent();

// Personal assistant: very slow core decay
let config = MemoryConfig::personal_assistant();

// Researcher: minimal forgetting
let config = MemoryConfig::researcher();

Re-exports§

pub use bus::EmpathyBus;
pub use bus::SoulUpdate;
pub use bus::HeartbeatUpdate;
pub use bus::Drive;
pub use bus::HeartbeatTask;
pub use bus::Identity;
pub use bus::EmpathyTrend;
pub use bus::ActionStats;
pub use bus::SubscriptionManager;
pub use bus::Subscription;
pub use bus::Notification;
pub use bus::DriveEmbeddings;
pub use bus::score_alignment_hybrid;
pub use bus::EmotionalBus;
pub use bus::EmotionalTrend;
pub use config::MemoryConfig;
pub use config::TripleConfig;
pub use embeddings::EmbeddingConfig;
pub use embeddings::EmbeddingProvider;
pub use embeddings::EmbeddingError;
pub use extractor::MemoryExtractor;
pub use extractor::ExtractedFact;
pub use extractor::AnthropicExtractor;
pub use extractor::AnthropicExtractorConfig;
pub use extractor::TokenProvider;
pub use extractor::OllamaExtractor;
pub use extractor::OllamaExtractorConfig;
pub use memory::Memory;
pub use memory::SleepReport;
pub use memory::is_insight;
pub use storage::EmbeddingStats;
pub use storage::EntityRecord;
pub use types::AclEntry;
pub use types::MemoryLayer;
pub use types::MergeOutcome;
pub use types::MemoryRecord;
pub use types::MemoryStats;
pub use types::MemoryType;
pub use types::Permission;
pub use types::RecallResult;
pub use types::RecallWithAssociationsResult;
pub use types::SupersessionError;
pub use types::SupersessionInfo;
pub use types::BulkCorrectionResult;
pub use anomaly::BaselineTracker;
pub use anomaly::Baseline;
pub use anomaly::AnomalyResult;
pub use confidence::confidence_score;
pub use confidence::confidence_label;
pub use confidence::confidence_detail;
pub use confidence::content_reliability;
pub use confidence::retrieval_salience;
pub use confidence::ConfidenceDetail;
pub use hybrid_search::reciprocal_rank_fusion;
pub use hybrid_search::HybridSearchResult;
pub use hybrid_search::HybridSearchOpts;
pub use session_wm::SessionWorkingMemory;
pub use session_wm::SessionRegistry;
pub use session_wm::SessionRecallResult;
pub use session_wm::CachedScore;
pub use synthesis::types::SynthesisSettings;
pub use synthesis::types::SynthesisReport;
pub use synthesis::types::SynthesisError;
pub use synthesis::types::SynthesisEngine;
pub use synthesis::types::SynthesisLlmProvider;
pub use synthesis::types::MemoryCluster;
pub use synthesis::types::GateDecision;
pub use synthesis::types::GateResult;
pub use synthesis::types::ProvenanceRecord;
pub use synthesis::types::ProvenanceChain;
pub use synthesis::types::UndoSynthesis;
pub use triple::Triple;
pub use triple::Predicate;
pub use triple::TripleSource;
pub use triple_extractor::TripleExtractor;
pub use triple_extractor::AnthropicTripleExtractor;
pub use triple_extractor::OllamaTripleExtractor;
pub use promotion::PromotionCandidate;
pub use lifecycle::DecayReport;
pub use lifecycle::ForgetReport;
pub use lifecycle::AddResult;
pub use lifecycle::LifecycleError;
pub use lifecycle::PhaseReport;
pub use lifecycle::HealthReport;
pub use lifecycle::RebalanceReport;

Modules§

anomaly
Anomaly/Baseline Tracker — sliding window statistics for anomaly detection.
association
Multi-signal Hebbian association discovery.
bus
Empathy Bus — Connects Engram to agent workspace files.
clustering
Unified Infomap clustering engine with pluggable edge-weight strategies.
compiler
Knowledge Compiler (KC)
confidence
Confidence Calibration — Two-dimensional metacognitive monitoring.
config
Memory configuration presets and tunable parameters.
embeddings
Embedding providers for semantic memory retrieval.
entities
Entity extraction for memory content.
extractor
LLM-based memory extraction.
hybrid_search
Adaptive Hybrid Search — combines vector similarity with FTS for optimal retrieval.
interoceptive
Interoceptive Layer — The brain-island integration module.
lifecycle
Memory lifecycle types: decay, forget, dedup, reconcile, rebalance.
memory
Main Memory API — simplified interface to Engram’s cognitive models.
models
Cognitive models for memory dynamics.
promotion
Knowledge Promotion: detect high-frequency memory patterns and suggest promoting them to persistent documents (SOUL.md, MEMORY.md, etc.)
query_classifier
Query type classification for adaptive weight adjustment.
session_wm
Session Working Memory — Miller’s Law-constrained active memory buffer.
storage
SQLite storage backend for Engram.
synthesis
Memory synthesis engine — cluster discovery, gate checking, insight generation.
triple
Triple types for LLM-based knowledge graph extraction.
triple_extractor
LLM-based triple extraction from memory content.
types
Core memory data types.