docs: add package documentation

Author: scream4ik

.github/workflows/docs.yml

@@ -0,0 +1,32 @@
+name: Publish Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "memstate/**"
+      - ".github/workflows/docs.yml"
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Build and Deploy
+        run: uv run mkdocs gh-deploy --force

docs/api/backends.md

@@ -0,0 +1,3 @@
+::: memstate.backends
+    options:
+        show_submodules: true

docs/api/index.md

@@ -0,0 +1,4 @@
+# API Reference
+
+Here's the reference or code API, the classes, functions, parameters, attributes, and
+all the MemState parts you can use in your applications.

docs/api/integrations.md

@@ -0,0 +1,3 @@
+::: memstate.integrations
+    options:
+        show_submodules: true

docs/api/memstate.md

@@ -0,0 +1,3 @@
+::: memstate.storage
+    options:
+        show_submodules: true

docs/changelog.md

@@ -0,0 +1 @@
+--8<-- "CHANGELOG.md"

docs/documentation/backends.md

@@ -0,0 +1,167 @@
+# Backends
+
+MemState separates logic from storage. You can start with `InMemoryStorage` for testing and switch to `PostgresStorage` or `RedisStorage` for production without changing your agent logic.
+
+**Pro Tip: Dependency Injection**
+
+MemState fully supports **Dependency Injection**. For all backends (Postgres, Redis, SQLite), you can pass an existing connection object instead of a connection string.
+
+## PostgreSQL
+
+Uses `SQLAlchemy` + `psycopg`. It supports JSONB for efficient querying.
+
+### Install the requirements
+
+=== "uv"
+    ```bash
+    uv add memstate[postgres]
+    ```
+
+=== "pip"
+    ```bash
+    pip install memstate[postgres]
+    ```
+
+### Initialize the storage
+
+=== "sync"
+    ```python
+    from memstate import MemoryStore
+    from memstate.backends.postgres import PostgresStorage
+
+    url = "postgresql+psycopg://user:pass@localhost:5432/db_name"
+    storage = PostgresStorage(url)
+    store = MemoryStore(storage=storage)
+    ```
+
+=== "async"
+    ```python
+    import asyncio
+    from memstate import AsyncMemoryStore
+    from memstate.backends.postgres import AsyncPostgresStorage
+    
+    async def main():
+        url = "postgresql+psycopg://user:pass@localhost:5432/db_name"
+        storage = AsyncPostgresStorage(url)
+        # Important: You must create tables explicitly in async mode
+        await store.create_tables()
+
+        store = AsyncMemoryStore(storage=storage)
+
+    if __name__ == "__main__":
+        asyncio.run(main())
+    ```
+
+## Redis
+
+Stores facts as JSON strings and maintains sets for efficient indexing.
+
+### Install the requirements
+
+=== "uv"
+    ```bash
+    uv add memstate[redis]
+    ```
+
+=== "pip"
+    ```bash
+    pip install memstate[redis]
+    ```
+
+### Initialize the storage
+
+=== "sync"
+    ```python
+    from memstate import MemoryStore
+    from memstate.backends.redis import RedisStorage
+
+    storage = RedisStorage("redis://localhost:6379/0")
+    store = MemoryStore(storage=storage)
+    ```
+
+=== "async"
+    ```python
+    import asyncio
+    from memstate import AsyncMemoryStore
+    from memstate.backends.redis import AsyncRedisStorage
+    
+    async def main():
+        storage = AsyncRedisStorage("redis://localhost:6379/0")
+        store = AsyncMemoryStore(storage=storage)
+
+    if __name__ == "__main__":
+        asyncio.run(main())
+    ```
+
+## SQLite
+
+The default, zero-config backend. Uses the JSON1 extension for querying.
+
+### Install the requirements
+
+For synchronous use, SQLite is built-in.
+
+For **async** use, you need `aiosqlite`.
+
+=== "uv"
+    ```bash
+    uv add memstate[sqlite-async]
+    ```
+
+=== "pip"
+    ```bash
+    pip install memstate[sqlite-async]
+    ```
+
+### Initialize the storage
+
+=== "sync"
+    ```python
+    from memstate import MemoryStore, SQLiteStorage
+
+    storage = SQLiteStorage("memory.db")
+    store = MemoryStore(storage=storage)
+    ```
+
+=== "async"
+    ```python
+    import asyncio
+    from memstate import AsyncMemoryStore, AsyncSQLiteStorage
+    
+    async def main():
+        storage = AsyncSQLiteStorage("memory.db")
+        # Important: Connect explicitly
+        await storage.connect()
+
+        store = AsyncMemoryStore(storage=storage)
+
+    if __name__ == "__main__":
+        asyncio.run(main())
+    ```
+
+## In-memory
+
+Non-persistent storage. Best for testing and prototyping.
+
+### Initialize the storage
+
+=== "sync"
+    ```python
+    from memstate import MemoryStore, InMemoryStorage
+
+    storage = InMemoryStorage()
+    store = MemoryStore(storage=storage)
+    ```
+
+=== "async"
+    ```python
+    import asyncio
+    from memstate import AsyncMemoryStore, AsyncInMemoryStorage
+    
+    async def main():
+        storage = AsyncInMemoryStorage()
+        store = AsyncMemoryStore(storage=storage)
+
+    if __name__ == "__main__":
+        asyncio.run(main())
+    ```

docs/documentation/exceptions.md

@@ -0,0 +1,90 @@
+# Exceptions & Error Handling
+
+MemState uses a hierarchy of custom exceptions to help you handle failures gracefully. All exceptions inherit from `MemStateError`.
+
+## Hierarchy
+
+```text
+MemStateError
+├── ValidationFailed    (Schema mismatch)
+├── ConflictError       (Constraint violation)
+├── HookError           (Vector DB sync failure)
+└── MemoryStoreError    (Storage issues, not found, etc.)
+```
+
+## HookError (The ACID Signal)
+
+This is the most important exception in MemState. It is raised when a **Sync Hook** (e.g., ChromaDB, Qdrant) fails during a commit.
+
+**What it means:**
+
+* The Vector DB write failed (network timeout, auth error).
+* **Crucial:** MemState has **already automatically rolled back** the SQL change.
+* Your data is consistent (nothing saved), but the operation failed.
+
+**How to handle:**
+
+=== "Sync"
+    ```python
+    from memstate import HookError
+
+    try:
+        store.commit_model(user_pref)
+    except HookError as e:
+        # The transaction was rolled back.
+        # You can retry, or ask the user to try again.
+        print(f"Sync failed: {e}. Changes rolled back.")
+    ```
+
+=== "Async"
+    ```python
+    from memstate import HookError
+
+    try:
+        await store.commit_model(user_pref)
+    except HookError as e:
+        print(f"Sync failed: {e}. Changes rolled back.")
+    ```
+
+## ValidationFailed
+
+Raised when the data provided (usually from an LLM) does not match the registered Pydantic schema.
+
+**What it means:**
+
+* The LLM generated a string for an `int` field, or missed a required field.
+* The transaction was **rejected** before touching the database.
+
+**How to handle:**
+Usually, you catch this and feed the error message back to the LLM so it can "Self-Correct".
+
+```python
+from memstate import ValidationFailed
+
+try:
+    store.commit_model(model_from_llm)
+except ValidationFailed as e:
+    # Feedback loop for the Agent
+    prompt_to_llm = f"You provided invalid data: {e}. Please fix and retry."
+    retry_llm(prompt_to_llm)
+```
+
+## ConflictError
+
+Raised when a write violates a defined `Constraint` (specifically `immutable=True`).
+
+**What it means:**
+
+* You tried to update a fact that was marked as immutable.
+* Example: Trying to change a signed "User Agreement" fact.
+
+```python
+from memstate import Constraint, ConflictError
+
+store.register_schema("policy", PolicyModel, constraint=Constraint(singleton_key="id", immutable=True))
+
+try:
+    store.commit_model(new_policy)
+except ConflictError:
+    print("Cannot overwrite immutable policy!")
+```