pub mod dense;
pub mod feedback;
pub mod hybrid;
pub mod memory;
pub mod metadata;
pub mod outcome;
pub mod persistent;
pub mod segment;
pub mod shared_add;
pub mod supersession;
pub mod tenant;
pub mod tombstone;
pub mod usage;
pub mod wal;
pub mod writer_lock;
use std::collections::HashMap;
use std::path::Path;
use async_trait::async_trait;
use serde::{Deserialize, Serialize};
use crate::compaction::{CompactionMetrics, CompactionResult};
use crate::error::{MemdError, Result};
use crate::metrics::IndexStats;
use crate::task_memory::{
TaskArtifact, TaskArtifactWriteResult, TaskProjection, TaskRecord, TaskSearchFilters,
};
use crate::tiered::TieredTiming;
use crate::types::lifecycle::{LifecycleMetadata, ResolvedChunk};
use crate::types::{ChunkId, MemoryChunk, TenantId};
pub use feedback::{
apply_feedback_scores, normalize_query, FeedbackConfig, FeedbackEntry, RelevanceLabel,
};
pub use outcome::{
apply_rendered_order, decayed_outcome_weight, stable_query_hash, OutcomeEvent, OutcomeEventId,
OutcomeKind, OutcomePrior, OutcomeVerifier, RankingPolicyMode, RetrievalEpisode,
RetrievalEpisodeId, RetrievalEpisodeItem, MAX_OUTCOME_ADJUSTMENT, OUTCOME_HALF_LIFE_MS,
OUTCOME_POLICY_VERSION,
};
#[derive(Debug, Clone, Default)]
pub struct StoreStats {
pub total_chunks: usize,
pub active_chunks: usize,
pub candidate_chunks: usize,
pub deleted_chunks: usize,
pub chunk_types: HashMap<String, usize>,
pub chunk_types_active: HashMap<String, usize>,
pub chunk_types_deleted: HashMap<String, usize>,
pub chunk_types_all: HashMap<String, usize>,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct HealthCounts {
pub active_chunks: usize,
#[serde(default)]
pub candidate_chunks: usize,
pub deleted_chunks: usize,
pub expired_chunks: usize,
pub superseded_chunks: usize,
pub history_chunks: usize,
pub total_chunks: usize,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct DuplicateExample {
pub canonical_text_preview: String,
pub count: usize,
pub byte_count: usize,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct DuplicateHealth {
pub unique_text_count: usize,
pub exact_duplicate_group_count: usize,
pub duplicate_row_count: usize,
pub duplicate_row_ratio: f64,
pub duplicate_byte_ratio: f64,
#[serde(default)]
pub examples: Vec<DuplicateExample>,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct IndexCoverageHealth {
pub pending: usize,
pub indexed: usize,
pub failed: usize,
pub indexed_percentage: f64,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct PayloadHealth {
pub p50_canonical_text_bytes: usize,
pub p95_canonical_text_bytes: usize,
pub max_canonical_text_bytes: usize,
pub p95_artifact_json_bytes: usize,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct StoreHealthSnapshot {
pub counts: HealthCounts,
pub chunk_types_active: HashMap<String, usize>,
pub chunk_types_all: HashMap<String, usize>,
pub duplicates: DuplicateHealth,
pub index_coverage: IndexCoverageHealth,
pub payload: PayloadHealth,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ExternalMutationOutcome {
Unavailable,
Clean,
OwnWrites,
External {
repaired: bool,
},
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct RywProbeStats {
pub checks: u64,
pub external_detected: u64,
pub repairs: u64,
pub repair_in_progress: bool,
}
pub(crate) fn score_candidate_chunk(query: &str, chunk: &MemoryChunk) -> f32 {
if query.trim().is_empty() {
return 1.0;
}
let haystack = format!("{} {}", chunk.text, chunk.tags.join(" ")).to_ascii_lowercase();
let terms = query
.split_whitespace()
.filter_map(|term| {
let normalized = term
.trim_matches(|character: char| {
!character.is_alphanumeric() && character != '_' && character != '-'
})
.to_ascii_lowercase();
normalized
.chars()
.any(char::is_alphanumeric)
.then_some(normalized)
})
.collect::<Vec<_>>();
if terms.is_empty() {
return 0.0;
}
let natural_haystack_terms = haystack
.split(|character: char| !character.is_ascii_alphanumeric())
.filter(|term| !term.is_empty())
.collect::<Vec<_>>();
let mut score = 0.0f32;
for term in terms {
let matched = if term
.chars()
.any(|character| !character.is_ascii_alphanumeric())
{
haystack.contains(&term)
} else {
natural_haystack_terms.iter().any(|candidate| {
*candidate == term
|| (candidate.len().min(term.len()) >= 4
&& (candidate.starts_with(&term) || term.starts_with(*candidate)))
})
};
if matched {
score += 1.0;
}
}
if haystack.contains(&query.to_ascii_lowercase()) {
score += 1.5;
}
score
}
pub(crate) fn compare_scored_chunks(
(left_chunk, left_score): &(MemoryChunk, f32),
(right_chunk, right_score): &(MemoryChunk, f32),
) -> std::cmp::Ordering {
right_score
.partial_cmp(left_score)
.unwrap_or(std::cmp::Ordering::Equal)
.then_with(|| {
right_chunk
.timestamp_created
.cmp(&left_chunk.timestamp_created)
})
.then_with(|| left_chunk.chunk_id.cmp(&right_chunk.chunk_id))
}
pub(crate) fn rank_candidate_chunks(
mut chunks: Vec<MemoryChunk>,
query: &str,
k: usize,
) -> Vec<(MemoryChunk, f32)> {
let mut scored = chunks
.drain(..)
.map(|chunk| {
let score = score_candidate_chunk(query, &chunk);
(chunk, score)
})
.collect::<Vec<_>>();
scored.sort_by(compare_scored_chunks);
if !query.trim().is_empty() {
scored.retain(|(_, score)| *score > 0.0);
}
scored.truncate(k);
scored
}
const UNSUPPORTED_STORE_CAPABILITY_PREFIX: &str = "store capability unsupported";
pub(crate) fn path_is_writable(path: &Path) -> bool {
let existing = path
.ancestors()
.find(|ancestor| !ancestor.as_os_str().is_empty() && ancestor.exists())
.unwrap_or_else(|| Path::new("."));
#[cfg(unix)]
{
use std::os::unix::ffi::OsStrExt;
std::ffi::CString::new(existing.as_os_str().as_bytes())
.is_ok_and(|c_path| unsafe { libc::access(c_path.as_ptr(), libc::W_OK) } == 0)
}
#[cfg(not(unix))]
{
std::fs::metadata(existing).is_ok_and(|metadata| !metadata.permissions().readonly())
}
}
fn unsupported_store_capability(capability: &str) -> MemdError {
MemdError::StorageError(format!(
"{UNSUPPORTED_STORE_CAPABILITY_PREFIX}: {capability}"
))
}
pub(crate) fn is_unsupported_store_capability(error: &MemdError) -> bool {
matches!(
error,
MemdError::StorageError(message) if message.starts_with(UNSUPPORTED_STORE_CAPABILITY_PREFIX)
)
}
#[async_trait]
pub trait Store: Send + Sync {
async fn add(&self, chunk: MemoryChunk) -> Result<ChunkId>;
async fn add_with_stored_ids(&self, chunk: MemoryChunk) -> Result<(ChunkId, Vec<ChunkId>)> {
let chunk_id = self.add(chunk).await?;
Ok((chunk_id.clone(), vec![chunk_id]))
}
async fn add_batch(&self, chunks: Vec<MemoryChunk>) -> Result<Vec<ChunkId>>;
async fn add_task_artifact(
&self,
_artifact: TaskArtifact,
_projections: Vec<TaskProjection>,
) -> Result<TaskArtifactWriteResult> {
Err(unsupported_store_capability("task artifacts"))
}
async fn get_task_artifact(
&self,
_tenant_id: &TenantId,
_artifact_id: &str,
) -> Result<Option<TaskArtifact>> {
Err(unsupported_store_capability("task artifact lookup"))
}
async fn get_task_artifact_global(&self, _artifact_id: &str) -> Result<Option<TaskArtifact>> {
Err(unsupported_store_capability("global task artifact lookup"))
}
async fn list_task_artifacts(
&self,
_tenant_id: &TenantId,
_task_id: &str,
) -> Result<Vec<TaskArtifact>> {
Err(unsupported_store_capability("task artifact listing"))
}
async fn list_thread_artifacts(
&self,
_tenant_id: &TenantId,
_thread_id: &str,
) -> Result<Vec<TaskArtifact>> {
Err(unsupported_store_capability("thread artifact listing"))
}
async fn list_tasks(
&self,
_tenant_id: &TenantId,
_project_id: Option<&str>,
_limit: usize,
) -> Result<Vec<TaskRecord>> {
Err(unsupported_store_capability("task listing"))
}
async fn get_task_global(&self, _task_id: &str) -> Result<Option<TaskRecord>> {
Err(unsupported_store_capability("global task lookup"))
}
async fn list_tenants(&self) -> Result<Vec<TenantId>> {
Err(unsupported_store_capability("tenant listing"))
}
async fn search_task_projection_chunk_ids(
&self,
_tenant_id: &TenantId,
_filters: &TaskSearchFilters,
_limit: usize,
) -> Result<Vec<ChunkId>> {
Err(unsupported_store_capability("task projection search"))
}
async fn rerank_chunks_for_query(
&self,
tenant_id: &TenantId,
query: &str,
chunk_ids: &[ChunkId],
k: usize,
) -> Result<Vec<(MemoryChunk, f32)>> {
let mut chunks = Vec::with_capacity(chunk_ids.len());
for chunk_id in chunk_ids {
if let Some(chunk) = self.get(tenant_id, chunk_id).await? {
chunks.push(chunk);
}
}
Ok(rank_candidate_chunks(chunks, query, k))
}
async fn rerank_chunks_for_query_at(
&self,
tenant_id: &TenantId,
query: &str,
chunk_ids: &[ChunkId],
k: usize,
_ranking_time_ms: i64,
) -> Result<Vec<(MemoryChunk, f32)>> {
self.rerank_chunks_for_query(tenant_id, query, chunk_ids, k)
.await
}
async fn resolve_artifacts_for_chunks(
&self,
_tenant_id: &TenantId,
_chunk_ids: &[ChunkId],
) -> Result<HashMap<String, TaskArtifact>> {
Err(unsupported_store_capability(
"artifact projection resolution",
))
}
async fn add_feedback(&self, _feedback: FeedbackEntry) -> Result<()> {
Err(unsupported_store_capability("retrieval feedback"))
}
async fn list_feedback(
&self,
_tenant_id: &TenantId,
_query: &str,
_limit: usize,
) -> Result<Vec<FeedbackEntry>> {
Err(unsupported_store_capability("retrieval feedback listing"))
}
async fn record_retrieval_episode(
&self,
_episode: RetrievalEpisode,
_items: Vec<RetrievalEpisodeItem>,
) -> Result<()> {
Err(unsupported_store_capability("retrieval episodes"))
}
async fn get_retrieval_episode(
&self,
_tenant_id: &TenantId,
_episode_id: &RetrievalEpisodeId,
) -> Result<Option<(RetrievalEpisode, Vec<RetrievalEpisodeItem>)>> {
Err(unsupported_store_capability("retrieval episode lookup"))
}
async fn finalize_retrieval_episode(
&self,
_tenant_id: &TenantId,
_episode_id: &RetrievalEpisodeId,
_rendered_chunk_ids: &[ChunkId],
) -> Result<()> {
Err(unsupported_store_capability(
"retrieval episode finalization",
))
}
async fn record_outcome(&self, _tenant_id: &TenantId, _event: OutcomeEvent) -> Result<()> {
Err(unsupported_store_capability("outcome recording"))
}
async fn list_outcomes_for_episode(
&self,
_tenant_id: &TenantId,
_episode_id: &RetrievalEpisodeId,
) -> Result<Vec<OutcomeEvent>> {
Err(unsupported_store_capability("outcome listing"))
}
async fn outcome_priors(
&self,
_scope_tenant_id: &TenantId,
_scope_project_id: Option<&str>,
_chunk_ids: &[ChunkId],
_now_ms: i64,
) -> Result<Vec<OutcomePrior>> {
Err(unsupported_store_capability("outcome priors"))
}
async fn get(&self, tenant_id: &TenantId, chunk_id: &ChunkId) -> Result<Option<MemoryChunk>>;
async fn get_with_lifecycle(
&self,
tenant_id: &TenantId,
chunk_id: &ChunkId,
) -> Result<Option<ResolvedChunk>> {
Ok(self
.get(tenant_id, chunk_id)
.await?
.map(|chunk| ResolvedChunk {
status: chunk.status,
chunk,
lifecycle: LifecycleMetadata::default(),
}))
}
fn as_persistent(&self) -> Option<&crate::store::persistent::PersistentStore> {
None
}
fn is_read_only(&self) -> bool {
false
}
fn record_usage_event(&self, _event: crate::store::usage::UsageEvent) {}
async fn probe_external_mutation(&self) -> ExternalMutationOutcome {
ExternalMutationOutcome::Unavailable
}
fn ryw_probe_stats(&self) -> Option<RywProbeStats> {
None
}
async fn search(&self, tenant_id: &TenantId, query: &str, k: usize)
-> Result<Vec<MemoryChunk>>;
async fn search_with_scores(
&self,
tenant_id: &TenantId,
query: &str,
k: usize,
) -> Result<Vec<(MemoryChunk, f32)>> {
let chunks = self.search(tenant_id, query, k).await?;
Ok(chunks.into_iter().map(|c| (c, 1.0)).collect())
}
async fn search_with_scores_at(
&self,
tenant_id: &TenantId,
query: &str,
k: usize,
_ranking_time_ms: i64,
) -> Result<Vec<(MemoryChunk, f32)>> {
self.search_with_scores(tenant_id, query, k).await
}
fn retrieval_mode(&self) -> &'static str {
"text_fallback"
}
async fn list_chunks(
&self,
tenant_id: &TenantId,
limit: usize,
offset: usize,
) -> Result<Vec<MemoryChunk>> {
if limit == 0 {
return Ok(Vec::new());
}
let fetch = limit.saturating_add(offset);
let mut chunks = self.search(tenant_id, "", fetch).await?;
if offset >= chunks.len() {
return Ok(Vec::new());
}
Ok(chunks.drain(offset..).take(limit).collect())
}
async fn list_chunks_for_project(
&self,
tenant_id: &TenantId,
project_id: Option<&str>,
limit: usize,
offset: usize,
) -> Result<Vec<MemoryChunk>> {
if limit == 0 {
return Ok(Vec::new());
}
if project_id.is_none() {
return self.list_chunks(tenant_id, limit, offset).await;
}
let page_size = limit.clamp(1, 500);
let target = offset.saturating_add(limit);
let mut raw_offset = 0usize;
let mut filtered = Vec::new();
while filtered.len() < target {
let chunks = self.list_chunks(tenant_id, page_size, raw_offset).await?;
if chunks.is_empty() {
break;
}
raw_offset = raw_offset.saturating_add(page_size);
filtered.extend(
chunks
.into_iter()
.filter(|chunk| chunk.project_id.as_option() == project_id),
);
}
if offset >= filtered.len() {
return Ok(Vec::new());
}
Ok(filtered.into_iter().skip(offset).take(limit).collect())
}
async fn delete(&self, tenant_id: &TenantId, chunk_id: &ChunkId) -> Result<bool>;
async fn stats(&self, tenant_id: &TenantId) -> Result<StoreStats>;
async fn health_snapshot(
&self,
_tenant_id: &TenantId,
_project_id: Option<&str>,
_duplicate_limit: usize,
) -> Result<Option<StoreHealthSnapshot>> {
Ok(None)
}
async fn search_with_tier_info(
&self,
tenant_id: &TenantId,
query: &str,
k: usize,
) -> Result<(Vec<(MemoryChunk, f32)>, Option<TieredTiming>)> {
let results = self.search_with_scores(tenant_id, query, k).await?;
Ok((results, None))
}
async fn search_with_tier_info_at(
&self,
tenant_id: &TenantId,
query: &str,
k: usize,
ranking_time_ms: i64,
) -> Result<(Vec<(MemoryChunk, f32)>, Option<TieredTiming>)> {
let results = self
.search_with_scores_at(tenant_id, query, k, ranking_time_ms)
.await?;
Ok((results, None))
}
fn get_tiered_stats(&self) -> Option<persistent::TieredStats> {
None
}
fn get_index_stats(&self, _tenant_id: Option<&TenantId>) -> HashMap<String, IndexStats> {
HashMap::new()
}
fn run_compaction(&self, _tenant_id: &TenantId) -> Result<CompactionResult> {
Err(MemdError::StorageError("compaction not supported".into()))
}
fn run_compaction_if_needed(&self, _tenant_id: &TenantId) -> Result<Option<CompactionResult>> {
Err(unsupported_store_capability("threshold compaction"))
}
fn get_compaction_metrics(&self, _tenant_id: &TenantId) -> Result<CompactionMetrics> {
Err(MemdError::StorageError(
"compaction metrics not available".into(),
))
}
}
pub use dense::{DenseSearchConfig, DenseSearchResult, DenseSearcher};
pub use hybrid::{HybridConfig, HybridSearchResult, HybridSearcher, HybridTiming, SearchContext};
pub use memory::MemoryStore;
pub use persistent::{PersistentStore, PersistentStoreConfig, TieredStats};
pub use shared_add::{split_for_add, ADD_CHUNK_THRESHOLD};
pub use tenant::TenantManager;
pub use tombstone::TombstoneSet;
#[cfg(test)]
mod tests {
use super::*;
use crate::types::ChunkType;
#[test]
fn candidate_ranking_matches_terms_across_boundary_punctuation() {
let tenant = TenantId::new("candidate_rank_test").unwrap();
let mut correct = MemoryChunk::new(
tenant.clone(),
"For atlas, cache keys must use tenant scope.",
ChunkType::Decision,
);
correct.timestamp_created = 1;
let correct_id = correct.chunk_id.clone();
let mut wrong = MemoryChunk::new(
tenant,
"For boreal, cache keys must use tenant scope.",
ChunkType::Decision,
);
wrong.timestamp_created = 2;
let ranked = rank_candidate_chunks(
vec![correct, wrong],
"Recall the cache-key namespace scope required by atlas.",
2,
);
assert_eq!(ranked[0].0.chunk_id, correct_id);
}
#[test]
fn candidate_ranking_does_not_match_alphanumeric_term_inside_another_word() {
let tenant = TenantId::new("candidate_rank_test").unwrap();
let mut correct = MemoryChunk::new(
tenant.clone(),
"For ion, cache keys must use tenant scope.",
ChunkType::Decision,
);
correct.timestamp_created = 1;
let correct_id = correct.chunk_id.clone();
let mut wrong = MemoryChunk::new(
tenant,
"For atlas, apply the corrected cache-key isolation scope rule.",
ChunkType::Decision,
);
wrong.timestamp_created = 2;
let ranked = rank_candidate_chunks(vec![correct, wrong], "scope for ion.", 2);
assert_eq!(ranked[0].0.chunk_id, correct_id);
}
#[test]
fn candidate_ranking_matches_natural_word_suffixes_at_token_boundaries() {
let tenant = TenantId::new("candidate_rank_test").unwrap();
let correct = MemoryChunk::new(
tenant.clone(),
"Parameters: sensitivity 7.5",
ChunkType::Trace,
);
let wrong = MemoryChunk::new(tenant, "Candidate search", ChunkType::Trace);
let ranked = rank_candidate_chunks(vec![wrong, correct], "parameter sweeps", 2);
assert_eq!(ranked.len(), 1);
assert!(ranked[0].0.text.starts_with("Parameters:"));
}
#[test]
fn candidate_ranking_preserves_dotted_identifier_terms() {
let tenant = TenantId::new("candidate_rank_test").unwrap();
let mut correct = MemoryChunk::new(
tenant.clone(),
"Release v1.3 fixed the recovery path.",
ChunkType::Decision,
);
correct.timestamp_created = 1;
let correct_id = correct.chunk_id.clone();
let mut wrong = MemoryChunk::new(
tenant,
"Release v1.2 fixed the recovery path.",
ChunkType::Decision,
);
wrong.timestamp_created = 2;
let ranked = rank_candidate_chunks(vec![correct, wrong], "v1.3", 2);
assert_eq!(ranked[0].0.chunk_id, correct_id);
}
#[test]
fn candidate_ranking_rejects_punctuation_only_queries() {
let tenant = TenantId::new("candidate_rank_test").unwrap();
let chunk = MemoryChunk::new(tenant, "durable fact", ChunkType::Decision);
for query in ["???", "---", "___"] {
assert!(rank_candidate_chunks(vec![chunk.clone()], query, 1).is_empty());
}
}
}