@keemgunn/pi-using-hermes-memories

---

What this is

@keemgunn/pi-using-hermes-memories is a 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 and Node.js >=24.

pi install npm:@keemgunn/pi-using-hermes-memories

No install lifecycle scripts. First-run config copy happens when the extension loads (see 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:

pi -e ./extensions

After pnpm run build, you can also load the compiled entry:

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)	<cwd>/.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:

{
  "$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.