Improved API layer

Author: anaslimem

crates/mnemos-core/src/facade.rs

@@ -199,9 +199,10 @@ impl Mnemos {
         Ok(id.0)
     }
 
-    /// Store a memory with explicit content bytes.
+    /// Store a memory with explicit content bytes optionally in a namespace.
     pub fn remember_with_content(
         &self,
+        namespace: &str,
         content: Vec<u8>,
         embedding: Vec<f32>,
         metadata: Option<HashMap<String, String>>,
@@ -215,7 +216,7 @@ impl Mnemos {
             .unwrap_or_default()
             .as_secs();
 
-        let mut entry = MemoryEntry::new(id, "default".to_string(), content, ts)
+        let mut entry = MemoryEntry::new(id, namespace.to_string(), content, ts)
             .with_embedding(embedding);
         if let Some(meta) = metadata {
             entry.metadata = meta;

crates/mnemos-py/.gitignore

@@ -1,2 +1,6 @@
 .venv/
-.env 
+.env 
+*.so
+*.dylib
+*.pyd
+__pycache__

crates/mnemos-py/Cargo.toml

@@ -4,7 +4,7 @@ version = "0.1.0"
 edition = "2024"
 
 [lib]
-name = "mnemos"
+name = "_mnemos"
 crate-type = ["cdylib"]
 
 [dependencies]

crates/mnemos-py/mnemos/__init__.py

@@ -0,0 +1,4 @@
+from .client import Mnemos, Namespace
+from ._mnemos import Hit, Memory, Stats, MnemosError
+
+__all__ = ["Mnemos", "Namespace", "Hit", "Memory", "Stats", "MnemosError"]

crates/mnemos-py/mnemos/client.py

@@ -0,0 +1,143 @@
+import typing as t
+
+from ._mnemos import MnemosError, Hit, Memory, Stats
+from . import _mnemos
+
+
+class Namespace:
+    """
+    A scoped context for Mnemos operations.
+    Automatically applies the namespace name to all store/query operations.
+    """
+    def __init__(self, db: "Mnemos", name: str):
+        self._db = db
+        self.name = name
+
+    def remember(
+        self,
+        text: str,
+        embedding: t.Union[t.List[float], None] = None,
+        metadata: t.Union[t.Dict[str, str], None] = None
+    ) -> int:
+        """
+        Store a new memory in this namespace.
+        Currently requires an embedding.
+        """
+        if embedding is None:
+            raise MnemosError(f"Embedding is currently required natively.")
+            
+        return self._db._inner.remember_embedding(
+            embedding=embedding,
+            metadata=metadata,
+            namespace=self.name,
+            content=text,
+        )
+
+    def ask(self, query: str, embedding: t.Union[t.List[float], None] = None, top_k: int = 5) -> t.List[Hit]:
+        """
+        Query for memories in this namespace using an embedding.
+        Currently requires an embedding.
+        Note: The underlying C API currently searches globally. We will refine this.
+        """
+        if embedding is None:
+            raise MnemosError(f"Embedding is currently required natively.")
+            
+        # In the future, ask will be constrained by namespace. 
+        # For now, it delegates to the backend.
+        hits = self._db._inner.ask_embedding(embedding=embedding, top_k=top_k)
+        # Manually filter by namespace since core `ask` doesn't enforce it yet
+        filtered_hits = []
+        for hit in hits:
+            m = self._db.get(hit.id)
+            if m.namespace == self.name:
+                filtered_hits.append(hit)
+                if len(filtered_hits) == top_k:
+                    break
+        return filtered_hits
+
+
+class Mnemos:
+    """
+    Pythonic interface to the Mnemos embedded vector + graph database.
+    """
+    def __init__(self, path: str, dimension: int):
+        try:
+            self._inner = _mnemos.Mnemos.open(path, dimension=dimension)
+        except Exception as e:
+            raise MnemosError(str(e))
+
+    @classmethod
+    def open(cls, path: str, dimension: int) -> "Mnemos":
+        """
+        Open or create a Mnemos database.
+        
+        Args:
+            path: Directory path for the database files.
+            dimension: Vector embedding dimension (required).
+        """
+        return cls(path, dimension)
+
+    def namespace(self, name: str) -> Namespace:
+        """
+        Return a scoped Namespace context.
+        """
+        return Namespace(self, name)
+
+    def remember(
+        self,
+        text: str,
+        embedding: t.Union[t.List[float], None] = None,
+        metadata: t.Union[t.Dict[str, str], None] = None,
+        namespace: str = "default",
+    ) -> int:
+        """
+        Store a new memory.
+        """
+        if embedding is None:
+             raise MnemosError(f"Embedding is currently required natively.")
+        return self._inner.remember_embedding(
+            embedding=embedding,
+            metadata=metadata,
+            namespace=namespace,
+            content=text,
+        )
+
+    def ask(self, query: str, embedding: t.Union[t.List[float], None] = None, top_k: int = 5) -> t.List[Hit]:
+        """
+        Query the database by embedding vector similarity.
+        """
+        if embedding is None:
+            raise MnemosError(f"Embedding is currently required natively.")
+        return self._inner.ask_embedding(embedding=embedding, top_k=top_k)
+
+    def get(self, mid: int) -> Memory:
+        """Retrieve a full memory by ID."""
+        return self._inner.get(mid)
+
+    def connect(self, from_id: int, to_id: int, relation: str):
+        """Create an edge between two memories."""
+        self._inner.connect(from_id, to_id, relation)
+
+    def compact(self):
+        """Compact on-disk segment storage."""
+        self._inner.compact()
+
+    def checkpoint(self):
+        """Force a checkpoint (snapshot states + truncate WAL)."""
+        self._inner.checkpoint()
+
+    def stats(self) -> Stats:
+        """Get database statistics."""
+        return self._inner.stats()
+
+    def __repr__(self) -> str:
+        return repr(self._inner).replace("Mnemos(", "MnemosClient(")
+
+    def __len__(self) -> int:
+        return len(self._inner)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        return False

crates/mnemos-py/pyproject.toml

@@ -11,3 +11,4 @@ license = { text = "GPL-3.0" }
 
 [tool.maturin]
 features = ["pyo3/extension-module"]
+module-name = "mnemos._mnemos"

crates/mnemos-py/src/lib.rs

@@ -214,15 +214,16 @@ impl PyMnemos {
     /// Raises:
     ///     MnemosError: If the embedding dimension is wrong.
     #[pyo3(
-        text_signature = "(self, embedding, *, metadata=None, namespace='default')",
-        signature = (embedding, *, metadata=None, namespace="default".to_string())
+        text_signature = "(self, embedding, *, metadata=None, namespace='default', content='')",
+        signature = (embedding, *, metadata=None, namespace="default".to_string(), content="".to_string())
     )]
     fn remember_embedding(
         &self,
         py: Python<'_>,
         embedding: Vec<f32>,
         metadata: Option<HashMap<String, String>>,
         namespace: String,
+        content: String,
     ) -> PyResult<u64> {
         if embedding.len() != self.dimension {
             return Err(MnemosError::new_err(format!(
@@ -233,8 +234,11 @@ impl PyMnemos {
         }
 
         let id = py.allow_threads(|| {
-            self.inner
-                .remember_in_namespace(&namespace, embedding, metadata)
+            if content.is_empty() {
+                 self.inner.remember_in_namespace(&namespace, embedding, metadata)
+            } else {
+                 self.inner.remember_with_content(&namespace, content.into_bytes(), embedding, metadata)
+            }
         }).map_err(to_py_err)?;
         Ok(id)
     }
@@ -379,7 +383,7 @@ impl PyMnemos {
 
 /// Mnemos — embedded vector + graph memory for AI agents.
 #[pymodule]
-fn mnemos(m: &Bound<'_, PyModule>) -> PyResult<()> {
+fn _mnemos(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<PyMnemos>()?;
     m.add_class::<PyHit>()?;
     m.add_class::<PyMemory>()?;

crates/mnemos-py/test_smoke.py

@@ -1,63 +1,85 @@
-from mnemos import Mnemos
+import pytest
+import os
+import shutil
+from mnemos import Mnemos, MnemosError
 
-def test_mnemos():
-    print("Testing Mnemos PyO3 bindings...")
-    
+DB_PATH = "/tmp/mnemos_test_py"
+
+@pytest.fixture(autouse=True)
+def cleanup():
+    if os.path.exists(DB_PATH):
+        shutil.rmtree(DB_PATH)
+    yield
+    if os.path.exists(DB_PATH):
+        shutil.rmtree(DB_PATH)
+
+def test_mnemos_basic_flow():
     # 1. Open with dimension 3
-    db = Mnemos.open("/tmp/mnemos_test_py", dimension=3)
+    db = Mnemos.open(DB_PATH, dimension=3)
 
     # 2. Store memory
-    mid = db.remember_embedding([1.0, 0.0, 0.0])
-    print(f"Stored memory: {mid}")
+    mid = db.remember("Hello world", embedding=[1.0, 0.0, 0.0])
 
     # 3. Ask
-    hits = db.ask_embedding([1.0, 0.0, 0.0])
-    print(f"Found {len(hits)} hits, top score={hits[0].score:.3f}")
+    hits = db.ask("world", embedding=[1.0, 0.0, 0.0])
+    assert len(hits) == 1
     assert hits[0].id == mid
 
     # 4. Get full memory
     mem = db.get(mid)
-    print(f"Memory: {mem}")
     assert mem.namespace == "default"
     assert mem.id == mid
+    assert bytes(mem.content).decode("utf-8") == "Hello world"
 
     # 5. Connect
-    mid2 = db.remember_embedding([0.0, 1.0, 0.0])
+    mid2 = db.remember("Goodbye", embedding=[0.0, 1.0, 0.0])
     db.connect(mid, mid2, "related")
-    print(f"Connected {mid} -> {mid2}")
 
-    # 6. Stats
+    # 6. Stats & Len
     stats = db.stats()
-    print(f"Stats: {stats}")
     assert stats.vector_dimension == 3
     assert stats.entries == 2
+    assert len(db) == 2
 
-    # 7. Stress - error handling
-    try:
-        db.remember_embedding([1.0, 0.0]) # Wrong dimension
-        assert False, "Should have raised an error"
-    except Exception as e:
-        print(f"Caught expected error: {e}")
+    # 7. Compact and Checkpoint
+    db.compact()
+    db.checkpoint()
 
-    try:
-        db2 = Mnemos.open("/tmp/mnemos_test_py", dimension=4) # Dimension mismatch on open
-        assert False, "Should have raised an error"
-    except Exception as e:
-        print(f"Caught expected error: {e}")
 
-    # 8. Compact
-    db.compact()
-    print("Compacted successfully")
+def test_mnemos_namespaces():
+    db = Mnemos.open(DB_PATH, dimension=3)
+    
+    agent_a = db.namespace("agent_a")
+    agent_b = db.namespace("agent_b")
 
-    # 9. Checkpoint
-    db.checkpoint()
-    print("Checkpointed successfully")
+    id_a = agent_a.remember("I am Agent A", embedding=[1.0, 0.0, 0.0])
+    agent_b.remember("I am Agent B", embedding=[0.0, 1.0, 0.0])
+
+    assert db.get(id_a).namespace == "agent_a"
+    
+    # Test ask filters by namespace using the wrapper
+    hits_a = agent_a.ask("Agent A", embedding=[1.0, 0.0, 0.0])
+    assert len(hits_a) == 1
+    assert hits_a[0].id == id_a
+
+    # Context manager test
+    with Mnemos.open(DB_PATH, dimension=3) as db_ctx:
+        assert len(db_ctx) == 2
+
+
+def test_mnemos_error_handling():
+    db = Mnemos.open(DB_PATH, dimension=3)
 
-    print("All tests passed!")
+    # Wrong dimension map
+    with pytest.raises(MnemosError, match="embedding dimension mismatch"):
+        db.remember("Wrong dim", embedding=[1.0, 0.0])
+        
+    # Missing embedding required
+    with pytest.raises(MnemosError, match="Embedding is currently required natively"):
+        db.remember("No embedding")
 
-if __name__ == "__main__":
-    import shutil
-    import os
-    if os.path.exists("/tmp/mnemos_test_py"):
-        shutil.rmtree("/tmp/mnemos_test_py")
-    test_mnemos()
+    # Wrong dimension on open — must first write something with dim=3
+    mid = db.remember("Seed", embedding=[1.0, 0.0, 0.0])
+    db.checkpoint()  # flush so the mismatch check sees entries > 0
+    with pytest.raises(MnemosError, match="(?i)dimension mismatch"):
+        Mnemos.open(DB_PATH, dimension=4)