docs(python): iii-sdk example replaces standalone REST client (#364)
Closes #342. agentmemory functions register as mem::remember, mem::observe, mem::context, mem::smart-search, mem::forget via sdk.registerFunction. iii-sdk already ships in Python, Rust, and Node — any of them can call those functions directly over the iii WebSocket transport. A standalone Python REST client would duplicate the transport layer and fragment the cross-language story. This patch adds: - examples/python/quickstart.py — minimal save + smart-search loop. - examples/python/observe_and_recall.py — observation ingest + context rendering at a token budget. - examples/python/README.md — function map + install + usage. - README "Programmatic access (Python / Rust / Node)" section pointing at the example and the three SDK install commands. REST on :3111 is unchanged for hosts without an iii runtime.
This commit is contained in:
Rohit Ghumare
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -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()
|
||||
@@ -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()
|
||||
Reference in New Issue
Block a user