Metadata-Version: 2.4
Name: memclaw-client
Version: 0.3.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 + Cursor adapter

Installing this package also provides the `memclaw-interviewer` CLI: the
MemClaw Interviewer's disk-parser adapter for Claude Code and Cursor
workstations. It reads agent session transcripts **read-only** — Claude
Code's `~/.claude/projects/…/*.jsonl` or Cursor's
`~/.cursor/projects/…/agent-transcripts/…/*.jsonl` — 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
memclaw-interviewer run --harness cursor        # harvest Cursor instead (or
                                                # MEMCLAW_INTERVIEWER_HARNESS=cursor)
```

**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 the harness's session-end hook so a
session is interviewed the moment it ends (a failed harvest never fails
the session — the hook always exits 0). The SAME hook command serves both
harnesses: each sends `transcript_path` on stdin, and the harness is
inferred from the path shape.

Claude Code (`~/.claude/settings.json`):
```json
{ "hooks": { "SessionEnd": [ { "hooks": [
  { "type": "command", "command": "memclaw-interviewer hook", "timeout": 300 }
] } ] } }
```

Cursor (`~/.cursor/hooks.json`):
```json
{ "version": 1, "hooks": {
  "sessionEnd": [ { "command": "memclaw-interviewer hook" } ]
} }
```

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
