feat: add first-session nudge to session_start display (OD-750)

When no prior sessions exist, appends a one-time nudge block to the
display output suggesting patterns the agent should save to its PMEM.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 2 people

README.md

@@ -3,11 +3,11 @@
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/gitmem-mcp"><img src="https://img.shields.io/npm/v/gitmem-mcp?style=flat-square&color=ed1e25&label=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/gitmem-mcp"><img src="https://img.shields.io/npm/v/gitmem-mcp?style=flat-square&color=c41920&label=npm" alt="npm version" /></a>
   <a href="https://www.npmjs.com/package/gitmem-mcp"><img src="https://img.shields.io/npm/dm/gitmem-mcp?style=flat-square&color=333333&label=downloads" alt="npm downloads" /></a>
-  <a href="https://github.com/gitmem-dev/gitmem/blob/main/LICENSE"><img src="https://img.shields.io/github/license/gitmem-dev/gitmem?style=flat-square&color=ed1e25" alt="MIT License" /></a>
+  <a href="https://github.com/gitmem-dev/gitmem/blob/main/LICENSE"><img src="https://img.shields.io/github/license/gitmem-dev/gitmem?style=flat-square&color=c41920" alt="MIT License" /></a>
   <a href="https://github.com/gitmem-dev/gitmem/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/gitmem-dev/gitmem/ci.yml?style=flat-square&color=333333&label=build" alt="Build" /></a>
-  <img src="https://img.shields.io/badge/node-%3E%3D22-ed1e25?style=flat-square" alt="Node.js >= 22" />
+  <img src="https://img.shields.io/badge/node-%3E%3D18-c41920?style=flat-square" alt="Node.js >= 18" />
 </p>
 
 <p align="center">

src/tools/session-start.ts

@@ -74,6 +74,20 @@ const CLOSING_PAYLOAD_SCHEMA: Record<string, unknown> = {
   decisions: [],
 };
 
+const FIRST_SESSION_NUDGE = [
+  "",
+  "Welcome to gitmem. Patterns that improve the experience:",
+  "",
+  "  - session_start: once per session — if a hook triggers it, don't repeat",
+  "  - Display protocol: echo tool results verbatim, including ANSI formatting",
+  "  - recall() before consequential actions (deploys, issues, agent spawns)",
+  "  - Read .gitmem/ state before session close — survives context compaction",
+  "  - Search gitmem before filesystem exploration — memory > re-discovery",
+  "  - Create learning entries after significant work, before closing",
+  "",
+  "Save these to your persistent memory (MEMORY.md) so they carry forward.",
+].join("\n");
+
 // Supabase record types
 interface SessionRecord {
   id: string;
@@ -567,7 +581,8 @@ async function sessionStartFree(
     project,
     performance,
   };
-  freeResult.display = formatStartDisplay(freeResult);
+  const isFirstSession = !isResuming && !lastSession;
+  freeResult.display = formatStartDisplay(freeResult, undefined, isFirstSession);
 
   // Write display to per-session dir
   try {
@@ -810,7 +825,7 @@ function stripThreadPrefix(text: string): string {
   return text.replace(/^t-[a-f0-9]+:\s*/i, "");
 }
 
-function formatStartDisplay(result: SessionStartResult, displayInfoMap?: Map<string, ThreadDisplayInfo>): string {
+function formatStartDisplay(result: SessionStartResult, displayInfoMap?: Map<string, ThreadDisplayInfo>, isFirstSession?: boolean): string {
   const visual: string[] = [];
 
   // Line 1: branded product line + session state
@@ -863,6 +878,11 @@ function formatStartDisplay(result: SessionStartResult, displayInfoMap?: Map<str
     visual.push("No threads or decisions.");
   }
 
+  // First-session nudge — agent sees this once, internalizes to PMEM
+  if (isFirstSession) {
+    visual.push(FIRST_SESSION_NUDGE);
+  }
+
   const visualBlock = visual.join("\n");
 
   // ── Display-first layout ──
@@ -1086,7 +1106,8 @@ export async function sessionStart(
   for (const info of threadDisplayInfo) {
     displayInfoMap.set(info.thread.id, info);
   }
-  result.display = formatStartDisplay(result, displayInfoMap);
+  const isFirstSession = !isResuming && !slimLastSession;
+  result.display = formatStartDisplay(result, displayInfoMap, isFirstSession);
 
   // Write display to per-session dir
   try {