Expand description
§semantic-memory
Local-first semantic memory backed by authoritative SQLite state and an optional recoverable HNSW sidecar.
The crate stores facts, chunked documents, conversation messages, and searchable episodes in
SQLite. Search combines BM25 (FTS5) and vector retrieval with Reciprocal Rank Fusion, and
search_explained() returns the exact scoring breakdown from the live pipeline.
Concurrency uses one writer connection plus a pool of WAL-enabled reader connections. Durable writes are committed to SQLite first; any required HNSW sidecar mutations are journaled in SQLite and replayed on open, flush, rebuild, or reconcile.
search() targets facts, document chunks, and episodes by default. Message retrieval is
available through search_conversations() or by opting into
SearchSourceType::Messages.
Integrity tooling is strict about malformed stored data: invalid roles, JSON, enums, embedding
blobs, quantized blobs, and sidecar drift are surfaced through verify_integrity() instead of
being silently converted into defaults. reconcile() can rebuild FTS or fully re-embed and
rebuild derived state from SQLite.
store.graph_view() exposes a deterministic graph traversal layer over namespaces, facts,
documents, chunks, sessions, messages, episodes, and semantic/temporal/causal links derived
from SQLite state.
§Quick Start
use semantic_memory::{MemoryConfig, MemoryStore};
let store = MemoryStore::open(MemoryConfig::default())?;
// Store a fact
store.add_fact("general", "Rust was first released in 2015", None, None).await?;
// Search
let results = store.search("when was Rust released", None, None, None).await?;§Operational Notes
- SQLite is authoritative for all durable records and embeddings.
- HNSW is an acceleration sidecar. Pending sidecar mutations are journaled in SQLite, so a sidecar failure does not imply the SQLite write rolled back.
- WAL mode plus pooled reader connections allows concurrent reads while writes serialize through the writer connection.
search_explained()reflects the exact ranking math used by the active search pipeline, including reranking from exact f32 cosine similarity when configured.
Re-exports§
pub use evidence_gap::rerank_state_aware;pub use evidence_gap::EvidenceAblationReceiptV1;pub use evidence_gap::EvidenceGapOutcomeV1;pub use evidence_gap::EvidenceGapReasonV1;pub use evidence_gap::EvidenceGapRequestV1;pub use evidence_gap::EvidenceGapV1;pub use evidence_gap::EvidencePacketItemV1;pub use evidence_gap::EvidencePacketV1;pub use evidence_gap::EvidenceRetrievalRouteV1;pub use evidence_gap::EvidenceRouteReceiptV1;pub use evidence_gap::EvidenceTerminalOutcome;pub use evidence_gap::EvidenceTerminalOutcomeV1;pub use evidence_gap::StateRerankCandidateV1;pub use evidence_gap::StateRerankWeightsV1;pub use evidence_gap::EVIDENCE_GAP_V1;pub use evidence_gap::EVIDENCE_PACKET_V1;pub use evidence_gap::EVIDENCE_ROUTE_RECEIPT_V1;pub use authority_contracts::AuthorityAdmission;pub use authority_contracts::AuthorityFaultStage;pub use authority_contracts::AuthorityOperationKind;pub use authority_contracts::AuthorityPermit;pub use authority_contracts::AuthorityReceiptV1;pub use authority_contracts::AuthoritySnapshotId;pub use authority_contracts::AuthorityStateV1;pub use authority_contracts::CapabilityManifestV1;pub use authority_contracts::Confidence;pub use authority_contracts::CosineSimilarity;pub use authority_contracts::InjectionDecisionV1;pub use authority_contracts::InjectionDisposition;pub use authority_contracts::MemoryEnvelopeV1;pub use authority_contracts::NonNegativeWeight;pub use authority_contracts::Probability;pub use authority_contracts::RetrievalEpoch;pub use authority_contracts::RetrievalResponseV1;pub use authority_contracts::RetrievalWitnessV1;pub use authority_contracts::StageOutcomeV1;pub use authority_contracts::SupersessionReceiptV1;pub use origin_authority::evaluate_governed_access_v1;pub use origin_authority::AudienceV1;pub use origin_authority::AuthorityScopeV1;pub use origin_authority::AuthorityScopesV1;pub use origin_authority::CallerPrincipalV1;pub use origin_authority::DelegationElevationLeaseV1;pub use origin_authority::ElevationRequirementV1;pub use origin_authority::GovernedAccessPurposeV1;pub use origin_authority::GovernedAccessRequestV1;pub use origin_authority::GovernedFactAccessV1;pub use origin_authority::GovernedFactListResponseV1;pub use origin_authority::GovernedGraphResponseV1;pub use origin_authority::GovernedProjectionResponseV1;pub use origin_authority::GovernedReplayResponseV1;pub use origin_authority::GovernedSearchResponseV1;pub use origin_authority::GovernedStateResolutionResponseV1;pub use origin_authority::NamespaceScopeV1;pub use origin_authority::OriginAuthorityDecisionV1;pub use origin_authority::OriginAuthorityLabelV1;pub use origin_authority::OriginAuthorityRecordV1;pub use origin_authority::OriginClassV1;pub use origin_authority::OriginDerivationKindV1;pub use origin_authority::OriginRiskV1;pub use origin_authority::PolicyDecisionV1;pub use origin_authority::RevocationStatusV1;pub use origin_authority::SubjectPrincipalV1;pub use shadow_policy::compare_shadow_execution_v1;pub use shadow_policy::evaluate_shadow_policy_promotion_v1;pub use shadow_policy::shadow_policy_digest;pub use shadow_policy::ActiveShadowPolicyV1;pub use shadow_policy::PromotionDecisionReceiptV1;pub use shadow_policy::PromotionDispositionV1;pub use shadow_policy::PromotionEvidenceV1;pub use shadow_policy::PromotionGateDecisionV1;pub use shadow_policy::ShadowEvaluationWindowV1;pub use shadow_policy::ShadowExecutionComparisonV1;pub use shadow_policy::ShadowPolicyKindV1;pub use shadow_policy::ShadowPolicyPromotionPermitV1;pub use shadow_policy::ShadowPolicyProposalV1;pub use shadow_policy::ShadowPolicyProvenanceV1;pub use shadow_policy::ShadowPolicyRiskV1;pub use shadow_policy::ShadowPolicyStatusV1;pub use shadow_policy::PROMOTION_DECISION_RECEIPT_V1;pub use shadow_policy::SHADOW_POLICY_PROPOSAL_V1;pub use state_epistemics::answer_policy_for;pub use state_epistemics::resolve_dependency_states;pub use state_epistemics::AnswerDisposition;pub use state_epistemics::AnswerPolicy;pub use state_epistemics::AnswerPolicyDecision;pub use state_epistemics::BeliefAlternativeV1;pub use state_epistemics::DependencyResolutionV1;pub use state_epistemics::DependencyState;pub use state_epistemics::PremiseStatus;pub use state_epistemics::ResolvedAssertionV1;pub use state_epistemics::ResolvedMemoryAnswerV1;pub use state_epistemics::StateDependencyEdgeV1;pub use state_epistemics::StateResolutionMode;pub use state_epistemics::StateResolutionReceiptV1;pub use state_epistemics::StateResolvedRetrievalResponseV1;pub use state_epistemics::STATE_RESOLUTION_RECEIPT_V1;pub use state_epistemics::STATE_RESOLVED_RETRIEVAL_V1;pub use transition_contracts::ActiveHeadSimulationV1;pub use transition_contracts::AssertionDraftV1;pub use transition_contracts::DependencySimulationV1;pub use transition_contracts::MemoryTransitionCandidateV1;pub use transition_contracts::MemoryTransitionOutcomeV1;pub use transition_contracts::MemoryTransitionRecordV1;pub use transition_contracts::MemoryTransitionVerificationV1;pub use transition_contracts::OmittedSourceSpanV1;pub use transition_contracts::SourceArtifactV1;pub use transition_contracts::SourceSpanRefV1;pub use transition_contracts::SupersessionDraftV1;pub use transition_contracts::TransitionDisposition;pub use transition_contracts::TransitionOperation;pub use transition_contracts::UnsupportedAssertionSpanV1;pub use transition_contracts::VerificationScore;pub use config::ChunkingConfig;pub use config::ChunkingStrategy;pub use config::DerivedVectorBackendPolicy;pub use config::EmbeddingConfig;pub use config::MemoryConfig;pub use config::MemoryLimits;pub use config::PoolConfig;pub use config::SearchConfig;pub use embedder::BgeM3DeriveConfig;pub use embedder::BgeM3Embedder;pub use embedder::Embedder;pub use embedder::MockEmbedder;pub use embedder::MultiEmbedBatchFuture;pub use embedder::MultiEmbedFuture;pub use embedder::MultiFunctionEmbedder;pub use embedder::MultiFunctionEmbedding;pub use embedder::MultiVectorEmbedding;pub use embedder::OllamaEmbedder;pub use embedder::OptionalMultiEmbedBatchFuture;pub use embedder::OptionalMultiEmbedFuture;pub use embedder::SparseWeights;pub use error::MemoryError;pub use quantize::pack_quantized;pub use quantize::unpack_quantized;pub use quantize::QuantizedVector;pub use quantize::Quantizer;pub use storage::StoragePaths;pub use tokenizer::EstimateTokenCounter;pub use tokenizer::TokenCounter;pub use types::ChunkManifestChunkMapping;pub use types::ChunkManifestEntry;pub use types::ChunkManifestIngestOptions;pub use types::ChunkManifestIngestResult;pub use types::DerivedCandidateReceiptV1;pub use types::Document;pub use types::EmbeddingDisplacement;pub use types::EpisodeAsOfReceiptV1;pub use types::EpisodeMeta;pub use types::EpisodeOutcome;pub use types::ExactnessProfile;pub use types::ExplainedResult;pub use types::ExplainedResultAnswerV1;pub use types::ExplainedSearchResponse;pub use types::Fact;pub use types::GraphDirection;pub use types::GraphEdge;pub use types::GraphEdgeType;pub use types::GraphView;pub use types::MemoryStats;pub use types::Message;pub use types::NamespaceDeleteReport;pub use types::ProjectionClaimVersion;pub use types::ProjectionEntityAlias;pub use types::ProjectionEpisode;pub use types::ProjectionEvidenceRef;pub use types::ProjectionQuery;pub use types::ProjectionRelationVersion;pub use types::ProveKvPoolArtifactBuildReceiptV1;pub use types::ProveKvPoolArtifactStatusV1;pub use types::ProveKvPoolGenerationStatus;pub use types::ProveKvPoolGenerationV1;pub use types::ProveKvPoolItemMapEntryV1;pub use types::ReceiptMode;pub use types::ReplayMode;pub use types::Role;pub use types::ScoreBreakdown;pub use types::SearchContext;pub use types::SearchReceiptAnswersV1;pub use types::SearchReplayReportV1;pub use types::SearchResponse;pub use types::SearchResult;pub use types::SearchSource;pub use types::SearchSourceType;pub use types::Session;pub use types::SparseRankReceiptV1;pub use types::TextChunk;pub use types::VectorArtifactBuildReceiptV1;pub use types::VectorSearchReceiptV1;pub use types::VerificationStatus;pub use vector_backend::VectorBackend;pub use vector_backend::VectorHit;pub use vector_backend::VectorIndex;pub use vector_backend::VectorIndexConfig;pub use vector_codec::RawF32Codec;pub use vector_codec::Sq8Codec;pub use vector_codec::VectorArtifactV1;pub use vector_codec::VectorCodec;pub use vector_codec::VectorCodecProfileV1;pub use vector_snapshot::build_embedding_snapshot;pub use vector_snapshot::EmbeddingSnapshotRow;pub use vector_snapshot::EmbeddingSnapshotV1;
Modules§
- authority_
contracts - Versioned wire contracts for authority, witnessed retrieval, and injection governance.
- chunker
- Text chunking with multiple content-aware strategies.
- config
- embedder
- Embedding trait and implementations.
- error
- evidence_
gap - Bounded evidence-gap retrieval and state-aware reranking over existing authority/search paths. Bounded evidence-gap retrieval and state-aware reranking.
- hostile_
benchmark - Claim-bounded scoring and receipt invariants for the hostile memory benchmark. Claim-bounded receipt types and invariant scoring for the hostile memory benchmark.
- hubness
- Deterministic CPU-only hubness scoring over dense embedding collections.
- origin_
authority - Immutable origin-bound authority labels and governed access decisions. Immutable origin labels and laundering-resistant governed-access decisions.
- projection_
import - V10 legacy projection import boundary.
- quantize
- Scalar quantization (SQ8) for f32 → i8 vector compression.
- quantize_
governed - Governed compression pipeline integration for semantic-memory.
- reinstatement
- Contextual reinstatement scoring building blocks. Contextual reinstatement building blocks.
- search
- Hybrid search engine: BM25 + vector similarity + Reciprocal Rank Fusion.
- shadow_
policy - Shadow-learned policy proposals with deterministic promotion and rollback.
- state_
epistemics - Deterministic state-resolution and answer-disposition contracts.
- storage
- Storage path management for the memory directory convention.
- tokenizer
- Pluggable token counting for context budget management.
- transition_
contracts - Versioned contracts for deterministic, source-grounded memory transitions.
- types
- vector_
backend - Vector index backend trait.
- vector_
codec - Vector codec profile and artifact boundary.
- vector_
snapshot - Deterministic snapshots over authoritative SQLite f32 embeddings.
Structs§
- AddGraph
Edge Params - Parameters for creating a graph edge.
- Allowed
Procedure Tool V1 - Applicability
Predicate V1 - Forgetting
Closure Receipt V1 - Forgetting
Closure Request V1 - Forgetting
Epochs V1 - Forgetting
Surface RefV1 - Forgetting
Verification V1 - Governed
Procedure Decision V1 - Governed
Procedure Retrieval V1 - Integrity
Report - Result of an integrity verification.
- Memory
Authority - Memory
Store - Thread-safe handle to the memory database.
- Procedural
Memory Artifact V1 - Immutable procedure version. Lifecycle state is recorded separately as append-only events.
- Procedure
Action Permit V1 - Procedure
Action V1 - Procedure
Capability V1 - Procedure
Effect V1 - Procedure
Evidence Test Envelope V1 - Procedure
Fixture Receipt V1 - Procedure
Fixture V1 - Procedure
Lifecycle Permit V1 - Procedure
Lifecycle Receipt V1 - Procedure
Precondition V1 - Procedure
Retrieval Request V1 - Procedure
Revocation V1 - Procedure
Step V1 - Procedure
Test Receipt V1 - Procedure
Validation V1 - Projection
Import Failure Receipt Entry - Public view of a durable failed projection import receipt.
- Projection
Import LogEntry - Public view of a V11 projection import log entry.
- Projection
Import Result - Result of a projection batch import (V11+).
- Stored
Graph Edge - A stored graph edge row.
Enums§
- Applicability
Operator V1 - Forgetting
Disposition V1 - Procedure
Access Path V1 - Procedure
Lifecycle Disposition V1 - Procedure
Risk V1 - Reconcile
Action - Action to take when integrity issues are found.
- State
View - Authority state selected by a fact retrieval.
- Verify
Mode - How thorough the integrity check should be.
Constants§
- FORGETTING_
CLOSURE_ RECEIPT_ V1 - PROCEDURAL_
MEMORY_ ARTIFACT_ V1 - PROCEDURE_
LIFECYCLE_ RECEIPT_ V1 - PROCEDURE_
TEST_ RECEIPT_ V1
Functions§
- bytes_
to_ embedding - Decode a SQLite embedding BLOB back to f32 values.
- compress_
search_ results - SimpleMem-style semantic content compression for search results.
- decode_
f32_ le - Decode a stable little-endian f32 persisted representation.
- embedding_
to_ bytes - Encode an f32 slice as bytes for SQLite BLOB storage.
- validate_
procedure_ artifact_ v1 - Deterministically validate a procedure without storing or executing it.
- verify_
procedure_ lifecycle_ receipt_ v1 - Verify a witnessed lifecycle receipt and its embedded fixture receipt, when present.
- verify_
procedure_ test_ receipt_ v1 - Verify the content-addressed deterministic fixture-test receipt.