# Understanding the Tinymemory-api Contract Surface in OpenHuman's Memory Subsystem

> Explore the tinymemory-api contract surface in OpenHuman's Memory subsystem. Learn how it ensures cross-process safety and version compatibility through serializable types and the MemoryProvider trait.

- Repository: [Tiny Humans/openhuman](https://github.com/tinyhumansai/openhuman)
- Tags: api-reference
- Published: 2026-08-24

---

**The tinymemory-api contract surface defines the strict communication boundary between OpenHuman's core and external memory modules, exposing only serializable types and the `MemoryProvider` trait through a thin façade in [`src/openhuman/memory/api/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/api/mod.rs) to ensure cross-process safety and version compatibility.**

The **tinymemory-api contract surface** serves as the authoritative interface for the Memory subsystem in the tinyhumansai/openhuman repository. This architectural boundary ensures that only explicitly exported symbols cross the module bus, preventing type mismatches between the core engine and dynamically loaded memory providers while maintaining a stable ABI for plugin developers.

## Contract Modules and Types Exposed by Tinymemory-api

The contract organizes functionality into thirteen distinct modules that define everything from capability discovery to wire-format serialization. According to the source code in [`vendor/tinymemory/crates/tinymemory-api/src/lib.rs`](https://github.com/tinyhumansai/openhuman/blob/main/vendor/tinymemory/crates/tinymemory-api/src/lib.rs), the following modules comprise the complete contract surface:

- **`capabilities`** – Describes provider abilities such as retrieval, chunking, and embedding generation.
- **`chunks`** – Defines chunk metadata structures, paging controls, and source-scoping types.
- **`error`** – Exports the unified **`MemoryError`** enum that both core and modules must handle.
- **`goals`** – Contains goal-related structures used for planning and continuation logic.
- **`health`** – Provides simple health-check request and response structs.
- **`provider`** – Defines the core **`MemoryProvider`** trait plus configuration types.
- **`provider::types`** – Detailed sub-types for provider configuration including token limits and rate limits.
- **`recall`** – Structures for the "recall" tool including search queries, filters, and pagination.
- **`tool_memory`** – Types specific to the tool-level memory API for request/response handling.
- **`tree`** – Tree navigation primitives including node IDs and parent/child links.
- **`types`** – Shared primitive types such as IDs and timestamps.
- **`wire`** – The canonical wire-format structs serialized over the bus; the source of truth for cross-process communication.
- **`CONTRACT_VERSION`** – A constant string identifying the contract version for compatibility negotiation.

## The Re-Export Architecture in src/openhuman/memory/api/mod.rs

The OpenHuman core does not duplicate these definitions. Instead, **[`src/openhuman/memory/api/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/api/mod.rs)** acts as a thin façade that re-exports the entire contract:

```rust
pub use tinymemory_api::{
    capabilities,
    chunks,
    error,
    goals,
    health,
    provider,
    provider::types as provider_types,
    recall,
    tool_memory,
    tree,
    types,
    wire,
    CONTRACT_VERSION,
};

```

This pattern ensures compile-time type equality between the core and loaded modules. Because both sides reference identical definitions from `tinymemory_api`, the Rust compiler prevents subtle bugs where the core and a module would otherwise use distinct type definitions.

## Design Principles for Cross-Process Safety

The contract surface enforces three critical architectural constraints:

**Cross-process safety** – All data crossing the module bus must be serializable. The contract modules contain only `serde`-compatible structs, ensuring that complex internal types never leak across process boundaries.

**Version stability** – The **`CONTRACT_VERSION`** constant allows the core to reject modules built against incompatible contract versions at load time, preventing runtime crashes due to API mismatches.

**Clear ownership boundaries** – Any type not listed in the thirteen exported modules remains internal to the core. Internal implementations such as `memory::binding::null` and the in-process engine stay hidden, giving the core freedom to refactor without breaking external contracts.

## Practical Implementation Examples

When implementing a memory provider or calling one from the core, you work exclusively with the types defined in the contract:

```rust
use openhuman::memory::api::{provider::MemoryProvider, error::MemoryError, wire};

// Constructing a request that any module can understand
let request = wire::RetrieveRequest {
    query: "recent meeting notes".into(),
    limit: Some(10),
    filters: None,
};

// Calling the provider from the core side
async fn retrieve(
    provider: &dyn MemoryProvider,
    req: wire::RetrieveRequest,
) -> Result<wire::RetrieveResponse, MemoryError> {
    provider.retrieve(req).await
}

```

Error handling uses the unified enum defined in the contract:

```rust
match retrieve(&my_provider, request).await {
    Ok(resp) => println!("Got {} results", resp.results.len()),
    Err(MemoryError::Unavailable) => eprintln!("Memory backend is offline"),
    Err(e) => eprintln!("Memory error: {:?}", e),
}

```

## Key Source Files Defining the Contract

| File | Role |
|------|------|
| [`src/openhuman/memory/api/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/api/mod.rs) | Re-exports the entire contract surface as the `memory::api` namespace. |
| [`src/openhuman/memory/api/capabilities.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/api/capabilities.rs) | Capability definitions for provider feature detection. |
| [`src/openhuman/memory/api/chunks.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/api/chunks.rs) | Chunk paging and metadata structures. |
| [`src/openhuman/memory/api/error.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/api/error.rs) | Unified `MemoryError` enum definition. |
| [`src/openhuman/memory/api/provider.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/api/provider.rs) | `MemoryProvider` trait and configuration types. |
| [`src/openhuman/memory/api/wire.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/api/wire.rs) | Wire-format request/response structs for bus serialization. |
| [`vendor/tinymemory/crates/tinymemory-api/src/lib.rs`](https://github.com/tinyhumansai/openhuman/blob/main/vendor/tinymemory/crates/tinymemory-api/src/lib.rs) | Original contract crate serving as the source of truth. |

## Summary

- The tinymemory-api contract surface consists of thirteen modules that strictly define the Memory subsystem's external boundary.
- All types are re-exported through [`src/openhuman/memory/api/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/api/mod.rs) to guarantee compile-time type equality between core and modules.
- The contract requires `serde`-compatible types for cross-process safety and exposes `CONTRACT_VERSION` for runtime compatibility checking.
- Only symbols explicitly listed in the contract may cross the module bus; everything else remains internal to the core implementation.
- New API methods must be added to `tinymemory-api` first; missing methods result in `Unsupported` errors rather than undefined behavior or serialization failures.

## Frequently Asked Questions

### What is the tinymemory-api contract surface in OpenHuman?

The tinymemory-api contract surface is the formal interface boundary that allows OpenHuman's core to communicate with external memory modules. It defines the exact types, traits, and constants—such as `MemoryProvider` and `MemoryError`—that may be serialized across the module bus, ensuring type safety and version compatibility between the core and dynamically loaded plugins.

### How does the core ensure type safety with dynamically loaded modules?

The core enforces type safety by re-exporting all contract types from [`src/openhuman/memory/api/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/api/mod.rs) as a thin façade over the `tinymemory_api` crate. This guarantees that both the core and loaded modules reference identical type definitions, preventing the "distinct type" bugs that would occur if each side defined its own versions of the same structures.

### What happens if a memory module uses an incompatible contract version?

If a module was compiled against a different version of the contract, the core detects the mismatch using the `CONTRACT_VERSION` constant and rejects the module with an `Unsupported` error. This prevents runtime crashes and undefined behavior that would result from serialization mismatches or missing method implementations.

### Where is the source of truth for the memory API defined?

The canonical source of truth resides in [`vendor/tinymemory/crates/tinymemory-api/src/lib.rs`](https://github.com/tinyhumansai/openhuman/blob/main/vendor/tinymemory/crates/tinymemory-api/src/lib.rs), which defines the thirteen contract modules. The OpenHuman core treats this crate as the single source of truth and re-exports its contents without modification, ensuring that `memory::api` is always synchronized with the underlying contract.