@lmaksym/agent-mem 0.1.0

package/src/commands/pull.js

@@ -0,0 +1,80 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import { contextDir as getContextDir } from '../core/context-root.js';
+import { git, isGitRepo } from '../core/git.js';
+
+/**
+ * Pull .context/ from its remote repository.
+ *
+ * agent-mem pull                     — pull from configured remote
+ * agent-mem pull --remote <url>      — clone/pull from specific remote
+ */
+export default async function pull({ args, flags }) {
+  const root = flags._contextRoot || process.cwd();
+  const ctxDir = join(root, '.context');
+
+  // Case 1: .context/ doesn't exist yet — clone from remote
+  if (!existsSync(ctxDir)) {
+    const remote = flags.remote || args[0];
+    if (!remote) {
+      console.error('❌ No .context/ found and no remote specified.');
+      console.error('Usage: agent-mem pull --remote <git-url>');
+      process.exit(1);
+    }
+
+    console.log(`  ⬇️  Cloning context from ${remote}...`);
+    try {
+      execSync(`git clone ${remote} .context`, {
+        cwd: root,
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      console.log(`\n✅ PULLED: ${remote} → .context/`);
+      console.log('Run: agent-mem snapshot');
+    } catch (err) {
+      console.error(`❌ Clone failed: ${err.stderr?.trim() || err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  // Case 2: .context/ exists with a remote — pull updates
+  if (!isGitRepo(ctxDir)) {
+    console.error('❌ .context/ exists but is not a git repo.');
+    process.exit(1);
+  }
+
+  // Set remote if provided
+  if (flags.remote) {
+    try {
+      git('remote remove origin', ctxDir);
+    } catch {}
+    git(`remote add origin ${flags.remote}`, ctxDir);
+  }
+
+  let remoteUrl;
+  try {
+    remoteUrl = git('remote get-url origin', ctxDir);
+  } catch {
+    console.error('❌ No remote configured. Use: agent-mem pull --remote <git-url>');
+    process.exit(1);
+  }
+
+  console.log(`  ⬇️  Pulling from ${remoteUrl}...`);
+  try {
+    git('pull --rebase origin main', ctxDir);
+    console.log(`\n✅ PULLED: latest context from ${remoteUrl}`);
+    console.log('Run: agent-mem snapshot');
+  } catch (err) {
+    // Try without rebase
+    try {
+      git('pull origin main --no-rebase', ctxDir);
+      console.log(`\n✅ PULLED (merged): latest context from ${remoteUrl}`);
+    } catch (err2) {
+      console.error(`❌ Pull failed: ${err2.message}`);
+      console.error('There may be conflicts. Check .context/ and resolve manually.');
+      process.exit(1);
+    }
+  }
+}

package/src/commands/push.js

@@ -0,0 +1,80 @@
+import { contextDir as getContextDir } from '../core/context-root.js';
+import { git, isGitRepo, hasChanges, commitContext } from '../core/git.js';
+
+/**
+ * Push .context/ to its own remote repository.
+ *
+ * agent-mem push                     — push to configured remote
+ * agent-mem push --remote <url>      — set remote and push
+ */
+export default async function push({ args, flags }) {
+  const root = flags._contextRoot;
+  const ctxDir = getContextDir(root);
+
+  if (!isGitRepo(ctxDir)) {
+    console.error("❌ .context/ is not a git repo. Run 'agent-mem init' first.");
+    process.exit(1);
+  }
+
+  // Set remote if provided
+  if (flags.remote) {
+    try {
+      git('remote remove origin', ctxDir);
+    } catch {}
+    git(`remote add origin ${flags.remote}`, ctxDir);
+    console.log(`  🔗 Remote set: ${flags.remote}`);
+  }
+
+  // Check if remote exists
+  let remoteUrl;
+  try {
+    remoteUrl = git('remote get-url origin', ctxDir);
+  } catch {
+    console.error('❌ No remote configured. Use: agent-mem push --remote <git-url>');
+    console.error('');
+    console.error('Example:');
+    console.error('  agent-mem push --remote git@github.com:user/myproject-context.git');
+    console.error('  agent-mem push --remote https://github.com/user/myproject-context.git');
+    process.exit(1);
+  }
+
+  // Auto-commit if there are changes
+  if (hasChanges(ctxDir)) {
+    const hash = commitContext(ctxDir, `sync: ${new Date().toISOString().slice(0, 16)}`);
+    if (hash) console.log(`  ⚡ Auto-committed: ${hash}`);
+  }
+
+  // Ensure branch exists
+  try {
+    git('rev-parse HEAD', ctxDir);
+  } catch {
+    console.error('❌ No commits yet. Run some commands first, then push.');
+    process.exit(1);
+  }
+
+  // Get current branch name
+  let branch;
+  try {
+    branch = git('branch --show-current', ctxDir);
+  } catch {
+    branch = 'main';
+  }
+
+  // Push
+  try {
+    console.log(`  ⬆️  Pushing to ${remoteUrl}...`);
+    git(`push -u origin ${branch}`, ctxDir);
+    console.log(`\n✅ PUSHED: .context/ → ${remoteUrl}`);
+    console.log(`Other machines can now: agent-mem pull`);
+  } catch (err) {
+    // First push might need --set-upstream or force
+    try {
+      git(`push --set-upstream origin ${branch}`, ctxDir);
+      console.log(`\n✅ PUSHED: .context/ → ${remoteUrl}`);
+    } catch (err2) {
+      console.error(`❌ Push failed: ${err2.message}`);
+      console.error('Try: agent-mem push --remote <url> (to reconfigure)');
+      process.exit(1);
+    }
+  }
+}

package/src/commands/read.js

@@ -0,0 +1,62 @@
+import { contextDir as getContextDir } from '../core/context-root.js';
+import { readContextFile } from '../core/fs.js';
+import { readConfig } from '../core/config.js';
+
+export default async function read({ args, flags }) {
+  const root = flags._contextRoot;
+  const ctxDir = getContextDir(root);
+
+  if (!args.length) {
+    console.error('❌ Usage: agent-mem read <path>');
+    console.error('Example: agent-mem read memory/decisions.md');
+    process.exit(1);
+  }
+
+  const relPath = args[0];
+  const config = readConfig(ctxDir);
+  const branch = config.branch || 'main';
+
+  // When on a branch and reading memory/, try branch-local first
+  let content = null;
+  if (branch !== 'main' && relPath.startsWith('memory/')) {
+    const branchPath = relPath.replace(/^memory\//, `branches/${branch}/memory/`);
+    content = readContextFile(ctxDir, branchPath);
+    if (content !== null) {
+      console.log(`(reading from branch: ${branch})\n`);
+    }
+  }
+
+  // Fall back to the exact path requested
+  if (content === null) {
+    content = readContextFile(ctxDir, relPath);
+  }
+
+  if (content === null) {
+    console.error(`❌ File not found: .context/${relPath}`);
+    process.exit(1);
+  }
+
+  // --last N: show only the last N entries (lines matching ^- [)
+  const last = parseInt(flags.last, 10);
+  if (last > 0) {
+    const lines = content.split('\n');
+    const entryIndices = [];
+    for (let i = 0; i < lines.length; i++) {
+      if (/^- \[/.test(lines[i])) entryIndices.push(i);
+    }
+    if (entryIndices.length > last) {
+      const cutoff = entryIndices[entryIndices.length - last];
+      // Keep header (everything before first entry) + last N entries
+      const headerEnd = entryIndices[0];
+      const header = lines.slice(0, headerEnd).join('\n');
+      const entries = lines.slice(cutoff).join('\n');
+      const skipped = entryIndices.length - last;
+      console.log(
+        header + `(${skipped} older entries hidden — showing last ${last})\n\n` + entries,
+      );
+      return;
+    }
+  }
+
+  console.log(content);
+}

package/src/commands/reflect.js

@@ -0,0 +1,328 @@
+import { contextDir as getContextDir } from '../core/context-root.js';
+import { readContextFile, writeContextFile, parseFrontmatter, listFiles } from '../core/fs.js';
+import { readConfig } from '../core/config.js';
+import { commitContext } from '../core/git.js';
+import { gatherReflectionPrompt, getReflectionFiles } from '../core/reflect-gather.js';
+import {
+  parseReflection,
+  extractGaps,
+  extractStaleEntries,
+  extractSummary,
+} from '../core/reflect-parse.js';
+import { analyzeDefrag, formatDefragOutput, applyStaleMarkers } from '../core/reflect-defrag.js';
+
+const MEMORY_CATEGORIES = {
+  decision: {
+    file: 'memory/decisions.md',
+    title: 'Decisions',
+    desc: 'Architectural decisions and rationale',
+  },
+  pattern: {
+    file: 'memory/patterns.md',
+    title: 'Patterns',
+    desc: 'Learned patterns and best practices',
+  },
+  mistake: {
+    file: 'memory/mistakes.md',
+    title: 'Mistakes',
+    desc: 'Anti-patterns and things to avoid',
+  },
+  note: { file: 'memory/notes.md', title: 'Notes', desc: 'Quick notes and observations' },
+  lesson: {
+    file: 'memory/lessons.md',
+    title: 'Lessons Learned',
+    desc: 'Lessons learned — problem/resolution pairs',
+  },
+};
+
+export default async function reflect({ args, flags }) {
+  const root = flags._contextRoot;
+  const ctxDir = getContextDir(root);
+
+  // Determine subcommand
+  const subcommand = args[0] || 'gather';
+  const subArgs = args.slice(1);
+
+  switch (subcommand) {
+    case 'gather':
+      return doGather(ctxDir, flags);
+    case 'save':
+      return doSave(ctxDir, subArgs, flags);
+    case 'history':
+      return doHistory(ctxDir, flags);
+    case 'defrag':
+      return doDefrag(ctxDir, flags);
+    default:
+      // If unrecognized subcommand, treat as gather
+      return doGather(ctxDir, flags);
+  }
+}
+
+// ─── GATHER ──────────────────────────────────────────────────────────────
+
+async function doGather(ctxDir, flags) {
+  const result = gatherReflectionPrompt(ctxDir, flags);
+
+  if (result.empty) {
+    console.log('ℹ️  No activity since last reflection. Nothing to reflect on.');
+    return;
+  }
+
+  console.log(result.prompt);
+}
+
+// ─── SAVE ────────────────────────────────────────────────────────────────
+
+async function doSave(ctxDir, args, flags) {
+  let content = flags.content;
+
+  if (!content) {
+    if (args.length > 0) {
+      content = args.join(' ');
+    } else {
+      content = await readStdin();
+    }
+  }
+
+  if (!content) {
+    console.error('❌ Usage: amem reflect save --content "YOUR_REFLECTION"');
+    console.error("  Or pipe: echo 'reflection' | amem reflect save");
+    process.exit(1);
+  }
+
+  // Parse the reflection
+  const parsed = parseReflection(content);
+
+  if (!parsed.recognized) {
+    console.log('⚠️  Could not parse structured sections. Saving as raw text.');
+  }
+
+  // Determine filename (handle multiple reflections same day)
+  const today = new Date().toISOString().slice(0, 10);
+  let filename = `reflections/${today}.md`;
+  let counter = 1;
+  while (readContextFile(ctxDir, filename) !== null) {
+    counter++;
+    filename = `reflections/${today}-${counter}.md`;
+  }
+
+  // Read breadcrumb state from gather phase
+  let state = {};
+  const stateRaw = readContextFile(ctxDir, '.reflect-state.json');
+  if (stateRaw) {
+    try {
+      state = JSON.parse(stateRaw);
+    } catch {}
+  }
+
+  // Extract actionable items (lessons can come from dedicated section or gaps)
+  const extractedLessons = parsed.recognized ? extractGaps(parsed.sections.lessons) : [];
+  const extractedGapsRaw = parsed.recognized ? extractGaps(parsed.sections.gaps) : [];
+  const extractedGaps = [...extractedLessons, ...extractedGapsRaw];
+  const staleEntries = parsed.recognized ? extractStaleEntries(parsed.sections.stale) : [];
+  const summary = parsed.recognized ? extractSummary(parsed.sections) : null;
+
+  // Build reflection file with frontmatter
+  const frontmatterLines = [
+    '---',
+    `date: "${today}"`,
+    state.window_start ? `window_start: "${state.window_start}"` : null,
+    state.window_end ? `window_end: "${state.window_end}"` : null,
+    state.commits_reviewed != null ? `commits_reviewed: ${state.commits_reviewed}` : null,
+    state.last_commit_hash ? `last_commit_hash: "${state.last_commit_hash}"` : null,
+    `entries_extracted: ${extractedGaps.length}`,
+    '---',
+  ].filter(Boolean);
+
+  const body = parsed.recognized ? content : `## Raw Reflection\n\n${content}`;
+  const reflectionContent = `${frontmatterLines.join('\n')}\n\n# Reflection: ${today}\n\n${body}`;
+  writeContextFile(ctxDir, filename, reflectionContent);
+
+  // Extract gaps to memory files
+  const extracted = {};
+  for (const gap of extractedGaps) {
+    const cat = MEMORY_CATEGORIES[gap.type];
+    if (!cat) continue;
+
+    const date = new Date().toISOString().slice(0, 10);
+    const time = new Date().toISOString().slice(11, 16);
+
+    let existing =
+      readContextFile(ctxDir, cat.file) ||
+      ['---', `description: "${cat.desc}"`, '---', '', `# ${cat.title}`, ''].join('\n');
+
+    if (gap.type === 'lesson') {
+      // Structured block format for lessons
+      let block = `\n### [${date} ${time}] ${gap.text}\n`;
+      block += `**Problem:** ${gap.problem || gap.text}\n`;
+      block += `**Resolution:** ${gap.resolution || gap.text}\n`;
+      existing += block;
+    } else {
+      existing += `\n- [${date} ${time}] ${gap.text}`;
+    }
+    writeContextFile(ctxDir, cat.file, existing);
+
+    if (!extracted[cat.file]) extracted[cat.file] = 0;
+    extracted[cat.file]++;
+  }
+
+  // Flag stale entries (non-destructive markers)
+  let staleMarked = 0;
+  if (staleEntries.length > 0) {
+    staleMarked = applyStaleMarkers(ctxDir, staleEntries);
+  }
+
+  // Update breadcrumb state
+  if (stateRaw) {
+    state.saved_at = new Date().toISOString();
+    state.reflection_file = filename;
+    writeContextFile(ctxDir, '.reflect-state.json', JSON.stringify(state, null, 2));
+  }
+
+  // Git commit
+  const commitMsg = summary ? `reflect: ${summary.slice(0, 60)}` : `reflect: ${today}`;
+  const hash = commitContext(ctxDir, commitMsg);
+
+  // Output
+  console.log(`✅ REFLECTED: ${filename}`);
+  if (state.window_start && state.window_end) {
+    console.log(
+      `Window: ${state.window_start} → ${state.window_end} (${state.commits_reviewed || '?'} commits reviewed)`,
+    );
+  }
+
+  if (Object.keys(extracted).length > 0) {
+    console.log('Extracted:');
+    for (const [file, count] of Object.entries(extracted)) {
+      console.log(`  → ${file}: +${count} entr${count > 1 ? 'ies' : 'y'}`);
+    }
+  }
+
+  if (staleMarked > 0) {
+    console.log(`Flagged stale: ${staleMarked} entr${staleMarked > 1 ? 'ies' : 'y'}`);
+  }
+
+  if (hash) {
+    console.log(`Committed: ${hash}`);
+  }
+}
+
+// ─── HISTORY ─────────────────────────────────────────────────────────────
+
+async function doHistory(ctxDir, flags) {
+  const reflections = getReflectionFiles(ctxDir);
+  const lastN = flags.last ? parseInt(flags.last, 10) : 5;
+
+  if (reflections.length === 0) {
+    console.log('📋 No reflections yet. Run `amem reflect` to create your first.');
+    return;
+  }
+
+  const shown = reflections.slice(-lastN).reverse();
+  console.log(`📋 REFLECTION HISTORY (showing ${shown.length} of ${reflections.length})`);
+  console.log('');
+
+  const allThemes = [];
+
+  for (let i = 0; i < shown.length; i++) {
+    const raw = readContextFile(ctxDir, shown[i]);
+    if (!raw) continue;
+
+    const { content: body } = parseFrontmatter(raw);
+
+    // Parse frontmatter for metadata
+    const fmMatch = raw.match(/^---\n([\s\S]*?)\n---/);
+    const fm = fmMatch ? fmMatch[1] : '';
+    const commits = fm.match(/commits_reviewed:\s*(\d+)/)?.[1] || '?';
+    const extracted = fm.match(/entries_extracted:\s*(\d+)/)?.[1] || '0';
+    const windowStart = fm.match(/window_start:\s*['"]?([^'"]+)['"]?/)?.[1] || '';
+    const windowEnd = fm.match(/window_end:\s*['"]?([^'"]+)['"]?/)?.[1] || '';
+
+    // Extract themes
+    const themeMatch = body.match(/## Themes?\n([\s\S]*?)(?=\n## |\n$|$)/);
+    const themes = themeMatch
+      ? themeMatch[1]
+          .split('\n')
+          .filter((l) => l.trim().startsWith('-'))
+          .map((l) => l.replace(/^-\s*/, '').trim())
+      : [];
+    allThemes.push(...themes);
+
+    // Extract summary
+    const summaryMatch = body.match(/## Summary\n([\s\S]*?)(?=\n## |\n$|$)/);
+    const summary = summaryMatch ? summaryMatch[1].trim().slice(0, 120) : '(no summary)';
+
+    const window =
+      windowStart && windowEnd ? ` | Window: ${windowStart.slice(5)}–${windowEnd.slice(5)}` : '';
+    const date = shown[i].replace('reflections/', '').replace('.md', '');
+
+    console.log(`${i + 1}. ${date} — ${commits} commits | ${extracted} extracted${window}`);
+    if (themes.length > 0) {
+      console.log(`   Themes: ${themes.join(', ')}`);
+    }
+    console.log(`   Summary: ${summary}`);
+    console.log('');
+  }
+
+  // Recurring themes across 3+ reflections
+  if (allThemes.length > 0 && shown.length >= 3) {
+    const themeCounts = {};
+    for (const theme of allThemes) {
+      const words = theme
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, '')
+        .split(/\s+/)
+        .filter((w) => w.length > 3);
+      for (const word of words) {
+        themeCounts[word] = (themeCounts[word] || 0) + 1;
+      }
+    }
+
+    const recurring = Object.entries(themeCounts)
+      .filter(([, count]) => count >= 3)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 5);
+
+    if (recurring.length > 0) {
+      console.log('Recurring themes (3+ reflections):');
+      for (const [word, count] of recurring) {
+        console.log(`  - "${word}" (${count}/${shown.length})`);
+      }
+    }
+  }
+}
+
+// ─── DEFRAG ──────────────────────────────────────────────────────────────
+
+async function doDefrag(ctxDir, flags) {
+  const isDryRun = flags['dry-run'] === true;
+  const analysis = analyzeDefrag(ctxDir);
+
+  console.log(formatDefragOutput(analysis, isDryRun));
+
+  // If not dry run, apply stale markers
+  if (!isDryRun && analysis.stale.length > 0) {
+    const marked = applyStaleMarkers(ctxDir, analysis.stale);
+    if (marked > 0) {
+      const hash = commitContext(ctxDir, `defrag: flagged ${marked} stale entries`);
+      console.log('');
+      console.log(`Applied: ${marked} stale markers. Committed: ${hash}`);
+    }
+  }
+}
+
+// ─── UTILS ───────────────────────────────────────────────────────────────
+
+function readStdin() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) {
+      resolve(null);
+      return;
+    }
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => (data += chunk));
+    process.stdin.on('end', () => resolve(data || null));
+    setTimeout(() => resolve(data || null), 100);
+  });
+}

package/src/commands/remember.js

@@ -0,0 +1,95 @@
+import { contextDir as getContextDir } from '../core/context-root.js';
+import { readContextFile, writeContextFile } from '../core/fs.js';
+import { readConfig } from '../core/config.js';
+
+const CATEGORIES = {
+  decision: {
+    file: 'memory/decisions.md',
+    title: 'Decisions',
+    desc: 'Architectural decisions and rationale',
+  },
+  pattern: {
+    file: 'memory/patterns.md',
+    title: 'Patterns',
+    desc: 'Learned patterns and best practices',
+  },
+  mistake: {
+    file: 'memory/mistakes.md',
+    title: 'Mistakes',
+    desc: 'Anti-patterns and things to avoid',
+  },
+  note: { file: 'memory/notes.md', title: 'Notes', desc: 'Quick notes and observations' },
+};
+
+/**
+ * Resolve memory file path based on active branch.
+ * On main: memory/notes.md
+ * On branch: branches/<name>/memory/notes.md
+ */
+function resolvePath(target, branch) {
+  if (branch && branch !== 'main') {
+    return target.replace(/^memory\//, `branches/${branch}/memory/`);
+  }
+  return target;
+}
+
+export default async function remember({ args, flags }) {
+  const root = flags._contextRoot;
+  const ctxDir = getContextDir(root);
+
+  if (!args.length) {
+    console.error('❌ Usage: agent-mem remember [--category] <text>');
+    console.error('');
+    console.error('Categories:');
+    console.error('  --decision  "Chose Qdrant over Pinecone because self-hosted"');
+    console.error('  --pattern   "Always check Grafana logs before fixing bugs"');
+    console.error('  --mistake   "Never force-push to fix branches"');
+    console.error('  --note      "Meeting with team re: auth refactor" (default)');
+    console.error('');
+    console.error('Or specify file directly:');
+    console.error('  --file memory/custom.md "some text"');
+    process.exit(1);
+  }
+
+  // Determine category from flags
+  let category = 'note';
+  for (const cat of Object.keys(CATEGORIES)) {
+    if (flags[cat] !== undefined) {
+      category = cat;
+      // Flag parser may consume the next arg as value — restore it
+      if (typeof flags[cat] === 'string') {
+        args.unshift(flags[cat]);
+      }
+      break;
+    }
+  }
+
+  if (!args.length) {
+    console.error(`❌ No text provided. Usage: agent-mem remember --${category} "your text"`);
+    process.exit(1);
+  }
+
+  const config = readConfig(ctxDir);
+  const branch = config.branch || 'main';
+  const baseTarget = flags.file || CATEGORIES[category].file;
+  const target = resolvePath(baseTarget, branch);
+  const { title, desc } = CATEGORIES[category] || CATEGORIES.note;
+  const text = args.join(' ');
+  const date = new Date().toISOString().slice(0, 10);
+  const time = new Date().toISOString().slice(11, 16);
+
+  let existing =
+    readContextFile(ctxDir, target) ||
+    ['---', `description: "${desc}"`, '---', '', `# ${title}`, ''].join('\n');
+
+  existing += `\n- [${date} ${time}] ${text}`;
+
+  writeContextFile(ctxDir, target, existing);
+  const branchLabel = branch !== 'main' ? ` [branch: ${branch}]` : '';
+  console.log(`✅ REMEMBERED (${category})${branchLabel} → .context/${target}`);
+  console.log(`  "${text}"`);
+
+  // Auto-commit if enabled
+  const { maybeAutoCommit } = await import('../core/auto-commit.js');
+  maybeAutoCommit(ctxDir, `remember ${category}`);
+}