Crate vipune 

vipune - A minimal memory layer for AI agents.

This crate provides a local, semantic memory store with conflict detection. All operations are synchronous (no async/await required).

Example

use vipune::{Config, MemoryStore, MemoryType, MemoryStatus, detect_project};

// Initialize memory store
let config = Config::default();
let mut store = MemoryStore::new(
    config.database_path.as_path(),
    &config.embedding_model,
    config.clone()
).expect("Failed to initialize store");

// Detect project ID
let project_id = detect_project(None);

// Add a memory with conflict detection
let result = store.add_with_conflict(&project_id, "Alice works at Microsoft", None, false, MemoryType::Fact, MemoryStatus::Active);
match result {
    Ok(vipune::AddResult::Added { id }) => println!("Added memory: {}", id),
    Ok(vipune::AddResult::Conflicts { .. }) => println!("Conflict detected"),
    Err(e) => eprintln!("Error: {}", e),
}

// Search memories
let results = store.search(&project_id, "where does alice work", 10, 0.0, vipune::memory::SearchOptions::default());
for memory in results.unwrap() {
    println!("{:.2}: {}", memory.similarity.unwrap_or(0.0), memory.content);
}

Mutability Requirements

Methods that generate embeddings (add, search, update) require &mut self because the embedding engine internally mutates state for ONNX tensor allocations.

Direct embedding (library)

EmbeddingEngine is also available for callers that embed directly (bypassing MemoryStore). It is prefix-aware: use embed_passage for stored text and embed_query for search/classification text — the engine prepends the model profile’s prefix (e5: "query: " / "passage: "; bge: none) before tokenisation, and the 512-token limit is enforced on the prefixed text. The engine performs no database model-identity check; if you keep vector caches outside vipune, key them by vipune::current_identity’s ModelIdentity (model id + revision) so a model switch invalidates them.

Re-exports

pub use config::Config;

pub use embedding::EMBED_MODEL_ID;

pub use embedding::EMBED_MODEL_REVISION;

pub use embedding::EMBEDDING_DIMS;

pub use embedding::EmbeddingEngine;

pub use embedding_profiles::BUILTIN_PROFILES;

pub use embedding_profiles::EmbeddingRole;

pub use embedding_profiles::ModelProfile;

pub use embedding_profiles::profile_for;

pub use errors::Error;

pub use memory::lifecycle::MemoryImportance;

pub use memory::lifecycle::MemoryStatus;

pub use memory::lifecycle::MemoryType;

pub use memory::MemoryStore;

pub use memory::NewMemory;

pub use memory::NewSupersedingMemory;

pub use memory::UpdateParams;

pub use memory_types::AddResult;

pub use memory_types::BatchIngestItemResult;

pub use memory_types::BatchIngestResult;

pub use memory_types::ConflictMemory;

pub use memory_types::IngestPolicy;

pub use migration::migrate_model;

pub use project::detect_project;

pub use project::detect_project_at;

Modules

config

Configuration system for vipune.

embedding

Synchronous ONNX embedding engine for text-to-vector conversion.

embedding_profiles

Built-in embedding model profiles.

errors

Error types for vipune.

mcp

MCP (Model Context Protocol) server for vipune.

memory

Core memory store orchestrating embedding and SQLite operations.

memory_types

Memory store data types.

migration

Library-level model-switch migration (issue #221).

project

Project auto-detection from git repository.

Structs

Database

SQLite database backend for vipune.

Memory

A single memory record with metadata, embedding vector, and optional similarity score.

MigrationReport

The result of a completed model migration pass.

MigrationRowFailure

A single row whose re-embedding failed during a migration pass.

ModelIdentity

Model identity tracking (issue #217): the recorded (model id, revision) pair a database’s vectors were produced with, plus the mismatch / in-flight-migration refusal shared by the embedding chokepoints. Model identity tracking (issue #217): the recorded (model id, revision) pair a database’s vectors were produced with, plus the mismatch / in-flight-migration refusal shared by the embedding chokepoints. Model identity tracking (issue #217): the recorded (model id, revision) pair a database’s vectors were produced with, plus the mismatch / in-flight-migration refusal shared by the embedding chokepoints. The (model id, pinned revision) pair a database’s vectors were produced with, or that a migration is switching to.

Enums

EmbeddingClass

Classification of an embedding vector based on its L2 norm.

Constants

MAX_INPUT_LENGTH

Maximum allowed input length (100,000 characters).

MAX_SEARCH_LIMIT

Maximum allowed limit for search operations.

Functions

assert_identity_ok

Model identity tracking (issue #217): the recorded (model id, revision) pair a database’s vectors were produced with, plus the mismatch / in-flight-migration refusal shared by the embedding chokepoints. Model identity tracking (issue #217): the recorded (model id, revision) pair a database’s vectors were produced with, plus the mismatch / in-flight-migration refusal shared by the embedding chokepoints. Model identity tracking (issue #217): the recorded (model id, revision) pair a database’s vectors were produced with, plus the mismatch / in-flight-migration refusal shared by the embedding chokepoints. Mismatch / in-flight-migration refusal for the embedding chokepoints (issue #217: add, update, search, hook inserts, and anything else that embeds).

classify_embedding

Classify an embedding vector by computing its L2 norm.

current_identity

Model identity tracking (issue #217): the recorded (model id, revision) pair a database’s vectors were produced with, plus the mismatch / in-flight-migration refusal shared by the embedding chokepoints. Model identity tracking (issue #217): the recorded (model id, revision) pair a database’s vectors were produced with, plus the mismatch / in-flight-migration refusal shared by the embedding chokepoints. Model identity tracking (issue #217): the recorded (model id, revision) pair a database’s vectors were produced with, plus the mismatch / in-flight-migration refusal shared by the embedding chokepoints. The identity the store currently has: the recorded identity, or the bge default when no row (or only a marker-only row) is recorded.

is_migrating

Model identity tracking (issue #217): the recorded (model id, revision) pair a database’s vectors were produced with, plus the mismatch / in-flight-migration refusal shared by the embedding chokepoints. Model identity tracking (issue #217): the recorded (model id, revision) pair a database’s vectors were produced with, plus the mismatch / in-flight-migration refusal shared by the embedding chokepoints. Model identity tracking (issue #217): the recorded (model id, revision) pair a database’s vectors were produced with, plus the mismatch / in-flight-migration refusal shared by the embedding chokepoints. True while a migration marker is present (an interrupted reindex --force).

read_identity

Model identity tracking (issue #217): the recorded (model id, revision) pair a database’s vectors were produced with, plus the mismatch / in-flight-migration refusal shared by the embedding chokepoints. Model identity tracking (issue #217): the recorded (model id, revision) pair a database’s vectors were produced with, plus the mismatch / in-flight-migration refusal shared by the embedding chokepoints. Model identity tracking (issue #217): the recorded (model id, revision) pair a database’s vectors were produced with, plus the mismatch / in-flight-migration refusal shared by the embedding chokepoints. Read the recorded identity, if any.