feat: add Supermemory Mem0 and Cognee adapters

Co-authored-by: Medulla <medulla@tinyhumans.ai>

Author: senamakel

Cargo.lock

@@ -1,6 +1,6 @@
 [workspace]
-members = [".", "api", "core", "adapters/tinycortex"]
-default-members = [".", "api", "core", "adapters/tinycortex"]
+members = [".", "api", "core", "adapters/tinycortex", "adapters/remote"]
+default-members = [".", "api", "core", "adapters/tinycortex", "adapters/remote"]
 # `vendor/` holds engine submodules (tinycortex, tinybus, tinyagents), each of
 # which is its own workspace with its own lockfile. Same exclusion
 # `vendor/tinycortex` uses for its own nested vendor directory.

Cargo.toml

@@ -22,7 +22,8 @@ src/
 └── mandatory/          the three mandatory capability families, composed once
                         over the `Memory` storage trait
 adapters/
-└── tinycortex/         the TinyCortex engine seen through the contract
+├── tinycortex/         the TinyCortex engine seen through the contract
+└── remote/             native HTTP dialects for Supermemory, Mem0, and Cognee
 vendor/
 ├── tinycortex/         the engine, pinned as a submodule
 └── tinybus/            pinned TinyBus submodule
@@ -69,6 +70,25 @@ that skips enforcement is the entire reason the policy layer exists.
    widen `capabilities()` in lockstep with the accessors.
 4. Reserve the driver id: `DriverRegistry::builtin().with_reserved("my-engine", DriverClass::Embedded)`.
 
+## Remote engines
+
+The `tinymemory-remote` crate supports the self-hosted native APIs of
+Supermemory, Mem0, and Cognee. Each adapter stores TinyMemory's key, category,
+session, and provenance in backend metadata (or a Cognee raw-data envelope), so
+exact CRUD and portability survive the seam while recall remains engine-native.
+
+```rust
+use tinymemory_remote::{SupermemoryMemory, supermemory_provider};
+
+let memory = SupermemoryMemory::new("http://localhost:6767", Some("sm_..."))?;
+let provider = supermemory_provider(memory);
+# Ok::<_, anyhow::Error>(provider)
+```
+
+All three advertise the mandatory Core, Recall, and Portability families. The
+live Docker harness and conformance command are documented in
+[`integration/remote-engines/`](integration/remote-engines/README.md).
+
 ## Development
 
 ```bash

README.md

@@ -0,0 +1,42 @@
+[package]
+name = "tinymemory-remote"
+publish = false
+version = "0.1.0"
+edition = "2021"
+rust-version = "1.85"
+license = "MIT"
+description = "HTTP adapters for self-hosted Supermemory, Mem0, and Cognee"
+repository = "https://github.com/tinyhumansai/tinymemory"
+
+[dependencies]
+# The engine-neutral contract and mandatory-family composition.
+tinymemory = { path = "../.." }
+tinymemory-api = { path = "../../api" }
+# Memory is an object-safe async trait and each native HTTP dialect is async.
+async-trait = "0.1"
+# The storage trait deliberately uses opaque backend errors.
+anyhow = "1"
+# Native self-hosted APIs are HTTP/JSON; multipart is required by Cognee.
+reqwest = { version = "0.12", default-features = false, features = ["json", "multipart", "rustls-tls"] }
+# Remote records are translated through a private, lossless envelope.
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+# Supermemory custom ids are bounded, so namespace/key identities use SHA-256.
+sha2 = "0.10"
+
+[dev-dependencies]
+# Adapter tests run lightweight native-API doubles over a real TCP transport.
+axum = { version = "0.8", features = ["multipart"] }
+tokio = { version = "1", features = ["macros", "rt-multi-thread", "net"] }
+
+[lints.rust]
+unsafe_code = "forbid"
+missing_docs = "warn"
+unreachable_pub = "warn"
+
+[lints.clippy]
+all = { level = "warn", priority = -1 }
+unwrap_used = "warn"
+expect_used = "warn"
+panic = "warn"
+missing_errors_doc = "warn"

adapters/remote/Cargo.toml

@@ -0,0 +1,112 @@
+//! Live mandatory-family smoke test for a self-hosted remote engine.
+
+use std::sync::Arc;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use tinymemory_api::provider::MemoryProvider;
+use tinymemory_api::recall::OwnedRecallOpts;
+use tinymemory_api::types::{MemoryCategory, MemoryTaint};
+use tinymemory_remote::{
+    cognee_provider, mem0_provider, supermemory_provider, CogneeMemory, Mem0Memory,
+    SupermemoryMemory,
+};
+
+fn usage() -> anyhow::Error {
+    anyhow::anyhow!("usage: conformance <supermemory|mem0|cognee> <endpoint> [credential]")
+}
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let mut args = std::env::args().skip(1);
+    let engine = args.next().ok_or_else(usage)?;
+    let endpoint = args.next().ok_or_else(usage)?;
+    let credential = args.next();
+    let provider: Arc<dyn MemoryProvider> = match engine.as_str() {
+        "supermemory" => Arc::new(supermemory_provider(SupermemoryMemory::new(
+            &endpoint,
+            credential.as_deref(),
+        )?)),
+        "mem0" => Arc::new(mem0_provider(Mem0Memory::new(
+            &endpoint,
+            credential.as_deref(),
+        )?)),
+        "cognee" => Arc::new(cognee_provider(CogneeMemory::new(
+            &endpoint,
+            credential.as_deref(),
+        )?)),
+        _ => return Err(usage()),
+    };
+
+    tinymemory_api::provider::audit_provider(provider.as_ref())?;
+    let health = provider.health().await;
+    anyhow::ensure!(health.is_usable(), "driver health is {health:?}");
+
+    let suffix = SystemTime::now().duration_since(UNIX_EPOCH)?.as_nanos();
+    let namespace = format!("tinymemory-conformance-{suffix}");
+    let key = "native-round-trip";
+    let content = format!("TinyMemory native adapter conformance marker {suffix}");
+
+    provider
+        .store(
+            &namespace,
+            key,
+            &content,
+            MemoryCategory::Core,
+            Some("live-conformance"),
+            MemoryTaint::ExternalSync,
+        )
+        .await?;
+    let stored = provider
+        .get(&namespace, key)
+        .await?
+        .ok_or_else(|| anyhow::anyhow!("stored record was not readable"))?;
+    anyhow::ensure!(stored.content == content, "stored content changed");
+    anyhow::ensure!(
+        stored.taint == MemoryTaint::ExternalSync,
+        "stored taint changed"
+    );
+
+    let hits = provider
+        .recall(
+            "conformance marker",
+            10,
+            &OwnedRecallOpts {
+                namespace: Some(namespace.clone()),
+                ..OwnedRecallOpts::default()
+            },
+            None,
+        )
+        .await?;
+    anyhow::ensure!(!hits.is_empty(), "native recall returned no record");
+
+    let mut cursor = None;
+    let mut exported_keys = Vec::new();
+    loop {
+        let page = provider.export_page(cursor.as_deref(), 100).await?;
+        exported_keys.extend(page.records.iter().filter_map(|record| {
+            record
+                .payload
+                .get("key")
+                .and_then(serde_json::Value::as_str)
+                .map(str::to_owned)
+        }));
+        let Some(next) = page.next_cursor else {
+            break;
+        };
+        cursor = Some(next);
+    }
+    anyhow::ensure!(
+        exported_keys.iter().any(|exported| exported == key),
+        "portability export omitted the record; exported keys: {exported_keys:?}"
+    );
+    anyhow::ensure!(
+        provider.forget(&namespace, key).await?,
+        "forget missed record"
+    );
+
+    println!(
+        "{}: Core, Recall, and Portability passed",
+        provider.driver_id()
+    );
+    Ok(())
+}