diff --git a/README.md b/README.md index 4f330c5..f133445 100644 --- a/README.md +++ b/README.md @@ -457,6 +457,30 @@ The agentmemory entry is the **same MCP server block** across every host that us **Sandboxed MCP clients** (Flatpak / Snap / restrictive containers) that can't reach the host's `localhost`: also set `"AGENTMEMORY_FORCE_PROXY": "1"` in the `env` block, and point `AGENTMEMORY_URL` at a route the sandbox can actually reach (e.g. your LAN IP). See [#234](https://github.com/rohitg00/agentmemory/issues/234) for the diagnostic walkthrough. +### Programmatic access (Python / Rust / Node) + +agentmemory registers its core operations as iii functions (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Any language with an iii SDK can call them directly over `ws://localhost:49134` — no separate REST client per language. + +```bash +pip install iii-sdk # Python +cargo add iii-sdk # Rust +npm install iii-sdk # Node +``` + +```python +from iii import register_worker + +iii = register_worker("ws://localhost:49134") +iii.connect() + +iii.trigger({ + "function_id": "mem::smart-search", + "payload": {"project": "demo", "query": "how do tokens refresh"}, +}) +``` + +Worked example: [`examples/python/`](examples/python/) (quickstart + observation/recall flow). REST on `:3111` remains available for hosts without an iii runtime. + ### From source ```bash diff --git a/examples/python/README.md b/examples/python/README.md new file mode 100644 index 0000000..ea284dd --- /dev/null +++ b/examples/python/README.md @@ -0,0 +1,71 @@ +# Python usage via `iii-sdk` + +agentmemory registers its core operations as iii functions (`mem::remember`, +`mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Any +language with an iii SDK can call them directly over the WebSocket transport +on `ws://localhost:49134` — no separate REST client needed. + +This example uses the official Python SDK. + +## Install + +```bash +pip install iii-sdk +``` + +## Quickstart + +Start the agentmemory daemon (defaults to `ws://localhost:49134`, REST on +`:3111`): + +```bash +npx -y @agentmemory/agentmemory +``` + +Then from Python: + +```python +from iii import register_worker + +iii = register_worker("ws://localhost:49134") +iii.connect() + +iii.trigger({ + "function_id": "mem::remember", + "payload": { + "project": "demo", + "title": "auth-stack", + "content": "Service uses HMAC bearer tokens; refresh every 24h.", + "concepts": ["auth", "hmac", "refresh"], + }, +}) + +hits = iii.trigger({ + "function_id": "mem::smart-search", + "payload": {"project": "demo", "query": "how do tokens refresh", "limit": 5}, +}) +print(hits) +``` + +## Functions exposed + +| Function id | Purpose | Required payload | +|---|---|---| +| `mem::remember` | Save a memory | `project`, `title`, `content` | +| `mem::observe` | Hook-driven observation ingest | `hookType`, `sessionId`, `project`, `cwd`, `timestamp` | +| `mem::context` | Render context for a session under a token budget | `sessionId`, `project`, optional `budget` | +| `mem::smart-search` | Hybrid BM25 + vector + concept recall | `project`, `query`, optional `limit` | +| `mem::forget` | Delete a memory by id | `id` | + +The HTTP-trigger wrappers under `api::*` (callable via REST on `:3111`) exist +for the same operations if you need to reach the daemon from a host without an +iii runtime. Inside the iii ecosystem, calling the `mem::*` functions directly +is lower latency. + +## Files + +- `quickstart.py` — minimal save-then-search loop. +- `observe_and_recall.py` — observation ingest + context rendering at a token + budget. + +Both scripts assume the daemon is already running. diff --git a/examples/python/observe_and_recall.py b/examples/python/observe_and_recall.py new file mode 100644 index 0000000..4747bf0 --- /dev/null +++ b/examples/python/observe_and_recall.py @@ -0,0 +1,67 @@ +"""Observation ingest + context rendering at a token budget. + +Pattern: send hook-style observations during a coding session, then ask +agentmemory to render the most relevant context back at a fixed token budget. + +Prerequisites: + pip install iii-sdk + npx -y @agentmemory/agentmemory + +Run: + python examples/python/observe_and_recall.py +""" + +from datetime import datetime, timezone +from iii import register_worker + + +SESSION_ID = "py-example-session-001" +PROJECT = "demo" + + +def now_iso() -> str: + return datetime.now(timezone.utc).isoformat() + + +def main() -> None: + iii = register_worker("ws://localhost:49134") + iii.connect() + + observations = [ + ("PreToolUse", {"tool": "Bash", "command": "cargo test"}), + ("PostToolUse", {"tool": "Bash", "exit_code": 0}), + ("UserPromptSubmit", {"prompt": "refactor auth middleware to use HMAC"}), + ] + + for hook_type, data in observations: + iii.trigger( + { + "function_id": "mem::observe", + "payload": { + "hookType": hook_type, + "sessionId": SESSION_ID, + "project": PROJECT, + "cwd": "/home/user/service", + "timestamp": now_iso(), + "data": data, + }, + } + ) + + context = iii.trigger( + { + "function_id": "mem::context", + "payload": { + "sessionId": SESSION_ID, + "project": PROJECT, + "budget": 2000, + }, + } + ) + + print(f"Rendered context ({context.get('token_count', 0)} tokens):\n") + print(context.get("text", "")) + + +if __name__ == "__main__": + main() diff --git a/examples/python/quickstart.py b/examples/python/quickstart.py new file mode 100644 index 0000000..56e5ae1 --- /dev/null +++ b/examples/python/quickstart.py @@ -0,0 +1,46 @@ +"""Minimal agentmemory usage via iii-sdk. + +Prerequisites: + pip install iii-sdk + npx -y @agentmemory/agentmemory # daemon at ws://localhost:49134 + +Run: + python examples/python/quickstart.py +""" + +from iii import register_worker + + +def main() -> None: + iii = register_worker("ws://localhost:49134") + iii.connect() + + iii.trigger( + { + "function_id": "mem::remember", + "payload": { + "project": "demo", + "title": "auth-stack", + "content": "Service uses HMAC bearer tokens; refresh every 24h.", + "concepts": ["auth", "hmac", "refresh"], + }, + } + ) + + hits = iii.trigger( + { + "function_id": "mem::smart-search", + "payload": { + "project": "demo", + "query": "how do tokens refresh", + "limit": 5, + }, + } + ) + + for memory in hits.get("results", []): + print(f"[{memory.get('score', 0):.3f}] {memory.get('title')}: {memory.get('content')}") + + +if __name__ == "__main__": + main()