docs: SDK launch polish + examples

README.md

@@ -7,6 +7,8 @@
 
 [![Tests](https://github.com/RecallWorks/Recall/actions/workflows/test.yml/badge.svg)](https://github.com/RecallWorks/Recall/actions/workflows/test.yml)
 [![Docker](https://github.com/RecallWorks/Recall/actions/workflows/docker.yml/badge.svg)](https://github.com/RecallWorks/Recall/actions/workflows/docker.yml)
+[![PyPI](https://img.shields.io/pypi/v/recall-client?label=pypi%3A%20recall-client&logo=pypi&logoColor=white)](https://pypi.org/project/recall-client/)
+[![npm](https://img.shields.io/npm/v/@recallworks/recall-client?label=npm%3A%20%40recallworks%2Frecall-client&logo=npm&logoColor=white)](https://www.npmjs.com/package/@recallworks/recall-client)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue?logo=python&logoColor=white)](pyproject.toml)
 [![MCP](https://img.shields.io/badge/MCP-compatible-7c3aed)](https://modelcontextprotocol.io)
@@ -34,6 +36,8 @@
 
 ## Five-minute install
 
+**1. Run the server:**
+
 ```bash
 docker run -d --name recall \
   -p 8787:8787 \
@@ -42,13 +46,36 @@ docker run -d --name recall \
   ghcr.io/recallworks/recall:latest
 ```
 
+**2. Talk to it — pick your stack:**
+
 ```bash
-curl -H "Authorization: Bearer changeme" \
+# Raw HTTP (any language)
+curl -H "X-API-Key: changeme" \
      -H "Content-Type: application/json" \
-     -d '{"content":"first memory","tags":["hello"]}' \
+     -d '{"content":"first memory","tags":"hello"}' \
      http://localhost:8787/tool/remember
 ```
 
+```python
+# Python
+pip install recall-client
+
+from recall_client import RecallClient
+with RecallClient("http://localhost:8787", api_key="changeme") as c:
+    c.remember("first memory", tags="hello")
+    print(c.recall("memory").result)
+```
+
+```ts
+// TypeScript / JavaScript (Node 18+, Bun, Deno, browser)
+npm install @recallworks/recall-client
+
+import { RecallClient } from "@recallworks/recall-client";
+const c = new RecallClient({ baseUrl: "http://localhost:8787", apiKey: "changeme" });
+await c.remember("first memory", { tags: "hello" });
+console.log((await c.recall("memory")).result);
+```
+
 Full walkthrough: [docs/quickstart.md](docs/quickstart.md).
 
 ---

examples/README.md

@@ -0,0 +1,34 @@
+# Recall examples
+
+Tiny end-to-end programs you can copy-paste. Each one assumes a Recall server running locally:
+
+```bash
+docker run -d --name recall -p 8787:8787 -e API_KEY=changeme \
+  -v recall-data:/data ghcr.io/recallworks/recall:latest
+```
+
+| Example | Stack | What it shows |
+|---|---|---|
+| [`python/agent_memory.py`](python/agent_memory.py) | Python 3.11+ | Remember session facts, recall by query, checkpoint at the end |
+| [`typescript/agent_memory.ts`](typescript/agent_memory.ts) | Node 18+ / Bun / Deno | Same flow, async client |
+| [`bash/curl_round_trip.sh`](bash/curl_round_trip.sh) | curl | Raw HTTP — no SDK needed |
+
+## Run a Python example
+
+```bash
+pip install recall-client
+python examples/python/agent_memory.py
+```
+
+## Run a TypeScript example
+
+```bash
+npm install @recallworks/recall-client
+npx tsx examples/typescript/agent_memory.ts
+```
+
+## Run the curl example
+
+```bash
+bash examples/bash/curl_round_trip.sh
+```

examples/bash/curl_round_trip.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# @wbx-modified copilot-a3f7·MTN | 2026-04-24 | raw HTTP round trip — no SDK
+#
+# Run a server first:
+#   docker run -d -p 8787:8787 -e API_KEY=changeme \
+#     -v recall-data:/data ghcr.io/recallworks/recall:latest
+
+set -euo pipefail
+
+URL="${RECALL_URL:-http://localhost:8787}"
+KEY="${RECALL_KEY:-changeme}"
+
+echo "== health =="
+curl -s "$URL/health"
+echo
+
+echo "== remember =="
+curl -s -X POST "$URL/tool/remember" \
+  -H "X-API-Key: $KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"content":"the project deadline is 2026-05-15","source":"project","tags":"deadline"}'
+echo
+
+echo "== recall =="
+curl -s -X POST "$URL/tool/recall" \
+  -H "X-API-Key: $KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"query":"when is the deadline","n":3}'
+echo

examples/python/agent_memory.py

@@ -0,0 +1,49 @@
+# @wbx-modified copilot-a3f7·MTN | 2026-04-24 | minimal Recall agent-memory example
+"""End-to-end agent memory: remember, recall, checkpoint.
+
+Run a server first:
+    docker run -d -p 8787:8787 -e API_KEY=changeme \
+        -v recall-data:/data ghcr.io/recallworks/recall:latest
+
+Then:
+    pip install recall-client
+    python agent_memory.py
+"""
+from __future__ import annotations
+
+import os
+
+from recall_client import RecallClient
+
+URL = os.environ.get("RECALL_URL", "http://localhost:8787")
+KEY = os.environ.get("RECALL_KEY", "changeme")
+
+
+def main() -> None:
+    with RecallClient(URL, api_key=KEY) as c:
+        # 0. Health
+        print("server:", c.health())
+
+        # 1. Store a few facts the agent should remember across sessions.
+        c.remember("user prefers dark mode", source="prefs", tags="ui,dark-mode")
+        c.remember("project deadline is 2026-05-15", source="project", tags="deadline")
+        c.remember("lead engineer is Jamie (jamie@example.com)", source="people", tags="contact")
+
+        # 2. Pull them back semantically.
+        hits = c.recall("when is the deadline", n=3)
+        print("\nrecall: when is the deadline")
+        print(hits.result)
+
+        # 3. End-of-session checkpoint so the next agent can pick up.
+        cp = c.checkpoint(
+            intent="onboard new agent to the project",
+            established="user prefers dark mode; deadline 2026-05-15; lead is Jamie",
+            pursuing="prepare kickoff doc draft",
+            open_questions="which team channel does Jamie use?",
+            session="e0a1",
+        )
+        print("\ncheckpoint:", cp.result.splitlines()[0])
+
+
+if __name__ == "__main__":
+    main()

examples/typescript/agent_memory.ts

@@ -0,0 +1,46 @@
+// @wbx-modified copilot-a3f7·MTN | 2026-04-24 | minimal Recall agent-memory example (TS)
+//
+// Run a server first:
+//   docker run -d -p 8787:8787 -e API_KEY=changeme \
+//     -v recall-data:/data ghcr.io/recallworks/recall:latest
+//
+// Then:
+//   npm install @recallworks/recall-client
+//   npx tsx agent_memory.ts
+
+import { RecallClient } from "@recallworks/recall-client";
+
+const URL = process.env.RECALL_URL ?? "http://localhost:8787";
+const KEY = process.env.RECALL_KEY ?? "changeme";
+
+async function main() {
+  const c = new RecallClient({ baseUrl: URL, apiKey: KEY });
+
+  // 0. Health
+  console.log("server:", await c.health());
+
+  // 1. Store a few facts the agent should remember across sessions.
+  await c.remember("user prefers dark mode", { source: "prefs", tags: "ui,dark-mode" });
+  await c.remember("project deadline is 2026-05-15", { source: "project", tags: "deadline" });
+  await c.remember("lead engineer is Jamie (jamie@example.com)", { source: "people", tags: "contact" });
+
+  // 2. Pull them back semantically.
+  const hits = await c.recall("when is the deadline", { n: 3 });
+  console.log("\nrecall: when is the deadline");
+  console.log(hits.result);
+
+  // 3. End-of-session checkpoint so the next agent can pick up.
+  const cp = await c.checkpoint({
+    intent: "onboard new agent to the project",
+    established: "user prefers dark mode; deadline 2026-05-15; lead is Jamie",
+    pursuing: "prepare kickoff doc draft",
+    openQuestions: "which team channel does Jamie use?",
+    session: "e0a1",
+  });
+  console.log("\ncheckpoint:", cp.result.split("\n")[0]);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});