@sylphx/flow 3.19.1 → 3.20.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @sylphx/flow
 
+## 3.20.0 (2026-02-08)
+
+### ✨ Features
+
+- **flow:** add SessionStart memory hook and use stdin for notifications ([6580500](https://github.com/SylphxAI/flow/commit/65805004f164a8f9a05d821e528c7412f7573e2f))
+
 ## 3.19.1 (2026-02-07)
 
 ### 🐛 Bug Fixes

package/assets/agents/builder.md

@@ -101,13 +101,22 @@ State-of-the-art industrial standard. Every time. Would you stake your reputatio
 
 ## Memory
 
+Two-layer durable memory:
+
+- **`MEMORY.md`** — Curated long-term memory. Decisions, preferences, durable facts.
+- **`memory/YYYY-MM-DD.md`** — Daily log (append-only). Running context, day-to-day notes.
+
+**Rules:**
+- If someone says "remember this," write it down immediately (do not keep it in RAM).
+- Decisions and preferences → `MEMORY.md`
+- Day-to-day notes and running context → `memory/YYYY-MM-DD.md`
+- SessionStart hook auto-loads MEMORY.md + today/yesterday daily logs.
+
 **Atomic commits.** Commit continuously. Each commit = one logical change. Semantic commit messages (feat, fix, docs, refactor, test, chore). This is your memory of what was done.
 
 **Todos.** Use TaskCreate/TaskUpdate to track what needs to be done. This is your memory of what to do.
 
-**CLAUDE.md** — Your persistent memory file. Commands, env setup, architecture decisions, patterns, gotchas. Read first. Summarize, don't append. Remove resolved. Consolidate duplicates.
-
-**Recovery:** Lost context? → `git log`. Forgot next steps? → TaskList.
+**Recovery:** Lost context? → `git log`. Forgot next steps? → TaskList. Need old memories? → read `memory/` directory.
 
 ## Issue Ownership
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sylphx/flow",
-	"version": "3.19.1",
+	"version": "3.20.0",
 	"description": "One CLI to rule them all. Unified orchestration layer for AI coding assistants. Auto-detection, auto-installation, auto-upgrade.",
 	"type": "module",
 	"bin": {

package/src/commands/hook-command.ts

@@ -1,27 +1,50 @@
 #!/usr/bin/env node
 /**
- * Hook command - OS notification for Claude Code startup
+ * Hook command - Claude Code hook handlers
  *
- * Purpose: Send OS-level notifications when Claude Code starts
+ * Purpose: Handle Claude Code lifecycle hooks:
+ * - notification: OS-level notification when Claude Code starts
+ * - session-start: Load durable memory (MEMORY.md + recent daily logs)
  *
  * DESIGN RATIONALE:
- * - Simple notification: Just notify user when Claude Code is ready
- * - Cross-platform: Supports macOS, Linux, and Windows
- * - Non-intrusive: Fails silently if notification system not available
+ * - Each hook type returns content to stdout (Claude Code injects as context)
+ * - Cross-platform notifications (macOS, Linux, Windows)
+ * - SessionStart hook loads cross-session memory at startup
  */
 
 import { exec } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
 import os from 'node:os';
+import path from 'node:path';
 import { promisify } from 'node:util';
 import { Command } from 'commander';
 import { cli } from '../utils/display/cli-output.js';
 
+/**
+ * Hook input from Claude Code via stdin.
+ * Claude Code sends JSON context about the event — we read what we need.
+ */
+interface HookInput {
+  /** Notification message text */
+  message?: string;
+  /** Notification title */
+  title?: string;
+  /** Notification type (permission_prompt, idle_prompt, etc.) */
+  notification_type?: string;
+  /** How the session started (startup, resume, clear, compact) */
+  source?: string;
+  /** Current working directory */
+  cwd?: string;
+}
+
 const execAsync = promisify(exec);
 
 /**
- * Hook types supported
+ * Hook types supported — single source of truth for both type and runtime validation
  */
-type HookType = 'notification';
+const VALID_HOOK_TYPES = ['notification', 'session-start'] as const;
+type HookType = (typeof VALID_HOOK_TYPES)[number];
+const VALID_HOOK_TYPE_SET = new Set<string>(VALID_HOOK_TYPES);
 
 /**
  * Target platforms supported
@@ -32,18 +55,20 @@ type TargetPlatform = 'claude-code';
  * Create the hook command
  */
 export const hookCommand = new Command('hook')
-  .description('Load dynamic system information for Claude Code hooks')
-  .requiredOption('--type <type>', 'Hook type (notification)')
+  .description('Handle Claude Code lifecycle hooks (notification, memory)')
+  .requiredOption('--type <type>', 'Hook type (notification | session-start)')
   .option('--target <target>', 'Target platform (claude-code)', 'claude-code')
   .option('--verbose', 'Show verbose output', false)
   .action(async (options) => {
     try {
-      const hookType = options.type as HookType;
+      const hookType = options.type as string;
       const target = options.target as TargetPlatform;
 
       // Validate hook type
-      if (hookType !== 'notification') {
-        throw new Error(`Invalid hook type: ${hookType}. Must be 'notification'`);
+      if (!VALID_HOOK_TYPE_SET.has(hookType)) {
+        throw new Error(
+          `Invalid hook type: ${hookType}. Must be one of: ${VALID_HOOK_TYPES.join(', ')}`
+        );
       }
 
       // Validate target
@@ -51,8 +76,11 @@ export const hookCommand = new Command('hook')
         throw new Error(`Invalid target: ${target}. Only 'claude-code' is currently supported`);
       }
 
+      // Read hook input from stdin (Claude Code passes JSON context)
+      const hookInput = await readStdinInput();
+
       // Load and display content based on hook type
-      const content = await loadHookContent(hookType, target, options.verbose);
+      const content = await loadHookContent(hookType as HookType, target, hookInput, options.verbose);
 
       // Output the content (no extra formatting, just the content)
       console.log(content);
@@ -72,27 +100,140 @@ export const hookCommand = new Command('hook')
     }
   });
 
+/**
+ * Read JSON input from stdin (non-blocking, returns empty object if no input)
+ * Claude Code sends event context as JSON on stdin for all hook types.
+ */
+async function readStdinInput(): Promise<HookInput> {
+  // stdin is not a TTY when piped from Claude Code
+  if (process.stdin.isTTY) {
+    return {};
+  }
+
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on('end', () => {
+      if (!data.trim()) {
+        resolve({});
+        return;
+      }
+      try {
+        resolve(JSON.parse(data) as HookInput);
+      } catch {
+        resolve({});
+      }
+    });
+    // Safety timeout — don't hang if stdin never closes
+    setTimeout(() => resolve({}), 1000);
+  });
+}
+
 /**
  * Load content for a specific hook type and target
  */
 async function loadHookContent(
   hookType: HookType,
   _target: TargetPlatform,
+  input: HookInput,
   verbose: boolean = false
 ): Promise<string> {
-  if (hookType === 'notification') {
-    return await sendNotification(verbose);
+  switch (hookType) {
+    case 'notification':
+      return await sendNotification(input, verbose);
+    case 'session-start':
+      return await loadSessionStartContent(verbose);
+  }
+}
+
+/**
+ * Read a file and return its contents, or empty string if not found
+ */
+async function readFileIfExists(filePath: string): Promise<string> {
+  try {
+    return await readFile(filePath, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Format a date as YYYY-MM-DD
+ */
+function formatDate(date: Date): string {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
+/**
+ * Load memory files for session start:
+ * - MEMORY.md (curated long-term memory)
+ * - memory/{today}.md (today's daily log)
+ * - memory/{yesterday}.md (yesterday's daily log)
+ *
+ * Returns concatenated content to stdout for Claude Code context injection
+ */
+async function loadSessionStartContent(verbose: boolean): Promise<string> {
+  const cwd = process.cwd();
+  const sections: string[] = [];
+
+  // Load MEMORY.md
+  const memoryPath = path.join(cwd, 'MEMORY.md');
+  const memoryContent = await readFileIfExists(memoryPath);
+  if (memoryContent.trim()) {
+    sections.push(`## MEMORY.md\n${memoryContent.trim()}`);
+    if (verbose) {
+      cli.info('Loaded MEMORY.md');
+    }
+  }
+
+  // Calculate today and yesterday dates
+  const today = new Date();
+  const yesterday = new Date(today);
+  yesterday.setDate(yesterday.getDate() - 1);
+
+  const todayStr = formatDate(today);
+  const yesterdayStr = formatDate(yesterday);
+
+  // Load today's daily log
+  const todayPath = path.join(cwd, 'memory', `${todayStr}.md`);
+  const todayContent = await readFileIfExists(todayPath);
+  if (todayContent.trim()) {
+    sections.push(`## memory/${todayStr}.md\n${todayContent.trim()}`);
+    if (verbose) {
+      cli.info(`Loaded memory/${todayStr}.md`);
+    }
+  }
+
+  // Load yesterday's daily log
+  const yesterdayPath = path.join(cwd, 'memory', `${yesterdayStr}.md`);
+  const yesterdayContent = await readFileIfExists(yesterdayPath);
+  if (yesterdayContent.trim()) {
+    sections.push(`## memory/${yesterdayStr}.md\n${yesterdayContent.trim()}`);
+    if (verbose) {
+      cli.info(`Loaded memory/${yesterdayStr}.md`);
+    }
+  }
+
+  if (verbose && sections.length === 0) {
+    cli.info('No memory files found');
   }
 
-  return '';
+  return sections.join('\n\n');
 }
 
 /**
- * Send OS-level notification
+ * Send OS-level notification using event data from Claude Code.
+ * Falls back to generic message when stdin input is missing.
  */
-async function sendNotification(verbose: boolean): Promise<string> {
-  const title = '🔮 Sylphx Flow';
-  const message = 'Claude Code is ready';
+async function sendNotification(input: HookInput, verbose: boolean): Promise<string> {
+  const title = input.title || '🔮 Sylphx Flow';
+  const message = input.message || 'Claude Code is ready';
   const platform = os.platform();
 
   if (verbose) {

package/src/targets/functional/claude-code-logic.ts

@@ -66,6 +66,7 @@ const DEFAULT_CLAUDE_CODE_SETTINGS: Partial<ClaudeCodeSettings> = {
 
 export interface HookConfig {
   notificationCommand?: string;
+  sessionStartCommand?: string;
 }
 
 /**
@@ -75,15 +76,16 @@ export interface HookConfig {
 export const generateHookCommands = async (targetId: string): Promise<HookConfig> => {
   return {
     notificationCommand: `sylphx-flow hook --type notification --target ${targetId}`,
+    sessionStartCommand: `sylphx-flow hook --type session-start --target ${targetId}`,
   };
 };
 
 /**
  * Default hook commands (fallback)
- * Simplified to only include notification hook
  */
 const DEFAULT_HOOKS: HookConfig = {
   notificationCommand: 'sylphx-flow hook --type notification --target claude-code',
+  sessionStartCommand: 'sylphx-flow hook --type session-start --target claude-code',
 };
 
 /**
@@ -94,17 +96,19 @@ export const processSettings = (
   hookConfig: HookConfig = DEFAULT_HOOKS
 ): Result<string, ConfigError> => {
   const notificationCommand = hookConfig.notificationCommand || DEFAULT_HOOKS.notificationCommand!;
+  const sessionStartCommand = hookConfig.sessionStartCommand || DEFAULT_HOOKS.sessionStartCommand!;
 
   const hookConfiguration: ClaudeCodeSettings['hooks'] = {
     Notification: [
       {
         matcher: '',
-        hooks: [
-          {
-            type: 'command',
-            command: notificationCommand,
-          },
-        ],
+        hooks: [{ type: 'command', command: notificationCommand }],
+      },
+    ],
+    SessionStart: [
+      {
+        matcher: '',
+        hooks: [{ type: 'command', command: sessionStartCommand }],
       },
     ],
   };