pi-hmem — HMEM Hybrid Memory Extension for Pi Agent

Let your Pi Agent have long-term memory and learn from experience.

A Pi extension that connects to the HMEM Server to provide:

• 🧠 Long-term memory — store and retrieve facts, experiences, and insights
• 🔍 Hybrid search — keyword + semantic vector + knowledge graph + time decay
• 🧠 Reflection engine — learns mental models from your interactions
• 🕸️ Knowledge graph — relationships between memories

Install

From npm (recommended)

pi install npm:pi-hmem

From source

pi install /path/to/pi-hmem

Or load directly

pi -e npm:pi-hmem
pi -e /path/to/pi-hmem/extensions/index.ts

Quick Start

Prerequisites

1. HMEM Server must be running. See hmem_hermes_agent for setup.

Configuration

Three configuration methods (priority high → low):

1. Environment variables (recommended)

export PIAGENT_HMEM_API_URL="http://localhost:8000"
export PIAGENT_HMEM_API_KEY="your-hmem-api-key"
export PIAGENT_HMEM_NAMESPACE="piagent"
export PIAGENT_HMEM_SHARED_NS="shared"   # optional: shared tier memory (user prefs / mental models)

2. Project config file

Create .pi-hmem.json in your project root:

{
  "apiUrl": "http://localhost:8000",
  "apiKey": "your-hmem-api-key",
  "namespace": "my-project",
  "sharedNs": "shared"
}

3. Runtime command

/hmem config set apiUrl http://localhost:8002
/hmem config set apiKey your-hmem-api-key
/hmem config set namespace piagent
/hmem config set sharedNs shared

Tiered Shared Memory (graded sharing)

Role-based memory isolation by default: each role keeps its own namespace (business memories + knowledge graph stay self-contained), while a shared tier (sharedNs) carries cross-role knowledge — user preferences, common mental models, environment layout.

• Every hmem_search also queries the sharedNs namespace (0.8× weight) when set
• Shared hits are tagged _ns / shared: true in results
• Business memories always go to your own namespace; write shared-tier content explicitly with namespace: "shared"

┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
│ lingjia  │   │   dev    │   │   wu     │   │  create  │  ← role namespaces (isolated, graph closed-loop)
└────┬─────┘   └────┬─────┘   └────┬─────┘   └────┬─────┘
     └──────────────┴──────┬──────┴──────────────┘
                    ┌──────┴──────┐
                    │   shared    │  ← prefs / mental models (queried at 0.8x)
                    └─────────────┘

Memory Hierarchy

observation ──write──→ experience ──reflect──→ insight ──aggregate──→ mental_model

Type	Description	Write
observation	Raw facts, user preferences	✅ hmem_write
experience	Structured experiences (action/context/outcome)	✅ hmem_write
insight	Patterns discovered by reflection	❌ Auto-generated only
mental_model	Abstract behavioral models	❌ Auto-generated only

⚠️ Only observation and experience can be written manually. insight and mental_model are generated exclusively by the hmem_reflect reflection engine.

Available Tools

Tool	Description
hmem_write	Store a memory (observation or experience)
hmem_search	Hybrid semantic search (FTS + vector + local HRR + graph expand) with rerank; supports min_score threshold
hmem_list	List recent memories, optionally by type
hmem_get	Get a single memory by ID
hmem_delete	Delete a memory by ID
hmem_stats	Memory statistics
hmem_reflect	Trigger reflection engine
hmem_models	List mental models and insights
hmem_graph	Knowledge graph nodes + edges
hmem_namespaces	List all namespaces
hmem_doc_import	Import a plain-text document (auto-chunked + vectorized) into a knowledge base
hmem_doc_list	List documents in a knowledge base
hmem_doc_get	Get full document content (all chunks)
hmem_doc_delete	Cascade-delete a document and all its chunks
hmem_kb_put	Add a single knowledge entry
hmem_kb_query	List knowledge entries (filter by category/doc_id/tags)
hmem_kb_categories	Knowledge base category summary
hmem_kb_create	Create/activate a knowledge base
hmem_kb_list	List all knowledge bases
hmem_kb_delete	Delete a knowledge base

Available Commands

Command	Description
/hmem	Show help
/hmem config	Show current configuration
/hmem config set <key> <value>	Set configuration
/hmem stats	Memory statistics
/hmem search <query>	Quick search (limit 5)
/hmem list [type]	List memories
/hmem models	List mental models
/hmem reflect	Trigger reflection
/hmem namespaces	List namespaces
/hmem kb list	List knowledge bases
/hmem kb create <ns>	Create a knowledge base
/hmem kb delete <ns>	Delete a knowledge base
/hmem doc list	List documents in default namespace
/hmem doc get <id>	Get document detail
/hmem doc delete <id>	Delete document

Namespace

Default namespace is piagent-default. Each namespace maps to an independent SQLite database.

• Same namespace → shared memory across sessions/agents
• Different namespace → complete isolation

Multi-Agent Support

Multiple Pi agents using the same namespace will share memories and mental models — enabling collaborative learning.

Architecture

Pi Agent ──HTTP──▶ HMEM Server (FastAPI)
                     │
              /api/v1/memories
              /api/v1/search
              /api/v1/stats
              /api/v1/reflect
              /api/v1/mental-models
              /api/v1/graph
              /api/v1/namespaces
              /api/v1/documents         ← knowledge base docs
              /api/v1/knowledge          ← knowledge entries
              /api/v1/knowledge-bases    ← library management
                     │
              ┌──────┴──────┐
              │ namespace-  │
              │   db.db     │
              └─────────────┘

Memory Lifecycle

hmem_write (observation / experience)
        │
        ▼
  hmem_reflect
  ┌─ Accumulate experiences ─┐
  │   LLM clustering         │
  └─→ insights ─→ mental models
        │
        ▼
  hmem_search / auto-prefetch
  ←─ Patterns guide behavior

Memory Prefetch

The extension auto-fetches relevant memories before each turn based on the user's message content, injecting up to 3 relevant memories into the context. When sharedNs is configured, shared-tier memories are merged into the results at 0.8× weight.

Version History

Version	Date	Notes
0.3.0	2026-08-26	Knowledge base support: document import/CRUD, knowledge entries, library management (10 new tools)
0.2.1	2026-08-25	README: tiered-shared-memory docs, v0.2.0 notes
0.2.0	2026-08-25	Tiered shared memory (sharedNs), min_score threshold, HRR local holographic retrieval integration
0.1.0	2026-08-05	Initial release: 10 tools, 10 commands, reflection integration, auto-prefetch

License

MIT