v0.5.1 - LangGraph Subgraph Support & Performance Indexes

🐛 Critical Fix: LangGraph Namespaces

Previously, MemStateCheckpointer did not strictly isolate states based on checkpoint_ns (namespace).

• The Issue: If a parent graph and a subgraph shared the same thread_id, their states could overwrite each other or get mixed up upon restoration.
• The Fix: We now explicitly store and filter by checkpoint_ns. This guarantees full support for Nested Graphs and complex agent architectures.

⚡ Performance: New Indexes

We added specific database indexes to optimize state retrieval for LangGraph workflows.

• PostgreSQL: Added a B-Tree index on the JSONB path payload ->> 'checkpoint_ns'.
• SQLite: Added a functional index on json_extract(data, '$.payload.checkpoint_ns').

These indexes are created automatically when you initialize the storage.

🔄 Internals

• Updated put and aput methods in the Checkpointer to persist namespace metadata into the underlying Fact payload.

v0.5.0 - Hybrid Search & Semantic Retrieval

This release transforms MemState into a complete Memory Engine.
Previously, MemState ensured your data was written consistently. Now, it ensures it is retrieved consistently.

🔍 New Feature: Hybrid Structured-Semantic Search

We introduced a unified store.search() API that bridges the gap between Vector similarity and SQL strictness.

Why is this safer than standard RAG?
Standard RAG retrieves text directly from the Vector DB. If your Vector DB is slightly behind (indexing lag) or out of sync, you get stale data.
MemState Search uses the "Index-Lookaside" pattern:

1. Discovery: Finds relevant IDs in the Vector DB (using semantic query + metadata filters).
2. Hydration: Loads the actual payload from the SQL Storage (Source of Truth).
3. Result: You always get the latest committed state, never stale vectors.

# Search by meaning + Filter by strict metadata
results = await store.search(
    query="What does the user like?",
    filters={"role": "preference"},
    limit=5
)
# Returns ScoredFact objects with fresh data

✨ Integrations Upgrade

• Qdrant: Implemented modern query_points API. Added DX Magic: you can now pass simple Python dicts {"role": "user"} as filters, and MemState automatically converts them to Qdrant's complex models.Filter syntax.
• ChromaDB: Full support for semantic search with metadata filtering.

⚠️ Breaking Changes

• Protocol Update: The MemoryHook and AsyncMemoryHook protocols now require a search method. If you have written custom hooks, you need to implement this method (returning an empty list [] is acceptable if retrieval is not supported).

v0.4.0 - Async, Postgres & Qdrant Support

🎉 MemState is now in Beta!
This release represents a massive architectural leap. MemState is no longer just for local scripts — it is now ready for high-concurrency FastAPI applications and production deployments.

⚡ Full Async Support

Blocking I/O is a killer for AI agents. v0.4.0 introduces a complete asynchronous stack:

• AsyncMemoryStore: Use await store.commit() for non-blocking operations.
• Async Backends: AsyncSQLiteStorage (via aiosqlite), AsyncPostgresStorage, AsyncRedisStorage.
• Async Hooks: Native support for AsyncQdrantClient and AsyncChromaHttpClient.

🐘 PostgreSQL Backend

We added a native PostgreSQL backend using SQLAlchemy + psycopg.

• Uses JSONB for high-performance querying of nested fields.
• Supports efficient indexing for Singleton constraints.

🌌 Qdrant Integration

Added QdrantSyncHook with built-in FastEmbed support.

• Automatically generates embeddings on the fly (CPU or GPU).
• Supports both Sync and Async clients.

🛡️ Hardened Reliability

• Surgical Rollback: The rollback() logic was rewritten to be multi-user safe. It now isolates transactions by session_id and removes specific entries by UUID, preventing history corruption.
• Safe Updates: The update() method now enforces Schema Re-validation. If you try to patch a record with data that violates the Pydantic schema, the operation is rejected before touching the DB.

📘 New Documentation

We launched a comprehensive documentation site with guides for LangGraph, Integrations, and Best Practices.
👉 Read the Docs

v0.3.3 - High-Level API & Better DX

This release significantly improves Developer Experience. We recognized that manually wrapping Pydantic models into Fact dictionaries was tedious and broke the flow.

✨ New: commit_model API

You can now pass Pydantic instances directly to MemState. The library automatically resolves the registered schema type and handles the serialization.

Before (Verbose):

user = User(name="Alice")
# You had to remember the schema string and manually dump the model
mem.commit(Fact(type="user_profile", payload=user.model_dump()))

Now (Clean):

user = User(name="Alice")
# MemState handles the rest
mem.commit_model(user)

It supports both INSERT (auto ID) and UPDATE (explicit fact_id).

📚 Documentation & Examples

• Refactored Examples: All scripts in examples/ have been updated to use the modern, type-safe syntax.
• New Benchmarks: Added a benchmark proving 0% Data Drift under network failure vs 9% drift in manual sync.

🐛 Fixes

• Ensured commit_model correctly handles the fact_id argument to perform updates instead of creating duplicates.

v0.3.2 - Critical Atomicity Fix & New Demo

This release reinforces the core promise of MemState: True Atomicity.

🛡️ Critical Fix: Compensating Transactions

We identified an edge case where a network failure in a Sync Hook (e.g., ChromaDB timeout) could leave the SQL database committed, breaking synchronization.

Fixed in v0.3.2:
The commit() method now implements a Compensating Transaction pattern.

• Scenario: SQL Write ✅ -> Vector Write ❌ (Fail)
• Old Behavior: SQL saved, Vector lost (Split-Brain).
• New Behavior: SQL is automatically ROLLED BACK. The transaction fails completely, ensuring your data never drifts.

🐛 Other Fixes

• Singleton Updates: Fixed a bug where updating a Singleton fact (e.g., overwriting a user profile) would correctly update SQLite but skip the vector sync hooks. Now updates are fully synchronized.

📚 Documentation & Demo

• New Positioning: Rebranded README to focus on Transactional Memory and Predictability.
• Visual Demo: Added a Before / After comparison GIF to demonstrate how MemState prevents hallucinations compared to manual synchronization.

v0.3.1 - Simplified Imports & Developer Experience

This is a maintenance release focused on improving Developer Experience (DX). We have flattened the internal package structure to expose the core API directly at the top level.

✨ Much Cleaner Imports

You no longer need to remember which submodule (.storage, .schemas, .constants) a class belongs to.

Before (v0.3.0):

from memstate.storage import MemoryStore, Constraint
from memstate.schemas import Fact
from memstate.constants import Operation
from memstate.backends.sqlite import SQLiteStorage

Now (v0.3.1):

from memstate import MemoryStore, Fact, Constraint, Operation, SQLiteStorage

(Note: Specialized backends like RedisStorage and integrations like ChromaSyncHook still require explicit imports to avoid unnecessary dependencies).

🛠 Internal Changes

• Dynamic Versioning: Converted the package to use importlib.metadata. The pyproject.toml is now the Single Source of Truth for the version number.
• Refactoring: Switched internal imports to absolute paths to prevent circular import issues and improve stability.

v0.3.0 - RAG Synchronization & ACID Consistency

This release marks a major strategic shift for MemState. We are evolving from a "Git-like" tool into a Hybrid Memory Engine that ensures atomicity between your structured data (SQL) and semantic data (Vector DBs).

⚡ Key Feature: Automatic RAG Sync

The biggest pain in AI Agents is "Split-Brain" memory: when the SQL database is updated, but the Vector DB still holds old embeddings, causing hallucinations.

MemState v0.3.0 solves this with ChromaSyncHook:

• Transactional Integrity: Vector embeddings are only created/updated when the transaction commits. No more "ghost data" from failed or discarded sessions.
• Automatic Cleanup: When a fact is deleted via rollback() or delete(), it is instantly removed from the vector store.
• Zero Boilerplate: No need to manually write collection.upsert() in your business logic.

🛠 New API

import chromadb
from memstate.integrations.chroma import ChromaSyncHook

# 1. Setup Chroma
chroma_client = chromadb.Client()

# 2. Attach the Hook
# Automatically syncs the 'content' field to ChromaDB on commit
hook = ChromaSyncHook(
    client=chroma_client,
    collection_name="agent_memory",
    text_field="content",
    metadata_fields=["role", "created_at"]
)

memory = MemoryStore(storage, hooks=[hook])

📦 Installation

To get the new vector capabilities:

pip install memstate[chromadb]

🔄 Changes

• Feature: Added memstate.integrations.chroma with strict Dependency Injection support.
• Feature: Added support for custom text_formatter and metadata_formatter strategies for flexible Schema-to-Vector mapping.
• Documentation: Rebranded project as an "ACID-like state manager" to emphasize data consistency guarantees.

v0.2.0 - LangGraph & LangChain Support

🚀 What's New

This release transforms MemState from a standalone engine into a fully integrated part of the AI ecosystem.

🦜 Native LangGraph Support

You can now use MemState as a persistence layer for LangGraph agents.

• New MemStateCheckpointer: Replaces the default SqliteSaver.
• Full State History: Persists not just chat messages, but the entire graph state (variables, tool outputs).
• Human-in-the-loop ready: Supports put_writes and interrupt_before.
• Thread Management: Easily clear conversation history with delete_thread.

📂 New Examples

We added production-ready demos to the examples/ folder:

1. LangGraph Persistence: Zero-config demo showing state recovery after a process restart.
2. Pizza Agent: An advanced stateful agent that separates conversational context from business data (orders).

📦 Installation

New optional dependencies group added:

pip install memstate[langgraph]

🛠 Fixes & Improvements

• Added put_writes and delete_thread methods to checkpointer.
• Updated README with architecture diagrams and LangGraph snippets.

---

Full Changelog: 0.1.0...0.2.0

v0.1.0 - First public release (Alpha)

🎉 MemState is now live on PyPI!

This is the first alpha release of the transactional state management library for LLM Agents.

Key Features:

• 🛡 Type-Safety: Enforce Pydantic schemas on your agent's memory.
• ⏪ Rollbacks: Undo agent mistakes with memory.rollback(1).
• 💾 Pluggable Backends: Includes SQLite (local), Redis (production), and InMemory (testing) adapters out of the box.
• 🦜 LangGraph Ready: Native MemStateCheckpointer for persisting agent graphs.
• 🔍 JSON Querying: Fast, structured search via backend-optimized filters (e.g., SQLite JSON1).

Installation:

pip install memstate

Documentation:
See README.md for quickstart guides.