The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
Rust agent-orchestrationai-agentsai-assistantdesktopllmlocal-firstmcppersonal-aiprivacyrustsecond-braintauri
//! Memory sub-facade — one tenant's memory, read and managed by the host.
//!
//! An agent's turns already run TinyMemory's lifecycle on their own (the
//! pre-turn pack, the post-turn log, compaction recall, the `memory` tool),
//! under the memory binding its [`AgentSpec`](crate::AgentSpec) carries. What
//! a host still needs beside its agents is the operator's view of the same
//! memory: which agents have logged turns, what one of them remembers, the
//! shared learnings and brain documents, and a way to file or forget them.
//!
//! Before this existed a host had two routes, both wrong for a multi-tenant
//! host: reach into `openhuman_core::memory::*` with a hand-built config, or
//! invoke the `openhuman.memory_*` RPCs, which run against the ambient config
//! and so against whichever root that config happens to name. [`Memory`] is
//! bound to one layout root ([`Runtime::memory`](crate::Runtime::memory)) and
//! every call it makes is confined to that root's subtree:
//!
//! ```text
//! <root> shared learnings
//! ├── source:<kind> the brain: documents by source type
//! └── agent:<memory agent> one agent's conversations
//! ```
//!
//! - every read carries a reach of the root's subtree, so a filter cannot
//! widen it to a sibling tenant;
//! - [`Memory::forget`] forgets only ids the root's subtree holds — an id from
//! another tenant is left alone as if it named nothing;
//! - [`Memory::learn`] writes at the root, whatever the caller's metadata says,
//! and [`Memory::store`] writes at the root or one agent's node below it;
//! - [`Memory::search`] ranks only items the root's subtree holds, narrowed by
//! kind and tag.
//!
//! The engine is the one every agent uses: the configured `[memory]` engine,
//! or one the host installed with [`install_host_engine`]. With neither, memory
//! is off and every call but [`Memory::status`] answers
//! [`Error::Off`].
use openhuman_core::config::Config;
use openhuman_core::memory::engine::{self, Binding};
use openhuman_core::memory::{brain, explore, lifecycle, ops, types};
use tinymemory_api::{
ItemKind, MemoryMeta, MetaFilter, Namespace, Reach, StoreItem, StoreReceipt, WriteOptions,
};
use tinymemory_tools::MemoryLayout;
pub use openhuman_core::memory::brain::{
BrainForgetView, BrainIngestParams, BrainIngestView, BrainSearchView,
};
pub use openhuman_core::memory::engine::{clear_host_engine, install_host_engine};
pub use openhuman_core::memory::lifecycle::views::{AgentCount, AgentsView};
pub use openhuman_core::memory::types::{
FetchView, ForgetView, ItemsListView, LearnParams, LearnView, RecallView,
};
use tinymemory_api::{Error, Result};
pub use tinymemory_tools::{BrainSourceCount, BrainSourcesView};
/// The TinyMemory engine contract, for a host that implements or installs an
/// engine ([`install_host_engine`]) or reads the items this facade returns.
pub use tinymemory_api as api;
/// Largest page [`Memory::forget_agent`] lists at once.
const FORGET_PAGE: usize = 100;
/// Whether memory is on for a root, and with which engine.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
pub struct MemoryStatus {
/// The layout root.
pub root: String,
/// Whether an engine is bound.
pub on: bool,
/// The engine id, when known.
#[serde(skip_serializing_if = "Option::is_none")]
pub engine: Option<String>,
/// The engine endpoint, when known.
#[serde(skip_serializing_if = "Option::is_none")]
pub endpoint: Option<String>,
/// Why memory is off.
#[serde(skip_serializing_if = "Option::is_none")]
pub reason: Option<String>,
}
/// Which items [`Memory::list`] pages through.
#[derive(Debug, Clone, Default)]
pub struct ItemsQuery {
/// One memory agent's node (its conversations and the beliefs built
/// there); `None` lists the whole root.
pub agent_id: Option<String>,
/// Item kinds to include; empty means every kind.
pub kinds: Vec<ItemKind>,
/// Match an item carrying any one of these tags; empty means no constraint.
pub tags_any: Vec<String>,
/// Page size.
pub limit: Option<usize>,
/// Engine cursor of the next page.
pub cursor: Option<String>,
}
/// Which items [`Memory::search`] ranks.
#[derive(Debug, Clone, Default)]
pub struct SearchQuery {
/// What to rank the items against.
pub query: String,
/// One memory agent's node plus the root's items it inherits, as
/// [`Memory::recall`] reads it; `None` searches the whole root.
pub agent_id: Option<String>,
/// Item kinds to include; empty means every kind.
pub kinds: Vec<ItemKind>,
/// Match an item carrying any one of these tags; empty means no constraint.
pub tags_any: Vec<String>,
/// Most hits returned.
pub limit: Option<usize>,
}
/// One tenant's memory: every call confined to one layout root. See the
/// module docs.
#[derive(Clone)]
pub struct Memory {
config: Config,
layout: MemoryLayout,
}
impl std::fmt::Debug for Memory {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Memory")
.field("root", &self.layout.root().to_string())
.finish_non_exhaustive()
}
}
impl Memory {
/// Binds `base` to the layout root `root` (`team:acme`).
pub(crate) fn bind(mut base: Config, root: &str) -> Result<Self> {
let root = root.trim();
tinymemory_tools::layout::identity::validate_root(root).map_err(Error::InvalidRequest)?;
let namespace: Namespace = root
.parse()
.map_err(|error: tinymemory_api::Error| Error::InvalidRequest(error.to_string()))?;
if namespace.is_root() {
return Err(Error::InvalidRequest(
"a tenant's memory needs a root below the store root".into(),
));
}
let layout = MemoryLayout::new(namespace)?;
// The host binding outranks every identity, and the facade acts as the
// root one, so a call made from inside an agent's turn still lands on
// this root.
base.memory.root = Some(root.to_string());
base.memory.agent_id = None;
log::debug!("[embed][memory] bound root={root}");
Ok(Self {
config: base,
layout,
})
}
/// The layout root.
pub fn root(&self) -> String {
self.layout.root().to_string()
}
/// The node `agent_id`'s conversations live at.
pub fn agent_node(&self, agent_id: &str) -> Result<String> {
Ok(self.layout.conversations(agent_id)?.to_string())
}
/// Whether memory is on, and with what.
pub fn status(&self) -> MemoryStatus {
match engine::resolve(&self.config) {
Binding::On(bound) => MemoryStatus {
root: self.root(),
on: true,
engine: Some(bound.id),
endpoint: Some(bound.endpoint),
reason: None,
},
Binding::Off {
engine,
endpoint,
reason,
} => MemoryStatus {
root: self.root(),
on: false,
engine,
endpoint,
reason: Some(reason),
},
}
}
/// Whether an engine is bound.
pub fn is_on(&self) -> bool {
engine::is_on(&self.config)
}
/// The agents with logged turns under the root, most first.
pub async fn agents(&self) -> Result<AgentsView> {
lifecycle::views::agents_list(
&self.config,
&tinymemory_tools::layout::identity::Identity::root(),
)
.await
}
/// A page of items, newest first.
pub async fn list(&self, query: ItemsQuery) -> Result<ItemsListView> {
let reach = self.reach_of(query.agent_id.as_deref())?;
ops::items_list(
&self.config,
types::ItemsListParams {
filter: Some(MetaFilter {
reach: Some(reach),
kinds: query.kinds,
tags_any: query.tags_any,
..MetaFilter::default()
}),
limit: query.limit,
cursor: query.cursor,
path: Vec::new(),
preview: false,
},
)
.await
}
/// The items among `ids` the root holds.
pub async fn get(&self, ids: Vec<String>) -> Result<Vec<api::Hit>> {
let view = explore::items_get(
&self.config,
explore::ItemsGetParams {
ids,
reach: Some(self.subtree()),
},
)
.await?;
Ok(view.items)
}
/// Answers `question` from the root's memory, or from one agent's node
/// plus the shared learnings at the root above it.
pub async fn recall(
&self,
question: impl Into<String>,
agent_id: Option<&str>,
limit: Option<usize>,
) -> Result<RecallView> {
ops::recall(
&self.config,
types::RecallParams {
refers_to: None,
question: question.into(),
filter: Some(self.reading(agent_id)?),
limit,
},
)
.await
}
/// Ranked items matching `query` under the root, optionally of `kinds`.
pub async fn fetch(
&self,
query: impl Into<String>,
kinds: Vec<ItemKind>,
limit: Option<usize>,
) -> Result<FetchView> {
ops::fetch(
&self.config,
types::FetchParams {
refers_to: None,
query: query.into(),
mode: None,
filter: Some(MetaFilter {
reach: Some(self.subtree()),
kinds,
..MetaFilter::default()
}),
limit,
cursor: None,
},
)
.await
}
/// Ranked items matching `query.query` under the root, narrowed by kind
/// and tag: [`Memory::fetch`] for a host that files what it captures
/// under tags of its own and reads only some of them back.
pub async fn search(&self, query: SearchQuery) -> Result<FetchView> {
let mut filter = self.reading(query.agent_id.as_deref())?;
filter.kinds = query.kinds;
filter.tags_any = query.tags_any;
ops::fetch(
&self.config,
types::FetchParams {
refers_to: None,
query: query.query,
mode: None,
filter: Some(filter),
limit: query.limit,
cursor: None,
},
)
.await
}
/// Stores an item of any kind the host captured itself (a document, a
/// conversation, a learning) at the root, shared by every agent bound
/// there, or at `agent_id`'s node. The node is authoritative: a
/// namespace in the item's meta is overwritten. Everything else in the
/// meta (tags, source, `observed_at`, `observed_actor`) is kept, so an
/// identical item stored again is a replay
/// ([`StoreItem::fingerprint`](api::StoreItem::fingerprint)).
///
/// [`WriteOptions::accepted`] returns once the engine has durably
/// accepted the item, before it is readable: a capture on a live path,
/// or a bulk import that reads nothing back until it ends.
pub async fn store(
&self,
mut item: StoreItem,
agent_id: Option<&str>,
options: WriteOptions,
) -> Result<StoreReceipt> {
let node = match agent_id.map(str::trim).filter(|agent| !agent.is_empty()) {
Some(agent) => self.layout.conversations(agent)?,
None => self.layout.learnings().clone(),
};
item.meta_mut().namespace = node;
ops::store_item_with(&self.config, item, options).await
}
/// Stores a shared learning at the root. The root is authoritative: a
/// namespace in `params.meta` is overwritten.
pub async fn learn(&self, params: LearnParams) -> Result<LearnView> {
let host = MemoryMeta {
namespace: self.layout.learnings().clone(),
..MemoryMeta::default()
};
ops::learn(&self.config, params, Some(host)).await
}
/// Forgets the items among `ids` the root holds; any other id is left
/// alone.
pub async fn forget(&self, ids: Vec<String>) -> Result<ForgetView> {
ops::forget(
&self.config,
types::ForgetParams {
ids,
reach: Some(self.subtree()),
},
)
.await
}
/// Forgets everything stored at and below one agent's node: its logged
/// turns and the beliefs built from them. Returns how many were removed.
pub async fn forget_agent(&self, agent_id: &str) -> Result<usize> {
let mut forgotten = 0;
loop {
let page = self
.list(ItemsQuery {
agent_id: Some(agent_id.to_string()),
limit: Some(FORGET_PAGE),
..ItemsQuery::default()
})
.await?;
if page.items.is_empty() {
break;
}
let ids = page.items.into_iter().map(|hit| hit.id.0).collect();
let removed = self.forget(ids).await?.forgotten;
forgotten += removed;
// Nothing removed means the engine keeps listing items it will not
// forget; stop rather than loop on them.
if removed == 0 {
break;
}
}
log::debug!(
"[embed][memory] forgot agent root={} agent={agent_id} items={forgotten}",
self.root()
);
Ok(forgotten)
}
/// The brain's sources under the root and their sizes.
pub async fn brain_sources(&self) -> Result<BrainSourcesView> {
brain::sources(
&self.config,
&tinymemory_tools::layout::identity::Identity::root(),
)
.await
}
/// Brain documents matching `query`, optionally of one source.
pub async fn brain_search(
&self,
query: impl Into<String>,
source: Option<String>,
limit: Option<usize>,
) -> Result<BrainSearchView> {
brain::search(
&self.config,
&tinymemory_tools::layout::identity::Identity::root(),
brain::BrainSearchParams {
query: query.into(),
source,
limit,
},
)
.await
}
/// Files a document (a file on disk, or text) in the root's brain.
pub async fn brain_ingest(&self, params: BrainIngestParams) -> Result<BrainIngestView> {
brain::ingest(
&self.config,
&tinymemory_tools::layout::identity::Identity::root(),
params,
)
.await
}
/// Forgets every brain document of one source under the root.
pub async fn brain_forget(&self, source: impl Into<String>) -> Result<BrainForgetView> {
brain::forget(
&self.config,
&tinymemory_tools::layout::identity::Identity::root(),
brain::BrainForgetParams {
source: source.into(),
},
)
.await
}
fn subtree(&self) -> Reach {
Reach::subtree(self.layout.root().clone())
}
/// The reach a listing reads: the root's subtree, or one agent's node
/// and everything below it.
fn reach_of(&self, agent_id: Option<&str>) -> Result<Reach> {
match agent_id.map(str::trim).filter(|agent| !agent.is_empty()) {
Some(agent) => Ok(Reach {
at: self.layout.conversations(agent)?,
inherit: false,
descendants: true,
}),
None => Ok(self.subtree()),
}
}
/// What a recall reads: the whole root, or one agent's node with the
/// root's shared learnings it inherits — never a sibling agent's turns.
fn reading(&self, agent_id: Option<&str>) -> Result<MetaFilter> {
match agent_id.map(str::trim).filter(|agent| !agent.is_empty()) {
Some(agent) => Ok(MetaFilter {
reach: Some(Reach {
at: self.layout.conversations(agent)?,
inherit: true,
descendants: true,
}),
..MetaFilter::default()
}),
None => Ok(self.layout.holistic_filter()),
}
}
}
#[cfg(test)]
#[path = "memory_tests.rs"]
mod tests;