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.
