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//! - [`entity`]: Resolves entity references (names, pronouns, descriptions) to
10//! canonical names using a three-tier strategy: learned cache, rule-based substring
11//! matching, and LLM-powered resolution. Persists alias tables across sessions.
12//!
13//! - [`interference`]: Detects pairs of memories similar enough to confuse an LLM,
14//! generates disambiguation text, and reorders context to maximize separation.
15//!
16//! - [`pain`]: Records negative experiences (failed actions, user corrections) as
17//! pain signals with intensity and decay. Surfaces warnings during context assembly.
18//!
19//! - [`phantom`]: Detects references to entities not present in the knowledge base
20//! (phantom memories). Flags gaps so the agent can acquire missing knowledge.
21//!
22//! - [`speculative`]: Pre-assembles context windows for predicted upcoming queries
23//! based on conversation trajectory. Uses cosine similarity on embeddings with
24//! keyword overlap as fallback.
25//!
26//! - [`stream`]: Monitors the LLM's output token stream in real time, comparing
27//! against stored facts to detect contradictions, forgotten knowledge, corrections,
28//! and reinforcements mid-generation.
29//!
30//! - [`trajectory`]: Tracks the reasoning arc of a conversation as a sequence of
31//! decision states. Learns topic transition patterns via a Markov chain frequency
32//! map that improves predictions over time. Supports resume context generation,
33//! next-topic prediction, and feedback reinforcement from cache hits.
34//!
35//! - [`write_inference`]: Runs inference at write time to detect contradictions,
36//! create relationship edges, mark obsolete memories, adjust confidence, and
37//! trigger belief propagation automatically.
38
39/// Entity resolution for merging equivalent references.
40pub mod entity;
41/// Interference detection between confusable memories.
42pub mod interference;
43/// LLM powered cognitive judgment for memory operations.
44pub mod llm;
45/// Pain signal registry for negative experience tracking.
46pub mod pain;
47/// Phantom memory detection for knowledge gaps.
48pub mod phantom;
49/// Speculative context pre assembly cache.
50pub mod speculative;
51/// Real time LLM output stream monitoring.
52pub mod stream;
53/// Conversation trajectory tracking and prediction.
54pub mod trajectory;
55/// Write time inference engine for automatic relationship discovery.
56pub mod write_inference;
57
58pub use entity::{EntityResolver, ResolutionSource, ResolvedEntity};
59pub use interference::{InterferenceDetector, InterferencePair};
60pub use llm::{
61 ClusterMember, CognitiveLlmService, ConsolidationDecision, ContradictionVerdict,
62 EntityCandidate, EntityMergeGroup, InvalidationVerdict, LlmJudge, LlmJudgeError, MemorySummary,
63 MockLlmJudge, TopicLabel,
64};
65pub use pain::{PainRegistry, PainSignal};
66pub use phantom::{EntityRegistry, PhantomConfig, PhantomMemory, PhantomPriority, PhantomTracker};
67pub use speculative::{CacheEntry, CacheStats, SpeculativeCache};
68pub use stream::{CognitionStream, StreamAlert, StreamConfig, TokenEvent};
69pub use trajectory::{DecisionState, TrajectoryNode, TrajectoryTracker, TransitionMap};
70pub use write_inference::{InferredAction, WriteInferenceConfig, WriteInferenceEngine};