mayamemo 0.1.0__tar.gz

mayamemo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MayaMemo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mayamemo-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: mayamemo
+Version: 0.1.0
+Summary: MayaMemo Python SDK — evidence-backed context, memories and cross-agent checkpoints for AI coding agents. Zero dependencies.
+Author: MayaMemo
+License: MIT
+Project-URL: Homepage, https://github.com/Coin1511/mayamemo
+Project-URL: Repository, https://github.com/Coin1511/mayamemo/tree/main/sdk/python
+Keywords: mayamemo,ai-agents,memory,context,checkpoints,mcp
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == "langchain"
+Dynamic: license-file
+
+# MayaMemo — Python SDK
+
+Zero-dependency Python client for the [MayaMemo](../..) API: projects, memories
+(with tags), semantic search, the context compiler, checkpoints and cross-agent resume.
+
+```bash
+# from the repo
+pip install -e sdk/python        # or: pip install -e "sdk/python[langchain]"
+```
+
+## Quickstart
+
+```python
+from mayamemo import MayaMemo
+
+client = MayaMemo(api_key="mm_sk_...", api_url="http://localhost:4000")
+
+project = client.create_project("my-app")
+
+client.add_memory(
+    project["id"],
+    "Checkout retries go through an idempotency table keyed by cart_id + attempt",
+    type="decision",
+    tags=["checkout", "billing"],
+)
+
+hits = client.search_memories(project["id"], "how do we avoid double charges?")
+print(hits[0]["statement"], hits[0]["score"])
+
+checkpoint = client.create_checkpoint(
+    project["id"], "billing groundwork",
+    "Idempotency decision captured; outbox worker noted.",
+    next_steps=["wire refund metrics"], agent="my-agent",
+)
+
+briefing = client.resume_checkpoint(checkpoint["id"], agent="another-agent")["briefing_markdown"]
+print(briefing)
+```
+
+Environment defaults: `MAYAMEMO_API_KEY` (or `MAYAMEMO_TOKEN`) and `MAYAMEMO_API_URL`
+(`http://localhost:4000`). API keys are created in the workspace (`POST /v1/keys`),
+scoped per workspace and revocable.
+
+## Framework adapters
+
+`mayamemo.integrations` ships a LangChain-style retriever and chat-memory adapter.
+They subclass the real `langchain-core` classes when it is installed (true drop-in)
+and work standalone otherwise.
+
+```python
+from mayamemo import MayaMemo, MayaMemoRetriever, MayaMemoMemory
+
+retriever = MayaMemoRetriever(client, project["id"], tags=["checkout"])
+docs = retriever.invoke("how do retries work?")        # [{page_content, metadata}, …]
+
+memory = MayaMemoMemory(client, project["id"])         # BaseMemory-compatible
+memory.load_memory_variables({"input": "how do deploys work?"})  # {"mayamemo_context": "…"}
+memory.save_context({"input": "…"}, {"output": "…"})    # recorded as a `discovery` memory
+```
+
+`MayaMemoMemory.clear()` is a no-op by design — the MayaMemo ledger is append-only
+(use retention windows or supersession; history is evidence).
+
+## Tests
+
+Live tests run against a real API (they skip without a key):
+
+```bash
+cd sdk/python
+MAYAMEMO_TEST_KEY_FILE=/path/to/.ctxkey python -m pytest tests -q
+```
+
+Each run creates its own project (`sdk-suite-<run>`) — semantic dedupe (0.92 cosine)
+correctly treats near-identical statements as duplicates, so per-run isolation keeps
+re-runs meaningful. Point the test key at a workspace with project-quota headroom
+(the runs consume project slots by design). `examples/quickstart.py` is idempotent:
+a duplicate is reported as `already captured — semantic dedupe` and reused.
+
+## Coverage
+
+`projects` · `memories` (add / search / list / patch / tags) · `compile_context` ·
+`checkpoints` (create / list / resume) · `events` · `public_status` · branded
+`MayaMemoError(status, code, message, request_id)` on every non-2xx.

mayamemo-0.1.0/README.md

@@ -0,0 +1,83 @@
+# MayaMemo — Python SDK
+
+Zero-dependency Python client for the [MayaMemo](../..) API: projects, memories
+(with tags), semantic search, the context compiler, checkpoints and cross-agent resume.
+
+```bash
+# from the repo
+pip install -e sdk/python        # or: pip install -e "sdk/python[langchain]"
+```
+
+## Quickstart
+
+```python
+from mayamemo import MayaMemo
+
+client = MayaMemo(api_key="mm_sk_...", api_url="http://localhost:4000")
+
+project = client.create_project("my-app")
+
+client.add_memory(
+    project["id"],
+    "Checkout retries go through an idempotency table keyed by cart_id + attempt",
+    type="decision",
+    tags=["checkout", "billing"],
+)
+
+hits = client.search_memories(project["id"], "how do we avoid double charges?")
+print(hits[0]["statement"], hits[0]["score"])
+
+checkpoint = client.create_checkpoint(
+    project["id"], "billing groundwork",
+    "Idempotency decision captured; outbox worker noted.",
+    next_steps=["wire refund metrics"], agent="my-agent",
+)
+
+briefing = client.resume_checkpoint(checkpoint["id"], agent="another-agent")["briefing_markdown"]
+print(briefing)
+```
+
+Environment defaults: `MAYAMEMO_API_KEY` (or `MAYAMEMO_TOKEN`) and `MAYAMEMO_API_URL`
+(`http://localhost:4000`). API keys are created in the workspace (`POST /v1/keys`),
+scoped per workspace and revocable.
+
+## Framework adapters
+
+`mayamemo.integrations` ships a LangChain-style retriever and chat-memory adapter.
+They subclass the real `langchain-core` classes when it is installed (true drop-in)
+and work standalone otherwise.
+
+```python
+from mayamemo import MayaMemo, MayaMemoRetriever, MayaMemoMemory
+
+retriever = MayaMemoRetriever(client, project["id"], tags=["checkout"])
+docs = retriever.invoke("how do retries work?")        # [{page_content, metadata}, …]
+
+memory = MayaMemoMemory(client, project["id"])         # BaseMemory-compatible
+memory.load_memory_variables({"input": "how do deploys work?"})  # {"mayamemo_context": "…"}
+memory.save_context({"input": "…"}, {"output": "…"})    # recorded as a `discovery` memory
+```
+
+`MayaMemoMemory.clear()` is a no-op by design — the MayaMemo ledger is append-only
+(use retention windows or supersession; history is evidence).
+
+## Tests
+
+Live tests run against a real API (they skip without a key):
+
+```bash
+cd sdk/python
+MAYAMEMO_TEST_KEY_FILE=/path/to/.ctxkey python -m pytest tests -q
+```
+
+Each run creates its own project (`sdk-suite-<run>`) — semantic dedupe (0.92 cosine)
+correctly treats near-identical statements as duplicates, so per-run isolation keeps
+re-runs meaningful. Point the test key at a workspace with project-quota headroom
+(the runs consume project slots by design). `examples/quickstart.py` is idempotent:
+a duplicate is reported as `already captured — semantic dedupe` and reused.
+
+## Coverage
+
+`projects` · `memories` (add / search / list / patch / tags) · `compile_context` ·
+`checkpoints` (create / list / resume) · `events` · `public_status` · branded
+`MayaMemoError(status, code, message, request_id)` on every non-2xx.

mayamemo-0.1.0/mayamemo/__init__.py

@@ -0,0 +1,7 @@
+"""MayaMemo Python SDK."""
+
+from .client import MayaMemo, MayaMemoError
+from .integrations import MayaMemoMemory, MayaMemoRetriever
+
+__all__ = ["MayaMemo", "MayaMemoError", "MayaMemoMemory", "MayaMemoRetriever"]
+__version__ = "0.1.0"

mayamemo-0.1.0/mayamemo/client.py

@@ -0,0 +1,284 @@
+"""MayaMemo Python SDK — thin, zero-dependency client for the MayaMemo API.
+
+    pip install -e sdk/python   (or copy the `mayamemo/` package — no deps)
+
+Quickstart:
+    from mayamemo import MayaMemo
+    client = MayaMemo(api_key="mm_sk_...", api_url="http://localhost:4000")
+    project = client.create_project("my-app")
+    client.add_memory(project["id"], "Retries go through an idempotency table", type="decision",
+                      tags=["checkout"])
+    hits = client.search_memories(project["id"], "how do we avoid double charges?")
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+__all__ = ["MayaMemo", "MayaMemoError"]
+
+__version__ = "0.1.0"
+
+
+class MayaMemoError(Exception):
+    """Branded API error: {status} {code}: {message} — request_id for support.
+
+    `details` carries any structured extras the API attached, e.g. a 409
+    DUPLICATE_MEMORY ships `{"duplicate_of": "<memory id>"}`.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        request_id: str | None = None,
+        details: dict[str, Any] | None = None,
+    ):
+        super().__init__(f"{status} {code}: {message}")
+        self.status = status
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        self.details = details or {}
+
+    @property
+    def duplicate_of(self) -> str | None:
+        value = self.details.get("duplicate_of")
+        return value if isinstance(value, str) else None
+
+
+class MayaMemo:
+    """Synchronous zero-dependency client. Auth: workspace API key (mm_sk_…)."""
+
+    def __init__(self, api_key: str | None = None, api_url: str | None = None, timeout: float = 60.0):
+        self.api_key = api_key or os.environ.get("MAYAMEMO_API_KEY") or os.environ.get("MAYAMEMO_TOKEN")
+        if not self.api_key:
+            raise ValueError("api_key is required (or set MAYAMEMO_API_KEY / MAYAMEMO_TOKEN)")
+        self.api_url = (api_url or os.environ.get("MAYAMEMO_API_URL") or "http://localhost:4000").rstrip("/")
+        self.timeout = timeout
+
+    # ------------------------------------------------------------------ HTTP
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Any = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        url = f"{self.api_url}{path}"
+        if params:
+            clean = {k: v for k, v in params.items() if v is not None}
+            if clean:
+                url += "?" + urllib.parse.urlencode(clean, doseq=True)
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(url, data=data, method=method)
+        req.add_header("Authorization", f"Bearer {self.api_key}")
+        req.add_header("Accept", "application/json")
+        if data is not None:
+            req.add_header("Content-Type", "application/json")
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                raw = res.read().decode()
+                return json.loads(raw) if raw.strip() else None
+        except urllib.error.HTTPError as exc:
+            raw = exc.read().decode(errors="replace")
+            code, message, request_id, details = "HTTP_ERROR", raw[:300], None, {}
+            try:
+                err = dict((json.loads(raw) or {}).get("error") or {})
+                code = err.pop("code", code)
+                message = err.pop("message", message)
+                request_id = err.pop("request_id", None)
+                details = err
+            except ValueError:
+                pass
+            raise MayaMemoError(exc.code, code, message, request_id, details) from None
+
+    # -------------------------------------------------------------- projects
+
+    def list_projects(self) -> list[dict[str, Any]]:
+        return self._request("GET", "/v1/projects")
+
+    def create_project(self, name: str, description: str | None = None) -> dict[str, Any]:
+        body: dict[str, Any] = {"name": name}
+        if description is not None:
+            body["description"] = description
+        return self._request("POST", "/v1/projects", body)
+
+    # -------------------------------------------------------------- memories
+
+    def add_memory(
+        self,
+        project_id: str,
+        statement: str,
+        *,
+        type: str = "fact",  # noqa: A002 - mirrors the API field name
+        tags: list[str] | None = None,
+        confidence: float | None = None,
+        importance: float | None = None,
+        authority: str | None = None,
+        source_session_id: str | None = None,
+        source_event_id: str | None = None,
+        entities: list[dict[str, Any]] | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"project_id": project_id, "statement": statement, "type": type}
+        for key, value in (
+            ("tags", tags),
+            ("confidence", confidence),
+            ("importance", importance),
+            ("authority", authority),
+            ("source_session_id", source_session_id),
+            ("source_event_id", source_event_id),
+            ("entities", entities),
+        ):
+            if value is not None:
+                body[key] = value
+        return self._request("POST", "/v1/memories", body)
+
+    def search_memories(
+        self,
+        project_id: str,
+        query: str,
+        *,
+        tags: list[str] | None = None,
+        limit: int = 10,
+        status: str | None = None,
+    ) -> list[dict[str, Any]]:
+        body: dict[str, Any] = {"project_id": project_id, "query": query, "limit": limit}
+        if tags:
+            body["tags"] = tags
+        if status:
+            body["status"] = status
+        return self._request("POST", "/v1/memories/search", body)
+
+    def list_memories(
+        self,
+        project_id: str,
+        *,
+        tag: str | None = None,
+        type: str | None = None,  # noqa: A002
+        status: str | None = None,
+        limit: int | None = None,
+    ) -> list[dict[str, Any]]:
+        return self._request(
+            "GET",
+            "/v1/memories",
+            params={"project_id": project_id, "tag": tag, "type": type, "status": status, "limit": limit},
+        )
+
+    def patch_memory(self, memory_id: str, **changes: Any) -> dict[str, Any]:
+        return self._request("PATCH", f"/v1/memories/{memory_id}", changes)
+
+    # ----------------------------------------------------------- checkpoints
+
+    def create_checkpoint(
+        self,
+        project_id: str,
+        title: str,
+        summary: str,
+        *,
+        next_steps: list[str] | None = None,
+        blockers: list[str] | None = None,
+        agent: str | None = None,
+        session_id: str | None = None,
+        token_budget: int | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"project_id": project_id, "title": title, "summary": summary}
+        for key, value in (
+            ("next_steps", next_steps),
+            ("blockers", blockers),
+            ("agent", agent),
+            ("session_id", session_id),
+            ("token_budget", token_budget),
+        ):
+            if value is not None:
+                body[key] = value
+        return self._request("POST", "/v1/checkpoints", body)
+
+    def list_checkpoints(self, project_id: str) -> list[dict[str, Any]]:
+        data = self._request("GET", f"/v1/projects/{project_id}/checkpoints")
+        return (data or {}).get("checkpoints", [])
+
+    def resume_checkpoint(self, checkpoint_id: str, *, agent: str) -> dict[str, Any]:
+        """Resume as `agent` (any agent key). Returns checkpoint, resumed_session and briefing_markdown."""
+        return self._request("POST", f"/v1/checkpoints/{checkpoint_id}/resume", {"agent": agent})
+
+    # --------------------------------------------------------------- context
+
+    def compile_context(
+        self,
+        project_id: str,
+        title: str,
+        *,
+        description: str | None = None,
+        token_budget: int | None = None,
+        branch: str | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"project_id": project_id, "title": title}
+        for key, value in (("description", description), ("token_budget", token_budget), ("branch", branch)):
+            if value is not None:
+                body[key] = value
+        return self._request("POST", "/v1/context/compile", body)
+
+    # ----------------------------------------------------------------- graph
+
+    def observe_entities(
+        self,
+        project_id: str,
+        entities: list[dict[str, Any]],
+        relations: list[dict[str, Any]] | None = None,
+    ) -> dict[str, Any]:
+        """Observe code entities + relations (idempotent by kind+name).
+
+        entities: [{"kind": "file", "name": "src/cart.js"}, ...] (max 50)
+        relations: [{"source": {...}, "target": {...}, "kind": "imports"}, ...] (max 100)
+        """
+        body: dict[str, Any] = {"project_id": project_id, "entities": entities}
+        if relations:
+            body["relations"] = relations
+        return self._request("POST", "/v1/entities/observe", body)
+
+    def list_entities(
+        self,
+        project_id: str,
+        *,
+        kind: str | None = None,
+        q: str | None = None,
+        limit: int | None = None,
+    ) -> list[dict[str, Any]]:
+        data = self._request(
+            "GET",
+            f"/v1/projects/{project_id}/entities",
+            params={"kind": kind, "q": q, "limit": limit},
+        )
+        return (data or {}).get("entities", [])
+
+    def get_entity(self, entity_id: str) -> dict[str, Any]:
+        """Entity detail: relations (direction, other) + linked active memories."""
+        return self._request("GET", f"/v1/entities/{entity_id}")
+
+    def entity_neighbors(self, entity_id: str, *, depth: int = 1) -> dict[str, Any]:
+        """BFS over relations (depth 1..2): {root, nodes, edges, truncated}."""
+        return self._request("GET", f"/v1/entities/{entity_id}/neighbors", params={"depth": depth})
+
+    # ---------------------------------------------------------------- events
+
+    def list_events(self, project_id: str, *, limit: int = 50, cursor: int | None = None) -> dict[str, Any]:
+        return self._request(
+            "GET", f"/v1/projects/{project_id}/events", params={"limit": limit, "cursor": cursor}
+        )
+
+    # ----------------------------------------------------------------- misc
+
+    @classmethod
+    def public_status(cls, api_url: str | None = None, timeout: float = 15.0) -> dict[str, Any]:
+        """Public /v1/status — no API key required."""
+        url = (api_url or os.environ.get("MAYAMEMO_API_URL") or "http://localhost:4000").rstrip("/")
+        with urllib.request.urlopen(urllib.request.Request(f"{url}/v1/status"), timeout=timeout) as res:
+            return json.loads(res.read().decode())

mayamemo-0.1.0/mayamemo/integrations.py

@@ -0,0 +1,147 @@
+"""Framework adapters — LangChain-style retriever + chat memory.
+
+Duck-typed by design: if `langchain-core` is installed these subclass the real
+base classes (true drop-in); if not, they still work standalone and the module
+imports without any dependency.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .client import MayaMemo
+
+try:  # optional — real LangChain integration when present
+    from langchain_core.memory import BaseMemory as _LCBaseMemory  # type: ignore[import-not-found]
+except Exception:  # pragma: no cover - exercised implicitly everywhere langchain is absent
+    _LCBaseMemory = object  # type: ignore[assignment,misc]
+
+try:
+    from langchain_core.retrievers import BaseRetriever as _LCBaseRetriever  # type: ignore[import-not-found]
+except Exception:  # pragma: no cover
+    _LCBaseRetriever = object  # type: ignore[assignment,misc]
+
+__all__ = ["MayaMemoRetriever", "MayaMemoMemory"]
+
+
+class MayaMemoRetriever(_LCBaseRetriever):  # type: ignore[misc]
+    """Retrieve project memories as documents for RAG-style prompt building."""
+
+    def __init__(self, client: MayaMemo, project_id: str, *, limit: int = 8, tags: list[str] | None = None):
+        self._client = client
+        self._project_id = project_id
+        self._limit = limit
+        self._tags = tags
+
+    def _to_document(self, hit: dict[str, Any]) -> dict[str, Any]:
+        return {
+            "page_content": hit.get("statement", ""),
+            "metadata": {
+                "id": hit.get("id"),
+                "type": hit.get("type"),
+                "tags": hit.get("tags", []),
+                "confidence": hit.get("confidence"),
+                "importance": hit.get("importance"),
+                "score": hit.get("score"),
+                "created_at": hit.get("createdAt"),
+            },
+        }
+
+    def invoke(self, query: Any, config: Any = None) -> list[dict[str, Any]]:
+        q = query if isinstance(query, str) else str((query or {}).get("query", ""))
+        return self._get_relevant_documents(q)
+
+    def _get_relevant_documents(self, query: str, **kwargs: Any) -> list[dict[str, Any]]:
+        hits = self._client.search_memories(
+            self._project_id, query, limit=self._limit, tags=self._tags
+        )
+        return [self._to_document(hit) for hit in hits]
+
+    def get_relevant_documents(self, query: str) -> list[dict[str, Any]]:  # legacy LangChain name
+        return self._get_relevant_documents(query)
+
+
+class MayaMemoMemory(_LCBaseMemory):  # type: ignore[misc]
+    """Chat-memory adapter: load compiles project context; save records the exchange.
+
+    The MayaMemo ledger is append-only by design — `clear()` cannot delete history;
+    it resets only local buffering (documented behavior, not a bug).
+    """
+
+    memory_variables: list[str] = ["mayamemo_context"]
+
+    def __init__(
+        self,
+        client: MayaMemo,
+        project_id: str,
+        *,
+        token_budget: int = 4000,
+        query_key: str = "input",
+        memory_type: str = "discovery",
+        tags: list[str] | None = None,
+    ):
+        self._client = client
+        self._project_id = project_id
+        self._token_budget = token_budget
+        self._query_key = query_key
+        self._memory_type = memory_type
+        self._tags = tags or ["langchain"]
+
+    # -- BaseMemory surface -------------------------------------------------
+
+    def load_memory_variables(self, inputs: dict[str, Any]) -> dict[str, Any]:
+        query = str(inputs.get(self._query_key) or inputs.get("question") or "").strip()
+        if not query:
+            return {"mayamemo_context": ""}
+        try:
+            compiled = self._client.compile_context(
+                self._project_id, query, token_budget=self._token_budget
+            )
+        except Exception:  # never break the host chain on a context hiccup
+            return {"mayamemo_context": ""}
+        lines: list[str] = []
+        for item in compiled.get("items", []):
+            reason = item.get("reason") or {}
+            preview = reason.get("preview") or item.get("statement") or ""
+            if preview:
+                lines.append(f"- [{item.get('source_type', 'item')}] {preview}")
+        return {"mayamemo_context": "\n".join(lines)}
+
+    def save_context(self, inputs: dict[str, Any], outputs: dict[str, Any]) -> None:
+        statement = self._summarize(inputs, outputs)
+        if not statement:
+            return
+        try:
+            self._client.add_memory(
+                self._project_id,
+                statement[:2000],
+                type=self._memory_type,
+                tags=self._tags,
+                authority="model",
+            )
+        except Exception:  # best-effort, like all memory capture
+            pass
+
+    def clear(self) -> None:
+        """No-op: the ledger is append-only. Kept for interface compatibility."""
+
+    # -- helpers ------------------------------------------------------------
+
+    @staticmethod
+    def _stringify(value: Any) -> str:
+        if isinstance(value, str):
+            return value
+        if isinstance(value, list):
+            return " / ".join(MayaMemoMemory._stringify(v) for v in value)
+        if isinstance(value, dict):
+            return json.dumps(value, ensure_ascii=False)
+        return str(value)
+
+    def _summarize(self, inputs: dict[str, Any], outputs: dict[str, Any]) -> str:
+        user = self._stringify(inputs.get(self._query_key) or inputs.get("question") or "")
+        reply = self._stringify(outputs.get("output") or outputs.get("answer") or outputs)
+        user, reply = user.strip(), reply.strip()
+        if not user and not reply:
+            return ""
+        return f"Exchange — user: {user[:400]} · assistant: {reply[:800]}"

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

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: mayamemo
+Version: 0.1.0
+Summary: MayaMemo Python SDK — evidence-backed context, memories and cross-agent checkpoints for AI coding agents. Zero dependencies.
+Author: MayaMemo
+License: MIT
+Project-URL: Homepage, https://github.com/Coin1511/mayamemo
+Project-URL: Repository, https://github.com/Coin1511/mayamemo/tree/main/sdk/python
+Keywords: mayamemo,ai-agents,memory,context,checkpoints,mcp
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == "langchain"
+Dynamic: license-file
+
+# MayaMemo — Python SDK
+
+Zero-dependency Python client for the [MayaMemo](../..) API: projects, memories
+(with tags), semantic search, the context compiler, checkpoints and cross-agent resume.
+
+```bash
+# from the repo
+pip install -e sdk/python        # or: pip install -e "sdk/python[langchain]"
+```
+
+## Quickstart
+
+```python
+from mayamemo import MayaMemo
+
+client = MayaMemo(api_key="mm_sk_...", api_url="http://localhost:4000")
+
+project = client.create_project("my-app")
+
+client.add_memory(
+    project["id"],
+    "Checkout retries go through an idempotency table keyed by cart_id + attempt",
+    type="decision",
+    tags=["checkout", "billing"],
+)
+
+hits = client.search_memories(project["id"], "how do we avoid double charges?")
+print(hits[0]["statement"], hits[0]["score"])
+
+checkpoint = client.create_checkpoint(
+    project["id"], "billing groundwork",
+    "Idempotency decision captured; outbox worker noted.",
+    next_steps=["wire refund metrics"], agent="my-agent",
+)
+
+briefing = client.resume_checkpoint(checkpoint["id"], agent="another-agent")["briefing_markdown"]
+print(briefing)
+```
+
+Environment defaults: `MAYAMEMO_API_KEY` (or `MAYAMEMO_TOKEN`) and `MAYAMEMO_API_URL`
+(`http://localhost:4000`). API keys are created in the workspace (`POST /v1/keys`),
+scoped per workspace and revocable.
+
+## Framework adapters
+
+`mayamemo.integrations` ships a LangChain-style retriever and chat-memory adapter.
+They subclass the real `langchain-core` classes when it is installed (true drop-in)
+and work standalone otherwise.
+
+```python
+from mayamemo import MayaMemo, MayaMemoRetriever, MayaMemoMemory
+
+retriever = MayaMemoRetriever(client, project["id"], tags=["checkout"])
+docs = retriever.invoke("how do retries work?")        # [{page_content, metadata}, …]
+
+memory = MayaMemoMemory(client, project["id"])         # BaseMemory-compatible
+memory.load_memory_variables({"input": "how do deploys work?"})  # {"mayamemo_context": "…"}
+memory.save_context({"input": "…"}, {"output": "…"})    # recorded as a `discovery` memory
+```
+
+`MayaMemoMemory.clear()` is a no-op by design — the MayaMemo ledger is append-only
+(use retention windows or supersession; history is evidence).
+
+## Tests
+
+Live tests run against a real API (they skip without a key):
+
+```bash
+cd sdk/python
+MAYAMEMO_TEST_KEY_FILE=/path/to/.ctxkey python -m pytest tests -q
+```
+
+Each run creates its own project (`sdk-suite-<run>`) — semantic dedupe (0.92 cosine)
+correctly treats near-identical statements as duplicates, so per-run isolation keeps
+re-runs meaningful. Point the test key at a workspace with project-quota headroom
+(the runs consume project slots by design). `examples/quickstart.py` is idempotent:
+a duplicate is reported as `already captured — semantic dedupe` and reused.
+
+## Coverage
+
+`projects` · `memories` (add / search / list / patch / tags) · `compile_context` ·
+`checkpoints` (create / list / resume) · `events` · `public_status` · branded
+`MayaMemoError(status, code, message, request_id)` on every non-2xx.

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

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+mayamemo/__init__.py
+mayamemo/client.py
+mayamemo/integrations.py
+mayamemo.egg-info/PKG-INFO
+mayamemo.egg-info/SOURCES.txt
+mayamemo.egg-info/dependency_links.txt
+mayamemo.egg-info/requires.txt
+mayamemo.egg-info/top_level.txt
+tests/test_sdk.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,3 @@
+
+[langchain]
+langchain-core>=0.2

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

@@ -0,0 +1 @@
+mayamemo

mayamemo-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "mayamemo"
+version = "0.1.0"
+description = "MayaMemo Python SDK — evidence-backed context, memories and cross-agent checkpoints for AI coding agents. Zero dependencies."
+requires-python = ">=3.10"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "MayaMemo" }]
+keywords = ["mayamemo", "ai-agents", "memory", "context", "checkpoints", "mcp"]
+classifiers = [
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+]
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.2"]
+
+[project.urls]
+Homepage = "https://github.com/Coin1511/mayamemo"
+Repository = "https://github.com/Coin1511/mayamemo/tree/main/sdk/python"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["mayamemo"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

mayamemo-0.1.0/setup.cfg

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

mayamemo-0.1.0/tests/test_sdk.py

@@ -0,0 +1,214 @@
+"""Live SDK tests — run against a real MayaMemo API.
+
+    MAYAMEMO_TEST_KEY=mm_sk_...  (or MAYAMEMO_TEST_KEY_FILE=/path/to/key)
+    python -m pytest tests -q
+
+Design notes:
+- ONE find-or-create project per workspace ("sdk-suite-live"): live tests must not
+  create a project per test — the free plan's project quota (correctly) rejects that.
+- Every run tags its memories with a unique `run-<hex>` tag, so count assertions are
+  stable across re-runs against the same project.
+- Tests skip (not fail) when no key is configured, so the suite is CI-safe.
+"""
+
+from __future__ import annotations
+
+import os
+import uuid
+
+import pytest
+
+from mayamemo import MayaMemo, MayaMemoError
+
+
+def _load_key() -> str | None:
+    key = os.environ.get("MAYAMEMO_TEST_KEY")
+    if key:
+        return key.strip()
+    path = os.environ.get("MAYAMEMO_TEST_KEY_FILE")
+    if path and os.path.exists(path):
+        with open(path, encoding="utf-8") as fh:
+            return fh.read().strip()
+    return None
+
+
+KEY = _load_key()
+pytestmark = pytest.mark.skipif(KEY is None, reason="no MAYAMEMO_TEST_KEY / _FILE configured")
+
+RUN = uuid.uuid4().hex[:8]
+RUN_TAG = f"run-{RUN}"
+
+# Each run gets its own project. Reusing one project across runs fights semantic
+# dedupe head-on (0.92 cosine correctly flags paraphrases), so instead every run
+# is isolated — the test workspace just needs project quota headroom (see README).
+PROJECT_NAME = f"sdk-suite-{RUN}"
+
+
+@pytest.fixture(scope="module")
+def client() -> MayaMemo:
+    return MayaMemo(api_key=KEY, api_url=os.environ.get("MAYAMEMO_API_URL", "http://localhost:4000"))
+
+
+@pytest.fixture(scope="module")
+def project(client: MayaMemo) -> dict:
+    try:
+        return client.create_project(PROJECT_NAME)
+    except MayaMemoError as exc:
+        if exc.status == 402:
+            raise RuntimeError(
+                "test workspace project quota is full — give the MAYAMEMO_TEST_KEY workspace "
+                "project headroom (live runs create one project per run by design)"
+            ) from exc
+        raise
+
+
+def test_projects_and_memories_roundtrip(client: MayaMemo, project: dict) -> None:
+    created = client.add_memory(
+        project["id"],
+        "Checkout retries go through an idempotency table keyed by cart_id + attempt",
+        type="decision",
+        tags=[RUN_TAG, "SDK", "checkout"],
+        confidence=0.9,
+        importance=0.8,
+    )
+    assert created["tags"] == [RUN_TAG, "sdk", "checkout"], "tags must lowercase + dedupe, order-preserving"
+    assert created["confidence"] == pytest.approx(0.9)
+
+    # semantic search: different wording, no shared keywords
+    hits = client.search_memories(project["id"], "how do we avoid double charging customers?", tags=[RUN_TAG])
+    assert len(hits) == 1
+    assert "idempotency" in hits[0]["statement"]
+    assert hits[0].get("score") is not None
+
+    # tag-filtered variants
+    assert len(client.list_memories(project["id"], tag=RUN_TAG)) == 1
+    assert len(client.list_memories(project["id"], tag="definitely-not-a-tag")) == 0
+    assert len(client.search_memories(project["id"], "retry strategy", tags=[RUN_TAG])) == 1
+    assert len(client.search_memories(project["id"], "retry strategy", tags=["other-not-a-tag"])) == 0
+
+    # patch replaces tags
+    patched = client.patch_memory(created["id"], tags=["release"])
+    assert patched["tags"] == ["release"]
+
+
+def test_checkpoint_create_list_resume(client: MayaMemo, project: dict) -> None:
+    client.add_memory(project["id"], "Auth uses refresh-token rotation", type="architecture")
+    checkpoint = client.create_checkpoint(
+        project["id"],
+        f"sdk handoff {RUN}",
+        "SDK created memories and a checkpoint end-to-end",
+        next_steps=["resume with another agent"],
+        agent="python-sdk",
+    )
+    assert checkpoint["status"] == "ACTIVE"
+
+    listed = client.list_checkpoints(project["id"])
+    assert any(c["id"] == checkpoint["id"] for c in listed)
+
+    resumed = client.resume_checkpoint(checkpoint["id"], agent="langchain-adapter")
+    assert resumed["resumed_session"]["agent"] == "langchain-adapter"
+    briefing = resumed["briefing_markdown"]
+    assert f"sdk handoff {RUN}" in briefing and "Next steps" in briefing
+
+
+def test_compile_context_and_events(client: MayaMemo, project: dict) -> None:
+    client.add_memory(project["id"], "The billing worker runs every 30 seconds", type="fact")
+    compiled = client.compile_context(project["id"], f"billing worker cadence {RUN}", token_budget=2000)
+    assert compiled["items"], "compiler should surface at least one item"
+    assert compiled["token_count"] >= 0
+
+    events = client.list_events(project["id"], limit=30)
+    types = [e["event_type"] for e in events["events"]]
+    assert "project.created" in types
+    assert "memory.created" in types
+    assert "context.compiled" in types
+
+
+def test_semantic_dedupe_surfaces_duplicate_of(client: MayaMemo, project: dict) -> None:
+    first = client.add_memory(project["id"], "Sessions expire after thirty minutes of inactivity", type="fact")
+    with pytest.raises(MayaMemoError) as excinfo:
+        client.add_memory(
+            project["id"],
+            "Sessions expire after thirty minutes of idle time",  # near-identical wording
+            type="fact",
+        )
+    assert excinfo.value.status == 409
+    assert excinfo.value.code == "DUPLICATE_MEMORY"
+    assert excinfo.value.duplicate_of == first["id"]
+
+
+def test_graph_entities_relations_and_memory_links(client: MayaMemo, project: dict) -> None:
+    observed = client.observe_entities(
+        project["id"],
+        [
+            {"kind": "file", "name": "sdk/graph_a.py"},
+            {"kind": "file", "name": "sdk/graph_b.py"},
+        ],
+        relations=[
+            {
+                "source": {"kind": "file", "name": "sdk/graph_a.py"},
+                "target": {"kind": "file", "name": "sdk/graph_b.py"},
+                "kind": "imports",
+            }
+        ],
+    )
+    assert observed["entity_count"] == 2 and observed["relation_count"] == 1
+
+    listed = client.list_entities(project["id"], q="sdk/graph")
+    assert len(listed) == 2
+    a = next(e for e in listed if e["name"].endswith("graph_a.py"))
+
+    detail = client.get_entity(a["id"])
+    assert any(r["other"]["name"].endswith("graph_b.py") for r in detail["relations"])
+
+    neighbors = client.entity_neighbors(a["id"], depth=1)
+    assert {n["name"] for n in neighbors["nodes"]} == {"sdk/graph_a.py", "sdk/graph_b.py"}
+
+    memory = client.add_memory(
+        project["id"],
+        "SDK graph proof: graph_a imports graph_b for the pipeline",
+        type="fact",
+        entities=[{"kind": "file", "name": "sdk/graph_a.py"}],
+    )
+    detail2 = client.get_entity(a["id"])
+    assert any(m["id"] == memory["id"] for m in detail2["memories"])
+
+
+def test_errors_are_branded(client: MayaMemo) -> None:
+    bad = MayaMemo(api_key="mm_sk_thisisnotarealkey000000000000000000", api_url=client.api_url)
+    with pytest.raises(MayaMemoError) as excinfo:
+        bad.list_projects()
+    assert excinfo.value.status == 401
+    assert excinfo.value.code == "UNAUTHENTICATED"
+
+    with pytest.raises(MayaMemoError) as excinfo:
+        client.list_memories("00000000-0000-4000-8000-000000000000")
+    assert excinfo.value.status in (404, 400)
+
+
+def test_retriever_and_memory_adapters(client: MayaMemo, project: dict) -> None:
+    from mayamemo import MayaMemoMemory, MayaMemoRetriever
+
+    client.add_memory(
+        project["id"],
+        "Deploys are blue-green via the proxy swap",
+        type="architecture",
+        tags=[RUN_TAG, "deploy"],
+    )
+
+    retriever = MayaMemoRetriever(client, project["id"], limit=5, tags=[RUN_TAG])
+    docs = retriever.invoke("how do releases go out?")
+    assert docs and "page_content" in docs[0] and "metadata" in docs[0]
+
+    memory = MayaMemoMemory(client, project["id"])
+    variables = memory.load_memory_variables({"input": f"how are deploys performed {RUN}?"})
+    assert isinstance(variables["mayamemo_context"], str)
+    assert "blue-green" in variables["mayamemo_context"]
+
+    memory.save_context(
+        {"input": "which proxy swaps traffic during an incident?"},
+        {"output": "the edge proxy does it"},
+    )
+    stored = client.search_memories(project["id"], "edge proxy swaps traffic incident")
+    assert any(m.get("type") == "discovery" for m in stored)
+    memory.clear()  # no-op by design