Rust API Reference

[dependencies]
agentic-memory = "0.2"

impl CognitiveGraph {
    /// Creates a new, empty cognitive graph.
    pub fn new() -> Self;
}

use agentic_memory::CognitiveGraph;

let mut graph = CognitiveGraph::new();

pub fn add_node(
    &mut self,
    event_type: EventType,
    content: &str,
    session: u32,
    confidence: f32,
    metadata: Option<HashMap<String, String>>,
) -> NodeId;

use agentic_memory::{CognitiveGraph, EventType};

let mut graph = CognitiveGraph::new();
let fact_id = graph.add_node(
    EventType::Fact,
    "Rust 1.75 introduces async fn in traits",
    1,      // session
    0.95,   // confidence
    None,
);

pub fn add_edge(
    &mut self,
    source: NodeId,
    target: NodeId,
    edge_type: EdgeType,
    weight: f32,
) -> Result<EdgeId, GraphError>;

use agentic_memory::EdgeType;

let decision_id = graph.add_node(EventType::Decision, "Adopt async traits", 1, 0.9, None);
graph.add_edge(decision_id, fact_id, EdgeType::Supports, 0.85)?;

pub fn node(&self, id: NodeId) -> Option<&CognitiveNode>;

pub fn neighbors(
    &self,
    id: NodeId,
    direction: Direction,
) -> Vec<(NodeId, &CognitiveEdge)>;

pub fn traverse(
    &self,
    start: NodeId,
    max_depth: usize,
    edge_filter: Option<&[EdgeType]>,
) -> TraversalResult;

pub fn node_count(&self) -> usize;
pub fn edge_count(&self) -> usize;

pub fn nodes_by_type(&self, event_type: EventType) -> Vec<NodeId>;

pub fn nodes_by_session(&self, session: u32) -> Vec<NodeId>;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum EventType {
    Fact,
    Decision,
    Inference,
    Correction,
    Skill,
    Episode,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum EdgeType {
    CausedBy,
    Supports,
    Contradicts,
    Supersedes,
    RelatedTo,
    PartOf,
    TemporalNext,
}

pub struct CognitiveNode {
    pub id: NodeId,
    pub event_type: EventType,
    pub content: String,
    pub session: u32,
    pub confidence: f32,
    pub timestamp: i64,                          // Unix timestamp (seconds)
    pub metadata: HashMap<String, String>,
    pub vector: Option<Vec<f32>>,                // 128-dim feature vector
}

pub struct CognitiveEdge {
    pub source: NodeId,
    pub target: NodeId,
    pub edge_type: EdgeType,
    pub weight: f32,
}

pub struct TraversalResult {
    pub nodes: Vec<NodeId>,
    pub edges: Vec<(NodeId, NodeId, EdgeType)>,
    pub depth_reached: usize,
}

pub enum Direction {
    Outgoing,
    Incoming,
    Both,
}

#[derive(Debug, thiserror::Error)]
pub enum GraphError {
    #[error("node {0} not found")]
    NodeNotFound(NodeId),
    #[error("invalid edge: {0}")]
    InvalidEdge(String),
    #[error("I/O error: {0}")]
    Io(#[from] std::io::Error),
    #[error("format error: {0}")]
    Format(String),
}

use agentic_memory::io::FileWriter;

impl FileWriter {
    /// Writes the graph to the specified file path.
    /// Creates the file if it does not exist; overwrites if it does.
    pub fn write(graph: &CognitiveGraph, path: &Path) -> Result<(), GraphError>;
}

use agentic_memory::io::FileWriter;
use std::path::Path;

FileWriter::write(&graph, Path::new("agent.amem"))?;

use agentic_memory::io::FileReader;

impl FileReader {
    /// Reads a .amem file and returns the full graph.
    pub fn read(path: &Path) -> Result<CognitiveGraph, GraphError>;
}

use agentic_memory::io::FileReader;
use std::path::Path;

let graph = FileReader::read(Path::new("agent.amem"))?;
println!("Loaded {} nodes", graph.node_count());

use agentic_memory::io::MmapReader;

impl MmapReader {
    /// Opens a .amem file with memory-mapped I/O.
    pub fn open(path: &Path) -> Result<Self, GraphError>;

    /// Returns a reference to the node with the given ID.
    pub fn node(&self, id: NodeId) -> Option<CognitiveNodeRef<'_>>;

    /// Returns the total number of nodes.
    pub fn node_count(&self) -> usize;

    /// Returns the total number of edges.
    pub fn edge_count(&self) -> usize;

    /// Returns edges for a given node.
    pub fn edges(&self, id: NodeId, direction: Direction) -> Vec<CognitiveEdgeRef<'_>>;
}

use agentic_memory::io::MmapReader;
use std::path::Path;

let reader = MmapReader::open(Path::new("large_brain.amem"))?;
if let Some(node) = reader.node(NodeId(42)) {
    println!("Node 42: {}", node.content());
}

use agentic_memory::query::QueryEngine;

impl QueryEngine {
    /// Creates a query engine from an in-memory graph.
    pub fn from_graph(graph: &CognitiveGraph) -> Self;

    /// Creates a query engine from a memory-mapped reader.
    pub fn from_mmap(reader: &MmapReader) -> Self;

    /// Returns all node IDs of the given event type.
    pub fn by_type(&self, event_type: EventType) -> Vec<NodeId>;

    /// Returns all node IDs in the given session.
    pub fn by_session(&self, session: u32) -> Vec<NodeId>;

    /// Performs a BFS traversal from the starting node.
    pub fn traverse(
        &self,
        start: NodeId,
        max_depth: usize,
        edge_filter: Option<&[EdgeType]>,
    ) -> TraversalResult;

    /// Finds the top-k most similar nodes to the given query vector.
    pub fn similarity_search(
        &self,
        query_vector: &[f32; 128],
        top_k: usize,
    ) -> Vec<(NodeId, f32)>;
}

use agentic_memory::query::QueryEngine;

let engine = QueryEngine::from_graph(&graph);

// Find all facts
let facts = engine.by_type(EventType::Fact);

// Similarity search
let results = engine.similarity_search(&query_vec, 10);
for (node_id, score) in results {
    println!("Node {}: score {:.3}", node_id.0, score);
}

pub fn search_text(&self, query: &str, top_k: usize) -> Vec<TextMatch>;

pub fn search_hybrid(
    &self,
    query: &str,
    query_vector: &[f32; 128],
    top_k: usize,
    alpha: f32,
) -> Vec<HybridMatch>;

pub fn centrality(&self, metric: CentralityMetric) -> Vec<(NodeId, f64)>;

pub fn shortest_path(
    &self,
    src: NodeId,
    dst: NodeId,
    algorithm: PathAlgorithm,
) -> Option<PathResult>;

pub fn revise(&self, node_id: NodeId) -> RevisionReport;

pub fn gaps(&self) -> GapReport;

pub fn analogy(&self, node_id: NodeId, top_k: usize) -> Vec<Analogy>;

pub fn consolidate(&self, dry_run: bool) -> ConsolidationReport;

pub fn drift(&self) -> DriftReport;

amem create <PATH>

amem create project.amem

amem add <PATH> <TYPE> <CONTENT> [OPTIONS]

amem add project.amem fact "Rust 1.75 supports async traits" --confidence 0.95 --meta source=docs

amem link <PATH> <SOURCE> <TARGET> <TYPE> [OPTIONS]

amem link project.amem 0 1 supports --weight 0.9

amem info <PATH> [OPTIONS]

amem info project.amem --sessions

amem traverse <PATH> <START_ID> [OPTIONS]

amem traverse project.amem 0 --depth 5 --edge-type supports --edge-type caused_by

amem query <PATH> [OPTIONS]

amem query project.amem --event-types fact --min-confidence 0.8
amem query project.amem --search "database performance" --top-k 5

amem mcp-serve <PATH> [OPTIONS]

amem mcp-serve project.amem --port 3100

amem text-search <PATH> <QUERY> [--top-k <INT>]

amem hybrid-search <PATH> <QUERY> [--top-k <INT>] [--alpha <FLOAT>]

amem centrality <PATH> --metric <pagerank|degree|betweenness> [--top-k <INT>] [--json]

amem path <PATH> <SRC_ID> <DST_ID> [--algorithm <bfs|dijkstra>] [--json]

amem revise <PATH> <NODE_ID> [--json]

amem gaps <PATH> [--json]

amem analogy <PATH> <NODE_ID> [--top-k <INT>] [--json]

amem consolidate <PATH> [--dry-run] [--json]

amem drift <PATH> [--json]