SDK Reference

The Hippocampus SDK is the primary Rust API for programmatic access to the local memory kernel. It wraps hippocampus-core and provides a clean interface for storing, retrieving, and reasoning over structured memory events.

Add to Your Project

[dependencies]
hippocampus-sdk = "0.1"

Quick Start

use hippocampus_sdk::{Hippocampus, HippocampusConfig, WriteRequest, SearchRequest, SdkEventType};

#[tokio::main]
async fn main() {
	let mem = Hippocampus::open(HippocampusConfig {
		db_path: "memory.db".into(),
		model_path: Some("./model.onnx".into()),
		..Default::default()
	}).unwrap();

	let event = mem.write(WriteRequest {
		event_type: SdkEventType::Decision,
		content: "Switched to JWT for authentication".into(),
		tags: vec!["auth".into(), "security".into()],
		importance: 0.9,
	}).await.unwrap();

	println!("stored: {}", event.id);

	let results = mem.search(SearchRequest {
		query: "auth".into(),
		tags: vec![],
		top_k: 5,
	}).unwrap();

	for r in &results {
		println!("[score={:.4}] {}", r.score.total, r.event.content);
	}
}

Configuration

Field	Type	Default	Description
db_path	PathBuf	"hippocampus.db"	Path to the SQLite database file
model_path	Option<PathBuf>	None	Path to the ONNX embedding model .onnx file
embedding_dim	usize	384	Dimensionality of the embedding vectors
recency_half_life_secs	f64	86400.0	Half-life in seconds for recency bias in search ranking

The model path can also be set via the CLI flag --model-path on first run; it is persisted in the database metadata and reused on subsequent runs.

API Reference

Hippocampus::open(config)

Opens a connection to the memory store and initializes the ONNX embedding model.

• Returns: Result<Hippocampus, SdkError>

Hippocampus::write(request)

Stores a new memory event. The event is written to SQLite immediately; its embedding is computed asynchronously in a background worker.

• Args: WriteRequest { event_type, content, tags, importance }
• Returns: Result<MemoryEvent, SdkError>

Hippocampus::search(request)

Retrieves memories using hybrid search with semantic similarity, keyword matching, recency, and importance.

• Args: SearchRequest { query, tags, top_k }
• Returns: Result<Vec<SearchResult>, SdkError>
• Ranking formula: 0.5 * semantic_similarity + 0.2 * keyword_match + 0.2 * recency_bias + 0.1 * importance

Hippocampus::recent(limit)

Returns the most recent events, ordered by timestamp descending.

• Args: limit: usize
• Returns: Result<Vec<MemoryEvent>, SdkError>

Hippocampus::tags(tag, limit)

Returns events tagged with a specific tag, ordered by timestamp descending.

• Args: tag: &str, limit: usize
• Returns: Result<Vec<MemoryEvent>, SdkError>

Hippocampus::reflect(question, top_k)

Performs a structured reflection over retrieved memories.

• Args: question: &str, top_k: usize
• Returns: Result<ReflectionOutput, SdkError>

Hippocampus::read(id)

Retrieves a single event by its UUID.

• Args: id: &str
• Returns: Result<Option<MemoryEvent>, SdkError>

Types

EventType

pub enum EventType {
	Observation,
	Decision,
	Action,
	Reflection,
}

Re-exported as SdkEventType at the crate root.

WriteRequest

pub struct WriteRequest {
	pub event_type: EventType,
	pub content: String,
	pub tags: Vec<String>,
	pub importance: f32,
}

SearchRequest

pub struct SearchRequest {
	pub query: String,
	pub tags: Vec<String>,
	pub top_k: usize,
}

Error Handling

All methods return Result<T, SdkError> where SdkError::Core(CoreError) wraps the core errors.

Common CoreError variants:

• ModelPathNotConfigured
• MissingModelPath(path)
• MissingTokenizerPath(path)
• Embedding(msg)
• Sqlite(err)

Async Behavior

• Writes are durable immediately before the function returns.
• Embeddings are computed asynchronously by a background Tokio task.
• Read, search, recent, tags, and reflect are synchronous and read from SQLite directly.