# @remnic/hermes-provider

> Typed HTTP client for the Remnic memory API

Latest version **9.69.56** (published 2026-08-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install @remnic/hermes-provider
pnpm add @remnic/hermes-provider
yarn add @remnic/hermes-provider
bun add @remnic/hermes-provider
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 9.69.56 |
| Published | 2026-08-26 |
| First published | 2026-04-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 44.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 204 |
| Maintainers | joshuaswarren |
| Keywords | remnic, memory, ai, agent, openclaw |

## Links

- npm: https://www.npmjs.com/package/@remnic/hermes-provider
- Repository: https://github.com/joshuaswarren/remnic
- Homepage: https://github.com/joshuaswarren/remnic#readme
- Issues: https://github.com/joshuaswarren/remnic/issues
- npm.io page: https://npm.io/package/@remnic/hermes-provider

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 9.69.56 (latest) — 2026-08-26
- 10.0.5 (alpha) — 2026-10-19
- 10.0.4 — 2026-10-19
- 10.0.3 — 2026-10-15
- 10.0.2 — 2026-10-12
- 10.0.1 — 2026-10-11
- 10.0.0 — 2026-10-11
- 9.69.105 — 2026-10-10
- 9.69.104 — 2026-10-10
- 9.69.103 — 2026-10-10
- 9.69.102 — 2026-10-10
- 9.69.101 — 2026-10-10
- 9.69.100 — 2026-10-10
- 9.69.99 — 2026-10-10
- 9.69.98 — 2026-10-10
- … 584 more at https://npm.io/package/@remnic/hermes-provider/versions

## README

# @remnic/hermes-provider

Typed TypeScript HTTP client for a remote [Remnic](https://github.com/joshuaswarren/remnic)
memory daemon. Wraps the Remnic HTTP API (`/engram/v1/*`) with a small, fully
typed `HermesClient` — recall, observe, store, entity/memory browse, and LCM
search — plus built-in retries, timeouts, and structured errors.

Use this when you are building a service or agent in TypeScript/JavaScript that
talks to a Remnic daemon over HTTP and you want types and retry handling instead
of hand-rolled `fetch` calls.

## Install

```bash
npm install @remnic/hermes-provider
```

## Usage

```ts
import { HermesClient } from "@remnic/hermes-provider";

const client = new HermesClient({
  baseUrl: "http://127.0.0.1:4318",
  authToken: "${REMNIC_AUTH_TOKEN}",
});

// Verify the daemon is reachable.
await client.health();

// Recall memories for a query.
const { context } = await client.recall("what did I decide about the schema?");

// Buffer a conversation turn for extraction.
await client.observe("session-1", [
  { role: "user", content: "We are switching the store to markdown files." },
  { role: "assistant", content: "Understood — local-first it is." },
]);

// Store an explicit memory.
await client.store({ content: "Team prefers short release notes." });
```

## Client options

`new HermesClient(options)` accepts:

| Option | Default | Description |
| --- | --- | --- |
| `baseUrl` | required | Base URL of the Remnic daemon, e.g. `http://127.0.0.1:4318`. |
| `authToken` | required | Bearer token for the daemon. |
| `namespace` | unset | Default namespace applied to requests. |
| `sessionKey` | unset | Default session key applied to requests. |
| `maxRetries` | `3` | Retry budget for retryable failures (5xx, 429, read POSTs). |
| `retryBaseDelayMs` | `100` | Base delay for exponential backoff. |
| `timeoutMs` | `5000` | Per-request timeout (via `AbortController`). |

## Methods

- `health()` — daemon health probe.
- `recall(query, options?)` — semantic recall; `options` covers `topK`, `mode`,
  `namespace`, `sessionKey`, `includeDebug`, `idempotencyKey`.
- `observe(sessionKey, messages, options?)` — buffer conversation turns for
  extraction.
- `store(request)` / `submitSuggestion(request)` — write a memory directly, or
  queue one for review.
- `getEntities(options?)` / `getEntity(name, options?)` — browse tracked entities.
- `getMemories(options?)` / `getMemory(id, options?)` — browse stored memories.
- `lcmSearch(query, options?)` — search the Lossless Context Management archive.

All response and option types are exported from the package.

## Behavior

- **Retries** use exponential backoff on 5xx and read-only POSTs. 429 responses
  honor a numeric `Retry-After` header. State-mutating writes are not retried
  unless you pass an `idempotencyKey`, so a lost response never duplicates a write.
- **Errors** throw a typed `HermesError` carrying `status`, `code`, `message`, and
  optional field-level `details`. A 404 on `getEntity`/`getMemory` resolves to
  `{ found: false }` rather than throwing.

The `/engram/v1/*` request paths are Remnic's stable HTTP API surface, kept under
the `engram` prefix for compatibility.

## Links

- HTTP API reference: [docs/api.md](https://github.com/joshuaswarren/remnic/blob/main/docs/api.md)
- Monorepo: [github.com/joshuaswarren/remnic](https://github.com/joshuaswarren/remnic)

## License

MIT

---
_Source: https://npm.io/package/@remnic/hermes-provider · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._