use super::{MemoryConfig, MemoryFusion, MemoryRecallResult, MemorySearchResponse, MemoryStats};
use crate::{Connection, Error, Result};
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct MemoryDocument {
pub content: String,
pub embedding: Option<Vec<f32>>,
pub importance: f32,
pub tags: Vec<String>,
pub namespace: Option<String>,
pub session_id: Option<String>,
pub external_id: Option<String>,
pub source_version: Option<String>,
pub embedding_model: Option<String>,
pub expires_at: Option<u64>,
pub ttl_seconds: Option<u64>,
pub expected_revision: Option<u64>,
}
impl Default for MemoryDocument {
fn default() -> Self {
Self {
content: String::new(),
embedding: None,
importance: 0.5,
tags: Vec::new(),
namespace: None,
session_id: None,
external_id: None,
source_version: None,
embedding_model: None,
expires_at: None,
ttl_seconds: None,
expected_revision: None,
}
}
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct MemorySearch {
pub query: Option<String>,
pub embedding: Option<Vec<f32>>,
pub limit: usize,
pub namespace: Option<String>,
pub session_id: Option<String>,
pub tags: Vec<String>,
pub embedding_model: Option<String>,
pub candidate_limit: usize,
pub fusion: MemoryFusion,
pub rrf_k: f32,
pub vector_weight: f32,
pub lexical_weight: f32,
pub recency_weight: f32,
pub importance_weight: f32,
pub half_life_seconds: u64,
pub min_score: f32,
pub exact: bool,
}
impl Default for MemorySearch {
fn default() -> Self {
Self {
query: None,
embedding: None,
limit: 5,
namespace: None,
session_id: None,
tags: Vec::new(),
embedding_model: None,
candidate_limit: 128,
fusion: MemoryFusion::Rrf,
rrf_k: 60.0,
vector_weight: 0.45,
lexical_weight: 0.35,
recency_weight: 0.10,
importance_weight: 0.10,
half_life_seconds: 30 * 86400,
min_score: 0.0,
exact: false,
}
}
}
impl Connection {
pub fn upsert_embedded_memories(
&self,
provider: &impl super::EmbeddingProvider,
documents: &[MemoryDocument],
) -> Result<Vec<u64>> {
let config = self.memory.read().configuration().clone();
if documents.is_empty() {
return Ok(Vec::new());
}
if documents.len() > config.max_batch_documents
|| provider.vector_dimensions() > config.max_vector_dimensions
{
return Err(Error::ConstraintViolation(
"Embedding batch exceeds configured limits".into(),
));
}
let texts: Vec<&str> = documents.iter().map(|doc| doc.content.as_str()).collect();
let vectors = provider.embed_documents(&texts)?;
super::embedder::validate_embeddings(
&vectors,
documents.len(),
provider.vector_dimensions(),
)?;
let model = provider.model_id();
let documents: Vec<_> = documents
.iter()
.zip(vectors)
.map(|(doc, vector)| {
let mut doc = doc.clone();
doc.embedding = Some(vector);
doc.embedding_model = Some(model.clone());
doc
})
.collect();
self.upsert_memory_batch(&documents)
}
pub fn memory_request_json(&self, operation: &str, payload: &str) -> Result<String> {
fn decode<T: serde::de::DeserializeOwned>(payload: &str) -> Result<T> {
serde_json::from_str(payload).map_err(|e| Error::Serialization(e.to_string()))
}
fn encode(value: impl Serialize) -> Result<String> {
serde_json::to_string(&value).map_err(|e| Error::Serialization(e.to_string()))
}
match operation {
"store" => encode(self.store_memory(&decode(payload)?)?),
"search" => encode(self.search_memories(&decode(payload)?)?),
"forget" => encode(self.memory_forget_checked(decode(payload)?)?),
"upsert" => encode(self.upsert_memory(&decode(payload)?)?),
"store_batch" => {
encode(self.store_memory_batch(&decode::<Vec<MemoryDocument>>(payload)?)?)
}
"upsert_batch" => {
encode(self.upsert_memory_batch(&decode::<Vec<MemoryDocument>>(payload)?)?)
}
"search_detailed" => encode(self.search_memories_detailed(&decode(payload)?)?),
"configure" => {
self.configure_memory(decode(payload)?)?;
encode(self.memory_stats())
}
"stats" => encode(self.memory_stats()),
"storage_health" => encode(self.storage_health()),
"prepare" => encode(self.prepare_memory_indexes()?),
"purge_expired" => encode(self.purge_expired_memories()?),
"delete" => encode(self.delete_memories(&decode(payload)?)?),
_ => Err(Error::ConstraintViolation(
"Unknown memory operation".into(),
)),
}
}
pub fn store_memory(&self, document: &MemoryDocument) -> Result<u64> {
self.write_memory_batch(std::slice::from_ref(document), false, unix_time())
.map(|ids| ids[0])
}
pub fn upsert_memory(&self, document: &MemoryDocument) -> Result<u64> {
self.write_memory_batch(std::slice::from_ref(document), true, unix_time())
.map(|ids| ids[0])
}
pub fn store_memory_batch(&self, documents: &[MemoryDocument]) -> Result<Vec<u64>> {
self.write_memory_batch(documents, false, unix_time())
}
pub fn upsert_memory_batch(&self, documents: &[MemoryDocument]) -> Result<Vec<u64>> {
self.write_memory_batch(documents, true, unix_time())
}
fn write_memory_batch(
&self,
documents: &[MemoryDocument],
upsert: bool,
now: u64,
) -> Result<Vec<u64>> {
if documents.is_empty() {
return Ok(Vec::new());
}
if documents.len() > self.memory.read().configuration().max_batch_documents {
return Err(Error::ConstraintViolation(
"Memory batch exceeds max_batch_documents".into(),
));
}
self.mutate_memory(|memory, executor, pager| {
let mut ids = Vec::with_capacity(documents.len());
for document in documents {
let id = memory.write_document(document, upsert, now)?;
executor
.persist_memory_entry(pager, memory.get_memory(id).expect("stored source"))?;
ids.push(id);
}
Ok(ids)
})
}
pub fn configure_memory(&self, config: MemoryConfig) -> Result<()> {
self.memory.write().configure(config)
}
pub fn memory_stats(&self) -> MemoryStats {
self.memory.read().stats()
}
pub fn prepare_memory_indexes(&self) -> Result<MemoryStats> {
self.memory.write().prepare_indexes()
}
pub fn purge_expired_memories(&self) -> Result<usize> {
self.purge_expired_memories_at(unix_time())
}
pub fn purge_expired_memories_at(&self, now: u64) -> Result<usize> {
self.mutate_memory(|memory, executor, pager| {
let ids: Vec<_> = memory
.all_entries()
.values()
.filter(|entry| entry.expires_at.is_some_and(|expiry| expiry <= now))
.map(|entry| entry.id)
.collect();
let (removed, updated) = memory.remove_ids(&ids);
for id in &removed {
executor.delete_memory_entry(pager, *id)?;
}
for id in updated {
executor.persist_memory_entry(
pager,
memory.get_memory(id).expect("remaining associated source"),
)?;
}
Ok(removed.len())
})
}
pub fn delete_memories(&self, scope: &MemoryDeleteScope) -> Result<usize> {
scope.validate()?;
self.mutate_memory(|memory, executor, pager| {
let ids: Vec<_> = memory
.all_entries()
.values()
.filter(|entry| scope.matches(entry))
.map(|entry| entry.id)
.collect();
let (removed, updated) = memory.remove_ids(&ids);
for id in &removed {
executor.delete_memory_entry(pager, *id)?;
}
for id in updated {
executor.persist_memory_entry(
pager,
memory.get_memory(id).expect("remaining associated source"),
)?;
}
Ok(removed.len())
})
}
pub fn search_memories(&self, search: &MemorySearch) -> Result<Vec<MemoryRecallResult>> {
Ok(self.search_memories_detailed(search)?.results)
}
pub fn search_memories_detailed(&self, search: &MemorySearch) -> Result<MemorySearchResponse> {
self.search_memories_at(search, unix_time())
}
pub fn search_memories_at(
&self,
search: &MemorySearch,
now: u64,
) -> Result<MemorySearchResponse> {
self.pager.read().ensure_io_ready()?;
self.memory.write().search_indexed(search, now)
}
}
pub(crate) fn unix_time() -> u64 {
web_time::SystemTime::now()
.duration_since(web_time::UNIX_EPOCH)
.unwrap_or_default()
.as_secs()
}
impl MemorySearch {
pub(crate) fn validate(&self, config: &MemoryConfig) -> Result<()> {
let reject = |text: &str| Error::ConstraintViolation(text.into());
if self.query.as_ref().is_none_or(|q| q.trim().is_empty()) && self.embedding.is_none() {
return Err(reject("Supply query text or an embedding"));
}
if self.query.as_ref().is_some_and(|q| q.len() > 65536) {
return Err(reject("Memory query exceeds 65536 bytes"));
}
if self.limit > self.candidate_limit
|| self.candidate_limit == 0
|| self.candidate_limit > config.max_candidates
{
return Err(reject(
"Require limit <= candidate_limit <= configured max_candidates",
));
}
if self.embedding.as_ref().is_some_and(|v| {
v.is_empty()
|| v.len() > config.max_vector_dimensions
|| v.iter().any(|x| !x.is_finite())
}) {
return Err(reject("Invalid query embedding"));
}
let weights = [
self.vector_weight,
self.lexical_weight,
self.recency_weight,
self.importance_weight,
];
if weights
.iter()
.any(|w| !w.is_finite() || !(0.0..=1_000_000.0).contains(w))
|| weights.iter().sum::<f32>() <= 0.0
|| (if self.query.is_some() {
self.lexical_weight
} else {
0.0
}) + (if self.embedding.is_some() {
self.vector_weight
} else {
0.0
}) <= 0.0
{
return Err(reject(
"Memory ranking requires finite nonnegative weights and a positive query-channel weight",
));
}
if !self.rrf_k.is_finite()
|| !(1.0..=1_000_000.0).contains(&self.rrf_k)
|| !self.min_score.is_finite()
|| !(0.0..=1.0).contains(&self.min_score)
{
return Err(reject("Invalid RRF constant or minimum score"));
}
Ok(())
}
}
#[derive(Debug, Default, Clone, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct MemoryDeleteScope {
pub namespace: Option<String>,
pub session_id: Option<String>,
pub external_id: Option<String>,
pub source_version: Option<String>,
pub except_source_version: Option<String>,
pub tags: Vec<String>,
pub all: bool,
}
impl MemoryDeleteScope {
fn validate(&self) -> Result<()> {
if !self.all
&& self.namespace.is_none()
&& self.session_id.is_none()
&& self.external_id.is_none()
&& self.source_version.is_none()
&& self.tags.is_empty()
{
return Err(Error::ConstraintViolation(
"Deletion requires explicit source filters or all=true".into(),
));
}
Ok(())
}
fn matches(&self, entry: &super::MemoryEntry) -> bool {
self.namespace.as_ref().is_none_or(|ns| {
entry
.namespace
.as_ref()
.is_some_and(|value| value.to_lowercase() == ns.to_lowercase())
}) && self
.session_id
.as_ref()
.is_none_or(|id| entry.session_id.as_ref() == Some(id))
&& self
.external_id
.as_ref()
.is_none_or(|id| entry.external_id.as_ref() == Some(id))
&& self
.source_version
.as_ref()
.is_none_or(|version| entry.source_version.as_ref() == Some(version))
&& self
.except_source_version
.as_ref()
.is_none_or(|version| entry.source_version.as_ref() != Some(version))
&& (self.tags.is_empty()
|| self.tags.iter().any(|tag| {
entry
.tags
.iter()
.any(|value| value.to_lowercase() == tag.to_lowercase())
}))
}
}