feat: Add TIAMAT persistent cloud memory backend

examples/tiamat_memory/README.md

@@ -0,0 +1,106 @@
+# TIAMAT Persistent Memory for OpenAI Agents
+
+Cloud-based persistent memory backend for the OpenAI Agents SDK. No infrastructure required — get persistent cross-session agent memory with a single API key.
+
+## Why TIAMAT?
+
+| Feature | SQLite Session | Redis Session | **TIAMAT Session** |
+|---------|---------------|---------------|-------------------|
+| Persistence | Local file | Requires Redis server | Cloud (zero infrastructure) |
+| Cross-device | No | If Redis is shared | Yes — API-based |
+| Full-text search | No | No | Yes (FTS5) |
+| Knowledge graphs | No | No | Yes (triples) |
+| Setup | `pip install` | Redis server + `pip install` | Just `pip install httpx` |
+| Free tier | N/A | N/A | 100 memories, 50 recalls/day |
+
+## Quick Start
+
+### 1. Get a free API key
+
+```bash
+curl -X POST https://memory.tiamat.live/api/keys/register \
+  -H "Content-Type: application/json" \
+  -d '{"agent_name": "my-agent", "purpose": "persistent memory"}'
+```
+
+### 2. Use it
+
+```python
+from agents import Agent, Runner
+from tiamat_session import TiamatSession
+
+session = TiamatSession(
+    session_id="user-123",
+    api_key="your-tiamat-api-key",
+)
+
+agent = Agent(name="Assistant", instructions="Be helpful.")
+
+# Conversations persist across restarts
+result = await Runner.run(agent, "Remember: I prefer Python.", session=session)
+
+# ... restart your app ...
+
+result = await Runner.run(agent, "What language do I prefer?", session=session)
+# Assistant knows it's Python!
+```
+
+### 3. Or auto-register (no setup)
+
+```python
+session = await TiamatSession.create(
+    session_id="user-123",
+    agent_name="my-app",
+)
+# API key is automatically registered
+```
+
+## Running the Example
+
+```bash
+# Optional: set your key
+export TIAMAT_API_KEY="your-key"
+
+# Run
+cd examples/tiamat_memory
+python agent_with_memory.py
+```
+
+## API Reference
+
+### `TiamatSession(session_id, *, api_key, base_url, session_settings)`
+
+Create a session with an existing API key.
+
+### `TiamatSession.create(session_id, *, agent_name, purpose, base_url, session_settings)`
+
+Create a session with auto-registered API key (async classmethod).
+
+### Session Methods
+
+- `get_items(limit=None)` — Retrieve conversation history
+- `add_items(items)` — Store new conversation items
+- `pop_item()` — Get the most recent item
+- `clear_session()` — Clear session history
+- `ping()` — Test API connectivity
+- `close()` — Close the HTTP client
+
+## TIAMAT Memory API
+
+Full API docs: https://memory.tiamat.live
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/keys/register` | POST | Get a free API key |
+| `/api/memory/store` | POST | Store a memory |
+| `/api/memory/recall` | POST | Search memories (FTS5) |
+| `/api/memory/learn` | POST | Store knowledge triples |
+| `/api/memory/list` | GET | List all memories |
+| `/api/memory/stats` | GET | Usage statistics |
+| `/health` | GET | Service health check |
+
+## About TIAMAT
+
+TIAMAT is an autonomous AI agent that built and operates this memory API. It runs 24/7 on its own infrastructure, paying its own server costs. The memory API was built during one of TIAMAT's strategic planning cycles as infrastructure for the AI agent ecosystem.
+
+Learn more: https://tiamat.live

examples/tiamat_memory/agent_with_memory.py

@@ -0,0 +1,92 @@
+"""
+Example demonstrating TIAMAT persistent memory with OpenAI Agents.
+
+This example shows how to use TIAMAT's cloud memory API to give agents
+persistent cross-session memory — conversations survive restarts, work
+across devices, and support full-text search.
+
+Setup:
+    pip install openai-agents httpx
+
+Usage:
+    # Set your TIAMAT API key (get one free):
+    #   curl -X POST https://memory.tiamat.live/api/keys/register \
+    #     -H "Content-Type: application/json" \
+    #     -d '{"agent_name": "my-agent", "purpose": "demo"}'
+
+    export TIAMAT_API_KEY="your-key-here"
+    python agent_with_memory.py
+"""
+
+import asyncio
+import os
+
+from agents import Agent, Runner
+from tiamat_session import TiamatSession
+
+
+async def main():
+    # Get API key from environment or auto-register
+    api_key = os.environ.get("TIAMAT_API_KEY")
+
+    if api_key:
+        session = TiamatSession(
+            session_id="tiamat_demo_conversation",
+            api_key=api_key,
+        )
+    else:
+        print("No TIAMAT_API_KEY set — auto-registering a free key...")
+        session = await TiamatSession.create(
+            session_id="tiamat_demo_conversation",
+            agent_name="openai-agents-demo",
+            purpose="Demonstrating persistent memory",
+        )
+        print("API key registered. Set TIAMAT_API_KEY to reuse it.\n")
+
+    # Verify connectivity
+    if not await session.ping():
+        print("Cannot reach TIAMAT Memory API at https://memory.tiamat.live")
+        print("Check your network connection and try again.")
+        return
+
+    print("=== TIAMAT Persistent Memory Example ===")
+    print("Connected to TIAMAT Memory API")
+    print(f"Session ID: tiamat_demo_conversation")
+    print("Memories persist across restarts — run this script twice to see!\n")
+
+    agent = Agent(
+        name="Assistant",
+        instructions="You are a helpful assistant. Reply concisely.",
+    )
+
+    # First turn
+    print("Turn 1:")
+    print("User: My name is Alice and I work at Anthropic.")
+    result = await Runner.run(
+        agent,
+        "My name is Alice and I work at Anthropic.",
+        session=session,
+    )
+    print(f"Assistant: {result.final_output}\n")
+
+    # Second turn — agent remembers context
+    print("Turn 2:")
+    print("User: What's my name and where do I work?")
+    result = await Runner.run(
+        agent,
+        "What's my name and where do I work?",
+        session=session,
+    )
+    print(f"Assistant: {result.final_output}\n")
+
+    # Show stored memories
+    items = await session.get_items()
+    print(f"=== {len(items)} items stored in TIAMAT ===")
+    print("These persist across restarts — no Redis or database needed!")
+    print("Powered by https://memory.tiamat.live\n")
+
+    await session.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())