Skip to main content

Crate pulsedb

Crate pulsedb 

Source
Expand description

§PulseDB

Distributed database for agentic AI systems - collective memory for multi-agent coordination.

PulseDB provides persistent storage for AI agent experiences, enabling semantic search, context retrieval, and knowledge sharing between agents. Supports native sync between instances for multi-device and client-server deployments.

§Quick Start

use pulsedb::{PulseDB, Config, NewExperience};

// Open or create a database
let db = PulseDB::open(dir.path().join("test.db"), Config::default())?;

// Create a collective (isolated namespace)
let collective = db.create_collective("my-project")?;

// Record an experience
db.record_experience(NewExperience {
    collective_id: collective,
    content: "Always validate user input before processing".to_string(),
    importance: 0.8,
    embedding: Some(vec![0.1f32; 384]),
    ..Default::default()
})?;

// Search for relevant experiences
let query_embedding = vec![0.1f32; 384];
let results = db.search_similar(collective, &query_embedding, 10)?;

// Clean up
db.close()?;

§Key Concepts

§Collective

A collective is an isolated namespace for experiences, typically one per project. Each collective has its own vector index and can have different embedding dimensions.

§Experience

An experience is a unit of learned knowledge. It contains:

  • Content (text description of the experience)
  • Embedding (vector representation for semantic search)
  • Metadata (type, importance, confidence, tags)

§Embedding Providers

PulseDB supports two modes for embeddings:

  • External (default): You provide pre-computed embeddings from your own service (OpenAI, Cohere, etc.)
  • Builtin: PulseDB generates embeddings using a bundled ONNX model (requires builtin-embeddings feature)

§Distributed Sync

With the sync feature, PulseDB instances can synchronize data across a network. See the sync module for full documentation.

Key components:

  • SyncManager — Orchestrates sync lifecycle (start/stop/sync_once)
  • SyncTransport — Pluggable transport trait (HTTP, in-memory, custom)
  • SyncServer — Server-side handler for Axum consumers (sync-http)
  • PulseDB::compact_wal() — WAL compaction for disk space reclamation

§Thread Safety

PulseDB is Send + Sync and can be shared across threads using Arc. The database uses MVCC for concurrent reads with exclusive write locking.

§Feature Flags

FeatureDescription
builtin-embeddingsBundles ONNX runtime with all-MiniLM-L6-v2 for local embedding generation. Without this feature, you must supply pre-computed embeddings.
syncCore sync protocol: types, transport trait, in-memory transport, echo prevention guard.
sync-httpHTTP sync transport via reqwest (implies sync).
sync-websocketWebSocket sync transport via tokio-tungstenite (implies sync).

Re-exports§

pub use substrate::PulseDBSubstrate;
pub use substrate::SubstrateProvider;
pub use storage::DatabaseMetadata;

Modules§

embedding
Embedding service abstractions for PulseDB.
prelude
Convenient imports for common PulseDB usage.
storage
Storage layer abstractions for PulseDB.
substrate
SubstrateProvider async trait for agent framework integration. Async storage trait for integrating PulseDB with agent frameworks.
syncsync
Native sync protocol for distributed PulseDB instances.
vector
Vector index module for HNSW-based approximate nearest neighbor search. Vector index abstractions for semantic search.

Structs§

Activity
A stored agent activity — presence record within a collective.
ActivityConfig
Configuration for agent activity tracking.
AgentId
Agent identifier.
ChangePoller
Cross-process change poller.
Collective
A collective — an isolated namespace for agent experiences.
CollectiveId
Collective identifier (UUID v7 for time-ordering).
CollectiveStats
Statistics for a collective.
Config
Database configuration options.
ContextCandidates
Aggregated context candidates from all retrieval primitives.
ContextRequest
Request for unified context retrieval.
DerivedInsight
A stored derived insight — synthesized knowledge from multiple experiences.
Experience
A stored experience — the core data type in PulseDB.
ExperienceId
Experience identifier (UUID v7 for time-ordering).
ExperienceRelation
A stored relationship between two experiences.
ExperienceUpdate
Partial update for an experience’s mutable fields.
HnswConfig
Configuration for the HNSW vector index.
InsightId
Insight identifier (UUID v7 for time-ordering).
NewActivity
Input for registering a new agent activity.
NewDerivedInsight
Input for creating a new derived insight.
NewExperience
Input for creating a new experience via PulseDB::record_experience().
NewExperienceRelation
Input for creating a new relation between two experiences.
PulseDB
The main PulseDB database handle.
RelationId
Relation identifier (UUID v7 for time-ordering).
SearchFilter
Filter criteria for experience search operations.
SearchResult
A search result pairing an experience with its similarity score.
TaskId
Task identifier.
Timestamp
Unix timestamp in milliseconds.
UserId
Opaque user identifier.
WatchConfig
Configuration for the watch system (in-process and cross-process).
WatchEvent
An event emitted when an experience changes.
WatchFilter
Filter for narrowing which watch events a subscriber receives.
WatchLock
Advisory file lock for cross-process watch coordination.
WatchStream
A stream of WatchEvent values backed by a crossbeam channel.

Enums§

EmbeddingDimension
Embedding vector dimensions.
EmbeddingProvider
Embedding provider configuration.
ExperienceType
Rich experience type with associated data per variant.
InsightType
Type of derived insight.
NotFoundError
Not found errors for specific entity types.
PulseDBError
Top-level error enum for all PulseDB operations.
RelationDirection
Direction for querying relations from a given experience.
RelationType
Type of relationship between two experiences.
Severity
Severity level for difficulty experiences.
StorageError
Storage-related errors.
SyncMode
Durability mode for write operations.
ValidationError
Validation errors for input data.
WatchEventType
The kind of change that triggered a WatchEvent.

Type Aliases§

Embedding
Embedding vector type alias.
Result
Result type alias for PulseDB operations.