Merge pull request #74 from tinyhumansai/tinymemory-bus

Move the wire vocabulary into tinymemory-bus, beneath tinymemory-api

Author: senamakel

Cargo.lock

@@ -21,6 +21,7 @@ members = ["crates/*"]
 default-members = [
     "crates/tinymemory",
     "crates/tinymemory-api",
+    "crates/tinymemory-bus",
     "crates/tinymemory-conformance",
     "crates/tinymemory-core",
     "crates/tinymemory-remote",

Cargo.toml

@@ -20,9 +20,17 @@ crates/
 │   │                   binds as, and the fail-closed external-driver gate
 │   ├── tests/          integration tests against the public API only
 │   └── examples/       runnable, compiled-in-CI usage examples
-├── tinymemory-api/     the contract. Dependency-light on purpose: depending on
-│                       it never drags in SQLite, git2, reqwest, or an async
-│                       runtime
+├── tinymemory-api/     the driver contract: the traits an engine implements and
+│                       the host seam it binds through, plus every
+│                       `tinymemory-bus` type re-exported at its historical path.
+│                       Dependency-light on purpose: depending on it never drags
+│                       in SQLite, git2, reqwest, or an async runtime
+├── tinymemory-bus/     the wire vocabulary: every type that crosses the module
+│                       boundary, plus the member names. Sits *below* the
+│                       contract — `tinymemory-api` depends on it and re-exports
+│                       it — so a host that only makes calls into
+│                       `tinymemory-module` links this alone and compiles no
+│                       traits, no null driver and no config surface
 ├── tinymemory-core/    the substance: ingestion, the summary tree, chunk
 │                       storage, entities, the graph, the diff ledger, goals,
 │                       tool-memory, and the Composio sync layer. The largest

README.md

@@ -2,4 +2,15 @@
 # a code item that forgot its backticks. These are product and technology names
 # written as prose on purpose; backticking them would imply they name a Rust
 # item. `..` keeps clippy's own default list rather than replacing it.
-doc-valid-idents = ["..", "TinyMemory", "TinyCortex", "OpenHuman", "SQLite", "snake_case"]
+doc-valid-idents = [
+    "..",
+    "TinyMemory",
+    "TinyCortex",
+    "OpenHuman",
+    "TinyBus",
+    "SQLite",
+    "snake_case",
+    # Product names in `chunks::SourceKind`'s prose, not Rust items.
+    "WhatsApp",
+    "FastMail",
+]

clippy.toml

@@ -11,28 +11,29 @@ license = "MIT"
 repository = "https://github.com/tinyhumansai/tinymemory"
 description = "Stable public contracts for the TinyMemory memory system"
 
-# Deliberately dependency-light: this crate is the stable contract surface that
-# hosts compile against, so it must stay free of native, async-runtime, and
-# storage dependencies. Anything heavier belongs in the `tinycortex` engine
-# crate, never here.
+# Deliberately dependency-light: this crate is the driver contract an engine
+# compiles against, so it must stay free of native, async-runtime, and storage
+# dependencies. Anything heavier belongs in the `tinycortex` engine crate, never
+# here.
 #
-# The full set is intentionally small and pure-Rust. Beyond the
-# serde/error/async-trait baseline it carries exactly three additions, each
-# pulled in by a value type that has to keep behaving identically after the
-# move out of the engine crate:
+# The set shrank when the payload vocabulary moved to `tinymemory-bus`:
+# `chrono`, `sha2` and `uuid` went with the types that needed them
+# (`chunks::Metadata`, `chunks::chunk_id`, `ToolMemoryRule::generate_id`), and
+# `thiserror` went with `MemoryError`. What is left is what the *traits* and the
+# host seam need:
 #
-# - `chrono`  — timestamps on chunk/tree nodes; the `serde` feature backs
-#               `chunks::Metadata`'s `chrono::serde::ts_milliseconds`.
-# - `sha2`    — the deterministic `chunks::chunk_id`.
-# - `uuid`    — `tool_memory::ToolMemoryRule::generate_id` (v4 bytes, nibble
-#               encoded). Only the `v4` feature is needed here; the engine
-#               crate additionally enables `serde`.
-# - `schemars` — the `host::` config sections are still fields of the host's
-#               root `Config`, which derives `JsonSchema` to generate the
-#               settings schema the UI renders. Dropping the derive on the way
-#               down here would silently shrink that schema. `schemars` is pure
-#               Rust (serde + serde_json + dyn-clone + ref-cast) and carries
-#               none of the forbidden dependencies below.
+# - `async-trait` — every capability-family trait is `async fn` on an
+#                   object-safe trait.
+# - `anyhow`      — `traits::Memory` and the mandatory composition are
+#                   anyhow-typed.
+# - `schemars`    — the `host::` config sections are still fields of the host's
+#                   root `Config`, which derives `JsonSchema` to generate the
+#                   settings schema the UI renders. Dropping the derive on the
+#                   way down here would silently shrink that schema. `schemars`
+#                   is pure Rust (serde + serde_json + dyn-clone + ref-cast).
+# - `log`         — the `host::cloud_providers` legacy-field migration logs what
+#                   it rewrote. The zero-dependency facade, not an
+#                   implementation.
 #
 # Nothing here may pull in `rusqlite`, `git2`, `reqwest`, `regex`, or an async
 # runtime. Guard with the FORWARD form, which is scoped to this package:
@@ -44,18 +45,17 @@ description = "Stable public contracts for the TinyMemory memory system"
 # scope and prints the whole-workspace inverse tree, so it exits 0 and looks
 # clean even when this crate is the one pulling the dependency in.
 [dependencies]
+# The wire vocabulary. Every payload type this crate exposes is defined there
+# and re-exported here, so a host that only makes calls into the loadable module
+# can depend on that crate alone and compile none of the traits, the null
+# driver, or the `host::` config surface. See `src/lib.rs`.
+tinymemory-bus = { path = "../tinymemory-bus" }
 anyhow = "1"
 async-trait = "0.1"
-chrono = { version = "0.4", features = ["serde"] }
-# `log` is the zero-dependency logging facade, not an implementation. The
-# `host::cloud_providers` legacy-field migration logs what it rewrote.
 log = "0.4"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 schemars = "1.2"
-sha2 = "0.11"
-thiserror = "2"
-uuid = { version = "1", features = ["v4"] }
 
 [dev-dependencies]
 # The moved `host::` config sections are parsed from TOML in their own tests,

crates/tinymemory-api/Cargo.toml

@@ -52,7 +52,6 @@ mod embedding_host;
 mod embeddings;
 mod error_reporter;
 mod events;
-mod evidence;
 mod nlp;
 mod routes;
 mod usage;
@@ -72,7 +71,6 @@ pub use events::{
     EmbeddingHealthReason, MemoryEvent, MemoryEventSink, NoopEventSink, SyncTrigger,
     LOCAL_MODEL_UNAVAILABLE_KIND, MEMORY_USER_ERROR_SOURCE,
 };
-pub use evidence::EvidenceRef;
 pub use local_ai::{LocalAiConfig, LocalAiUsage};
 pub use nlp::{SpacyEntity, SpacyResponse};
 pub use routes::EmbeddingRouteConfig;
@@ -84,6 +82,7 @@ pub use storage_memory::{
 pub use subsystems::{
     MemoryDriverConfig, MemoryHooksConfig, MemorySubsystemConfig, SubsystemsConfig,
 };
+pub use tinymemory_bus::evidence::EvidenceRef;
 pub use usage::UsageInfo;
 
 /// Effective default global memory-sync cadence (seconds) used when

crates/tinymemory-api/src/host/mod.rs

@@ -1,15 +1,32 @@
 //! Stable public contracts for the TinyMemory memory system.
 //!
-//! This crate holds the value types, error enum, capability vocabulary, and
-//! storage trait that memory engines and their embedding hosts compile
-//! against. It is engine-neutral on purpose: `tinycortex` is the default
-//! embedded engine, not the owner of the contract, and a second engine
-//! (`supermemory`, `mem0`, a self-hosted HTTP backend) implements the same
-//! traits without either engine learning about the other.
-//! It is deliberately dependency-light (serde / serde_json /
-//! chrono / sha2 / anyhow / thiserror / async-trait / uuid only) so depending on
-//! the contract never drags in SQLite, git2, reqwest, regex, or an async
-//! runtime.
+//! This crate holds the traits a memory engine implements, the host seam it is
+//! bound through, and — re-exported from [`tinymemory_bus`] — the value types,
+//! error enum and capability vocabulary they exchange. It is engine-neutral on
+//! purpose: `tinycortex` is the default embedded engine, not the owner of the
+//! contract, and a second engine (`supermemory`, `mem0`, a self-hosted HTTP
+//! backend) implements the same traits without either engine learning about the
+//! other. It is deliberately dependency-light (serde / serde_json / anyhow /
+//! async-trait / schemars / log, plus `tinymemory-bus`) so depending on the
+//! contract never drags in SQLite, git2, reqwest, regex, or an async runtime.
+//!
+//! ## The vocabulary lives one layer down
+//!
+//! Every payload type is defined in [`tinymemory_bus`] and re-exported here at
+//! its historical path, so `tinymemory_api::types::MemoryEntry` is the *same
+//! item* as `tinymemory_bus::types::MemoryEntry`, not a structural twin.
+//!
+//! The split follows what a consumer actually needs. A **driver author**
+//! implements [`provider::MemoryProvider`] and wants this crate: traits, the
+//! null driver, the mandatory composition, the [`host`] seam. A **host** loads
+//! `tinymemory-module` over `TinyBus` and only makes calls — it names
+//! `MemoryEntry` and `MemoryCategory` and implements nothing — so it depends on
+//! `tinymemory-bus` alone and compiles none of this.
+//!
+//! Defining a second set of payload types for that host was the alternative,
+//! and it is the failure the root manifest's `[patch]` table exists to prevent:
+//! `MemoryCategory` from the module would not be `MemoryCategory` in the host,
+//! with a conversion at every call site that nothing type-checks.
 //!
 //! ## Self-contained by design
 //!
@@ -64,13 +81,26 @@
 //!   round-trips [`error::MemoryError`] through. Shared by both ends of every
 //!   such transport, so the names cannot drift apart.
 
-pub mod capabilities;
-pub mod chunks;
 pub mod drivers;
-pub mod error;
-pub mod goals;
-pub mod health;
 pub mod host;
+
+// The wire vocabulary, re-exported from `tinymemory-bus`.
+//
+// These modules used to be defined here. They moved down a layer because a
+// *host* needs them and needs nothing else in this crate: it loads
+// `tinymemory-module` and makes calls, so it names `MemoryEntry` and
+// `MemoryCategory` but implements no trait, binds no driver and parses no
+// config. Making it depend on the whole driver contract to spell a payload type
+// was the wrong shape.
+//
+// Re-exported rather than merely available, so every historical path still
+// resolves — `tinymemory_api::types::MemoryEntry` is the same item as
+// `tinymemory_bus::types::MemoryEntry`, not a twin of it. That identity is the
+// point: a second definition would need a conversion at the module seam that
+// nothing type-checks.
+pub use tinymemory_bus::{
+    capabilities, chunks, error, goals, health, recall, tool_memory, tree, types, version, wire,
+};
 /// The mandatory-family composition: wrap any [`traits::Memory`] backend as a
 /// complete [`provider::MemoryProvider`].
 ///
@@ -84,12 +114,6 @@ pub mod host;
 pub mod mandatory;
 pub mod null;
 pub mod provider;
-pub mod recall;
-pub mod tool_memory;
 pub mod traits;
-pub mod tree;
-pub mod types;
-pub mod version;
-pub mod wire;
 
-pub use version::{is_compatible, CONTRACT_VERSION};
+pub use tinymemory_bus::{is_compatible, CONTRACT_VERSION};

crates/tinymemory-api/src/lib.rs

@@ -31,90 +31,16 @@
 //! `docs/specs/2026-08-13-memory-module-port.md` §3.
 
 use async_trait::async_trait;
-use serde::{Deserialize, Serialize};
 
-use crate::chunks::{Chunk, SourceKind};
+use crate::chunks::Chunk;
 use crate::error::MemoryError;
 use crate::provider::types::SourceScope;
 
-/// Filters for [`MemoryChunks::list_chunks`].
-///
-/// Every field is optional and they compose with AND. The default matches
-/// everything the scope allows, bounded by the driver's own safety cap.
-#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
-pub struct ChunkQuery {
-    /// Restrict to one source kind.
-    #[serde(default)]
-    pub source_kind: Option<SourceKind>,
-    /// Restrict to one logical source id.
-    #[serde(default)]
-    pub source_id: Option<String>,
-    /// Restrict to one owner.
-    #[serde(default)]
-    pub owner: Option<String>,
-    /// Inclusive lower bound on source time, epoch milliseconds.
-    #[serde(default)]
-    pub since_ms: Option<i64>,
-    /// Inclusive upper bound on source time, epoch milliseconds.
-    #[serde(default)]
-    pub until_ms: Option<i64>,
-    /// Maximum rows. The driver clamps this to its own cap — a caller cannot
-    /// raise the ceiling by asking for more.
-    #[serde(default)]
-    pub limit: Option<usize>,
-    /// Rows to skip, for pagination.
-    #[serde(default)]
-    pub offset: Option<usize>,
-    /// Drop chunks marked dropped by the lifecycle.
-    #[serde(default)]
-    pub exclude_dropped: bool,
-}
-
-/// One chunk's stored embedding.
-///
-/// Returned as a list rather than a map because the wire form of a map keyed by
-/// chunk id is a JSON object, and an id is caller-supplied text; a list keeps
-/// the encoding independent of what an id happens to contain.
-#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
-pub struct ChunkEmbedding {
-    /// The chunk this vector belongs to.
-    pub chunk_id: String,
-    /// The vector, in the embedding space named by the requested signature.
-    pub vector: Vec<f32>,
-}
-
-/// One chunk plus the per-chunk facts stored beside it.
-///
-/// # Why a detail view rather than four accessors
-///
-/// An inspection caller wants the row, its body, where the body lives, its
-/// lifecycle state and whether it has been embedded. Exposing those as four
-/// methods would read naturally in-process and cost **four bus round trips per
-/// row** out of it — and this is used to render lists. One method, one trip.
-#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
-pub struct ChunkDetail {
-    /// The chunk row.
-    pub chunk: Chunk,
-    /// The chunk's body as stored in the content vault, when it could be read.
-    ///
-    /// `None` means the vault read failed — distinct from an empty body, which
-    /// is a legitimately empty chunk. A caller rendering a preview should fall
-    /// back to [`Chunk::content`] rather than showing nothing.
-    #[serde(default)]
-    pub body: Option<String>,
-    /// Path of the body in the content vault, when it has one.
-    #[serde(default)]
-    pub content_path: Option<String>,
-    /// Lifecycle state (`active`, `dropped`, …); `None` when unrecorded.
-    #[serde(default)]
-    pub lifecycle_status: Option<String>,
-    /// Whether an embedding vector exists for this chunk in **any** space.
-    ///
-    /// Not scoped to a signature on purpose: this answers "has this been
-    /// embedded at all", which is what an inspection view wants. Asking whether
-    /// a *particular* space has it is [`MemoryChunks::chunk_embeddings`].
-    pub has_embedding: bool,
-}
+// The value types this family exchanges. They are defined in `tinymemory-bus`
+// — they cross the module boundary, and a host that only makes calls must be
+// able to name them without compiling this trait — and re-exported here so
+// every historical path keeps resolving and the types stay the same types.
+pub use tinymemory_bus::provider::chunks::{ChunkDetail, ChunkEmbedding, ChunkQuery};
 
 /// Direct read access to the chunk tier.
 ///