mentedb_cognitive/lib.rs
1//! # mentedb-cognitive: Cognitive Engine for MenteDB
2//!
3//! This crate implements the seven cognitive features that distinguish MenteDB
4//! from a conventional vector database. These features run at write time and
5//! read time, giving the engine awareness of the knowledge it holds.
6//!
7//! ## Modules
8//!
9//! - [`interference`]: Detects pairs of memories similar enough to confuse an LLM,
10//! generates disambiguation text, and reorders context to maximize separation.
11//!
12//! - [`pain`]: Records negative experiences (failed actions, user corrections) as
13//! pain signals with intensity and decay. Surfaces warnings during context assembly.
14//!
15//! - [`phantom`]: Detects references to entities not present in the knowledge base
16//! (phantom memories). Flags gaps so the agent can acquire missing knowledge.
17//!
18//! - [`speculative`]: Pre-assembles context windows for predicted upcoming queries
19//! based on conversation trajectory. Uses cosine similarity on embeddings with
20//! keyword overlap as fallback.
21//!
22//! - [`stream`]: Monitors the LLM's output token stream in real time, comparing
23//! against stored facts to detect contradictions, forgotten knowledge, corrections,
24//! and reinforcements mid-generation.
25//!
26//! - [`trajectory`]: Tracks the reasoning arc of a conversation as a sequence of
27//! decision states. Learns topic transition patterns via a Markov chain frequency
28//! map that improves predictions over time. Supports resume context generation,
29//! next-topic prediction, and feedback reinforcement from cache hits.
30//!
31//! - [`write_inference`]: Runs inference at write time to detect contradictions,
32//! create relationship edges, mark obsolete memories, adjust confidence, and
33//! trigger belief propagation automatically.
34
35/// Interference detection between confusable memories.
36pub mod interference;
37/// LLM powered cognitive judgment for memory operations.
38pub mod llm;
39/// Pain signal registry for negative experience tracking.
40pub mod pain;
41/// Phantom memory detection for knowledge gaps.
42pub mod phantom;
43/// Speculative context pre assembly cache.
44pub mod speculative;
45/// Real time LLM output stream monitoring.
46pub mod stream;
47/// Conversation trajectory tracking and prediction.
48pub mod trajectory;
49/// Write time inference engine for automatic relationship discovery.
50pub mod write_inference;
51
52pub use interference::{InterferenceDetector, InterferencePair};
53pub use llm::{
54 ClusterMember, CognitiveLlmService, ConsolidationDecision, ContradictionVerdict,
55 EntityCandidate, EntityMergeGroup, InvalidationVerdict, LlmJudge, LlmJudgeError, MemorySummary,
56 MockLlmJudge, TopicLabel,
57};
58pub use pain::{PainRegistry, PainSignal};
59pub use phantom::{EntityRegistry, PhantomConfig, PhantomMemory, PhantomPriority, PhantomTracker};
60pub use speculative::{CacheEntry, CacheStats, SpeculativeCache};
61pub use stream::{CognitionStream, StreamAlert, StreamConfig, TokenEvent};
62pub use trajectory::{DecisionState, TrajectoryNode, TrajectoryTracker, TransitionMap};
63pub use write_inference::{InferredAction, WriteInferenceConfig, WriteInferenceEngine};