memclaw-client 0.2.0__tar.gz

memclaw_client-0.2.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: memclaw-client
+Version: 0.2.0
+Summary: Official Python client for MemClaw — governed shared memory for AI agent fleets (multi-agent, multi-tenant, MCP-native).
+Author-email: Caura <hello@caura.ai>
+License: Apache-2.0
+Project-URL: Homepage, https://memclaw.net
+Project-URL: Documentation, https://memclaw.net/docs
+Project-URL: Repository, https://github.com/caura-ai/caura-memclaw
+Project-URL: Issues, https://github.com/caura-ai/caura-memclaw/issues
+Keywords: memclaw,agent-memory,ai-agents,llm-memory,rag,mcp,knowledge-graph,vector-search,multi-agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+
+# memclaw-client
+
+Official Python client for [MemClaw](https://memclaw.net) — governed shared
+memory for AI agent fleets (multi-agent, multi-tenant, MCP-native).
+
+A thin wrapper over the MemClaw REST API. Point it at a managed
+(`https://memclaw.net`) or self-hosted (`http://localhost:8000`) deployment.
+
+## Install
+
+```bash
+pip install memclaw-client
+```
+
+## Quickstart
+
+```python
+from memclaw_client import MemClaw
+
+mc = MemClaw("mc_xxx", tenant_id="my-team", agent_id="my-agent")
+
+# Write a memory — enriched server-side with type, title, tags, importance.
+mc.write("Q3 revenue target is $4M, set on 2026-04-15.")
+
+# Search (ranked raw results)
+for m in mc.search("Q3 revenue target", top_k=5):
+    print(m.title, "—", m.content)
+
+# Recall (LLM-synthesized context brief)
+print(mc.recall("Q3 revenue target").summary)
+```
+
+Self-hosted? Pass `base_url`:
+
+```python
+mc = MemClaw("standalone", tenant_id="default", base_url="http://localhost:8000")
+```
+
+## API
+
+| Method | Endpoint | Returns |
+|---|---|---|
+| `write(content, ...)` | `POST /api/v1/memories` | `Memory` |
+| `search(query, top_k=5, ...)` | `POST /api/v1/search` | `list[Memory]` |
+| `recall(query, top_k=5, ...)` | `POST /api/v1/recall` | `RecallResult` |
+| `health()` | `GET /api/v1/health` | `dict` |
+
+The client is a context manager (`with MemClaw(...) as mc:`) and raises
+`AuthError` (401/403), `NotFoundError` (404), or `MemClawAPIError` on failures.
+Every result also exposes the full API payload on `.raw`.
+
+For credentials, scopes, and the full API surface, see the
+[MemClaw docs](https://memclaw.net/docs). Production fleets should use
+[per-agent keys](https://memclaw.net/docs/integrations/per-agent-keys).
+
+## memclaw-interviewer — Claude Code adapter (Interviewer Phase 2)
+
+Installing this package also provides the `memclaw-interviewer` CLI: the
+MemClaw Interviewer's disk-parser adapter for Claude Code workstations. It
+reads Claude Code session transcripts (`~/.claude/projects/…/*.jsonl`)
+**read-only**, tracks a per-file cursor via the server's forward-only
+watermark documents (no local state), and submits event windows to
+`POST /api/v1/interview/submit`, where MemClaw synthesizes them into typed
+memories. Requires the tenant to have `interviewer.enabled = true`.
+
+```bash
+export MEMCLAW_API_KEY=mc_xxx MEMCLAW_TENANT_ID=my-team
+export MEMCLAW_INTERVIEWER_PROJECTS="-Users-me-work-*"   # allowlist, default-deny
+
+memclaw-interviewer status --since-hours 24     # cursors vs. local line counts
+memclaw-interviewer run --dry-run -v            # parse + window, submit nothing
+memclaw-interviewer run --max-windows 8         # submit due windows
+```
+
+**Privacy:** default-deny — with no allowlist the CLI lists discovered
+project dirs and exits with guidance; `--all-projects` is the explicit
+opt-in. Credential-shaped strings are scrubbed locally before anything
+leaves the machine, and the server masks PII again on receipt.
+
+**Triggers:** run it from cron, or wire Claude Code's SessionEnd hook so a
+session is interviewed the moment it ends (a failed harvest never fails
+the session — the hook always exits 0):
+
+```json
+{ "hooks": { "SessionEnd": [ { "hooks": [
+  { "type": "command", "command": "memclaw-interviewer hook", "timeout": 300 }
+] } ] } }
+```
+
+Crash-safety is inherited from the Interviewer protocol: the watermark
+advances only after the server commits a window, and retries of the same
+window dedup server-side via a deterministic attempt id — never a gap,
+never a duplicate.
+
+## License
+
+Apache-2.0

memclaw_client-0.2.0/README.md

@@ -0,0 +1,97 @@
+# memclaw-client
+
+Official Python client for [MemClaw](https://memclaw.net) — governed shared
+memory for AI agent fleets (multi-agent, multi-tenant, MCP-native).
+
+A thin wrapper over the MemClaw REST API. Point it at a managed
+(`https://memclaw.net`) or self-hosted (`http://localhost:8000`) deployment.
+
+## Install
+
+```bash
+pip install memclaw-client
+```
+
+## Quickstart
+
+```python
+from memclaw_client import MemClaw
+
+mc = MemClaw("mc_xxx", tenant_id="my-team", agent_id="my-agent")
+
+# Write a memory — enriched server-side with type, title, tags, importance.
+mc.write("Q3 revenue target is $4M, set on 2026-04-15.")
+
+# Search (ranked raw results)
+for m in mc.search("Q3 revenue target", top_k=5):
+    print(m.title, "—", m.content)
+
+# Recall (LLM-synthesized context brief)
+print(mc.recall("Q3 revenue target").summary)
+```
+
+Self-hosted? Pass `base_url`:
+
+```python
+mc = MemClaw("standalone", tenant_id="default", base_url="http://localhost:8000")
+```
+
+## API
+
+| Method | Endpoint | Returns |
+|---|---|---|
+| `write(content, ...)` | `POST /api/v1/memories` | `Memory` |
+| `search(query, top_k=5, ...)` | `POST /api/v1/search` | `list[Memory]` |
+| `recall(query, top_k=5, ...)` | `POST /api/v1/recall` | `RecallResult` |
+| `health()` | `GET /api/v1/health` | `dict` |
+
+The client is a context manager (`with MemClaw(...) as mc:`) and raises
+`AuthError` (401/403), `NotFoundError` (404), or `MemClawAPIError` on failures.
+Every result also exposes the full API payload on `.raw`.
+
+For credentials, scopes, and the full API surface, see the
+[MemClaw docs](https://memclaw.net/docs). Production fleets should use
+[per-agent keys](https://memclaw.net/docs/integrations/per-agent-keys).
+
+## memclaw-interviewer — Claude Code adapter (Interviewer Phase 2)
+
+Installing this package also provides the `memclaw-interviewer` CLI: the
+MemClaw Interviewer's disk-parser adapter for Claude Code workstations. It
+reads Claude Code session transcripts (`~/.claude/projects/…/*.jsonl`)
+**read-only**, tracks a per-file cursor via the server's forward-only
+watermark documents (no local state), and submits event windows to
+`POST /api/v1/interview/submit`, where MemClaw synthesizes them into typed
+memories. Requires the tenant to have `interviewer.enabled = true`.
+
+```bash
+export MEMCLAW_API_KEY=mc_xxx MEMCLAW_TENANT_ID=my-team
+export MEMCLAW_INTERVIEWER_PROJECTS="-Users-me-work-*"   # allowlist, default-deny
+
+memclaw-interviewer status --since-hours 24     # cursors vs. local line counts
+memclaw-interviewer run --dry-run -v            # parse + window, submit nothing
+memclaw-interviewer run --max-windows 8         # submit due windows
+```
+
+**Privacy:** default-deny — with no allowlist the CLI lists discovered
+project dirs and exits with guidance; `--all-projects` is the explicit
+opt-in. Credential-shaped strings are scrubbed locally before anything
+leaves the machine, and the server masks PII again on receipt.
+
+**Triggers:** run it from cron, or wire Claude Code's SessionEnd hook so a
+session is interviewed the moment it ends (a failed harvest never fails
+the session — the hook always exits 0):
+
+```json
+{ "hooks": { "SessionEnd": [ { "hooks": [
+  { "type": "command", "command": "memclaw-interviewer hook", "timeout": 300 }
+] } ] } }
+```
+
+Crash-safety is inherited from the Interviewer protocol: the watermark
+advances only after the server commits a window, and retries of the same
+window dedup server-side via a deterministic attempt id — never a gap,
+never a duplicate.
+
+## License
+
+Apache-2.0

memclaw_client-0.2.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["setuptools>=75"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "memclaw-client"
+version = "0.2.0"
+description = "Official Python client for MemClaw — governed shared memory for AI agent fleets (multi-agent, multi-tenant, MCP-native)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Caura", email = "hello@caura.ai" }]
+keywords = [
+    "memclaw",
+    "agent-memory",
+    "ai-agents",
+    "llm-memory",
+    "rag",
+    "mcp",
+    "knowledge-graph",
+    "vector-search",
+    "multi-agent",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.scripts]
+memclaw-interviewer = "memclaw_client.interviewer.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[project.urls]
+Homepage = "https://memclaw.net"
+Documentation = "https://memclaw.net/docs"
+Repository = "https://github.com/caura-ai/caura-memclaw"
+Issues = "https://github.com/caura-ai/caura-memclaw/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+memclaw_client = ["py.typed"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 110
+src = ["src", "tests"]
+
+[tool.pytest.ini_options]
+# Self-contained config so the client suite doesn't inherit the repo-root
+# pytest.ini (which configures pytest-asyncio for the backend services).
+testpaths = ["tests"]

memclaw_client-0.2.0/setup.cfg

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

memclaw_client-0.2.0/src/memclaw_client/__init__.py

@@ -0,0 +1,20 @@
+"""Official Python client for MemClaw — governed shared memory for AI agent fleets."""
+
+from __future__ import annotations
+
+from .client import DEFAULT_BASE_URL, MemClaw
+from .exceptions import AuthError, MemClawAPIError, MemClawError, NotFoundError
+from .models import Memory, RecallResult
+
+__all__ = [
+    "MemClaw",
+    "Memory",
+    "RecallResult",
+    "MemClawError",
+    "MemClawAPIError",
+    "AuthError",
+    "NotFoundError",
+    "DEFAULT_BASE_URL",
+]
+
+__version__ = "0.1.0"

memclaw_client-0.2.0/src/memclaw_client/client.py

@@ -0,0 +1,219 @@
+"""Synchronous MemClaw client.
+
+A thin wrapper over the MemClaw REST API. Point it at a managed
+(``https://memclaw.net``) or self-hosted (``http://localhost:8000``) deployment.
+"""
+
+from __future__ import annotations
+
+import urllib.parse
+from typing import Any
+
+import httpx
+
+from .exceptions import AuthError, MemClawAPIError, NotFoundError
+from .models import Memory, RecallResult
+
+DEFAULT_BASE_URL = "https://memclaw.net"
+
+
+class MemClaw:
+    """Client for a MemClaw deployment.
+
+    Example::
+
+        from memclaw_client import MemClaw
+
+        mc = MemClaw("mc_xxx", tenant_id="my-team", agent_id="my-agent")
+        mc.write("Q3 revenue target is $4M, set on 2026-04-15.")
+        for m in mc.search("Q3 revenue target"):
+            print(m.title, m.content)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        tenant_id: str,
+        base_url: str = DEFAULT_BASE_URL,
+        agent_id: str | None = None,
+        timeout: float = 30.0,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        if not tenant_id:
+            raise ValueError("tenant_id is required")
+        self.tenant_id = tenant_id
+        self.agent_id = agent_id
+        self._http = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            headers={"X-API-Key": api_key, "Content-Type": "application/json"},
+            timeout=timeout,
+            transport=transport,
+        )
+
+    # ------------------------------------------------------------------ ops
+    def write(
+        self,
+        content: str,
+        *,
+        agent_id: str | None = None,
+        memory_type: str | None = None,
+        fleet_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        **extra: Any,
+    ) -> Memory:
+        """Persist a memory. Returns the enriched ``Memory`` (POST /api/v1/memories)."""
+        body: dict[str, Any] = {"tenant_id": self.tenant_id, "content": content}
+        resolved_agent = agent_id or self.agent_id
+        if resolved_agent:
+            body["agent_id"] = resolved_agent
+        if memory_type:
+            body["memory_type"] = memory_type
+        if fleet_id:
+            body["fleet_id"] = fleet_id
+        if metadata is not None:
+            body["metadata"] = metadata
+        body.update(extra)
+        return Memory.from_dict(self._post("/api/v1/memories", body))
+
+    def search(
+        self,
+        query: str,
+        *,
+        top_k: int = 5,
+        fleet_ids: list[str] | None = None,
+        filter_agent_id: str | None = None,
+        **extra: Any,
+    ) -> list[Memory]:
+        """Hybrid vector + keyword search. Returns ranked ``Memory`` objects (POST /api/v1/search)."""
+        body: dict[str, Any] = {"tenant_id": self.tenant_id, "query": query, "top_k": top_k}
+        if fleet_ids:
+            body["fleet_ids"] = fleet_ids
+        if filter_agent_id:
+            body["filter_agent_id"] = filter_agent_id
+        body.update(extra)
+        data = self._post("/api/v1/search", body)
+        if not isinstance(data, dict):
+            raise MemClawAPIError(200, "search response must be a JSON object")
+        if "items" not in data:
+            raise MemClawAPIError(200, 'search response missing "items" list')
+        items = data["items"]
+        if not isinstance(items, list):
+            raise MemClawAPIError(200, 'search response "items" must be a list')
+        return [Memory.from_dict(m) for m in items]
+
+    def recall(self, query: str, *, top_k: int = 5, **extra: Any) -> RecallResult:
+        """Search + LLM summary. Returns a ``RecallResult`` context brief (POST /api/v1/recall)."""
+        body: dict[str, Any] = {"tenant_id": self.tenant_id, "query": query, "top_k": top_k}
+        body.update(extra)
+        return RecallResult.from_dict(self._post("/api/v1/recall", body))
+
+    def health(self) -> dict[str, Any]:
+        """Liveness probe (GET /api/v1/health)."""
+        response = self._http.get("/api/v1/health")
+        return response.json()
+
+    def get_document(
+        self,
+        doc_id: str,
+        *,
+        collection: str,
+        tenant_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Fetch one structured document (GET /api/v1/documents/{doc_id}).
+
+        Returns the full ``DocOut`` envelope — the stored record is under
+        the ``"data"`` key. Raises ``NotFoundError`` if absent.
+        """
+        # Percent-encode the path segment: httpx does not encode f-string
+        # paths, so a doc_id containing '/' would hit a different route and
+        # '?' would inject query params.
+        encoded = urllib.parse.quote(doc_id, safe="")
+        response = self._http.get(
+            f"/api/v1/documents/{encoded}",
+            params={"tenant_id": tenant_id or self.tenant_id, "collection": collection},
+        )
+        self._raise_for_status(response)
+        return response.json()
+
+    def submit_interview(
+        self,
+        *,
+        node_id: str,
+        agent_id: str,
+        cursor_from: int,
+        cursor_to: int,
+        events: list[dict[str, Any]],
+        tenant_id: str | None = None,
+        fleet_id: str | None = None,
+        command_id: str | None = None,
+        timeout: float = 120.0,
+    ) -> dict[str, Any]:
+        """Submit one Interviewer window (POST /api/v1/interview/submit).
+
+        The server interviews the window synchronously (its budget is 90s),
+        so ``timeout`` defaults well above the client-wide 30s. Returns the
+        response body plus ``"http_status"`` so callers can distinguish a
+        207 partial from a 200 committed. Raises on 4xx/5xx via the shared
+        error mapping (403 → ``AuthError``: tenant not enabled / bad key).
+        """
+        body: dict[str, Any] = {
+            "tenant_id": tenant_id or self.tenant_id,
+            "node_id": node_id,
+            "agent_id": agent_id,
+            "cursor_from": cursor_from,
+            "cursor_to": cursor_to,
+            "events": events,
+        }
+        if fleet_id:
+            body["fleet_id"] = fleet_id
+        if command_id:
+            body["command_id"] = command_id
+        response = self._http.post("/api/v1/interview/submit", json=body, timeout=timeout)
+        self._raise_for_status(response)
+        result = response.json()
+        if isinstance(result, dict):
+            result["http_status"] = response.status_code
+        return result
+
+    # ------------------------------------------------------------- internals
+    def _post(self, path: str, body: dict[str, Any]) -> Any:
+        response = self._http.post(path, json=body)
+        self._raise_for_status(response)
+        return response.json()
+
+    @staticmethod
+    def _raise_for_status(response: httpx.Response) -> None:
+        if response.is_success:
+            return
+        try:
+            payload: Any = response.json()
+        except ValueError:
+            payload = {}
+        message = ""
+        details: Any = None
+        if isinstance(payload, dict):
+            error = payload.get("error")
+            if isinstance(error, dict):
+                message = error.get("message") or ""
+                details = error.get("details")
+            message = message or payload.get("detail") or payload.get("message") or response.text
+        else:
+            message = response.text
+        if response.status_code in (401, 403):
+            raise AuthError(response.status_code, message or "authentication failed", details=details)
+        if response.status_code == 404:
+            raise NotFoundError(response.status_code, message or "not found", details=details)
+        raise MemClawAPIError(response.status_code, message or "request failed", details=details)
+
+    # ------------------------------------------------------------- lifecycle
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> MemClaw:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

memclaw_client-0.2.0/src/memclaw_client/exceptions.py

@@ -0,0 +1,30 @@
+"""Exceptions raised by the MemClaw client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class MemClawError(Exception):
+    """Base class for all MemClaw client errors."""
+
+
+class MemClawAPIError(MemClawError):
+    """Raised when the MemClaw API returns a non-success status code.
+
+    The structured ``error`` envelope (``{"error": {"code", "message", "details"}}``)
+    is parsed when present; otherwise the raw body is used as the message.
+    """
+
+    def __init__(self, status_code: int, message: str, *, details: Any = None) -> None:
+        self.status_code = status_code
+        self.details = details
+        super().__init__(f"[{status_code}] {message}")
+
+
+class AuthError(MemClawAPIError):
+    """Raised on 401/403 — bad or insufficiently-scoped credential."""
+
+
+class NotFoundError(MemClawAPIError):
+    """Raised on 404."""

memclaw_client-0.2.0/src/memclaw_client/interviewer/__init__.py

@@ -0,0 +1,10 @@
+"""memclaw-interviewer — the Claude Code disk-parser adapter (Interviewer Phase 2).
+
+Reads Claude Code session transcripts (``~/.claude/projects/<slug>/<uuid>.jsonl``)
+READ-ONLY, tracks per-file cursors via the server's forward-only watermark
+documents, and submits event windows to ``POST /api/v1/interview/submit``.
+No local state; no server changes; the trail belongs to Claude Code and is
+never modified.
+"""
+
+from __future__ import annotations