memio 0.1.0__tar.gz

memio-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,20 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install mkdocs-material "mkdocstrings[python]"
+      - run: mkdocs gh-deploy --force

memio-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,22 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

memio-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.venv/
+.superpowers/
+.reference/
+site/
+docs/superpowers/
+docs/specs/
+dist/

memio-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 y3zai
+
+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.

memio-0.1.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: memio
+Version: 0.1.0
+Summary: Unified memory gateway for AI agents
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Provides-Extra: all
+Requires-Dist: chromadb; extra == 'all'
+Requires-Dist: mem0ai; extra == 'all'
+Requires-Dist: zep-cloud; extra == 'all'
+Provides-Extra: chroma
+Requires-Dist: chromadb; extra == 'chroma'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Provides-Extra: mem0
+Requires-Dist: mem0ai; extra == 'mem0'
+Provides-Extra: zep
+Requires-Dist: zep-cloud; extra == 'zep'

memio-0.1.0/README.md

@@ -0,0 +1,228 @@
+# memio
+
+Unified memory gateway for AI agents. One interface, multiple memory providers.
+
+memio lets you swap between memory backends (Mem0, Zep, Chroma) without changing your application code. Define what memory capabilities you need — facts, conversation history, documents, knowledge graphs — and plug in any supported provider.
+
+## Features
+
+- **Protocol-based architecture** — providers implement Python protocols, so you can mix and match or bring your own
+- **Async-first** — all operations are `async`/`await`
+- **Zero production dependencies** — install only the providers you need
+- **Composable** — use Mem0 for facts, Zep for history, and Chroma for documents in the same client
+- **Multi-tenant** — scope data by `user_id` or `agent_id`
+- **Consistent error handling** — all provider errors wrapped in `ProviderError` with context
+
+## Install
+
+```bash
+pip install memio
+```
+
+Install with providers:
+
+```bash
+pip install memio[mem0]      # Mem0 provider
+pip install memio[zep]       # Zep provider
+pip install memio[chroma]    # Chroma provider
+pip install memio[all]       # All providers
+```
+
+## Quick start
+
+```python
+from memio import Memio
+from memio.providers.mem0 import Mem0FactAdapter
+from memio.providers.zep import ZepHistoryAdapter
+from memio.providers.chroma import ChromaDocumentAdapter
+import chromadb
+
+client = Memio(
+    facts=Mem0FactAdapter(api_key="your-mem0-key"),
+    history=ZepHistoryAdapter(api_key="your-zep-key"),
+    documents=ChromaDocumentAdapter(
+        client=chromadb.EphemeralClient(),
+        collection_name="my-docs",
+    ),
+)
+
+# Store and retrieve facts
+fact = await client.facts.add(content="likes coffee", user_id="alice")
+results = await client.facts.search(query="coffee", user_id="alice")
+
+# Manage conversation history
+from memio import Message
+
+await client.history.add(
+    session_id="session-1",
+    messages=[
+        Message(role="user", content="hello"),
+        Message(role="assistant", content="hi there"),
+    ],
+)
+messages = await client.history.get(session_id="session-1")
+
+# Store and search documents
+doc = await client.documents.add(content="memio is a memory gateway")
+results = await client.documents.search(query="memory")
+```
+
+## Memory stores
+
+memio defines four memory store protocols. Each provider implements one or more:
+
+| Store | Purpose | Mem0 | Zep | Chroma |
+|-------|---------|------|-----|--------|
+| `FactStore` | Structured facts about users/agents | yes | yes | - |
+| `HistoryStore` | Conversation message history | - | yes | - |
+| `DocumentStore` | Document storage with semantic search | - | - | yes |
+| `GraphStore` | Knowledge graph triples | yes | yes | - |
+
+### FactStore
+
+```python
+fact = await store.add(content="prefers dark mode", user_id="alice")
+fact = await store.get(fact_id=fact.id)
+results = await store.search(query="preferences", user_id="alice")
+updated = await store.update(fact_id=fact.id, content="prefers light mode")
+all_facts = await store.get_all(user_id="alice")
+await store.delete(fact_id=fact.id)
+await store.delete_all(user_id="alice")
+```
+
+### HistoryStore
+
+```python
+await store.add(session_id="s1", messages=[Message(role="user", content="hello")])
+messages = await store.get(session_id="s1", limit=50)
+results = await store.search(session_id="s1", query="hello")
+sessions = await store.get_all(user_id="alice")
+await store.delete(session_id="s1")
+await store.delete_all(user_id="alice")
+```
+
+### DocumentStore
+
+```python
+doc = await store.add(content="some text", metadata={"source": "wiki"})
+doc = await store.get(doc_id=doc.id)
+results = await store.search(query="text", limit=10)
+all_docs = await store.get_all(limit=100)
+updated = await store.update(doc_id=doc.id, content="updated text")
+await store.delete(doc_id=doc.id)
+await store.delete_all()
+```
+
+### GraphStore
+
+```python
+from memio import Triple
+
+await store.add(
+    triples=[Triple(subject="Alice", predicate="likes", object="coffee")],
+    user_id="alice",
+)
+result = await store.get(entity="Alice", user_id="alice")
+result = await store.search(query="coffee", user_id="alice")
+await store.delete_all(user_id="alice")
+```
+
+## Data models
+
+```python
+from memio import Fact, Message, Document, Triple, GraphResult
+
+# Fact — a stored piece of knowledge
+Fact(id, content, user_id, agent_id, metadata, score, created_at, updated_at)
+
+# Message — a conversation message
+Message(role, content, metadata, timestamp, name)
+
+# Document — a stored document
+Document(id, content, metadata, score, created_at, updated_at)
+
+# Triple — a knowledge graph triple
+Triple(subject, predicate, object, metadata)
+
+# GraphResult — result from graph queries
+GraphResult(triples, nodes, scores)
+```
+
+## Custom providers
+
+Implement any protocol to create your own provider:
+
+```python
+from memio import Memio, DocumentStore, Document
+
+class MyDocumentStore:
+    async def add(self, *, content, doc_id=None, metadata=None):
+        # your implementation
+        return Document(id="...", content=content, metadata=metadata)
+
+    async def get(self, *, doc_id):
+        ...
+
+    async def search(self, *, query, limit=10, filters=None):
+        ...
+
+    async def update(self, *, doc_id, content, metadata=None):
+        ...
+
+    async def delete(self, *, doc_id):
+        ...
+
+    async def get_all(self, *, limit=100, filters=None):
+        ...
+
+    async def delete_all(self):
+        ...
+
+# memio validates the protocol at runtime
+client = Memio(documents=MyDocumentStore())
+```
+
+## Error handling
+
+All provider errors are wrapped in `ProviderError`:
+
+```python
+from memio import ProviderError, MemioError
+
+try:
+    await client.facts.search(query="test", user_id="alice")
+except ProviderError as e:
+    print(e.provider)    # "mem0", "zep", etc.
+    print(e.operation)   # "search", "add", etc.
+    print(e.cause)       # original exception
+except MemioError:
+    # base class for all memio errors
+    ...
+```
+
+## Provider notes
+
+**Mem0** — content may be rephrased by Mem0's LLM. Duplicate content is deduplicated automatically.
+
+**Zep** — graph operations are eventually consistent. `graph.add` sends text to an LLM for asynchronous fact extraction. Individual fact/triple deletion is not supported; use `delete_all` instead.
+
+**Chroma** — uses a local client you provide. No API key required for ephemeral or persistent local usage.
+
+## Development
+
+```bash
+git clone https://github.com/y3zai/memio.git
+cd memio
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[all,dev]"
+
+# Run unit tests
+pytest
+
+# Run integration tests (requires API keys)
+MEM0_API_KEY=... ZEP_API_KEY=... pytest -m integration -v
+```
+
+## License
+
+MIT

memio-0.1.0/docs/api/client.md

@@ -0,0 +1,5 @@
+# Client
+
+The `Memio` class is the main entry point for using memio.
+
+::: memio.client.Memio

memio-0.1.0/docs/api/exceptions.md

@@ -0,0 +1,5 @@
+# Exceptions
+
+::: memio.exceptions.MemioError
+
+::: memio.exceptions.ProviderError

memio-0.1.0/docs/api/models.md

@@ -0,0 +1,13 @@
+# Models
+
+Data models used across all providers.
+
+::: memio.models.Fact
+
+::: memio.models.Message
+
+::: memio.models.Document
+
+::: memio.models.Triple
+
+::: memio.models.GraphResult

memio-0.1.0/docs/api/protocols.md

@@ -0,0 +1,11 @@
+# Protocols
+
+Store protocols that providers must implement.
+
+::: memio.protocols.FactStore
+
+::: memio.protocols.HistoryStore
+
+::: memio.protocols.DocumentStore
+
+::: memio.protocols.GraphStore

memio-0.1.0/docs/concepts/architecture.md

@@ -0,0 +1,168 @@
+# Architecture
+
+memio is a unified memory gateway for AI agents. It lets you connect any
+combination of memory providers behind a single client, so your agent code
+never depends on a specific vendor SDK.
+
+This page explains the design decisions that make that possible.
+
+## Protocol-based design
+
+memio defines four store **protocols** using Python's `@runtime_checkable`
+`Protocol` from the `typing` module:
+
+| Protocol | Purpose |
+|---|---|
+| `FactStore` | Structured facts scoped to a user or agent |
+| `HistoryStore` | Conversation message history grouped by session |
+| `DocumentStore` | Documents with semantic search and metadata filtering |
+| `GraphStore` | Knowledge graph triples (subject-predicate-object) |
+
+Because these are protocols -- not base classes -- any class that provides the
+right async methods satisfies the contract. No inheritance is required. The
+`Memio` client validates each store with `isinstance()` at init time and raises
+`TypeError` if the check fails.
+
+```python
+from memio import Memio
+from memio.providers.mem0 import Mem0FactAdapter
+
+# Mem0FactAdapter has no base class -- it just implements
+# the same async methods that FactStore declares.
+client = Memio(facts=Mem0FactAdapter(api_key="..."))
+```
+
+## The adapter pattern
+
+Each provider ships one or more **adapter** classes. An adapter translates
+memio's protocol methods into the provider's own SDK calls and normalizes
+responses into memio's data models:
+
+| Model | Fields |
+|---|---|
+| `Fact` | id, content, user_id, agent_id, metadata, score, created_at, updated_at |
+| `Message` | role, content, metadata, timestamp, name |
+| `Document` | id, content, metadata, score, created_at, updated_at |
+| `Triple` | subject, predicate, object, metadata |
+| `GraphResult` | triples, nodes, scores |
+
+Your agent code works exclusively with these models. If you swap providers,
+you change one import and one constructor call -- the rest of your code stays
+the same.
+
+## Architecture diagram
+
+```
+Your AI Agent
+     |
+     v
+   Memio Client
+     |
+     |-- facts     -> Mem0FactAdapter      -> Mem0 Cloud API
+     |-- history   -> ZepHistoryAdapter     -> Zep Cloud API
+     |-- documents -> ChromaDocumentAdapter -> Local Chroma
+     |-- graph     -> ZepGraphAdapter       -> Zep Cloud API
+```
+
+## Composability
+
+You can mix providers freely. The `Memio` client accepts any combination of
+stores -- use whichever provider is strongest for each memory type:
+
+```python
+from memio import Memio
+from memio.providers.mem0 import Mem0FactAdapter
+from memio.providers.zep import ZepHistoryAdapter
+from memio.providers.chroma import ChromaDocumentAdapter
+
+import chromadb
+
+client = Memio(
+    facts=Mem0FactAdapter(api_key="mem0-key"),
+    history=ZepHistoryAdapter(api_key="zep-key"),
+    documents=ChromaDocumentAdapter(
+        client=chromadb.PersistentClient(path="./chroma_data"),
+        collection_name="docs",
+    ),
+)
+```
+
+At least one store must be provided. Stores you do not need can be omitted --
+accessing an omitted store attribute returns `None`.
+
+### Provider support matrix
+
+| Store | Mem0 | Zep | Chroma |
+|---|---|---|---|
+| FactStore | Mem0FactAdapter | ZepFactAdapter | -- |
+| HistoryStore | -- | ZepHistoryAdapter | -- |
+| DocumentStore | -- | -- | ChromaDocumentAdapter |
+| GraphStore | Mem0GraphAdapter | ZepGraphAdapter | -- |
+
+## Error handling
+
+Every adapter wraps provider SDK exceptions in a single error type:
+
+```python
+from memio.exceptions import ProviderError
+
+try:
+    fact = await client.facts.add(content="likes coffee", user_id="alice")
+except ProviderError as e:
+    print(e.provider)   # "mem0"
+    print(e.operation)  # "add"
+    print(e.cause)      # the original SDK exception
+```
+
+`ProviderError` always carries three attributes:
+
+- **`provider`** -- the name of the provider (`"mem0"`, `"zep"`, `"chroma"`).
+- **`operation`** -- the protocol method that failed (`"add"`, `"search"`, etc.).
+- **`cause`** -- the original exception from the provider SDK.
+
+This means your error-handling code never needs to import provider-specific
+exception types.
+
+## Async-first
+
+All store operations are `async`/`await`. Every method on every protocol is
+declared `async def`, and every adapter implements them as coroutines:
+
+```python
+# Every call goes through await
+fact = await client.facts.add(content="likes coffee", user_id="alice")
+results = await client.facts.search(query="coffee", user_id="alice")
+await client.facts.delete(fact_id=fact.id)
+```
+
+This makes memio a natural fit for async frameworks, LLM tool-calling loops,
+and any agent runtime that uses `asyncio`.
+
+## Multi-tenancy
+
+`FactStore` and `GraphStore` support **`user_id`** and **`agent_id`**
+parameters for scoped data access. This lets a single memio deployment serve
+multiple users or agents without data leaking across boundaries:
+
+```python
+# Facts scoped to a specific user
+await client.facts.add(
+    content="prefers dark mode",
+    user_id="alice",
+)
+
+# Search only returns facts for this user
+results = await client.facts.search(
+    query="UI preferences",
+    user_id="alice",
+)
+
+# Graph triples scoped to a user
+await client.graph.add(
+    triples=[Triple(subject="Alice", predicate="works_at", object="Acme")],
+    user_id="alice",
+)
+```
+
+`HistoryStore` scopes data by **`session_id`**, with `get_all` accepting a
+`user_id` to list all sessions for a given user.