Agents hallucinate because their memory drifts. SQL says one thing, the Vector DB says another. MemState keeps them in sync, always.
Mental Model: MemState extends database transactions to your Vector DB.
One unit. One commit. One rollback.
Documentation: https://scream4ik.github.io/MemState/
Source Code: https://github.com/scream4ik/MemState
pip install memstate[chromadb]frompydanticimportBaseModelfrommemstateimportMemoryStore, SQLiteStorage, HookErrorfrommemstate.integrations.chromaimportChromaSyncHookimportchromadb# 1. Define Data SchemaclassUserPref(BaseModel):
content: strrole: str# 2. Setup Storage (Local)sqlite=SQLiteStorage("agent_memory.db")
chroma=chromadb.Client()
# 3. Initialize with Sync Hookmem=MemoryStore(sqlite)
mem.add_hook(ChromaSyncHook(chroma, "agent_memory", text_field="content", metadata_fields=["role"]))
mem.register_schema("preference", UserPref)
# 4. Atomic Commit# Validates Pydantic model -> Writes SQL -> Upserts Vectortry:
mem.commit_model(model=UserPref(content="User prefers vegetarian", role="preference"))
exceptHookErrorase:
print("Commit failed, SQL rolled back automatically:", e)
# 5. Undo (if needed)# mem.rollback(1)👉 See full Documentation & Examples
AI agents usually store memory in two places: SQL (structured facts) and Vector DB (semantic search).
These two stores drift easily. If a network request to the Vector DB fails, or the agent crashes mid-operation, you end up with "Split-Brain" memory:
- SQL: "User lives in London"
- Vector DB: "User lives in New York" (Stale embedding)
Result: The agent retrieves wrong context and hallucinates.
MemState acts as a Consistency Layer between your agent and its storage.
- Atomic Commits: SQL and Vector DB stay in sync. If one fails, both rollback.
- Async & Fast: Full asyncio support for high-performance FastAPI/LangGraph apps.
- Type Safety: Pydantic validation prevents LLMs from corrupting your JSON schema.
- Hybrid Search: Search by meaning (Vector), filter by facts (SQL).
- Time Travel: Undo N steps with rollback(n). Great for user corrections.
1000 memory updates with 10% random vector DB failures:
| METRIC | MANUAL SYNC | MEMSTATE |
|---|---|---|
| SQL Records | 1000 | 900 |
| Vector Records | 910 | 900 |
| DATA DRIFT | 90 | 0 |
| INCONSISTENCY RATE | 9.0% | 0.0% |
Why 900 instead of 1000?
MemState refuses partial writes.
If vector sync fails, SQL is rolled back automatically.
Manual sync produces silent drift.
Drift compounds over time, stale embeddings keep being retrieved forever.
Full benchmark script: benchmarks/
| Category | Supported |
|---|---|
| Storage Backends | SQLite, PostgreSQL (JSONB), Redis, In-Memory |
| Vector Hooks | ChromaDB, Qdrant (more coming) |
| Frameworks | LangGraph (Native Checkpointer), LangChain |
| Runtime | Sync & Async (FastAPI ready) |
frommemstate.integrations.langgraphimportMemStateCheckpointercheckpointer=MemStateCheckpointer(memory=mem)
app=workflow.compile(checkpointer=checkpointer)Beta. The API is stable. Suitable for production agents that require high reliability.
Read the Docs | Report an Issue
Apache 2.0 - see LICENSE
Issues and PRs welcome. See CONTRIBUTING.md for details.