Crate zeph_memory

Expand description

Semantic memory layer for the Zeph agent.

zeph-memory implements a two-backend hybrid memory system:

store::DbStore (SqliteStore) — relational persistence for messages, summaries, persona facts, trajectory entries, and session metadata.
embedding_store::EmbeddingStore — Qdrant-backed vector index for semantic recall. Falls back gracefully to db_vector_store::DbVectorStore when Qdrant is unavailable.

The high-level entry point is semantic::SemanticMemory, which combines both backends and exposes remember / recall / summarize operations consumed by zeph-core.

§Architecture overview

SemanticMemory
├── SqliteStore  ── messages, summaries, corrections, persona, trajectory …
└── EmbeddingStore ── Qdrant (primary) / DbVectorStore (fallback)
        └── QdrantOps  ── thin gRPC wrapper over qdrant-client

§Memory tiers

Messages are classified into four tiers (see types::MemoryTier):

Tier	Description
`Working`	Current context window; never persisted.
`Episodic`	Per-session messages stored in `SQLite`.
`Semantic`	Cross-session distilled facts promoted from episodic.
`Persona`	Long-lived user attributes (preferences, domain knowledge).

§Admission control

Each remember() call is gated by admission::AdmissionControl (A-MAC, #2317), which evaluates five factors (future utility, factual confidence, semantic novelty, temporal recency, content-type prior) and rejects low-value messages before they reach the DB.

§Memory routing

router::HybridRouter classifies each recall query and dispatches to the appropriate backend: keyword (SQLite FTS5), semantic (Qdrant), graph (BFS traversal), episodic (timestamp-filtered FTS5), or hybrid (reciprocal-rank fusion of keyword + semantic).

§Background loops

Several background tasks maintain memory health:

eviction::start_eviction_loop — Ebbinghaus-curve eviction.
forgetting::start_forgetting_loop — SleepGate importance downscaling.
consolidation::start_consolidation_loop — cross-session fact merging.
tiers::start_tier_promotion_loop — Episodic → Semantic promotion.
semantic::start_tree_consolidation_loop — hierarchical note consolidation.

§Feature flags

Feature	Description
`sqlite` (default)	Enable SQLite persistence via `zeph-db`.
`pdf`	Enable `PdfLoader` for PDF ingestion.
`postgres`	Enable PostgreSQL support via `zeph-db`.

Re-exports§

pub use admission::AdmissionControl;
pub use admission::AdmissionDecision;
pub use admission::AdmissionFactors;
pub use admission::AdmissionRejected;
pub use admission::AdmissionWeights;
pub use admission::GoalGateConfig;
pub use admission::compute_content_type_prior;
pub use admission::compute_factual_confidence;
pub use admission::log_admission_decision;
pub use anchored_summary::AnchoredSummary;
pub use compaction_probe::CategoryScore;
pub use compaction_probe::CompactionProbeConfig;
pub use compaction_probe::CompactionProbeResult;
pub use compaction_probe::ProbeCategory;
pub use compaction_probe::ProbeQuestion;
pub use compaction_probe::ProbeVerdict;
pub use compaction_probe::answer_probe_questions;
pub use compaction_probe::generate_probe_questions;
pub use compaction_probe::score_answers;
pub use compaction_probe::validate_compaction;
pub use compression_guidelines::CompressionGuidelinesConfig;
pub use compression_guidelines::build_guidelines_update_prompt;
pub use compression_guidelines::sanitize_guidelines;
pub use compression_guidelines::start_guidelines_updater;
pub use compression_guidelines::truncate_to_token_budget;
pub use compression_guidelines::update_guidelines_once;
pub use compression_predictor::CompressionFeatures;
pub use compression_predictor::CompressionModelWeights;
pub use compression_predictor::CompressionPredictor;
pub use consolidation::ConsolidationResult;
pub use consolidation::TopologyOp;
pub use consolidation::run_consolidation_sweep;
pub use consolidation::start_consolidation_loop;
pub use document::Chunk;
pub use document::Document;
pub use document::DocumentError;
pub use document::DocumentLoader;
pub use document::DocumentMetadata;
pub use document::IngestionPipeline;
pub use document::SplitterConfig;
pub use document::TextLoader;
pub use document::TextSplitter;
pub use embedding_registry::EmbedFuture;
pub use embedding_registry::Embeddable;
pub use embedding_registry::EmbeddingRegistry;
pub use embedding_registry::EmbeddingRegistryError;
pub use embedding_registry::SyncStats;
pub use embedding_store::ensure_qdrant_collection;
pub use error::MemoryError;
pub use eviction::EbbinghausPolicy;
pub use eviction::EvictionConfig;
pub use eviction::EvictionPolicy;
pub use eviction::start_eviction_loop;
pub use facade::CompactionContext;
pub use facade::CompactionResult;
pub use facade::InMemoryFacade;
pub use facade::MemoryEntry;
pub use facade::MemoryFacade;
pub use facade::MemoryMatch;
pub use facade::MemorySource;
pub use forgetting::ForgettingResult;
pub use forgetting::start_forgetting_loop;
pub use graph::EntityLockManager;
pub use graph::Community;
pub use graph::Edge;
pub use graph::EdgeType;
pub use graph::Entity;
pub use graph::EntityType;
pub use graph::GraphFact;
pub use graph::GraphStore;
pub use graph::RpeRouter;
pub use graph::RpeSignal;
pub use graph::extract_candidate_entities;
pub use qdrant_ops::QdrantOps;
pub use response_cache::ResponseCache;
pub use router::AsyncMemoryRouter;
pub use router::HeuristicRouter;
pub use router::HybridRouter;
pub use router::LlmRouter;
pub use router::MemoryRoute;
pub use router::MemoryRouter;
pub use router::RoutingDecision;
pub use router::TemporalRange;
pub use router::classify_graph_subgraph;
pub use router::parse_route_str;
pub use router::strip_temporal_keywords;
pub use scenes::MemScene;
pub use scenes::SceneConfig;
pub use scenes::consolidate_scenes;
pub use scenes::list_scenes;
pub use scenes::start_scene_consolidation_loop;
pub use semantic::BufferedWrite;
pub use semantic::EmbedContext;
pub use semantic::ExtractionResult;
pub use semantic::ExtractionStats;
pub use semantic::GraphExtractionConfig;
pub use semantic::LinkingStats;
pub use semantic::PersonaExtractionConfig;
pub use semantic::StructuredSummary;
pub use semantic::TrajectoryEntry;
pub use semantic::TrajectoryExtractionConfig;
pub use semantic::TreeConsolidationConfig;
pub use semantic::TreeConsolidationResult;
pub use semantic::WriteBuffer;
pub use semantic::build_summarization_prompt;
pub use semantic::contains_self_referential_language;
pub use semantic::extract_and_store;
pub use semantic::extract_persona_facts;
pub use semantic::extract_trajectory_entries;
pub use semantic::link_memory_notes;
pub use semantic::run_tree_consolidation_sweep;
pub use semantic::start_tree_consolidation_loop;
pub use snapshot::ImportStats;
pub use snapshot::MemorySnapshot;
pub use snapshot::export_snapshot;
pub use snapshot::import_snapshot;
pub use store::compression_guidelines::CompressionFailurePair;
pub use store::corrections::UserCorrectionRow;
pub use store::experiments::ExperimentResultRow;
pub use store::experiments::NewExperimentResult;
pub use store::experiments::SessionSummaryRow;
pub use store::memory_tree::MemoryTreeRow;
pub use store::persona::PersonaFactRow;
pub use store::session_digest::SessionDigest;
pub use store::trajectory::NewTrajectoryEntry;
pub use store::trajectory::TrajectoryEntryRow;
pub use tiers::TierPromotionConfig;
pub use tiers::start_tier_promotion_loop;
pub use token_counter::TokenCounter;
pub use types::ConversationId;
pub use types::MemSceneId;
pub use types::MemoryTier;
pub use types::MessageId;
pub use vector_store::FieldCondition;
pub use vector_store::FieldValue;
pub use vector_store::ScoredVectorPoint;
pub use vector_store::VectorFilter;
pub use vector_store::VectorPoint;
pub use vector_store::VectorStore;
pub use vector_store::VectorStoreError;

Modules§

admission: A-MAC adaptive memory admission control (#2317).
admission_rl: Lightweight logistic regression model for RL-based admission control (#2416).
anchored_summary: Structured compaction summary with anchored, typed sections.
compaction_probe: Compaction probe: validates summary quality before committing it to the context.
compression_guidelines: ACON failure-driven compression guidelines updater.
compression_predictor: Performance-floor compression ratio predictor (#2460).
consolidation: All-Mem lifelong memory consolidation (#2270).
db_vector_store: SQLite BLOB vector store — offline fallback implementation.
document
embedding_registry: Generic embedding registry backed by Qdrant.
embedding_store: Qdrant-backed embedding store for message vector search.
error
eviction: Memory eviction subsystem.
facade: Thin trait abstraction over crate::semantic::SemanticMemory.
forgetting: Forgetting sweep — SleepGate (#2397).
graph
in_memory_store: Purely in-memory VectorStore implementation for unit tests.
qdrant_ops: Low-level Qdrant operations shared across crates.
response_cache: SQLite-backed response cache with TTL expiry.
router: Memory routing — classify recall queries and dispatch to the right backend.
scenes: MemScene consolidation (#2332).
semantic: High-level semantic memory orchestrator.
snapshot: Memory snapshot export and import.
store: SQLite-backed relational store for all persistent agent data.
testing: Test helpers for zeph-memory.
tiers: AOI three-layer memory tier promotion.
token_counter
types: Core identifier and tier types used throughout zeph-memory.
vector_store: Abstract vector-store trait and associated types.

Structs§

BeliefRevisionConfig: Runtime config for Kumiho belief revision passed into resolver methods.
CancellationToken: A token which can be used to signal a cancellation request to one or more tasks.
ConsolidationConfig: Runtime config for the consolidation sweep loop.
ForgettingConfig: Runtime config for the forgetting sweep (#2397).
NoteLinkingConfig: Runtime config for A-MEM dynamic note linking.