All packages Compare

@skepsun/pi-loom

extension

Long-term memory plugin for pi with Dream Engine for insight generation — designed to collaborate with pi-esr

by — · v0.5.0 · published 4w ago

$ pi install npm:@skepsun/pi-loom
downloads/mo
497
stars
—
last push
—
open issues
—

Signals

license: MITtestspi manifest: missinginstall size: —deps: 0peer deps: 0

Download trend

No downloads in the last 12 weeks.

memory
npm ↗ repo ↗

README

@skepsun/pi-loom

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

与 pi-esr 松耦合设计 —— 两个插件通过不透明的 entity_id 引用和 fire-and-forget 事件协作，同时各自独立部署。

English

架构

┌─────────────┐       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 为高重要性记忆

快速开始

安装

pi add @skepsun/pi-loom

或通过 npm 安装：

npm install @skepsun/pi-loom

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

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

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

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_MODELDream Engine 使用的洞察生成模型，如 openai/gpt-4.1 或 deepseek/deepseek-v3.1。未设置时使用当前对话模型。

工具

工具说明
loom_store存储一条记忆，支持重要性、过期时间和实体锚定
loom_recall按实体、全文搜索或列出全部活跃记忆
loom_search5 信号混合搜索：关键词、语义或混合模式
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。

许可

MIT