Rust API

Reference for the cortexadb-core Rust crate.

CortexaDB (Facade)

The high-level API for interacting with the database.

Opening a Database

use cortexadb_core::CortexaDB;

// Simple open with default config
let db = CortexaDB::open("/path/to/db", 128)?;

// Builder pattern for advanced config
let db = CortexaDB::builder("/path/to/db", config).build()?;

Memory Operations

`remember(embedding, metadata) -> Result<u64>`

Stores a memory in the default namespace.

let id = db.remember(vec![0.1; 128], None)?;
let id = db.remember(vec![0.1; 128], Some(metadata_map))?;

`remember_in_namespace(ns, embedding, metadata) -> Result<u64>`

Stores a memory in a specific namespace.

let id = db.remember_in_namespace("agent_a", vec![0.1; 128], None)?;

`remember_with_content(ns, content, embedding, metadata) -> Result<u64>`

Stores a memory with raw content bytes.

let id = db.remember_with_content(
    "default",
    b"Hello world".to_vec(),
    vec![0.1; 128],
    None,
)?;

`ask(embedding, top_k, metadata_filter) -> Result<Vec<Hit>>`

Vector similarity search in the default namespace.

let hits = db.ask(vec![0.1; 128], 5, None)?;
for hit in &hits {
    println!("ID: {}, Score: {:.3}", hit.id, hit.score);
}

`ask_in_namespace(ns, embedding, top_k, filter) -> Result<Vec<Hit>>`

Namespace-scoped search.

let hits = db.ask_in_namespace("agent_a", vec![0.1; 128], 5, None)?;

`get_memory(id) -> Result<Memory>`

Retrieves a full memory entry by ID.

let mem = db.get_memory(42)?;
println!("{:?}", mem.metadata);

`delete_memory(id) -> Result<()>`

Deletes a memory and updates all indexes.

db.delete_memory(42)?;

Graph Operations

`connect(from_id, to_id, relation) -> Result<()>`

Creates a directed edge between two memories.

db.connect(1, 2, "relates_to")?;

`get_neighbors(id) -> Result<Vec<(u64, String)>>`

Returns outgoing edges from a memory.

let neighbors = db.get_neighbors(1)?;
for (target_id, relation) in &neighbors {
    println!("→ {} ({})", target_id, relation);
}

Maintenance

`compact() -> Result<()>`

Removes tombstoned entries from segment files.

`flush() -> Result<()>`

Forces fsync of all pending writes.

`checkpoint() -> Result<()>`

Creates a state snapshot and truncates the WAL.

`stats() -> Result<Stats>`

Returns database statistics.

let stats = db.stats()?;
println!("Entries: {}", stats.entries);
println!("Indexed: {}", stats.indexed_embeddings);

Types

`Hit`

pub struct Hit {
    pub id: u64,
    pub score: f32,
}

`Memory`

pub struct Memory {
    pub id: u64,
    pub content: Vec<u8>,
    pub namespace: String,
    pub embedding: Option<Vec<f32>>,
    pub metadata: HashMap<String, String>,
    pub created_at: u64,
    pub importance: f32,
}

`MemoryEntry`

Internal representation used by the storage engine.

pub struct MemoryEntry {
    pub id: MemoryId,
    pub namespace: String,
    pub content: Vec<u8>,
    pub embedding: Option<Vec<f32>>,
    pub metadata: HashMap<String, String>,
    pub created_at: u64,
    pub importance: f32,
}

`MemoryId`

pub struct MemoryId(pub u64);

`Stats`

pub struct Stats {
    pub entries: usize,
    pub indexed_embeddings: usize,
    pub wal_length: u64,
    pub vector_dimension: usize,
    pub storage_version: u32,
}

Configuration

`CortexaDBConfig`

pub struct CortexaDBConfig {
    pub vector_dimension: usize,
    pub sync_policy: SyncPolicy,
    pub checkpoint_policy: CheckpointPolicy,
    pub capacity_policy: CapacityPolicy,
    pub index_mode: IndexMode,
}

`SyncPolicy`

pub enum SyncPolicy {
    Strict,
    Batch { max_ops: usize, max_delay_ms: u64 },
    Async { interval_ms: u64 },
}

`CheckpointPolicy`

pub enum CheckpointPolicy {
    Disabled,
    Periodic { every_ops: usize, every_ms: u64 },
}

`CapacityPolicy`

pub struct CapacityPolicy {
    pub max_entries: Option<usize>,
    pub max_bytes: Option<u64>,
}

`IndexMode`

pub enum IndexMode {
    Exact,
    Hnsw(HnswConfig),
}

`HnswConfig`

pub struct HnswConfig {
    pub m: usize,              // default: 16
    pub ef_construction: usize, // default: 200
    pub ef_search: usize,      // default: 50
    pub metric: MetricKind,    // default: Cos
}

`MetricKind`

pub enum MetricKind {
    Cos,  // Cosine similarity
    L2,   // Euclidean distance
}

Errors

`CortexaDBError`

pub enum CortexaDBError {
    Store(CortexaDBStoreError),
    StateMachine(StateMachineError),
    Io(std::io::Error),
    MemoryNotFound(u64),
}

`CortexaDBStoreError`

pub enum CortexaDBStoreError {
    Engine(String),
    Vector(String),
    Query(String),
    Checkpoint(String),
    Wal(String),
    InvariantViolation(String),
    MissingEmbeddingOnContentChange,
}

Chunking

`chunk(text, strategy, chunk_size, overlap) -> Vec<ChunkResult>`

use cortexadb_core::chunker::{chunk, ChunkStrategy};

let results = chunk("Long text...", ChunkStrategy::Recursive, 512, 50);
for c in &results {
    println!("Chunk {}: {}", c.index, &c.text[..50]);
}

`ChunkStrategy`

pub enum ChunkStrategy {
    Fixed,
    Recursive,
    Semantic,
    Markdown,
    Json,
}

`ChunkResult`

pub struct ChunkResult {
    pub text: String,
    pub index: usize,
    pub metadata: Option<ChunkMetadata>,
}

Rust API

On this page