# mimirs-agent

![mimirs-agent concept](../docs/assets/mimirs_agent_concept.png)


Unified facade crate that integrates all 15 MimirsWell subsystems behind the `MemoryAgent` async trait.

## What It Does

- `MimirAgent`: The main struct. Holds references to all subsystems (Urdarbrunnr, Hugin, Muninn, Vafthrudnir, Forseti, Ginnunga, Saga, ThingNode, EventBus, Nott, Yggdrasil, IdentityKnot, optional encoder, optional SleipnirEngine).
- Implements `MemoryAgent` for `MimirAgent` with full store/recall/forget/consolidate/reflect/snapshot/propagate/monitor_criticality and block operations.
- `AgentConfig`: Configuration loaded from environment variables with defaults.
- `ZenohQueryable`: Wrapper for Zenoh queryable endpoints.

## What It Does NOT Do

- No new algorithms. This crate assembles existing crates.

## Public API

```rust
pub struct MimirAgent {
    /* internal: all subsystem handles */
}

impl MimirAgent {
    /// Creates a new agent with the given storage well and configuration.
    /// Initializes all subsystems with default Phase 6 parameters.
    pub fn new(well: Arc<Urdarbrunnr>, config: AgentConfig) -> Self;

    /// Attaches a pre-built semantic encoder.
    pub fn with_encoder(self, encoder: SharedEncoder) -> Self;

    /// Downloads and loads the default semantic encoder (all-MiniLM-L6-v2).
    pub fn load_semantic_encoder(&mut self) -> Result<(), Box<dyn std::error::Error>>;

    /// Attaches a pre-built Sleipnir engine.
    pub fn with_sleipnir(self, sleipnir: Arc<SleipnirEngine>) -> Self;

    /// Loads the default Sleipnir engine from models/sleipnir.gguf.
    pub fn load_sleipnir_default(&mut self) -> Result<(), Box<dyn std::error::Error>>;

    /// Sets the Nott reflection engine.
    pub fn set_nott(&mut self, nott: Nott);

    /// Returns the current identity depth (Ollivier-Ricci curvature).
    pub async fn identity_depth(&self) -> Result<f64, MimirError>;

    /// Synchronizes ethical anchors from the topological manifold.
    pub async fn sync_identity_anchors(
        &mut self,
        memories: &[(MemoryId, DensityMemory)],
    ) -> Result<(), MimirError>;

    /// Performs recursive stabilization on the identity knot.
    pub async fn stabilize_identity(&mut self, alpha: f64) -> Result<(), MimirError>;

    /// Returns a reference to the event bus.
    pub fn bus(&self) -> &EventBus;
}

pub struct AgentConfig {
    pub agent_id: String,
    pub backend: String,
    pub ha_enabled: bool,
    pub contradiction_threshold: f32,
    pub coherence_threshold: f32,
    pub decay_rate: f64,
    pub target_metastability: f32,
    pub use_local_encoder: bool,
    pub manifold_dim: usize,
}

impl AgentConfig {
    /// Loads configuration from environment variables.
    pub fn load() -> Self;
}

impl Default for AgentConfig {
    fn default() -> Self { Self::load() }
}
```

## Usage Example

```rust
use mimirs_agent::{MimirAgent, AgentConfig};
use mimirs_store::Urdarbrunnr;
use mimirs_core::{MemoryInput, RecallQuery};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Open the storage well
    let well = Arc::new(Urdarbrunnr::opna("./my_well")?);

    // Create the agent with default config
    let config = AgentConfig::default();
    let mut agent = MimirAgent::new(well, config);

    // Load the semantic encoder (downloads all-MiniLM-L6-v2 on first call)
    agent.load_semantic_encoder()?;

    // Store a memory
    let input = MemoryInput::new("The capital of France is Paris.");
    let id = agent.store(input).await?;
    println!("Stored memory: {}", id);

    // Recall memories
    let query = RecallQuery::new("capital of France").with_limit(10);
    let results = agent.recall(query).await?;
    for res in &results {
        println!("Found: {} (overlap: {})", res.id, res.expected);
    }

    Ok(())
}
```

## Dependencies

This crate depends on all 14 other workspace crates:

- `mimirs-core`, `mimirs-density`, `mimirs-reservoir`, `mimirs-otoc`, `mimirs-encoding`, `mimirs-store`, `mimirs-forget`, `mimirs-oracle`, `mimirs-sleeptime`, `mimirs-ha`, `mimirs-yggdrasil`, `mimirs-identity`, `mimirs-embed`, `mimirs-bridge`

External dependencies: `tokio`, `async-trait`, `serde`, `serde_json`, `toml`, `config`, `uuid`, `chrono`, `thiserror`, `derive_builder`, `nalgebra`, `candle-core`, `tracing`, `tracing-subscriber`

## Known Limitations

- The `new()` constructor uses `unwrap()` when parsing the agent ID UUID. If `MIMIRS_AGENT_ID` is set to an invalid UUID string, the constructor will panic.
- The identity knot is initialized with a 128-dimensional density matrix, which is independent of the `manifold_dim` config (384 by default). This is intentional for the identity subsystem.
