memnos-sdk 1.1.0__tar.gz

memnos_sdk-1.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: memnos-sdk
+Version: 1.1.0
+Summary: memnos SDK — memory layer for AI agents
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == "langchain"
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.10; extra == "llamaindex"
+Provides-Extra: all
+Requires-Dist: memnos-sdk[langchain,llamaindex]; extra == "all"

memnos_sdk-1.1.0/README.md

@@ -0,0 +1,241 @@
+# memnos-sdk
+
+Python SDK for [memnos](https://github.com/thameema/memnos) — persistent memory for AI agents.
+
+```python
+from memnos_sdk import MemnosClient
+
+client = MemnosClient(base_url="http://localhost:8766", api_key="your-key")
+
+client.write("Chose PostgreSQL for the event store — ACID guarantees required",
+             namespace="org:myproject",
+             memory_type="decision",
+             affects=["event-store", "payment-service"],
+             rationale="Transactional writes across tables need ACID; Redis/Kafka can't provide this.")
+
+results = client.search("event store choice", namespace="org:myproject")
+for r in results:
+    print(r.content)
+```
+
+## Install
+
+```bash
+pip install memnos-sdk
+```
+
+With LangChain or LlamaIndex integrations:
+
+```bash
+pip install "memnos-sdk[langchain]"
+pip install "memnos-sdk[llamaindex]"
+pip install "memnos-sdk[all]"
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+### Sync client
+
+```python
+from memnos_sdk import MemnosClient
+
+client = MemnosClient(
+    base_url="http://localhost:8766",
+    api_key="memnos-local-dev-key",
+)
+
+# Write a memory
+mem = client.write(
+    content="Use ArcadeDB as the sole graph store — single process handles vector + graph + docs",
+    namespace="org:myproject",
+    memory_type="decision",
+    affects=["storage", "arcadedb"],
+    rationale="Eliminates three-service ops complexity (Neo4j + Qdrant + Graphiti).",
+    tags=["architecture", "adr"],
+)
+print(mem.id)
+
+# Search across all accessible namespaces
+results = client.search("storage architecture decision")
+for r in results:
+    print(f"[{r.score:.2f}] {r.content[:80]}")
+
+# Get a specific memory
+mem = client.get(mem.id)
+
+# Delete a memory
+client.delete(mem.id)
+```
+
+### Async client
+
+```python
+import asyncio
+from memnos_sdk import AsyncMemnosClient
+
+async def main():
+    async with AsyncMemnosClient(base_url="http://localhost:8766", api_key="key") as client:
+        await client.write("Chose gRPC for inter-service comms", namespace="org:svc",
+                           memory_type="decision", affects=["api-gateway"])
+        results = await client.search("gRPC decision")
+        for r in results:
+            print(r.content)
+
+asyncio.run(main())
+```
+
+## Memory types
+
+| Type | When to use |
+|------|-------------|
+| `decision` | Architectural choices — what was decided and why |
+| `constraint` | Rules that apply to a component — enforced at code review |
+| `adr` | Architecture Decision Records |
+| `fact` | Context, session notes, anything else |
+| `session` | Automated session summaries from hooks |
+
+```python
+from memnos_sdk import MemoryType
+
+client.write("...", namespace="org:x", memory_type=MemoryType.DECISION)
+```
+
+## Corpus — architecture docs as a CI gate
+
+Register a folder of markdown ADRs/decision docs and query them as constraints:
+
+```python
+from memnos_sdk import MemnosClient
+
+client = MemnosClient(base_url="http://localhost:8766", api_key="key")
+
+# Register a corpus (one-time setup)
+corpus = client.corpus.register(
+    name="backend-adrs",
+    source="./docs/architecture",
+    namespace="org:myproject",
+)
+
+# Check a code change against registered constraints
+result = client.corpus.check(
+    corpus_id=corpus.id,
+    component="payment-service",
+    code_snippet="db.execute('INSERT INTO payments ...')",
+)
+for hit in result.violations:
+    print(f"[{hit.severity}] {hit.rule}")
+```
+
+## LangChain integration
+
+```python
+from langchain_openai import ChatOpenAI
+from langchain.chains import ConversationChain
+from memnos_sdk.integrations.langchain import MemnosMemory
+
+memory = MemnosMemory(
+    base_url="http://localhost:8766",
+    api_key="your-key",
+    namespace="org:myproject",
+    top_k=5,
+)
+
+chain = ConversationChain(llm=ChatOpenAI(), memory=memory)
+response = chain.predict(input="What storage decisions have we made?")
+```
+
+`MemnosMemory` loads the top-k most relevant memories as conversation context and writes new exchanges back to memnos automatically.
+
+## LlamaIndex integration
+
+```python
+from llama_index.core import VectorStoreIndex
+from memnos_sdk.integrations.llamaindex import MemnosReader
+
+reader = MemnosReader(base_url="http://localhost:8766", api_key="your-key")
+documents = reader.load_data(namespace="org:myproject", query="architecture decisions", top_k=20)
+
+index = VectorStoreIndex.from_documents(documents)
+query_engine = index.as_query_engine()
+print(query_engine.query("Which storage system did we pick and why?"))
+```
+
+## Governance queries
+
+```python
+# Get all decisions governing a component
+decisions = client.get_governing_decisions(namespace="org:myproject", component="auth-service")
+for d in decisions:
+    print(f"[{d.memory_type}] {d.content[:80]}")
+    print(f"  WHY: {d.rationale}")
+
+# Get all constraints in a namespace
+constraints = client.get_constraints(namespace="org:myproject")
+```
+
+## Namespace export / import
+
+```python
+# Export
+data = client.export_namespace("org:myproject")
+import json
+json.dump(data, open("backup.json", "w"), indent=2)
+
+# Import into a new namespace
+with open("backup.json") as f:
+    client.import_namespace("org:newproject", json.load(f))
+```
+
+## Error handling
+
+```python
+from memnos_sdk.exceptions import NotFoundError, AuthenticationError, MemnosError
+
+try:
+    mem = client.get("nonexistent-id")
+except NotFoundError:
+    print("Memory not found")
+except AuthenticationError:
+    print("Check your API key")
+except MemnosError as e:
+    print(f"Memnos error: {e}")
+```
+
+| Exception | When raised |
+|-----------|-------------|
+| `MemnosError` | Base class for all SDK errors |
+| `AuthenticationError` | Invalid or missing API key |
+| `NotFoundError` | Memory or corpus not found |
+| `ValidationError` | Malformed request (bad namespace, etc.) |
+| `ServerError` | 5xx from the memnos server |
+| `ConnectionError` | Server unreachable |
+
+## Configuration
+
+```python
+client = MemnosClient(
+    base_url="http://localhost:8766",  # or MEMNOS_API env var
+    api_key="your-key",               # or MEMNOS_KEY env var
+    timeout=15.0,                     # per-request timeout in seconds
+)
+```
+
+Environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MEMNOS_API` | `http://localhost:8766` | Server URL |
+| `MEMNOS_KEY` | — | API key |
+
+## Running memnos locally
+
+```bash
+git clone https://github.com/thameema/memnos
+cd memnos
+docker compose up -d
+# Server is at http://localhost:8766, key: memnos-local-dev-key
+```
+
+See the [main README](../../README.md) for full setup.

memnos_sdk-1.1.0/memnos_sdk/__init__.py

@@ -0,0 +1,52 @@
+"""memnos-sdk — memory layer for AI agents."""
+from memnos_sdk.client import AsyncMemnosClient, MemnosClient
+from memnos_sdk.models import (
+    Memory,
+    MemoryType,
+    SearchResult,
+    HealthStatus,
+    CorpusInfo,
+    CorpusStatus,
+    ConstraintHit,
+    CheckResult,
+)
+from memnos_sdk.corpus import AsyncCorpusClient, SyncCorpusClient
+from memnos_sdk.exceptions import (
+    MemnosError,
+    AuthenticationError,
+    NotFoundError,
+    ValidationError,
+    ServerError,
+    ConnectionError,
+)
+
+__version__ = "1.1.0"
+SCHEMA_VERSION = "1.0"
+
+__all__ = [
+    # Clients
+    "MemnosClient",
+    "AsyncMemnosClient",
+    # Memory models
+    "Memory",
+    "MemoryType",
+    "SearchResult",
+    "HealthStatus",
+    # Corpus models
+    "CorpusInfo",
+    "CorpusStatus",
+    "ConstraintHit",
+    "CheckResult",
+    # Corpus sub-clients (advanced use)
+    "AsyncCorpusClient",
+    "SyncCorpusClient",
+    # Exceptions
+    "MemnosError",
+    "AuthenticationError",
+    "NotFoundError",
+    "ValidationError",
+    "ServerError",
+    "ConnectionError",
+    "__version__",
+    "SCHEMA_VERSION",
+]

memnos_sdk-1.1.0/memnos_sdk/_http.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from memnos_sdk.exceptions import (
+    AuthenticationError,
+    ConnectionError,
+    NotFoundError,
+    ServerError,
+    ValidationError,
+)
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    code = response.status_code
+    if code in (401, 403):
+        raise AuthenticationError(f"HTTP {code}: {response.text}")
+    if code == 404:
+        raise NotFoundError(f"HTTP 404: {response.text}")
+    if code == 422:
+        raise ValidationError(f"HTTP 422: {response.text}")
+    if code >= 500:
+        raise ServerError(f"HTTP {code}: {response.text}")
+    response.raise_for_status()
+
+
+class _SyncTransport:
+    def __init__(self, base_url: str, api_key: str, timeout: float = 30.0) -> None:
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=timeout,
+        )
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> dict:
+        try:
+            response = self._client.get(path, params=params)
+        except httpx.TransportError as exc:
+            raise ConnectionError(str(exc)) from exc
+        _raise_for_status(response)
+        return response.json()
+
+    def post(self, path: str, json: dict | None = None) -> dict:
+        try:
+            response = self._client.post(path, json=json)
+        except httpx.TransportError as exc:
+            raise ConnectionError(str(exc)) from exc
+        _raise_for_status(response)
+        return response.json()
+
+    def delete(self, path: str) -> None:
+        try:
+            response = self._client.delete(path)
+        except httpx.TransportError as exc:
+            raise ConnectionError(str(exc)) from exc
+        _raise_for_status(response)
+
+    def close(self) -> None:
+        self._client.close()
+
+
+class _AsyncTransport:
+    def __init__(self, base_url: str, api_key: str, timeout: float = 30.0) -> None:
+        self._client = httpx.AsyncClient(
+            base_url=base_url,
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=timeout,
+        )
+
+    async def get(self, path: str, params: dict[str, Any] | None = None) -> dict:
+        try:
+            response = await self._client.get(path, params=params)
+        except httpx.TransportError as exc:
+            raise ConnectionError(str(exc)) from exc
+        _raise_for_status(response)
+        return response.json()
+
+    async def post(self, path: str, json: dict | None = None) -> dict:
+        try:
+            response = await self._client.post(path, json=json)
+        except httpx.TransportError as exc:
+            raise ConnectionError(str(exc)) from exc
+        _raise_for_status(response)
+        return response.json()
+
+    async def delete(self, path: str) -> None:
+        try:
+            response = await self._client.delete(path)
+        except httpx.TransportError as exc:
+            raise ConnectionError(str(exc)) from exc
+        _raise_for_status(response)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()