@chendpoc/pi-memory 0.2.0 → 0.2.1

package/doc/README-zh.md

@@ -0,0 +1,365 @@
+# @chendpoc/pi-memory
+
+<p align="center">
+  <a href="../README.md">English</a> |
+  <a href="README-zh.md">简体中文</a>
+</p>
+
+Pi coding agent 的跨 session 情景记忆扩展。
+
+`pi-memory` 给 Pi 增加一层本地、可审计的跨 session 记忆。它把长期事实保存在 **`MEMORY.md` 这个 Ground Truth** 里，把 `memory.vec.sqlite` 作为派生向量索引，并在主模型回答前通过 Preflight 注入相关的私有上下文。
+
+## 这个 Package 做什么
+
+Pi 已经有长 session compaction，它解决的是“当前对话太长了怎么办”；但它不解决“新开 session 后忘记用户偏好、项目约定、历史决策和未完成 TODO”的问题。
+
+`pi-memory` 补的是这条链路：
+
+```text
+长期事实 -> MEMORY.md -> 派生向量索引 -> 每轮 Preflight 召回
+```
+
+它提供：
+
+- 通过 `/remember` 写入显式记忆。
+- 从 Pi compaction 自动导出长期事实。
+- 用 Shutdown Queue 补捞短 session 或漏处理 session。
+- 在主模型运行前做每轮私有记忆召回。
+- 用 Markdown 保存人类可编辑的事实，向量搜索只是可重建索引。
+- 离线 maintenance 负责 consolidate、去重、overflow 处理和 queue drain。
+
+## 安装与启用
+
+要求：
+
+- Node.js `>=24 <25`
+- pnpm
+- Pi 提供的 extension runtime packages
+
+在 Pi extension 环境中安装包：
+
+```bash
+pnpm add @chendpoc/pi-memory
+```
+
+从本仓库本地开发：
+
+```bash
+pnpm install
+pnpm build
+pnpm typecheck
+pnpm test
+```
+
+通过 Pi 的 extension 加载机制启用。本包声明：
+
+```json
+{
+  "pi": {
+    "extensions": ["./src/pi-extension.ts"]
+  }
+}
+```
+
+需要时可显式初始化记忆：
+
+```bash
+pi-memory init
+```
+
+初始化不会覆盖非空 `MEMORY.md`。
+
+## 为什么选择 `pi-memory`
+
+### Agent 使用前后差异
+
+| 场景 | 未使用 `pi-memory` | 使用 `pi-memory` 后 |
+| --- | --- | --- |
+| 新 session 问“继续上次计划” | Agent 只能追问上下文，或基于当前仓库猜测。 | Preflight 召回匹配的 `MEMORY.md` 事实并注入私有参考上下文。 |
+| 用户说“记住这个 repo 用 Vitest” | 事实可能只留在当前 session 摘要里。 | `/remember` 写入 `[user]` 条目，consolidate 必须保留。 |
+| 长 session 触发压缩 | Compaction 只帮助当前 session 续聊，不必然产生跨 session 事实。 | 一次 dual-purpose summary 同时保留当前上下文并导出长期事实。 |
+| 启动 subagent | 可能重复父 session 的召回和记忆写入。 | Subagent 只拿 Memory Cap，只写新增 Compact Delta。 |
+| 向量 sidecar 不可用 | 如果是硬依赖，会直接影响对话。 | Preflight 静默回退到 Markdown 或空注入，主模型照常运行。 |
+| 记忆持续增长 | 文件容易变成无边界流水账。 | `MEMORY.md` 150 行上限，`auto-*.md` 溢出，consolidate 合并去重。 |
+
+### 核心优势
+
+- **Markdown Ground Truth**：`MEMORY.md` 和 `auto-*.md` 可以直接打开、审查、编辑、grep、复制或纳入版本控制。
+- **索引不是隐藏事实源**：`memory.vec.sqlite` 可以删除，并从 Markdown 重新构建。
+- **Preflight 召回**：记忆在主模型回答前注入，而不是依赖模型主动调用搜索工具。
+- **热路径有预算**：默认 Preflight 预算是 **800ms**，QueryIntent、sidecar query 和 fallback 都有边界。
+- **用户显式记忆受保护**：`/remember` 写入 `[user]` 条目，consolidate 不能删除或改写。
+- **Sidecar 隔离**：embedding、向量扫描、MMR、stats 和 reindex 在扩展进程外运行；写入仍由 `MemoryStore` 负责。
+- **Subagent 策略**：root session 跑 Memory Cap + Episodic Preflight；subagent 默认只拿 Memory Cap。
+- **优雅降级**：sidecar 召回为空、超时或不可用时，当前 turn 仍然继续。
+
+### 对比
+
+`pi-memory` 不试图成为所有 memory 系统的集合。它的价值是一个 Pi-native 闭环：Markdown ground truth、Preflight 注入、sidecar 检索、compaction export 和离线 maintenance。
+
+| 系统 | 优势 | 与 `@chendpoc/pi-memory` 的差异 |
+| --- | --- | --- |
+| Cursor Rules / OpenCode `AGENTS.md` | 静态项目指令，注入行为可预测。 | 主要是用户手写规则，没有自动长期事实提取，也没有每轮 Episodic Preflight。 |
+| Claude Code Auto Memory | Agent 可以写本地记忆文件。 | 也是文件记忆，但没有 sidecar 向量召回，也没有 Pi compact/shutdown 集成。 |
+| `pi-hermes-memory` | 功能丰富，有 FTS5、失败记忆、纠正学习、安全扫描。 | 自动化更重；但没有 `<private_memory>` Preflight 闭环，也没有 sidecar 派生向量索引。 |
+| OpenClaw memory-core | 成熟的文件+索引设计，有 dreaming、混合搜索、本地 embedding。 | OpenClaw 是更大的 memory 平台；`pi-memory` 更窄，聚焦 Pi extension。 |
+| Mem0 / Zep | 托管 memory API，有混合搜索、图和时序建模。 | 检索基础设施更强，但更偏外部服务/数据库，不以 Markdown 事实源为第一原则。 |
+| Letta | 上下文工程，git-backed memory repo 和 sleep-time compute。 | 自主记忆管理更强，但心智模型比 Pi extension lifecycle 更重。 |
+| Cognee | 知识引擎，图/向量/关系存储和多种检索模式。 | 更适合知识图谱；对轻量编码 agent 偏好/约定来说偏重。 |
+
+其他系统更强的地方：
+
+- `pi-hermes-memory`：失败记忆、纠正检测、工具怪癖、安全扫描。
+- OpenClaw：dreaming 阶段、memory wiki、FTS/vector 混合搜索、本地 embedding provider。
+- Zep/Cognee：时序图推理和多跳图检索。
+- Mem0：托管多租户 memory API。
+- Letta：自主 context repository 和 sleep-time memory work。
+
+## 工作方式
+
+### 架构
+
+```text
+Pi 扩展进程
+  |- session_start
+  |    |- 初始化 MEMORY.md
+  |    |- 启动/warm sidecar
+  |    |- 重建派生向量索引
+  |    `- 预加载 Memory Cap
+  |
+  |- before_agent_start / context
+  |    `- Preflight recall -> <private_memory> 注入
+  |
+  |- /remember
+  |    `- 追加 [user] Memory Entry
+  |
+  |- session_before_compact / session_compact
+  |    `- dual-purpose summary -> Memory Export ingest
+  |
+  |- session_shutdown
+  |    `- 只追加 shutdown 元数据
+  |
+  `- consolidate scheduler
+       `- 合并/去重 -> 重写 Ground Truth -> reindex
+
+通过 UDS JSONL 通信的 Sidecar 进程
+  |- ping
+  |- stats
+  |- query: embed -> cosine scan -> MMR
+  `- reindex: upsert chunks into memory.vec.sqlite
+```
+
+### 读取路径
+
+Root session：
+
+```text
+来自 Ground Truth 的 Memory Cap
+  + 当前用户消息的 Episodic Preflight
+  -> 合并为 <private_memory>
+```
+
+Subagent session：
+
+```text
+只使用 Memory Cap
+  -> 默认不跑 episodic QueryIntent / sidecar query
+```
+
+回退链：
+
+```text
+Sidecar 结果
+  -> 空结果、错误或超时：回退到 MEMORY.md
+  -> 仍为空：不注入
+```
+
+### 写入路径
+
+| 路径 | 触发 | LLM? | 是否阻塞 | 目的 |
+| --- | --- | --- | --- | --- |
+| `/remember` | 用户命令 | 否 | 是 | 显式长期记忆 |
+| Compaction | `session_before_compact` + `session_compact` | 一次摘要调用 | 摘要阻塞，入库后台执行 | 当前 session 续聊 + 导出长期事实 |
+| Shutdown Queue | `session_shutdown` + `pi-memory maintenance` | 仅离线且无 compaction summary 时 | shutdown 时不阻塞 | 补捞短 session 或漏处理事实 |
+| Consolidate | overflow >= 12、7 天或每日 cron | 可选 | 离线或后台 | 去重、合并、清理过期 TODO |
+
+## 数据和 MEMORY.md 格式
+
+所有产物都放在同一个 memory agent directory 下。
+
+解析顺序：
+
+1. `--agent-dir` CLI flag
+2. `PI_MEMORY_AGENT_DIR`
+3. 默认 `~/.pi/pi-memory-data`
+
+| 文件 | 作用 |
+| --- | --- |
+| `MEMORY.md` | 事实源文件 |
+| `auto-*.md` | 150 行上限后的溢出文件 |
+| `.memory_gc` | 上次 consolidate 时间 |
+| `.memory_compactions.json` | compaction 幂等状态 |
+| `.memory_shutdown_queue.jsonl` | append-only shutdown 元数据 |
+| `.memory_shutdown_processed.json` | drain 幂等状态 |
+| `memory.vec.sqlite` | 派生向量索引 |
+| `memory.sock` | Sidecar UDS socket |
+
+标准模板：[`templates/MEMORY.md.example`](../templates/MEMORY.md.example)
+
+```markdown
+# Memory
+
+## Preferences
+
+## Conventions
+
+## Findings
+
+## Todos
+```
+
+每条记忆是一个 Markdown bullet：
+
+```markdown
+- [user] Prefer pnpm over npm <!-- id:abc123 user ts:2026-07-04T09:00:00.000+08:00 -->
+- Project tests use Vitest <!-- id:def456 ts:2026-07-04T09:05:00.000+08:00 -->
+```
+
+规则：
+
+- `/remember` 写入 `[user]` 条目。
+- Consolidate 不能删除或改写 `[user]` 条目。
+- `MEMORY.md` 上限为 150 行。
+- 溢出条目写入 `auto-*.md`，并在 `MEMORY.md` 留指针。
+- 向量 chunk 从条目派生；默认超过 `PI_MEMORY_CHUNK_MAX_CHARS=512` 的长条目会拆分。
+
+## 配置
+
+可选 env 文件按以下顺序加载：
+
+1. `PI_MEMORY_ENV_FILE`
+2. 项目 `.env`
+3. 项目 `.env.local`
+4. `~/.pi/agent/pi-memory.env`
+
+常用变量：
+
+| 变量 | 默认 | 用途 |
+| --- | --- | --- |
+| `PI_MEMORY_AGENT_DIR` | `~/.pi/pi-memory-data` | 记忆数据根目录 |
+| `PI_MEMORY_EMBEDDER` | `hash` | 支持 `hash`、`ollama`、`openai` |
+| `PI_MEMORY_HELPER_MODEL` | `deepseek/deepseek-v4-flash` | QueryIntent 和 consolidate 使用的辅助模型 |
+| `PI_MEMORY_PREFLIGHT_BUDGET_MS` | `800` | Preflight 共享预算，限制在 250-1500ms |
+| `PI_MEMORY_INTENT_RETRIES` | `0` | 首次尝试后的 helper LLM 重试次数 |
+| `PI_MEMORY_WARM_SIDECAR` | `1` | 在 `session_start` warm sidecar |
+| `PI_MEMORY_INTENT_CACHE` | `1` | session 级 QueryIntent 缓存 |
+| `PI_MEMORY_REINDEX_DEBOUNCE_MS` | `500` | 写入后的 sidecar reindex debounce |
+| `PI_MEMORY_TOP_K` | `3` | 向量召回条数 |
+| `PI_MEMORY_MMR_LAMBDA` | `0.8` | MMR 相关性与多样性权重 |
+| `PI_MEMORY_MIN_RELEVANCE` | `0.4` | 最小 cosine similarity |
+| `PI_MEMORY_CHUNK_MAX_CHARS` | `512` | 索引长条目拆分阈值；`0` 表示关闭 |
+| `PI_MEMORY_DEBUG` | 未设置 | `1` 打印 debug timing logs |
+
+完整列表见 [`.env.example`](../.env.example)。
+
+### Embedding Provider
+
+| Embedder | 适用场景 | 说明 |
+| --- | --- | --- |
+| `hash` | 零配置本地开发 | 离线、确定性、语义质量较低 |
+| `ollama` | 本地语义 embedding | 使用 `PI_MEMORY_OLLAMA_BASE_URL` 和 `PI_MEMORY_OLLAMA_EMBED_MODEL` |
+| `openai` | 更高质量云端 embedding | 需要 `PI_MEMORY_OPENAI_API_KEY` 或 `OPENAI_API_KEY` |
+
+Vector Index 会保存 embedding provider、model 和 dimension 元数据。配置变化时会清空旧 chunks 并重建。
+
+## 命令
+
+Pi 内部：
+
+```text
+/remember [section] <content>
+/memory-status [refresh|expand|collapse|hide]
+```
+
+CLI：
+
+```bash
+pi-memory init
+pi-memory status
+pi-memory maintenance --cron --verbose
+pi-memory consolidate --force --verbose
+pi-memory drain-shutdown-queue --verbose
+```
+
+`maintenance` 是推荐的调度入口：
+
+```text
+consolidate -> drain-shutdown-queue
+```
+
+调度模板：
+
+- [`templates/com.pi.memory.consolidate.plist.example`](../templates/com.pi.memory.consolidate.plist.example)
+- [`templates/crontab.example`](../templates/crontab.example)
+- [`templates/consolidate.cmd.example`](../templates/consolidate.cmd.example)
+- [`templates/schtasks.example.txt`](../templates/schtasks.example.txt)
+
+## 诊断
+
+使用 `/memory-status` 或 `pi-memory status` 检查：
+
+- memory agent 目录
+- `MEMORY.md` 行数
+- 条目数
+- overflow 文件数
+- 上次 consolidate 时间
+- sidecar socket 状态
+- vector index generation 和 chunk 数
+- 当前配置的 embedder
+- 索引 embedder 是否与当前配置不一致
+
+设置 `PI_MEMORY_DEBUG=1` 可打印 Preflight timing 日志：
+
+```json
+{
+  "phase": "preflight",
+  "event": "recall",
+  "intent_ms": 0,
+  "intent_skipped": true,
+  "intent_cache_hit": false,
+  "sidecar_ms": 42,
+  "cache_hit": true,
+  "total_ms": 45,
+  "fallback": false,
+  "results": 3
+}
+```
+
+## 非目标
+
+- 不替代 Pi compaction。
+- 不替代 session search；历史对话搜索应使用专门的 session-search 扩展。
+- 不在本包内维护图数据库。
+- 不让 sidecar 成为事实源。
+- 不把完整聊天记录当作 memory 存储。
+- 不给每轮用户消息增加多秒级 reflection。
+
+## 开发
+
+```bash
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+sidecar IPC 测试会打开 Unix domain socket。如果在受限沙盒中因为 `listen EPERM` 失败，请在正常本地 shell 中运行。
+
+## 文档
+
+- [English README](../README.md)
+- [路线图](./ROADMAP-zh.md)
+- [UBIQUITOUS_LANGUAGE.md](../UBIQUITOUS_LANGUAGE.md) - 领域术语表
+
+## 许可证
+
+MIT

package/doc/ROADMAP-zh.md

@@ -0,0 +1,52 @@
+# @chendpoc/pi-memory 路线图
+
+<p align="center">
+  <a href="ROADMAP.md">English</a> |
+  <a href="ROADMAP-zh.md">简体中文</a>
+</p>
+
+本文档记录 `@chendpoc/pi-memory` 的产品方向。README 保持聚焦，只讲定位、安装和当前架构。
+
+## 当前基础
+
+- 带 overflow 的 `MEMORY.md` Ground Truth。
+- `/remember` 和 `/memory-status`。
+- 基于 UDS JSONL 的 Sidecar。
+- `memory.vec.sqlite` 向量索引。
+- QueryIntent + raw-query fallback。
+- 800ms 共享 Preflight 预算。
+- sidecar warm、intent cache、query cache。
+- dual-purpose compaction summary。
+- Shutdown Queue + `maintenance`。
+- Consolidate + reindex。
+- Subagent Memory Cap + Compact Delta。
+
+## P0：信任与安全
+
+- 记忆写入前做 secret/token redaction。
+- 对 LLM 生成的 Memory Export 增加 prompt-injection 防护。
+- 针对用户明确纠正做 correction detector。
+- 为跳过写入和 fallback 原因提供更好的诊断。
+
+## P1：召回质量
+
+- 对 `MEMORY.md` 条目做 lexical + vector 混合召回。
+- 为常见 coding-agent 问题建立 recall eval fixtures。
+- debug metrics 拆分 intent、embed、scan、MMR、render。
+- 延迟预算允许时，在 MMR 后增加可选 reranker。
+- 改进 Ollama 之外的本地 embedding provider。
+
+## P2：记忆生命周期
+
+- 增加 failure 和 tool-quirk 类别。
+- 晋升前提供人类可审查的 memory draft 或 diary。
+- 基于使用信号的晋升和裁剪。
+- rewrite 前提供更安全的 consolidate preview。
+- 显式处理 stale fact，而不是只做简单 TODO 清理。
+
+## P3：产品表面
+
+- 更好的 TUI status panel。
+- memory edit/review 命令。
+- 不同 Pi 安装之间的 import/export。
+- 常见 Pi 配置的文档 recipes。

package/doc/ROADMAP.md

@@ -0,0 +1,52 @@
+# @chendpoc/pi-memory Roadmap
+
+<p align="center">
+  <a href="ROADMAP.md">English</a> |
+  <a href="ROADMAP-zh.md">简体中文</a>
+</p>
+
+This roadmap tracks product direction for `@chendpoc/pi-memory`. The README stays focused on positioning, installation, and the current architecture.
+
+## Current Foundation
+
+- `MEMORY.md` Ground Truth with overflow.
+- `/remember` and `/memory-status`.
+- Sidecar over UDS JSONL.
+- `memory.vec.sqlite` vector index.
+- QueryIntent with raw-query fallback.
+- 800ms shared Preflight budget.
+- Warm sidecar, intent cache, query cache.
+- Dual-purpose compaction summary.
+- Shutdown Queue + `maintenance`.
+- Consolidate + reindex.
+- Subagent Memory Cap + Compact Delta.
+
+## P0: Trust And Safety
+
+- Secret and token redaction before memory writes.
+- Prompt-injection guardrails for LLM-generated Memory Export.
+- Correction detector for explicit user corrections.
+- Better diagnostics for skipped writes and fallback reasons.
+
+## P1: Recall Quality
+
+- Hybrid lexical + vector recall for `MEMORY.md` entries.
+- Recall eval fixtures for common coding-agent questions.
+- Debug metrics split by intent, embed, scan, MMR, render.
+- Optional reranker after MMR when latency budget allows.
+- Local embedding provider improvements beyond Ollama.
+
+## P2: Memory Lifecycle
+
+- Failure and tool-quirk categories.
+- Human-reviewable memory draft or diary before promotion.
+- Usage-weighted promotion and pruning.
+- Safer consolidate previews before rewrite.
+- Explicit stale fact handling instead of simple TODO pruning.
+
+## P3: Product Surface
+
+- Better TUI status panel.
+- Memory edit/review commands.
+- Import/export between Pi installations.
+- Documentation recipes for common Pi setups.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chendpoc/pi-memory",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Cross-session episodic memory for Pi agent — MEMORY.md ground truth, JSONL sidecar retrieval, and Preflight injection",
   "type": "module",
   "main": "./dist/index.js",
@@ -45,6 +45,9 @@
     "scripts/platform-fs.mjs",
     "scripts/postinstall.mjs",
     "README.md",
+    "doc/README-zh.md",
+    "doc/ROADMAP.md",
+    "doc/ROADMAP-zh.md",
     "UBIQUITOUS_LANGUAGE.md"
   ],
   "engines": {

package/src/config/index.ts

@@ -2,5 +2,6 @@ export { KNOWN_EMBED_DIMS, readPiMemoryEnv, resolveEmbedDim, type EmbedderProvid
 export { readRetrievalConfig, type RetrievalConfig } from "./retrieval.js";
 export { readChunkingConfig, type ChunkingConfig } from "./chunking.js";
 export { resolvePreflightBudget, type PreflightBudget } from "./preflightBudget.js";
+export { readPreflightRuntimeConfig, type PreflightRuntimeConfig } from "./preflight.js";
 export { resolveAgentDirFromEnv, resolveMemoryAgentDir, type ResolveMemoryAgentDirOptions } from "./agentDir.js";
 export { loadEnv } from "./loadEnv.js";

package/src/config/preflight.ts

@@ -0,0 +1,34 @@
+import { ENV_KEYS } from "../constants/env.js";
+import {
+  DEFAULT_INTENT_CACHE_ENABLED,
+  DEFAULT_INTENT_RETRIES,
+  DEFAULT_WARM_SIDECAR_ENABLED,
+  MAX_INTENT_RETRIES,
+} from "../constants/preflight.js";
+
+export type PreflightRuntimeConfig = {
+  intentRetries: number;
+  warmSidecar: boolean;
+  intentCache: boolean;
+};
+
+function parseOnOff(value: string | undefined, defaultOn: boolean): boolean {
+  if (value === undefined || value.trim() === "") return defaultOn;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "0" || normalized === "false" || normalized === "no") return false;
+  return true;
+}
+
+/** Runtime toggles for preflight latency optimizations. */
+export function readPreflightRuntimeConfig(
+  env: NodeJS.ProcessEnv = process.env,
+): PreflightRuntimeConfig {
+  const retries = Number.parseInt(env[ENV_KEYS.INTENT_RETRIES] ?? String(DEFAULT_INTENT_RETRIES), 10);
+  return {
+    intentRetries: Number.isFinite(retries)
+      ? Math.min(Math.max(0, retries), MAX_INTENT_RETRIES)
+      : DEFAULT_INTENT_RETRIES,
+    warmSidecar: parseOnOff(env[ENV_KEYS.WARM_SIDECAR], DEFAULT_WARM_SIDECAR_ENABLED),
+    intentCache: parseOnOff(env[ENV_KEYS.INTENT_CACHE], DEFAULT_INTENT_CACHE_ENABLED),
+  };
+}

package/src/constants/env.ts

@@ -25,6 +25,9 @@ export const ENV_KEYS = {
   MMR_LAMBDA: "PI_MEMORY_MMR_LAMBDA",
   MIN_RELEVANCE: "PI_MEMORY_MIN_RELEVANCE",
   CHUNK_MAX_CHARS: "PI_MEMORY_CHUNK_MAX_CHARS",
+  INTENT_RETRIES: "PI_MEMORY_INTENT_RETRIES",
+  WARM_SIDECAR: "PI_MEMORY_WARM_SIDECAR",
+  INTENT_CACHE: "PI_MEMORY_INTENT_CACHE",
   AGENT_DIR: "PI_MEMORY_AGENT_DIR",
   ENV_FILE: "PI_MEMORY_ENV_FILE",
   DEBUG: "PI_MEMORY_DEBUG",

package/src/constants/preflight.ts

@@ -11,3 +11,12 @@ export const MEMORY_CUE_RE =
 
 export const PREFLIGHT_SKIP_MIN_LENGTH = 12;
 export const PREFLIGHT_EXTRACT_MIN_LENGTH = 24;
+
+/** Helper LLM retries after the first attempt (0 = single try). */
+export const DEFAULT_INTENT_RETRIES = 0;
+export const MAX_INTENT_RETRIES = 3;
+
+/** Sidecar warm start + intent LRU defaults. */
+export const DEFAULT_WARM_SIDECAR_ENABLED = true;
+export const DEFAULT_INTENT_CACHE_ENABLED = true;
+export const INTENT_CACHE_MAX_ENTRIES = 128;

package/src/constants/timing.ts

@@ -39,6 +39,8 @@ export const SIDECAR_FORCE_KILL_DELAY_MS = 5_000;
 export const SIDECAR_PING_TIMEOUT_MS = 1_000;
 export const SIDECAR_QUERY_TIMEOUT_MS = 3_000;
 export const SIDECAR_REINDEX_TIMEOUT_MS = 10_000;
+/** Warm start dummy query (session_start; not counted against Preflight budget). */
+export const SIDECAR_WARMUP_QUERY_TIMEOUT_MS = 500;
 
 /** proper-lockfile on MEMORY.md. */
 export const MEMORY_LOCK_RETRIES = 5;

package/src/pi-extension.ts

@@ -4,10 +4,12 @@ import findLastIndex from "lodash/findLastIndex.js";
 
 import { createLlmClient, type LlmClient } from "./adapters/llm/index.js";
 import { loadEnv, readPiMemoryEnv, resolveMemoryAgentDir } from "./config/index.js";
+import { readPreflightRuntimeConfig } from "./config/preflight.js";
 import { createConsolidateScheduler, startConsolidateInterval, type ConsolidateScheduler } from "./consolidate/scheduler.js";
 import { registerCommands } from "./commands/index.js";
 import { registerCompactHandlers } from "./compact/register.js";
 import { runEpisodicPreflight } from "./preflight/episodic.js";
+import { queryIntentCache } from "./preflight/intentCache.js";
 import { mergePrivateMemoryBlocks, renderMemoryCapPrivateMemory } from "./preflight/render.js";
 import { isSubagentSession } from "./preflight/session.js";
 import { injectPrivateMemoryContext } from "./preflight/strip.js";
@@ -15,6 +17,7 @@ import { enqueueShutdownMetadata, readParentSession } from "./shutdown/enqueue.j
 import { resolveSidecarPaths } from "./sidecar/paths.js";
 import { formatTimestamp } from "./utils/time.js";
 import { createReindexScheduler, type ReindexScheduler } from "./sidecar/reindexBridge.js";
+import { warmSidecar } from "./sidecar/warmup.js";
 import { ensureSidecarRunning, stopSidecar } from "./sidecar/sidecarManager.js";
 import { MemoryStore } from "./store/memoryStore.js";
 
@@ -35,6 +38,7 @@ let sessionMemoryCap: string | null = null;
 let turnPreflight: TurnPreflight | null = null;
 let isFirstTurn = false;
 let isSubagent = false;
+let sessionId: string | null = null;
 
 function getUserMessageText(message: AgentMessage): string | null {
   if (message.role !== "user") return null;
@@ -70,6 +74,14 @@ async function bootstrapSidecar(): Promise<void> {
     dbPath: sidecarPaths.dbPath,
   });
 
+  if (readPreflightRuntimeConfig().warmSidecar) {
+    try {
+      await warmSidecar(sidecarPaths.socketPath);
+    } catch {
+      // warm is best-effort
+    }
+  }
+
   reindexScheduler ??= createReindexScheduler({
     sidecar: sidecarPaths,
     agentDir: memoryStore.agentDir,
@@ -117,6 +129,7 @@ export default function piMemoryExtension(pi: ExtensionAPI): void {
     isSubagent = isSubagentSession(ctx);
     isFirstTurn = true;
     turnPreflight = null;
+    sessionId = ctx.sessionManager.getSessionFile() ?? null;
 
     await refreshLlm(ctx, pi);
 
@@ -141,6 +154,10 @@ export default function piMemoryExtension(pi: ExtensionAPI): void {
       }).catch(() => {});
     }
 
+    if (sessionId) {
+      queryIntentCache.clearSession(sessionId);
+    }
+
     stopConsolidateInterval?.();
     stopConsolidateInterval = null;
     consolidateScheduler = null;
@@ -152,6 +169,7 @@ export default function piMemoryExtension(pi: ExtensionAPI): void {
     turnPreflight = null;
     isFirstTurn = false;
     isSubagent = false;
+    sessionId = null;
 
     try {
       await stopSidecar();
@@ -194,7 +212,8 @@ export default function piMemoryExtension(pi: ExtensionAPI): void {
         agentDir: memoryStore.agentDir,
         store: memoryStore,
         llm: llmClient,
-        force: forceHelper,
+        forceEpisodic: forceHelper,
+        sessionId: sessionId ?? undefined,
         budgetMs: env.preflightBudgetMs,
         signal: ctx.signal,
         onProgress: workingUi?.update,
@@ -237,7 +256,8 @@ export default function piMemoryExtension(pi: ExtensionAPI): void {
           agentDir: memoryStore.agentDir,
           store: memoryStore,
           llm: llmClient,
-          force: userTurnCount === 1,
+          forceEpisodic: userTurnCount === 1,
+          sessionId: sessionId ?? undefined,
           budgetMs: env.preflightBudgetMs,
           signal: ctx.signal,
         });