Skip to main content

tokio_memory/
lib.rs

1//! # tokio-memory
2//!
3//! Agent memory primitives for Tokio-based async agents.
4//!
5//! ## Modules
6//! - [`episodic`] — Time-ordered event memory (episodes, store, timeline).
7//! - [`semantic`] — Subject-predicate-object fact store.
8//! - [`working`] — Bounded priority-queue scratchpad.
9//! - [`decay`] — Memory strength decay policies (Ebbinghaus exponential).
10//! - [`retrieval`] — Fluent query builder for episodic recall.
11//! - [`consolidation`] — Policy-driven episode → fact promotion pipeline.
12//! - [`shared`] — Namespaced shared memory with conflict resolution.
13//! - [`persistence`] — Snapshot serialisation/deserialisation (postcard).
14//! - `sqlite` — Durable SQLite store with full-text search (`sqlite` feature).
15//! - [`error`] — Unified [`MemoryError`] type.
16//! - [`id`] — Strongly-typed ID newtypes.
17
18pub mod consolidation;
19pub mod decay;
20pub mod episodic;
21pub mod error;
22pub mod id;
23pub mod persistence;
24pub mod retrieval;
25pub mod semantic;
26pub mod shared;
27#[cfg(feature = "sqlite")]
28pub mod sqlite;
29pub mod working;
30
31// Convenience re-exports
32pub use error::MemoryError;
33pub use id::{AgentId, EntityId, MemoryId, NamespaceId, SessionId, Tag};
34
35#[cfg(test)]
36mod property_tests {
37    use proptest::prelude::*;
38
39    use crate::decay::decay::DecayPolicy;
40    use crate::decay::ebbinghaus::ExponentialDecay;
41    use crate::id::{AgentId, MemoryId, SessionId};
42    use crate::persistence::{decode_snapshot, encode_snapshot, MemorySnapshot};
43
44    proptest! {
45        #[test]
46        fn test_decay_strength_always_in_unit_interval(
47            half_life_secs in 0.001f64..=86400.0,
48            elapsed_secs in 0i64..=1_000_000i64,
49        ) {
50            let policy = ExponentialDecay::new(half_life_secs);
51            let created = chrono::Utc::now();
52            let now = created + chrono::Duration::seconds(elapsed_secs);
53            let s = policy.strength_at(created, now);
54            prop_assert!(s >= 0.0, "strength below 0: {s}");
55            prop_assert!(s <= 1.0, "strength above 1: {s}");
56        }
57
58        #[test]
59        fn test_memory_id_display_is_stable_proptest(
60            hi in any::<u64>(),
61            lo in any::<u64>(),
62        ) {
63            let bytes = {
64                let mut b = [0u8; 16];
65                b[..8].copy_from_slice(&hi.to_le_bytes());
66                b[8..].copy_from_slice(&lo.to_le_bytes());
67                b
68            };
69            let uuid = uuid::Uuid::from_bytes(bytes);
70            let id = MemoryId::from(uuid);
71            let s1 = id.to_string();
72            let s2 = id.to_string();
73            prop_assert_eq!(s1, s2);
74        }
75
76        #[test]
77        fn test_snapshot_roundtrip_preserves_all_episodes_proptest(
78            episode_count in 0usize..=10usize,
79        ) {
80            let agent = AgentId::new();
81            let session = SessionId::new();
82            let episodes: Vec<_> = (0..episode_count).map(|i| {
83                crate::episodic::episode::Episode::new(
84                    agent.clone(),
85                    session.clone(),
86                    crate::episodic::episode::EpisodeKind::Observation,
87                    format!("episode {i}"),
88                    0.8,
89                    vec![],
90                ).unwrap()
91            }).collect();
92            let snap = MemorySnapshot::new(agent, episodes, vec![]);
93            let bytes = encode_snapshot(&snap).unwrap();
94            let decoded = decode_snapshot(&bytes).unwrap();
95            prop_assert_eq!(decoded.episodes.len(), episode_count);
96        }
97    }
98}
99
100/// Every Rust example in the README is compiled by `cargo test --doc`.
101#[cfg(doctest)]
102#[doc = include_str!("../README.md")]
103mod readme_examples {}