memx-ai 0.1.8__tar.gz

memx_ai-0.1.8/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+uv.lock
+
+# Virtual environments
+.venv
+
+tmp/
+.DS_Store

memx_ai-0.1.8/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Pablo Galilea
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

memx_ai-0.1.8/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: memx-ai
+Version: 0.1.8
+Summary: Lightweight and extensible memory layer for LLMs
+Author-email: Pablo Galilea <pgalilea@me.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: aiofiles>=25.1.0
+Requires-Dist: orjson>=3.11.4
+Provides-Extra: all
+Requires-Dist: aiosqlite>=0.21.0; extra == 'all'
+Requires-Dist: psycopg>=3.2.12; extra == 'all'
+Requires-Dist: pymongo>=4.15.3; extra == 'all'
+Requires-Dist: sqlalchemy[asyncio,postgresql-psycopg]>=2.0.44; extra == 'all'
+Provides-Extra: mongodb
+Requires-Dist: pymongo>=4.15.3; extra == 'mongodb'
+Provides-Extra: postgres
+Requires-Dist: psycopg>=3.2.12; extra == 'postgres'
+Requires-Dist: sqlalchemy[asyncio,postgresql-psycopg]>=2.0.44; extra == 'postgres'
+Provides-Extra: sqlite
+Requires-Dist: aiosqlite>=0.21.0; extra == 'sqlite'
+Requires-Dist: sqlalchemy[asyncio]>=2.0.44; extra == 'sqlite'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://github.com/pgalilea/memx"><img src="https://i.ibb.co/JjYq8fzW/memx.png" alt="memx - memory layer"></a>
+</p>
+
+<br/>
+Lightweight and extensible memory layer for LLMs.
+<br/><br/>
+
+**Important Disclaimer**: This library is intended to be production-ready, but currently is in active development. Fix the version and run your own tests :)
+
+
+##  🔥 Key Features
+- **Framework agnostic**: Use your preferred AI agent framework.
+- **Own infrastructure**: Use your preferred cloud provider. No third-party api keys; your data, your rules.
+- **Multiple backends**: Move from your local *POC* to production deployment, seamlessly (SQLite, MongoDB, PostgreSQL).
+- **Sync and async api**: Highly compatible with modern and *legacy* frameworks. 
+- **No forced schema**: As long it is a list of json serializable objects.
+- **Resumable memory**: Perfect for chat applications and REST APIs
+- **Robust**: Get production-ready code with minimal effort.
+
+
+## ⚙️ Installation
+
+From pypi
+```bash
+pip install memx-ai
+```
+Or clone the repo and install it 
+```bash
+pip install . 
+```
+
+## 🚀 Quickstart
+
+### OpenAI
+Simple conversation with [OpenAI Python library](https://github.com/openai/openai-python)
+```Python
+# https://platform.openai.com/docs/guides/conversation-state?api-mode=responses
+# tested on openai==2.6.1
+
+from openai import OpenAI
+from memx.memory.sqlite import SQLiteMemory
+
+sqlite_uri = "sqlite+aiosqlite:///message-storage.db"
+engine = SQLiteEngine(sqlite_uri, "memx-messages", start_up=True)
+m1 = engine.create_session()  # create a new session
+
+client = OpenAI()
+
+m1.sync.add([{"role": "user", "content": "tell me a good joke about programmers"}])
+
+first_response = client.responses.create(
+    model="gpt-4o-mini", input=m1.sync.get(), store=False
+)
+
+print(first_response.output_text)
+
+m1.sync.add(
+    [{"role": r.role, "content": r.content[0].text} for r in first_response.output]
+)
+
+m1.sync.add([{"role": "user", "content": "tell me another"}])
+
+second_response = client.responses.create(
+    model="gpt-4o-mini", input=m1.sync.get(), store=False
+)
+
+m1.sync.add(
+    [{"role": r.role, "content": r.content[0].text} for r in second_response.output]
+)
+
+print(f"\n\n{second_response.output_text}")
+
+print(m1.sync.get())
+```
+### Pydantic AI
+Message history with async [Pydantic AI](https://ai.pydantic.dev/) + OpenAI
+
+```Python
+# Reference: https://ai.pydantic.dev/message-history/
+
+import asyncio
+
+import orjson
+from pydantic_ai import Agent, ModelMessagesTypeAdapter
+
+from memx.engine.sqlite import SQLiteEngine
+
+agent = Agent("openai:gpt-4o-mini")
+
+
+async def main():
+    sqlite_uri = "sqlite+aiosqlite:///message_store.db"
+    engine = SQLiteEngine(sqlite_uri, "memx-messages", start_up=True)
+    m1 = engine.create_session()  # create a new session
+
+    result1 = await agent.run('Where does "hello world" come from?')
+
+    # it is your responsibility to add the messages as a list[dict]
+    messages = orjson.loads(result1.new_messages_json())
+
+    await m1.add(messages)  # messages: list[dict] must be json serializable
+
+    session_id = m1.get_id()
+    print("Messages added with session_id: ", session_id)
+
+    # resume the conversation from 'another' memory
+    m2 = await engine.get_session(session_id)
+    old_messages = ModelMessagesTypeAdapter.validate_python(await m2.get())
+
+    print("Past messages:\n", old_messages)
+
+    result2 = await agent.run(
+        "Could you tell me more about the authors?", message_history=old_messages
+    )
+    print("\n\nContext aware result:\n", result2.output)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+
+```
+
+You can change the memory backend with minimal modifications. Same api to add and get messages.
+```Python
+from memx.memory.mongodb import MongoDBMemory
+from memx.memory.postgres import PostgresMemory
+from memx.memory.sqlite import SQLiteMemory
+
+# SQLite backend
+sqlite_uri = "sqlite+aiosqlite:///message_store.db"
+e1 = SQLiteMemory(sqlite_uri, "memx-messages", start_up=True)
+m1 = e1.create_session() # memory session ready to go
+
+# PostgreSQL backend
+pg_uri = "postgresql+psycopg://admin:1234@localhost:5433/test-database"
+e2 = PostgresMemory(pg_uri, "memx-messages", start_up=True)
+m2 = e2.create_session()
+
+# MongoDB backend
+mongodb_uri = "mongodb://admin:1234@localhost:27017"
+e3 = MongoDBMemory(uri=mongodb_uri, database="memx-test", "memx-messages")
+m3 = e3.create_session()
+
+```
+
+[More examples...](examples/)
+
+## Tasks
+- [x] Add mongodb backend
+- [x] Add SQLite backend
+- [x] Add Postgres backend
+- [ ] Add redis backend
+- [ ] Add tests
+- [x] Publish on pypi
+- [ ] Add full sync support
+- [ ] Add docstrings

memx_ai-0.1.8/README.md

@@ -0,0 +1,158 @@
+<p align="center">
+  <a href="https://github.com/pgalilea/memx"><img src="https://i.ibb.co/JjYq8fzW/memx.png" alt="memx - memory layer"></a>
+</p>
+
+<br/>
+Lightweight and extensible memory layer for LLMs.
+<br/><br/>
+
+**Important Disclaimer**: This library is intended to be production-ready, but currently is in active development. Fix the version and run your own tests :)
+
+
+##  🔥 Key Features
+- **Framework agnostic**: Use your preferred AI agent framework.
+- **Own infrastructure**: Use your preferred cloud provider. No third-party api keys; your data, your rules.
+- **Multiple backends**: Move from your local *POC* to production deployment, seamlessly (SQLite, MongoDB, PostgreSQL).
+- **Sync and async api**: Highly compatible with modern and *legacy* frameworks. 
+- **No forced schema**: As long it is a list of json serializable objects.
+- **Resumable memory**: Perfect for chat applications and REST APIs
+- **Robust**: Get production-ready code with minimal effort.
+
+
+## ⚙️ Installation
+
+From pypi
+```bash
+pip install memx-ai
+```
+Or clone the repo and install it 
+```bash
+pip install . 
+```
+
+## 🚀 Quickstart
+
+### OpenAI
+Simple conversation with [OpenAI Python library](https://github.com/openai/openai-python)
+```Python
+# https://platform.openai.com/docs/guides/conversation-state?api-mode=responses
+# tested on openai==2.6.1
+
+from openai import OpenAI
+from memx.memory.sqlite import SQLiteMemory
+
+sqlite_uri = "sqlite+aiosqlite:///message-storage.db"
+engine = SQLiteEngine(sqlite_uri, "memx-messages", start_up=True)
+m1 = engine.create_session()  # create a new session
+
+client = OpenAI()
+
+m1.sync.add([{"role": "user", "content": "tell me a good joke about programmers"}])
+
+first_response = client.responses.create(
+    model="gpt-4o-mini", input=m1.sync.get(), store=False
+)
+
+print(first_response.output_text)
+
+m1.sync.add(
+    [{"role": r.role, "content": r.content[0].text} for r in first_response.output]
+)
+
+m1.sync.add([{"role": "user", "content": "tell me another"}])
+
+second_response = client.responses.create(
+    model="gpt-4o-mini", input=m1.sync.get(), store=False
+)
+
+m1.sync.add(
+    [{"role": r.role, "content": r.content[0].text} for r in second_response.output]
+)
+
+print(f"\n\n{second_response.output_text}")
+
+print(m1.sync.get())
+```
+### Pydantic AI
+Message history with async [Pydantic AI](https://ai.pydantic.dev/) + OpenAI
+
+```Python
+# Reference: https://ai.pydantic.dev/message-history/
+
+import asyncio
+
+import orjson
+from pydantic_ai import Agent, ModelMessagesTypeAdapter
+
+from memx.engine.sqlite import SQLiteEngine
+
+agent = Agent("openai:gpt-4o-mini")
+
+
+async def main():
+    sqlite_uri = "sqlite+aiosqlite:///message_store.db"
+    engine = SQLiteEngine(sqlite_uri, "memx-messages", start_up=True)
+    m1 = engine.create_session()  # create a new session
+
+    result1 = await agent.run('Where does "hello world" come from?')
+
+    # it is your responsibility to add the messages as a list[dict]
+    messages = orjson.loads(result1.new_messages_json())
+
+    await m1.add(messages)  # messages: list[dict] must be json serializable
+
+    session_id = m1.get_id()
+    print("Messages added with session_id: ", session_id)
+
+    # resume the conversation from 'another' memory
+    m2 = await engine.get_session(session_id)
+    old_messages = ModelMessagesTypeAdapter.validate_python(await m2.get())
+
+    print("Past messages:\n", old_messages)
+
+    result2 = await agent.run(
+        "Could you tell me more about the authors?", message_history=old_messages
+    )
+    print("\n\nContext aware result:\n", result2.output)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+
+```
+
+You can change the memory backend with minimal modifications. Same api to add and get messages.
+```Python
+from memx.memory.mongodb import MongoDBMemory
+from memx.memory.postgres import PostgresMemory
+from memx.memory.sqlite import SQLiteMemory
+
+# SQLite backend
+sqlite_uri = "sqlite+aiosqlite:///message_store.db"
+e1 = SQLiteMemory(sqlite_uri, "memx-messages", start_up=True)
+m1 = e1.create_session() # memory session ready to go
+
+# PostgreSQL backend
+pg_uri = "postgresql+psycopg://admin:1234@localhost:5433/test-database"
+e2 = PostgresMemory(pg_uri, "memx-messages", start_up=True)
+m2 = e2.create_session()
+
+# MongoDB backend
+mongodb_uri = "mongodb://admin:1234@localhost:27017"
+e3 = MongoDBMemory(uri=mongodb_uri, database="memx-test", "memx-messages")
+m3 = e3.create_session()
+
+```
+
+[More examples...](examples/)
+
+## Tasks
+- [x] Add mongodb backend
+- [x] Add SQLite backend
+- [x] Add Postgres backend
+- [ ] Add redis backend
+- [ ] Add tests
+- [x] Publish on pypi
+- [ ] Add full sync support
+- [ ] Add docstrings

memx_ai-0.1.8/memx/engine/__init__.py

@@ -0,0 +1,15 @@
+from abc import ABC, abstractmethod
+
+from memx.memory import BaseMemory
+
+
+class BaseEngine(ABC):
+    @abstractmethod
+    def create_session(self) -> BaseMemory:
+        """Create a memory session."""
+        pass
+
+    @abstractmethod
+    def get_session(self, session_id: str) -> BaseMemory | None:
+        """Get a memory session from backend."""
+        pass

memx_ai-0.1.8/memx/engine/config.py

@@ -0,0 +1,8 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class SQLEngineConfig:
+    table: str
+    add_query: int
+    get_query: float

memx_ai-0.1.8/memx/engine/mongodb.py

@@ -0,0 +1,34 @@
+from datetime import UTC, datetime
+from uuid import uuid4
+
+from pymongo import AsyncMongoClient, MongoClient
+from pymongo.server_api import ServerApi
+
+from memx.engine import BaseEngine
+from memx.memory.mongodb import MongoDBMemory
+
+
+class MongoDBEngine(BaseEngine):
+    def __init__(self, uri: str, database: str, collection: str):
+        """MongoDB memory engine."""
+
+        self.client = MongoClient(uri)
+        self.async_client = AsyncMongoClient(
+            uri,
+            server_api=ServerApi(version="1", strict=True, deprecation_errors=True),
+        )
+
+        self.db = self.client[database]
+        self.async_db = self.async_client.get_database(database)
+
+        self.sync_collection = self.db[collection]
+        self.async_collection = self.async_db[collection]
+
+    def create_session(self) -> MongoDBMemory:
+        return MongoDBMemory(self.async_collection, self.sync_collection)
+
+    async def get_session(self, id: str) -> MongoDBMemory | None:
+        result = await self.async_collection.find_one({"session_id": id})
+
+        if result:
+            return MongoDBMemory(self.async_collection, self.sync_collection, id)

memx_ai-0.1.8/memx/engine/postgres.py

@@ -0,0 +1,122 @@
+from datetime import UTC, datetime
+from textwrap import dedent
+from uuid import uuid4
+
+import orjson
+from sqlalchemy import create_engine, text
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.orm import Session, sessionmaker
+
+from memx.engine import BaseEngine
+from memx.engine.config import SQLEngineConfig
+from memx.memory.postgres import PostgresMemory
+
+
+class PostgresEngine(BaseEngine):
+    def __init__(self, uri: str, table: str, schema: str = "public", start_up: bool = None):
+        """."""
+
+        self.table_name = f'"{table.strip()}"'
+        self.init_queries()
+
+        driver, _ = uri.split(":", 1)
+        if driver.strip() != "postgresql+psycopg":
+            raise ValueError("For the moment, only 'postgresql+psycopg' driver is supported")
+
+        common_args = {
+            "autocommit": False,
+            "autoflush": False,
+            "expire_on_commit": True,
+        }
+
+        self.async_engine = create_async_engine(
+            uri,
+            connect_args={"options": f"-csearch_path={schema}"},
+        )
+        self.AsyncSession = async_sessionmaker(
+            **common_args,
+            bind=self.async_engine,
+            class_=AsyncSession,
+        )  # type: ignore
+
+        self.sync_engine = create_engine(
+            uri,
+            connect_args={"options": f"-csearch_path={schema}"},
+        )
+        self.SyncSession = sessionmaker(
+            **common_args,
+            bind=self.sync_engine,
+            class_=Session,
+        )  # type: ignore
+
+        if start_up:
+            self.start_up()  # blocking operation
+
+    def create_session(self) -> PostgresMemory:
+        """Get or create a memory session."""
+
+        engine_config = SQLEngineConfig(
+            table=self.table_name,
+            add_query=self.add_sql,
+            get_query=self.get_sql,
+        )
+        return PostgresMemory(self.AsyncSession, self.SyncSession, engine_config)
+
+    async def get_session(self, id: str) -> PostgresMemory | None:
+        """Get a memory session."""
+
+        async with self.AsyncSession() as session:
+            result = (
+                await session.execute(
+                    text(self.get_session_sql),
+                    {"session_id": id},
+                )
+            ).first()
+
+        if result[0] == 1:  # type: ignore
+            engine_config = SQLEngineConfig(
+                table=self.table_name,
+                add_query=self.add_sql,
+                get_query=self.get_sql,
+            )
+            return PostgresMemory(self.AsyncSession, self.SyncSession, engine_config, id)
+
+    def init_queries(self):
+        """."""
+
+        self.table_sql = dedent(f"""
+            CREATE TABLE IF NOT EXISTS {self.table_name} (
+                session_id uuid PRIMARY KEY,
+                message JSONB,
+                created_at TIMESTAMP WITH TIME ZONE DEFAULT (NOW() AT TIME ZONE 'UTC'),
+                updated_at TIMESTAMP WITH TIME ZONE DEFAULT (NOW() AT TIME ZONE 'UTC')
+            );
+        """)
+
+        self.add_sql = dedent(f"""
+            INSERT INTO {self.table_name} (session_id, message, updated_at)
+            VALUES (:session_id, cast(:message as jsonb), :updated_at)
+            ON CONFLICT (session_id)
+            DO UPDATE SET
+                message = COALESCE({self.table_name}.message, '[]'::jsonb) || EXCLUDED.message,
+                updated_at = EXCLUDED.updated_at;
+        """)
+
+        self.get_sql = dedent(f"""
+            SELECT * FROM {self.table_name}
+            WHERE session_id = :session_id;
+        """)
+
+        self.get_session_sql = dedent(f"""
+            SELECT EXISTS(
+                SELECT 1 FROM {self.table_name}
+                WHERE session_id=:session_id
+            ) as r;
+        """)
+
+    def start_up(self):
+        """Create the table if it doesn't exist."""
+
+        with self.SyncSession() as session:
+            session.execute(text(self.table_sql))
+            session.commit()

memx_ai-0.1.8/memx/engine/sqlite.py

@@ -0,0 +1,106 @@
+from textwrap import dedent
+
+from sqlalchemy import create_engine, text
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.orm import Session, sessionmaker
+
+from memx.engine import BaseEngine
+from memx.engine.config import SQLEngineConfig
+from memx.memory.sqlite import SQLiteMemory
+
+
+class SQLiteEngine(BaseEngine):
+    def __init__(self, uri: str, table: str, start_up: bool = False):
+        """SQLite memory engine."""
+
+        self.table_name = f"'{table.strip()}'"
+        self.init_queries()
+
+        self.async_engine = create_async_engine(uri, echo=False, future=True)
+        self.AsyncSession = async_sessionmaker(
+            bind=self.async_engine,
+            expire_on_commit=False,
+            class_=AsyncSession,
+        )
+
+        drivers, others = uri.split(":", 1)  # type: ignore[reportUnusedVariable]
+        self.sync_engine = create_engine(
+            f"sqlite:{others}",
+            echo=False,
+            connect_args={"check_same_thread": True},
+        )
+
+        self.SyncSession = sessionmaker(
+            autocommit=False,
+            autoflush=False,
+            bind=self.sync_engine,
+            class_=Session,
+        )
+
+        if start_up:
+            self.start_up()  # blocking operation
+
+    def create_session(self) -> SQLiteMemory:
+        """Create a local memory session."""
+
+        engine_config = SQLEngineConfig(
+            table=self.table_name,
+            add_query=self.add_sql,
+            get_query=self.get_sql,
+        )
+        return SQLiteMemory(self.AsyncSession, self.SyncSession, engine_config)
+
+    async def get_session(self, id: str) -> SQLiteMemory | None:
+        """Get a memory session."""
+
+        async with self.AsyncSession() as session:
+            result = (
+                await session.execute(
+                    text(self.get_session_sql),
+                    {"session_id": id},
+                )
+            ).first()
+
+        if result[0] == 1:  # type: ignore
+            engine_config = SQLEngineConfig(
+                table=self.table_name,
+                add_query=self.add_sql,
+                get_query=self.get_sql,
+            )
+            return SQLiteMemory(self.AsyncSession, self.SyncSession, engine_config, id)
+
+    def init_queries(self):
+        """."""
+
+        self.table_sql = dedent(f"""
+            CREATE TABLE IF NOT EXISTS {self.table_name} (
+                session_id TEXT,
+                message JSONB,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            );
+            CREATE INDEX IF NOT EXISTS session_index ON {self.table_name} (session_id);
+        """)
+
+        self.add_sql = dedent(f"""
+            INSERT INTO {self.table_name} (session_id, message, created_at)
+            VALUES (:session_id, :message, :created_at);
+        """)
+
+        self.get_sql = dedent(f"""
+            SELECT message FROM {self.table_name}
+            WHERE session_id = :session_id
+            ORDER BY created_at ASC;
+        """)
+
+        self.get_session_sql = dedent(f"""
+            SELECT EXISTS(
+                SELECT 1 FROM {self.table_name}
+                WHERE session_id=:session_id
+            ) as r;
+        """)
+
+    def start_up(self):
+        """Create the table if it doesn't exist."""
+
+        with self.sync_engine.begin() as conn:
+            conn.connection.executescript(self.table_sql)

memx_ai-0.1.8/memx/memory/__init__.py

@@ -0,0 +1,14 @@
+from abc import ABC, abstractmethod
+
+
+class BaseMemory(ABC):
+    @abstractmethod
+    def add(self, messages: list[dict]):
+        pass
+
+    @abstractmethod
+    def get(self) -> list[dict]:
+        pass
+
+    def get_id(self) -> str:
+        return self._session_id  # type: ignore

memx_ai-0.1.8/memx/memory/mongodb.py

@@ -0,0 +1,66 @@
+from datetime import UTC, datetime
+from uuid import uuid4
+
+from pymongo.asynchronous.collection import AsyncCollection
+from pymongo.collection import Collection
+
+from memx.memory import BaseMemory
+
+
+class MongoDBMemory(BaseMemory):
+    def __init__(
+        self,
+        async_collection: AsyncCollection,
+        sync_collection: Collection,
+        session_id: str = None,
+    ):
+        self.async_collection = async_collection
+        self.sync_collection = sync_collection
+
+        self.sync = _sync(self)  # to group sync methods
+
+        if session_id:
+            self._session_id = session_id
+        else:
+            self._session_id = str(uuid4())
+
+    async def add(self, messages: list[dict]):
+        ts_now = datetime.now(UTC)
+
+        await self.async_collection.find_one_and_update(
+            {"session_id": self._session_id},
+            {
+                "$push": {"messages": {"$each": messages}},
+                "$setOnInsert": {"created_at": ts_now},
+                "$set": {"updated_at": ts_now},
+            },
+            upsert=True,
+        )
+
+    async def get(self) -> list[dict]:
+        doc = await self.async_collection.find_one({"session_id": self._session_id})
+
+        return (doc or {}).get("messages", [])
+
+
+class _sync(BaseMemory):
+    def __init__(self, parent: "MongoDBMemory"):
+        self.pm = parent  # parent memory (?)
+
+    def add(self, messages: list[dict]):
+        ts_now = datetime.now(UTC)
+
+        self.pm.sync_collection.find_one_and_update(
+            {"session_id": self.pm._session_id},
+            {
+                "$push": {"messages": {"$each": messages}},
+                "$setOnInsert": {"created_at": ts_now},
+                "$set": {"updated_at": ts_now},
+            },
+            upsert=True,
+        )
+
+    def get(self) -> list[dict]:
+        doc = self.pm.sync_collection.find_one({"session_id": self.pm._session_id})
+
+        return (doc or {}).get("messages", [])

memx_ai-0.1.8/memx/memory/postgres.py

@@ -0,0 +1,97 @@
+from datetime import UTC, datetime
+from uuid import uuid4
+
+import orjson
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+from sqlalchemy.orm import Session, sessionmaker
+
+from memx.engine.config import SQLEngineConfig
+from memx.memory import BaseMemory
+
+
+class PostgresMemory(BaseMemory):
+    def __init__(
+        self,
+        async_session_maker: async_sessionmaker[AsyncSession],  # type: ignore
+        sync_session_maker: sessionmaker[Session],
+        engine_config: SQLEngineConfig,
+        session_id: str = None,
+    ):
+        self.AsyncSession = async_session_maker
+        self.SyncSession = sync_session_maker
+
+        self.engine_config = engine_config
+
+        self.sync = _sync(self)  # to group sync methods
+
+        if session_id:
+            self._session_id = session_id
+        else:
+            self._session_id = str(uuid4())
+
+    async def add(self, messages: list[dict]):
+        # TODO: refactor this with sqlite
+        await self._pre_add()
+
+        ts_now = datetime.now(UTC)
+        data = {
+            "session_id": self._session_id,
+            "message": orjson.dumps(messages).decode("utf-8"),
+            "updated_at": ts_now,
+        }
+
+        async with self.AsyncSession() as session:
+            await session.execute(text(self.engine_config.add_query), data)
+            await session.commit()
+
+    async def get(self) -> list[dict]:
+        async with self.AsyncSession() as session:
+            result = await session.execute(
+                text(self.engine_config.get_query),
+                {"session_id": self._session_id},
+            )
+
+        result = result.first()
+        result = getattr(result, "message", [])
+
+        return result
+
+    async def _pre_add(self):
+        pass
+
+
+class _sync(BaseMemory):
+    def __init__(self, parent: "PostgresMemory"):
+        self.pm = parent  # parent memory (?)
+
+    def add(self, messages: list[dict]):
+        # TODO: refactor this with sqlite
+
+        self._pre_add()
+
+        ts_now = datetime.now(UTC)
+        data = {
+            "session_id": self.pm._session_id,
+            "message": orjson.dumps(messages).decode("utf-8"),
+            "updated_at": ts_now,
+        }
+
+        with self.pm.SyncSession() as session:
+            session.execute(text(self.pm.engine_config.add_query), data)
+            session.commit()
+
+    def get(self) -> list[dict]:
+        with self.pm.SyncSession() as session:
+            result = session.execute(
+                text(self.pm.engine_config.get_query),
+                {"session_id": self.pm._session_id},
+            )
+
+        result = result.first()
+        result = getattr(result, "message", [])
+
+        return result
+
+    def _pre_add(self):
+        pass

memx_ai-0.1.8/memx/memory/simple.py

@@ -0,0 +1,101 @@
+import asyncio
+import pickle
+from pathlib import Path
+from uuid import uuid4
+
+import aiofiles
+
+from memx.memory import BaseMemory
+
+
+class DiskMemory(BaseMemory):
+    def __init__(self, session_id: str = None, dir: str = None):
+        file_id = session_id if session_id else str(uuid4())
+        file_dir = Path(dir) if dir else Path.home() / ".memx"
+
+        self.file_path = Path(file_dir) / f"{file_id}.pkl"
+        file_dir.mkdir(parents=True, exist_ok=True)
+
+        if not self.file_path.is_file():
+            with open(self.file_path, "wb") as f:
+                pickle.dump([], f, protocol=pickle.HIGHEST_PROTOCOL)
+
+        self._session_id = file_id
+
+        self.sync = _sync(self)  # to group sync methods
+
+    async def add(self, messages: list[dict]):
+        # read the file
+        async with aiofiles.open(self.file_path, "rb") as f:
+            pickled_data = await f.read()
+
+        stored_messages: list[dict] = await asyncio.to_thread(
+            pickle.loads, pickled_data
+        )
+
+        # extend the messages
+        stored_messages.extend(messages)
+
+        # write the file
+        pickled_data = await asyncio.to_thread(
+            pickle.dumps, stored_messages, protocol=pickle.HIGHEST_PROTOCOL
+        )
+
+        async with aiofiles.open(self.file_path, "wb") as f:
+            await f.write(pickled_data)
+
+    async def get(self) -> list[dict]:
+        async with aiofiles.open(self.file_path, "rb") as f:
+            pickled_data = await f.read()
+
+        stored_messages: list[dict] = await asyncio.to_thread(
+            pickle.loads, pickled_data
+        )
+
+        return stored_messages
+
+
+class _sync(BaseMemory):
+    def __init__(self, parent: "DiskMemory"):
+        self.pm = parent  # parent memory (?)
+
+    def add(self, messages: list[dict]):
+        with open(self.pm.file_path, "rb") as f:
+            stored_messages: list[dict] = pickle.load(f)
+
+        stored_messages.extend(messages)
+
+        with open(self.pm.file_path, "wb") as f:
+            pickle.dump(stored_messages, f, protocol=pickle.HIGHEST_PROTOCOL)
+
+    def get(self) -> list[dict]:
+        with open(self.pm.file_path, "rb") as f:
+            stored_messages: list[dict] = pickle.load(f)
+
+        return stored_messages
+
+
+class InMemory(BaseMemory):
+    # TODO: add .sync just for consistency
+    def __init__(self, session_id: str = None):
+        global __memx_in_memory__
+        if "__memx_in_memory__" not in globals().keys():
+            __memx_in_memory__ = {}
+
+        if session_id:
+            self._messages = __memx_in_memory__[session_id]
+            _session_id = session_id
+        else:
+            _session_id = str(uuid4())
+            __memx_in_memory__[_session_id] = []
+            self._messages = __memx_in_memory__[_session_id]
+
+        self._session_id = _session_id
+
+    def add(self, messages: list[dict]):
+        self._messages.extend(messages)
+
+    def get(
+        self,
+    ) -> list[str]:
+        return self._messages

memx_ai-0.1.8/memx/memory/sqlite.py

@@ -0,0 +1,105 @@
+from datetime import UTC, datetime
+from uuid import uuid4
+
+import orjson
+from sqlalchemy import Result, text
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+from sqlalchemy.orm import Session, sessionmaker
+
+from memx.engine.config import SQLEngineConfig
+from memx.memory import BaseMemory
+
+
+class SQLiteMemory(BaseMemory):
+    def __init__(
+        self,
+        async_session_maker: async_sessionmaker[AsyncSession],  # type: ignore
+        sync_session_maker: sessionmaker[Session],
+        engine_config: SQLEngineConfig,
+        session_id: str = None,
+    ):
+        self.AsyncSession = async_session_maker
+        self.SyncSession = sync_session_maker
+
+        self.engine_config = engine_config
+
+        self.sync = _sync(self)  # to group sync methods
+
+        if session_id:
+            self._session_id = session_id
+        else:
+            self._session_id = str(uuid4())
+
+    async def add(self, messages: list[dict]):
+        await self._pre_add()
+
+        data = self._format_messages(messages)
+
+        async with self.AsyncSession() as session:
+            await session.execute(text(self.engine_config.add_query), data)
+            await session.commit()
+
+    async def get(self) -> list[dict]:
+        async with self.AsyncSession() as session:
+            result = await session.execute(
+                text(self.engine_config.get_query),
+                {"session_id": self._session_id},
+            )
+
+        messages = _merge_messages(result)
+
+        return messages
+
+    async def _pre_add(self):
+        pass
+
+    def _format_messages(self, messages: list[dict]) -> dict:
+        ts_now = datetime.now(UTC)
+        data = {
+            "session_id": self._session_id,
+            "message": orjson.dumps(messages).decode("utf-8"),
+            "created_at": ts_now,
+        }
+
+        return data
+
+
+class _sync(BaseMemory):
+    def __init__(self, parent: "SQLiteMemory"):
+        self.pm = parent  # parent memory (?)
+
+    def add(self, messages: list[dict]):
+        self._pre_add()
+
+        data = self.pm._format_messages(messages)
+
+        with self.pm.SyncSession() as session:
+            session.execute(text(self.pm.engine_config.add_query), data)
+            session.commit()
+
+    def get(self) -> list[dict]:
+        with self.pm.SyncSession() as session:
+            result = session.execute(
+                text(self.pm.engine_config.get_query),
+                {"session_id": self.pm._session_id},
+            )
+
+        messages = _merge_messages(result)
+
+        return messages
+
+    def _pre_add(self):
+        pass
+
+
+def _merge_messages(msg_result: Result) -> list[dict]:
+    """."""
+
+    # list.extend is the fastest approach
+    result = [dict(row._mapping) for row in msg_result.fetchall()]
+    messages = []
+
+    for r in result:
+        messages.extend(orjson.loads(r["message"]))
+
+    return messages

memx_ai-0.1.8/pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "memx-ai"
+version = "0.1.8"
+description = "Lightweight and extensible memory layer for LLMs"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [
+    { name = "Pablo Galilea", email = "pgalilea@me.com" },
+]
+dependencies = [
+    "aiofiles>=25.1.0",
+    "orjson>=3.11.4",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.2",
+    "ruff>=0.14.2"
+]
+
+[project.optional-dependencies]
+all = [
+    "aiosqlite>=0.21.0",
+    "psycopg>=3.2.12",
+    "pymongo>=4.15.3",
+    "sqlalchemy[asyncio, postgresql-psycopg]>=2.0.44"
+]
+
+sqlite = [
+    "sqlalchemy[asyncio]>=2.0.44",
+    "aiosqlite>=0.21.0"
+]
+
+postgres = [
+    "sqlalchemy[postgresql-psycopg, asyncio]>=2.0.44",
+    "psycopg>=3.2.12"
+]
+
+mongodb = [
+    "pymongo>=4.15.3"
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["memx"]
+only-include = ["memx"]
+
+[tool.hatch.build]
+include = [
+    "memx/**/*.py",
+    "tests"
+]
+
+[tool.hatch.build.targets.wheel.shared-data]
+"README.md" = "README.md"
+
+[tool.ruff]
+select = [
+    "E",  # pycodestyle errors
+    "W",  # pycodestyle warnings
+    "F",  # pyflakes
+    "I",  # isort
+    "B",  # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+]
+line-length = 99
+fixable = ["ALL"]
+unfixable = ["F401", "F403"]
+ignore = ["F401", "F403"]
+
+[tool.pyright]
+pythonVersion = "3.11"
+typeCheckingMode = "basic"
+reportInvalidTypeForm = "none"
+reportArgumentType = false