pi-hermes-memory 0.1.0

package/docs/ROADMAP.md

@@ -0,0 +1,272 @@
+# Pi Hermes Memory — Roadmap
+
+> From markdown files to a pluggable memory substrate for any Pi agent harness.
+
+## Where We Are (v0.1.0)
+
+- Persistent memory via `MEMORY.md` + `USER.md` with `§` delimiter
+- Real-time `memory` tool (add / replace / remove) for the LLM
+- Content scanning: prompt injection, role hijacking, secret exfiltration, invisible unicode
+- Background learning loop (every N turns via `pi.exec`)
+- Session flush before compaction and shutdown
+- `/memory-insights` command
+- Frozen snapshot injection into system prompt
+- 119 automated tests, 0 type errors
+- Atomic writes (temp + rename)
+
+## Architecture Evolution
+
+```mermaid
+graph TB
+    subgraph "v0.1.0 — Current"
+        T1["memory tool<br/>(add / replace / remove)"]
+        SC["Content Scanner<br/>(injection · exfiltration · unicode)"]
+        MD["Markdown Backend<br/>MEMORY.md · USER.md"]
+        FS["Frozen Snapshot<br/>(system prompt injection)"]
+        BL["Background Review<br/>(pi.exec child process)"]
+        SF["Session Flush<br/>(compact · shutdown)"]
+        IC["/memory-insights<br/>(command)"]
+        CF["Config File<br/>(hermes-memory-config.json)"]
+    end
+
+    T1 --> SC --> MD
+    BL --> MD
+    SF --> MD
+    MD --> FS
+
+    style T1 fill:#e94560,stroke:#fff,color:#fff
+    style SC fill:#ff6600,stroke:#fff,color:#fff
+    style MD fill:#0f3460,stroke:#fff,color:#fff
+    style FS fill:#16213e,stroke:#fff,color:#fff
+    style BL fill:#16213e,stroke:#fff,color:#fff
+    style SF fill:#16213e,stroke:#fff,color:#fff
+    style IC fill:#16213e,stroke:#fff,color:#fff
+    style CF fill:#16213e,stroke:#fff,color:#fff
+```
+
+```mermaid
+graph TB
+    subgraph "v0.2.0 — Structured Storage & Search"
+        T2["memory tool<br/>(add / replace / remove / search)"]
+        SC2["Content Scanner<br/>(v0.1.0 scanner unchanged)"]
+        SA["Search Abstraction<br/>(MemoryBackend interface)"]
+        SQL["SQLite Backend<br/>(FTS5 · key-value · confidence)"]
+        PI2["Context-Aware Injection<br/>(relevance-filtered)"]
+        PS["Project-Scoped Memory<br/>(keyed by cwd)"]
+    end
+
+    T2 --> SC2 --> SA
+    SA --> SQL
+    SQL --> PI2
+    SQL --> PS
+
+    style T2 fill:#e94560,stroke:#fff,color:#fff
+    style SC2 fill:#ff6600,stroke:#fff,color:#fff
+    style SA fill:#1282a2,stroke:#fff,color:#fff
+    style SQL fill:#0f3460,stroke:#fff,color:#fff
+    style PI2 fill:#16213e,stroke:#fff,color:#fff
+    style PS fill:#16213e,stroke:#fff,color:#fff
+```
+
+```mermaid
+graph TB
+    subgraph "v0.3.0 — Pluggable Backend & External Memory"
+        T3["memory tool<br/>(add / replace / remove / search)"]
+        SC3["Content Scanner<br/>(unchanged — guards all backends)"]
+        SA3["Search Abstraction<br/>(MemoryBackend interface)"]
+        LOC["Local SQLite<br/>(default · offline)"]
+        M0["Mem0 Backend<br/>(vector search · cloud)"]
+        HON["Honcho Backend<br/>(dialectic reasoning · Hermes-native)"]
+        SEL["Selective Injection<br/>(search-relevant · project-scoped)"]
+    end
+
+    T3 --> SC3 --> SA3
+    SA3 --> LOC
+    SA3 --> M0
+    SA3 --> HON
+    LOC --> SEL
+    M0 --> SEL
+    HON --> SEL
+
+    style T3 fill:#e94560,stroke:#fff,color:#fff
+    style SC3 fill:#ff6600,stroke:#fff,color:#fff
+    style SA3 fill:#1282a2,stroke:#fff,color:#fff
+    style LOC fill:#0f3460,stroke:#fff,color:#fff
+    style M0 fill:#6b21a8,stroke:#fff,color:#fff
+    style HON fill:#6b21a8,stroke:#fff,color:#fff
+    style SEL fill:#16213e,stroke:#fff,color:#fff
+```
+
+```mermaid
+graph TB
+    subgraph "v1.0.0 — Production Memory Substrate"
+        T4["memory tool<br/>(add / replace / remove / search / consolidate)"]
+        SC4["Content Scanner<br/>(extensible rule system)"]
+        SA4["Pluggable Backend<br/>(local · Mem0 · Honcho · custom)"]
+        CON["Smart Consolidation<br/>(structured extraction · dedup)"]
+        MUL["Multi-Agent Memory<br/>(shared context · scoping)"]
+        OBS["Observability<br/>(memory stats · usage · audit log)"]
+    end
+
+    T4 --> SC4 --> SA4
+    SA4 --> CON
+    SA4 --> MUL
+    CON --> OBS
+
+    style T4 fill:#e94560,stroke:#fff,color:#fff
+    style SC4 fill:#ff6600,stroke:#fff,color:#fff
+    style SA4 fill:#1282a2,stroke:#fff,color:#fff
+    style CON fill:#16213e,stroke:#fff,color:#fff
+    style MUL fill:#16213e,stroke:#fff,color:#fff
+    style OBS fill:#16213e,stroke:#fff,color:#fff
+```
+
+---
+
+## v0.2.0 — Structured Storage & Search
+
+**Goal**: Replace flat markdown with SQLite. Add search. Keep the same tool interface.
+
+### `MemoryBackend` Interface
+
+The core abstraction that makes everything after this possible:
+
+```typescript
+interface MemoryBackend {
+  // Write
+  add(target: "memory" | "user", entry: MemoryEntry): Promise<MemoryResult>;
+  replace(target: "memory" | "user", query: string, entry: MemoryEntry): Promise<MemoryResult>;
+  remove(target: "memory" | "user", query: string): Promise<MemoryResult>;
+
+  // Read
+  getAll(target: "memory" | "user"): Promise<MemoryEntry[]>;
+  search(query: string, limit?: number): Promise<MemoryEntry[]>;
+
+  // Lifecycle
+  formatForSystemPrompt(cwd?: string, prompt?: string): Promise<string>;
+  close(): Promise<void>;
+}
+```
+
+Current `MemoryStore` becomes `MarkdownBackend` — the default, zero-dependency implementation. New `SQLiteBackend` adds structure without breaking anything.
+
+### Deliverables
+
+- [ ] `MemoryBackend` interface in `src/types.ts`
+- [ ] `MarkdownBackend` — wraps current `MemoryStore` (backwards compatible)
+- [ ] `SQLiteBackend` — FTS5 search, key-value entries, confidence scores, dedup by key
+- [ ] `memory search` tool action — LLM can query existing entries
+- [ ] Project-scoped memory — entries tagged with `cwd`, injected when matching
+- [ ] Context-aware injection — `formatForSystemPrompt(cwd, prompt)` filters by relevance
+- [ ] Config: `"backend": "markdown" | "sqlite"` (defaults to `markdown` for zero-dep install)
+- [ ] Migration tool: `markdown → sqlite` one-time import
+
+### What Does NOT Change
+
+- Content scanner (guards all backends)
+- Tool interface (`memory` tool name and actions)
+- System prompt injection (frozen snapshot pattern)
+- Config file location and format (just adds new fields)
+
+---
+
+## v0.3.0 — Pluggable External Memory
+
+**Goal**: Let users swap the backend to Mem0 or Honcho without changing anything else. The content scanner guards all data before it leaves the machine.
+
+### Why This Matters
+
+External memory services provide better semantic search, cross-session continuity, and multi-agent awareness. But they introduce trust boundaries — your agent's memories leave your machine. The content scanner becomes the security gate between Pi and any external service.
+
+### Deliverables
+
+- [ ] `Mem0Backend` — wraps Mem0's Node.js SDK (`add`, `search`, `update`, `delete`)
+- [ ] `HonchoBackend` — wraps Honcho's API (`honcho_context`, `honcho_search_conclusions`, `honcho_reasoning`)
+- [ ] Backend auto-detection — check for `MEM0_API_KEY` or `HONCHO_API_KEY` env vars, offer to configure
+- [ ] Config: `"backend": "sqlite" | "mem0" | "honcho"` with `"mem0": { "apiKey": "...", "orgId": "..." }` options
+- [ ] Selective injection by default when using external backends (leverage their search APIs)
+- [ ] Offline fallback — if external backend is unreachable, fall back to local SQLite cache
+- [ ] Data export — `memory export` command to dump all entries as JSON
+
+### Security Model
+
+```
+LLM tool call
+    ↓
+Content Scanner (local, always runs first)
+    ↓ blocked? → return error to LLM
+    ↓ passed
+MemoryBackend.add()
+    ↓
+Mem0 / Honcho / SQLite / Markdown
+```
+
+The scanner runs **before** any backend. No adversarial content reaches external services.
+
+---
+
+## v1.0.0 — Production Memory Substrate
+
+**Goal**: The memory layer that any Pi agent harness can build on top of.
+
+### Deliverables
+
+- [ ] Smart consolidation — structured extraction with typed output (preferences, patterns, corrections, tool prefs)
+- [ ] Confidence scoring — entries gain confidence over time as they're referenced, decay if never used
+- [ ] Multi-agent memory — shared context between agents, scoping rules (per-user, per-project, global)
+- [ ] Extensible scanner rules — users can add custom patterns to the content scanner
+- [ ] `/memory-insights` upgrade — show backend type, entry count, storage stats, last sync time
+- [ ] Audit log — track all memory operations with timestamps (already in SQLite schema for `SQLiteBackend`)
+- [ ] Import/export — migrate between backends without data loss
+- [ ] Benchmarks — context injection latency, search relevance, token budget utilization
+
+---
+
+## Design Principles (Unchanging)
+
+These hold across all versions:
+
+1. **Security first** — Content scanning before any write, regardless of backend. No exceptions.
+2. **Real-time saves** — The LLM can save memories mid-conversation via tool calls, not just at session end.
+3. **Frozen snapshot** — Memory is injected into the system prompt once at session start. Never mutated mid-session.
+4. **Crash safety** — Atomic writes for markdown, WAL mode for SQLite, graceful degradation for external backends.
+5. **Zero-config start** — Install and it works with sensible defaults. Configuration is for power users.
+6. **Backwards compatible** — Every new version is a drop-in upgrade. No breaking changes to the tool interface or config format without a major version bump.
+
+---
+
+## Version Timeline
+
+```mermaid
+gantt
+    title Pi Hermes Memory — Release Timeline
+    dateFormat YYYY-MM-DD
+    axisFormat %b %Y
+
+    section v0.1.0
+    Core memory + scanner + tool + review + flush    :done, v01, 2025-04-20, 5d
+
+    section v0.2.0
+    MemoryBackend interface                          :v02a, after v01, 7d
+    SQLite backend + FTS5 search                     :v02b, after v02a, 7d
+    memory search tool + project scoping             :v02c, after v02b, 5d
+    Context-aware injection                          :v02d, after v02c, 5d
+
+    section v0.3.0
+    Mem0 backend                                     :v03a, after v02d, 7d
+    Honcho backend                                   :v03b, after v03a, 7d
+    Offline fallback + data export                   :v03c, after v03b, 5d
+
+    section v1.0.0
+    Smart consolidation + confidence                 :v1a, after v03c, 10d
+    Multi-agent memory + audit log                   :v1b, after v1a, 10d
+    Extensible scanner + benchmarks                  :v1c, after v1b, 7d
+```
+
+---
+
+## How to Contribute
+
+See [TASKS.md](0.1/TASKS.md) for current work. Pick an unchecked item, mark it `[~]`, implement, mark it `[x]` with the commit hash.
+
+For roadmap items, open an issue with the version tag (e.g. `v0.2.0`) and describe what you want to work on.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "pi-hermes-memory",
+  "version": "0.1.0",
+  "description": "Persistent memory and self-directed learning loop for Pi — ported from the Hermes agent harness. Security-first content scanning, real-time saves, and frozen snapshot injection.",
+  "type": "module",
+  "main": "src/index.ts",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "docs"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "npx tsx --test 'tests/**/*.test.ts' --test-concurrency=1"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "memory",
+    "learning-loop",
+    "agent",
+    "hermes",
+    "persistent-memory",
+    "content-scanner"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chandra447/pi-hermes-memory"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-ai": "^0.70.0",
+    "@mariozechner/pi-coding-agent": "^0.70.0",
+    "typebox": "^1.1.33",
+    "typescript": "^6.0.3"
+  }
+}

package/src/config.ts

@@ -0,0 +1,49 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import type { MemoryConfig } from "./types.js";
+import {
+  DEFAULT_MEMORY_CHAR_LIMIT,
+  DEFAULT_USER_CHAR_LIMIT,
+  DEFAULT_NUDGE_INTERVAL,
+  DEFAULT_FLUSH_MIN_TURNS,
+} from "./constants.js";
+
+const DEFAULT_CONFIG: MemoryConfig = {
+  memoryCharLimit: DEFAULT_MEMORY_CHAR_LIMIT,
+  userCharLimit: DEFAULT_USER_CHAR_LIMIT,
+  nudgeInterval: DEFAULT_NUDGE_INTERVAL,
+  reviewEnabled: true,
+  flushOnCompact: true,
+  flushOnShutdown: true,
+  flushMinTurns: DEFAULT_FLUSH_MIN_TURNS,
+};
+
+export const DEFAULT_CONFIG_PATH = path.join(
+  os.homedir(),
+  ".pi",
+  "agent",
+  "hermes-memory-config.json",
+);
+
+export function loadConfig(): MemoryConfig {
+  try {
+    if (fs.existsSync(DEFAULT_CONFIG_PATH)) {
+      const raw = fs.readFileSync(DEFAULT_CONFIG_PATH, "utf-8");
+      const parsed = JSON.parse(raw);
+      // Merge: override defaults with user config
+      const config: MemoryConfig = { ...DEFAULT_CONFIG };
+      if (typeof parsed.memoryCharLimit === "number") config.memoryCharLimit = parsed.memoryCharLimit;
+      if (typeof parsed.userCharLimit === "number") config.userCharLimit = parsed.userCharLimit;
+      if (typeof parsed.nudgeInterval === "number") config.nudgeInterval = parsed.nudgeInterval;
+      if (typeof parsed.reviewEnabled === "boolean") config.reviewEnabled = parsed.reviewEnabled;
+      if (typeof parsed.flushOnCompact === "boolean") config.flushOnCompact = parsed.flushOnCompact;
+      if (typeof parsed.flushOnShutdown === "boolean") config.flushOnShutdown = parsed.flushOnShutdown;
+      if (typeof parsed.flushMinTurns === "number") config.flushMinTurns = parsed.flushMinTurns;
+      return config;
+    }
+  } catch {
+    // Fall back to defaults on parse error or access issues
+  }
+  return { ...DEFAULT_CONFIG };
+}

package/src/constants.ts

@@ -0,0 +1,52 @@
+/**
+ * Constants — prompts, defaults, and delimiter.
+ * Ported from hermes-agent/tools/memory_tool.py and hermes-agent/run_agent.py.
+ * See PLAN.md → "Hermes Source File Reference Map" for exact source lines.
+ */
+
+// ─── Entry delimiter (same as Hermes) ───
+export const ENTRY_DELIMITER = "\n§\n";
+
+// ─── Character limits (not tokens — model-independent) ───
+export const DEFAULT_MEMORY_CHAR_LIMIT = 2200;
+export const DEFAULT_USER_CHAR_LIMIT = 1375;
+
+// ─── Learning loop defaults ───
+export const DEFAULT_NUDGE_INTERVAL = 10;
+export const DEFAULT_FLUSH_MIN_TURNS = 6;
+
+// ─── File names ───
+export const MEMORY_FILE = "MEMORY.md";
+export const USER_FILE = "USER.md";
+
+// ─── Tool description (ported from MEMORY_SCHEMA in hermes-agent/tools/memory_tool.py) ───
+export const MEMORY_TOOL_DESCRIPTION = `Save durable information to persistent memory that survives across sessions. Memory is injected into future turns, so keep it compact and focused on facts that will still matter later.
+
+WHEN TO SAVE (do this proactively, don't wait to be asked):
+- User corrects you or says 'remember this' / 'don't do that again'
+- User shares a preference, habit, or personal detail (name, role, timezone, coding style)
+- You discover something about the environment (OS, installed tools, project structure)
+- You learn a convention, API quirk, or workflow specific to this user's setup
+- You identify a stable fact that will be useful again in future sessions
+
+PRIORITY: User preferences and corrections > environment facts > procedural knowledge.
+
+Do NOT save task progress, session outcomes, completed-work logs, or temporary TODO state.
+
+TWO TARGETS:
+- 'user': who the user is -- name, role, preferences, communication style, pet peeves
+- 'memory': your notes -- environment facts, project conventions, tool quirks, lessons learned
+
+ACTIONS: add (new entry), replace (update existing -- old_text identifies it), remove (delete -- old_text identifies it).`;
+
+// ─── Background review prompt (ported from _COMBINED_REVIEW_PROMPT in run_agent.py ~L2855) ───
+export const COMBINED_REVIEW_PROMPT = `Review the conversation above and consider two things:
+
+**Memory**: Has the user revealed things about themselves — their persona, desires, preferences, or personal details? Has the user expressed expectations about how you should behave, their work style, or ways they want you to operate? If so, save using the memory tool.
+
+**Skills**: Was a non-trivial approach used to complete a task that required trial and error, or changing course due to experiential findings along the way, or did the user expect or desire a different method or outcome?
+
+Only act if there's something genuinely worth saving. If nothing stands out, just say 'Nothing to save.' and stop.`;
+
+// ─── Flush prompt (ported from flush_memories() in run_agent.py ~L7379) ───
+export const FLUSH_PROMPT = `[System: The session is being compressed. Save anything worth remembering — prioritize user preferences, corrections, and recurring patterns over task-specific details.]`;

package/src/handlers/background-review.ts

@@ -0,0 +1,95 @@
+/**
+ * Background review — learning loop that auto-saves memory every N turns.
+ * Ported from hermes-agent/run_agent.py (_spawn_background_review, _memory_nudge_interval).
+ * See PLAN.md → "Hermes Source File Reference Map" for source lines.
+ *
+ * Uses pi.exec("pi", ["-p", ...]) for isolated one-shot review,
+ * keeping us within Pi's intended extension API.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { MemoryStore } from "../store/memory-store.js";
+import { COMBINED_REVIEW_PROMPT } from "../constants.js";
+import type { MemoryConfig } from "../types.js";
+import { getMessageText } from "../types.js";
+
+export function setupBackgroundReview(
+  pi: ExtensionAPI,
+  store: MemoryStore,
+  config: MemoryConfig,
+): void {
+  let turnsSinceReview = 0;
+  let userTurnCount = 0;
+  let reviewInProgress = false;
+
+  pi.on("message_end", async (event, _ctx) => {
+    if (event.message.role === "user") {
+      userTurnCount++;
+    }
+  });
+
+  pi.on("turn_end", async (event, ctx) => {
+    turnsSinceReview++;
+
+    if (!config.reviewEnabled) return;
+    if (reviewInProgress) return;
+    if (turnsSinceReview < config.nudgeInterval) return;
+    if (userTurnCount < 3) return;
+
+    turnsSinceReview = 0;
+    reviewInProgress = true;
+
+    try {
+      // Build conversation snapshot from session entries
+      const entries = ctx.sessionManager.getBranch();
+      const parts: string[] = [];
+
+      for (const entry of entries) {
+        if (entry.type !== "message") continue;
+        const msg = entry.message;
+        const text = getMessageText(msg);
+        if (!text) continue;
+        const prefix = msg.role === "user" ? "[USER]" : "[ASSISTANT]";
+        parts.push(`${prefix}: ${text}`);
+      }
+      if (parts.length < 4) return; // Not enough conversation to review
+
+      const currentMemory = store.getMemoryEntries().join("\n§\n");
+      const currentUser = store.getUserEntries().join("\n§\n");
+
+      const reviewPrompt = [
+        COMBINED_REVIEW_PROMPT,
+        "",
+        "--- Current Memory ---",
+        currentMemory || "(empty)",
+        "",
+        "--- Current User Profile ---",
+        currentUser || "(empty)",
+        "",
+        "--- Conversation to Review ---",
+        parts.join("\n\n"),
+      ].join("\n");
+
+      const result = await pi.exec("pi", ["-p", "--no-session", reviewPrompt], {
+        signal: ctx.signal,
+        timeout: 60000,
+      });
+
+      if (result.code === 0 && result.stdout) {
+        const output = result.stdout.trim();
+        if (output && !output.toLowerCase().includes("nothing to save")) {
+          ctx.ui.notify("💾 Memory auto-reviewed and updated", "info");
+        }
+      } else {
+        ctx.ui.notify(
+          `[hermes] auto-review failed (exit=${result.code}): ${result.stderr?.slice(0, 200) || "unknown error"}`,
+          "error",
+        );
+      }
+    } catch (err) {
+      ctx.ui.notify(`[hermes] auto-review error: ${String(err).slice(0, 200)}`, "error");
+    } finally {
+      reviewInProgress = false;
+    }
+  });
+}

package/src/handlers/insights.ts

@@ -0,0 +1,57 @@
+/**
+ * Insights command — /memory-insights shows what's stored in persistent memory.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { MemoryStore } from "../store/memory-store.js";
+
+export function registerInsightsCommand(pi: ExtensionAPI, store: MemoryStore): void {
+  pi.registerCommand("memory-insights", {
+    description: "Show what's stored in persistent memory",
+    handler: async (_args, ctx) => {
+      const memoryEntries = store.getMemoryEntries();
+      const userEntries = store.getUserEntries();
+
+      const lines: string[] = [];
+      lines.push("");
+      lines.push("  ╔══════════════════════════════════════════════╗");
+      lines.push("  ║            🧠 Memory Insights                ║");
+      lines.push("  ╚══════════════════════════════════════════════╝");
+      lines.push("");
+
+      // Memory section
+      lines.push("  📋 MEMORY (your personal notes)");
+      lines.push("  " + "─".repeat(44));
+      if (memoryEntries.length === 0) {
+        lines.push("  (empty)");
+      } else {
+        for (let i = 0; i < memoryEntries.length; i++) {
+          const preview =
+            memoryEntries[i].length > 100
+              ? memoryEntries[i].slice(0, 100) + "..."
+              : memoryEntries[i];
+          lines.push(`  ${i + 1}. ${preview}`);
+        }
+      }
+      lines.push("");
+
+      // User section
+      lines.push("  👤 USER PROFILE");
+      lines.push("  " + "─".repeat(44));
+      if (userEntries.length === 0) {
+        lines.push("  (empty)");
+      } else {
+        for (let i = 0; i < userEntries.length; i++) {
+          const preview =
+            userEntries[i].length > 100
+              ? userEntries[i].slice(0, 100) + "..."
+              : userEntries[i];
+          lines.push(`  ${i + 1}. ${preview}`);
+        }
+      }
+      lines.push("");
+
+      ctx.ui.notify(lines.join("\n"), "info");
+    },
+  });
+}

package/src/handlers/session-flush.ts

@@ -0,0 +1,75 @@
+/**
+ * Session flush — gives the agent one turn to save memories before context is lost.
+ * Ported from hermes-agent/run_agent.py (flush_memories).
+ * See PLAN.md → "Hermes Source File Reference Map" for source lines.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { MemoryStore } from "../store/memory-store.js";
+import { FLUSH_PROMPT } from "../constants.js";
+import type { MemoryConfig } from "../types.js";
+import { getMessageText } from "../types.js";
+
+export function setupSessionFlush(
+  pi: ExtensionAPI,
+  store: MemoryStore,
+  config: MemoryConfig,
+): void {
+  let userTurnCount = 0;
+
+  pi.on("message_end", async (event, _ctx) => {
+    if (event.message.role === "user") userTurnCount++;
+  });
+
+  /** Shared flush logic — builds conversation snapshot and spawns pi -p */
+  async function flush(ctx: any, signal?: AbortSignal, timeoutMs = 30000): Promise<void> {
+    if (userTurnCount < config.flushMinTurns) return;
+
+    let entries;
+    try {
+      entries = ctx.sessionManager.getBranch();
+    } catch {
+      return; // Context already stale
+    }
+
+    const parts: string[] = [];
+
+    for (const entry of entries) {
+      if (entry.type !== "message") continue;
+      const msg = entry.message;
+      const text = getMessageText(msg);
+      if (!text) continue;
+      const prefix = msg.role === "user" ? "[USER]" : "[ASSISTANT]";
+      parts.push(`${prefix}: ${text}`);
+    }
+    const flushMessage = [
+      FLUSH_PROMPT,
+      "",
+      "--- Conversation ---",
+      parts.join("\n\n"),
+    ].join("\n");
+
+    try {
+      await pi.exec("pi", ["-p", "--no-session", flushMessage], {
+        signal,
+        timeout: timeoutMs,
+      });
+    } catch {
+      // Best-effort flush — never block shutdown
+    }
+  }
+
+  // Flush before compaction (can afford to wait)
+  pi.on("session_before_compact", async (event, ctx) => {
+    if (!config.flushOnCompact) return;
+    await flush(ctx, event.signal, 30000);
+  });
+
+  // Flush before session shutdown (must be fast, non-blocking)
+  pi.on("session_shutdown", async (event, ctx) => {
+    if (!config.flushOnShutdown) return;
+    // Fire-and-forget with a short timeout so we don't block Pi's shutdown.
+    // We intentionally do NOT await — Pi should not wait for the child process.
+    flush(ctx, undefined, 10000).catch(() => {});
+  });
+}