# @skepsun/pi-loom

适用于 **pi** 编码代理框架的极简记忆插件。提供带自动过期的时序记忆存储、实时召回，以及通过 LLM 驱动的模式发现从记忆生成洞察的 Dream Engine。

**与 [pi-esr](https://github.com/skepsun/pi-esr) 松耦合设计** —— 两个插件通过不透明的 entity_id 引用和 fire-and-forget 事件协作，同时各自独立部署。

[English](./README.md)

---

## 架构

```
┌─────────────┐       entity_id（不透明字符串）        ┌─────────────┐
│   pi-esr    │ ←──────────────────────────────────→ │   @skepsun/pi-loom   │
│   状态图      │       tool_result hook 事件           │   记忆流      │
└─────────────┘                                       └─────────────┘
  任务 · 实体                                            记忆 · 洞察
  关系 · 状态机                                          重要性 · 过期
  闭包验证                                               Dream Engine
```

两个独立插件、两种独立数据模型、两个独立数据库。唯一的耦合点是自动捕获 ESR 任务完成事件写入记忆的 fire-and-forget 事件钩子。

---

## 特性

| 特性 | 说明 |
|------|------|
| **时序记忆** | 存储观察、决策、事实，支持重要性(0–1)、可选过期时间、标签 |
| **实体锚定** | 将记忆绑定到 pi-esr 的 entity_id 以支持按范围召回 |
| **实时召回** | 按实体查询、全文搜索、或列出所有活跃记忆 |
| **Dream Engine** | 多阶段洞察生成：加权采样 → 冲突检测 → 随机打乱 → LLM 提炼 |
| **洞察管理** | Agent 可以随着理解的深入更新或删除已有洞察 |
| **归档** | 从活跃池中移除记忆但保留在库中 |
| **自动过期** | 带 expire_at 的记忆到期自动清理 |
| **上下文注入** | `[PI_LOOM]` 块注入到 agent 系统提示中——格式稳定以命中前缀缓存 |
| **ESR 协作** | 自动捕获 `esr_promote_task → stable` 为高重要性记忆 |

---

## 快速开始

### 安装

```bash
pi add @skepsun/pi-loom
```

或通过 npm 安装：

```bash
npm install @skepsun/pi-loom
```

插件随 pi 启动自动激活，基础使用无需配置。

Codex 和 Claude Code 也可以通过随包发布的原生 hooks 直接获得 `[PI_LOOM]` 上下文注入，并在工具调用后自动捕获低成本编码信号。该路径不启动常驻 worker，hook 进程直接读写本地 SQLite；MCP 仍用于显式召回、存储和审查。

`pi-loom` 仍保持为 MCP stdio server，避免破坏已有配置；本地操作面使用 `pi-loom-cli`：

```bash
pi-loom-cli doctor
pi-loom-cli status --json
pi-loom-cli context --max-total-chars 1200
pi-loom-cli search "release procedure" --limit 5
pi-loom-cli store "发布前运行 retrieval precision" --importance 0.8 --tags procedure
pi-loom-cli install codex
```

CLI 不启动常驻 worker，也不会自动修改 `~/.claude` / `~/.codex` 配置；安装命令只打印最小接入指引。

### 配置

| 环境变量 | 用途 |
|----------|------|
| `PI_LOOM_DIR` | 覆盖数据目录（默认：项目根目录下的 `.pi-loom/`） |
| `PI_LOOM_CODEX_HOOK_DISABLE` / `PI_LOOM_CLAUDE_HOOK_DISABLE` | 设为 `true` 时分别关闭 Codex / Claude Code 原生 hooks，MCP 和服务模式不受影响 |
| `PI_LOOM_HOOK_DISABLE` | 设为 `true` 时关闭所有原生 agent hooks |
| `PI_LOOM_CODEX_MAX_TOKENS` / `PI_LOOM_CLAUDE_MAX_TOKENS` | 控制原生 hook 注入上下文的预算 |
| `PI_LOOM_HOOK_SCOPE_TYPE` / `PI_LOOM_HOOK_SCOPE_ID` | 原生 hook 注入时的共享 scope 过滤 fallback |
| `PI_DREAM_MODEL` | Dream Engine 使用的洞察生成模型，如 `openai/gpt-4.1` 或 `deepseek/deepseek-v3.1`。未设置时使用当前对话模型。 |

---

## 工具

| 工具 | 说明 |
|------|------|
| `loom_store` | 存储一条记忆，支持重要性、过期时间和实体锚定 |
| `loom_recall` | 按实体、全文搜索或列出全部活跃记忆 |
| `loom_search` | 5 信号混合搜索：关键词、语义或混合模式 |
| `loom_detail` | 按 ID 查看一条记忆的完整内容 |
| `loom_timeline` | 查看某个实体的时间线 |
| `loom_episode` | 查看完整会话摘要：决策、错误、变更、未完成事项 |
| `loom_dream` | 运行 Dream Engine 从记忆中生成洞察 |
| `loom_insights` | 查看已生成的洞察，可按实体过滤 |
| `loom_manage_insight` | 更新或删除已有洞察 |
| `loom_extract` | 从记忆中提取原子事实 |
| `loom_consolidate` | 合并反复出现的潜意识记忆 |
| `loom_link` | 在两个实体之间创建带类型的关系 |
| `loom_related` | 列出与某个实体相关的实体 |
| `loom_graph` | 从某个实体开始做 BFS 图遍历 |
| `loom_audit` | 查看原始工具事件日志 |
| `loom_summarize_session` | 为会话生成 LLM 摘要 |
| `loom_stats` | 查看记忆统计 |
| `loom_status` | 轻量级会话状态检查 |
| `loom_constrain` | 创建路径条件约束 |
| `loom_check_path` | 检查运行时护栏违规 |
| `loom_offload` | 将大文本卸载到外部文件，返回 `[REF:node_id]` |
| `loom_offload_recall` | 按 node_id 取回卸载内容 |
| `loom_mermaid` | 从卸载的会话引用生成 Mermaid 任务图 |
| `loom_context` | 构建 `[PI_LOOM]` 上下文注入块 |
| `loom_profile` | 生成或查看实体画像 |
| `loom_setup` | 会话初始化：检查 DB 与 embedding 配置 |
| `loom_evidence` | 基于来源引用的查询时证据提炼 |
| `loom_views` | 从 MemoryNode 导出只读 Markdown 视图 |

推荐默认路径：`loom_setup` → `loom_recall`/`loom_context` → `loom_review` → `loom_apply`。其他工具只在需要事实提取、合并、画像、卸载或图遍历时使用。

---

## Dream Engine（梦境引擎）

Dream Engine 通过四步管线生成洞察：

1. **加权采样** —— 按重要性(70%) × 时间新鲜度(30%) 指数衰减采样
2. **冲突检测** —— 找出相互矛盾的记忆对（如同实体上的 task-started ↔ task-completed）
3. **随机打乱** —— 消除位置偏差
4. **LLM 提炼** —— 生成简洁、可操作的洞察并附带支持记忆引用

洞察存储于独立表中，**不**回流到记忆池——防止回声效应，同时保持在 agent 上下文中可见。

**触发时机**：系统提示在活跃记忆达到 10+ 时提示可运行 `loom_dream`。也可手动触发或配置自动触发。

---

## 设计原则

- **独立且能完美协作** —— Loom 和 ESR 各自独立可用，通过不透明 ID 协作
- **统一记忆图** —— facts、decisions、procedures、handoffs、profiles、insights 都是 MemoryNode
- **克制的设计** —— 无全局索引、无自动跨项目同步、过期作为核心机制
- **上下文格式稳定** —— 确定性 `[PI_LOOM]` 块以命中 LLM 前缀缓存
- **杜绝回声循环** —— 洞察为只输出产品，Dream Engine 仅采样原始记忆
- **仅追加记忆** —— 语义不可变（归档而不删除）

### Memory Graph Runtime

pi-loom 保持一套极简架构：`memories` 表是 MemoryNode，`memory_edges` 表是 MemoryEdge，procedures、handoffs、profiles、insights、decisions 都只是同一张表上的视图。

`loom_review` 基于同一套图模型产生 merge、supersede、contradicts、promote-to-procedure 等维护提案。它只提出建议；只有显式调用 `loom_apply` 才会修改记忆或写入 MemoryEdge。

`loom_views(scope_type, scope_id)` 会在 `.pi-loom/views/` 下导出确定性的 Markdown 投影：`index.md`、`procedures.md`、`handoffs.md`、`decisions.md`、`profiles.md`、`insights.md`、`edges.md`。这些文件只用于检查和交接；SQLite 仍然是唯一事实源。

当前改进边界和后续顺序见 [Memory Graph Runtime Roadmap](./docs/memory-graph-runtime.md)。

---

## 许可

MIT