chandra447/pi-hermes-memory

Pi Hermes Memory – Persistent, searchable memory for your Pi agent

What it is – An official Pi extension that gives the Pi assistant a durable knowledge base. It stores facts, user preferences, failure logs, and reusable procedures (called skills) across sessions, lets the agent search past conversations, and protects secrets from being persisted.

Key capabilities

Feature	What it does
Session search	Full‑text search of every prior Pi conversation via SQLite FTS5 (/session_search).
Persistent memory	Facts, preferences, and corrections are saved as markdown (MEMORY.md, USER.md) and survive restarts.
Background learning	Every 10 turns (or 15 tool calls) the extension reviews the dialogue, extracts failures, corrections, insights, and writes them to memory.
Procedural skills	The agent can create, view, patch, update, or delete reusable SKILL.md files (global or project‑scoped) through the skill_manage tool.
Secret scanning	API keys, tokens, SSH keys, etc. are automatically rejected before being written.
Two‑tier architecture	Global memory lives under ~/.pi/agent/pi-hermes-memory/; project memory lives under ~/.pi/agent/projects-memory/<project>/. Both are searchable.
Auto‑consolidation	When a markdown memory file hits its size limit, the extension runs a consolidation pass that merges or drops stale entries.
Standing instructions	A small, user‑controlled block (STANDING.md) that is injected into every session for hard‑coded directives.
Memory aging & policy	Entries carry timestamps; a configurable <memory‑policy> tells the agent when to call memory_search.

How it works

• The extension creates three main stores: MEMORY.md (facts), USER.md (profile), and a SQLite sessions.db that mirrors markdown entries for unlimited search.
• All writes pass through a content scanner that strips secrets and blocks malicious payloads.
• The agent can call specialized tools (memory_add, memory_replace, memory_remove) to manipulate memories directly, and skill_manage to handle procedural skills.
• A background review process runs periodically, extracts useful knowledge, and writes it to the appropriate store.

Installation

# From the Pi package manager
pi install npm:pi-hermes-memory
# Or directly from GitHub
pi install git:github.com/chandra447/pi-hermes-memory

You can also test locally without installing:

pi -e /path/to/pi-hermes-memory/src/index.ts

Quick start

# Index existing sessions (one‑time)
/memory-index-sessions
# Sync older markdown memories into SQLite (optional)
/memory-sync-markdown
# Learn the commands
/learn-memory-tool

Typical workflow:

1. Add a fact – memory_add → "my project codename is ZEPHYR‑7741".
2. Recall later – memory_search("ZEPHYR") or simply ask the agent.
3. Update – memory_replace to change a stale entry.
4. Delete – memory_remove if the fact is no longer relevant.
5. Create a skill – skill_manage.create with structured fields (when_to_use, procedure_steps, …).

Configuration

• memoryPolicyStyle: full, compact, custom, or none to control how much policy text is injected.
• memoryMode: legacy-inject (injects markdown into the system prompt) or policy‑only (uses SQLite query only).
• standingInstructionsEnabled: toggle the permanent <standing‑instructions> block.

Development notes

• The published npm package omits tests and TypeScript sources; clone the repo to run npm run check and npm test.
• The native addon better-sqlite3 may need a rebuild if your Node ABI differs (common on Homebrew installations).

Why it matters Without this extension Pi forgets everything when a session ends, forcing you to repeat preferences, project conventions, or past failures. Pi Hermes Memory gives the assistant a reliable, searchable “brain” that grows over time while keeping secrets safe, making long‑running or multi‑project workflows far more efficient.