rem-memory 0.1.0__tar.gz

rem_memory-0.1.0/.gitignore

@@ -0,0 +1,69 @@
+# Binaries
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Go build output
+go-api/bin/
+go-api/tmp/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+env/
+.Python
+
+# Node / Next.js
+node_modules/
+.next/
+out/
+dashboard/.next/
+dashboard/out/
+dashboard/node_modules/
+
+# Environment files
+.env
+.env.local
+.env.*.local
+
+# IDE / Editor
+.idea/
+.vscode/settings.json
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# Test coverage
+coverage/
+*.coverprofile
+htmlcov/
+.coverage
+
+# Compiled / generated
+*.pb.go
+*.pb.gw.go
+
+# Docker
+.dockerignore
+
+# Misc
+*.tmp
+*.bak

rem_memory-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: rem-memory
+Version: 0.1.0
+Summary: Recursive Episodic Memory for AI Agents — persistent memory infrastructure
+Project-URL: Homepage, https://rem.ai
+Project-URL: Documentation, https://rem.ai/docs
+Project-URL: Repository, https://github.com/yourusername/rem
+Project-URL: Bug Tracker, https://github.com/yourusername/rem/issues
+Author-email: Your Name <you@example.com>
+License: MIT
+Keywords: agents,ai,episodic-memory,llm,memory,rag
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.26.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: all
+Requires-Dist: langchain-core>=0.1.0; extra == 'all'
+Requires-Dist: langchain>=0.1.0; extra == 'all'
+Requires-Dist: pyautogen>=0.2.0; extra == 'all'
+Provides-Extra: autogen
+Requires-Dist: pyautogen>=0.2.0; extra == 'autogen'
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: respx; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
+Requires-Dist: langchain>=0.1.0; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# REM Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/rem-memory)](https://pypi.org/project/rem-memory/)
+[![Python](https://img.shields.io/pypi/pyversions/rem-memory)](https://pypi.org/project/rem-memory/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**rem-memory** is the official Python SDK for [REM](https://github.com/your-org/rem) (Recursive Episodic Memory) — an open-source memory layer for AI agents.
+
+---
+
+## Installation
+
+```bash
+pip install rem-memory
+```
+
+## Quick start
+
+```python
+import asyncio
+from rem_memory import REMClient
+
+async def main():
+    async with REMClient(api_key="rem_sk_...") as client:
+        # Write a memory episode
+        result = await client.write(
+            content="User prefers TypeScript with strict mode for all new projects.",
+            agent_id="agent_cursor",
+            user_id="user_alice",
+        )
+        print(result.episode_id)
+
+        # Retrieve relevant memories
+        memories = await client.retrieve(
+            query="Does the user prefer TypeScript or JavaScript?",
+            agent_id="agent_cursor",
+            top_k=5,
+        )
+        for m in memories.episodes:
+            print(m.intent, m.importance_score)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `api_key` | — | Your REM API key (`X-API-Key` header) |
+| `base_url` | `http://localhost:8080` | Base URL of the REM Go API |
+| `timeout` | `30` | Request timeout in seconds |
+
+Environment variables are also supported:
+
+```bash
+export REM_API_KEY=rem_sk_...
+export REM_BASE_URL=http://localhost:8080
+```
+
+## Integrations
+
+### LangChain
+
+```python
+from rem_memory.integrations.langchain import REMMemory
+from langchain.chains import ConversationChain
+from langchain_openai import ChatOpenAI
+
+memory = REMMemory(
+    api_key="rem_sk_...",
+    agent_id="agent_cursor",
+    user_id="user_alice",
+)
+
+chain = ConversationChain(llm=ChatOpenAI(), memory=memory)
+response = chain.predict(input="What are my coding preferences?")
+```
+
+### AutoGen
+
+```python
+from rem_memory.integrations.autogen import REMMemoryStore
+from autogen import ConversableAgent
+
+memory_store = REMMemoryStore(
+    api_key="rem_sk_...",
+    agent_id="agent_autogen",
+)
+
+agent = ConversableAgent(
+    name="assistant",
+    system_message="You are a helpful coding assistant.",
+)
+
+# Inject past memories into system prompt
+context = await memory_store.get_context(query="user coding preferences")
+```
+
+## API Reference
+
+### `REMClient`
+
+#### `write(content, agent_id, user_id, session_id?, metadata?)`
+Write a raw interaction to episodic memory. Returns `WriteResult`.
+
+#### `retrieve(query, agent_id, top_k?, include_semantic?)`
+Retrieve semantically relevant episodes and facts. Returns `RetrieveResult`.
+
+#### `get_agent(agent_id)`
+Fetch agent metadata. Returns `Agent`.
+
+#### `list_agents()`
+List all agents. Returns `List[Agent]`.
+
+#### `list_episodes(agent_id, limit?, offset?)`
+Page through raw episodes for an agent. Returns `List[Episode]`.
+
+#### `list_semantic_memories(agent_id)`
+Fetch all consolidated semantic memories. Returns `List[SemanticMemory]`.
+
+## Development
+
+```bash
+cd sdk/python
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT © REM Contributors

rem_memory-0.1.0/README.md

@@ -0,0 +1,131 @@
+# REM Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/rem-memory)](https://pypi.org/project/rem-memory/)
+[![Python](https://img.shields.io/pypi/pyversions/rem-memory)](https://pypi.org/project/rem-memory/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**rem-memory** is the official Python SDK for [REM](https://github.com/your-org/rem) (Recursive Episodic Memory) — an open-source memory layer for AI agents.
+
+---
+
+## Installation
+
+```bash
+pip install rem-memory
+```
+
+## Quick start
+
+```python
+import asyncio
+from rem_memory import REMClient
+
+async def main():
+    async with REMClient(api_key="rem_sk_...") as client:
+        # Write a memory episode
+        result = await client.write(
+            content="User prefers TypeScript with strict mode for all new projects.",
+            agent_id="agent_cursor",
+            user_id="user_alice",
+        )
+        print(result.episode_id)
+
+        # Retrieve relevant memories
+        memories = await client.retrieve(
+            query="Does the user prefer TypeScript or JavaScript?",
+            agent_id="agent_cursor",
+            top_k=5,
+        )
+        for m in memories.episodes:
+            print(m.intent, m.importance_score)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `api_key` | — | Your REM API key (`X-API-Key` header) |
+| `base_url` | `http://localhost:8080` | Base URL of the REM Go API |
+| `timeout` | `30` | Request timeout in seconds |
+
+Environment variables are also supported:
+
+```bash
+export REM_API_KEY=rem_sk_...
+export REM_BASE_URL=http://localhost:8080
+```
+
+## Integrations
+
+### LangChain
+
+```python
+from rem_memory.integrations.langchain import REMMemory
+from langchain.chains import ConversationChain
+from langchain_openai import ChatOpenAI
+
+memory = REMMemory(
+    api_key="rem_sk_...",
+    agent_id="agent_cursor",
+    user_id="user_alice",
+)
+
+chain = ConversationChain(llm=ChatOpenAI(), memory=memory)
+response = chain.predict(input="What are my coding preferences?")
+```
+
+### AutoGen
+
+```python
+from rem_memory.integrations.autogen import REMMemoryStore
+from autogen import ConversableAgent
+
+memory_store = REMMemoryStore(
+    api_key="rem_sk_...",
+    agent_id="agent_autogen",
+)
+
+agent = ConversableAgent(
+    name="assistant",
+    system_message="You are a helpful coding assistant.",
+)
+
+# Inject past memories into system prompt
+context = await memory_store.get_context(query="user coding preferences")
+```
+
+## API Reference
+
+### `REMClient`
+
+#### `write(content, agent_id, user_id, session_id?, metadata?)`
+Write a raw interaction to episodic memory. Returns `WriteResult`.
+
+#### `retrieve(query, agent_id, top_k?, include_semantic?)`
+Retrieve semantically relevant episodes and facts. Returns `RetrieveResult`.
+
+#### `get_agent(agent_id)`
+Fetch agent metadata. Returns `Agent`.
+
+#### `list_agents()`
+List all agents. Returns `List[Agent]`.
+
+#### `list_episodes(agent_id, limit?, offset?)`
+Page through raw episodes for an agent. Returns `List[Episode]`.
+
+#### `list_semantic_memories(agent_id)`
+Fetch all consolidated semantic memories. Returns `List[SemanticMemory]`.
+
+## Development
+
+```bash
+cd sdk/python
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT © REM Contributors

rem_memory-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rem-memory"
+version = "0.1.0"
+description = "Recursive Episodic Memory for AI Agents — persistent memory infrastructure"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [{name = "Your Name", email = "you@example.com"}]
+keywords = ["ai", "memory", "agents", "llm", "rag", "episodic-memory"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+dependencies = [
+    "httpx>=0.26.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+langchain = ["langchain>=0.1.0", "langchain-core>=0.1.0"]
+autogen = ["pyautogen>=0.2.0"]
+all = ["rem-memory[langchain,autogen]"]
+dev = ["pytest", "pytest-asyncio", "respx", "black", "ruff", "mypy"]
+
+[project.urls]
+Homepage = "https://rem.ai"
+Documentation = "https://rem.ai/docs"
+Repository = "https://github.com/yourusername/rem"
+"Bug Tracker" = "https://github.com/yourusername/rem/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["rem_memory"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py39"
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+
+

rem_memory-0.1.0/rem_memory/__init__.py

@@ -0,0 +1,29 @@
+__version__ = "0.1.0"
+
+from .client import REMClient
+from .types import Agent, RetrieveResult, SemanticMemory, WriteResult
+from .exceptions import (
+    REMError,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    APIError,
+    ConnectionError,
+    ValidationError,
+)
+
+__all__ = [
+    "REMClient",
+    "WriteResult",
+    "RetrieveResult",
+    "SemanticMemory",
+    "Agent",
+    "REMError",
+    "AuthenticationError",
+    "NotFoundError",
+    "RateLimitError",
+    "APIError",
+    "ConnectionError",
+    "ValidationError",
+]
+

rem_memory-0.1.0/rem_memory/client.py

@@ -0,0 +1,379 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, List, Optional, Tuple, Literal
+
+import httpx
+
+from .types import (
+    Agent,
+    CreateAgentRequest,
+    EpisodeResult,
+    RetrieveResult,
+    SemanticMemory,
+    WriteResult,
+)
+from .exceptions import (
+    REMError,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    APIError,
+    ConnectionError,
+    ValidationError,
+)
+
+
+SDK_VERSION = "0.1.0"
+
+
+class REMClient:
+    """
+    Recursive Episodic Memory client for AI agents.
+
+    Quick start:
+        client = REMClient(api_key="rem_sk_...")
+
+        # After agent task
+        await client.write(
+            content="User prefers TypeScript",
+            agent_id="my-agent",
+        )
+
+        # Before next task
+        result = await client.retrieve(
+            query="user preferences",
+            agent_id="my-agent",
+        )
+        print(result.injection_prompt)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.rem.ai",
+        timeout: int = 30,
+        max_retries: int = 3,
+    ) -> None:
+        if not api_key:
+            raise AuthenticationError("api_key is required")
+        if not api_key.startswith("rem_sk_"):
+            raise AuthenticationError(
+                "Invalid API key format. Key must start with 'rem_sk_'",
+            )
+
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+        self._headers = {
+            "X-API-Key": api_key,
+            "Content-Type": "application/json",
+            "User-Agent": f"rem-memory-python/{SDK_VERSION}",
+        }
+
+        self._async_client: Optional[httpx.AsyncClient] = None
+        self._sync_client: Optional[httpx.Client] = None
+
+    # ── ASYNC METHODS ────────────────────────────────────────────
+
+    async def write(
+        self,
+        content: str,
+        agent_id: str,
+        user_id: str = "default",
+        session_id: str = "",
+        outcome: Literal["success", "failure", "partial", "unknown"] = "unknown",
+        metadata: Optional[Dict[str, str]] = None,
+    ) -> WriteResult:
+        """
+        Write an episode to memory after your agent completes a task.
+        """
+        if not content or len(content.strip()) < 10:
+            raise ValidationError("content must be at least 10 characters")
+        if not agent_id:
+            raise ValidationError("agent_id is required")
+
+        response = await self._async_request(
+            "POST",
+            "/api/v1/episodes",
+            json={
+                "content": content,
+                "agent_id": agent_id,
+                "user_id": user_id,
+                "session_id": session_id,
+                "outcome": outcome,
+                "metadata": metadata or {},
+            },
+        )
+        return WriteResult(**response)
+
+    async def retrieve(
+        self,
+        query: str,
+        agent_id: str,
+        top_k: int = 5,
+        include_semantic: bool = True,
+    ) -> RetrieveResult:
+        """
+        Retrieve relevant memories before your agent starts a task.
+        Inject result.injection_prompt into your LLM system prompt.
+        """
+        if not query:
+            raise ValidationError("query is required")
+        if not agent_id:
+            raise ValidationError("agent_id is required")
+        top_k = max(1, min(top_k, 20))
+
+        raw = await self._async_request(
+            "POST",
+            "/api/v1/retrieve",
+            json={
+                "query": query,
+                "agent_id": agent_id,
+                "top_k": top_k,
+                "include_semantic": include_semantic,
+            },
+        )
+
+        # Flatten episode results (Go API returns {"episode": {...}, "score": ..., "retrieval_source": ...})
+        flat_episodes: List[EpisodeResult] = []
+        for item in raw.get("episodes", []):
+            ep = item.get("episode") or {}
+            flat_episodes.append(
+                EpisodeResult(
+                    episode_id=ep.get("episode_id", ""),
+                    agent_id=ep.get("agent_id", ""),
+                    raw_content=ep.get("raw_content", ""),
+                    intent=ep.get("intent", ""),
+                    domain=ep.get("domain", "general"),
+                    outcome=ep.get("outcome", "unknown"),
+                    importance_score=float(ep.get("importance_score", 0.5)),
+                    retrieval_count=int(ep.get("retrieval_count", 0)),
+                    consolidated=bool(ep.get("consolidated", False)),
+                    created_at=ep.get("created_at"),
+                    score=float(item.get("score", 0.0)),
+                    retrieval_source=str(item.get("retrieval_source", "qdrant")),
+                )
+            )
+
+        sem_raw = raw.get("semantic_memories", [])
+        semantic: List[SemanticMemory] = []
+        for sm in sem_raw:
+            semantic.append(
+                SemanticMemory(
+                    semantic_id=sm.get("semantic_id", ""),
+                    agent_id=sm.get("agent_id", ""),
+                    fact=sm.get("fact", ""),
+                    confidence=float(sm.get("confidence", 0.0)),
+                    evidence_count=int(sm.get("evidence_count", 0)),
+                    domain=sm.get("domain", "general"),
+                    fact_type=sm.get("fact_type", "pattern"),
+                    created_at=sm.get("created_at"),
+                    score=sm.get("score"),
+                )
+            )
+
+        result = RetrieveResult(
+            episodes=flat_episodes,
+            semantic_memories=semantic,
+            injection_prompt=raw.get("injection_prompt", ""),
+            latency_ms=int(raw.get("latency_ms", 0)),
+        )
+        return result
+
+    async def create_agent(
+        self,
+        name: str,
+        description: str = "",
+    ) -> Agent:
+        """Create a new agent to store memories for."""
+        if not name:
+            raise ValidationError("name is required")
+
+        req = CreateAgentRequest(name=name, description=description)
+        response = await self._async_request(
+            "POST",
+            "/api/v1/agents",
+            json=req.model_dump(),
+        )
+        return Agent(**response)
+
+    async def get_semantic_memory(
+        self,
+        agent_id: str,
+        limit: int = 20,
+    ) -> List[SemanticMemory]:
+        """Get semantic memories (consolidated facts) for an agent."""
+        if not agent_id:
+            raise ValidationError("agent_id is required")
+        response = await self._async_request(
+            "GET",
+            f"/api/v1/semantic?agent_id={agent_id}&limit={limit}",
+        )
+        items = response.get("memories") or response.get("items") or []
+        return [
+            SemanticMemory(
+                semantic_id=sm.get("semantic_id", ""),
+                agent_id=sm.get("agent_id", ""),
+                fact=sm.get("fact", ""),
+                confidence=float(sm.get("confidence", 0.0)),
+                evidence_count=int(sm.get("evidence_count", 0)),
+                domain=sm.get("domain", "general"),
+                fact_type=sm.get("fact_type", "pattern"),
+                created_at=sm.get("created_at"),
+                score=sm.get("score"),
+            )
+            for sm in items
+        ]
+
+    async def list_episodes(
+        self,
+        agent_id: str,
+        limit: int = 20,
+        offset: int = 0,
+        domain: Optional[str] = None,
+        outcome: Optional[str] = None,
+    ) -> Tuple[List[EpisodeResult], int]:
+        """
+        List episodes for an agent. Returns (episodes, total_count).
+
+        This flattens the Go API /episodes response into EpisodeResult objects
+        with score=0 and retrieval_source="episodes".
+        """
+        if not agent_id:
+            raise ValidationError("agent_id is required")
+
+        params = f"agent_id={agent_id}&limit={limit}&offset={offset}"
+        if domain:
+            params += f"&domain={domain}"
+        if outcome:
+            params += f"&outcome={outcome}"
+
+        response = await self._async_request("GET", f"/api/v1/episodes?{params}")
+        eps: List[EpisodeResult] = []
+        for ep in response.get("episodes", []):
+            eps.append(
+                EpisodeResult(
+                    episode_id=ep.get("episode_id", ""),
+                    agent_id=ep.get("agent_id", ""),
+                    raw_content=ep.get("raw_content", ""),
+                    intent=ep.get("intent", ""),
+                    domain=ep.get("domain", "general"),
+                    outcome=ep.get("outcome", "unknown"),
+                    importance_score=float(ep.get("importance_score", 0.5)),
+                    retrieval_count=int(ep.get("retrieval_count", 0)),
+                    consolidated=bool(ep.get("consolidated", False)),
+                    created_at=ep.get("created_at"),
+                    score=0.0,
+                    retrieval_source="episodes",
+                )
+            )
+        total = int(response.get("total", len(eps)))
+        return eps, total
+
+    async def close(self) -> None:
+        """Close the async HTTP client. Call when done."""
+        if self._async_client is not None:
+            await self._async_client.aclose()
+        if self._sync_client is not None:
+            self._sync_client.close()
+
+    # ── SYNC WRAPPERS ─────────────────────────────────────────────
+    # For developers not using async — wraps async methods
+
+    def write_sync(self, content: str, agent_id: str, **kwargs: Any) -> WriteResult:
+        """Synchronous version of write(). Use in non-async code."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.write(content, agent_id, **kwargs),
+        )
+
+    def retrieve_sync(self, query: str, agent_id: str, **kwargs: Any) -> RetrieveResult:
+        """Synchronous version of retrieve(). Use in non-async code."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.retrieve(query, agent_id, **kwargs),
+        )
+
+    def create_agent_sync(self, name: str, description: str = "") -> Agent:
+        """Synchronous version of create_agent()."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.create_agent(name, description),
+        )
+
+    # ── CONTEXT MANAGER ───────────────────────────────────────────
+
+    async def __aenter__(self) -> "REMClient":
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:  # type: ignore[override]
+        await self.close()
+
+    # ── PRIVATE HTTP LAYER ────────────────────────────────────────
+
+    def _get_async_client(self) -> httpx.AsyncClient:
+        if self._async_client is None or self._async_client.is_closed:
+            self._async_client = httpx.AsyncClient(
+                base_url=self.base_url,
+                headers=self._headers,
+                timeout=self.timeout,
+            )
+        return self._async_client
+
+    async def _async_request(
+        self,
+        method: str,
+        path: str,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        client = self._get_async_client()
+        last_error: Optional[REMError] = None
+
+        for attempt in range(self.max_retries):
+            try:
+                response = await client.request(method, path, **kwargs)
+                return self._handle_response(response)
+            except httpx.ConnectError as e:
+                last_error = ConnectionError(
+                    f"Cannot connect to REM API at {self.base_url}. "
+                    f"Is the server running? Error: {e}",
+                )
+                if attempt < self.max_retries - 1:
+                    await asyncio.sleep(2**attempt)
+            except httpx.TimeoutException:
+                last_error = APIError(
+                    f"Request to {self.base_url}{path} timed out after {self.timeout}s",
+                )
+                if attempt < self.max_retries - 1:
+                    await asyncio.sleep(1)
+
+        if last_error is not None:
+            raise last_error
+        raise ConnectionError("Request failed and no error captured")
+
+    def _handle_response(self, response: httpx.Response) -> Dict[str, Any]:
+        if response.status_code in (200, 201):
+            data = response.json()
+            if isinstance(data, Dict):
+                return data
+            return {"data": data}
+
+        try:
+            error_body = response.json()
+            message = error_body.get("error", f"HTTP {response.status_code}")
+        except Exception:
+            message = f"HTTP {response.status_code}"
+
+        status = response.status_code
+        if status == 400:
+            raise ValidationError(message, status)
+        if status == 401:
+            raise AuthenticationError(message, status)
+        if status == 404:
+            raise NotFoundError(message, status)
+        if status == 429:
+            retry_after = int(response.headers.get("Retry-After", "60"))
+            raise RateLimitError(message, retry_after=retry_after)
+        raise APIError(message, status)
+
+

rem_memory-0.1.0/rem_memory/exceptions.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import Optional
+
+
+class REMError(Exception):
+    """Base exception for all REM errors."""
+
+    def __init__(self, message: str, status_code: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.message!r})"
+
+
+class AuthenticationError(REMError):
+    """Raised when API key is invalid or missing."""
+
+
+class NotFoundError(REMError):
+    """Raised when requested resource doesn't exist."""
+
+
+class RateLimitError(REMError):
+    """Raised when rate limit exceeded."""
+
+    def __init__(self, message: str, retry_after: Optional[int] = None) -> None:
+        super().__init__(message, 429)
+        self.retry_after = retry_after
+
+
+class APIError(REMError):
+    """Generic API error with status code."""
+
+
+class ConnectionError(REMError):
+    """Raised when cannot connect to REM API."""
+
+
+class ValidationError(REMError):
+    """Raised when request data is invalid."""

rem_memory-0.1.0/rem_memory/integrations/autogen.py

@@ -0,0 +1,196 @@
+"""
+AutoGen integration for REM (Recursive Episodic Memory).
+
+This module provides a drop-in memory store that injects relevant context
+from REM into AutoGen agent conversations and persists interactions back
+to episodic memory automatically.
+
+Usage::
+
+    from rem_memory.integrations.autogen import REMMemoryStore
+
+    store = REMMemoryStore(api_key="rem_sk_...", agent_id="agent_autogen_001")
+
+    # Retrieve relevant context string for injection into system_message
+    context = await store.get_context("user's TypeScript preferences")
+
+    # After a conversation turn, persist it
+    await store.save_turn(user_input="...", assistant_output="...")
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, Dict, List, Optional
+
+from ..client import REMClient
+from ..types import RetrieveResult
+
+logger = logging.getLogger(__name__)
+
+
+class REMMemoryStore:
+    """
+    Async memory store for AutoGen agents backed by REM.
+
+    Parameters
+    ----------
+    api_key:
+        REM API key (``X-API-Key`` header).
+    agent_id:
+        Identifier for the AutoGen agent.
+    user_id:
+        Optional user identifier scoped to this conversation.
+    base_url:
+        Base URL for the REM Go API (default ``http://localhost:8080``).
+    top_k:
+        How many episodes/facts to retrieve for context injection.
+    include_semantic:
+        Whether to include consolidated semantic facts in retrieval.
+    inject_format:
+        ``"prose"`` (paragraph) or ``"bullets"`` (markdown list).
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        agent_id: str,
+        user_id: str = "user_default",
+        base_url: str = "http://localhost:8080",
+        top_k: int = 5,
+        include_semantic: bool = True,
+        inject_format: str = "prose",
+    ) -> None:
+        self.agent_id = agent_id
+        self.user_id = user_id
+        self.top_k = top_k
+        self.include_semantic = include_semantic
+        self.inject_format = inject_format
+        self._client = REMClient(api_key=api_key, base_url=base_url)
+
+    # ── Context retrieval ────────────────────────────────────────────────────
+
+    async def get_context(self, query: str) -> str:
+        """
+        Retrieve relevant memories and return them as a formatted string
+        suitable for injection into an AutoGen agent's system message or
+        the first turn of a conversation.
+
+        Parameters
+        ----------
+        query:
+            The user input or topic to retrieve relevant memories for.
+
+        Returns
+        -------
+        str
+            Formatted context string, or empty string if no memories found.
+        """
+        async with self._client:
+            result: RetrieveResult = await self._client.retrieve(
+                query=query,
+                agent_id=self.agent_id,
+                top_k=self.top_k,
+                include_semantic=self.include_semantic,
+            )
+
+        if not result.episodes and not result.semantic_memories:
+            return ""
+
+        if hasattr(result, "injection_prompt") and result.injection_prompt:
+            return result.injection_prompt
+
+        return self._format_context(result)
+
+    def get_context_sync(self, query: str) -> str:
+        """Synchronous wrapper around :meth:`get_context`."""
+        return asyncio.get_event_loop().run_until_complete(self.get_context(query))
+
+    # ── Saving turns ─────────────────────────────────────────────────────────
+
+    async def save_turn(
+        self,
+        user_input: str,
+        assistant_output: str,
+        session_id: Optional[str] = None,
+        outcome: str = "success",
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """
+        Persist a conversation turn to REM episodic memory.
+
+        Parameters
+        ----------
+        user_input:
+            The user message for this turn.
+        assistant_output:
+            The agent's response for this turn.
+        session_id:
+            Optional session identifier for grouping turns.
+        outcome:
+            Conversation outcome signal: ``"success"``, ``"partial"``, or ``"failure"``.
+        metadata:
+            Additional key/value pairs to attach to the episode.
+        """
+        content = f"User: {user_input}\nAssistant: {assistant_output}"
+        async with self._client:
+            await self._client.write(
+                content=content,
+                agent_id=self.agent_id,
+                user_id=self.user_id,
+                session_id=session_id,
+                outcome=outcome,
+                metadata=metadata or {},
+            )
+
+    def save_turn_sync(self, user_input: str, assistant_output: str, **kwargs: Any) -> None:
+        """Synchronous wrapper around :meth:`save_turn`."""
+        asyncio.get_event_loop().run_until_complete(
+            self.save_turn(user_input, assistant_output, **kwargs)
+        )
+
+    # ── AutoGen hook helpers ─────────────────────────────────────────────────
+
+    def build_system_prefix(self, query: str) -> str:
+        """
+        Return a system message prefix string that injects relevant memories.
+
+        Suitable for prepending to an AutoGen agent's ``system_message``:
+
+        .. code-block:: python
+
+            prefix = store.build_system_prefix("code style preferences")
+            agent = ConversableAgent(
+                name="assistant",
+                system_message=prefix + "\\n\\nYou are a helpful coding assistant.",
+            )
+        """
+        context = self.get_context_sync(query)
+        if not context:
+            return ""
+        return f"## Relevant memory context\\n\\n{context}\\n\\n---\\n\\n"
+
+    # ── Formatting helpers ───────────────────────────────────────────────────
+
+    def _format_context(self, result: RetrieveResult) -> str:
+        parts: List[str] = []
+
+        if result.semantic_memories:
+            if self.inject_format == "bullets":
+                parts.append("**Known facts about this user/agent:**")
+                for sm in result.semantic_memories:
+                    parts.append(f"- {sm.fact} (confidence: {sm.confidence:.0%})")
+            else:
+                facts = "; ".join(sm.fact for sm in result.semantic_memories)
+                parts.append(f"Known facts: {facts}.")
+
+        if result.episodes:
+            if self.inject_format == "bullets":
+                parts.append("**Recent relevant episodes:**")
+                for ep in result.episodes[:3]:
+                    parts.append(f"- {ep.intent} [{ep.outcome}]")
+            else:
+                recent = "; ".join(ep.intent for ep in result.episodes[:3])
+                parts.append(f"Recent interactions: {recent}.")
+
+        return "\n".join(parts)

rem_memory-0.1.0/rem_memory/integrations/langchain.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, PrivateAttr
+
+try:
+    from langchain.memory import BaseChatMemory
+except ImportError as exc:  # pragma: no cover - import-time guard
+    raise ImportError(
+        "langchain package required. Install with: pip install rem-memory[langchain]",
+    ) from exc
+
+from ..client import REMClient
+
+
+class REMMemory(BaseChatMemory, BaseModel):
+    """
+    Drop-in LangChain memory backed by REM.
+
+    Usage:
+        from rem_memory.integrations.langchain import REMMemory
+
+        memory = REMMemory(
+            api_key="rem_sk_...",
+            agent_id="my-agent",
+        )
+        chain = ConversationChain(llm=ChatOpenAI(), memory=memory)
+    """
+
+    api_key: str
+    agent_id: str
+    user_id: str = "default"
+    memory_key: str = "relevant_memories"
+    return_messages: bool = False
+
+    _client: Optional[REMClient] = PrivateAttr(default=None)
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    def model_post_init(self, __context: Any) -> None:  # type: ignore[override]
+        base_url = os.getenv("REM_BASE_URL", "https://api.rem.ai")
+        self._client = REMClient(api_key=self.api_key, base_url=base_url)
+        super().model_post_init(__context)  # type: ignore[misc]
+
+    @property
+    def memory_variables(self) -> List[str]:
+        return [self.memory_key]
+
+    def load_memory_variables(self, inputs: Dict[str, Any]) -> Dict[str, Any]:
+        """Called before LLM invoke — fetches relevant memories."""
+        query = (
+            inputs.get("input")
+            or inputs.get("question")
+            or inputs.get("human_input")
+            or ""
+        )
+
+        if not query or self._client is None:
+            return {self.memory_key: ""}
+
+        result = self._client.retrieve_sync(
+            query=query,
+            agent_id=self.agent_id,
+            top_k=5,
+            include_semantic=True,
+        )
+
+        return {self.memory_key: result.injection_prompt}
+
+    def save_context(self, inputs: Dict[str, Any], outputs: Dict[str, Any]) -> None:
+        """Called after LLM response — writes episode to REM."""
+        if self._client is None:
+            return
+
+        human_input = (
+            inputs.get("input")
+            or inputs.get("question")
+            or inputs.get("human_input")
+            or ""
+        )
+        ai_output = (
+            outputs.get("response")
+            or outputs.get("output")
+            or outputs.get("text")
+            or ""
+        )
+
+        if not human_input:
+            return
+
+        content = f"Human: {human_input}\nAssistant: {ai_output}"
+
+        self._client.write_sync(
+            content=content,
+            agent_id=self.agent_id,
+            user_id=self.user_id,
+            outcome="success",
+        )
+
+    def clear(self) -> None:
+        """REM memories persist. This is intentional."""
+        return
+

rem_memory-0.1.0/rem_memory/types.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import List, Optional
+
+from pydantic import BaseModel, ConfigDict
+
+
+def _ensure_aware(dt: datetime) -> datetime:
+    """Ensure datetimes are timezone-aware (UTC)."""
+    if dt.tzinfo is None:
+        return dt.replace(tzinfo=timezone.utc)
+    return dt
+
+
+class BaseModelTZ(BaseModel):
+    """Base model that normalises datetimes to timezone-aware UTC."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    def model_post_init(self, __context) -> None:  # type: ignore[override]
+        for field_name, field in self.model_fields.items():  # type: ignore[attr-defined]
+            value = getattr(self, field_name)
+            if isinstance(value, datetime):
+                setattr(self, field_name, _ensure_aware(value))
+        super().model_post_init(__context)  # type: ignore[misc]
+
+
+class WriteResult(BaseModelTZ):
+    episode_id: str
+    agent_id: str
+    created_at: datetime
+    status: str  # "stored"
+
+
+class EpisodeResult(BaseModelTZ):
+    episode_id: str
+    agent_id: str
+    raw_content: str
+    intent: str
+    domain: str
+    outcome: str
+    importance_score: float
+    retrieval_count: int
+    consolidated: bool
+    created_at: datetime
+    score: float  # retrieval relevance score
+    retrieval_source: str  # "qdrant" | "graph" | "semantic" | "episodes"
+
+
+class SemanticMemory(BaseModelTZ):
+    semantic_id: str
+    agent_id: str
+    fact: str
+    confidence: float
+    evidence_count: int
+    domain: str
+    fact_type: str  # "preference" | "rule" | "pattern" | "skill" | "fact"
+    created_at: datetime
+    score: Optional[float] = None  # if retrieved, has relevance score
+
+
+class RetrieveResult(BaseModelTZ):
+    episodes: List[EpisodeResult]
+    semantic_memories: List[SemanticMemory]
+    injection_prompt: str
+    latency_ms: int
+
+    def to_prompt(self) -> str:
+        """Alias for injection_prompt — most common usage."""
+        return self.injection_prompt
+
+
+class Agent(BaseModelTZ):
+    agent_id: str
+    name: str
+    description: str
+    total_episodes: int
+    total_semantic_memories: int
+    last_active_at: Optional[datetime]
+    created_at: datetime
+
+
+class CreateAgentRequest(BaseModelTZ):
+    name: str
+    description: str = ""
+
+