memnos-sdk 0.1.0__tar.gz

memnos_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: memnos-sdk
+Version: 0.1.0
+Summary: Lightweight client + LangChain/LangGraph adapters for memnos — backend memory for AI agents.
+Author: memnos
+License: Apache-2.0
+Project-URL: Homepage, https://memnos.net
+Project-URL: Source, https://github.com/thameema/memnos
+Keywords: memnos,memory,AI agents,LangChain,LangGraph,RAG,MCP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == "langchain"
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2; extra == "langgraph"
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.10; extra == "llamaindex"
+Provides-Extra: all
+Requires-Dist: langchain-core>=0.3; extra == "all"
+Requires-Dist: langgraph>=0.2; extra == "all"
+Requires-Dist: llama-index-core>=0.10; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: langchain-core>=0.3; extra == "dev"
+Requires-Dist: langgraph>=0.2; extra == "dev"
+Requires-Dist: llama-index-core>=0.10; extra == "dev"
+
+# memnos-sdk
+
+Lightweight Python client for [memnos](https://memnos.net) — governed, vendor-neutral
+**backend memory for AI agents**. Use it directly, or as a **LangChain** retriever, a
+**LangGraph** long-term-memory store, or a **LlamaIndex** retriever.
+
+`httpx`-only (no server deps). Talks to a running memnos server over REST.
+
+```bash
+pip install memnos-sdk                  # core client
+pip install 'memnos-sdk[langchain]'     # + LangChain retriever
+pip install 'memnos-sdk[langgraph]'     # + LangGraph BaseStore
+pip install 'memnos-sdk[llamaindex]'    # + LlamaIndex retriever
+pip install 'memnos-sdk[all]'           # everything
+```
+
+## Core client (sync + async)
+
+```python
+from memnos_sdk import MemnosClient
+
+with MemnosClient(base_url="http://127.0.0.1:8900", token="mnk_...", namespace="org:acme") as mem:
+    mem.remember("We chose PostgreSQL + pgvector for the memory store")
+    ctx = mem.context("what database did we choose?")   # ready-to-inject; no LLM at query time
+    rows = mem.recall("database decision")["memories"]   # ranked memories w/ scores + dates
+```
+
+```python
+from memnos_sdk import AsyncMemnosClient
+
+async with AsyncMemnosClient(token="mnk_...", namespace="org:acme") as mem:
+    await mem.remember("...")
+    print(await mem.context("..."))
+```
+
+A **token** + **namespace** come from your memnos admin (`memnos token <principal>`,
+`memnos grant <principal> <namespace>`). Every call is namespace-scoped and audited
+server-side.
+
+## LangChain
+
+```python
+from memnos_sdk import MemnosClient
+from memnos_sdk.integrations.langchain import MemnosRetriever
+
+retriever = MemnosRetriever(client=MemnosClient(token="mnk_...", namespace="org:acme"))
+docs = retriever.invoke("auth token expiry policy")     # drop into any RAG chain
+retriever.save("JWT tokens expire after 15 minutes in prod")
+```
+
+## LangGraph (long-term memory)
+
+```python
+from memnos_sdk import MemnosClient
+from memnos_sdk.integrations.langgraph import MemnosStore
+
+store = MemnosStore(MemnosClient(token="mnk_..."))
+graph = builder.compile(store=store)
+# in a node:  store.search(("org","acme"), query="...")  ·  store.put(("org","acme"), key, {"text": "..."})
+```
+
+memnos is *semantic* memory: `put`→remember, `search`→hybrid+reranked recall. Exact-key
+`get` is best-effort (use `search`).
+
+## LlamaIndex
+
+```python
+from memnos_sdk import MemnosClient
+from memnos_sdk.integrations.llamaindex import MemnosRetriever
+
+retriever = MemnosRetriever(client=MemnosClient(token="mnk_...", namespace="org:acme"))
+nodes = retriever.retrieve("auth token expiry policy")   # NodeWithScore[]; drop into a query engine
+retriever.save("JWT tokens expire after 15 minutes in prod")
+```
+
+## API surface
+`remember(text)` · `recall(query) -> {memories, context}` · `context(query) -> str` ·
+`consolidate()` · `feedback(query, helpful)` · `healthy()`. Async mirror on
+`AsyncMemnosClient`.
+
+Apache-2.0.

memnos_sdk-0.1.0/README.md

@@ -0,0 +1,81 @@
+# memnos-sdk
+
+Lightweight Python client for [memnos](https://memnos.net) — governed, vendor-neutral
+**backend memory for AI agents**. Use it directly, or as a **LangChain** retriever, a
+**LangGraph** long-term-memory store, or a **LlamaIndex** retriever.
+
+`httpx`-only (no server deps). Talks to a running memnos server over REST.
+
+```bash
+pip install memnos-sdk                  # core client
+pip install 'memnos-sdk[langchain]'     # + LangChain retriever
+pip install 'memnos-sdk[langgraph]'     # + LangGraph BaseStore
+pip install 'memnos-sdk[llamaindex]'    # + LlamaIndex retriever
+pip install 'memnos-sdk[all]'           # everything
+```
+
+## Core client (sync + async)
+
+```python
+from memnos_sdk import MemnosClient
+
+with MemnosClient(base_url="http://127.0.0.1:8900", token="mnk_...", namespace="org:acme") as mem:
+    mem.remember("We chose PostgreSQL + pgvector for the memory store")
+    ctx = mem.context("what database did we choose?")   # ready-to-inject; no LLM at query time
+    rows = mem.recall("database decision")["memories"]   # ranked memories w/ scores + dates
+```
+
+```python
+from memnos_sdk import AsyncMemnosClient
+
+async with AsyncMemnosClient(token="mnk_...", namespace="org:acme") as mem:
+    await mem.remember("...")
+    print(await mem.context("..."))
+```
+
+A **token** + **namespace** come from your memnos admin (`memnos token <principal>`,
+`memnos grant <principal> <namespace>`). Every call is namespace-scoped and audited
+server-side.
+
+## LangChain
+
+```python
+from memnos_sdk import MemnosClient
+from memnos_sdk.integrations.langchain import MemnosRetriever
+
+retriever = MemnosRetriever(client=MemnosClient(token="mnk_...", namespace="org:acme"))
+docs = retriever.invoke("auth token expiry policy")     # drop into any RAG chain
+retriever.save("JWT tokens expire after 15 minutes in prod")
+```
+
+## LangGraph (long-term memory)
+
+```python
+from memnos_sdk import MemnosClient
+from memnos_sdk.integrations.langgraph import MemnosStore
+
+store = MemnosStore(MemnosClient(token="mnk_..."))
+graph = builder.compile(store=store)
+# in a node:  store.search(("org","acme"), query="...")  ·  store.put(("org","acme"), key, {"text": "..."})
+```
+
+memnos is *semantic* memory: `put`→remember, `search`→hybrid+reranked recall. Exact-key
+`get` is best-effort (use `search`).
+
+## LlamaIndex
+
+```python
+from memnos_sdk import MemnosClient
+from memnos_sdk.integrations.llamaindex import MemnosRetriever
+
+retriever = MemnosRetriever(client=MemnosClient(token="mnk_...", namespace="org:acme"))
+nodes = retriever.retrieve("auth token expiry policy")   # NodeWithScore[]; drop into a query engine
+retriever.save("JWT tokens expire after 15 minutes in prod")
+```
+
+## API surface
+`remember(text)` · `recall(query) -> {memories, context}` · `context(query) -> str` ·
+`consolidate()` · `feedback(query, helpful)` · `healthy()`. Async mirror on
+`AsyncMemnosClient`.
+
+Apache-2.0.

memnos_sdk-0.1.0/memnos_sdk/__init__.py

@@ -0,0 +1,12 @@
+"""memnos SDK — backend memory for agentic apps (LangChain / LangGraph / any).
+
+    from memnos_sdk import MemnosClient, AsyncMemnosClient
+
+Framework adapters are optional extras (import only if the framework is installed):
+    from memnos_sdk.integrations.langchain import MemnosRetriever   # pip install 'memnos-sdk[langchain]'
+    from memnos_sdk.integrations.langgraph import MemnosStore        # pip install 'memnos-sdk[langgraph]'
+"""
+from .client import AsyncMemnosClient, MemnosClient, MemnosError
+
+__version__ = "0.1.0"
+__all__ = ["MemnosClient", "AsyncMemnosClient", "MemnosError", "__version__"]

memnos_sdk-0.1.0/memnos_sdk/client.py

@@ -0,0 +1,137 @@
+"""memnos SDK — typed REST client (sync + async) for app developers.
+
+Lightweight (httpx only) so agentic apps can `pip install memnos-sdk` without the server's
+heavy deps. Talks to a running memnos server. Auth = a bearer token; every call is scoped
+to a namespace (set once on the client or per call).
+
+    from memnos_sdk import MemnosClient
+    mem = MemnosClient(base_url="http://127.0.0.1:8900", token="mnk_...", namespace="org:acme")
+    mem.remember("We chose Postgres for the memory store")
+    print(mem.context("what db did we choose?"))   # ready-to-inject context, no LLM at query time
+"""
+from __future__ import annotations
+
+import httpx
+
+DEFAULT_URL = "http://127.0.0.1:8900"
+
+
+class MemnosError(RuntimeError):
+    def __init__(self, status, detail):
+        super().__init__(f"memnos {status}: {detail}")
+        self.status, self.detail = status, detail
+
+
+def _ns(namespace, default):
+    ns = namespace or default
+    if not ns:
+        raise ValueError("namespace required (set MemnosClient(namespace=...) or pass namespace=)")
+    return ns
+
+
+def _raise(r):
+    if r.status_code >= 400:
+        try:
+            detail = r.json().get("error", r.text)
+        except Exception:
+            detail = r.text
+        raise MemnosError(r.status_code, detail)
+    return r.json()
+
+
+class MemnosClient:
+    """Synchronous client. Use as a context manager or call .close()."""
+
+    def __init__(self, base_url=DEFAULT_URL, token=None, namespace=None, timeout=30.0, transport=None):
+        self.namespace = namespace
+        self._h = {"Authorization": f"Bearer {token}"} if token else {}
+        self._c = httpx.Client(base_url=base_url.rstrip("/"), timeout=timeout, headers=self._h,
+                               transport=transport)
+
+    def remember(self, text, *, namespace=None, speaker=None, session_id=None) -> dict:
+        return _raise(self._c.post("/remember", json={
+            "namespace": _ns(namespace, self.namespace), "text": text,
+            "speaker": speaker, "session_id": session_id}))
+
+    def recall(self, query, *, namespace=None, raw_quota=None, fact_quota=None, max_chars=None) -> dict:
+        body = {"namespace": _ns(namespace, self.namespace), "query": query}
+        for k, v in (("raw_quota", raw_quota), ("fact_quota", fact_quota), ("max_chars", max_chars)):
+            if v is not None:
+                body[k] = v
+        return _raise(self._c.post("/recall", json=body))
+
+    def ingest_file(self, filename, text, *, namespace=None, extract=False) -> dict:
+        """Chunk a document's text into memory under `filename`. Pass extracted text
+        (md/txt/code, or text pulled from a PDF/DOCX)."""
+        return _raise(self._c.post("/ingest/file", json={
+            "namespace": _ns(namespace, self.namespace), "filename": filename,
+            "text": text, "extract": extract}))
+
+    def context(self, query, *, namespace=None, **kw) -> str:
+        """Just the ready-to-inject context string from recall()."""
+        return self.recall(query, namespace=namespace, **kw).get("context", "")
+
+    def consolidate(self, *, namespace=None) -> dict:
+        return _raise(self._c.post("/consolidate", json={"namespace": _ns(namespace, self.namespace)}))
+
+    def feedback(self, query, helpful, *, namespace=None, note=None) -> dict:
+        return _raise(self._c.post("/feedback", json={
+            "namespace": _ns(namespace, self.namespace), "query": query,
+            "helpful": bool(helpful), "note": note}))
+
+    def healthy(self) -> bool:
+        try:
+            return self._c.get("/healthz").status_code == 200
+        except httpx.HTTPError:
+            return False
+
+    def close(self):
+        self._c.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        self.close()
+
+
+class AsyncMemnosClient:
+    """Async client (httpx.AsyncClient). Use `async with` or call .aclose()."""
+
+    def __init__(self, base_url=DEFAULT_URL, token=None, namespace=None, timeout=30.0, transport=None):
+        self.namespace = namespace
+        self._h = {"Authorization": f"Bearer {token}"} if token else {}
+        self._c = httpx.AsyncClient(base_url=base_url.rstrip("/"), timeout=timeout, headers=self._h,
+                                    transport=transport)
+
+    async def remember(self, text, *, namespace=None, speaker=None, session_id=None) -> dict:
+        return _raise(await self._c.post("/remember", json={
+            "namespace": _ns(namespace, self.namespace), "text": text,
+            "speaker": speaker, "session_id": session_id}))
+
+    async def recall(self, query, *, namespace=None, raw_quota=None, fact_quota=None, max_chars=None) -> dict:
+        body = {"namespace": _ns(namespace, self.namespace), "query": query}
+        for k, v in (("raw_quota", raw_quota), ("fact_quota", fact_quota), ("max_chars", max_chars)):
+            if v is not None:
+                body[k] = v
+        return _raise(await self._c.post("/recall", json=body))
+
+    async def context(self, query, *, namespace=None, **kw) -> str:
+        return (await self.recall(query, namespace=namespace, **kw)).get("context", "")
+
+    async def consolidate(self, *, namespace=None) -> dict:
+        return _raise(await self._c.post("/consolidate", json={"namespace": _ns(namespace, self.namespace)}))
+
+    async def feedback(self, query, helpful, *, namespace=None, note=None) -> dict:
+        return _raise(await self._c.post("/feedback", json={
+            "namespace": _ns(namespace, self.namespace), "query": query,
+            "helpful": bool(helpful), "note": note}))
+
+    async def aclose(self):
+        await self._c.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *a):
+        await self.aclose()

memnos_sdk-0.1.0/memnos_sdk/integrations/__init__.py

@@ -0,0 +1 @@
+# memnos SDK framework adapters (optional). Import the submodule you need.

memnos_sdk-0.1.0/memnos_sdk/integrations/langchain.py

@@ -0,0 +1,51 @@
+"""LangChain adapter — memnos as a retriever (and a tiny save helper).
+
+    pip install 'memnos-sdk[langchain]'
+    from memnos_sdk import MemnosClient
+    from memnos_sdk.integrations.langchain import MemnosRetriever
+
+    mem = MemnosClient(token="mnk_...", namespace="org:acme")
+    retriever = MemnosRetriever(client=mem)          # drop into any chain / RAG pipeline
+    docs = retriever.invoke("what database did we choose?")
+
+Built on `langchain_core` (stable) — no heavy langchain deps. Retrieval uses memnos's
+hybrid + reranked recall (no LLM at query time); each memory becomes a Document.
+"""
+from __future__ import annotations
+
+from typing import List
+
+try:
+    from langchain_core.callbacks import CallbackManagerForRetrieverRun
+    from langchain_core.documents import Document
+    from langchain_core.retrievers import BaseRetriever
+except ImportError as e:  # pragma: no cover
+    raise ImportError("LangChain integration needs langchain_core: pip install 'memnos-sdk[langchain]'") from e
+
+from ..client import MemnosClient
+
+
+class MemnosRetriever(BaseRetriever):
+    """A LangChain retriever backed by memnos recall."""
+
+    client: MemnosClient
+    namespace: str | None = None
+    k: int = 8
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    def _get_relevant_documents(self, query: str, *, run_manager: "CallbackManagerForRetrieverRun" = None
+                                ) -> List[Document]:
+        rows = self.client.recall(query, namespace=self.namespace).get("memories", [])
+        docs = []
+        for r in rows[: self.k]:
+            md = {"kind": r.get("kind"), "score": r.get("score")}
+            if r.get("date"):
+                md["date"] = r["date"]
+            docs.append(Document(page_content=r.get("content", ""), metadata=md))
+        return docs
+
+    def save(self, text: str, *, namespace: str | None = None) -> dict:
+        """Convenience: write a memory (LangChain has no standard 'write' on retrievers)."""
+        return self.client.remember(text, namespace=namespace or self.namespace)

memnos_sdk-0.1.0/memnos_sdk/integrations/langgraph.py

@@ -0,0 +1,103 @@
+"""LangGraph adapter — memnos as a long-term-memory `BaseStore`.
+
+    pip install 'memnos-sdk[langgraph]'
+    from memnos_sdk import MemnosClient
+    from memnos_sdk.integrations.langgraph import MemnosStore
+
+    store = MemnosStore(MemnosClient(token="mnk_..."))
+    graph = builder.compile(store=store)     # nodes get long-term memory via store.search/put
+
+Mapping (memnos is SEMANTIC memory, not a KV store):
+  • Put(namespace, key, value)      -> remember(value)     (key kept inline so it's searchable)
+  • Search(namespace, query)        -> recall(query)       (hybrid + reranked, no LLM at query time)
+  • Get(namespace, key)             -> best-effort via search; None if not found
+  • ListNamespaces                  -> [] (memnos doesn't enumerate per-key namespaces here)
+
+LangGraph namespace tuples are joined with ':' into a memnos namespace.
+"""
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+
+try:
+    from langgraph.store.base import (BaseStore, GetOp, Item, ListNamespacesOp, PutOp,
+                                      SearchItem, SearchOp)
+except ImportError as e:  # pragma: no cover
+    raise ImportError("LangGraph integration needs langgraph: pip install 'memnos-sdk[langgraph]'") from e
+
+from ..client import AsyncMemnosClient, MemnosClient
+
+
+def _ns(tup):
+    return ":".join(str(p) for p in tup) if tup else "default"
+
+
+def _text(value):
+    return value if isinstance(value, str) else json.dumps(value, default=str)
+
+
+class MemnosStore(BaseStore):
+    """A LangGraph BaseStore backed by memnos semantic memory."""
+
+    def __init__(self, client: MemnosClient, async_client: AsyncMemnosClient | None = None):
+        self.client = client
+        self.aclient = async_client
+
+    # --- sync ---
+    def batch(self, ops):
+        out = []
+        for op in ops:
+            if isinstance(op, PutOp):
+                if op.value is None:                       # delete — memnos has no key delete; no-op
+                    out.append(None)
+                else:
+                    self.client.remember(f"[{op.key}] {_text(op.value)}", namespace=_ns(op.namespace))
+                    out.append(None)
+            elif isinstance(op, SearchOp):
+                rows = self.client.recall(op.query or "", namespace=_ns(op.namespace_prefix)).get("memories", [])
+                out.append(self._to_items(op.namespace_prefix, rows, getattr(op, "limit", 10)))
+            elif isinstance(op, GetOp):
+                rows = self.client.recall(str(op.key), namespace=_ns(op.namespace)).get("memories", [])
+                out.append(self._to_items(op.namespace, rows, 1)[0] if rows else None)
+            elif isinstance(op, ListNamespacesOp):
+                out.append([])
+            else:
+                out.append(None)
+        return out
+
+    # --- async ---
+    async def abatch(self, ops):
+        if self.aclient is None:
+            return self.batch(ops)
+        out = []
+        for op in ops:
+            if isinstance(op, PutOp):
+                if op.value is not None:
+                    await self.aclient.remember(f"[{op.key}] {_text(op.value)}", namespace=_ns(op.namespace))
+                out.append(None)
+            elif isinstance(op, SearchOp):
+                r = await self.aclient.recall(op.query or "", namespace=_ns(op.namespace_prefix))
+                out.append(self._to_items(op.namespace_prefix, r.get("memories", []), getattr(op, "limit", 10)))
+            elif isinstance(op, GetOp):
+                r = await self.aclient.recall(str(op.key), namespace=_ns(op.namespace))
+                rows = r.get("memories", [])
+                out.append(self._to_items(op.namespace, rows, 1)[0] if rows else None)
+            elif isinstance(op, ListNamespacesOp):
+                out.append([])
+            else:
+                out.append(None)
+        return out
+
+    def _to_items(self, namespace, rows, limit):
+        now = datetime.now(timezone.utc)
+        items = []
+        for i, r in enumerate(rows[: (limit or 10)]):
+            try:
+                items.append(SearchItem(namespace=tuple(namespace), key=str(i),
+                                        value={"content": r.get("content", ""), "kind": r.get("kind")},
+                                        created_at=now, updated_at=now, score=r.get("score")))
+            except TypeError:   # SearchItem signature drift across langgraph versions
+                items.append(Item(namespace=tuple(namespace), key=str(i),
+                                  value={"content": r.get("content", "")}, created_at=now, updated_at=now))
+        return items

memnos_sdk-0.1.0/memnos_sdk/integrations/llamaindex.py

@@ -0,0 +1,52 @@
+"""LlamaIndex adapter — memnos as a retriever (and a tiny save helper).
+
+    pip install 'memnos-sdk[llamaindex]'
+    from memnos_sdk import MemnosClient
+    from memnos_sdk.integrations.llamaindex import MemnosRetriever
+
+    mem = MemnosClient(token="mnk_...", namespace="org:acme")
+    retriever = MemnosRetriever(client=mem)            # drop into any LlamaIndex query engine
+    nodes = retriever.retrieve("what database did we choose?")
+
+Built on `llama_index.core` (stable). Retrieval uses memnos's hybrid + reranked recall
+(no LLM at query time); each memory becomes a TextNode with its score + metadata.
+"""
+from __future__ import annotations
+
+from typing import List, Optional
+
+try:
+    from llama_index.core.retrievers import BaseRetriever
+    from llama_index.core.schema import NodeWithScore, QueryBundle, TextNode
+except ImportError as e:  # pragma: no cover
+    raise ImportError("LlamaIndex integration needs llama-index-core: "
+                      "pip install 'memnos-sdk[llamaindex]'") from e
+
+from ..client import MemnosClient
+
+
+class MemnosRetriever(BaseRetriever):
+    """A LlamaIndex retriever backed by memnos recall."""
+
+    def __init__(self, client: MemnosClient, namespace: Optional[str] = None, k: int = 8,
+                 callback_manager=None):
+        self.client = client
+        self.namespace = namespace
+        self.k = k
+        super().__init__(callback_manager=callback_manager)
+
+    def _retrieve(self, query_bundle: "QueryBundle") -> List["NodeWithScore"]:
+        q = query_bundle.query_str if hasattr(query_bundle, "query_str") else str(query_bundle)
+        rows = self.client.recall(q, namespace=self.namespace).get("memories", [])
+        nodes: List[NodeWithScore] = []
+        for r in rows[: self.k]:
+            md = {"kind": r.get("kind")}
+            if r.get("date"):
+                md["date"] = r["date"]
+            node = TextNode(text=r.get("content", ""), metadata=md)
+            nodes.append(NodeWithScore(node=node, score=r.get("score")))
+        return nodes
+
+    def save(self, text: str, *, namespace: Optional[str] = None) -> dict:
+        """Convenience: write a memory (LlamaIndex retrievers have no standard 'write')."""
+        return self.client.remember(text, namespace=namespace or self.namespace)

memnos_sdk-0.1.0/memnos_sdk.egg-info/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: memnos-sdk
+Version: 0.1.0
+Summary: Lightweight client + LangChain/LangGraph adapters for memnos — backend memory for AI agents.
+Author: memnos
+License: Apache-2.0
+Project-URL: Homepage, https://memnos.net
+Project-URL: Source, https://github.com/thameema/memnos
+Keywords: memnos,memory,AI agents,LangChain,LangGraph,RAG,MCP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == "langchain"
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2; extra == "langgraph"
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.10; extra == "llamaindex"
+Provides-Extra: all
+Requires-Dist: langchain-core>=0.3; extra == "all"
+Requires-Dist: langgraph>=0.2; extra == "all"
+Requires-Dist: llama-index-core>=0.10; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: langchain-core>=0.3; extra == "dev"
+Requires-Dist: langgraph>=0.2; extra == "dev"
+Requires-Dist: llama-index-core>=0.10; extra == "dev"
+
+# memnos-sdk
+
+Lightweight Python client for [memnos](https://memnos.net) — governed, vendor-neutral
+**backend memory for AI agents**. Use it directly, or as a **LangChain** retriever, a
+**LangGraph** long-term-memory store, or a **LlamaIndex** retriever.
+
+`httpx`-only (no server deps). Talks to a running memnos server over REST.
+
+```bash
+pip install memnos-sdk                  # core client
+pip install 'memnos-sdk[langchain]'     # + LangChain retriever
+pip install 'memnos-sdk[langgraph]'     # + LangGraph BaseStore
+pip install 'memnos-sdk[llamaindex]'    # + LlamaIndex retriever
+pip install 'memnos-sdk[all]'           # everything
+```
+
+## Core client (sync + async)
+
+```python
+from memnos_sdk import MemnosClient
+
+with MemnosClient(base_url="http://127.0.0.1:8900", token="mnk_...", namespace="org:acme") as mem:
+    mem.remember("We chose PostgreSQL + pgvector for the memory store")
+    ctx = mem.context("what database did we choose?")   # ready-to-inject; no LLM at query time
+    rows = mem.recall("database decision")["memories"]   # ranked memories w/ scores + dates
+```
+
+```python
+from memnos_sdk import AsyncMemnosClient
+
+async with AsyncMemnosClient(token="mnk_...", namespace="org:acme") as mem:
+    await mem.remember("...")
+    print(await mem.context("..."))
+```
+
+A **token** + **namespace** come from your memnos admin (`memnos token <principal>`,
+`memnos grant <principal> <namespace>`). Every call is namespace-scoped and audited
+server-side.
+
+## LangChain
+
+```python
+from memnos_sdk import MemnosClient
+from memnos_sdk.integrations.langchain import MemnosRetriever
+
+retriever = MemnosRetriever(client=MemnosClient(token="mnk_...", namespace="org:acme"))
+docs = retriever.invoke("auth token expiry policy")     # drop into any RAG chain
+retriever.save("JWT tokens expire after 15 minutes in prod")
+```
+
+## LangGraph (long-term memory)
+
+```python
+from memnos_sdk import MemnosClient
+from memnos_sdk.integrations.langgraph import MemnosStore
+
+store = MemnosStore(MemnosClient(token="mnk_..."))
+graph = builder.compile(store=store)
+# in a node:  store.search(("org","acme"), query="...")  ·  store.put(("org","acme"), key, {"text": "..."})
+```
+
+memnos is *semantic* memory: `put`→remember, `search`→hybrid+reranked recall. Exact-key
+`get` is best-effort (use `search`).
+
+## LlamaIndex
+
+```python
+from memnos_sdk import MemnosClient
+from memnos_sdk.integrations.llamaindex import MemnosRetriever
+
+retriever = MemnosRetriever(client=MemnosClient(token="mnk_...", namespace="org:acme"))
+nodes = retriever.retrieve("auth token expiry policy")   # NodeWithScore[]; drop into a query engine
+retriever.save("JWT tokens expire after 15 minutes in prod")
+```
+
+## API surface
+`remember(text)` · `recall(query) -> {memories, context}` · `context(query) -> str` ·
+`consolidate()` · `feedback(query, helpful)` · `healthy()`. Async mirror on
+`AsyncMemnosClient`.
+
+Apache-2.0.

memnos_sdk-0.1.0/memnos_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+memnos_sdk/__init__.py
+memnos_sdk/client.py
+memnos_sdk.egg-info/PKG-INFO
+memnos_sdk.egg-info/SOURCES.txt
+memnos_sdk.egg-info/dependency_links.txt
+memnos_sdk.egg-info/requires.txt
+memnos_sdk.egg-info/top_level.txt
+memnos_sdk/integrations/__init__.py
+memnos_sdk/integrations/langchain.py
+memnos_sdk/integrations/langgraph.py
+memnos_sdk/integrations/llamaindex.py
+tests/test_client.py
+tests/test_integrations.py

memnos_sdk-0.1.0/memnos_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

memnos_sdk-0.1.0/memnos_sdk.egg-info/requires.txt

@@ -0,0 +1,21 @@
+httpx>=0.27
+
+[all]
+langchain-core>=0.3
+langgraph>=0.2
+llama-index-core>=0.10
+
+[dev]
+pytest>=8
+langchain-core>=0.3
+langgraph>=0.2
+llama-index-core>=0.10
+
+[langchain]
+langchain-core>=0.3
+
+[langgraph]
+langgraph>=0.2
+
+[llamaindex]
+llama-index-core>=0.10

memnos_sdk-0.1.0/memnos_sdk.egg-info/top_level.txt

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

memnos_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "memnos-sdk"
+version = "0.1.0"
+description = "Lightweight client + LangChain/LangGraph adapters for memnos — backend memory for AI agents."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "memnos" }]
+keywords = ["memnos", "memory", "AI agents", "LangChain", "LangGraph", "RAG", "MCP"]
+dependencies = ["httpx>=0.27"]
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.3"]
+langgraph = ["langgraph>=0.2"]
+llamaindex = ["llama-index-core>=0.10"]
+all = ["langchain-core>=0.3", "langgraph>=0.2", "llama-index-core>=0.10"]
+dev = ["pytest>=8", "langchain-core>=0.3", "langgraph>=0.2", "llama-index-core>=0.10"]
+
+[project.urls]
+Homepage = "https://memnos.net"
+Source = "https://github.com/thameema/memnos"
+
+[tool.setuptools]
+packages = ["memnos_sdk", "memnos_sdk.integrations"]

memnos_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

memnos_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,102 @@
+"""memnos-sdk tests.
+
+Unit tests use an httpx MockTransport (no server needed) — deterministic. A live smoke
+test runs only if MEMNOS_TOKEN + MEMNOS_NS env are set and a server is reachable.
+Run: python -m pytest sdk/tests -q     (or: python sdk/tests/test_client.py)
+"""
+import os
+import sys
+
+import httpx
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from memnos_sdk import AsyncMemnosClient, MemnosClient, MemnosError
+
+PASS = FAIL = 0
+
+
+def check(name, cond):
+    global PASS, FAIL
+    print(f"  {'PASS' if cond else 'FAIL'}  {name}")
+    PASS += cond; FAIL += (not cond)
+
+
+def _handler(request):
+    import json
+    body = json.loads(request.content or b"{}")
+    if request.url.path == "/remember":
+        assert body["namespace"] and body["text"]
+        return httpx.Response(200, json={"turn_id": 1, "facts": 2, "superseded": 0})
+    if request.url.path == "/recall":
+        return httpx.Response(200, json={"memories": [{"content": "we chose postgres", "kind": "fact",
+                                                       "score": 0.9, "date": "2026-06-07"}],
+                                         "context": "- (fact) we chose postgres"})
+    if request.url.path == "/consolidate":
+        return httpx.Response(200, json={"dossiers": 3})
+    if request.url.path == "/feedback":
+        return httpx.Response(200, json={"ok": True})
+    if request.url.path == "/healthz":
+        return httpx.Response(200, json={"ok": True})
+    return httpx.Response(404, json={"error": "not found"})
+
+
+def main():
+    print("=== memnos-sdk (mock transport) ===")
+    mem = MemnosClient(token="mnk_test", namespace="org:acme", transport=httpx.MockTransport(_handler))
+    check("remember returns ids", mem.remember("we chose postgres")["facts"] == 2)
+    check("recall returns memories", mem.recall("db?")["memories"][0]["content"] == "we chose postgres")
+    check("context returns string", mem.context("db?").startswith("- (fact)"))
+    check("consolidate", mem.consolidate()["dossiers"] == 3)
+    check("feedback", mem.feedback("db?", True)["ok"] is True)
+    check("healthy()", mem.healthy() is True)
+    # namespace required if neither client-default nor per-call
+    try:
+        MemnosClient(token="x", transport=httpx.MockTransport(_handler)).remember("y")
+        check("missing namespace raises", False)
+    except ValueError:
+        check("missing namespace raises", True)
+    # error mapping
+    def err_handler(req):
+        return httpx.Response(403, json={"error": "forbidden for namespace"})
+    em = MemnosClient(token="x", namespace="n", transport=httpx.MockTransport(err_handler))
+    try:
+        em.recall("q"); check("4xx -> MemnosError", False)
+    except MemnosError as e:
+        check("4xx -> MemnosError", e.status == 403)
+    mem.close(); em.close()
+
+    # async
+    import asyncio
+    async def _a():
+        async with AsyncMemnosClient(token="x", namespace="n", transport=httpx.MockTransport(_handler)) as am:
+            r = await am.recall("db?")
+            return r["memories"][0]["content"]
+    check("async recall", asyncio.run(_a()) == "we chose postgres")
+
+    # adapters import (skip if frameworks absent)
+    try:
+        from memnos_sdk.integrations.langchain import MemnosRetriever  # noqa
+        check("langchain adapter imports", True)
+    except ImportError:
+        print("  SKIP langchain adapter (langchain_core not installed)")
+    try:
+        from memnos_sdk.integrations.langgraph import MemnosStore  # noqa
+        check("langgraph adapter imports", True)
+    except ImportError:
+        print("  SKIP langgraph adapter (langgraph not installed)")
+
+    # live smoke (optional)
+    tok, ns = os.environ.get("MEMNOS_TOKEN"), os.environ.get("MEMNOS_NS")
+    if tok and ns:
+        live = MemnosClient(token=tok, namespace=ns)
+        if live.healthy():
+            live.remember("sdk live smoke: postgres chosen")
+            check("LIVE recall", "context" in live.recall("what was chosen?"))
+        live.close()
+
+    print(f"\n{PASS} passed, {FAIL} failed")
+    sys.exit(1 if FAIL else 0)
+
+
+if __name__ == "__main__":
+    main()

memnos_sdk-0.1.0/tests/test_integrations.py

@@ -0,0 +1,108 @@
+"""Adapter tests for memnos_sdk integrations (LangChain, LangGraph, LlamaIndex), driven
+by an httpx MockTransport — no live server. Each adapter section is skipped if its
+framework isn't installed, so this runs standalone. Exits non-zero on any failure.
+
+    python sdk/tests/test_integrations.py
+"""
+import json
+import sys
+
+import httpx
+
+sys.path.insert(0, "sdk")
+sys.path.insert(0, ".")
+from memnos_sdk import MemnosClient
+
+PASS = FAIL = SKIP = 0
+
+
+def check(name, cond):
+    global PASS, FAIL
+    print(f"  {'PASS' if cond else 'FAIL'}  {name}")
+    PASS += bool(cond); FAIL += (not cond)
+
+
+def skip(name):
+    global SKIP
+    print(f"  SKIP  {name}")
+    SKIP += 1
+
+
+# canned server responses
+REMEMBERED = []
+
+
+def handler(request):
+    path = request.url.path
+    if path == "/recall":
+        return httpx.Response(200, json={"memories": [
+            {"id": 1, "content": "We chose PostgreSQL + pgvector over a graph DB", "kind": "fact", "score": 0.92, "date": "2026-01-01"},
+            {"id": 2, "content": "Redis OOM on prod-02 fixed with allkeys-lru", "kind": "incident", "score": 0.71}],
+            "context": "..."})
+    if path == "/remember":
+        REMEMBERED.append(json.loads(request.content))
+        return httpx.Response(200, json={"turn_id": 99, "facts": 1, "superseded": 0})
+    return httpx.Response(404, json={"error": "not found"})
+
+
+def make_client():
+    return MemnosClient(base_url="http://test", token="mnk_x", namespace="org:acme",
+                        transport=httpx.MockTransport(handler))
+
+
+def test_langchain():
+    try:
+        from memnos_sdk.integrations.langchain import MemnosRetriever
+    except ImportError:
+        return skip("langchain adapter (langchain_core not installed)")
+    r = MemnosRetriever(client=make_client(), k=8)
+    docs = r.invoke("what database did we choose?")
+    check("langchain: returns documents", len(docs) == 2)
+    check("langchain: content mapped", "PostgreSQL" in docs[0].page_content)
+    check("langchain: metadata kind+score", docs[0].metadata.get("kind") == "fact" and docs[0].metadata.get("score") == 0.92)
+    REMEMBERED.clear()
+    r.save("We use JWT with 24h expiry")
+    check("langchain: save -> remember", REMEMBERED and REMEMBERED[0]["text"] == "We use JWT with 24h expiry")
+
+
+def test_llamaindex():
+    try:
+        from memnos_sdk.integrations.llamaindex import MemnosRetriever
+    except ImportError:
+        return skip("llamaindex adapter (llama-index-core not installed)")
+    r = MemnosRetriever(client=make_client(), k=8)
+    nodes = r.retrieve("what database did we choose?")
+    check("llamaindex: returns nodes-with-score", len(nodes) == 2)
+    check("llamaindex: text mapped", "PostgreSQL" in nodes[0].node.get_content())
+    check("llamaindex: score mapped", nodes[0].score == 0.92)
+    check("llamaindex: metadata kind", nodes[0].node.metadata.get("kind") == "fact")
+    REMEMBERED.clear()
+    r.save("Prefer Go for backends")
+    check("llamaindex: save -> remember", REMEMBERED and REMEMBERED[0]["text"] == "Prefer Go for backends")
+
+
+def test_langgraph():
+    try:
+        from memnos_sdk.integrations.langgraph import MemnosStore
+    except ImportError:
+        return skip("langgraph adapter (langgraph not installed)")
+    store = MemnosStore(make_client())
+    items = store.search(("org", "acme"), query="database")
+    check("langgraph: search -> items from recall", len(items) >= 1)
+    check("langgraph: item content mapped", "PostgreSQL" in items[0].value.get("content", ""))
+    REMEMBERED.clear()
+    store.put(("org", "acme"), "decision-1", {"text": "use pgvector"})
+    check("langgraph: put -> remember", bool(REMEMBERED) and "decision-1" in REMEMBERED[0]["text"])
+
+
+def main():
+    print("=== memnos_sdk framework adapters ===")
+    test_langchain()
+    test_llamaindex()
+    test_langgraph()
+    print(f"\n{PASS} passed, {FAIL} failed, {SKIP} skipped")
+    sys.exit(1 if FAIL else 0)
+
+
+if __name__ == "__main__":
+    main()