memnos-sdk 1.1.0__py3-none-any.whl

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/_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()

memnos_sdk/client.py

@@ -0,0 +1,418 @@
+from __future__ import annotations
+
+import asyncio
+import threading
+from contextlib import asynccontextmanager, contextmanager
+from datetime import datetime
+from typing import Any, AsyncIterator, Iterator
+
+from memnos_sdk._http import _AsyncTransport, _SyncTransport
+from memnos_sdk.corpus import AsyncCorpusClient, SyncCorpusClient
+from memnos_sdk.models import HealthStatus, Memory, MemoryType
+
+
+def _parse_memory(data: dict) -> Memory:
+    raw_type = data.get("memory_type", "fact")
+    try:
+        mem_type = MemoryType(raw_type)
+    except ValueError:
+        mem_type = MemoryType.FACT
+    return Memory(
+        id=data["id"],
+        content=data["content"],
+        namespace=data["namespace"],
+        memory_type=mem_type,
+        tags=data.get("tags") or [],
+        affects=data.get("affects") or [],
+        rationale=data.get("rationale") or "",
+        author=data.get("author") or "",
+        created_at=data["created_at"],
+        score=data.get("score"),
+        provenance=data.get("provenance") or {},
+        contradiction_warnings=data.get("contradiction_warnings") or [],
+    )
+
+
+def _write_payload(
+    content: str,
+    namespace: str,
+    memory_type: MemoryType | str,
+    tags: list[str],
+    affects: list[str],
+    rationale: str,
+    author: str,
+    source: str,
+    metadata: dict,
+    expires_at: datetime | None,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "content": content,
+        "namespace": namespace,
+        "memory_type": memory_type.value if isinstance(memory_type, MemoryType) else memory_type,
+        "tags": tags,
+        "affects": affects,
+        "rationale": rationale,
+        "author": author,
+        "source": source,
+        "metadata": metadata,
+    }
+    if expires_at is not None:
+        payload["expires_at"] = expires_at.isoformat()
+    return payload
+
+
+def _search_params(
+    query: str,
+    namespace: str,
+    top_k: int,
+    as_of: datetime | None,
+) -> dict[str, Any]:
+    params: dict[str, Any] = {"q": query, "ns": namespace, "top_k": top_k}
+    if as_of is not None:
+        params["as_of"] = as_of.isoformat()
+    return params
+
+
+class AsyncMemnosClient:
+    def __init__(
+        self,
+        url: str = "http://localhost:8766",
+        api_key: str = "",
+        timeout: float = 30.0,
+    ) -> None:
+        self._transport = _AsyncTransport(url, api_key, timeout)
+        self.corpus = AsyncCorpusClient(self._transport)
+
+    async def __aenter__(self) -> "AsyncMemnosClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self._transport.aclose()
+
+    async def health(self) -> HealthStatus:
+        data = await self._transport.get("/api/v1/admin/health")
+        return HealthStatus(
+            status=data.get("status", "unknown"),
+            arcadedb=data.get("arcadedb", "unknown"),
+            version=data.get("version", ""),
+            schema_version=data.get("schema_version", "1.0"),
+        )
+
+    async def write(
+        self,
+        content: str,
+        namespace: str,
+        *,
+        memory_type: MemoryType | str = MemoryType.FACT,
+        tags: list[str] = [],
+        affects: list[str] = [],
+        rationale: str = "",
+        author: str = "",
+        source: str = "sdk",
+        metadata: dict = {},
+        expires_at: datetime | None = None,
+    ) -> Memory:
+        data = await self._transport.post(
+            "/api/v1/memory/",
+            json=_write_payload(
+                content, namespace, memory_type, tags, affects,
+                rationale, author, source, metadata, expires_at,
+            ),
+        )
+        return _parse_memory(data)
+
+    async def search(
+        self,
+        query: str,
+        namespace: str,
+        *,
+        top_k: int = 10,
+        as_of: datetime | None = None,
+    ) -> list[Memory]:
+        data = await self._transport.get(
+            "/api/v1/memory/search",
+            params=_search_params(query, namespace, top_k, as_of),
+        )
+        return [_parse_memory(item) for item in data]
+
+    async def get(self, memory_id: str) -> Memory:
+        data = await self._transport.get(f"/api/v1/memory/{memory_id}")
+        return _parse_memory(data)
+
+    async def delete(self, memory_id: str) -> None:
+        await self._transport.delete(f"/api/v1/memory/{memory_id}")
+
+    async def get_constraints(self, namespace: str) -> list[Memory]:
+        """Return all active constraints for a namespace (score=2.0, always governs)."""
+        results = await self.search(
+            "constraints rules must always", namespace=namespace, top_k=50
+        )
+        return [m for m in results if m.memory_type == MemoryType.CONSTRAINT]
+
+    async def get_governing_decisions(
+        self, entities: list[str], namespace: str
+    ) -> list[Memory]:
+        """Return decisions/ADRs whose affects[] overlaps with the given entity names."""
+        query = " ".join(entities)
+        results = await self.search(query, namespace=namespace, top_k=100)
+        entity_set = {e.lower() for e in entities}
+        return [
+            m for m in results
+            if m.memory_type in (MemoryType.DECISION, MemoryType.ADR)
+            and entity_set & {a.lower() for a in m.affects}
+        ]
+
+    async def export_namespace(
+        self,
+        namespace: str,
+        *,
+        memory_type: str | None = None,
+        include_superseded: bool = False,
+    ) -> dict:
+        """Export all memories in a namespace. Returns the export envelope dict."""
+        params: dict[str, Any] = {"ns": namespace, "format": "json"}
+        if memory_type:
+            params["memory_type"] = memory_type
+        if include_superseded:
+            params["include_superseded"] = "true"
+        return await self._transport.get("/api/v1/admin/export", params=params)
+
+    async def import_namespace(
+        self,
+        data: dict,
+        *,
+        target_namespace: str | None = None,
+    ) -> dict:
+        """Import memories from an export envelope. Returns {imported, skipped, namespace}."""
+        path = "/api/v1/admin/import"
+        if target_namespace:
+            from urllib.parse import quote
+            path = f"{path}?ns={quote(target_namespace, safe='')}"
+        return await self._transport.post(path, json=data)
+
+    async def list_namespaces(self) -> list[str]:
+        """Return all configured namespace names."""
+        data = await self._transport.get("/api/v1/admin/namespaces")
+        if isinstance(data, list):
+            return [item["name"] if isinstance(item, dict) else item for item in data]
+        return []
+
+    # ------------------------------------------------------------------
+    # Episodes
+    # ------------------------------------------------------------------
+
+    async def create_episode(
+        self,
+        title: str,
+        namespace: str,
+        *,
+        summary: str = "",
+        tags: list[str] = [],
+    ) -> dict:
+        """Create a named session container Episode. Returns the episode dict."""
+        return await self._transport.post(
+            "/api/v1/episodes/",
+            json={"title": title, "namespace": namespace, "summary": summary, "tags": tags},
+        )
+
+    async def close_episode(self, episode_id: str) -> dict:
+        """Mark an Episode as closed (session complete)."""
+        return await self._transport.post(f"/api/v1/episodes/{episode_id}/close", json={})
+
+    async def link_memory_to_episode(self, episode_id: str, memory_id: str) -> dict:
+        """Associate a memory with an Episode."""
+        return await self._transport.post(
+            f"/api/v1/episodes/{episode_id}/memories/{memory_id}", json={}
+        )
+
+    async def get_episode(self, episode_id: str) -> dict:
+        """Fetch an Episode with its linked memories."""
+        return await self._transport.get(f"/api/v1/episodes/{episode_id}")
+
+    async def list_episodes(self, namespace: str, *, include_closed: bool = False) -> list[dict]:
+        """List Episodes in a namespace."""
+        params: dict[str, Any] = {"ns": namespace}
+        if include_closed:
+            params["include_closed"] = "true"
+        data = await self._transport.get("/api/v1/episodes/", params=params)
+        return data if isinstance(data, list) else []
+
+    @asynccontextmanager
+    async def session(
+        self,
+        title: str,
+        namespace: str,
+        *,
+        summary: str = "",
+        tags: list[str] = [],
+        auto_link: bool = False,
+    ) -> AsyncIterator[dict]:
+        """Async context manager: open an Episode on enter, close on exit.
+
+        Usage:
+            async with client.session("my task", "org:acme:eng") as episode:
+                mem = await client.write("Found the bug", "org:acme:eng")
+                # memories written inside are auto-linked when auto_link=True
+        """
+        episode = await self.create_episode(title, namespace, summary=summary, tags=tags)
+        try:
+            yield episode
+        finally:
+            await self.close_episode(episode["id"])
+
+
+class MemnosClient:
+    """Synchronous wrapper around AsyncMemnosClient. Suitable for scripts and non-async code.
+
+    Usage:
+        client = MemnosClient(url="http://localhost:8766", api_key="my-key")
+        with client:
+            memories = client.search("database decisions", "org:acme:engineering")
+    """
+
+    def __init__(
+        self,
+        url: str = "http://localhost:8766",
+        api_key: str = "",
+        timeout: float = 30.0,
+    ) -> None:
+        self._async_client = AsyncMemnosClient(url=url, api_key=api_key, timeout=timeout)
+        self._loop = asyncio.new_event_loop()
+        self._lock = threading.Lock()
+        self.corpus = SyncCorpusClient(self._async_client.corpus, self._run)
+
+    def _run(self, coro):
+        with self._lock:
+            return self._loop.run_until_complete(coro)
+
+    def __enter__(self) -> "MemnosClient":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._run(self._async_client._transport.aclose())
+        self._loop.close()
+
+    def health(self) -> HealthStatus:
+        return self._run(self._async_client.health())
+
+    def write(
+        self,
+        content: str,
+        namespace: str,
+        *,
+        memory_type: MemoryType | str = MemoryType.FACT,
+        tags: list[str] = [],
+        affects: list[str] = [],
+        rationale: str = "",
+        author: str = "",
+        source: str = "sdk",
+        metadata: dict = {},
+        expires_at: datetime | None = None,
+    ) -> Memory:
+        return self._run(
+            self._async_client.write(
+                content, namespace,
+                memory_type=memory_type, tags=tags, affects=affects,
+                rationale=rationale, author=author, source=source,
+                metadata=metadata, expires_at=expires_at,
+            )
+        )
+
+    def search(
+        self,
+        query: str,
+        namespace: str,
+        *,
+        top_k: int = 10,
+        as_of: datetime | None = None,
+    ) -> list[Memory]:
+        return self._run(
+            self._async_client.search(query, namespace, top_k=top_k, as_of=as_of)
+        )
+
+    def get(self, memory_id: str) -> Memory:
+        return self._run(self._async_client.get(memory_id))
+
+    def delete(self, memory_id: str) -> None:
+        self._run(self._async_client.delete(memory_id))
+
+    def get_constraints(self, namespace: str) -> list[Memory]:
+        return self._run(self._async_client.get_constraints(namespace))
+
+    def get_governing_decisions(
+        self, entities: list[str], namespace: str
+    ) -> list[Memory]:
+        return self._run(
+            self._async_client.get_governing_decisions(entities, namespace)
+        )
+
+    def export_namespace(
+        self,
+        namespace: str,
+        *,
+        memory_type: str | None = None,
+        include_superseded: bool = False,
+    ) -> dict:
+        return self._run(
+            self._async_client.export_namespace(
+                namespace,
+                memory_type=memory_type,
+                include_superseded=include_superseded,
+            )
+        )
+
+    def import_namespace(
+        self,
+        data: dict,
+        *,
+        target_namespace: str | None = None,
+    ) -> dict:
+        return self._run(
+            self._async_client.import_namespace(data, target_namespace=target_namespace)
+        )
+
+    def list_namespaces(self) -> list[str]:
+        return self._run(self._async_client.list_namespaces())
+
+    # ------------------------------------------------------------------
+    # Episodes (sync wrappers)
+    # ------------------------------------------------------------------
+
+    def create_episode(self, title: str, namespace: str, *, summary: str = "", tags: list[str] = []) -> dict:
+        return self._run(self._async_client.create_episode(title, namespace, summary=summary, tags=tags))
+
+    def close_episode(self, episode_id: str) -> dict:
+        return self._run(self._async_client.close_episode(episode_id))
+
+    def link_memory_to_episode(self, episode_id: str, memory_id: str) -> dict:
+        return self._run(self._async_client.link_memory_to_episode(episode_id, memory_id))
+
+    def get_episode(self, episode_id: str) -> dict:
+        return self._run(self._async_client.get_episode(episode_id))
+
+    def list_episodes(self, namespace: str, *, include_closed: bool = False) -> list[dict]:
+        return self._run(self._async_client.list_episodes(namespace, include_closed=include_closed))
+
+    @contextmanager
+    def session(
+        self,
+        title: str,
+        namespace: str,
+        *,
+        summary: str = "",
+        tags: list[str] = [],
+    ) -> Iterator[dict]:
+        """Sync context manager: open an Episode on enter, close on exit.
+
+        Usage:
+            with client.session("my task", "org:acme:eng") as episode:
+                client.write("Found the bug", "org:acme:eng")
+        """
+        episode = self.create_episode(title, namespace, summary=summary, tags=tags)
+        try:
+            yield episode
+        finally:
+            self.close_episode(episode["id"])

memnos_sdk/corpus.py

@@ -0,0 +1,279 @@
+"""
+memnos_sdk.corpus — Corpus sub-client for architecture constraint management.
+
+Accessed via ``client.corpus`` on both AsyncMemnosClient and MemnosClient.
+Provides a typed interface to the corpus REST API without requiring callers
+to know endpoint paths or parse raw JSON.
+
+Async usage::
+
+    async with AsyncMemnosClient(url="...", api_key="...") as client:
+        corpus = await client.corpus.register(
+            name="hdig-platform-architecture",
+            source_path="/repos/hdig-platform/docs",
+            namespace="org:hc:hdig:architecture",
+            watch=True,
+        )
+        # Wait for initial sync, then check code:
+        result = await client.corpus.check(
+            corpus_id=corpus.id,
+            code=diff_text,
+            context="patient-access consent validation filter",
+        )
+        for hit in result.shall_violations:
+            print(f"SHALL violation: {hit.content}")
+            print(f"  Source: {hit.source_file} | {hit.section}")
+
+Sync usage::
+
+    with MemnosClient(url="...", api_key="...") as client:
+        corpora = client.corpus.list()
+        result  = client.corpus.check(corpus_id=corpora[0].id, code=code)
+        print(result.format())
+
+CI / GitLab webhook integration::
+
+    # Register once with watch=True and a webhook_secret:
+    corpus = await client.corpus.register(..., watch=True, webhook_secret="secret")
+    # Then configure GitLab to POST corpus.sync_url to trigger re-sync on push.
+    print(corpus.sync_url(base_url="https://memnos.internal"))
+
+Custom connectors::
+
+    # To use a non-default connector type, pass connector_type:
+    corpus = await client.corpus.register(
+        name="payments-openapi",
+        source_path="/specs/payments-v3.yaml",
+        namespace="org:acme:payments:architecture",
+        connector_type="openapi",        # must be registered in server REGISTRY
+    )
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from memnos_sdk.models import CheckResult, ConstraintHit, CorpusInfo, CorpusStatus
+
+
+def _parse_corpus(data: dict) -> CorpusInfo:
+    return CorpusInfo(
+        id=data["id"],
+        name=data["name"],
+        source_path=data["source_path"],
+        path_pattern=data.get("path_pattern", "**/*.md"),
+        namespace=data["namespace"],
+        connector_type=data.get("connector_type", "git-doc"),
+        watch=data.get("watch", False),
+        status=CorpusStatus(data.get("status", "pending")),
+        node_count=data.get("node_count", 0),
+        last_sync_sha=data.get("last_sync_sha", ""),
+        last_sync_at=data.get("last_sync_at"),
+        error_msg=data.get("error_msg", ""),
+        created_at=data["created_at"],
+        created_by=data.get("created_by", ""),
+    )
+
+
+def _parse_check(data: dict) -> CheckResult:
+    hits = [
+        ConstraintHit(
+            memory_id=c["memory_id"],
+            content=c["content"],
+            severity=c.get("severity", ""),
+            source_file=c.get("source_file", ""),
+            section=c.get("section", ""),
+            score=float(c.get("score", 0)),
+        )
+        for c in data.get("constraints", [])
+    ]
+    return CheckResult(
+        corpus_id=data["corpus_id"],
+        namespace=data["namespace"],
+        constraints=hits,
+    )
+
+
+class AsyncCorpusClient:
+    """Async corpus operations. Accessed via ``AsyncMemnosClient.corpus``."""
+
+    def __init__(self, transport) -> None:
+        self._t = transport
+
+    async def register(
+        self,
+        name: str,
+        source_path: str,
+        namespace: str,
+        *,
+        path_pattern: str = "**/*.md",
+        connector_type: str = "git-doc",
+        watch: bool = False,
+        webhook_secret: str = "",
+    ) -> CorpusInfo:
+        """Register a corpus source and trigger initial ingestion.
+
+        The ingestion runs in the background on the server; poll ``get()``
+        until ``status == CorpusStatus.READY`` before calling ``check()``.
+        """
+        data = await self._t.post(
+            "/api/v1/corpus/",
+            json={
+                "name": name,
+                "source_path": source_path,
+                "namespace": namespace,
+                "path_pattern": path_pattern,
+                "connector_type": connector_type,
+                "watch": watch,
+                "webhook_secret": webhook_secret,
+            },
+        )
+        return _parse_corpus(data)
+
+    async def list(self) -> list[CorpusInfo]:
+        """Return all registered corpus sources."""
+        data = await self._t.get("/api/v1/corpus/")
+        return [_parse_corpus(item) for item in data]
+
+    async def get(self, corpus_id: str) -> CorpusInfo:
+        """Fetch a single corpus by ID."""
+        data = await self._t.get(f"/api/v1/corpus/{corpus_id}")
+        return _parse_corpus(data)
+
+    async def sync(self, corpus_id: str) -> CorpusInfo:
+        """Trigger a re-sync of corpus nodes from source.
+
+        Non-blocking: the sync runs in the background.  Poll ``get()``
+        until ``status == CorpusStatus.READY``.
+        """
+        data = await self._t.post(f"/api/v1/corpus/{corpus_id}/sync", json={})
+        return _parse_corpus(data)
+
+    async def delete(self, corpus_id: str) -> None:
+        """Unregister a corpus. Does not delete the ingested memory nodes."""
+        await self._t.delete(f"/api/v1/corpus/{corpus_id}")
+
+    async def check(
+        self,
+        corpus_id: str,
+        code: str,
+        context: str = "",
+        *,
+        top_k: int = 10,
+    ) -> CheckResult:
+        """Return architecture constraints relevant to a code snippet.
+
+        Parameters
+        ----------
+        corpus_id : ID of the registered corpus
+        code      : code snippet being reviewed or implemented
+        context   : free-text description of what the code does and which
+                    module/component it belongs to, e.g.
+                    "patient-access consent validation filter"
+        top_k     : max constraints to return
+
+        Returns
+        -------
+        CheckResult with ``.constraints``, ``.shall_violations``,
+        ``.should_violations``, and ``.format()`` helper.
+
+        Example
+        -------
+        ::
+
+            result = await client.corpus.check(
+                corpus_id=corpus.id,
+                code=diff_text,
+                context="patient-access consent filter",
+            )
+            if result.shall_violations:
+                raise ArchitectureViolationError(result.format())
+        """
+        data = await self._t.post(
+            f"/api/v1/corpus/{corpus_id}/check",
+            json={"code": code, "context": context, "top_k": top_k},
+        )
+        return _parse_check(data)
+
+    async def check_all(
+        self,
+        code: str,
+        context: str = "",
+        *,
+        top_k: int = 10,
+    ) -> list[CheckResult]:
+        """Check code against ALL registered corpora and return combined results.
+
+        Useful when a code change may touch multiple modules and you want
+        constraints from all relevant corpora without knowing the corpus IDs.
+        Only READY corpora are checked; SYNCING/ERROR corpora are skipped.
+        """
+        corpora = await self.list()
+        results = []
+        for corpus in corpora:
+            if corpus.status != CorpusStatus.READY:
+                continue
+            result = await self.check(corpus.id, code, context, top_k=top_k)
+            if result.constraints:
+                results.append(result)
+        return results
+
+
+class SyncCorpusClient:
+    """Synchronous corpus operations. Accessed via ``MemnosClient.corpus``."""
+
+    def __init__(self, async_client: AsyncCorpusClient, run_fn) -> None:
+        self._async = async_client
+        self._run = run_fn
+
+    def register(
+        self,
+        name: str,
+        source_path: str,
+        namespace: str,
+        *,
+        path_pattern: str = "**/*.md",
+        connector_type: str = "git-doc",
+        watch: bool = False,
+        webhook_secret: str = "",
+    ) -> CorpusInfo:
+        return self._run(
+            self._async.register(
+                name, source_path, namespace,
+                path_pattern=path_pattern,
+                connector_type=connector_type,
+                watch=watch,
+                webhook_secret=webhook_secret,
+            )
+        )
+
+    def list(self) -> list[CorpusInfo]:
+        return self._run(self._async.list())
+
+    def get(self, corpus_id: str) -> CorpusInfo:
+        return self._run(self._async.get(corpus_id))
+
+    def sync(self, corpus_id: str) -> CorpusInfo:
+        return self._run(self._async.sync(corpus_id))
+
+    def delete(self, corpus_id: str) -> None:
+        self._run(self._async.delete(corpus_id))
+
+    def check(
+        self,
+        corpus_id: str,
+        code: str,
+        context: str = "",
+        *,
+        top_k: int = 10,
+    ) -> CheckResult:
+        return self._run(self._async.check(corpus_id, code, context, top_k=top_k))
+
+    def check_all(
+        self,
+        code: str,
+        context: str = "",
+        *,
+        top_k: int = 10,
+    ) -> list[CheckResult]:
+        return self._run(self._async.check_all(code, context, top_k=top_k))

memnos_sdk/exceptions.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+
+class MemnosError(Exception):
+    """Base exception for all memnos SDK errors."""
+
+
+class AuthenticationError(MemnosError):
+    """Raised on HTTP 401 or 403 responses."""
+
+
+class NotFoundError(MemnosError):
+    """Raised on HTTP 404 responses."""
+
+
+class ValidationError(MemnosError):
+    """Raised on HTTP 422 responses."""
+
+
+class ServerError(MemnosError):
+    """Raised on HTTP 5xx responses."""
+
+
+class ConnectionError(MemnosError):
+    """Raised when a network-level failure prevents the request from completing."""

memnos_sdk/integrations/langchain.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    from langchain_core.memory import BaseMemory
+    from langchain_core.messages import BaseMessage  # noqa: F401
+    _LANGCHAIN_AVAILABLE = True
+except ImportError:
+    _LANGCHAIN_AVAILABLE = False
+    BaseMemory = object  # type: ignore[assignment,misc]
+
+from memnos_sdk.models import MemoryType
+
+
+class MemnosMemory(BaseMemory):
+    """LangChain memory backend backed by memnos.
+
+    Usage:
+        client = MemnosClient(url="...", api_key="...")
+        memory = MemnosMemory(client=client, namespace="org:acme", session_id="session-123")
+        agent = ConversationChain(llm=..., memory=memory)
+    """
+
+    client: Any
+    namespace: str
+    session_id: str
+    memory_key: str = "history"
+    input_key: str = "input"
+    output_key: str = "output"
+
+    def __init__(self, **data: Any) -> None:
+        if not _LANGCHAIN_AVAILABLE:
+            raise ImportError(
+                "langchain-core is required for MemnosMemory. "
+                "Install it with: pip install 'memnos-sdk[langchain]'"
+            )
+        super().__init__(**data)
+
+    @property
+    def memory_variables(self) -> list[str]:
+        return [self.memory_key]
+
+    def load_memory_variables(self, inputs: dict) -> dict:
+        memories = self.client.search(
+            f"session {self.session_id}",
+            self.namespace,
+            top_k=20,
+        )
+        history_lines: list[str] = []
+        for m in sorted(memories, key=lambda x: x.created_at):
+            if self.session_id in m.tags:
+                history_lines.append(m.content)
+        return {self.memory_key: "\n".join(history_lines)}
+
+    def save_context(self, inputs: dict, outputs: dict) -> None:
+        user_input = inputs.get(self.input_key, "")
+        ai_output = outputs.get(self.output_key, "")
+        combined = f"Human: {user_input}\nAI: {ai_output}"
+        self.client.write(
+            combined,
+            self.namespace,
+            memory_type=MemoryType.SESSION,
+            tags=[self.session_id, "conversation"],
+            rationale=f"LangChain session {self.session_id}",
+            source="langchain",
+        )
+
+    def clear(self) -> None:
+        # memnos uses supersede for lifecycle management, not deletion
+        pass

memnos_sdk/integrations/llamaindex.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    from llama_index.core.readers.base import BaseReader
+    from llama_index.core.schema import Document
+    _LLAMAINDEX_AVAILABLE = True
+except ImportError:
+    _LLAMAINDEX_AVAILABLE = False
+    BaseReader = object  # type: ignore[assignment,misc]
+    Document = None  # type: ignore[assignment]
+
+
+class MemnosReader(BaseReader):
+    """LlamaIndex reader that loads memnos memories as Documents.
+
+    Usage:
+        client = MemnosClient(url="...", api_key="...")
+        reader = MemnosReader(client=client, namespace="org:acme:engineering")
+        documents = reader.load_data(query="database decisions", top_k=10)
+        index = VectorStoreIndex.from_documents(documents)
+    """
+
+    def __init__(self, client: Any, namespace: str) -> None:
+        if not _LLAMAINDEX_AVAILABLE:
+            raise ImportError(
+                "llama-index-core is required for MemnosReader. "
+                "Install it with: pip install 'memnos-sdk[llamaindex]'"
+            )
+        self.client = client
+        self.namespace = namespace
+
+    def load_data(self, query: str, top_k: int = 10) -> list:
+        memories = self.client.search(query, self.namespace, top_k=top_k)
+        documents = []
+        for m in memories:
+            doc = Document(
+                text=m.content,
+                metadata={
+                    "id": m.id,
+                    "namespace": m.namespace,
+                    "memory_type": m.memory_type.value,
+                    "tags": m.tags,
+                    "affects": m.affects,
+                    "created_at": m.created_at.isoformat(),
+                    "score": m.score,
+                },
+            )
+            documents.append(doc)
+        return documents

memnos_sdk/models.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class MemoryType(str, Enum):
+    FACT = "fact"
+    DECISION = "decision"
+    CONSTRAINT = "constraint"
+    ADR = "adr"
+    SESSION = "session"
+    EPISODE = "episode"
+
+
+# ---------------------------------------------------------------------------
+# Corpus models
+# ---------------------------------------------------------------------------
+
+class CorpusStatus(str, Enum):
+    PENDING  = "pending"
+    SYNCING  = "syncing"
+    READY    = "ready"
+    ERROR    = "error"
+
+
+class CorpusInfo(BaseModel):
+    """Metadata for a registered corpus source."""
+    id: str
+    name: str
+    source_path: str
+    path_pattern: str
+    namespace: str
+    connector_type: str = "git-doc"
+    watch: bool
+    status: CorpusStatus
+    node_count: int
+    last_sync_sha: str
+    last_sync_at: datetime | None = None
+    error_msg: str = ""
+    created_at: datetime
+    created_by: str = ""
+
+
+class ConstraintHit(BaseModel):
+    """A single constraint node returned by a corpus check."""
+    memory_id: str
+    content: str
+    severity: str       # "SHALL" | "SHOULD" | "MAY" | ""
+    source_file: str
+    section: str
+    score: float
+
+
+class CheckResult(BaseModel):
+    """Result of a corpus constraint check against a code snippet."""
+    corpus_id: str
+    namespace: str
+    constraints: list[ConstraintHit]
+
+    @property
+    def shall_violations(self) -> list[ConstraintHit]:
+        """Constraints with SHALL severity — highest priority."""
+        return [c for c in self.constraints if c.severity == "SHALL"]
+
+    @property
+    def should_violations(self) -> list[ConstraintHit]:
+        """Constraints with SHOULD severity."""
+        return [c for c in self.constraints if c.severity == "SHOULD"]
+
+    def format(self) -> str:
+        """Human-readable summary for agent prompts."""
+        if not self.constraints:
+            return f"No constraints found for corpus {self.corpus_id}."
+        lines = [f"Corpus: {self.corpus_id} | Namespace: {self.namespace}"]
+        lines.append(f"Found {len(self.constraints)} relevant constraint(s):\n")
+        for i, c in enumerate(self.constraints, 1):
+            sev = f"[{c.severity}] " if c.severity else ""
+            lines.append(f"{i}. {sev}{c.content}")
+            if c.source_file or c.section:
+                src = c.source_file
+                lines.append(f"   Source: {src}" + (f" | Section: {c.section}" if c.section else ""))
+            lines.append(f"   Score: {c.score:.3f}")
+            lines.append("")
+        return "\n".join(lines)
+
+
+class Memory(BaseModel):
+    id: str
+    content: str
+    namespace: str
+    memory_type: MemoryType
+    tags: list[str]
+    affects: list[str]
+    rationale: str
+    author: str
+    created_at: datetime
+    score: float | None = None
+    provenance: dict = Field(default_factory=dict)
+    contradiction_warnings: list[dict] = Field(default_factory=list)
+
+
+class SearchResult(BaseModel):
+    memories: list[Memory]
+    # constraints are returned as Memory objects with memory_type=constraint and score=2.0
+    # They are already in the memories list; this model is transparent about that
+
+
+class HealthStatus(BaseModel):
+    status: str
+    arcadedb: str
+    version: str
+    schema_version: str = "1.0"

memnos_sdk-1.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+memnos_sdk/__init__.py,sha256=jNolTbqK0tgV8IpWRXAgfHJccuh8955ZwX4yhmOKWug,1092
+memnos_sdk/_http.py,sha256=R-GuYqC8lKxQZLjjyyjnCFQEp-Jp8TTpW9jAqOJL3E0,3099
+memnos_sdk/client.py,sha256=OK36OUc-W-j-ra9BHIafmJA6bNlBmliB5spwHQEzy30,14074
+memnos_sdk/corpus.py,sha256=Lf8M2bYTV1nFJ0Q31yby6CmeDwjPJ6GLHLPEkJmKoqI,9137
+memnos_sdk/exceptions.py,sha256=6tiv59i-pYp2ZhBp9GqkvK5p-rhjUnNmvKH_LdBgSrI,558
+memnos_sdk/models.py,sha256=ade1v8LaDJ6Agqy0tDq6fSZKf-6Nq_ZFB6vTmmRll7Q,3358
+memnos_sdk/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+memnos_sdk/integrations/langchain.py,sha256=hIp0RbXQlEe3wlsaJInMXU-DOKKQUvw4fIFQqqZcX08,2284
+memnos_sdk/integrations/llamaindex.py,sha256=Na17HuslvJa6PGz_Q735pFVdvxfSVDqqZF30Z4ivKdU,1775
+memnos_sdk-1.1.0.dist-info/METADATA,sha256=ytqKmfbGjInV4rGDym4oC4TPEJtigIMq739skgQDs_c,440
+memnos_sdk-1.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+memnos_sdk-1.1.0.dist-info/top_level.txt,sha256=2pE0i6SWCUuJQl4NPrGhauh36f5I-XSPEkW6MdKoVzg,11
+memnos_sdk-1.1.0.dist-info/RECORD,,

memnos_sdk-1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

memnos_sdk-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+memnos_sdk