pi-using-hermes-memories
Share Hermes memories with Pi.
Inject MEMORY.md / USER.md into Pi and use a Hermes-compatible memory tool — memory interoperability, not soul transfer.
What this is ·
Install ·
Quick start ·
Basics ·
Settings ·
Safety notes
---
## What this is
`@keemgunn/pi-using-hermes-memories` is a [Pi](https://github.com/earendil-works/pi) coding-agent package that:
- Appends Hermes-compatible memory guidance to Pi's existing system prompt
- Injects session snapshots of `MEMORY.md` and `USER.md`
- Registers a tool named `memory` with Hermes-compatible add / replace / remove / batched `operations` behavior
**Non-goals:** this package does not transfer Hermes soul, identity, skills, or session history. Scope is **memory file interoperability** only.
## Install
Requires [Pi](https://github.com/earendil-works/pi) and Node.js `>=24`.
```bash
pi install npm:@keemgunn/pi-using-hermes-memories
```
No install lifecycle scripts. First-run config copy happens when the extension loads (see [Settings](#settings)).
## Quick start
1. Install the package (above).
2. Ensure Hermes memory files exist under the configured directory (default `~/.hermes/memories`): `MEMORY.md`, `USER.md`.
3. Start Pi. On first load the extension seeds global settings if missing and appends MEMORY / USER snapshots to the system prompt.
4. Use the `memory` tool for add / replace / remove (or batched `operations`). Check `/hermes-memory-status`; refresh the frozen snapshot with `/hermes-memory-reload` (prompt-cache-changing).
Local development from this package root:
```bash
pi -e ./extensions
```
After `pnpm run build`, you can also load the compiled entry:
```bash
pi -e ./dist/extensions/index.js
```
Use `/reload` after extension or config edits.
## Basics
- Pi keeps its normal system prompt. This package **appends** memory guidance and frozen MEMORY / USER snapshots; it does not replace Pi's base prompt, `SYSTEM.md`, skills, or other extensions.
- Snapshots load at session start and stay frozen until a new session or `/hermes-memory-reload`. Tool writes update disk immediately; the current session's prompt snapshot does not change mid-session.
- Default memory directory is `~/.hermes/memories` — the same files Hermes uses.
- Character caps come from Hermes `~/.hermes/config.yaml` (`memory.memory_char_limit`, `memory.user_char_limit`). Missing file or keys → Hermes defaults 2200 / 1375.
- Tool name is exactly `memory` (Hermes-compatible schema, `\n§\n` delimiter).
- Sibling flock locks: `MEMORY.md.lock` / `USER.md.lock`. Writes use atomic `.mem_` temp + rename.
- Memory content is threat-scanned (Hermes `strict`) before write; unsafe content is refused.
## Settings
| Item | Path / value |
| --- | --- |
| Global config | `$PI_CODING_AGENT_DIR/pi-using-hermes-memories.json` |
| Default `$PI_CODING_AGENT_DIR` | `~/.pi/agent` |
| Packaged template | `share/settings/pi-using-hermes-memories.json` |
| Project override (trusted only) | `/.pi/pi-using-hermes-memories.json` |
| Schema | `schemas/config.schema.json` |
| Hermes char caps | `$HERMES_HOME/config.yaml` or `~/.hermes/config.yaml` (`memory.memory_char_limit`, `memory.user_char_limit`) |
Minimal config:
```json
{
"$schema": "https://unpkg.com/@keemgunn/pi-using-hermes-memories/schemas/config.schema.json",
"memoryDirectory": "~/.hermes/memories"
}
```
**First run:** if the global config file is absent, the extension creates its parent directory and copies the packaged template. Existing user settings are never overwritten. Reset by deleting the global file and restarting Pi (or reinstalling and letting first-run seed again).
Resolution order: built-in defaults → global file → trusted project override. Unknown keys and malformed JSON fail closed.
## Safety notes
Installing this package grants it permission to **read and write** the configured memory files (`MEMORY.md`, `USER.md`) under `memoryDirectory`. Pi extensions run with your full filesystem permissions and are not sandboxed.
- Project overrides apply only when the project is trusted.
- Do not point `memoryDirectory` at directories you do not want the model to modify.
- Status commands never dump full memory contents by default.
- No telemetry.