memoir-cli 3.6.1 → 3.8.0

package/src/session/inject.js

@@ -0,0 +1,117 @@
+// Inject / update the pinned session block in target files.
+//
+// Primary target: ~/.claude/CLAUDE.md (user-global, always loaded by Claude Code
+// regardless of MEMORY.md truncation).
+//
+// Rules:
+// - If markers are present, replace the block in place. Nothing else is touched.
+// - If markers are absent, prepend the block at the top of the file (after any
+//   leading frontmatter or title line).
+// - If the file doesn't exist, create it containing only the block.
+// - Never touch content outside the markers.
+
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import { BLOCK_START, BLOCK_END } from './render.js';
+
+const home = os.homedir();
+const isWin = process.platform === 'win32';
+const appData = process.env.APPDATA || path.join(home, 'AppData', 'Roaming');
+
+// Every target that memoir knows how to inject the pinned block into.
+// Added when we extend cross-tool support. Each target is a single file path.
+//
+// Claude:   ~/.claude/CLAUDE.md                (always loaded by Claude Code)
+// Cursor:   ~/.cursor/rules/memoir-session.mdc (global user rules — auto-loaded)
+// Windsurf: {AppSupport}/Windsurf/User/memoir-session.md (user-global instructions)
+// Gemini:   ~/.gemini/GEMINI.md                (user-global)
+export const INJECTION_TARGETS = {
+  claude:   path.join(home, '.claude', 'CLAUDE.md'),
+  cursor:   path.join(home, '.cursor', 'rules', 'memoir-session.mdc'),
+  windsurf: isWin
+    ? path.join(appData, 'Windsurf', 'User', 'memoir-session.md')
+    : path.join(home, 'Library', 'Application Support', 'Windsurf', 'User', 'memoir-session.md'),
+  gemini:   path.join(home, '.gemini', 'GEMINI.md'),
+};
+
+// Returns the target paths whose parent infrastructure exists — i.e. the tool
+// is actually installed. Avoids creating empty tool dirs for tools the user
+// doesn't use.
+export function detectAvailableTargets() {
+  const detectors = {
+    claude:   path.join(home, '.claude'),
+    cursor:   path.join(home, '.cursor'),
+    windsurf: isWin
+      ? path.join(appData, 'Windsurf', 'User')
+      : path.join(home, 'Library', 'Application Support', 'Windsurf', 'User'),
+    gemini:   path.join(home, '.gemini'),
+  };
+  const available = {};
+  for (const [name, dir] of Object.entries(detectors)) {
+    try {
+      if (fs.existsSync(dir)) available[name] = INJECTION_TARGETS[name];
+    } catch {}
+  }
+  return available;
+}
+
+// Pattern that matches the whole block including markers. Tolerant of the
+// marker text evolving across versions — anchors on `memoir:session-block`.
+const BLOCK_RE = /<!--\s*memoir:session-block[^>]*-->[\s\S]*?<!--\s*\/memoir:session-block\s*-->/;
+
+export async function injectInto(targetPath, renderedBlock) {
+  await fs.ensureDir(path.dirname(targetPath));
+
+  let content = '';
+  let existed = false;
+  try {
+    content = await fs.readFile(targetPath, 'utf8');
+    existed = true;
+  } catch {
+    // Doesn't exist yet — will create.
+  }
+
+  const updated = applyBlock(content, renderedBlock, existed);
+
+  // Atomic write
+  const tmp = `${targetPath}.tmp-${process.pid}`;
+  await fs.writeFile(tmp, updated);
+  await fs.move(tmp, targetPath, { overwrite: true });
+
+  return { path: targetPath, created: !existed, replaced: existed && BLOCK_RE.test(content) };
+}
+
+// Apply the block to existing content. Exported for tests.
+export function applyBlock(content, renderedBlock, existed = true) {
+  if (!existed || content.trim() === '') {
+    // Fresh file — block only, plus a trailing newline for poetry.
+    return renderedBlock + '\n';
+  }
+
+  if (BLOCK_RE.test(content)) {
+    // Replace in place.
+    return content.replace(BLOCK_RE, renderedBlock);
+  }
+
+  // No existing block — prepend. Preserve any H1 title at the top by placing
+  // the block immediately after it. Otherwise put it at the very top.
+  const h1Match = content.match(/^(#\s.+\n+)/);
+  if (h1Match) {
+    return h1Match[1] + renderedBlock + '\n\n' + content.slice(h1Match[1].length);
+  }
+  return renderedBlock + '\n\n' + content;
+}
+
+// Remove the block, if present. Used when user wants memoir to stop managing CLAUDE.md.
+export async function uninjectFrom(targetPath) {
+  if (!await fs.pathExists(targetPath)) return { removed: false };
+  const content = await fs.readFile(targetPath, 'utf8');
+  if (!BLOCK_RE.test(content)) return { removed: false };
+  // Strip the block and any trailing blank lines that follow it
+  const cleaned = content.replace(BLOCK_RE, '').replace(/\n{3,}/g, '\n\n').trimStart();
+  const tmp = `${targetPath}.tmp-${process.pid}`;
+  await fs.writeFile(tmp, cleaned);
+  await fs.move(tmp, targetPath, { overwrite: true });
+  return { removed: true };
+}

package/src/session/render.js

@@ -0,0 +1,114 @@
+// Render session state → pinned markdown block.
+// The block is wrapped in <!-- memoir:session-block v1 --> markers so inject.js
+// can find and replace it without touching anything else in CLAUDE.md.
+
+export const BLOCK_START = '<!-- memoir:session-block v1 — managed by memoir, edit via `memoir goal/next/note` -->';
+export const BLOCK_END = '<!-- /memoir:session-block -->';
+
+const MAX_RENDERED_GOALS = 2;
+const MAX_RENDERED_NEXT = 6;
+const MAX_RENDERED_QUESTIONS = 4;
+const MAX_RENDERED_DECISIONS = 5;
+const MAX_RENDERED_HISTORY = 5;
+
+export function renderSession(state) {
+  if (!state) return renderEmpty();
+
+  const lines = [BLOCK_START, '## 🎯 Continuing from where we left off', ''];
+
+  const goals = (state.current?.goals || []).slice(0, MAX_RENDERED_GOALS);
+  const nexts = (state.current?.next_actions || []).slice(-MAX_RENDERED_NEXT).reverse();
+  const questions = (state.current?.open_questions || []).slice(-MAX_RENDERED_QUESTIONS).reverse();
+  const decisions = (state.current?.decisions || []).slice(0, MAX_RENDERED_DECISIONS);
+  const history = (state.history || []).slice(0, MAX_RENDERED_HISTORY);
+
+  const everythingEmpty = !goals.length && !nexts.length && !questions.length && !decisions.length && !history.length;
+  if (everythingEmpty) return renderEmpty();
+
+  // Goals — show current goal prominently
+  if (goals.length === 1) {
+    lines.push(`**Current goal:** ${goals[0].text}${machineTag(goals[0], state)}`);
+    lines.push('');
+  } else if (goals.length > 1) {
+    lines.push('**Goals:**');
+    for (const g of goals) lines.push(`- ${g.text}${machineTag(g, state)}`);
+    lines.push('');
+  }
+
+  // Next actions — checkbox format so they read as actionable
+  if (nexts.length) {
+    lines.push('**Next:**');
+    for (const n of nexts) {
+      lines.push(`- [ ] ${n.text}${machineTag(n, state)}`);
+    }
+    lines.push('');
+  }
+
+  // Open questions
+  if (questions.length) {
+    lines.push('**Open questions:**');
+    for (const q of questions) lines.push(`- ${q.text}${machineTag(q, state)}`);
+    lines.push('');
+  }
+
+  // Recent decisions
+  if (decisions.length) {
+    lines.push('**Recent decisions:**');
+    for (const d of decisions) {
+      let line = `- ${d.text}`;
+      if (d.why) line += ` — *${d.why}*`;
+      line += machineTag(d, state);
+      lines.push(line);
+    }
+    lines.push('');
+  }
+
+  // Recent session history — machine-tagged so user sees cross-machine trail
+  if (history.length) {
+    lines.push('**Recent sessions:**');
+    for (const h of history) {
+      const date = (h.date || '').slice(0, 10);
+      const machineLabel = labelFor(h.machine_id, state) || 'unknown';
+      const dur = h.duration_min ? ` (${formatDuration(h.duration_min)})` : '';
+      const summary = h.summary || '—';
+      lines.push(`- ${date} ${machineLabel}${dur}: ${summary}`);
+    }
+    lines.push('');
+  }
+
+  lines.push(BLOCK_END);
+  return lines.join('\n');
+}
+
+function machineTag(item, state) {
+  if (!item?.machine_id) return '';
+  const label = labelFor(item.machine_id, state);
+  // Only show machine tag if we have more than one machine — otherwise it's noise
+  const machineCount = Object.keys(state?.machines || {}).length;
+  if (machineCount <= 1 || !label) return '';
+  return ` _(${label})_`;
+}
+
+function labelFor(machineId, state) {
+  if (!machineId) return null;
+  return state?.machines?.[machineId]?.label || null;
+}
+
+function formatDuration(min) {
+  if (!min || min <= 0) return '';
+  if (min < 60) return `${min}m`;
+  const h = Math.floor(min / 60);
+  const m = min % 60;
+  return m ? `${h}h ${m}m` : `${h}h`;
+}
+
+function renderEmpty() {
+  return [
+    BLOCK_START,
+    '## 🎯 Continuing from where we left off',
+    '',
+    '_No session context yet. Set one with:_ `memoir goal "your current focus"`',
+    '',
+    BLOCK_END,
+  ].join('\n');
+}

package/src/session/state.js

@@ -0,0 +1,296 @@
+// Session state: the canonical source of truth for "what are we working on"
+// across sessions and machines. Rendered into CLAUDE.md (and other tools) as a
+// pinned block at the top, guaranteed to load.
+//
+// File: ~/.config/memoir/session.json
+// See CLAUDE.md pinned block for how this gets displayed.
+
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+
+const home = os.homedir();
+const CONFIG_DIR = path.join(home, '.config', 'memoir');
+const SESSION_PATH = path.join(CONFIG_DIR, 'session.json');
+const MACHINE_ID_PATH = path.join(CONFIG_DIR, 'machine.id');
+
+export const SCHEMA_VERSION = 1;
+
+// Maximum items kept in each list before oldest entries rotate into history.
+// Prevents unbounded growth of the live pinned block.
+const MAX_GOALS = 3;
+const MAX_NEXT = 8;
+const MAX_QUESTIONS = 5;
+const MAX_DECISIONS_RECENT = 10;
+const MAX_HISTORY = 30;
+
+// ── Machine identity ─────────────────────────────────────────────
+
+// Stable per-machine identifier. Persisted once, reused forever.
+// We pair a UUID (stable across hostname changes) with a human label (hostname)
+// for display — "mac-mini (abc1234)".
+export async function getMachineId() {
+  try {
+    if (await fs.pathExists(MACHINE_ID_PATH)) {
+      const id = (await fs.readFile(MACHINE_ID_PATH, 'utf8')).trim();
+      if (id) return { id, label: os.hostname() };
+    }
+  } catch {}
+
+  const id = crypto.randomUUID();
+  await fs.ensureDir(CONFIG_DIR);
+  await fs.writeFile(MACHINE_ID_PATH, id);
+  return { id, label: os.hostname() };
+}
+
+// ── Schema ───────────────────────────────────────────────────────
+
+function emptySession() {
+  return {
+    version: SCHEMA_VERSION,
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    machines: {}, // { [machineId]: { label, last_seen } }
+    current: {
+      goals: [],         // { text, machine_id, set_on }
+      next_actions: [],  // { text, machine_id, added, completed? }
+      open_questions: [],// { text, machine_id, asked }
+      decisions: [],     // { text, why?, rejected?, machine_id, date }
+    },
+    history: [],         // { date, machine_id, summary, files_touched, duration_min? }
+  };
+}
+
+// ── Read / write ─────────────────────────────────────────────────
+
+// Atomic read with graceful recovery from corrupted JSON.
+export async function readSession() {
+  if (!await fs.pathExists(SESSION_PATH)) return emptySession();
+
+  try {
+    const raw = await fs.readFile(SESSION_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    return migrateIfNeeded(parsed);
+  } catch (err) {
+    // Corrupted — preserve it for inspection, start fresh.
+    const backup = `${SESSION_PATH}.corrupted-${Date.now()}`;
+    try { await fs.copy(SESSION_PATH, backup); } catch {}
+    return emptySession();
+  }
+}
+
+// Atomic write: write to tmp, rename. Prevents torn writes on crash.
+export async function writeSession(state) {
+  await fs.ensureDir(CONFIG_DIR);
+  state.updated_at = new Date().toISOString();
+  const tmp = `${SESSION_PATH}.tmp-${process.pid}`;
+  await fs.writeFile(tmp, JSON.stringify(state, null, 2));
+  await fs.move(tmp, SESSION_PATH, { overwrite: true });
+}
+
+function migrateIfNeeded(state) {
+  if (state && state.version === SCHEMA_VERSION) return state;
+  // Future versions: add migration steps here.
+  // For now, if version mismatch, merge defaults to fill gaps.
+  const fresh = emptySession();
+  return {
+    ...fresh,
+    ...state,
+    version: SCHEMA_VERSION,
+    current: { ...fresh.current, ...(state?.current || {}) },
+    machines: { ...fresh.machines, ...(state?.machines || {}) },
+    history: Array.isArray(state?.history) ? state.history : [],
+  };
+}
+
+// ── Machine registration ────────────────────────────────────────
+
+async function touchMachine(state) {
+  const { id, label } = await getMachineId();
+  state.machines[id] = {
+    label,
+    last_seen: new Date().toISOString(),
+  };
+  return id;
+}
+
+// ── Mutators ────────────────────────────────────────────────────
+
+export async function addGoal(text) {
+  const state = await readSession();
+  const machineId = await touchMachine(state);
+  state.current.goals.unshift({
+    text,
+    machine_id: machineId,
+    set_on: new Date().toISOString(),
+  });
+  state.current.goals = state.current.goals.slice(0, MAX_GOALS);
+  await writeSession(state);
+  return state;
+}
+
+export async function addNext(text) {
+  const state = await readSession();
+  const machineId = await touchMachine(state);
+  // Dedupe by text (case-insensitive)
+  const normalized = text.trim().toLowerCase();
+  const exists = state.current.next_actions.some(a => a.text.trim().toLowerCase() === normalized);
+  if (!exists) {
+    state.current.next_actions.push({
+      text,
+      machine_id: machineId,
+      added: new Date().toISOString(),
+    });
+    state.current.next_actions = state.current.next_actions.slice(-MAX_NEXT);
+  }
+  await writeSession(state);
+  return state;
+}
+
+export async function completeNext(textOrIndex) {
+  const state = await readSession();
+  await touchMachine(state);
+  let idx = -1;
+  if (typeof textOrIndex === 'number') {
+    idx = textOrIndex;
+  } else {
+    const normalized = String(textOrIndex).trim().toLowerCase();
+    idx = state.current.next_actions.findIndex(a => a.text.trim().toLowerCase().includes(normalized));
+  }
+  if (idx >= 0) {
+    state.current.next_actions.splice(idx, 1);
+  }
+  await writeSession(state);
+  return state;
+}
+
+export async function addNote(text, opts = {}) {
+  const state = await readSession();
+  const machineId = await touchMachine(state);
+  const decision = {
+    text,
+    machine_id: machineId,
+    date: new Date().toISOString(),
+  };
+  if (opts.why) decision.why = opts.why;
+  if (opts.rejected) decision.rejected = opts.rejected;
+  state.current.decisions.unshift(decision);
+  state.current.decisions = state.current.decisions.slice(0, MAX_DECISIONS_RECENT);
+  await writeSession(state);
+  return state;
+}
+
+export async function addQuestion(text) {
+  const state = await readSession();
+  const machineId = await touchMachine(state);
+  state.current.open_questions.push({
+    text,
+    machine_id: machineId,
+    asked: new Date().toISOString(),
+  });
+  state.current.open_questions = state.current.open_questions.slice(-MAX_QUESTIONS);
+  await writeSession(state);
+  return state;
+}
+
+// Roll up the current state into a history entry. Use at session end / push.
+// Does not clear `current` — these are "the working set," not per-session scratch.
+export async function recordSessionEnd({ summary, filesTouched = [], durationMin = null } = {}) {
+  const state = await readSession();
+  const machineId = await touchMachine(state);
+  state.history.unshift({
+    date: new Date().toISOString(),
+    machine_id: machineId,
+    summary: summary || '',
+    files_touched: filesTouched.slice(0, 20),
+    duration_min: durationMin,
+  });
+  state.history = state.history.slice(0, MAX_HISTORY);
+  await writeSession(state);
+  return state;
+}
+
+// ── Cross-machine merge ─────────────────────────────────────────
+
+// Merge a remote session (from another machine's backup) into local.
+// Never clobbers — unions lists, dedupes by text, keeps newest timestamp.
+// Machine entries accumulate so we can show "last seen on X".
+export function mergeSessions(local, remote) {
+  if (!remote) return local;
+  if (!local) local = { ...remote };
+
+  const merged = {
+    version: SCHEMA_VERSION,
+    created_at: earliest(local.created_at, remote.created_at),
+    updated_at: latest(local.updated_at, remote.updated_at),
+    machines: { ...remote.machines, ...local.machines }, // local wins for same machine
+    current: {
+      goals: unionByText(local.current?.goals, remote.current?.goals, 'set_on', MAX_GOALS),
+      next_actions: unionByText(local.current?.next_actions, remote.current?.next_actions, 'added', MAX_NEXT),
+      open_questions: unionByText(local.current?.open_questions, remote.current?.open_questions, 'asked', MAX_QUESTIONS),
+      decisions: unionByText(local.current?.decisions, remote.current?.decisions, 'date', MAX_DECISIONS_RECENT),
+    },
+    history: mergeHistory(local.history, remote.history),
+  };
+
+  // machines: union last_seen per id (take the newer)
+  for (const [id, entry] of Object.entries(remote.machines || {})) {
+    const existing = merged.machines[id];
+    if (!existing || new Date(entry.last_seen) > new Date(existing.last_seen)) {
+      merged.machines[id] = entry;
+    }
+  }
+
+  return merged;
+}
+
+function unionByText(a = [], b = [], dateField, cap) {
+  const byText = new Map();
+  for (const item of [...a, ...b]) {
+    if (!item || !item.text) continue;
+    const key = item.text.trim().toLowerCase();
+    const existing = byText.get(key);
+    if (!existing || new Date(item[dateField] || 0) > new Date(existing[dateField] || 0)) {
+      byText.set(key, item);
+    }
+  }
+  return Array.from(byText.values())
+    .sort((x, y) => new Date(y[dateField] || 0) - new Date(x[dateField] || 0))
+    .slice(0, cap);
+}
+
+function mergeHistory(a = [], b = []) {
+  const seen = new Set();
+  const all = [...a, ...b].filter(h => h && h.date);
+  // Dedupe by (date + machine_id + summary) — the three keys that make a session unique
+  const unique = all.filter(h => {
+    const key = `${h.date}|${h.machine_id}|${(h.summary || '').slice(0, 50)}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+  return unique
+    .sort((x, y) => new Date(y.date) - new Date(x.date))
+    .slice(0, MAX_HISTORY);
+}
+
+function earliest(a, b) {
+  if (!a) return b;
+  if (!b) return a;
+  return new Date(a) < new Date(b) ? a : b;
+}
+
+function latest(a, b) {
+  if (!a) return b;
+  if (!b) return a;
+  return new Date(a) > new Date(b) ? a : b;
+}
+
+// ── Paths (exported for tests + other modules) ──────────────────
+
+export const paths = {
+  config: CONFIG_DIR,
+  session: SESSION_PATH,
+  machineId: MACHINE_ID_PATH,
+};

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,26 +0,0 @@
----
-name: Bug report
-about: Something isn't working
-title: ''
-labels: bug
-assignees: ''
----
-
-**What happened?**
-A clear description of the bug.
-
-**Steps to reproduce**
-1. Run `memoir ...`
-2. See error
-
-**Expected behavior**
-What you expected to happen.
-
-**Environment**
-- OS: [e.g. macOS 15, Windows 11, Ubuntu 24]
-- Node: [e.g. 20.11.0]
-- memoir version: [e.g. 3.2.2]
-- AI tools: [e.g. Claude Code, Cursor]
-
-**Logs / screenshots**
-Paste any error output here.

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,16 +0,0 @@
----
-name: Feature request
-about: Suggest an idea for memoir
-title: ''
-labels: enhancement
-assignees: ''
----
-
-**What would you like?**
-A clear description of the feature.
-
-**Why?**
-What problem does this solve for you?
-
-**Alternatives considered**
-Any workarounds you've tried.

package/CONTRIBUTING.md

@@ -1,47 +0,0 @@
-# Contributing to memoir
-
-Thanks for your interest in contributing! memoir is open source and welcomes contributions.
-
-## Quick start
-
-```bash
-git clone https://github.com/camgitt/memoir.git
-cd memoir
-npm install
-node bin/memoir.js status
-```
-
-## What to work on
-
-- **New tool adapters** — add support for more AI tools in `src/tools/`
-- **MCP improvements** — enhance the MCP server in `src/mcp.js`
-- **Bug fixes** — check [open issues](https://github.com/camgitt/memoir/issues)
-- **Documentation** — improve README, add examples
-
-## Submitting changes
-
-1. Fork the repo
-2. Create a branch (`git checkout -b feature/my-feature`)
-3. Make your changes
-4. Test locally: `npm test`
-5. Commit and push
-6. Open a PR with a clear description
-
-## Code style
-
-- ES modules (`import`/`export`)
-- No TypeScript (plain JS)
-- Keep dependencies minimal
-
-## Adding a tool adapter
-
-See `src/tools/claude.js` for an example. Each adapter exports:
-- `name` — display name
-- `icon` — emoji
-- `source` — path to the tool's config directory
-- `files` — specific files to sync (if `customExtract` is true)
-- `filter` — function to include/exclude files
-
-## Questions?
-
-Open an issue or start a discussion.