Struct AgentMemory 

pub struct AgentMemory { /* private fields */ }

High-level agent memory store built on a Kronroe temporal graph.

This is the primary entry point for AI agent developers. It wraps TemporalGraph with an API designed for agent use cases.

Implementations

impl AgentMemory

pub fn open(path: &str) -> Result<Self>

Open or create an agent memory store at the given path.

use kronroe_agent_memory::AgentMemory;
let memory = AgentMemory::open("./my-agent.kronroe").unwrap();

pub fn open_in_memory() -> Result<Self>

Create an in-memory agent memory store.

Useful for tests, WASM/browser bindings, and ephemeral workloads.

pub fn assert( &self, subject: &str, predicate: &str, object: impl Into<Value>, ) -> Result<FactId>

Store a structured fact with the current time as valid_from.

Use this when you already know the structure of the fact. For unstructured text, use remember() (Phase 1).

pub fn assert_idempotent( &self, idempotency_key: &str, subject: &str, predicate: &str, object: impl Into<Value>, ) -> Result<FactId>

Store a structured fact with idempotent retry semantics.

Reusing the same idempotency_key returns the original fact ID and avoids duplicate writes.

pub fn assert_idempotent_with_params( &self, idempotency_key: &str, subject: &str, predicate: &str, object: impl Into<Value>, params: AssertParams, ) -> Result<FactId>

Store a structured fact with idempotent retry semantics and explicit timing.

pub fn assert_with_params( &self, subject: &str, predicate: &str, object: impl Into<Value>, params: AssertParams, ) -> Result<FactId>

Store a structured fact with explicit parameters.

pub fn facts_about(&self, entity: &str) -> Result<Vec<Fact>>

Get all currently known facts about an entity (across all predicates).

pub fn facts_about_at( &self, entity: &str, predicate: &str, at: KronroeTimestamp, ) -> Result<Vec<Fact>>

Get what was known about an entity for a given predicate at a point in time.

pub fn current_facts(&self, entity: &str, predicate: &str) -> Result<Vec<Fact>>

Get currently valid facts for one (entity, predicate) pair.

pub fn what_changed( &self, entity: &str, since: KronroeTimestamp, predicate_filter: Option<&str>, ) -> Result<WhatChangedReport>

Return what changed for an entity since a given timestamp.

This is intentionally decision-oriented: it groups newly-recorded facts, recently invalidated facts, inferred correction pairs, and confidence shifts.

pub fn memory_health( &self, entity: &str, predicate_filter: Option<&str>, low_confidence_threshold: f32, stale_after_days: i64, ) -> Result<MemoryHealthReport>

Produce a health report for one entity’s memory state.

The report flags low-confidence active facts, stale high-impact facts, and contradiction counts (when contradiction support is enabled).

pub fn recall_for_task( &self, task: &str, subject: Option<&str>, now: Option<KronroeTimestamp>, horizon_days: Option<i64>, limit: usize, _query_embedding: Option<&[f32]>, ) -> Result<RecallForTaskReport>

Build task-focused recall output that is immediately useful for planning and execution-oriented workflows.

pub fn search(&self, query: &str, limit: usize) -> Result<Vec<Fact>>

Full-text search across known facts.

Delegates to core search functionality on the underlying temporal graph.

pub fn correct_fact( &self, fact_id: impl AsRef<str>, new_value: impl Into<Value>, ) -> Result<FactId>

Correct an existing fact by id, preserving temporal history.

pub fn invalidate_fact(&self, fact_id: impl AsRef<str>) -> Result<()>

Invalidate an existing fact by id, recording the current time as the transaction end.

pub fn remember( &self, text: &str, episode_id: &str, _embedding: Option<Vec<f32>>, ) -> Result<FactId>

Store an unstructured memory episode as one fact.

Subject is the episode_id, predicate is "memory", object is text.

pub fn remember_idempotent( &self, idempotency_key: &str, text: &str, episode_id: &str, ) -> Result<FactId>

Store an unstructured memory episode with idempotent retry semantics.

Reusing idempotency_key returns the same fact ID and avoids duplicates.

pub fn recall( &self, query: &str, query_embedding: Option<&[f32]>, limit: usize, ) -> Result<Vec<Fact>>

Retrieve memory facts by query.

Convenience wrapper over recall_scored that strips the score breakdowns. Use recall_scored when you need per-channel signal visibility.

pub fn recall_with_min_confidence( &self, query: &str, _query_embedding: Option<&[f32]>, limit: usize, min_confidence: f32, ) -> Result<Vec<Fact>>

Retrieve memory facts by query with an explicit minimum confidence threshold.

This shares the same filtering semantics as recall_scored_with_options, including confidence filtering before final result truncation.

use kronroe_agent_memory::AgentMemory;

let memory = AgentMemory::open("./agent.kronroe").unwrap();
memory.assert_with_confidence("alice", "works_at", "Acme", 0.95).unwrap();
memory.assert_with_confidence("alice", "worked_at", "Startup", 0.42).unwrap();

let facts = memory
    .recall_with_min_confidence("alice", None, 10, 0.9)
    .unwrap();
assert!(facts.iter().all(|f| f.confidence >= 0.9));

pub fn recall_scored( &self, query: &str, _query_embedding: Option<&[f32]>, limit: usize, ) -> Result<Vec<(Fact, RecallScore)>>

Retrieve memory facts by query with per-channel signal breakdowns.

Returns a (Fact, RecallScore) pair for each result. The result ordering is authoritative — the RecallScore explains per-channel contributions and fact confidence, not the final composite ranking score (see RecallScore docs for details).

• Hybrid path (with embedding): returns RecallScore::Hybrid with pre-rerank RRF channel contributions (text, vector) and fact confidence.
• Text-only path (no embedding): returns RecallScore::TextOnly with ordinal rank, BM25 relevance score, and fact confidence.

pub fn recall_scored_with_min_confidence( &self, query: &str, _query_embedding: Option<&[f32]>, limit: usize, min_confidence: f32, ) -> Result<Vec<(Fact, RecallScore)>>

Retrieve memory facts using scored recall plus confidence filtering.

Equivalent to recall_scored_with_options with only limit and min_confidence set, preserving the ordering and pagination semantics introduced by the options-based path.

use kronroe_agent_memory::AgentMemory;

let memory = AgentMemory::open("./agent.kronroe").unwrap();
memory.assert_with_confidence("alice", "works_at", "Acme", 0.95).unwrap();
memory.assert_with_confidence("alice", "visited", "London", 0.55).unwrap();

let scored = memory
    .recall_scored_with_min_confidence("alice", None, 1, 0.9)
    .unwrap();
assert_eq!(scored.len(), 1);
assert!(scored[0].1.confidence() >= 0.9);

pub fn assemble_context( &self, query: &str, query_embedding: Option<&[f32]>, max_tokens: usize, ) -> Result<String>

Build a token-bounded prompt context from recalled facts.

Internally uses scored recall so results are ordered by relevance. The output format includes a retrieval score tag for transparency:

[2024-06-01] (0.032) alice · works_at · Acme            ← hybrid, full confidence
[2024-06-01] (#1 bm25:4.21 conf:0.7) bob · lives_in · NYC  ← text-only, low confidence

query_embedding is used only when the hybrid feature is enabled. Without it, the embedding is ignored and fulltext search is used.

pub fn recall_scored_with_options( &self, opts: &RecallOptions<'_>, ) -> Result<Vec<(Fact, RecallScore)>>

Retrieve memory facts using RecallOptions, with per-channel signal breakdowns.

Like recall_scored but accepts a RecallOptions struct for cleaner parameter passing. When min_confidence is set, facts below the threshold are filtered from the results. Filtering occurs before truncating to the final limit, so low-confidence head matches cannot consume the result budget. By default, filtering uses base fact confidence; call [RecallOptions::with_min_effective_confidence] to use uncertainty-aware effective confidence instead.

pub fn recall_with_options(&self, opts: &RecallOptions<'_>) -> Result<Vec<Fact>>

Retrieve memory facts using RecallOptions.

Convenience wrapper over recall_scored_with_options that strips the score breakdowns.

pub fn assert_with_confidence( &self, subject: &str, predicate: &str, object: impl Into<Value>, confidence: f32, ) -> Result<FactId>

Store a structured fact with explicit confidence.

Like assert but allows setting the confidence score (clamped to [0.0, 1.0]).

pub fn assert_with_confidence_with_params( &self, subject: &str, predicate: &str, object: impl Into<Value>, params: AssertParams, confidence: f32, ) -> Result<FactId>

Store a structured fact with explicit confidence and explicit timing.

pub fn assert_with_source( &self, subject: &str, predicate: &str, object: impl Into<Value>, confidence: f32, source: &str, ) -> Result<FactId>

Store a structured fact with explicit source provenance.

Like assert but attaches a source marker (e.g. "user:owner", "api:linkedin") that the uncertainty engine uses for source-weighted confidence.

pub fn assert_with_source_with_params( &self, subject: &str, predicate: &str, object: impl Into<Value>, params: AssertParams, confidence: f32, source: &str, ) -> Result<FactId>

Store a structured fact with explicit source provenance and explicit timing.

pub fn effective_confidence_for_fact( &self, fact: &Fact, at: KronroeTimestamp, ) -> Result<Option<f32>>

Compute effective confidence for a fact at a point in time.

Returns Ok(Some(value)) when uncertainty support is enabled and Ok(None) when uncertainty support is disabled in this build.