tsunami-code 2.5.3 → 2.6.0

package/.tsunami/README.md

@@ -0,0 +1,10 @@
+# .tsunami/ — Project Memory
+
+Auto-managed by Tsunami Code CLI. Safe to commit.
+
+## Structure
+- `memory/` — Per-file notes and change history
+- `decisions/` — Team-shared decision log by date
+- `CODEBASE.md` — High-level project understanding
+
+Do not edit manually unless you know what you're doing.

package/index.js

@@ -7,8 +7,20 @@ import os from 'os';
 import { agentLoop } from './lib/loop.js';
 import { buildSystemPrompt } from './lib/prompt.js';
 import { runPreflight } from './lib/preflight.js';
-
-const VERSION = '2.5.3';
+import { setSession } from './lib/tools.js';
+import {
+  initSession,
+  initProjectMemory,
+  getLastSessionSummary,
+  endSession,
+  getMemoryStats,
+  listFileMemories,
+  getFileMemory,
+  getRecentDecisions,
+  getSessionContext
+} from './lib/memory.js';
+
+const VERSION = '2.6.0';
 const CONFIG_DIR = join(os.homedir(), '.tsunami-code');
 const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
 const DEFAULT_SERVER = 'https://radiometric-reita-amuck.ngrok-free.dev';
@@ -27,7 +39,6 @@ function saveConfig(cfg) {
 }
 
 function getServerUrl(argv) {
-  // Priority: --server flag > KEYSTONE_SERVER env var > saved config > default
   const flagIdx = argv.indexOf('--server');
   if (flagIdx !== -1 && argv[flagIdx + 1]) return argv[flagIdx + 1];
   if (process.env.TSUNAMI_SERVER) return process.env.TSUNAMI_SERVER;
@@ -43,6 +54,7 @@ const cyan = (s) => chalk.cyan(s);
 const red = (s) => chalk.red(s);
 const green = (s) => chalk.green(s);
 const yellow = (s) => chalk.yellow(s);
+const blue = (s) => chalk.blue(s);
 
 function printBanner(serverUrl) {
   console.log(cyan(bold('\n  🌊 Tsunami Code CLI')) + dim(` v${VERSION}`));
@@ -59,6 +71,12 @@ function printToolCall(name, args) {
   process.stdout.write('\n' + dim(`  ⚙ ${name}(${preview})\n`));
 }
 
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / 1024 / 1024).toFixed(2)}MB`;
+}
+
 // ── CLI Parsing ───────────────────────────────────────────────────────────────
 const argv = process.argv.slice(2);
 
@@ -84,6 +102,12 @@ if (argv.includes('--help') || argv.includes('-h')) {
   ${bold('Global config:')}
     ~/.tsunami-code/TSUNAMI.md — applies to all projects.
 
+  ${bold('Memory commands:')}
+    /memory           Show memory stats
+    /memory files     List files with memory entries
+    /memory view <f>  Show memory for a specific file
+    /memory clear     Clear session memory (keep project memory)
+
   ${bold('Settings:')}
     ${CONFIG_FILE}
   `);
@@ -108,6 +132,12 @@ if (setServerIdx !== -1 && argv[setServerIdx + 1]) {
 // ── Main ──────────────────────────────────────────────────────────────────────
 async function run() {
   const serverUrl = getServerUrl(argv);
+  const cwd = process.cwd();
+
+  // Initialize memory systems
+  const { sessionId, sessionDir } = initSession(cwd);
+  initProjectMemory(cwd);
+  setSession({ sessionDir, cwd });
 
   printBanner(serverUrl);
 
@@ -127,7 +157,13 @@ async function run() {
     process.exit(1);
   }
 
-  console.log(green('  ✓ Connected') + dim(' · Type your task. /help for commands. Ctrl+C to exit.\n'));
+  console.log(
+    green('  ✓ Connected') +
+    dim(` · ${sessionId} · Type your task. /help for commands. Ctrl+C to exit.\n`)
+  );
+
+  // Load last session summary if available
+  const lastSessionSummary = getLastSessionSummary(cwd);
 
   let currentServerUrl = serverUrl;
   let messages = [];
@@ -138,6 +174,15 @@ async function run() {
     systemPrompt = buildSystemPrompt();
   }
 
+  /** Trim messages to the last N entries (rolling window) */
+  function trimMessages(msgs, maxEntries = 8) {
+    // Always keep system message (index 0)
+    if (msgs.length <= maxEntries + 1) return msgs;
+    const system = msgs[0];
+    const rest = msgs.slice(1);
+    return [system, ...rest.slice(-maxEntries)];
+  }
+
   const rl = readline.createInterface({
     input: process.stdin,
     output: process.stdout,
@@ -150,25 +195,108 @@ async function run() {
   let isProcessing = false;
   let pendingClose = false;
 
+  // ── Exit handler ─────────────────────────────────────────────────────────────
+  function gracefulExit(code = 0) {
+    try {
+      endSession(sessionDir);
+    } catch {}
+    console.log(dim('\n  Goodbye.\n'));
+    process.exit(code);
+  }
+
   rl.on('close', () => {
     if (isProcessing) { pendingClose = true; return; }
-    console.log(dim('\n  Goodbye.\n'));
-    process.exit(0);
+    gracefulExit(0);
   });
 
+  // ── Memory commands ───────────────────────────────────────────────────────────
+  async function handleMemoryCommand(args) {
+    const sub = args[0]?.toLowerCase();
+
+    if (!sub) {
+      // /memory — show stats
+      const stats = getMemoryStats(cwd);
+      console.log(blue('\n  Living Memory Stats'));
+      console.log(dim(`  Project memory files : ${stats.projectMemoryFiles}`));
+      console.log(dim(`  Project memory size  : ${formatBytes(stats.projectMemorySize)}`));
+      console.log(dim(`  CODEBASE.md          : ${stats.hasCODEBASE ? 'exists' : 'none'}`));
+      console.log(dim(`  Sessions this dir    : ${stats.sessionCount}`));
+      console.log(dim(`  Current session      : ${sessionId}`));
+      console.log();
+      return;
+    }
+
+    if (sub === 'files') {
+      const files = listFileMemories(cwd);
+      if (files.length === 0) {
+        console.log(dim('  No file memories yet.\n'));
+      } else {
+        console.log(blue(`\n  Files with memory (${files.length}):`));
+        for (const f of files) console.log(dim(`    ${f}`));
+        console.log();
+      }
+      return;
+    }
+
+    if (sub === 'view') {
+      const filePath = args.slice(1).join(' ');
+      if (!filePath) {
+        console.log(red('  Usage: /memory view <filepath>\n'));
+        return;
+      }
+      const mem = getFileMemory(cwd, filePath);
+      if (!mem) {
+        console.log(dim(`  No memory for: ${filePath}\n`));
+      } else {
+        console.log(blue(`\n  Memory: ${filePath}`));
+        console.log(dim('  ' + mem.replace(/\n/g, '\n  ')));
+        console.log();
+      }
+      return;
+    }
+
+    if (sub === 'clear') {
+      // Reinitialize session (clear session memory, keep project memory)
+      resetSession();
+      console.log(green('  Session memory cleared. Project memory preserved.\n'));
+      return;
+    }
+
+    if (sub === 'context') {
+      // Debug: show current session context
+      const ctx = getSessionContext(sessionDir);
+      const decisions = getRecentDecisions(sessionDir, 10);
+      console.log(blue('\n  Current Session Context:'));
+      console.log(dim('  ' + (ctx || '(empty)').replace(/\n/g, '\n  ')));
+      console.log(blue('\n  Recent Decisions:'));
+      console.log(dim('  ' + (decisions || '(none)').replace(/\n/g, '\n  ')));
+      console.log();
+      return;
+    }
+
+    console.log(red(`  Unknown memory subcommand: ${sub}\n  Try: /memory, /memory files, /memory view <file>, /memory clear\n`));
+  }
+
   rl.on('line', async (input) => {
     const line = input.trim();
     if (!line) { rl.prompt(); return; }
 
     if (line.startsWith('/')) {
-      const [cmd, ...rest] = line.slice(1).split(' ');
-      switch (cmd.toLowerCase()) {
+      const parts = line.slice(1).split(' ');
+      const cmd = parts[0].toLowerCase();
+      const rest = parts.slice(1);
+
+      switch (cmd) {
         case 'help':
           console.log(dim(`
   Commands:
     /clear            Start new conversation
     /status           Show context size
     /server <url>     Change server URL for this session
+    /memory           Show memory stats
+    /memory files     List files with memory entries
+    /memory view <f>  Show memory for a file
+    /memory clear     Clear session memory (keep project memory)
     /exit             Exit
 `));
           break;
@@ -187,8 +315,12 @@ async function run() {
             console.log(dim(`  Current server: ${currentServerUrl}\n`));
           }
           break;
+        case 'memory':
+          await handleMemoryCommand(rest);
+          break;
         case 'exit': case 'quit':
-          process.exit(0);
+          gracefulExit(0);
+          return;
         default:
           console.log(red(`  Unknown command: /${cmd}\n`));
       }
@@ -196,12 +328,18 @@ async function run() {
       return;
     }
 
+    // Build the user message, optionally injecting last session summary on first turn
+    let userContent = line;
+    if (messages.length === 0 && lastSessionSummary) {
+      userContent = `[Previous session summary]\n${lastSessionSummary}\n\n---\n\n${line}`;
+    }
+
     const fullMessages = [
       { role: 'system', content: systemPrompt },
       ...messages,
-      { role: 'user', content: line }
+      { role: 'user', content: userContent }
     ];
-    messages.push({ role: 'user', content: line });
+    messages.push({ role: 'user', content: userContent });
 
     rl.pause();
     isProcessing = true;
@@ -219,10 +357,15 @@ async function run() {
         (toolName, toolArgs) => {
           printToolCall(toolName, toolArgs);
           firstToken = true;
-        }
+        },
+        { sessionDir, cwd }
       );
 
-      messages = fullMessages.slice(1);
+      // Update messages from the loop (fullMessages was mutated by agentLoop)
+      // Trim to rolling window: keep system + last 8 entries
+      const loopMessages = fullMessages.slice(1); // drop system, agentLoop added to fullMessages
+      messages = trimMessages([{ role: 'system', content: systemPrompt }, ...loopMessages]).slice(1);
+
       process.stdout.write('\n\n');
     } catch (e) {
       process.stdout.write('\n');
@@ -231,8 +374,8 @@ async function run() {
 
     isProcessing = false;
     if (pendingClose) {
-      console.log(dim('  Goodbye.\n'));
-      process.exit(0);
+      gracefulExit(0);
+      return;
     }
     rl.resume();
     rl.prompt();
@@ -240,8 +383,11 @@ async function run() {
 
   process.on('SIGINT', () => {
     if (!isProcessing) {
-      console.log(dim('\n  Goodbye.\n'));
-      process.exit(0);
+      gracefulExit(0);
+    } else {
+      // If processing, mark pending and let the loop finish
+      pendingClose = true;
+      console.log(dim('\n  (finishing current operation...)\n'));
     }
   });
 }

package/lib/loop.js

@@ -1,5 +1,12 @@
 import fetch from 'node-fetch';
 import { ALL_TOOLS } from './tools.js';
+import {
+  assembleContext,
+  extractFilePaths,
+  logFileAccess,
+  logFileChange,
+  appendDecision
+} from './memory.js';
 
 // Parse tool calls from any format the model might produce
 function parseToolCalls(content) {
@@ -81,12 +88,60 @@ function normalizeArgs(args) {
   return out;
 }
 
-async function runTool(name, args) {
+/**
+ * Detect key patterns in Bash commands and return a decision string, or null.
+ * We log psql, npm, pm2, git, and deploy-related commands.
+ */
+function bashDecisionHint(cmd) {
+  if (!cmd) return null;
+  const c = cmd.trim();
+  if (/psql\s/.test(c)) return `DB: ${c.slice(0, 120)}`;
+  if (/npm\s+(install|run|publish|build)/.test(c)) return `NPM: ${c.slice(0, 120)}`;
+  if (/pm2\s+(restart|stop|start|delete|reload)/.test(c)) return `PM2: ${c.slice(0, 120)}`;
+  if (/git\s+(commit|push|checkout|merge|rebase|reset)/.test(c)) return `GIT: ${c.slice(0, 120)}`;
+  if (/ssh\s+/.test(c)) return `SSH: ${c.slice(0, 80)}`;
+  if (/scp\s+/.test(c)) return `SCP: ${c.slice(0, 80)}`;
+  if (/rm\s+-rf|DROP TABLE|ALTER TABLE|CREATE TABLE/.test(c)) return `DESTRUCTIVE: ${c.slice(0, 120)}`;
+  return null;
+}
+
+async function runTool(name, args, sessionInfo) {
   const tool = ALL_TOOLS.find(t => t.name === name);
   if (!tool) return `Error: Unknown tool "${name}"`;
   try {
     const parsed = typeof args === 'string' ? JSON.parse(args) : args;
-    return await tool.run(normalizeArgs(parsed));
+    const normalized = normalizeArgs(parsed);
+
+    // Auto-capture memory BEFORE running the tool (for access/change logging)
+    if (sessionInfo) {
+      const { sessionDir, cwd } = sessionInfo;
+      try {
+        if (name === 'Read' && normalized.file_path) {
+          logFileAccess(cwd, normalized.file_path);
+        }
+      } catch {}
+    }
+
+    const result = await tool.run(normalized);
+
+    // Auto-capture memory AFTER running the tool
+    if (sessionInfo) {
+      const { sessionDir, cwd } = sessionInfo;
+      try {
+        if (name === 'Write' && normalized.file_path) {
+          const lines = (normalized.content || '').split('\n').length;
+          logFileChange(cwd, normalized.file_path, `Written ${lines} lines`);
+        } else if (name === 'Edit' && normalized.file_path) {
+          const preview = (normalized.old_string || '').slice(0, 60).replace(/\n/g, '↵');
+          logFileChange(cwd, normalized.file_path, `Edited: replaced "${preview}"`);
+        } else if (name === 'Bash') {
+          const hint = bashDecisionHint(normalized.command);
+          if (hint) appendDecision(sessionDir, hint);
+        }
+      } catch {}
+    }
+
+    return result;
   } catch (e) {
     return `Error executing ${name}: ${e.message}`;
   }
@@ -104,14 +159,30 @@ async function waitForServer(serverUrl, retries = 10, delay = 2000) {
   throw new Error(`Model server not responding at ${serverUrl}`);
 }
 
-async function streamCompletion(serverUrl, messages, onToken) {
+/**
+ * Stream a completion from the model server.
+ * Injects memoryContext into the system message if provided.
+ */
+async function streamCompletion(serverUrl, messages, onToken, memoryContext = '') {
   await waitForServer(serverUrl, 5, 1000);
+
+  // Inject memory context into the system message (first message with role=system)
+  let finalMessages = messages;
+  if (memoryContext) {
+    finalMessages = messages.map((msg, idx) => {
+      if (idx === 0 && msg.role === 'system') {
+        return { ...msg, content: msg.content + memoryContext };
+      }
+      return msg;
+    });
+  }
+
   const res = await fetch(`${serverUrl}/v1/chat/completions`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({
       model: 'local',
-      messages,
+      messages: finalMessages,
       stream: true,
       temperature: 0.1,
       max_tokens: 4096,
@@ -146,20 +217,65 @@ async function streamCompletion(serverUrl, messages, onToken) {
   return fullContent;
 }
 
-export async function agentLoop(serverUrl, messages, onToken, onToolCall, maxIterations = 15) {
+/**
+ * Main agent loop.
+ *
+ * @param {string} serverUrl
+ * @param {Array} messages  — full message array including system prompt at index 0
+ * @param {Function} onToken
+ * @param {Function} onToolCall
+ * @param {{ sessionDir: string, cwd: string } | null} sessionInfo
+ * @param {number} maxIterations
+ */
+export async function agentLoop(serverUrl, messages, onToken, onToolCall, sessionInfo = null, maxIterations = 15) {
+  // Extract the current task from the last user message for context assembly
+  const lastUserMsg = [...messages].reverse().find(m => m.role === 'user');
+  const currentTask = typeof lastUserMsg?.content === 'string' ? lastUserMsg.content : '';
+
   for (let i = 0; i < maxIterations; i++) {
-    const content = await streamCompletion(serverUrl, messages, onToken);
+    // Assemble memory context before each model call
+    let memoryContext = '';
+    if (sessionInfo) {
+      try {
+        const filesToConsider = extractFilePaths(currentTask);
+        memoryContext = assembleContext({
+          sessionDir: sessionInfo.sessionDir,
+          cwd: sessionInfo.cwd,
+          currentTask,
+          filesToConsider
+        });
+      } catch {}
+    }
+
+    const content = await streamCompletion(serverUrl, messages, onToken, memoryContext);
     const toolCalls = parseToolCalls(content);
 
     messages.push({ role: 'assistant', content });
 
-    if (toolCalls.length === 0) break;
+    if (toolCalls.length === 0) {
+      // Log final assistant response as a decision if it's substantive
+      if (sessionInfo && content.length > 50) {
+        try {
+          const summary = content.slice(0, 150).replace(/\n/g, ' ');
+          appendDecision(sessionInfo.sessionDir, `RESPONSE: ${summary}`);
+        } catch {}
+      }
+      break;
+    }
 
     const results = [];
     for (const tc of toolCalls) {
       onToolCall(tc.name, typeof tc.arguments === 'string' ? tc.arguments : JSON.stringify(tc.arguments));
-      const result = await runTool(tc.name, tc.arguments);
+      const result = await runTool(tc.name, tc.arguments, sessionInfo);
       results.push(`[${tc.name} result]\n${String(result).slice(0, 8000)}`);
+
+      // Log tool execution as a decision entry
+      if (sessionInfo) {
+        try {
+          const argsPreview = JSON.stringify(tc.arguments || {}).slice(0, 80);
+          appendDecision(sessionInfo.sessionDir, `TOOL ${tc.name}: ${argsPreview}`);
+        } catch {}
+      }
     }
 
     messages.push({

package/lib/memory.js

@@ -0,0 +1,493 @@
+/**
+ * Living Memory Engine — Tsunami Code CLI v2.6.0
+ *
+ * Three-layer persistent memory that eliminates the context window problem.
+ * All writes are silent-fail — memory must never crash the agent.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from 'fs';
+import { join, relative, dirname, sep } from 'path';
+import { createHash } from 'crypto';
+import os from 'os';
+
+const CONFIG_DIR = join(os.homedir(), '.tsunami-code');
+const SESSIONS_DIR = join(CONFIG_DIR, 'sessions');
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function safeRead(filePath, fallback = '') {
+  try {
+    if (!existsSync(filePath)) return fallback;
+    return readFileSync(filePath, 'utf8');
+  } catch {
+    return fallback;
+  }
+}
+
+function safeWrite(filePath, content) {
+  try {
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(filePath, content, 'utf8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function safeAppend(filePath, line) {
+  try {
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const existing = safeRead(filePath, '');
+    writeFileSync(filePath, existing + line, 'utf8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Normalize a file path to a relative, forward-slash key safe for filenames */
+function normalizeFilePath(cwd, filePath) {
+  try {
+    const rel = relative(cwd, filePath).split(sep).join('/');
+    // Strip leading ../ — if truly outside cwd, use the basename
+    return rel.startsWith('../') ? filePath.split(sep).pop() : rel;
+  } catch {
+    return filePath.split(sep).pop() || filePath;
+  }
+}
+
+/** Convert a relative path into a safe filesystem path segment */
+function safePathSegment(relPath) {
+  // Replace path separators and special chars with underscores
+  return relPath.replace(/[\/\\:*?"<>|]/g, '_');
+}
+
+function cwdHash(cwd) {
+  return createHash('sha1').update(cwd).digest('hex').slice(0, 12);
+}
+
+function dateId() {
+  const now = new Date();
+  const d = now.toISOString().split('T')[0];
+  const t = now.toTimeString().slice(0, 8).replace(/:/g, '');
+  return `${d}_${t}`;
+}
+
+function now() {
+  return new Date().toISOString();
+}
+
+/** Truncate a string to approximately maxChars, preserving whole lines */
+function truncate(str, maxChars) {
+  if (str.length <= maxChars) return str;
+  // Keep the last maxChars characters (most recent content is most relevant)
+  const truncated = str.slice(str.length - maxChars);
+  const firstNewline = truncated.indexOf('\n');
+  return firstNewline > 0 ? '...[truncated]\n' + truncated.slice(firstNewline + 1) : '...[truncated]\n' + truncated;
+}
+
+// ── Layer 2: Session Memory ───────────────────────────────────────────────────
+
+/**
+ * Initialize a new session for the given working directory.
+ * Creates: ~/.tsunami-code/sessions/[cwd-hash]/[date-id]/
+ * Returns { sessionId, sessionDir }
+ */
+export function initSession(cwd) {
+  try {
+    const hash = cwdHash(cwd);
+    const id = dateId();
+    const sessionId = `${hash}-${id}`;
+    const sessionDir = join(SESSIONS_DIR, hash, id);
+    if (!existsSync(sessionDir)) mkdirSync(sessionDir, { recursive: true });
+    // Write initial context placeholder
+    safeWrite(join(sessionDir, 'context.md'), `# Session Context\nStarted: ${now()}\nCWD: ${cwd}\n\n_No checkpoint yet._\n`);
+    safeWrite(join(sessionDir, 'decisions.log'), `# Decisions Log\nSession: ${sessionId}\nStarted: ${now()}\n\n`);
+    return { sessionId, sessionDir };
+  } catch (e) {
+    // Fallback: use a temp session dir that won't crash anything
+    const fallback = join(os.tmpdir(), `tsunami-session-${Date.now()}`);
+    try { mkdirSync(fallback, { recursive: true }); } catch {}
+    return { sessionId: `fallback-${Date.now()}`, sessionDir: fallback };
+  }
+}
+
+/** Update the current session's context.md with task progress */
+export function updateContext(sessionDir, content) {
+  try {
+    const header = `# Session Context\nUpdated: ${now()}\n\n`;
+    safeWrite(join(sessionDir, 'context.md'), header + content);
+  } catch {}
+}
+
+/** Append a decision entry (append-only, timestamped) */
+export function appendDecision(sessionDir, decision) {
+  try {
+    safeAppend(join(sessionDir, 'decisions.log'), `[${now()}] ${decision}\n`);
+  } catch {}
+}
+
+/** Read the current session context */
+export function getSessionContext(sessionDir) {
+  return safeRead(join(sessionDir, 'context.md'), '');
+}
+
+/** Read the last N decisions from the log */
+export function getRecentDecisions(sessionDir, n = 5) {
+  const raw = safeRead(join(sessionDir, 'decisions.log'), '');
+  const lines = raw.split('\n').filter(l => l.startsWith('['));
+  return lines.slice(-n).join('\n');
+}
+
+/**
+ * Get the most recent session summary from a prior session for this cwd.
+ * Returns empty string if none exists.
+ */
+export function getLastSessionSummary(cwd) {
+  try {
+    const hash = cwdHash(cwd);
+    const hashDir = join(SESSIONS_DIR, hash);
+    if (!existsSync(hashDir)) return '';
+
+    const sessions = readdirSync(hashDir)
+      .filter(d => existsSync(join(hashDir, d, 'summary.md')))
+      .sort()
+      .reverse();
+
+    if (sessions.length === 0) return '';
+    return safeRead(join(hashDir, sessions[0], 'summary.md'), '');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * End a session: auto-generate summary.md from decisions.log + context.md.
+ * Produces useful output even with zero model cooperation.
+ */
+export function endSession(sessionDir) {
+  try {
+    const context = safeRead(join(sessionDir, 'context.md'), '');
+    const decisions = safeRead(join(sessionDir, 'decisions.log'), '');
+
+    const decisionLines = decisions.split('\n').filter(l => l.startsWith('['));
+    const decisionCount = decisionLines.length;
+
+    // Extract last checkpoint content (between first and second # heading or all)
+    const contextBody = context.replace(/^# Session Context\n.*\n\n/, '').trim();
+
+    const summary = [
+      `# Session Summary`,
+      `Generated: ${now()}`,
+      ``,
+      `## Task State`,
+      contextBody || '_No checkpoint was saved this session._',
+      ``,
+      `## Decisions Made (${decisionCount} total)`,
+      decisionCount > 0
+        ? decisionLines.slice(-20).join('\n')
+        : '_No decisions logged._',
+      ``,
+      `## Session End`,
+      `Ended: ${now()}`,
+    ].join('\n');
+
+    safeWrite(join(sessionDir, 'summary.md'), summary);
+  } catch {}
+}
+
+// ── Layer 3: Project Memory ───────────────────────────────────────────────────
+
+/** Initialize .tsunami/ project memory structure. Idempotent. */
+export function initProjectMemory(cwd) {
+  try {
+    const tsunamiDir = join(cwd, '.tsunami');
+    const memoryDir = join(tsunamiDir, 'memory');
+    const decisionsDir = join(tsunamiDir, 'decisions');
+
+    for (const dir of [tsunamiDir, memoryDir, decisionsDir]) {
+      if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    }
+
+    const readmePath = join(tsunamiDir, 'README.md');
+    if (!existsSync(readmePath)) {
+      safeWrite(readmePath, [
+        `# .tsunami/ — Project Memory`,
+        ``,
+        `Auto-managed by Tsunami Code CLI. Safe to commit.`,
+        ``,
+        `## Structure`,
+        `- \`memory/\` — Per-file notes and change history`,
+        `- \`decisions/\` — Team-shared decision log by date`,
+        `- \`CODEBASE.md\` — High-level project understanding`,
+        ``,
+        `Do not edit manually unless you know what you're doing.`,
+      ].join('\n'));
+    }
+  } catch {}
+}
+
+/** Get the path to a file's memory file in .tsunami/memory/ */
+function fileMemoryPath(cwd, filePath) {
+  const rel = normalizeFilePath(cwd, filePath);
+  const segment = safePathSegment(rel);
+  return join(cwd, '.tsunami', 'memory', `${segment}.md`);
+}
+
+/**
+ * Add a permanent note about a file to project memory.
+ * filePath: absolute or relative. Use null/undefined for project-wide notes (→ CODEBASE.md).
+ */
+export function addFileNote(cwd, filePath, note) {
+  try {
+    if (!filePath) {
+      // Project-wide note → CODEBASE.md
+      const codebasePath = join(cwd, '.tsunami', 'CODEBASE.md');
+      const existing = safeRead(codebasePath, '# Project Notes\n\n');
+      safeWrite(codebasePath, existing + `\n## [${now()}]\n${note}\n`);
+      return;
+    }
+
+    const memPath = fileMemoryPath(cwd, filePath);
+    const rel = normalizeFilePath(cwd, filePath);
+    let existing = safeRead(memPath, '');
+
+    if (!existing) {
+      existing = `# Memory: ${rel}\n\n## Notes\n\n## Changes\n\n## Access Log\n`;
+    }
+
+    // Insert note after ## Notes heading
+    const updated = existing.replace(
+      /## Notes\n/,
+      `## Notes\n\n### [${now()}]\n${note}\n`
+    );
+    safeWrite(memPath, compressIfNeeded(updated));
+  } catch {}
+}
+
+/** Log a file change to project memory */
+export function logFileChange(cwd, filePath, desc) {
+  try {
+    const memPath = fileMemoryPath(cwd, filePath);
+    const rel = normalizeFilePath(cwd, filePath);
+    let existing = safeRead(memPath, '');
+
+    if (!existing) {
+      existing = `# Memory: ${rel}\n\n## Notes\n\n## Changes\n\n## Access Log\n`;
+    }
+
+    const entry = `- [${now()}] ${desc}`;
+    const updated = existing.replace(
+      /## Changes\n/,
+      `## Changes\n${entry}\n`
+    );
+    safeWrite(memPath, compressIfNeeded(updated));
+
+    // Also log to today's team decisions
+    const today = new Date().toISOString().split('T')[0];
+    const decisionsPath = join(cwd, '.tsunami', 'decisions', `${today}.log`);
+    safeAppend(decisionsPath, `[${now()}] CHANGE ${rel}: ${desc}\n`);
+  } catch {}
+}
+
+/** Log a lightweight file access (read) to project memory */
+export function logFileAccess(cwd, filePath) {
+  try {
+    const memPath = fileMemoryPath(cwd, filePath);
+    const rel = normalizeFilePath(cwd, filePath);
+    let existing = safeRead(memPath, '');
+
+    if (!existing) {
+      existing = `# Memory: ${rel}\n\n## Notes\n\n## Changes\n\n## Access Log\n`;
+    }
+
+    // Only log access if this is the first time or add to existing access log (lightweight)
+    const entry = `- [${now()}] Read`;
+    const updated = existing.replace(/## Access Log\n/, `## Access Log\n${entry}\n`);
+    safeWrite(memPath, compressIfNeeded(updated));
+  } catch {}
+}
+
+/** Read memory for a specific file. Returns '' if none exists. */
+export function getFileMemory(cwd, filePath) {
+  try {
+    return safeRead(fileMemoryPath(cwd, filePath), '');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Compress file memory when it exceeds 3KB:
+ * Keep all Notes sections, keep last 5 Changes, drop older access log entries.
+ */
+function compressIfNeeded(content) {
+  const MAX_BYTES = 3 * 1024;
+  if (content.length <= MAX_BYTES) return content;
+
+  try {
+    // Split into sections
+    const notesMatch = content.match(/(## Notes[\s\S]*?)(## Changes)/);
+    const changesMatch = content.match(/(## Changes\n)([\s\S]*?)(## Access Log)/);
+    const header = content.match(/^(# Memory:.*\n)/)?.[1] || '';
+
+    const notesSection = notesMatch ? notesMatch[1] : '## Notes\n\n';
+    let changesContent = changesMatch ? changesMatch[2] : '';
+    const accessSection = '## Access Log\n- [compressed] older entries removed\n';
+
+    // Keep only last 5 change entries
+    const changeLines = changesContent.split('\n').filter(l => l.startsWith('- ['));
+    const keptChanges = changeLines.slice(-5).join('\n') + '\n';
+
+    return `${header}\n${notesSection}## Changes\n${keptChanges}\n${accessSection}`;
+  } catch {
+    // If compression fails, just hard-truncate
+    return content.slice(0, MAX_BYTES);
+  }
+}
+
+// ── Context Assembly ──────────────────────────────────────────────────────────
+
+/**
+ * Extract file paths from text using multiple heuristics.
+ * Returns an array of unique paths.
+ */
+export function extractFilePaths(text) {
+  if (!text) return [];
+  const paths = new Set();
+
+  // Absolute paths (/foo/bar.ts, C:\foo\bar.ts)
+  const absUnix = /(?:^|[\s"'`(])(\/?[\w.-]+(?:\/[\w.-]+)+\.\w+)/gm;
+  const absWin = /[A-Za-z]:\\[\w\\.-]+\.\w+/g;
+  // Relative paths (./foo.ts, ../foo/bar.js)
+  const rel = /(?:^|[\s"'`(])(\.{1,2}\/[\w./\\-]+\.\w+)/gm;
+
+  let m;
+  while ((m = absUnix.exec(text)) !== null) {
+    const p = m[1].trim();
+    if (p.length > 3 && p.includes('.')) paths.add(p);
+  }
+  while ((m = absWin.exec(text)) !== null) {
+    paths.add(m[0].trim());
+  }
+  while ((m = rel.exec(text)) !== null) {
+    paths.add(m[1].trim());
+  }
+
+  return [...paths].slice(0, 20);
+}
+
+/**
+ * Assemble the context string injected into every model call.
+ * Hard budget: stays under ~2,500 tokens (approx 10,000 chars).
+ *
+ * @param {Object} opts
+ * @param {string} opts.sessionDir
+ * @param {string} opts.cwd
+ * @param {string} [opts.currentTask]
+ * @param {string[]} [opts.filesToConsider]
+ * @returns {string}
+ */
+export function assembleContext({ sessionDir, cwd, currentTask = '', filesToConsider = [] }) {
+  try {
+    const parts = [];
+
+    // Session context (~150 tokens / ~600 chars)
+    const sessionCtx = truncate(getSessionContext(sessionDir), 600);
+    if (sessionCtx && !sessionCtx.includes('_No checkpoint yet._')) {
+      parts.push(`<session_context>\n${sessionCtx}\n</session_context>`);
+    }
+
+    // Recent decisions (~100 tokens / ~400 chars)
+    const decisions = getRecentDecisions(sessionDir, 5);
+    if (decisions) {
+      parts.push(`<recent_decisions>\n${decisions}\n</recent_decisions>`);
+    }
+
+    // CODEBASE.md truncated (~300 tokens / ~1,200 chars)
+    const codebasePath = join(cwd, '.tsunami', 'CODEBASE.md');
+    const codebase = truncate(safeRead(codebasePath, ''), 1200);
+    if (codebase && codebase !== '# Project Notes\n\n') {
+      parts.push(`<codebase_knowledge>\n${codebase}\n</codebase_knowledge>`);
+    }
+
+    // File memories for files relevant to current task (max 4 files × ~1,200 chars = 4,800)
+    const allCandidates = [
+      ...filesToConsider,
+      ...extractFilePaths(currentTask)
+    ];
+    const uniqueFiles = [...new Set(allCandidates)].slice(0, 4);
+
+    const fileMemories = [];
+    for (const fp of uniqueFiles) {
+      const mem = getFileMemory(cwd, fp);
+      if (mem && mem.trim()) {
+        const rel = normalizeFilePath(cwd, fp);
+        fileMemories.push(`### ${rel}\n${truncate(mem, 1200)}`);
+      }
+    }
+    if (fileMemories.length > 0) {
+      parts.push(`<file_memories>\n${fileMemories.join('\n\n')}\n</file_memories>`);
+    }
+
+    if (parts.length === 0) return '';
+
+    return `\n<current_memory>\n${parts.join('\n\n')}\n</current_memory>`;
+  } catch {
+    return '';
+  }
+}
+
+// ── Memory Stats & Listing ────────────────────────────────────────────────────
+
+/**
+ * Returns stats about project memory.
+ * @returns {{ projectMemoryFiles: number, projectMemorySize: number, hasCODEBASE: boolean, sessionCount: number }}
+ */
+export function getMemoryStats(cwd) {
+  try {
+    const memDir = join(cwd, '.tsunami', 'memory');
+    const codebasePath = join(cwd, '.tsunami', 'CODEBASE.md');
+    const hash = cwdHash(cwd);
+    const hashDir = join(SESSIONS_DIR, hash);
+
+    let projectMemoryFiles = 0;
+    let projectMemorySize = 0;
+    if (existsSync(memDir)) {
+      const files = readdirSync(memDir).filter(f => f.endsWith('.md'));
+      projectMemoryFiles = files.length;
+      for (const f of files) {
+        try { projectMemorySize += statSync(join(memDir, f)).size; } catch {}
+      }
+    }
+
+    const hasCODEBASE = existsSync(codebasePath);
+
+    let sessionCount = 0;
+    if (existsSync(hashDir)) {
+      sessionCount = readdirSync(hashDir).length;
+    }
+
+    return { projectMemoryFiles, projectMemorySize, hasCODEBASE, sessionCount };
+  } catch {
+    return { projectMemoryFiles: 0, projectMemorySize: 0, hasCODEBASE: false, sessionCount: 0 };
+  }
+}
+
+/**
+ * List all files that have memory entries.
+ * @returns {string[]}
+ */
+export function listFileMemories(cwd) {
+  try {
+    const memDir = join(cwd, '.tsunami', 'memory');
+    if (!existsSync(memDir)) return [];
+    return readdirSync(memDir)
+      .filter(f => f.endsWith('.md'))
+      .map(f => f.slice(0, -3).replace(/_/g, '/'));
+  } catch {
+    return [];
+  }
+}

package/lib/prompt.js

@@ -15,7 +15,11 @@ function loadContextFile() {
   return '';
 }
 
-export function buildSystemPrompt() {
+/**
+ * Build the system prompt.
+ * @param {string} [memoryContext] — assembled memory string from assembleContext()
+ */
+export function buildSystemPrompt(memoryContext = '') {
   const cwd = process.cwd();
   const context = loadContextFile();
 
@@ -27,7 +31,7 @@ To use a tool, output ONLY this format — nothing else before or after the tool
 </tool_call>
 
 After receiving a tool result, continue your response naturally.
-Available tools: Bash, Read, Write, Edit, Glob, Grep. Use them autonomously to complete tasks without asking permission.
+Available tools: Bash, Read, Write, Edit, Glob, Grep, Note, Checkpoint. Use them autonomously to complete tasks without asking permission.
 
 <environment>
 - Working directory: ${cwd}
@@ -43,6 +47,8 @@ Available tools: Bash, Read, Write, Edit, Glob, Grep. Use them autonomously to c
 - **Edit**: Precise string replacements. Preferred for modifying files.
 - **Glob**: Find files by pattern.
 - **Grep**: Search file contents by regex. Always use instead of grep in Bash.
+- **Note**: Save a permanent discovery to project memory (.tsunami/). Use liberally for traps, patterns, architectural decisions.
+- **Checkpoint**: Save current task progress to session memory so work is resumable if the session ends.
 </tools>
 
 <reasoning_protocol>
@@ -58,6 +64,27 @@ When something breaks:
 4. Change one thing at a time
 </reasoning_protocol>
 
+<memory_protocol>
+You have persistent memory across sessions. Use it actively.
+
+**Note tool** — Call this when you discover anything future sessions should know:
+- Traps and footguns: "this column stores seconds not minutes"
+- Schema quirks: "two tables with similar names serve different purposes"
+- Architectural decisions: "portal auth uses portal_sessions, NOT req.session"
+- Patterns: "all routes follow this exact shape"
+- Anything surprising you had to learn the hard way
+
+Examples of excellent notes:
+  Note({ file_path: "/app/server/db.ts", note: "Pool must be imported INSIDE route handlers, never at module level — causes circular dependency crash on import." })
+  Note({ file_path: null, note: "CODEBASE: Two auth systems. Dashboard: req.session.userId. Portal: portal_sessions table. Never mix them." })
+  Note({ file_path: "/app/shared/schema.ts", note: "break_duration is INTEGER SECONDS not minutes. time_entries.status is 'closed' not 'clocked_out'." })
+
+**Checkpoint tool** — Call this after each major step to preserve progress:
+  Checkpoint({ content: "Task: Add pipeline to deals.\n\nDone: schema updated, route written\nNext: wire React component\nContext: pipeline state on deals table, not leads" })
+
+Notes persist permanently in .tsunami/memory/. Checkpoints persist for the session in ~/.tsunami-code/sessions/.
+</memory_protocol>
+
 <behavior>
 - Complete tasks fully without stopping to ask unless genuinely blocked
 - Short user messages = full autonomy, proceed immediately
@@ -74,5 +101,5 @@ When something breaks:
 - Error paths as clear as success paths
 - Parameterized queries only — never concatenate user input into SQL
 - Every protected route: check auth at the top, first line
-</code_quality>${context}`;
+</code_quality>${context}${memoryContext ? `\n\n${memoryContext}` : ''}`;
 }

package/lib/tools.js

@@ -3,9 +3,19 @@ import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { glob } from 'glob';
 import { promisify } from 'util';
 import { getRgPath } from './preflight.js';
+import { addFileNote, updateContext, appendDecision } from './memory.js';
 
 const execAsync = promisify(exec);
 
+// ── Session Context (set by index.js at startup) ──────────────────────────────
+let _sessionDir = null;
+let _cwd = null;
+
+export function setSession({ sessionDir, cwd }) {
+  _sessionDir = sessionDir;
+  _cwd = cwd;
+}
+
 // ── BASH ──────────────────────────────────────────────────────────────────────
 export const BashTool = {
   name: 'Bash',
@@ -203,4 +213,91 @@ export const GrepTool = {
   }
 };
 
-export const ALL_TOOLS = [BashTool, ReadTool, WriteTool, EditTool, GlobTool, GrepTool];
+// ── NOTE ──────────────────────────────────────────────────────────────────────
+export const NoteTool = {
+  name: 'Note',
+  description: `Saves a permanent discovery to project memory (.tsunami/). Use this liberally whenever you find something future sessions must know.
+
+WHEN TO USE (use aggressively):
+- You discover a trap or footgun: "pool import must be inside handler, not module level — causes crash on import cycle"
+- You find a schema quirk: "break_duration column is in SECONDS not minutes — displaying as minutes causes 60x error"
+- You learn an architectural decision: "Two separate tables: app_settings (key/value) and settings (user prefs) — wrong one = silent fail"
+- You understand a pattern: "All portal routes use portal_sessions table, NOT req.session — completely separate auth"
+- You spot a gotcha: "static sitemap.xml in dist/ silently shadows the dynamic /sitemap.xml route after every build"
+- Any decision you made that future Claude should know about
+
+EXAMPLES of excellent notes:
+  Note({ file_path: "server/db.ts", note: "Pool import must be INSIDE each route handler function, never at module level. Import at module level causes circular dependency crash on server start." })
+  Note({ file_path: null, note: "CODEBASE: Two auth systems coexist. Internal dashboard uses req.session.userId. Buyer portal uses portal_sessions table. Never mix them." })
+  Note({ file_path: "shared/schema.ts", note: "time_entries.status uses 'closed' not 'clocked_out'. Querying for clocked_out returns nothing. break_duration is INTEGER SECONDS, not minutes." })
+
+Set file_path to null for project-wide notes (written to CODEBASE.md).`,
+  input_schema: {
+    type: 'object',
+    properties: {
+      file_path: {
+        type: ['string', 'null'],
+        description: 'Absolute path to the file this note is about. null for project-wide notes.'
+      },
+      note: {
+        type: 'string',
+        description: 'The note content. Be specific and concrete — future sessions depend on this.'
+      }
+    },
+    required: ['note']
+  },
+  async run({ file_path, note }) {
+    try {
+      if (!_cwd) return 'Note saved (no project memory initialized yet)';
+      addFileNote(_cwd, file_path || null, note);
+      return `Note saved to project memory${file_path ? ` for ${file_path}` : ' (CODEBASE.md)'}.`;
+    } catch (e) {
+      return `Note recorded (memory write failed silently: ${e.message})`;
+    }
+  }
+};
+
+// ── CHECKPOINT ────────────────────────────────────────────────────────────────
+export const CheckpointTool = {
+  name: 'Checkpoint',
+  description: `Saves current task progress to session memory so work is resumable if the session ends.
+
+Call this after completing each major step. If the user closes and reopens Tsunami Code, the next session will see exactly where you left off.
+
+WHEN TO USE:
+- After completing a significant step in a multi-step task
+- After discovering something important about the task structure
+- Before starting a risky operation (so progress is preserved)
+- When switching between different aspects of a task
+
+The content should be a clear summary of:
+1. What the overall task is
+2. What has been done so far
+3. What the next step is
+4. Any blockers or important context
+
+EXAMPLE:
+  Checkpoint({ content: "Task: Add dispo pipeline tracking to leads table.\n\nDone:\n- Added status column (MATCHING/CONTACTED/INTERESTED/WALKTHROUGH/CONTRACTED/CLOSED)\n- Updated shared/schema.ts with new enum\n- Route GET /api/deals/pipeline written and tested\n\nNext: Wire up the React frontend pipeline component to the new route.\n\nContext: The deals table has a lead_id FK — pipeline state lives on deals, not leads." })`,
+  input_schema: {
+    type: 'object',
+    properties: {
+      content: {
+        type: 'string',
+        description: 'Task progress summary: what was done, what is next, key context.'
+      }
+    },
+    required: ['content']
+  },
+  async run({ content }) {
+    try {
+      if (!_sessionDir) return 'Checkpoint saved (no session initialized yet)';
+      updateContext(_sessionDir, content);
+      appendDecision(_sessionDir, `CHECKPOINT: ${content.split('\n')[0]}`);
+      return 'Checkpoint saved to session memory.';
+    } catch (e) {
+      return `Checkpoint recorded (memory write failed silently: ${e.message})`;
+    }
+  }
+};
+
+export const ALL_TOOLS = [BashTool, ReadTool, WriteTool, EditTool, GlobTool, GrepTool, NoteTool, CheckpointTool];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tsunami-code",
-  "version": "2.5.3",
+  "version": "2.6.0",
   "description": "Tsunami Code CLI — AI coding agent by Keystone World Management Navy Seal Unit XI3",
   "type": "module",
   "bin": {