Skip to content

Commit 7c009e4

Browse files
scream4ikscream4ik
committed
docs: update description based on feedback
1 parent 306ce49 commit 7c009e4

File tree

1 file changed

+91
-69
lines changed

1 file changed

+91
-69
lines changed

‎README.md‎

Lines changed: 91 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,74 @@
1-
# MemState - Transactional Memory for AI Agents
1+
# MemState — Transactional Memory for AI Agents
2+
3+
**Keeps SQL and Vector DBs in sync. No drift. No ghost data. ACID-like consistency for agent state.**
24

35
[![PyPI version](https://img.shields.io/pypi/v/memstate.svg)](https://pypi.org/project/memstate/)
46
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/memstate?period=total&units=INTERNATIONAL_SYSTEM&left_color=GREY&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/memstate)
57
[![Python versions](https://img.shields.io/pypi/pyversions/memstate.svg)](https://pypi.org/project/memstate/)
68
[![License](https://img.shields.io/pypi/l/memstate.svg)](https://github.com/scream4ik/MemState/blob/main/LICENSE)
79
[![Tests](https://github.com/scream4ik/MemState/actions/workflows/test.yml/badge.svg)](https://github.com/scream4ik/MemState/actions)
810

9-
**ACID-like consistency layer for agent state.**
10-
Ensures Structured Data (SQL) and Semantic Data (Vector Embeddings) stay synchronized, reversible, and type-safe.
11+
---
1112

12-
<p align="center">
13-
<img src="https://raw.githubusercontent.com/scream4ik/MemState/main/assets/docs/demo.gif" width="100%" />
14-
<br>
15-
<strong>Demo:</strong> Without MemState → memory gets inconsistent ❌ &nbsp;&nbsp;|&nbsp;&nbsp; With MemState → atomic, type-safe, rollbackable agent state ✅
16-
<br>
17-
<em>All demo scripts are available in the <code>examples/</code> folder for reproducibility.</em>
18-
</p>
13+
## Why MemState exists
1914

20-
---
15+
AI agents usually store memory in two places:
16+
17+
* **SQL** (structured facts)
18+
* **Vector DB** (semantic search context)
19+
20+
These two **drift** easily:
21+
22+
### ❌ Example of real-world corruption
2123

22-
## The Problem: Agent State Corruption
24+
```python
25+
# Step 1: SQL write succeeds
26+
db.update("user_city", "London")
27+
28+
# Step 2: Vector DB update fails (timeout)
29+
vectors.upsert("User lives in London") # ❌ failed
2330

24-
In most frameworks, agent state is treated as a second-class citizen:
25-
* Scattered JSON blobs.
26-
* Ad-hoc RAG embeddings that drift from the source of truth.
27-
* Inconsistent partial updates during failures.
28-
* No rollback mechanisms.
31+
# Final state:
32+
SQL: London
33+
Vectors: New York
34+
→ Agent retrieves stale context and behaves unpredictably
35+
```
2936

30-
This leads to **Data Drift**: The SQL database says one thing, the Vector DB says another. The agent becomes unpredictable and hallucinates because its memory is fractured.
37+
Failures, crashes, retries, malformed payloads — all silently accumulate “ghost vectors” and inconsistent state.
3138

32-
**Agents need reliable state. Not a document dump.**
39+
**Vector DBs don't have transactions.
40+
JSON memory has no schema.
41+
Agents drift over time.**
3342

3443
---
3544

36-
## MemState: A Consistency Layer
45+
## What MemState does
3746

38-
MemState treats agent memory as a transactional system, offering database semantics for application logic:
47+
MemState makes all memory operations **atomic**:
3948

40-
* **⚛️ Atomicity** — SQL and Vector DB changes succeed or rollback together.
41-
* **🛡️ Isolation** — Intermediate steps in a workflow never leak to the main memory.
42-
* **⏪ Rollback** — Revert any number of committed steps instantly.
43-
* **🔒 Schema Safety** — Pydantic validation prevents data corruption at runtime.
49+
```
50+
SQL write + Vector upsert
51+
→ succeed together or rollback together
52+
```
53+
54+
Also provides:
4455

45-
It is the missing architecture between your Agent Logic and your Storage.
56+
* **Rollback**: undo N steps (SQL + vectors)
57+
* **Type safety**: Pydantic schema validation
58+
* **Append-only Fact Log**: full version history
59+
* **Crash safety**: WAL replay for vector sync
60+
61+
<p align="center">
62+
<img src="https://raw.githubusercontent.com/scream4ik/MemState/main/assets/docs/demo.gif" width="100%" />
63+
<br>
64+
<strong>Demo:</strong> Without MemState → memory gets inconsistent ❌ &nbsp;&nbsp;|&nbsp;&nbsp; With MemState → atomic, type-safe, rollbackable agent state ✅
65+
<br>
66+
<em>All demo scripts are available in the <code>examples/</code> folder for reproducibility.</em>
67+
</p>
4668

4769
---
4870

49-
## Quick Example
71+
## Minimal example (copy–paste)
5072

5173
```bash
5274
pip install memstate[chromadb]
@@ -57,89 +79,89 @@ from memstate import MemoryStore, Fact, SQLiteStorage
5779
from memstate.integrations.chroma import ChromaSyncHook
5880
import chromadb
5981

60-
# 1. Setup Storage
82+
# Storage
6183
sqlite = SQLiteStorage("state.db")
6284
chroma = chromadb.Client()
6385

64-
# 2. Define Transactional Sync
65-
# This hook binds the Vector DB to the Atomic Lifecycle of the MemoryStore
86+
# Hook: sync vectors atomically with SQL
6687
hook = ChromaSyncHook(
6788
client=chroma,
68-
collection_name="agent_memory",
89+
collection_name="memory",
6990
text_field="content",
70-
metadata_fields=["role", "topic"]
91+
metadata_fields=["role"]
7192
)
7293

73-
memory = MemoryStore(sqlite)
74-
memory.add_hook(hook=hook)
75-
76-
# 3. Atomic Write
77-
# Persists to SQLite AND upserts to ChromaDB.
78-
# If either fails, both are rolled back.
79-
memory.commit(Fact(
80-
type="user_feedback",
81-
payload={
82-
"content": "User prefers vegetarian options",
83-
"role": "profile"
84-
}
94+
mem = MemoryStore(sqlite)
95+
mem.add_hook(hook)
96+
97+
# Atomic commit: SQL + Vectors
98+
mem.commit(Fact(
99+
type="profile_update",
100+
payload={"content": "User prefers vegetarian", "role": "preference"}
85101
))
86102

87-
# 4. Rollback
88-
# Restores SQLite state AND deletes the vector from ChromaDB.
89-
memory.rollback(1)
103+
# Rollback: removes SQL row + vector entry
104+
mem.rollback(1)
90105
```
91106

92107
---
93108

94-
## Why this matters
95-
96-
Standard tooling stores memory as a single opaque document. This breaks for:
97-
* **Long-running agents** where state accumulates errors.
98-
* **Multi-step workflows** requiring intermediate checkpoints.
99-
* **Compliance/Audit systems** needing a ledger of changes.
100-
* **Hybrid Search** where structured state and RAG context must match.
109+
## How MemState compares
101110

102-
MemState introduces **determinism** to your agent's behavior.
111+
| Operation | Without MemState | With MemState |
112+
| --------------------------- | -------------------- | ------------------- |
113+
| Vector DB write fails | ❌ SQL+Vector diverge | ✔ auto-rollback |
114+
| Partial workflow crash | ❌ ghost vectors | ✔ consistent |
115+
| LLM outputs malformed JSON | ❌ corrupt state | ✔ schema validation |
116+
| Need to undo last N actions | ❌ impossible | ✔ rollback() |
117+
| Need deterministic behavior | ❌ drift | ✔ ACID-like |
103118

104119
---
105120

106-
## Integrates with LangGraph
121+
## Ideal for
107122

108-
Drop-in replacement for the default checkpointer.
109-
Your graph state becomes structured, queryable, and transaction-safe.
123+
* **Long-running agents**
124+
* **LangGraph projects** needing reliable state
125+
* **RAG systems** where DB data must match embeddings
126+
* **Local-first setups** (SQLite + Chroma/Qdrant/FAISS)
127+
128+
---
129+
130+
## LangGraph integration
110131

111132
```python
112133
from memstate.integrations.langgraph import MemStateCheckpointer
113134

114-
checkpointer = MemStateCheckpointer(memory=memory)
135+
checkpointer = MemStateCheckpointer(memory=mem)
115136
app = workflow.compile(checkpointer=checkpointer)
116137
```
117138

118139
---
119140

120-
## Key Capabilities
141+
## Storage backends
142+
143+
* SQLite (JSON1)
144+
* Redis
145+
* In-memory
146+
* Custom backends via simple interface
121147

122-
* **Hybrid Transactional Storage** (SQL + Vectors)
123-
* **Pydantic Schema Enforcement**
124-
* **Fact-based Versioning** (Append-only Log)
125-
* **Multi-step Atomic Commits**
126-
* **Pluggable Backends:** SQLite (JSON1), Redis, In-Memory
148+
Vector sync hooks: ChromaDB (more coming)
127149

128150
---
129151

130152
## Status
131153

132-
**Alpha.** The API is stable enough for building reliable agent prototypes.
133-
We follow Semantic Versioning.
154+
**Alpha.** API stable enough for prototypes and local agents.
155+
Semantic Versioning.
134156

135157
---
136158

137-
## 📄 License
159+
## License
138160

139161
Licensed under the [Apache 2.0 License](LICENSE).
140162

141163
---
142164

143-
## 🤝 Contributing
165+
## Contributing
144166

145167
Issues and PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

0 commit comments

Comments
 (0)