use std::collections::{BTreeMap, HashSet};
use std::sync::{Arc, Mutex, MutexGuard};
use async_trait::async_trait;
use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use serde_json::{json, Value};
use crate::agents::StateScope;
use crate::error::{Result, RustyError};
use crate::journal::{EventDraft, Journal, JournalSnapshot};
use crate::record::{
sha256_hex, ArtifactRef, Effect, PayloadRef, RunEvent, RunEventKind, INLINE_PAYLOAD_MAX_BYTES,
};
use crate::replay::ServedEffect;
pub const MEMORY_SCHEMA_VERSION: &str = "memory-v1";
pub const TOKEN_BYTES_PER_ESTIMATE: u64 = 4;
pub const DEFAULT_TOKEN_MARGIN_PERCENT: u32 = 20;
fn invalid(message: impl Into<String>) -> RustyError {
RustyError::InvalidUpdate(message.into())
}
fn replay_error(message: impl Into<String>) -> RustyError {
RustyError::Replay(message.into())
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum MemoryKind {
Fact,
Preference,
Example,
Summary,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Candidacy {
Pending,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum MemoryScope {
Run,
Agent,
Team,
User,
Tenant,
}
impl MemoryScope {
pub fn from_state_scope(scope: StateScope) -> Option<MemoryScope> {
Some(match scope {
StateScope::Private => MemoryScope::Agent,
StateScope::Team => MemoryScope::Team,
StateScope::User => MemoryScope::User,
StateScope::Tenant => MemoryScope::Tenant,
})
}
pub fn to_state_scope(self) -> Option<StateScope> {
match self {
MemoryScope::Run => None,
MemoryScope::Agent => Some(StateScope::Private),
MemoryScope::Team => Some(StateScope::Team),
MemoryScope::User => Some(StateScope::User),
MemoryScope::Tenant => Some(StateScope::Tenant),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct ScopeAddress {
pub scope: MemoryScope,
pub id: String,
}
impl ScopeAddress {
pub fn new(scope: MemoryScope, id: impl Into<String>) -> Self {
Self {
scope,
id: id.into(),
}
}
pub fn as_address(&self) -> String {
let scope = serde_json::to_value(self.scope)
.ok()
.and_then(|v| v.as_str().map(str::to_owned))
.unwrap_or_else(|| format!("{:?}", self.scope).to_lowercase());
format!("{scope}:{}", self.id)
}
}
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ProvenanceAuthor {
Agent {
agent_id: String,
},
Human {
human_id: String,
},
Distiller {
name: String,
},
System,
}
impl ProvenanceAuthor {
pub fn as_id_string(&self) -> String {
match self {
ProvenanceAuthor::Agent { agent_id } => format!("agent:{agent_id}"),
ProvenanceAuthor::Human { human_id } => format!("human:{human_id}"),
ProvenanceAuthor::Distiller { name } => format!("distiller:{name}"),
ProvenanceAuthor::System => "system".to_owned(),
}
}
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct MemoryEvidence {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub run_id: Option<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub event_ids: Vec<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub correction_id: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub candidate_id: Option<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub source_memory_ids: Vec<String>,
}
impl MemoryEvidence {
pub fn is_empty(&self) -> bool {
self.run_id.is_none()
&& self.event_ids.is_empty()
&& self.correction_id.is_none()
&& self.candidate_id.is_none()
&& self.source_memory_ids.is_empty()
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct MemoryProvenance {
pub author: ProvenanceAuthor,
#[serde(default, skip_serializing_if = "MemoryEvidence::is_empty")]
pub evidence: MemoryEvidence,
pub written_at: DateTime<Utc>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ValidityWindow {
pub valid_from: DateTime<Utc>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub valid_until: Option<DateTime<Utc>>,
}
impl ValidityWindow {
pub fn starting(valid_from: DateTime<Utc>) -> Self {
Self {
valid_from,
valid_until: None,
}
}
pub fn contains(&self, t: DateTime<Utc>) -> bool {
self.valid_from <= t && self.valid_until.is_none_or(|until| t < until)
}
}
fn is_false(value: &bool) -> bool {
!*value
}
fn is_zero(value: &i64) -> bool {
*value == 0
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct MemoryRecord {
pub memory_id: String,
pub kind: MemoryKind,
pub scope: ScopeAddress,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub key: Option<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub tags: Vec<String>,
#[serde(default, skip_serializing_if = "is_zero")]
pub priority: i64,
pub provenance: MemoryProvenance,
pub confidence: f64,
pub validity: ValidityWindow,
pub created_at: DateTime<Utc>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub expires_at: Option<DateTime<Utc>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub supersedes: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub candidacy: Option<Candidacy>,
pub content: PayloadRef,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub embedding: Option<Value>,
}
impl MemoryRecord {
pub fn new(
kind: MemoryKind,
scope: ScopeAddress,
provenance: MemoryProvenance,
confidence: f64,
validity: ValidityWindow,
created_at: DateTime<Utc>,
content: Value,
) -> Result<Self> {
if !(confidence > 0.0 && confidence <= 1.0) {
return Err(invalid(format!(
"memory confidence must be in (0, 1], got {confidence} — confidence is a \
writer-declared claim, and a value outside the interval is not a claim at all"
)));
}
let content_ref = content_ref_of(&content);
let memory_id = derive_memory_id(&content_ref, &provenance)?;
Ok(Self {
memory_id,
kind,
scope,
key: None,
tags: Vec::new(),
priority: 0,
provenance,
confidence,
validity,
created_at,
expires_at: None,
supersedes: None,
candidacy: None,
content: content_ref,
embedding: None,
})
}
pub fn with_key(mut self, key: impl Into<String>) -> Self {
self.key = Some(key.into());
self
}
pub fn with_tags(mut self, tags: impl IntoIterator<Item = impl Into<String>>) -> Self {
self.tags = tags.into_iter().map(Into::into).collect();
self
}
pub fn with_priority(mut self, priority: i64) -> Self {
self.priority = priority;
self
}
pub fn with_expires_at(mut self, expires_at: DateTime<Utc>) -> Self {
self.expires_at = Some(expires_at);
self
}
pub fn with_supersedes(mut self, supersedes: impl Into<String>) -> Self {
self.supersedes = Some(supersedes.into());
self
}
pub fn with_candidacy(mut self, candidacy: Candidacy) -> Self {
self.candidacy = Some(candidacy);
self
}
pub fn content_bytes(&self) -> u64 {
match &self.content {
PayloadRef::Inline(value) => serde_json::to_vec(value)
.map(|bytes| bytes.len() as u64)
.unwrap_or(0),
PayloadRef::Artifact(reference) => reference.bytes,
}
}
pub fn content_ref_of(content: &Value) -> PayloadRef {
content_ref_of(content)
}
}
fn content_ref_of(content: &Value) -> PayloadRef {
let Ok(bytes) = serde_json::to_vec(content) else {
return PayloadRef::Inline(content.clone());
};
if bytes.len() <= INLINE_PAYLOAD_MAX_BYTES {
return PayloadRef::Inline(content.clone());
}
PayloadRef::Artifact(ArtifactRef {
sha256: sha256_hex(&bytes),
bytes: bytes.len() as u64,
})
}
pub fn derive_memory_id(content: &PayloadRef, provenance: &MemoryProvenance) -> Result<String> {
let content_hash = content.content_hash()?;
let identity = json!({ "content": content_hash, "provenance": provenance });
Ok(sha256_hex(&serde_json::to_vec(&identity)?))
}
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct MemoryQuery {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub scope: Option<ScopeAddress>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub kinds: Vec<MemoryKind>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub key: Option<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub tags: Vec<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub valid_at: Option<DateTime<Utc>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub min_confidence: Option<f64>,
#[serde(default, skip_serializing_if = "is_false")]
pub include_expired: bool,
#[serde(default, skip_serializing_if = "is_false")]
pub include_superseded: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub authored_by: Option<ProvenanceAuthor>,
#[serde(default, skip_serializing_if = "is_false")]
pub candidates_only: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub as_of: Option<DateTime<Utc>>,
}
impl MemoryQuery {
pub fn matches(&self, record: &MemoryRecord, superseded: bool, now: DateTime<Utc>) -> bool {
if let Some(scope) = &self.scope {
if &record.scope != scope {
return false;
}
}
if !self.kinds.is_empty() && !self.kinds.contains(&record.kind) {
return false;
}
if let Some(key) = &self.key {
if record.key.as_deref() != Some(key.as_str()) {
return false;
}
}
if !self
.tags
.iter()
.all(|tag| record.tags.iter().any(|t| t == tag))
{
return false;
}
if let Some(valid_at) = self.valid_at {
if !record.validity.contains(valid_at) {
return false;
}
}
if let Some(min_confidence) = self.min_confidence {
if record.confidence < min_confidence {
return false;
}
}
if !self.include_expired && record.expires_at.is_some_and(|expires| expires <= now) {
return false;
}
if !self.include_superseded && superseded {
return false;
}
if let Some(author) = &self.authored_by {
if &record.provenance.author != author {
return false;
}
}
if self.candidates_only && record.candidacy.is_none() {
return false;
}
true
}
}
pub fn apply_query(
universe: &[MemoryRecord],
query: &MemoryQuery,
now: DateTime<Utc>,
) -> Vec<MemoryRecord> {
let superseded: HashSet<&str> = superseded_set(universe);
universe
.iter()
.filter(|record| query.matches(record, superseded.contains(record.memory_id.as_str()), now))
.cloned()
.collect()
}
pub fn superseded_set(universe: &[MemoryRecord]) -> HashSet<&str> {
universe
.iter()
.filter_map(|record| record.supersedes.as_deref())
.chain(
universe
.iter()
.filter(|record| record.kind == MemoryKind::Summary)
.flat_map(|record| {
record
.provenance
.evidence
.source_memory_ids
.iter()
.map(String::as_str)
}),
)
.collect()
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum BudgetOverflow {
#[default]
Truncate,
Fail,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ContextBudget {
pub max_tokens: u32,
#[serde(
default = "default_margin_percent",
skip_serializing_if = "is_default_margin_percent"
)]
pub margin_percent: u32,
#[serde(default)]
pub overflow: BudgetOverflow,
}
fn default_margin_percent() -> u32 {
DEFAULT_TOKEN_MARGIN_PERCENT
}
fn is_default_margin_percent(value: &u32) -> bool {
*value == DEFAULT_TOKEN_MARGIN_PERCENT
}
impl ContextBudget {
pub fn new(max_tokens: u32) -> Self {
Self {
max_tokens,
margin_percent: DEFAULT_TOKEN_MARGIN_PERCENT,
overflow: BudgetOverflow::Truncate,
}
}
pub fn with_margin_percent(mut self, margin_percent: u32) -> Self {
self.margin_percent = margin_percent;
self
}
pub fn with_overflow(mut self, overflow: BudgetOverflow) -> Self {
self.overflow = overflow;
self
}
}
pub fn estimated_tokens(bytes: u64, margin_percent: u32) -> u32 {
let base = bytes.div_ceil(TOKEN_BYTES_PER_ESTIMATE) as u128;
let scaled = base * (100 + margin_percent as u128) / 100;
scaled.min(u32::MAX as u128) as u32
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TokenAccounting {
pub bytes_per_token: u64,
pub margin_percent: u32,
pub budget_tokens: u32,
pub used_tokens: u32,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct MemoryAssembly {
pub memory_ids: Vec<String>,
pub records: Vec<MemoryRecord>,
pub token_accounting: TokenAccounting,
pub truncated: bool,
}
pub fn assemble(records: Vec<MemoryRecord>, budget: &ContextBudget) -> Result<MemoryAssembly> {
let mut ranked = records;
ranked.sort_by(|a, b| {
b.priority
.cmp(&a.priority)
.then_with(|| b.confidence.total_cmp(&a.confidence))
.then_with(|| b.created_at.cmp(&a.created_at))
.then_with(|| a.memory_id.cmp(&b.memory_id))
});
let mut used_tokens: u32 = 0;
let mut packed: Vec<MemoryRecord> = Vec::new();
let mut truncated = false;
for record in ranked {
let cost = estimated_tokens(record.content_bytes(), budget.margin_percent);
if used_tokens.saturating_add(cost) > budget.max_tokens {
match budget.overflow {
BudgetOverflow::Truncate => {
truncated = true;
break;
}
BudgetOverflow::Fail => {
return Err(invalid(format!(
"memory assembly exceeds the context budget: record `{}` costs an \
estimated {cost} tokens with {} of {} already used — the filtered \
set does not fit, and the budget was declared hard",
record.memory_id, used_tokens, budget.max_tokens
)));
}
}
}
used_tokens = used_tokens.saturating_add(cost);
packed.push(record);
}
let memory_ids = packed
.iter()
.map(|record| record.memory_id.clone())
.collect();
Ok(MemoryAssembly {
memory_ids,
records: packed,
token_accounting: TokenAccounting {
bytes_per_token: TOKEN_BYTES_PER_ESTIMATE,
margin_percent: budget.margin_percent,
budget_tokens: budget.max_tokens,
used_tokens,
},
truncated,
})
}
fn deserialize_non_empty_id<'de, D>(deserializer: D) -> std::result::Result<String, D::Error>
where
D: serde::Deserializer<'de>,
{
let value = String::deserialize(deserializer)?;
if value.trim().is_empty() {
return Err(serde::de::Error::custom(
"identity must be non-empty — attribution is mandatory",
));
}
Ok(value)
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum CorrectionTarget {
RunEvent {
run_id: String,
event_id: String,
},
Memory {
memory_id: String,
},
Prompt {
prompt_hash: String,
},
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Correction {
#[serde(deserialize_with = "deserialize_non_empty_id")]
pub correction_id: String,
#[serde(deserialize_with = "deserialize_non_empty_id")]
pub author: String,
pub target: CorrectionTarget,
pub corrected: Value,
pub scope: ScopeAddress,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub rationale: Option<String>,
}
impl Correction {
pub fn author_as_provenance(&self) -> ProvenanceAuthor {
ProvenanceAuthor::Human {
human_id: self.author.clone(),
}
}
pub fn attribution(&self) -> String {
format!(
"human:{} via correction:{}",
self.author, self.correction_id
)
}
pub fn evidence(&self) -> MemoryEvidence {
let (run_id, event_ids) = match &self.target {
CorrectionTarget::RunEvent { run_id, event_id } => {
(Some(run_id.clone()), vec![event_id.clone()])
}
_ => (None, Vec::new()),
};
MemoryEvidence {
run_id,
event_ids,
correction_id: Some(self.correction_id.clone()),
..MemoryEvidence::default()
}
}
pub fn is_candidate(&self) -> bool {
self.scope.scope != MemoryScope::Run
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ForgetReason {
Expired,
Retracted,
ErasureRequest,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct MemoryForgetTombstone {
pub memory_id: String,
pub scope: ScopeAddress,
pub reason: ForgetReason,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub invalidated: Vec<String>,
}
pub fn memory_forget_effect_key(scope: &ScopeAddress, memory_id: &str) -> String {
format!("memory_forget:{}:{memory_id}", scope.as_address())
}
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct ForgetPlan {
pub forgotten: Vec<String>,
pub invalidated: Vec<String>,
}
pub fn plan_forget(universe: &[MemoryRecord], targets: &[String]) -> ForgetPlan {
let mut removed: HashSet<&str> = universe
.iter()
.filter(|record| targets.iter().any(|t| t == &record.memory_id))
.map(|record| record.memory_id.as_str())
.collect();
loop {
let mut grew = false;
for record in universe {
if record.kind != MemoryKind::Summary || removed.contains(record.memory_id.as_str()) {
continue;
}
if record
.provenance
.evidence
.source_memory_ids
.iter()
.any(|source| removed.contains(source.as_str()))
{
removed.insert(record.memory_id.as_str());
grew = true;
}
}
if !grew {
break;
}
}
let mut forgotten: Vec<String> = removed
.iter()
.filter(|id| targets.iter().any(|t| t.as_str() == **id))
.map(|id| id.to_string())
.collect();
forgotten.sort();
let mut invalidated: Vec<String> = removed
.iter()
.filter(|id| !forgotten.iter().any(|f| f.as_str() == **id))
.map(|id| id.to_string())
.collect();
invalidated.sort();
ForgetPlan {
forgotten,
invalidated,
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct MemoryConflict {
pub scope: ScopeAddress,
pub key: String,
pub memory_ids: Vec<String>,
pub overlap: ValidityWindow,
}
pub fn detect_conflicts(universe: &[MemoryRecord], now: DateTime<Utc>) -> Vec<MemoryConflict> {
let superseded = superseded_set(universe);
let is_live = |record: &MemoryRecord| {
!superseded.contains(record.memory_id.as_str())
&& record.expires_at.is_none_or(|expires| expires > now)
};
let mut groups: BTreeMap<(String, &str), Vec<&MemoryRecord>> = BTreeMap::new();
for record in universe.iter().filter(|r| is_live(r)) {
let Some(key) = record.key.as_deref() else {
continue;
};
groups
.entry((record.scope.as_address(), key))
.or_default()
.push(record);
}
let mut conflicts = Vec::new();
for ((_, key), mut group) in groups {
group.sort_by(|a, b| a.memory_id.cmp(&b.memory_id));
for (i, a) in group.iter().enumerate() {
for b in &group[i + 1..] {
if a.supersedes.as_deref() == Some(b.memory_id.as_str())
|| b.supersedes.as_deref() == Some(a.memory_id.as_str())
{
continue;
}
let Some(overlap) = validity_overlap(&a.validity, &b.validity) else {
continue;
};
if same_content(a, b) {
continue;
}
conflicts.push(MemoryConflict {
scope: a.scope.clone(),
key: key.to_string(),
memory_ids: vec![a.memory_id.clone(), b.memory_id.clone()],
overlap,
});
}
}
}
conflicts.sort_by(|a, b| {
a.scope
.as_address()
.cmp(&b.scope.as_address())
.then_with(|| a.key.cmp(&b.key))
.then_with(|| a.memory_ids.cmp(&b.memory_ids))
});
conflicts
}
fn validity_overlap(a: &ValidityWindow, b: &ValidityWindow) -> Option<ValidityWindow> {
let valid_from = a.valid_from.max(b.valid_from);
let valid_until = match (a.valid_until, b.valid_until) {
(Some(x), Some(y)) => Some(x.min(y)),
(x, y) => x.or(y),
};
if valid_until.is_some_and(|until| valid_from >= until) {
return None;
}
Some(ValidityWindow {
valid_from,
valid_until,
})
}
fn same_content(a: &MemoryRecord, b: &MemoryRecord) -> bool {
match (a.content.content_hash(), b.content.content_hash()) {
(Ok(x), Ok(y)) => x == y,
_ => a.content == b.content,
}
}
pub fn consolidation_summary(
scope: ScopeAddress,
distiller: impl Into<String>,
sources: &[MemoryRecord],
content: Value,
now: DateTime<Utc>,
) -> Result<MemoryRecord> {
if sources.is_empty() {
return Err(invalid(
"consolidation needs at least one source record — a summary that names no \
sources is not a consolidation, and an unnamed derivation can neither be \
audited nor forgotten correctly",
));
}
let mut source_ids: Vec<String> = sources
.iter()
.map(|record| record.memory_id.clone())
.collect();
source_ids.sort();
let confidence = sources
.iter()
.map(|record| record.confidence)
.fold(f64::INFINITY, f64::min);
let valid_from = sources
.iter()
.map(|record| record.validity.valid_from)
.min()
.expect("sources is non-empty");
let valid_until = sources
.iter()
.map(|record| record.validity.valid_until)
.collect::<Option<Vec<DateTime<Utc>>>>()
.and_then(|untils| untils.into_iter().max());
let provenance = MemoryProvenance {
author: ProvenanceAuthor::Distiller {
name: distiller.into(),
},
evidence: MemoryEvidence {
source_memory_ids: source_ids,
..MemoryEvidence::default()
},
written_at: now,
};
MemoryRecord::new(
MemoryKind::Summary,
scope,
provenance,
confidence,
ValidityWindow {
valid_from,
valid_until,
},
now,
content,
)
}
#[async_trait]
pub trait MemoryStore: Send + Sync + std::fmt::Debug {
async fn put(&self, record: &MemoryRecord) -> Result<bool>;
async fn get(&self, memory_id: &str) -> Result<Option<MemoryRecord>>;
async fn all(&self) -> Result<Vec<MemoryRecord>>;
async fn remove(&self, memory_id: &str) -> Result<bool>;
async fn query(&self, query: &MemoryQuery, now: DateTime<Utc>) -> Result<Vec<MemoryRecord>> {
Ok(apply_query(&self.all().await?, query, now))
}
}
#[derive(Debug, Default)]
pub struct InMemoryMemoryStore {
records: Mutex<BTreeMap<String, MemoryRecord>>,
}
impl InMemoryMemoryStore {
pub fn new() -> Self {
Self::default()
}
fn lock(&self) -> MutexGuard<'_, BTreeMap<String, MemoryRecord>> {
self.records.lock().unwrap_or_else(|e| e.into_inner())
}
}
#[async_trait]
impl MemoryStore for InMemoryMemoryStore {
async fn put(&self, record: &MemoryRecord) -> Result<bool> {
let mut map = self.lock();
if map.contains_key(&record.memory_id) {
return Ok(false);
}
map.insert(record.memory_id.clone(), record.clone());
Ok(true)
}
async fn get(&self, memory_id: &str) -> Result<Option<MemoryRecord>> {
Ok(self.lock().get(memory_id).cloned())
}
async fn all(&self) -> Result<Vec<MemoryRecord>> {
Ok(self.lock().values().cloned().collect())
}
async fn remove(&self, memory_id: &str) -> Result<bool> {
Ok(self.lock().remove(memory_id).is_some())
}
}
pub fn memory_read_request(query: &MemoryQuery, budget: &ContextBudget) -> Value {
json!({ "query": query, "budget": budget })
}
pub fn memory_effect_key(scope: &ScopeAddress, memory_id: &str) -> String {
format!("memory:{}:{memory_id}", scope.as_address())
}
fn request_hash(request: &Value) -> Result<String> {
Ok(sha256_hex(&serde_json::to_vec(request)?))
}
#[derive(Debug)]
struct MemoryReplayInner {
servable: Vec<RunEvent>,
artifacts: BTreeMap<String, Value>,
cursor: usize,
}
#[derive(Debug, Clone)]
pub struct MemoryReplaySource {
inner: Arc<Mutex<MemoryReplayInner>>,
}
impl MemoryReplaySource {
pub fn new(snapshot: &JournalSnapshot) -> Self {
Self {
inner: Arc::new(Mutex::new(MemoryReplayInner {
servable: snapshot
.events
.iter()
.filter(|event| event.kind == RunEventKind::MemoryRead)
.cloned()
.collect(),
artifacts: snapshot.artifacts.clone(),
cursor: 0,
})),
}
}
fn lock(&self) -> MutexGuard<'_, MemoryReplayInner> {
self.inner.lock().unwrap_or_else(|e| e.into_inner())
}
pub fn serve(&self, request: &Value) -> Result<ServedEffect> {
let issued_hash = request_hash(request)?;
let mut inner = self.lock();
let Some(event) = inner.servable.get(inner.cursor) else {
return Err(replay_error(format!(
"replay exhaustion: the run issued a memory read (request hash {issued_hash}), \
but the journal holds no further recorded memory reads to serve — the \
replayed run is doing more work than the recorded one"
)));
};
let recorded_input = event
.input
.as_ref()
.and_then(|payload| match payload {
PayloadRef::Inline(value) => Some(value.clone()),
PayloadRef::Artifact(reference) => inner.artifacts.get(&reference.sha256).cloned(),
})
.ok_or_else(|| {
replay_error(format!(
"recorded memory read at seq {} has no input payload to match against",
event.seq
))
})?;
let recorded_hash = request_hash(&recorded_input)?;
if recorded_hash != issued_hash {
return Err(replay_error(format!(
"replay divergence at recorded seq {} (memory read): the run issued a request \
whose canonical hash is {issued_hash}, but the journaled request hashes to \
{recorded_hash} — the replayed run has diverged from its evidence",
event.seq
)));
}
let served = ServedEffect {
input: Some(recorded_input),
output: event.output.as_ref().and_then(|payload| match payload {
PayloadRef::Inline(value) => Some(value.clone()),
PayloadRef::Artifact(reference) => inner.artifacts.get(&reference.sha256).cloned(),
}),
event: event.clone(),
};
inner.cursor += 1;
Ok(served)
}
pub fn is_exhausted(&self) -> bool {
let inner = self.lock();
inner.cursor == inner.servable.len()
}
}
#[derive(Debug, Clone)]
pub enum MemorySource {
Store(Arc<dyn MemoryStore>),
Replay(MemoryReplaySource),
}
#[derive(Debug, Clone)]
pub struct JournaledMemory {
journal: Journal,
source: MemorySource,
}
impl JournaledMemory {
pub fn new(journal: &Journal, source: MemorySource) -> Self {
Self {
journal: journal.clone(),
source,
}
}
pub fn source(&self) -> &MemorySource {
&self.source
}
pub async fn read(
&self,
query: &MemoryQuery,
budget: &ContextBudget,
parent: Option<String>,
) -> Result<MemoryAssembly> {
let mut resolved = query.clone();
let as_of = resolved.as_of.unwrap_or_else(|| self.journal.clock().now());
resolved.as_of = Some(as_of);
let request = memory_read_request(&resolved, budget);
match &self.source {
MemorySource::Store(store) => {
let started = self.journal.clock().now();
let records = store.query(&resolved, as_of).await?;
let latency_ms = (self.journal.clock().now() - started)
.num_milliseconds()
.max(0) as u64;
let assembly = assemble(records, budget)?;
let mut draft = EventDraft::new(RunEventKind::MemoryRead, Effect::ReadOnly)
.input(request)
.output(serde_json::to_value(&assembly)?)
.latency_ms(latency_ms);
if let Some(parent) = parent {
draft = draft.parent(parent);
}
self.journal.record(draft);
Ok(assembly)
}
MemorySource::Replay(source) => {
let served = source.serve(&request)?;
let _started = self.journal.clock().now();
let _ended = self.journal.clock().now();
let parent = parent
.or_else(|| served.event.parent.clone())
.unwrap_or_default();
served.rejournal(&self.journal, parent);
let output = served.output.clone().ok_or_else(|| {
replay_error(format!(
"recorded memory read at seq {} carries no assembly payload — the \
journal is inconsistent",
served.event.seq
))
})?;
let assembly: MemoryAssembly = serde_json::from_value(output)?;
Ok(assembly)
}
}
}
pub async fn write(&self, record: &MemoryRecord, parent: Option<String>) -> Result<String> {
match &self.source {
MemorySource::Store(store) => {
store.put(record).await?;
let effect_key = memory_effect_key(&record.scope, &record.memory_id);
let mut draft = EventDraft::new(RunEventKind::MemoryWrite, Effect::Idempotent)
.input(json!({
"effect_key": effect_key,
"memory_id": record.memory_id,
}))
.output(serde_json::to_value(record)?);
if let Some(parent) = parent {
draft = draft.parent(parent);
}
self.journal.record(draft);
Ok(record.memory_id.clone())
}
MemorySource::Replay(_) => Err(replay_error(
"memory writes are not served during replay: the run issued a write the \
recorded evidence does not contain — the replayed run has diverged from its \
evidence",
)),
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::journal::Clock;
fn ts(millis: i64) -> DateTime<Utc> {
DateTime::<Utc>::from_timestamp_millis(millis).unwrap()
}
fn provenance() -> MemoryProvenance {
MemoryProvenance {
author: ProvenanceAuthor::Human {
human_id: "amjad".into(),
},
evidence: MemoryEvidence::default(),
written_at: ts(1_000),
}
}
fn record(content: Value) -> MemoryRecord {
MemoryRecord::new(
MemoryKind::Fact,
ScopeAddress::new(MemoryScope::User, "user-7"),
provenance(),
1.0,
ValidityWindow::starting(ts(500)),
ts(1_000),
content,
)
.unwrap()
}
#[test]
fn scope_mapping_is_the_documented_superset() {
assert_eq!(
MemoryScope::from_state_scope(StateScope::Private),
Some(MemoryScope::Agent)
);
assert_eq!(
MemoryScope::from_state_scope(StateScope::Team),
Some(MemoryScope::Team)
);
assert_eq!(
MemoryScope::from_state_scope(StateScope::User),
Some(MemoryScope::User)
);
assert_eq!(
MemoryScope::from_state_scope(StateScope::Tenant),
Some(MemoryScope::Tenant)
);
assert_eq!(
MemoryScope::Agent.to_state_scope(),
Some(StateScope::Private)
);
assert_eq!(MemoryScope::Run.to_state_scope(), None);
for scope in [
MemoryScope::Run,
MemoryScope::Agent,
MemoryScope::Team,
MemoryScope::User,
MemoryScope::Tenant,
] {
if let Some(state_scope) = scope.to_state_scope() {
assert_eq!(MemoryScope::from_state_scope(state_scope), Some(scope));
}
}
}
#[test]
fn memory_id_is_a_content_address() {
let a = record(json!({"timezone": "UTC+4"}));
let b = record(json!({"timezone": "UTC+4"}));
let c = record(json!({"timezone": "UTC+1"}));
assert_eq!(a.memory_id, b.memory_id);
assert_eq!(a.memory_id.len(), 64);
assert_ne!(a.memory_id, c.memory_id);
let mut other_provenance = provenance();
other_provenance.written_at = ts(2_000);
let d = MemoryRecord::new(
MemoryKind::Fact,
ScopeAddress::new(MemoryScope::User, "user-7"),
other_provenance,
1.0,
ValidityWindow::starting(ts(500)),
ts(1_000),
json!({"timezone": "UTC+4"}),
)
.unwrap();
assert_ne!(a.memory_id, d.memory_id);
}
#[test]
fn confidence_outside_the_interval_is_rejected() {
for confidence in [0.0, -0.1, 1.01, f64::NAN] {
assert!(
MemoryRecord::new(
MemoryKind::Fact,
ScopeAddress::new(MemoryScope::User, "u"),
provenance(),
confidence,
ValidityWindow::starting(ts(0)),
ts(0),
json!(null),
)
.is_err(),
"confidence {confidence} must be rejected"
);
}
}
#[test]
fn content_split_follows_the_payload_discipline() {
let small = record(json!({"k": "v"}));
assert!(matches!(small.content, PayloadRef::Inline(_)));
let big = record(json!({"blob": "x".repeat(INLINE_PAYLOAD_MAX_BYTES)}));
let reference = match &big.content {
PayloadRef::Artifact(reference) => reference.clone(),
other => panic!("expected artifact reference, got {other:?}"),
};
assert_eq!(reference.bytes, big.content_bytes());
assert_eq!(
derive_memory_id(&big.content, &big.provenance).unwrap(),
big.memory_id
);
}
#[test]
fn estimated_tokens_applies_bytes_divisor_and_margin() {
assert_eq!(estimated_tokens(0, 20), 0);
assert_eq!(estimated_tokens(4, 0), 1);
assert_eq!(estimated_tokens(5, 0), 2); assert_eq!(estimated_tokens(400, 20), 120); assert_eq!(estimated_tokens(u64::MAX, 100), u32::MAX); }
#[tokio::test]
async fn journaled_write_is_idempotent_under_the_derived_key() {
let journal = Journal::new("run-1", "thread-1", Clock::System);
let store = Arc::new(InMemoryMemoryStore::new());
let memory = journal.memory(MemorySource::Store(store.clone()));
let record = record(json!({"a": 1}));
let id = memory.write(&record, None).await.unwrap();
assert_eq!(id, record.memory_id);
assert!(!store.put(&record).await.unwrap());
let events = journal.events();
assert_eq!(events.len(), 1);
let event = &events[0];
assert_eq!(event.kind, RunEventKind::MemoryWrite);
assert_eq!(event.effect, Effect::Idempotent);
let input = event.input.as_ref().unwrap();
let PayloadRef::Inline(input) = input else {
panic!("write request travels inline")
};
assert_eq!(
input["effect_key"].as_str().unwrap(),
memory_effect_key(&record.scope, &record.memory_id)
);
}
#[tokio::test]
async fn write_fails_during_replay() {
let journal = Journal::new("run-1", "thread-1", Clock::System);
let snapshot = journal.snapshot();
let memory = journal.memory(MemorySource::Replay(MemoryReplaySource::new(&snapshot)));
let err = memory
.write(&record(json!({"a": 1})), None)
.await
.unwrap_err();
assert!(matches!(err, RustyError::Replay(_)));
}
}