do_memory_core/

lib.rs

#![deny(unsafe_code)]
// Justified clippy suppressions for this crate (WG-113 audit)
//
// CAST-RELATED (necessary for embedding/similarity calculations):
// - cast_precision_loss: f32/f64 conversions in similarity math
// - cast_possible_truncation: usize to u32 for storage IDs
// - cast_sign_loss: positive integers cast to unsigned
// - cast_possible_wrap: negative to unsigned with validation
//
// DOCUMENTATION (would require extensive rework across all functions):
// - missing_errors_doc: Documenting every Result error variant
// - missing_panics_doc: Documenting every potential panic
// - doc_markdown: Backticks around field names in docs is pedantic
//
// API DESIGN CHOICES (intentional decisions):
// - unused_self: Methods that may use self in future extensions
// - implicit_hasher: Accepting HashMap/HashSet without generic bound
// - needless_pass_by_value: Ownership semantics for builder pattern
//
// PEDANTIC LINTS (widespread, provide minimal value):
// - must_use_candidate: Constructors commonly return Self; not worth marking all
// - redundant_closure_for_method_calls: Style preference; closures are clear
// - ref_option: API design choice for consistency with existing patterns
// - match_same_arms: Merging arms reduces readability for maintenance
// - map_unwrap_or: map_or is less readable than the explicit pattern
// - float_cmp: Intentional exact comparisons for known values (e.g., 1.0, 0.5)
// - assigning_clones: clone_from is not always more efficient
// - similar_names: Short variable names common in mathematical contexts
// - missing_docs: Documentation for all public items would require extensive rework
// - cognitive_complexity: Complex functions exist; refactoring tracked as tech debt
// - expect_used/unwrap_used: Required for infallible operations and test assertions
#![allow(clippy::cognitive_complexity)]
#![allow(clippy::cast_precision_loss)]
#![allow(clippy::cast_possible_truncation)]
#![allow(clippy::cast_sign_loss)]
#![allow(clippy::cast_possible_wrap)]
#![allow(clippy::missing_errors_doc)]
#![allow(clippy::missing_panics_doc)]
#![allow(clippy::doc_markdown)]
#![allow(clippy::unused_self)]
#![allow(clippy::implicit_hasher)]
#![allow(clippy::needless_pass_by_value)]
#![allow(clippy::must_use_candidate)]
#![allow(clippy::redundant_closure_for_method_calls)]
#![allow(clippy::ref_option)]
#![allow(clippy::match_same_arms)]
#![allow(clippy::map_unwrap_or)]
#![allow(clippy::float_cmp)]
#![allow(clippy::assigning_clones)]
#![allow(clippy::similar_names)]
#![allow(clippy::expect_used)]
#![allow(clippy::unwrap_used)]
#![allow(clippy::panic)]
#![allow(missing_docs)]

//! # Memory Core
//!
//! Core data structures and types for the self-learning memory system with episodic learning.
//!
//! This crate provides the fundamental building blocks for AI agents to learn from execution:
//!
//! ## Core Concepts
//!
//! - **Episodes**: Complete task execution records with steps, outcomes, and metadata
//! - **Patterns**: Reusable patterns extracted from episodes using statistical analysis
//! - **Heuristics**: Learned condition-action rules for future decision-making
//! - **Reflections**: Generated insights after episode completion
//! - **Rewards**: Quantitative scoring of episode success
//!
//! ## Module Organization
//!
//! ### Primary APIs
//! - [`memory`]: Main orchestrator for the learning cycle
//! - [`episode`]: Episode creation, logging, and management
//! - [`patterns`]: Pattern extraction, clustering, and validation
//! - [`embeddings`]: Semantic embedding generation and similarity search
//!
//! ### Support Modules
//! - [`types`]: Common types used across the system
//! - [`storage`]: Storage backend abstractions (persistence layer)
//! - [`pre_storage`]: Pre-storage ingest layer (quality, normalization, validation)
//! - [`retrieval`]: Memory retrieval and caching
//! - [`search`]: Search and ranking functionality
//! - [`security`]: Audit logging and security
//! - [`monitoring`]: Agent performance monitoring
//!
//! ### Data Pipeline
//!
//! ```text
//! Episode → [pre_storage: ingest] → [storage: persistence] → Backend (Turso/redb)
//! ```
//!
//! - **pre_storage**: Sanitize, enrich, normalize, validate episodes
//! - **storage**: Backend traits, repository interfaces, query construction
//!
//! ## Quick Start
//!
//! ### Local Development (No Credentials)
//!
//! Use `do-memory-storage-turso` for durable local storage:
//!
//! ```no_run
//! use do_memory_core::SelfLearningMemory;
//!
//! // In-memory storage for quick testing (no dependencies)
//! let memory = SelfLearningMemory::new();
//! ```
//!
//! For local SQLite storage, see the `do_memory_storage_turso::SelfLearningMemoryExt` trait.
//!
//! ### Basic Episode Recording
//!
//! ```no_run
//! use do_memory_core::memory::SelfLearningMemory;
//! use do_memory_core::{TaskContext, TaskType, TaskOutcome, ExecutionStep, ExecutionResult};
//!
//! #[tokio::main]
//! async fn main() {
//!     let memory = SelfLearningMemory::new();
//!
//!     // 1. Start an episode for a task
//!     let context = TaskContext::default();
//!     let episode_id = memory.start_episode(
//!         "Implement authentication".to_string(),
//!         context,
//!         TaskType::CodeGeneration,
//!     ).await;
//!
//!     // 2. Log execution steps
//!     let mut step = ExecutionStep::new(
//!         1,
//!         "analyzer".to_string(),
//!         "Analyze requirements".to_string()
//!     );
//!     step.result = Some(ExecutionResult::Success {
//!         output: "Requirements clear".to_string()
//!     });
//!     memory.log_step(episode_id, step).await;
//!
//!     // 3. Complete episode with learning
//!     memory.complete_episode(episode_id, TaskOutcome::Success {
//!         verdict: "Auth implemented successfully".to_string(),
//!         artifacts: vec!["auth.rs".to_string()],
//!     }).await.unwrap();
//!
//!     // 4. Retrieve relevant context for future tasks
//!     let relevant = memory.retrieve_relevant_context(
//!         "Add authorization".to_string(),
//!         TaskContext::default(),
//!         5,
//!     ).await;
//!
//!     println!("Found {} relevant episodes", relevant.len());
//! }
//! ```
//!
//! ### Pattern-Based Learning
//!
//! The system automatically extracts reusable patterns from completed episodes:
//!
//! ```no_run
//! use do_memory_core::memory::SelfLearningMemory;
//! use do_memory_core::patterns::HybridPatternExtractor;
//! use do_memory_core::episode::Episode;
//!
//! # #[tokio::main]
//! # async fn main() {
//! # let memory = SelfLearningMemory::new();
//! // Configure hybrid pattern extraction
//! let extractor = HybridPatternExtractor::new();
//!
//! // Patterns are automatically extracted during episode completion
//! // The system tracks pattern effectiveness over time
//! # }
//! ```
//!
//! ### Semantic Search with Embeddings
//!
//! ```no_run
//! use do_memory_core::embeddings::{SemanticService, EmbeddingConfig, InMemoryEmbeddingStorage};
//! use do_memory_core::episode::Episode;
//! use do_memory_core::TaskContext;
//!
//! # #[tokio::main]
//! # async fn main() {
//! # let config = EmbeddingConfig::default();
//! // Use semantic similarity to find related episodes
//! # let storage = Box::new(InMemoryEmbeddingStorage::new());
//! let semantic = SemanticService::default(storage).await.unwrap();
//!
//! let related_episodes = semantic
//!     .find_similar_episodes(
//!         "fix authentication bug",
//!         &TaskContext::default(),
//!         10
//!     )
//!     .await
//!     .unwrap();
//! # }
//! ```
//!
//! ## Learning Cycle
//!
//! 1. **Start Episode**: Create a new episode with task context
//! 2. **Log Steps**: Record each execution step with outcomes
//! 3. **Complete Episode**: Mark episode as success/failure
//! 4. **Extract Patterns**: Identify reusable patterns
//! 5. **Generate Reflection**: Create insights and lessons learned
//! 6. **Calculate Reward**: Score episode success
//! 7. **Retrieve**: Use learned patterns for future tasks
//!
//! ## Error Handling
//!
//! Most functions return [`Result<T>`] for proper error handling:
//!
//! ```no_run
//! use do_memory_core::{Error, Result};
//!
//! async fn example() -> Result<()> {
//!     // Operations that can fail
//!     // .await?
//!     Ok(())
//! }
//! ```
//!
//! ## Feature Flags
//!
//! - `openai`: Enable OpenAI embeddings
//! - `local-embeddings`: Enable local ONNX-based embeddings
//! - `turso`: Enable Turso/libSQL storage backend
//! - `redb`: Enable redb cache storage
//! - `full`: Enable all features
//!

pub mod constants;
pub mod context;
pub mod embeddings;
pub mod episode;
pub mod error;
pub mod extraction;
pub mod indexing;
pub mod learning;
pub mod memory;
pub mod monitoring;
pub mod patterns;
pub mod pre_storage;
pub mod procedural;
pub mod reflection;
pub mod retrieval;
pub mod retry;
pub mod reward;
pub mod search;
pub mod security;
pub mod semantic;
pub mod spatiotemporal;
pub mod storage;
pub mod sync;
pub use sync::StorageSynchronizer;
pub mod types;

// Re-export commonly used types
pub use episode::{CapacityManager, Episode, EvictionPolicy, ExecutionStep, PatternId};
pub use error::{CacheError, Error, RelationshipError, Result};
pub use extraction::PatternExtractor;
pub use indexing::{
    BenchmarkResult, IndexMetrics, IndexableMemory, QueryPerformance,
    hierarchical::{HierarchicalIndex, HierarchicalIndexStats, HierarchicalQuery},
    spatiotemporal::{IndexStats, QueryOptions, SpatiotemporalIndex, TimeBucket},
};
pub use learning::queue::{PatternExtractionQueue, QueueConfig, QueueStats};
pub use memory::SelfLearningMemory;
pub use memory::checkpoint::{CheckpointMeta, HandoffPack};
pub use memory::filters::{EpisodeFilter, EpisodeFilterBuilder, OutcomeType};
pub use memory::step_buffer::BatchConfig;
pub use monitoring::{AgentMetrics, AgentMonitor, AgentType, MonitoringConfig, TaskMetrics};
pub use patterns::{
    Anomaly, AnomalyReason, ChangeDirection, ChangeType, Changepoint, ChangepointConfig,
    ChangepointDetector, ClusterCentroid, ClusteringConfig, DBSCANAnomalyDetector,
    DBSCANClusterResult, DBSCANConfig, DBSCANStats, EffectivenessTracker, EpisodeCluster,
    FeatureWeights, Heuristic, Pattern, PatternClusterer, PatternEffectiveness, PatternMetrics,
    PatternUsage, PatternValidator, SegmentComparison, SegmentComparisonConfig, SegmentStats,
    UsageStats, ValidationConfig,
};
pub use procedural::ProceduralMemory;
pub use reflection::ReflectionGenerator;
pub use retrieval::{CacheKey, CacheMetrics, QueryCache};
pub use reward::{
    AdaptiveRewardCalculator, DomainStatistics, DomainStatisticsCache, RewardCalculator,
};
pub use security::audit::{
    ActorType, AuditConfig, AuditContext, AuditEntry, AuditEventType, AuditLogLevel, AuditLogger,
    AuditOutput, AuditResult,
};
pub use storage::{DEFAULT_QUERY_LIMIT, MAX_QUERY_LIMIT, StorageBackend, apply_query_limit};
pub use types::{
    CloudEvent, ComplexityLevel, ConcurrencyConfig, DualRewardScore, EventEmitter,
    EventEmitterMode, Evidence, ExecutionResult, LogEmitter, MemoryConfig, MemoryEventMapping,
    NoOpEmitter, OutcomeStats, Reflection, RewardScore, StorageConfig, TaskContext, TaskOutcome,
    TaskType,
};

// Re-export attribution types (ADR-044 Feature 2)
pub use memory::attribution::{
    RecommendationFeedback, RecommendationSession, RecommendationStats, RecommendationTracker,
};

// Re-export context bundle types (WG-117)
pub use context::{
    AddResult, BundleAccumulator, BundleConfig, BundleStats, ContextItem, ContextItemType,
};

// Re-export retry types (issue #753)
pub use retry::{ConcurrencyLimiter, RetryBudget, RetryConfig, RetryMetrics, RetryPolicy};