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

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 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, 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 acts as a thin façade that re-exports the entire contract:

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:

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:

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	Re-exports the entire contract surface as the memory::api namespace.
src/openhuman/memory/api/capabilities.rs	Capability definitions for provider feature detection.
src/openhuman/memory/api/chunks.rs	Chunk paging and metadata structures.
src/openhuman/memory/api/error.rs	Unified MemoryError enum definition.
src/openhuman/memory/api/provider.rs	MemoryProvider trait and configuration types.
src/openhuman/memory/api/wire.rs	Wire-format request/response structs for bus serialization.
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 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 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}