From aa84960108b57274dc4322196636c5aa59ff1792 Mon Sep 17 00:00:00 2001 From: Steve Paltridge Date: Fri, 24 Apr 2026 03:05:56 -0600 Subject: [PATCH] docs: SDK launch polish + examples folder - README: PyPI + npm badges, multi-stack quickstart (curl + pip + npm) using real X-API-Key + string tags - examples/python/agent_memory.py: end-to-end remember/recall/checkpoint, validated against ghcr.io/recallworks/recall:0.1.0 - examples/typescript/agent_memory.ts: same flow, async; validated end-to-end - examples/bash/curl_round_trip.sh: SDK-free raw HTTP - examples/README.md: index --- README.md | 31 ++++++++++++++++-- examples/README.md | 34 ++++++++++++++++++++ examples/bash/curl_round_trip.sh | 29 +++++++++++++++++ examples/python/agent_memory.py | 49 +++++++++++++++++++++++++++++ examples/typescript/agent_memory.ts | 46 +++++++++++++++++++++++++++ 5 files changed, 187 insertions(+), 2 deletions(-) create mode 100644 examples/README.md create mode 100644 examples/bash/curl_round_trip.sh create mode 100644 examples/python/agent_memory.py create mode 100644 examples/typescript/agent_memory.ts diff --git a/README.md b/README.md index 856eec0..a2d4601 100644 --- a/README.md +++ b/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). --- diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..0896c5d --- /dev/null +++ b/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 +``` diff --git a/examples/bash/curl_round_trip.sh b/examples/bash/curl_round_trip.sh new file mode 100644 index 0000000..c0cc444 --- /dev/null +++ b/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 diff --git a/examples/python/agent_memory.py b/examples/python/agent_memory.py new file mode 100644 index 0000000..bca2b27 --- /dev/null +++ b/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() diff --git a/examples/typescript/agent_memory.ts b/examples/typescript/agent_memory.ts new file mode 100644 index 0000000..e1cde7f --- /dev/null +++ b/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); +});