Merge remote-tracking branch 'origin/main' into memory-module-port

# Conflicts:
#	vendor/tinycortex

Author: senamakel

Cargo.lock

@@ -72,19 +72,40 @@ that skips enforcement is the entire reason the policy layer exists.
 
 ## 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.
+The `tinymemory-remote` crate supports the managed and self-hosted native APIs
+of Supermemory and Cognee, plus self-hosted Mem0. 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. Provider-facing dataset names, container tags,
+and filenames are bounded stable hashes, so every namespace and key accepted by
+the TinyMemory contract remains valid on the remote API.
 
 ```rust
 use tinymemory_remote::{SupermemoryMemory, supermemory_provider};
 
-let memory = SupermemoryMemory::new("http://localhost:6767", Some("sm_..."))?;
+let memory = SupermemoryMemory::self_hosted("http://localhost:6767", "sm_...")?;
 let provider = supermemory_provider(memory);
 # Ok::<_, anyhow::Error>(provider)
 ```
 
+Managed APIs have explicit constructors so their authentication cannot be
+confused with a self-hosted token:
+
+```rust
+use tinymemory_remote::{CogneeMemory, SupermemoryMemory};
+
+let cognee = CogneeMemory::cloud("cognee-api-key")?;
+let supermemory = SupermemoryMemory::cloud("sm_...")?;
+
+// Cognee also issues tenant-specific API origins.
+let tenant = CogneeMemory::api("https://tenant.example.cognee.ai", "api-key")?;
+# Ok::<_, anyhow::Error>((cognee, supermemory, tenant))
+```
+
+Cognee Cloud uses `X-Api-Key`; authenticated self-hosted Cognee uses a bearer
+access token. Supermemory uses bearer API keys for both deployment modes. All
+constructors redact credentials from `Debug` output and transport errors.
+
 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).

README.md

@@ -13,7 +13,9 @@ use tinymemory_remote::{
 
 /// Builds the command-line usage error returned for invalid arguments.
 fn usage() -> anyhow::Error {
-    anyhow::anyhow!("usage: conformance <supermemory|mem0|cognee> <endpoint> [credential]")
+    anyhow::anyhow!(
+        "usage: conformance <supermemory|mem0|cognee|cognee-api> <endpoint> [credential]"
+    )
 }
 
 #[tokio::main]
@@ -36,6 +38,12 @@ async fn main() -> anyhow::Result<()> {
             &endpoint,
             credential.as_deref(),
         )?)),
+        "cognee-api" => Arc::new(cognee_provider(CogneeMemory::api(
+            &endpoint,
+            credential
+                .as_deref()
+                .ok_or_else(|| anyhow::anyhow!("cognee-api requires a credential"))?,
+        )?)),
         _ => return Err(usage()),
     };
 

adapters/remote/examples/conformance.rs

@@ -8,19 +8,22 @@ use tinymemory_api::recall::RecallOpts;
 use tinymemory_api::traits::Memory;
 use tinymemory_api::types::MemoryTaint;
 
-use crate::common::{encode, Dialect, HttpClient, RemoteMemory, StoredEntry};
+use crate::common::{stable_id, Dialect, HttpClient, RemoteMemory, StoredEntry};
 
 /// Stable driver id used by configuration and status output.
 pub use tinymemory::registry::COGNEE_DRIVER_ID;
 
-/// A self-hosted Cognee server exposed through TinyMemory's storage contract.
+/// Default base URL for Cognee's managed API.
+pub const COGNEE_API_ENDPOINT: &str = "https://api.cognee.ai";
+
+/// A Cognee managed or self-hosted service exposed through TinyMemory's contract.
 #[derive(Debug)]
 pub struct CogneeMemory {
     inner: RemoteMemory<CogneeDialect>,
 }
 
 impl CogneeMemory {
-    /// Connect to a Cognee server.
+    /// Connect to a self-hosted Cognee server.
     ///
     /// `access_token` is sent as a bearer token. Local deployments with
     /// backend access control disabled may pass `None`.
@@ -29,12 +32,53 @@ impl CogneeMemory {
     ///
     /// Returns an error when `endpoint` is not an HTTP(S) URL.
     pub fn new(endpoint: &str, access_token: Option<&str>) -> anyhow::Result<Self> {
+        Self::self_hosted(endpoint, access_token)
+    }
+
+    /// Connect to a self-hosted Cognee server.
+    ///
+    /// `access_token` is sent as a bearer token. Local deployments with
+    /// authentication disabled may pass `None`.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error when `endpoint` is not an HTTP(S) URL.
+    pub fn self_hosted(endpoint: &str, access_token: Option<&str>) -> anyhow::Result<Self> {
         Ok(Self {
             inner: RemoteMemory::new(CogneeDialect {
                 client: HttpClient::bearer(endpoint, access_token)?,
             }),
         })
     }
+
+    /// Connect to a Cognee managed API using `X-Api-Key` authentication.
+    ///
+    /// This accepts a custom endpoint because Cognee Cloud may issue a
+    /// tenant-specific base URL. Use [`Self::cloud`] for the shared default.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error when `endpoint` is invalid or `api_key` is blank.
+    pub fn api(endpoint: &str, api_key: &str) -> anyhow::Result<Self> {
+        anyhow::ensure!(
+            !api_key.trim().is_empty(),
+            "cognee API key must not be empty"
+        );
+        Ok(Self {
+            inner: RemoteMemory::new(CogneeDialect {
+                client: HttpClient::api_key(endpoint, Some(api_key))?,
+            }),
+        })
+    }
+
+    /// Connect to Cognee's shared managed API endpoint.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error when `api_key` is blank.
+    pub fn cloud(api_key: &str) -> anyhow::Result<Self> {
+        Self::api(COGNEE_API_ENDPOINT, api_key)
+    }
 }
 
 #[async_trait]
@@ -128,11 +172,11 @@ struct Dataset {
 impl CogneeDialect {
     /// Encodes a TinyMemory namespace as a collision-free Cognee dataset name.
     fn dataset_name(namespace: &str) -> String {
-        format!("tinymemory__{}", encode(namespace))
+        format!("tinymemory__{}", stable_id("dataset", namespace))
     }
     /// Encodes a TinyMemory key as the uploaded envelope's filename.
     fn filename(key: &str) -> String {
-        format!("{}.tinymemory.json", encode(key))
+        format!("{}.tinymemory.json", stable_id("key", key))
     }
 
     /// Discovers only datasets owned by the TinyMemory adapter.
@@ -239,33 +283,45 @@ impl Dialect for CogneeDialect {
 
     /// Replaces an existing envelope and uploads the new exact record.
     async fn upsert(&self, entry: StoredEntry) -> anyhow::Result<()> {
-        if let Some(existing) = self
+        let existing = self
             .entries()
             .await?
             .into_iter()
-            .find(|item| item.namespace == entry.namespace && item.key == entry.key)
-        {
-            self.delete_entry(&existing).await?;
-        }
+            .find(|item| item.namespace == entry.namespace && item.key == entry.key);
         let body = serde_json::to_vec(&entry)?;
-        let form = multipart::Form::new()
-            .text("datasetName", Self::dataset_name(&entry.namespace))
-            .text("run_in_background", "false")
-            .part(
-                "data",
-                multipart::Part::bytes(body)
-                    .file_name(Self::filename(&entry.key))
-                    .mime_str("application/json")?,
-            );
+        let form = multipart::Form::new().part(
+            "data",
+            multipart::Part::bytes(body)
+                .file_name(Self::filename(&entry.key))
+                .mime_str("application/json")?,
+        );
+        let (method, path, form) = if let Some(existing) = existing {
+            let (dataset_id, data_id) = existing
+                .remote_id
+                .split_once(':')
+                .ok_or_else(|| anyhow!("Cognee record has no dataset id"))?;
+            (
+                Method::PATCH,
+                format!("api/v1/update?data_id={data_id}&dataset_id={dataset_id}"),
+                form,
+            )
+        } else {
+            (
+                Method::POST,
+                "api/v1/remember".to_owned(),
+                form.text("datasetName", Self::dataset_name(&entry.namespace))
+                    .text("run_in_background", "false"),
+            )
+        };
         let response = self
             .client
-            .multipart("api/v1/remember")?
+            .multipart(method, &path)?
             .multipart(form)
             .send()
             .await?;
         if !response.status().is_success() {
             return Err(anyhow!(
-                "memory API api/v1/remember returned HTTP {}",
+                "memory API {path} returned HTTP {}",
                 response.status()
             ));
         }