---
name: piagent-hmem
description: |
  HMEM long-term memory skill with semantic search, knowledge graph, and
  reflection engine that learns mental models from experience. Manage
  memories (observations/experiences), search past interactions, and
  trigger reflection to discover insights automatically.
---

# piagent-hmem — HMEM Memory Skill

Use this skill when the user asks about memory, past experiences, or when you need to recall information from previous interactions. The HMEM extension provides long-term memory with semantic search, knowledge graph, and a reflection engine that learns mental models from experience.

## Behavior

### On Session Start

- The extension connects to the HMEM server and displays connection status.
- A memory stats summary is injected into the system prompt so you know the memory landscape.

### During Conversation

- **Before each turn**, relevant memories are auto-prefetched based on the user's prompt and injected as system context.
- **Use `hmem_search`** to find relevant past experiences before answering questions.
- **Use `hmem_write`** to store important facts, decisions, and outcomes.
- **Use `hmem_models`** to check learned mental models before adapting your style.

### Memory Hierarchy (逐级升级)

```
observation ──写入──→ 经验积累 ──→ reflection ──→ insight ──→ 聚合 ──→ mental_model
```

- `observation` — 原始事实/偏好（手动写入）
- `experience` — 结构化经历（手动写入，含 action/context/outcome）
- `insight` — 反思引擎从经验中自动发现的模式（**不能手动写入**）
- `mental_model` — 多个 insight 聚合成的心智模型（**不能手动写入**）

> ⚠️ **只允许手动写入 `observation` 和 `experience`**。`insight` 和 `mental_model` 只能通过 `hmem_reflect` 触发反思引擎自动生成。

### Mental Models

When the reflection engine runs, it clusters experiences into insights, then insights into mental models. These capture:

- User preferences (e.g., "prefers detailed technical explanations with code samples")
- Workflow patterns (e.g., "uses TDD for new features")
- Common pitfalls and solutions

Check `hmem_models` periodically to stay aligned with learned patterns.

## Knowledge Base (知识库)

HMEM 支持知识库角色：文档级导入/生命周期管理 + 知识条目标签分类，检索命中带 `source` 溯源。

- **库级**：`hmem_kb_create`（建库，独立 namespace）、`hmem_kb_list`、`hmem_kb_delete`
- **文档级**：`hmem_doc_import`（纯文本自动分块向量化，同 doc_id 覆盖）、`hmem_doc_list`、`hmem_doc_get`（含全部 chunks）、`hmem_doc_delete`（级联）
- **条目级**：`hmem_kb_put`（单条知识，可带 category/doc_id）、`hmem_kb_query`（按 category/doc_id/tags 过滤）、`hmem_kb_categories`（分类汇总）
- 知识条目不参与时间衰减、不参与 auto_reflect（保真）；`hmem_search` 命中知识条目时返回 `source`（doc_id/title/chunk_index）便于引用

## When to Write Memories

- After completing a task, write the outcome as an **experience** (with action/context/outcome).
- When the user states a preference or workflow rule, write it as an **observation**.
- **Do NOT** manually write insights or mental models — those are generated by reflection.
- After accumulating experiences, periodically run `hmem_reflect` to discover insights.

## When to Search Memories

- Before answering a complex question, search for relevant past experiences.
- When the user references "last time" or "the previous issue", search for context.
- When adapting your style, check mental models first.

## Example Flow

```
1. User: "Remember how I like my API docs?"
2. → hmem_models → finds mental model: "prefers OpenAPI 3.1 with curl examples"
3. → hmem_search "API documentation style" → confirms past experiences
4. → Write new observation to reinforce the pattern
5. → Generate docs matching the learned style
```