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
docs(storage): describe the storage runtime and URL-sourced embed storage
oxoxDev91ed7b7e173d
diff --git a/crates/openhuman-core/src/storage/README.md b/crates/openhuman-core/src/storage/README.mdindex 2f728f470b..cf60238b77 100644--- a/crates/openhuman-core/src/storage/README.md+++ b/crates/openhuman-core/src/storage/README.md@@ -89,7 +89,10 @@ it with the core stopped.## Entry points- `configured_url(&Config)` / `url_from(env, &Config)`: the URL in effect.-- `open(url)`: parse and open a backend (credentials are redacted in logs).+- `open(url)`: parse and open a backend (credentials are redacted in logs) The+ driver connects on the process's storage runtime (two `openhuman-storage`+ worker threads, alive for the whole process), so a driver's background tasks+ (MongoDB's connection pool and monitors) never depend on the host runtime.- `install(backend)` / `installed()` / `clear()`: the process slot domainsread the backend from.- `scope_for_agent(agent_id)`: the storage scope (`local/agent:<id>`) an agent's records live@@ -120,7 +123,9 @@ it with the core stopped.host; an error in SaaS mode without a profile — and the installed backendunder it.- `block_on(future)`: runs a storage future from synchronous store code on- one shared runtime thread.+ one shared runtime thread. The future depends only on that thread and the+ storage runtime, so callers blocked on it cannot starve the host runtime of+ the threads a backend needs.- `documents::Repo` and `documents::compare_and_swap`: the base the domainstores build on. A `Repo` holds one domain's scoped document handle,declares its collections and runs each call on the blocking bridge;diff --git a/crates/openhuman-embed/src/runtime/seams.rs b/crates/openhuman-embed/src/runtime/seams.rsindex a0fcfbcd8f..834fb107a7 100644--- a/crates/openhuman-embed/src/runtime/seams.rs+++ b/crates/openhuman-embed/src/runtime/seams.rs@@ -48,7 +48,9 @@ pub enum StorageSource {/// A storage URL (`sqlite://…`, `memory`, `mongodb://…`), opened when the/// runtime is built. A URL that cannot be opened fails the build.Url(String),- /// A backend the host already opened.+ /// A backend the host already opened. Pass a MongoDB backend as a+ /// [`Url`](Self::Url) instead, so its connection pool runs on the core's+ /// storage runtime rather than the host's.Backend(Arc<dyn StorageBackend>),}@@ -110,8 +112,8 @@ impl HostSeams {Ok(())}- /// [`open_storage`](Self::open_storage) from synchronous code, on the- /// core's dedicated storage runtime thread so the backend outlives the call.+ /// [`open_storage`](Self::open_storage) from synchronous code. The backend+ /// is opened on the core's storage runtime, so it outlives the call.pub(crate) fn open_storage_blocking(&mut self) -> Result<(), String> {let Some(StorageSource::Url(url)) = self.storage.take() else {return Ok(());diff --git a/docs/gitbooks/en/developing/architecture/storage.md b/docs/gitbooks/en/developing/architecture/storage.mdindex b78cfb8764..291591bddd 100644--- a/docs/gitbooks/en/developing/architecture/storage.md+++ b/docs/gitbooks/en/developing/architecture/storage.md@@ -97,6 +97,10 @@ Background work runs under the process default context, which names no agent, anOn a shared backend (MongoDB) other processes may write the same records, so boot-time recovery such as the orphaned-run sweep is skipped (`storage::installed_is_shared`).+### The storage runtime++`storage::open` connects the driver on a process-wide tokio runtime of its own (two `openhuman-storage` worker threads, never shut down). A driver's background tasks, such as the MongoDB client's connection pool and server monitors, live there and not on the host's runtime. Synchronous stores reach the ports through `storage::block_on`, which parks the calling thread; with the backend on the storage runtime, any number of parked callers cannot leave the host runtime without the threads the backend needs to answer them. An embedder that wants this isolation passes its storage as a URL (`StorageSource::Url`) rather than a backend it opened on its own runtime.+## Drivers and on-disk layout| Driver | Where the data lives |