memnos-sdk 0.1.0__py3-none-any.whl

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/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/integrations/__init__.py

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

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

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

@@ -0,0 +1,10 @@
+memnos_sdk/__init__.py,sha256=y9VKTyGO1692ay3M2yd3Xod2MO4AcVGPVKCzQcNAEr4,609
+memnos_sdk/client.py,sha256=etorgZPdcYwhJw2UNLsG6fAScDW_fpg_y22g5eHiqc0,5734
+memnos_sdk/integrations/__init__.py,sha256=REDXaovbT4vPkp382xHt99LQy9VpkwJ0B1Xb9bDAewI,75
+memnos_sdk/integrations/langchain.py,sha256=XOz0cnZdqf44O0x9kTSLaRp3djwR5wGe02aHQ0s1qPk,2054
+memnos_sdk/integrations/langgraph.py,sha256=AmgzgRkCtq5qqfwW0ZldStZksHl_wqKI0UyXybPiLY4,4616
+memnos_sdk/integrations/llamaindex.py,sha256=OhQvpXPFoS1uaBQGZzIseVCzPbbMJpoWzB5jOxW4N1Q,2276
+memnos_sdk-0.1.0.dist-info/METADATA,sha256=rA4vZACJZC7y6fpOKqi-8FUopHcyqAnqLMvUcp4vsn8,3973
+memnos_sdk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+memnos_sdk-0.1.0.dist-info/top_level.txt,sha256=2pE0i6SWCUuJQl4NPrGhauh36f5I-XSPEkW6MdKoVzg,11
+memnos_sdk-0.1.0.dist-info/RECORD,,

memnos_sdk-0.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-0.1.0.dist-info/top_level.txt

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