docs: update examples with commit_model

Author: scream4ik

README.md

@@ -29,31 +29,29 @@ pip install memstate[chromadb]
 ```
 
 ```python
-from memstate import MemoryStore, Fact, SQLiteStorage, HookError
+from pydantic import BaseModel
+from memstate import MemoryStore, SQLiteStorage, HookError
 from memstate.integrations.chroma import ChromaSyncHook
 import chromadb
 
+# Define your Data Schema
+class UserPref(BaseModel):
+    content: str
+    role: str
+
 # Storage
 sqlite = SQLiteStorage("agent_memory.db")
 chroma = chromadb.Client()
 
 # Hook: sync vectors atomically with SQL
 mem = MemoryStore(sqlite)
 mem.add_hook(ChromaSyncHook(chroma, "agent_memory", text_field="content", metadata_fields=["role"]))
+mem.register_schema("preference", UserPref)  # Register type for validation
 
-# Multi-step agent workflow
-# Each commit is atomic: if vector DB fails, SQL write is automatically rolled back
-mem.commit(Fact(
-    type="profile_update",
-    payload={"content": "User prefers vegetarian", "role": "preference"}
-))
-
-# Attempt a task that may fail
+# Atomic Commit (Type-Safe)
+# Validates Pydantic model -> Writes SQL -> Upserts Vector
 try:
-    mem.commit(Fact(
-        type="shopping_list",
-        payload={"content": "Generate shopping list based on plan", "role": "task"}
-    ))
+    mem.commit_model(model=UserPref(content="User prefers vegetarian", role="preference"))
 except HookError as e:
     print("Commit failed, operation rolled back automatically:", e)
 
@@ -135,7 +133,7 @@ SQL write + Vector upsert
 * **Rollback**: undo N steps across SQL and vectors
 * **Type safety**: Pydantic validation prevents malformed JSON
 * **Append-only Fact Log**: full versioned history
-* **Crash-safe atomicity**: if a vector DB write fails, the entire memory operation (SQL + vector) is **rolled back**.  
+* **Crash-safe atomicity**: if a vector DB write fails, the entire memory operation (SQL + vector) is **rolled back**.
   No partial writes, no ghost embeddings, no inconsistent checkpoints.
 
 ---

examples/demo_with_memstate.py

@@ -2,7 +2,7 @@
 
 from pydantic import BaseModel
 
-from memstate import Constraint, Fact, HookError, MemoryStore, Operation
+from memstate import Constraint, HookError, MemoryStore, Operation
 from memstate.backends.sqlite import SQLiteStorage
 
 
@@ -35,13 +35,15 @@ def __call__(self, op, fact_id, data):
 mem.register_schema("food", Food, Constraint(singleton_key="user_id"))
 
 # Seed initial state
-mem.commit(Fact(type="food", payload={"user_id": "bob", "diet": "likes meat"}), session_id="session_id")
+meet_food = Food(user_id="bob", diet="likes meat")
+mem.commit_model(meet_food, session_id="session_id")
 
 print("Initial state:", mem.query())
 
 print("\nStarting transaction to update diet → 'vegetarian'...")
 try:
-    mem.commit(Fact(type="food", payload={"user_id": "bob", "diet": "vegetarian"}), session_id="session_id")
+    vegetarian_food = Food(user_id="bob", diet="vegetarian")
+    mem.commit_model(vegetarian_food, session_id="session_id")
 except HookError as e:
     print("ERROR:", e)
     print("Rollback triggered...")

examples/document_lifecycle.py

@@ -2,12 +2,19 @@
 import shutil
 
 import chromadb
+from pydantic import BaseModel
 
-from memstate import Fact, MemoryStore
+from memstate import MemoryStore
 from memstate.backends.sqlite import SQLiteStorage
 from memstate.integrations.chroma import ChromaSyncHook
 
 
+class Project(BaseModel):
+    content: str
+    status: str
+    author: str
+
+
 def clean_environment():
     """Removes old database files for a clean run."""
     if os.path.exists("lifecycle_demo.db"):
@@ -56,18 +63,16 @@ def run_demo():
 
     memory = MemoryStore(sqlite)
     memory.add_hook(hook)
+    memory.register_schema("project", Project)
     collection = chroma_client.get_collection("docs_memory")
 
     # =========================================================================
     # STEP 1: CREATE (INSERT)
     # =========================================================================
     print(f"1️⃣  Creating new document...")
 
-    fact = Fact(
-        type="doc",
-        payload={"content": "Project Alpha is currently in planning phase.", "status": "draft", "author": "Alice"},
-    )
-    doc_id = memory.commit(fact)
+    project = Project(content="Project Alpha is currently in planning phase.", status="draft", author="Alice")
+    doc_id = memory.commit_model(model=project)
 
     print_state("AFTER INSERT", doc_id, sqlite, collection)
 
@@ -77,17 +82,12 @@ def run_demo():
     print(f"\n2️⃣  Updating document (content + metadata)...")
 
     # We use the SAME fact ID to perform an update
-    memory.commit(
-        Fact(
-            id=doc_id,
-            type="doc",
-            payload={
-                "content": "Project Alpha has been CANCELLED.",  # Content changed
-                "status": "archived",  # Metadata changed
-                "author": "Alice",
-            },
-        )
+    updated_project = Project(
+        content="Project Alpha has been CANCELLED.",  # Content changed
+        status="archived",  # Metadata changed
+        author="Alice",
     )
+    memory.commit_model(fact_id=doc_id, model=updated_project)
 
     print_state("AFTER UPDATE", doc_id, sqlite, collection)
 

examples/main_demo.py

@@ -5,7 +5,7 @@
 
 sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
 
-from memstate import Constraint, Fact, InMemoryStorage, MemoryStore
+from memstate import Constraint, InMemoryStorage, MemoryStore
 
 # --- 1. Defining Schemes ---
 
@@ -45,17 +45,8 @@ class MeetingNote(BaseModel):
 
 # Scenario 1: Agent learns about the user
 print("--- Step 1: Creating User Profile ---")
-fact_profile = Fact(
-    type="user_profile",
-    payload={
-        "email": "alex@corp.com",
-        "full_name": "Alex Dev",
-        "role": "Backend",
-        # 'level' is not passed, Pydantic will substitute 'Junior' automatically!
-    },
-    source="chat_onboarding",
-)
-memory.commit(fact_profile, actor="Agent_Smith")
+fact_profile = UserProfile(email="alex@corp.com", full_name="Alex Dev", role="Backend")
+memory.commit_model(model=fact_profile, source="chat_onboarding", actor="Agent_Smith")
 
 # Let's check what was recorded
 saved_profile = memory.query(typename="user_profile")[0]
@@ -66,12 +57,8 @@ class MeetingNote(BaseModel):
 print("\n--- Step 2: Updating Profile (Singleton Logic) ---")
 # The agent realized that Alex was actually a Senior.
 # He simply commits a new fact. The system will automatically find the old one by email and update it.
-fact_update = Fact(
-    type="user_profile",
-    payload={"email": "alex@corp.com", "full_name": "Alex Dev", "role": "Backend Lead", "level": "Senior"},
-    source="linkedin_parser",
-)
-memory.commit(fact_update, actor="Agent_Smith", reason="found linkedin profile")
+fact_update = UserProfile(email="alex@corp.com", full_name="Alex Dev", role="Backend Lead", level="Senior")
+memory.commit_model(fact_update, source="linkedin_parser", actor="Agent_Smith", reason="found linkedin profile")
 
 # We're checking. There should be one fact left, but it should be updated.
 profiles = memory.query(typename="user_profile")
@@ -81,15 +68,11 @@ class MeetingNote(BaseModel):
 
 # Scenario 3: Agent hallucinates (writes down delusions)
 print("\n--- Step 3: Agent Hallucination ---")
-bad_fact = Fact(
-    type="meeting_note",
-    payload={
-        "topic": "Salary Negotiation",
-        "summary": "Alex agreed to work for free.",  # Hallucination!
-    },
-    source="voice_transcription_error",
+bad_fact = MeetingNote(
+    topic="Salary Negotiation",
+    summary="Alex agreed to work for free.",  # Hallucination!
 )
-memory.commit(bad_fact, actor="Agent_Smith")
+memory.commit_model(bad_fact, actor="Agent_Smith")
 print("⚠️  Bad fact committed.")
 
 

examples/rag_hook_demo.py

@@ -4,8 +4,19 @@
 
 sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
 
+from pydantic import BaseModel
+
 from memstate import Fact, InMemoryStorage, MemoryStore
 
+
+class KnowledgeBase(BaseModel):
+    content: str
+
+
+class UserPref(BaseModel):
+    theme: str
+
+
 # --- Simulated Vector Store ---
 # In real life, this would use OpenAI Embeddings and Qdrant/Chroma
 
@@ -80,20 +91,22 @@ def main():
 
     storage = InMemoryStorage()  # Our "Postgres"
     memory = MemoryStore(storage)  # Our "Brain"
+    memory.register_schema("knowledge_base", KnowledgeBase)
+    memory.register_schema("user_pref", UserPref)
 
     # Add hook
     memory.add_hook(hook)
 
     print("\n--- Phase 1: Ingestion ---")
     # We simply commit the facts to MemState. The hook will automatically transfer them to Vectors.
 
-    doc1 = Fact(type="knowledge_base", payload={"content": "The moon is made of rock and dust."})
-    doc2 = Fact(type="knowledge_base", payload={"content": "Mars is known as the Red Planet due to iron oxide."})
-    doc3 = Fact(type="user_pref", payload={"theme": "dark"})  # This should NOT be in vectors (filter by type)
+    doc1 = KnowledgeBase(content="The moon is made of rock and dust.")
+    doc2 = KnowledgeBase(content="Mars is known as the Red Planet due to iron oxide.")
+    doc3 = UserPref(theme="dark")  # This should NOT be in vectors (filter by type)
 
-    memory.commit(doc1)
-    memory.commit(doc2)
-    memory.commit(doc3)
+    memory.commit_model(model=doc1)
+    doc2_id = memory.commit_model(model=doc2)
+    memory.commit_model(model=doc3)
 
     print("\n--- Phase 2: RAG Search (Emulation) ---")
     # User asks: "Tell me about the red planet"
@@ -118,7 +131,7 @@ def main():
     # We update ONLY MemState.
 
     print("🛠 Updating Mars fact in SQL...")
-    memory.update(doc2.id, {"payload": {"content": "Mars is the Red Planet and has two moons: Phobos and Deimos."}})
+    memory.update(doc2_id, {"payload": {"content": "Mars is the Red Planet and has two moons: Phobos and Deimos."}})
 
     # Check if the vector index has been updated AUTOMATICALLY?
     print("🔎 Searching again for 'Phobos'...")
@@ -132,7 +145,7 @@ def main():
     print("\n--- Phase 4: Forgetting (Deletion) ---")
     # Deleting a fact from the database
     print("🗑 Deleting Mars fact...")
-    memory.delete(doc2.id)
+    memory.delete(doc2_id)
 
     # Checking the search
     found_ids = vector_db.search("Mars")