@remnic/hermes-provider 9.6.24 → 9.6.26
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +92 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# @remnic/hermes-provider
|
|
2
|
+
|
|
3
|
+
Typed TypeScript HTTP client for a remote [Remnic](https://github.com/joshuaswarren/remnic)
|
|
4
|
+
memory daemon. Wraps the Remnic HTTP API (`/engram/v1/*`) with a small, fully
|
|
5
|
+
typed `HermesClient` — recall, observe, store, entity/memory browse, and LCM
|
|
6
|
+
search — plus built-in retries, timeouts, and structured errors.
|
|
7
|
+
|
|
8
|
+
Use this when you are building a service or agent in TypeScript/JavaScript that
|
|
9
|
+
talks to a Remnic daemon over HTTP and you want types and retry handling instead
|
|
10
|
+
of hand-rolled `fetch` calls.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npm install @remnic/hermes-provider
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Usage
|
|
19
|
+
|
|
20
|
+
```ts
|
|
21
|
+
import { HermesClient } from "@remnic/hermes-provider";
|
|
22
|
+
|
|
23
|
+
const client = new HermesClient({
|
|
24
|
+
baseUrl: "http://127.0.0.1:4318",
|
|
25
|
+
authToken: "${REMNIC_AUTH_TOKEN}",
|
|
26
|
+
});
|
|
27
|
+
|
|
28
|
+
// Verify the daemon is reachable.
|
|
29
|
+
await client.health();
|
|
30
|
+
|
|
31
|
+
// Recall memories for a query.
|
|
32
|
+
const { context } = await client.recall("what did I decide about the schema?");
|
|
33
|
+
|
|
34
|
+
// Buffer a conversation turn for extraction.
|
|
35
|
+
await client.observe("session-1", [
|
|
36
|
+
{ role: "user", content: "We are switching the store to markdown files." },
|
|
37
|
+
{ role: "assistant", content: "Understood — local-first it is." },
|
|
38
|
+
]);
|
|
39
|
+
|
|
40
|
+
// Store an explicit memory.
|
|
41
|
+
await client.store({ content: "Team prefers short release notes." });
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Client options
|
|
45
|
+
|
|
46
|
+
`new HermesClient(options)` accepts:
|
|
47
|
+
|
|
48
|
+
| Option | Default | Description |
|
|
49
|
+
| --- | --- | --- |
|
|
50
|
+
| `baseUrl` | required | Base URL of the Remnic daemon, e.g. `http://127.0.0.1:4318`. |
|
|
51
|
+
| `authToken` | required | Bearer token for the daemon. |
|
|
52
|
+
| `namespace` | unset | Default namespace applied to requests. |
|
|
53
|
+
| `sessionKey` | unset | Default session key applied to requests. |
|
|
54
|
+
| `maxRetries` | `3` | Retry budget for retryable failures (5xx, 429, read POSTs). |
|
|
55
|
+
| `retryBaseDelayMs` | `100` | Base delay for exponential backoff. |
|
|
56
|
+
| `timeoutMs` | `5000` | Per-request timeout (via `AbortController`). |
|
|
57
|
+
|
|
58
|
+
## Methods
|
|
59
|
+
|
|
60
|
+
- `health()` — daemon health probe.
|
|
61
|
+
- `recall(query, options?)` — semantic recall; `options` covers `topK`, `mode`,
|
|
62
|
+
`namespace`, `sessionKey`, `includeDebug`, `idempotencyKey`.
|
|
63
|
+
- `observe(sessionKey, messages, options?)` — buffer conversation turns for
|
|
64
|
+
extraction.
|
|
65
|
+
- `store(request)` / `submitSuggestion(request)` — write a memory directly, or
|
|
66
|
+
queue one for review.
|
|
67
|
+
- `getEntities(options?)` / `getEntity(name, options?)` — browse tracked entities.
|
|
68
|
+
- `getMemories(options?)` / `getMemory(id, options?)` — browse stored memories.
|
|
69
|
+
- `lcmSearch(query, options?)` — search the Lossless Context Management archive.
|
|
70
|
+
|
|
71
|
+
All response and option types are exported from the package.
|
|
72
|
+
|
|
73
|
+
## Behavior
|
|
74
|
+
|
|
75
|
+
- **Retries** use exponential backoff on 5xx and read-only POSTs. 429 responses
|
|
76
|
+
honor a numeric `Retry-After` header. State-mutating writes are not retried
|
|
77
|
+
unless you pass an `idempotencyKey`, so a lost response never duplicates a write.
|
|
78
|
+
- **Errors** throw a typed `HermesError` carrying `status`, `code`, `message`, and
|
|
79
|
+
optional field-level `details`. A 404 on `getEntity`/`getMemory` resolves to
|
|
80
|
+
`{ found: false }` rather than throwing.
|
|
81
|
+
|
|
82
|
+
The `/engram/v1/*` request paths are Remnic's stable HTTP API surface, kept under
|
|
83
|
+
the `engram` prefix for compatibility.
|
|
84
|
+
|
|
85
|
+
## Links
|
|
86
|
+
|
|
87
|
+
- HTTP API reference: [docs/api.md](https://github.com/joshuaswarren/remnic/blob/main/docs/api.md)
|
|
88
|
+
- Monorepo: [github.com/joshuaswarren/remnic](https://github.com/joshuaswarren/remnic)
|
|
89
|
+
|
|
90
|
+
## License
|
|
91
|
+
|
|
92
|
+
MIT
|