Skip to main content

zeph_memory/
lib.rs

1// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Semantic memory layer for the Zeph agent.
5//!
6//! `zeph-memory` implements a two-backend hybrid memory system:
7//!
8//! - **[`store::SqliteStore`]** — relational persistence for messages, summaries,
9//!   persona facts, trajectory entries, and session metadata.
10//! - **[`embedding_store::EmbeddingStore`]** — Qdrant-backed vector index for semantic recall.
11//!   Falls back gracefully to [`db_vector_store::DbVectorStore`] when Qdrant is unavailable.
12//!
13//! The high-level entry point is [`semantic::SemanticMemory`], which combines both backends
14//! and exposes `remember` / `recall` / `summarize` operations consumed by `zeph-core`.
15//!
16//! # Architecture overview
17//!
18//! ```text
19//! SemanticMemory
20//! ├── SqliteStore  ── messages, summaries, corrections, persona, trajectory …
21//! └── EmbeddingStore ── Qdrant (primary) / DbVectorStore (fallback)
22//!         └── QdrantOps  ── thin gRPC wrapper over qdrant-client
23//! ```
24//!
25//! # Memory tiers
26//!
27//! Messages are classified into four tiers (see [`types::MemoryTier`]):
28//!
29//! | Tier | Description |
30//! |------|-------------|
31//! | `Working` | Current context window; never persisted. |
32//! | `Episodic` | Per-session messages stored in `SQLite`. |
33//! | `Semantic` | Cross-session distilled facts promoted from episodic. |
34//! | `Persona` | Long-lived user attributes (preferences, domain knowledge). |
35//!
36//! # Admission control
37//!
38//! Each `remember()` call is gated by [`admission::AdmissionControl`] (A-MAC, #2317), which
39//! evaluates five factors (future utility, factual confidence, semantic novelty, temporal
40//! recency, content-type prior) and rejects low-value messages before they reach the DB.
41//!
42//! # Memory routing
43//!
44//! [`router::HybridRouter`] classifies each recall query and dispatches to the appropriate
45//! backend: keyword (`SQLite` FTS5), semantic (Qdrant), graph (BFS traversal), episodic
46//! (timestamp-filtered FTS5), or hybrid (reciprocal-rank fusion of keyword + semantic).
47//!
48//! # Background loops
49//!
50//! Several background tasks maintain memory health:
51//!
52//! - [`eviction::start_eviction_loop`] — Ebbinghaus-curve eviction.
53//! - [`forgetting::start_forgetting_loop`] — `SleepGate` importance downscaling.
54//! - [`consolidation::start_consolidation_loop`] — cross-session fact merging.
55//! - [`tiers::start_tier_promotion_loop`] — Episodic → Semantic promotion.
56//! - [`semantic::start_tree_consolidation_loop`] — hierarchical note consolidation.
57//! - [`hebbian_consolidation::spawn_consolidation_loop`] — HL-F3/F4 cluster distillation.
58//! - [`episodic_consolidation::start_episodic_consolidation_loop`] — episodic → semantic fact extraction.
59//!
60//! # Feature flags
61//!
62//! | Feature | Description |
63//! |---------|-------------|
64//! | `sqlite` (default) | Enable SQLite persistence via `zeph-db`. |
65//! | `pdf` | Enable `PdfLoader` for PDF ingestion. |
66//! | `postgres` | Enable PostgreSQL support via `zeph-db`. |
67
68pub mod admission;
69pub mod anchored_summary;
70pub mod compaction_probe;
71pub mod compression;
72pub mod compression_guidelines;
73pub mod consolidation;
74pub mod document;
75pub mod episodic_consolidation;
76pub mod episodic_graph;
77pub mod facade;
78pub mod five_signal;
79pub mod forgetting;
80pub mod hebbian_consolidation;
81pub mod optical_forgetting;
82pub mod reasoning;
83pub mod recall_view;
84pub mod retrieval_failure_logger;
85pub mod scenes;
86mod sweep_helpers;
87pub mod tiered_retrieval;
88pub mod tiers;
89
90pub mod db_vector_store;
91pub mod embed_probe;
92pub mod embedding_registry;
93pub mod embedding_store;
94pub mod error;
95pub mod eviction;
96pub mod graph;
97pub mod in_memory_store;
98mod llm_judge;
99pub mod qdrant_ops;
100pub mod quality_gate;
101pub mod response_cache;
102pub mod router;
103pub mod semantic;
104pub mod shadow;
105pub mod snapshot;
106mod sqlite_time;
107pub mod store;
108#[cfg(any(test, feature = "testing"))]
109pub mod testing;
110pub mod token_counter;
111pub mod types;
112pub mod vector_store;
113
114pub use admission::{
115    AdmissionControl, AdmissionDecision, AdmissionFactors, AdmissionRejected, AdmissionWeights,
116    GoalGateConfig, compute_content_type_prior, compute_factual_confidence, log_admission_decision,
117};
118pub use anchored_summary::AnchoredSummary;
119pub use compaction_probe::{
120    CategoryScore, CompactionProbeResult, ProbeQuestion, ProbeVerdict, answer_probe_questions,
121    generate_probe_questions, score_answers, validate_compaction,
122};
123pub use compression::{
124    CompressionLevel, RetrievalPolicy,
125    promotion::{
126        PromotionCandidate, PromotionConfig, PromotionEngine, PromotionInput, SkillWriter,
127    },
128};
129pub use compression_guidelines::{
130    build_guidelines_update_prompt, sanitize_guidelines, start_guidelines_updater,
131    truncate_to_token_budget, update_guidelines_once,
132};
133pub use consolidation::{
134    ConsolidationConfig, ConsolidationResult, TopologyOp, run_consolidation_sweep,
135    start_consolidation_loop,
136};
137#[cfg(feature = "pdf")]
138pub use document::PdfLoader;
139pub use document::{
140    Chunk, Document, DocumentError, DocumentLoader, DocumentMetadata, IngestionPipeline,
141    SplitterConfig, TextLoader, TextSplitter,
142};
143pub use embed_probe::{ProbeError, probe_vector_size};
144pub use embedding_registry::{
145    EmbedFuture, Embeddable, EmbeddingRegistry, EmbeddingRegistryError, SyncStats,
146};
147pub use embedding_store::ensure_qdrant_collection;
148pub use episodic_consolidation::{
149    EpisodicConsolidationConfig, EpisodicConsolidationResult, run_episodic_consolidation_sweep,
150    start_episodic_consolidation_loop,
151};
152pub use episodic_graph::{
153    CausalLink, EmGraphConfig, EpisodicEvent, extract_events, fetch_recent_events, link_events,
154    recall_episodic_causal, store_events, store_links,
155};
156pub use error::MemoryError;
157pub use eviction::{EbbinghausPolicy, EvictionPolicy, start_eviction_loop};
158pub use facade::{
159    CompactionContext, CompactionResult, InMemoryFacade, MemoryEntry, MemoryFacade, MemoryMatch,
160    MemorySource,
161};
162pub use forgetting::{ForgettingConfig, ForgettingResult, start_forgetting_loop};
163pub use graph::EntityLockManager;
164pub use graph::experience::{EvolutionSweepStats, ExperienceStore};
165pub use graph::ingest::{
166    BatchIdResolution, ClaudeCodeJsonl, CodexJsonl, HubDegree, ImportBatchId, IngestDocument,
167    IngestFailure, IngestLedger, IngestProgress, IngestReport, IngestSourceAdapter,
168    IngestSourceKind, LedgerEntry, SubagentJsonl, TranscriptEntry,
169};
170pub use graph::{
171    BeliefMemConfig, BeliefRevisionConfig, BeliefStore, Community, Edge, EdgeType, Entity,
172    EntityType, GraphFact, GraphOrigin, GraphProvenance, GraphStore, PendingBelief, RpeRouter,
173    RpeSignal, extract_candidate_entities, noisy_or, time_decayed_prob,
174};
175pub use hebbian_consolidation::{
176    GraphRule, HebbianConsolidationCandidate, HebbianConsolidationOutcome,
177    run_consolidation_sweep as run_hebbian_consolidation_sweep,
178    spawn_consolidation_loop as spawn_hebbian_consolidation_loop,
179};
180pub use optical_forgetting::{
181    ContentFidelity, OpticalForgettingConfig, OpticalForgettingResult,
182    run_optical_forgetting_sweep, start_optical_forgetting_loop,
183};
184pub use qdrant_ops::QdrantOps;
185pub use reasoning::{
186    Outcome, ProcessTurnConfig, ReasoningMemory, ReasoningStrategy, SelfJudgeOutcome,
187    distill_strategy, process_turn as process_reasoning_turn, run_self_judge,
188};
189pub use recall_view::{RecallView, RecalledFact};
190pub use response_cache::ResponseCache;
191pub use retrieval_failure_logger::RetrievalFailureLogger;
192pub use router::{
193    AsyncMemoryRouter, HeuristicRouter, HybridRouter, LlmRouter, MemoryRoute, MemoryRouter,
194    RoutingDecision, TemporalRange, classify_graph_subgraph, parse_route_str,
195    strip_temporal_keywords,
196};
197pub use scenes::{
198    MemScene, SceneConfig, consolidate_scenes, list_scenes, start_scene_consolidation_loop,
199};
200pub use semantic::{
201    EmbedContext, ExtractionResult, ExtractionStats, GraphExtractionConfig, HebbianReinforcement,
202    HelaSpreadRuntime, ImportanceScoring, IngestBatchConfig, LinkingStats, MmrReranking,
203    NoteLinkingConfig, PersonaExtractionConfig, QueryBiasCorrection, RecalledMessage,
204    SharedPostExtractValidator, StructuredSummary, TemporalDecay, TrajectoryEntry,
205    TrajectoryExtractionConfig, TreeConsolidationConfig, TreeConsolidationResult,
206    build_summarization_prompt, contains_self_referential_language, extract_and_store,
207    extract_persona_facts, extract_trajectory_entries, link_memory_notes,
208    run_tree_consolidation_sweep, start_tree_consolidation_loop,
209};
210pub use snapshot::{ImportStats, MemorySnapshot, export_snapshot, import_snapshot};
211pub use store::agent_sessions::{AgentSessionRow, SessionChannel, SessionKind, SessionStatus};
212pub use store::compression_guidelines::CompressionFailurePair;
213pub use store::corrections::UserCorrectionRow;
214pub use store::experiments::{ExperimentResultRow, NewExperimentResult, SessionSummaryRow};
215pub use store::memory_tree::MemoryTreeRow;
216pub use store::persona::PersonaFactRow;
217pub use store::retrieval_failures::{RetrievalFailureRecord, RetrievalFailureType};
218pub use store::session_digest::SessionDigest;
219pub use store::trajectory::{NewTrajectoryEntry, TrajectoryEntryRow};
220pub use tiered_retrieval::{
221    IntentClass, TieredRetrievalConfig, TieredRetrievalResult, recall_tiered,
222};
223pub use tiers::{TierPromotionConfig, start_tier_promotion_loop};
224pub use token_counter::TokenCounter;
225pub use tokio_util::sync::CancellationToken;
226pub use types::{ConversationId, EntityId, ExperienceId, MemSceneId, MemoryTier, MessageId};
227pub use vector_store::{
228    FieldCondition, FieldValue, ScoredVectorPoint, VectorFilter, VectorPoint, VectorStore,
229    VectorStoreError,
230};
231pub use zeph_common::config::memory::HebbianConsolidationConfig;
232pub use zeph_common::memory::TokenCounting;
233pub use zeph_config::memory::CompressionGuidelinesConfig;
234pub use zeph_config::memory::EvictionConfig;
235pub use zeph_config::memory::{CompactionProbeConfig, ProbeCategory};