memoir-cli 3.9.0 → 3.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memoir-cli",
-  "version": "3.9.0",
+  "version": "3.10.0",
   "mcpName": "io.github.camgitt/memoir",
   "description": "Private, portable AI memory: synced across every coding tool and machine, end-to-end encrypted, free. One memory for Claude Code, Cursor, Copilot, Gemini + more — MCP-native, zero-knowledge, open source.",
   "main": "src/index.js",
@@ -30,7 +30,7 @@
     "start": "node bin/memoir.js",
     "test": "node run-tests.mjs",
     "test:legacy": "bash test-local.sh",
-    "prepublishOnly": "npm test",
+    "prepublishOnly": "node scripts/check-clean-for-publish.mjs && npm test",
     "postinstall": "node -e \"try{const c='\\x1b[36m',r='\\x1b[0m',g='\\x1b[90m';console.log('\\n  '+c+'memoir'+r+' installed.\\n  Run '+c+'memoir activate'+r+' in any project to give your AI long-term memory.\\n  '+g+'https://memoir.sh'+r+'\\n')}catch{}\""
   },
   "keywords": [
@@ -73,7 +73,7 @@
   "author": "camgitt",
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.28.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "boxen": "^7.1.1",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",

package/src/adapters/index.js

@@ -4,18 +4,12 @@ import path from 'path';
 import os from 'os';
 import chalk from 'chalk';
 import { shouldIgnoreProject } from '../context/capture.js';
-import { vscodeUserDir, vscodeGlobalStorage } from '../utils/platform.js';
 
 const home = os.homedir();
 
 const isWin = process.platform === 'win32';
 const appData = process.env.APPDATA || path.join(home, 'AppData', 'Roaming');
 
-// VS Code-family config dirs — resolved per-OS (incl. Linux) via platform.js.
-const cursorUserDir = vscodeUserDir('Cursor');
-const windsurfUserDir = vscodeUserDir('Windsurf');
-const clineStorageDir = vscodeGlobalStorage('saoudrizwan.claude-dev');
-
 export const adapters = [
   {
     name: 'Gemini CLI',
@@ -84,9 +78,13 @@ export const adapters = [
   {
     name: 'Cursor',
     icon: '⚡',
-    source: cursorUserDir,
+    source: isWin
+      ? path.join(appData, 'Cursor', 'User')
+      : path.join(home, 'Library', 'Application Support', 'Cursor', 'User'),
     filter: (src) => {
-      const cursorDir = cursorUserDir;
+      const cursorDir = isWin
+        ? path.join(appData, 'Cursor', 'User')
+        : path.join(home, 'Library', 'Application Support', 'Cursor', 'User');
       const rel = path.relative(cursorDir, src);
       if (src === cursorDir) return true;
       const basename = path.basename(src);
@@ -119,9 +117,13 @@ export const adapters = [
   {
     name: 'Windsurf',
     icon: '🏄',
-    source: windsurfUserDir,
+    source: isWin
+      ? path.join(appData, 'Windsurf', 'User')
+      : path.join(home, 'Library', 'Application Support', 'Windsurf', 'User'),
     filter: (src) => {
-      const windsurfDir = windsurfUserDir;
+      const windsurfDir = isWin
+        ? path.join(appData, 'Windsurf', 'User')
+        : path.join(home, 'Library', 'Application Support', 'Windsurf', 'User');
       const rel = path.relative(windsurfDir, src);
       if (src === windsurfDir) return true;
       const basename = path.basename(src);

package/src/commands/autopush.js

@@ -13,9 +13,11 @@ import fs from 'fs-extra';
 import path from 'path';
 import os from 'os';
 import { spawn } from 'child_process';
+import { withSessionLock } from '../session/lock.js';
 
 const home = os.homedir();
 const STAMP_FILE = path.join(home, '.config', 'memoir', 'last-autopush.timestamp');
+const STAMP_LOCK_FILE = path.join(home, '.config', 'memoir', 'last-autopush.timestamp.lock');
 const DEBOUNCE_SECONDS_DEFAULT = 30;
 
 export async function autopushCommand(options = {}) {
@@ -26,23 +28,35 @@ export async function autopushCommand(options = {}) {
     await fs.ensureDir(path.dirname(STAMP_FILE));
   } catch {}
 
-  const now = Date.now();
-  let last = 0;
-  try {
-    const raw = await fs.readFile(STAMP_FILE, 'utf8');
-    last = parseInt(raw.trim(), 10) || 0;
-  } catch {}
+  // The debounce check ("read timestamp, compare elapsed, write new
+  // timestamp") is itself an unlocked check-then-act — two Stop hooks firing
+  // in the same window could both pass the debounce gate and both spawn a
+  // detached `memoir push`, racing each other against the git remote. Wrap
+  // the whole read+compare+stamp cycle in the same lock primitive
+  // state.js's mutators use (a dedicated lock file — this stamp is an
+  // unrelated concern from session.json itself).
+  const shouldRun = await withSessionLock(STAMP_LOCK_FILE, async () => {
+    const now = Date.now();
+    let last = 0;
+    try {
+      const raw = await fs.readFile(STAMP_FILE, 'utf8');
+      last = parseInt(raw.trim(), 10) || 0;
+    } catch {}
 
-  const elapsed = (now - last) / 1000;
-  if (last && elapsed < debounce) {
-    if (verbose) console.log(`memoir autopush: skipped (${Math.floor(elapsed)}s since last, debounce=${debounce}s)`);
-    return;
-  }
+    const elapsed = (now - last) / 1000;
+    if (last && elapsed < debounce) {
+      if (verbose) console.log(`memoir autopush: skipped (${Math.floor(elapsed)}s since last, debounce=${debounce}s)`);
+      return false;
+    }
 
-  // Stamp BEFORE spawning so rapid repeat calls don't all race through.
-  try {
-    await fs.writeFile(STAMP_FILE, String(now));
-  } catch {}
+    // Stamp BEFORE spawning so rapid repeat calls don't all race through.
+    try {
+      await fs.writeFile(STAMP_FILE, String(now));
+    } catch {}
+    return true;
+  });
+
+  if (!shouldRun) return;
 
   // Detach a background push. Parent exits immediately so Claude isn't blocked.
   const memoirBin = process.argv[1]; // path to this same memoir CLI

package/src/commands/push.js

@@ -5,20 +5,72 @@ import os from 'os';
 import ora from 'ora';
 import boxen from 'boxen';
 import gradient from 'gradient-string';
+import { execFileSync } from 'child_process';
 import { getConfig, autoSetup } from '../config.js';
 import { extractMemories, adapters } from '../adapters/index.js';
 import { syncToLocal, syncToGit } from '../providers/index.js';
 import inquirer from 'inquirer';
-import { findClaudeSessions, parseSession, generateContextHandoff, shouldIgnoreProject, persistDecisions } from '../context/capture.js';
+import { findClaudeSessions, parseSession, generateContextHandoff, shouldIgnoreProject, persistDecisions, isQuality } from '../context/capture.js';
 import { scanForSecrets, printSecurityReport } from '../security/scanner.js';
 import { encryptDirectory, createVerifyToken } from '../security/encryption.js';
 import { getRawConfig, saveConfig, migrateConfigToV2 } from '../config.js';
 import { scanWorkspace } from '../workspace/tracker.js';
 import { promptActivate } from './activate.js';
-import { paths as sessionPaths, readSession, addNote, recordSessionEnd } from '../session/state.js';
+import { paths as sessionPaths, readSession, writeSession, mergeSessions, addNote, recordSessionEnd } from '../session/state.js';
+import { migrateSessionData } from '../session/migrations.js';
+import { withSessionLock } from '../session/lock.js';
 import { renderSession } from '../session/render.js';
 import { injectInto, detectAvailableTargets } from '../session/inject.js';
 
+// Best-effort fetch of the CURRENT remote session.json, so push.js can merge
+// before overwrite instead of blindly clobbering it (see below). Returns the
+// remote session state (already migrated to SCHEMA_VERSION) or null if the
+// remote is unreachable, this is the very first push (nothing there yet), or
+// the remote backup is encrypted (best-effort only — we deliberately don't
+// force an extra decrypt passphrase prompt mid-push; falls back to
+// local-only in that case, exactly like an unreachable remote).
+async function fetchRemoteSessionBestEffort(config) {
+  try {
+    if (config.provider === 'local' || config.provider?.includes?.('local')) {
+      const resolvedDest = (config.localPath || '').replace(/^~/, os.homedir());
+      if (!resolvedDest) return null;
+      if (await fs.pathExists(path.join(resolvedDest, 'manifest.enc'))) return null; // encrypted
+      const remotePath = path.join(resolvedDest, 'session.json');
+      if (!(await fs.pathExists(remotePath))) return null;
+      const raw = JSON.parse(await fs.readFile(remotePath, 'utf8'));
+      const { state } = migrateSessionData(raw);
+      return state;
+    }
+
+    if (config.provider === 'git' || config.provider?.includes?.('git')) {
+      const repoUrl = config.gitRepo;
+      if (!repoUrl) return null;
+      const peekDir = path.join(os.tmpdir(), `memoir-push-peek-${Date.now()}`);
+      await fs.ensureDir(peekDir);
+      try {
+        try {
+          execFileSync('git', ['clone', '--depth', '1', repoUrl, '.'], { cwd: peekDir, stdio: 'ignore', timeout: 30000 });
+        } catch {
+          // Unreachable, or this is the very first push (repo doesn't exist
+          // yet / is empty) — fall back to local-only.
+          return null;
+        }
+        if (await fs.pathExists(path.join(peekDir, 'manifest.enc'))) return null; // encrypted
+        const remotePath = path.join(peekDir, 'session.json');
+        if (!(await fs.pathExists(remotePath))) return null;
+        const raw = JSON.parse(await fs.readFile(remotePath, 'utf8'));
+        const { state } = migrateSessionData(raw);
+        return state;
+      } finally {
+        await fs.remove(peekDir).catch(() => {});
+      }
+    }
+  } catch {
+    // Never let a merge-fetch failure block the push.
+  }
+  return null;
+}
+
 // Recursively scan every staged file (the REAL tool memory/config files about
 // to be uploaded — CLAUDE.md, .cursorrules, settings.json, project configs,
 // etc.) for secrets. When `redact` is true, rewrite each offending file in
@@ -134,11 +186,20 @@ export async function pushCommand(options = {}) {
           await fs.writeFile(path.join(localHandoffDir, `${timestamp}-claude.md`), clean);
           await fs.writeFile(path.join(localHandoffDir, 'latest.md'), clean);
 
+          // Quality filter: auto-extracted decisions come from regex patterns
+          // that sometimes catch table cells, prose fragments, or truncated
+          // pasted-spec snippets. Run the SAME filter over parsed.decisions
+          // ONCE, before either persistence sink — previously persistDecisions()
+          // received the raw unfiltered list while only the session.json sink
+          // below filtered, so junk could reach session-decisions.md even after
+          // being rejected from session.json. Both sinks now agree on what's junk.
+          const qualityDecisions = parsed.decisions.filter(d => isQuality(String(d.value || '').trim()));
+
           // Persist decisions to Claude's memory so they survive across sessions
           let decisionCount = 0;
-          if (parsed.decisions.length > 0) {
+          if (qualityDecisions.length > 0) {
             try {
-              decisionCount = persistDecisions(parsed.decisions);
+              decisionCount = persistDecisions(qualityDecisions);
             } catch {}
           }
 
@@ -150,25 +211,8 @@ export async function pushCommand(options = {}) {
             const existingTexts = new Set(
               current.current.decisions.map(d => (d.text || '').trim().toLowerCase())
             );
-            // Quality filter: auto-extracted decisions come from regex patterns
-            // that sometimes catch table cells or prose fragments. Keep only
-            // substantive-looking entries.
-            const isQuality = (text) => {
-              if (!text) return false;
-              if (text.length < 15) return false;                // too short to be a real decision
-              if (text.length > 200) return false;               // probably a snippet, not a decision
-              if (/\|/.test(text)) return false;                 // markdown table fragment
-              if (/[_*`]{3,}/.test(text)) return false;          // markdown formatting leaked in
-              if (!/[a-zA-Z]/.test(text)) return false;          // no actual words
-              if (/\?/.test(text)) return false;                 // questions aren't decisions
-              if (/^(it|this|that|these|those|we|i|they|you|some|there|here|just|back|now|also)\b/i.test(text)) return false; // fragment
-              const words = text.split(/\s+/).length;
-              if (words < 3) return false;                       // less than 3 words isn't a decision
-              return true;
-            };
-            for (const d of parsed.decisions.slice(0, 10)) {
+            for (const d of qualityDecisions.slice(0, 10)) {
               const text = String(d.value || '').trim();
-              if (!isQuality(text)) continue;
               if (existingTexts.has(text.toLowerCase())) continue;
               await addNote(text, { why: d.context ? `auto-captured: ${d.context.slice(0, 80)}` : undefined });
             }
@@ -227,11 +271,38 @@ export async function pushCommand(options = {}) {
       // Workspace scan is best-effort
     }
 
-    // Include session.json (continuity state) so it syncs across machines
+    // Include session.json (continuity state) so it syncs across machines.
+    //
+    // MERGE-BEFORE-OVERWRITE: this used to be a blind fs.copy() of the LOCAL
+    // session.json, and syncToGit/syncToLocal do a full-mirror overwrite of
+    // the remote (clone-or-init, delete every tracked file, copy the local
+    // staging dir wholesale over it, commit, push). Any machine that pushed
+    // without having restored first would silently and completely destroy
+    // whatever ANY OTHER machine had added to the remote in the interim —
+    // goals, next-actions, decisions, everything. Not an edge case: it's the
+    // default behavior of the most common operation in the tool (autopush
+    // fires after every single Claude Code response).
+    //
+    // Best-effort fetch the current remote session.json first, migrate it,
+    // and merge with mergeSessions (the same newest-timestamp-wins
+    // union-by-text function restore.js already uses) BEFORE writing the
+    // result to both the staging dir (for upload) and back to the local
+    // session.json (so this machine also gains whatever the remote had that
+    // it didn't) — symmetric with restore.js instead of a blind overwrite.
     let sessionIncluded = false;
     try {
       if (await fs.pathExists(sessionPaths.session)) {
-        await fs.copy(sessionPaths.session, path.join(stagingDir, 'session.json'));
+        const remote = await fetchRemoteSessionBestEffort(config);
+        const local = await readSession();
+        const merged = remote ? mergeSessions(local, remote) : local;
+        if (remote) {
+          // Persist the merge locally too, inside the same lock every other
+          // session.json read-modify-write cycle uses.
+          await withSessionLock(sessionPaths.sessionLock, async () => {
+            await writeSession(merged);
+          });
+        }
+        await fs.writeFile(path.join(stagingDir, 'session.json'), JSON.stringify(merged, null, 2));
         sessionIncluded = true;
       }
     } catch {

package/src/commands/restore.js

@@ -15,6 +15,7 @@ import { getSession } from '../cloud/auth.js';
 import { unbundleToDir } from '../cloud/storage.js';
 import { SUPABASE_URL, SUPABASE_ANON_KEY, STORAGE_BUCKET } from '../cloud/constants.js';
 import { readSession, writeSession, mergeSessions, paths as sessionPaths } from '../session/state.js';
+import { migrateSessionData } from '../session/migrations.js';
 import { renderSession } from '../session/render.js';
 import { injectInto, detectAvailableTargets } from '../session/inject.js';
 
@@ -128,7 +129,13 @@ export async function restoreCommand(options = {}) {
     try {
       const remoteSessionPath = path.join(stagingDir, 'session.json');
       if (await fs.pathExists(remoteSessionPath)) {
-        const remote = JSON.parse(await fs.readFile(remoteSessionPath, 'utf8'));
+        // Route the remote backup through the same migrate-on-load path as
+        // the local file (migrateSessionData — pure, no I/O) rather than a
+        // raw JSON.parse, so an old-schema file from a lagging machine gets
+        // migrated up (or a too-new one safely degraded) BEFORE mergeSessions
+        // ever touches it. Symmetric with the push-side fix in push.js.
+        const rawRemote = JSON.parse(await fs.readFile(remoteSessionPath, 'utf8'));
+        const { state: remote } = migrateSessionData(rawRemote);
         const local = await readSession();
         const beforeMachines = Object.keys(local.machines || {}).length;
         const merged = mergeSessions(local, remote);

package/src/commands/tidy.js

@@ -9,6 +9,7 @@
 
 import fs from 'fs-extra';
 import path from 'path';
+import { appendEvent } from '../events/log.js';
 
 export const DEFAULT_BUDGET = 180; // Claude loads ~200 lines of MEMORY.md; leave headroom.
 
@@ -57,6 +58,15 @@ function inlineWeight(section) {
 
 const PROTECTED = (header) => /critical behavior rules/i.test(header) || header === '(preamble)';
 
+// Informational-only schema marker for MEMORY.md itself (distinct from — and
+// unrelated to — session.json's SCHEMA_VERSION). No enforcement/refusal
+// logic: this file is human-edited markdown, so a strict gate would hurt UX,
+// not help it. Appended as a single HTML comment line (invisible when
+// rendered) only when tidyIndex actually rewrites the file, and only once —
+// idempotent, never duplicated on repeat runs. Counted in newLineCount like
+// any other line, so it never causes a silent budget overshoot.
+const MEMORY_SCHEMA_MARKER = '<!-- memoir:schemaVersion 1 -->';
+
 async function atomicWrite(filePath, content) {
   const tmp = `${filePath}.tmp-${process.pid}`;
   await fs.writeFile(tmp, content);
@@ -123,10 +133,20 @@ export async function tidyIndex(memoryDir, { budgetLines = DEFAULT_BUDGET, dryRu
     else out.push(...sections[i].lines);
   }
 
+  if (!out.some(l => l.includes('memoir:schemaVersion'))) {
+    out.push(MEMORY_SCHEMA_MARKER);
+  }
+
   const fm = `---\nname: Memory index archive (${stamp})\ndescription: Fat inline sections moved out of MEMORY.md to keep the loaded index under ${budgetLines} lines. Nothing deleted; pointers remain in MEMORY.md.\nmetadata:\n  type: reference\n---\n`;
   const base = priorArchive || fm;
   if (toAppend) await atomicWrite(archivePath, base.trimEnd() + '\n\n' + toAppend.trimEnd() + '\n');
   await atomicWrite(mdPath, out.join('\n'));
 
+  // Only reached when tidyIndex actually changed something (both earlier
+  // no-op paths — under budget, or over budget with nothing archivable —
+  // return before this point, and dryRun never writes). The event should
+  // mean "something happened," not "this function was called."
+  await appendEvent('tidy_ran', { archived_count: archived.length, from_lines: lineCount, to_lines: out.length });
+
   return { overBudget: true, lineCount, newLineCount: out.length, budgetLines, archived, archiveFile };
 }

package/src/commands/why.js

@@ -27,7 +27,11 @@ function searchDecisions(decisions, query) {
 
 export async function whyCommand(query) {
   const state = await readSession();
-  const decisions = state.current?.decisions || [];
+  // hidden:true is a tombstone (distinct from the live `rejected` field) —
+  // see scripts/cleanup-junk-decisions-2026-07.mjs. Excluded here so
+  // tombstoned junk isn't fully discoverable via `memoir why` even after
+  // being hidden from the pinned block.
+  const decisions = (state.current?.decisions || []).filter(d => !d?.hidden);
   const matches = searchDecisions(decisions, query);
 
   if (matches.length === 0) {
@@ -54,7 +58,10 @@ export async function whyCommand(query) {
   console.log('\n' + lines.join('\n'));
 }
 
-// Exported for MCP tool
+// Exported for MCP tool (memoir_why in mcp.js). Same hidden:true tombstone
+// filter as whyCommand above — kept independent rather than relying solely
+// on the caller, so this stays correct even if mcp.js's call chain changes.
 export function findDecisions(state, query) {
-  return searchDecisions(state.current?.decisions || [], query);
+  const decisions = (state.current?.decisions || []).filter(d => !d?.hidden);
+  return searchDecisions(decisions, query);
 }

package/src/context/capture.js

@@ -161,6 +161,48 @@ function looksLikeFragment(v) {
   return false;
 }
 
+// Quality gate for auto-extracted decisions before they're written to EITHER
+// persistence sink (session-decisions.md via persistDecisions, or session.json
+// via addNote — see push.js, which now runs this once over parsed.decisions
+// before both call sites). Auto-extraction is regex-based and occasionally
+// produces prose fragments, markdown-table cells, or truncated pasted-spec
+// snippets — this rejects the shapes that look like junk rather than a real
+// decision.
+//
+// 2026-07: two real junk decisions made it into a live session.json because
+// the user-note regex (see extractDecisions below) matched mid-paragraph
+// inside long pasted spec/prompt text, and one of them was a hard 150-char
+// truncation with an unbalanced closing paren. The regex is now anchored to
+// message/line start (see below), which independently prevents both from
+// matching at all — these two extra checks are defense-in-depth for the
+// other, unanchored pattern branches (rename/tech/design/stack) that can
+// still match mid-message.
+export function isQuality(text) {
+  if (!text) return false;
+  if (text.length < 15) return false;                // too short to be a real decision
+  if (text.length > 200) return false;                // probably a snippet, not a decision
+  if (/\|/.test(text)) return false;                  // markdown table fragment
+  if (/[_*`]{3,}/.test(text)) return false;           // markdown formatting leaked in
+  if (!/[a-zA-Z]/.test(text)) return false;           // no actual words
+  if (looksLikeFragment(text)) return false;          // question, or pronoun/filler-start fragment
+  const words = text.split(/\s+/).length;
+  if (words < 3) return false;                        // less than 3 words isn't a decision
+
+  // Unbalanced parens/brackets — a hallmark of a regex capture that got cut
+  // off mid-parenthetical (real junk: "...only gain is Y)" with no opener,
+  // because the opening "(" was in the text BEFORE the capture started).
+  const opens = (text.match(/[(\[]/g) || []).length;
+  const closes = (text.match(/[)\]]/g) || []).length;
+  if (opens !== closes) return false;
+
+  // Suspiciously long AND doesn't end in sentence-ending punctuation or a
+  // closing quote — another truncation signature (a capture cut off mid-word
+  // or mid-sentence by a regex length cap rather than ending naturally).
+  if (text.length >= 140 && !/[.!?"')\]]$/.test(text)) return false;
+
+  return true;
+}
+
 /**
  * Extract durable decisions from session conversation.
  * These are things like renames, tech choices, preferences — stuff that should persist.
@@ -201,12 +243,37 @@ function extractDecisions(userMessages, assistantTexts) {
     }
   }
 
-  // Look for explicit "remember this" instructions from the user
+  // Look for explicit "remember this" instructions from the user.
+  //
+  // Anchored to message/line start ((?:^|\n) immediately before optional
+  // indentation and an optional "please") — unlike the pattern branches
+  // above, this used to match ANYWHERE in the message, which meant a phrase
+  // like "note that" or "keep in mind that" appearing mid-sentence inside a
+  // long pasted spec/prompt got misread as an explicit remember-instruction.
+  // Requiring it to start the message (or a line within it) means only a
+  // genuine top-of-message instruction matches, not incidental prose deep in
+  // pasted content.
+  //
+  // Only scanned within the first ~500 chars of the message: a short
+  // "Remember that X." followed by a long paste in the SAME turn must still
+  // be captured (the instruction is still at message start), but a trigger
+  // phrase that only occurs later/mid-document in a long paste is excluded
+  // — it was never an instruction to begin with.
+  const USER_NOTE_RE = /(?:^|\n)[ \t]*(?:please\s+)?(?:remember (?:that|this)|note that|keep in mind that|from now on)[:\s]+(.{10,150})/i;
   for (const msg of userMessages) {
-    // Only match when user is clearly asking to remember something
-    const rememberMatch = msg.match(/(?:remember (?:that|this)|note that|keep in mind that|from now on)[:\s]+(.{10,150})/i);
+    const scope = msg.slice(0, 500);
+    const rememberMatch = scope.match(USER_NOTE_RE);
     if (rememberMatch) {
-      decisions.push({ type: 'user-note', value: rememberMatch[1].trim(), context: msg.slice(0, 120) });
+      const capturedRaw = rememberMatch[1];
+      // The capture group is capped at 150 chars. Hitting that cap exactly is
+      // a truncation signature — real junk in the wild was a parenthetical
+      // cut off mid-thought with an unbalanced closing paren. Reject rather
+      // than keep a truncated tail.
+      const hitCap = capturedRaw.length === 150;
+      const value = capturedRaw.trim();
+      if (!hitCap && !looksLikeFragment(value)) {
+        decisions.push({ type: 'user-note', value, context: msg.slice(0, 120) });
+      }
     }
   }
 
@@ -231,6 +298,18 @@ export function resolveHomeMemoryDir(claudeSource) {
   return path.join(projectsDir, homeKey, 'memory');
 }
 
+// Atomic write (sync): write to a pid-scoped tmp file, then rename over the
+// target. Matches the tmp-then-rename idiom used elsewhere in this codebase
+// (state.js's writeSession, inject.js's injectInto) — prevents a torn/partial
+// file if the process crashes mid-write. persistDecisions stays synchronous
+// (its one caller in push.js doesn't await it), so this uses the sync
+// fs-extra APIs rather than switching the whole call chain to async.
+function writeFileAtomicSync(targetPath, content) {
+  const tmp = `${targetPath}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, content);
+  fs.moveSync(tmp, targetPath, { overwrite: true });
+}
+
 /**
  * Write extracted decisions to Claude's persistent memory.
  * This ensures decisions survive across sessions and machines.
@@ -277,10 +356,10 @@ type: project
 
 # Decisions from coding sessions
 ${section}`;
-    fs.writeFileSync(decisionsFile, content);
+    writeFileAtomicSync(decisionsFile, content);
   } else {
     // Append to existing
-    fs.writeFileSync(decisionsFile, existing.trimEnd() + '\n' + section);
+    writeFileAtomicSync(decisionsFile, existing.trimEnd() + '\n' + section);
   }
 
   // Ensure MEMORY.md references the decisions file
@@ -288,7 +367,7 @@ ${section}`;
     const memoryMd = fs.readFileSync(memoryMdPath, 'utf8');
     if (!memoryMd.includes('session-decisions.md')) {
       const addition = `\n- [Session Decisions](session-decisions.md) — project renames, tech choices, architecture decisions from coding sessions\n`;
-      fs.writeFileSync(memoryMdPath, memoryMd.trimEnd() + addition);
+      writeFileAtomicSync(memoryMdPath, memoryMd.trimEnd() + addition);
     }
   }
 

package/src/events/log.js

@@ -0,0 +1,113 @@
+// Additive, size-bounded, crash-safe JSONL event log.
+//
+// Target: ~/.config/memoir/events.jsonl — one JSON object per line:
+//   { ts, type, machine_id, ...minimal metadata }
+//
+// PRIVACY: this must never become a second, unfiltered copy of sensitive
+// user data. NEVER log raw decision/note/goal TEXT content — only counts,
+// ids, booleans, and short enum-like type strings. Every call site in this
+// codebase that calls appendEvent() is expected to honor that; review any
+// new call site against it.
+//
+// CRASH-SAFE: pure fs.appendFileSync (O_APPEND) for the actual write —
+// never a read-modify-write on this file, so a crash mid-write can at worst
+// leave a truncated LAST line, never corrupt earlier ones.
+//
+// SIZE-BOUNDED: rotates at MAX_BYTES — events.jsonl -> .1 -> .2, oldest
+// generation beyond MAX_ROTATIONS is deleted.
+//
+// LOCKED ROTATE-THEN-APPEND: the size-check-and-maybe-rotate is itself a
+// check-then-act sequence that would race under concurrent processes
+// exactly like the session.json bug Commit 4 fixed (two processes both see
+// "under the cap," both append, one rotates mid-write, etc.). Rather than
+// threading through whichever *other* lock happens to be held at each of
+// the 6+ call sites (some of which, like sync_pushed/sync_failed, have no
+// adjacent lock at all), this uses ONE small dedicated lock
+// (events.jsonl.lock) around every rotate-then-append, uniformly. Simpler
+// and always-safe, at the cost of a little lock contention on an
+// infrequent, cheap operation — a deliberate simplification over coupling
+// to each caller's own lock.
+//
+// NEVER BREAKS THE CALLER: appendEvent() catches everything internally and
+// never throws. The primary operation it's logging (writeSession,
+// injectInto, push, etc.) must always succeed or fail on its own merits,
+// never because event logging failed.
+
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import { getMachineId } from '../session/state.js';
+import { withSessionLock } from '../session/lock.js';
+
+const CONFIG_DIR = process.platform === 'win32'
+  ? path.join(process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'), 'memoir')
+  : path.join(os.homedir(), '.config', 'memoir');
+const EVENTS_PATH = path.join(CONFIG_DIR, 'events.jsonl');
+const EVENTS_LOCK_PATH = path.join(CONFIG_DIR, 'events.jsonl.lock');
+
+const MAX_BYTES = 5 * 1024 * 1024; // 5MB
+const MAX_ROTATIONS = 2; // keep events.jsonl.1 and .2; older generations are dropped
+
+let cachedMachineId = null;
+async function machineId() {
+  if (cachedMachineId) return cachedMachineId;
+  try {
+    const { id } = await getMachineId();
+    cachedMachineId = id;
+  } catch {
+    cachedMachineId = 'unknown';
+  }
+  return cachedMachineId;
+}
+
+// Rotate events.jsonl -> .1 -> .2, drop anything beyond MAX_ROTATIONS. Must
+// only be called from within the events lock (see appendEvent) — this
+// function itself does no locking.
+function rotateIfNeeded() {
+  try {
+    if (!fs.existsSync(EVENTS_PATH)) return;
+    const stat = fs.statSync(EVENTS_PATH);
+    if (stat.size < MAX_BYTES) return;
+
+    // Shift existing generations up (.1 -> .2 -> dropped), oldest first.
+    for (let i = MAX_ROTATIONS; i >= 1; i--) {
+      const src = `${EVENTS_PATH}.${i}`;
+      if (!fs.existsSync(src)) continue;
+      if (i === MAX_ROTATIONS) {
+        fs.removeSync(src); // oldest generation, drop it
+      } else {
+        fs.moveSync(src, `${EVENTS_PATH}.${i + 1}`, { overwrite: true });
+      }
+    }
+    fs.moveSync(EVENTS_PATH, `${EVENTS_PATH}.1`, { overwrite: true });
+  } catch {
+    // Rotation failure must never block an append.
+  }
+}
+
+/**
+ * Append one JSON event line. See file header for the privacy contract
+ * (counts/ids/booleans/enum-strings only, never raw content) and the
+ * crash-safety / size-bound / locking guarantees.
+ *
+ * Always safe to call and await — never throws, never rejects.
+ */
+export async function appendEvent(type, payload = {}) {
+  try {
+    await fs.ensureDir(CONFIG_DIR);
+    const id = await machineId();
+    const line = JSON.stringify({ ts: new Date().toISOString(), type, machine_id: id, ...payload }) + '\n';
+
+    await withSessionLock(EVENTS_LOCK_PATH, async () => {
+      rotateIfNeeded();
+      fs.appendFileSync(EVENTS_PATH, line);
+    });
+  } catch {
+    // Never break the caller.
+  }
+}
+
+export const paths = {
+  events: EVENTS_PATH,
+  eventsLock: EVENTS_LOCK_PATH,
+};