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, PartialEq, Eq, Serialize, Deserialize)]
pub struct MemoryAccessScope {
pub namespace: String,
pub session_id: Option<String>,
}
fn validate_scope_token(label: &str, value: &str) -> Result<()> {
if value.trim().is_empty() || value.len() > 512 || value.chars().any(char::is_control) {
return Err(Error::ConstraintViolation(format!(
"Invalid memory scope {label}"
)));
}
Ok(())
}
impl MemoryAccessScope {
pub fn new(namespace: impl Into<String>, session_id: Option<String>) -> Result<Self> {
let namespace = namespace.into();
validate_scope_token("namespace", &namespace)?;
if let Some(ref session) = session_id {
validate_scope_token("session_id", session)?;
}
Ok(Self {
namespace,
session_id,
})
}
pub fn matches_entry(&self, entry: &super::MemoryEntry) -> bool {
entry
.namespace
.as_ref()
.is_some_and(|ns| ns.eq_ignore_ascii_case(&self.namespace))
&& self
.session_id
.as_ref()
.is_none_or(|sess| entry.session_id.as_ref() == Some(sess))
}
pub fn resolve_target(
&self,
requested_namespace: Option<&str>,
requested_session_id: Option<&str>,
) -> Result<(String, Option<String>)> {
if let Some(ns) = requested_namespace
&& !ns.eq_ignore_ascii_case(&self.namespace)
{
return Err(Error::PermissionDenied(format!(
"Namespace '{ns}' is outside scoped owner boundary '{}'",
self.namespace
)));
}
let session = if let Some(bound_session) = &self.session_id {
if let Some(req_session) = requested_session_id
&& req_session != bound_session
{
return Err(Error::PermissionDenied(format!(
"Session '{req_session}' is outside scoped owner session boundary"
)));
}
Some(bound_session.clone())
} else {
requested_session_id.map(str::to_owned)
};
Ok((self.namespace.clone(), session))
}
pub fn enforce_document(&self, document: &MemoryDocument) -> Result<MemoryDocument> {
let (ns, sess) = self.resolve_target(
document.namespace.as_deref(),
document.session_id.as_deref(),
)?;
let mut scoped = document.clone();
scoped.namespace = Some(ns);
scoped.session_id = sess;
Ok(scoped)
}
pub fn enforce_search(&self, search: &MemorySearch) -> Result<MemorySearch> {
let (ns, sess) =
self.resolve_target(search.namespace.as_deref(), search.session_id.as_deref())?;
let mut scoped = search.clone();
scoped.namespace = Some(ns);
scoped.session_id = sess;
Ok(scoped)
}
pub fn enforce_recall_filter(
&self,
filter: &super::MemoryRecallFilter,
) -> Result<super::MemoryRecallFilter> {
let (ns, sess) =
self.resolve_target(filter.namespace.as_deref(), filter.session_id.as_deref())?;
let mut scoped = filter.clone();
scoped.namespace = Some(ns);
scoped.session_id = sess;
Ok(scoped)
}
pub fn enforce_delete_scope(&self, scope: &MemoryDeleteScope) -> Result<MemoryDeleteScope> {
if scope.all {
return Err(Error::PermissionDenied(
"Global all=true deletion is forbidden on a scoped memory connection".into(),
));
}
let (ns, sess) =
self.resolve_target(scope.namespace.as_deref(), scope.session_id.as_deref())?;
let mut scoped = scope.clone();
scoped.namespace = Some(ns);
scoped.session_id = sess;
Ok(scoped)
}
}
#[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: 20.0,
vector_weight: 0.65,
lexical_weight: 0.25,
recency_weight: 0.05,
importance_weight: 0.05,
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 scoped_document;
let document = if let Some(scope) = self.memory_scope.as_ref() {
scoped_document = scope.enforce_document(document)?;
&scoped_document
} else {
document
};
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<()> {
if self.memory_scope.is_some() {
return Err(Error::PermissionDenied(
"Scoped memory connections cannot alter global memory configuration".into(),
));
}
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> {
let scope = self.memory_scope.as_ref();
self.mutate_memory(|memory, executor, pager| {
let ids: Vec<_> = memory
.all_entries()
.values()
.filter(|entry| {
entry.expires_at.is_some_and(|expiry| expiry <= now)
&& scope.is_none_or(|s| s.matches_entry(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 delete_memories(&self, scope: &MemoryDeleteScope) -> Result<usize> {
scope.validate()?;
let scoped_delete;
let effective_scope = if let Some(owner_scope) = self.memory_scope.as_ref() {
scoped_delete = owner_scope.enforce_delete_scope(scope)?;
&scoped_delete
} else {
scope
};
self.mutate_memory(|memory, executor, pager| {
let ids: Vec<_> = memory
.all_entries()
.values()
.filter(|entry| effective_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> {
let scoped_search;
let effective_search = if let Some(scope) = self.memory_scope.as_ref() {
scoped_search = scope.enforce_search(search)?;
&scoped_search
} else {
search
};
self.pager.read().ensure_io_ready()?;
self.memory.write().search_indexed(effective_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())
}))
}
}