@lmaksym/agent-mem 0.1.0

package/src/commands/diff.js

@@ -0,0 +1,157 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { contextDir as getContextDir } from '../core/context-root.js';
+import { readContextFile } from '../core/fs.js';
+
+/**
+ * Collect all .md files recursively from a directory, returning { relPath → content }.
+ */
+function collectFiles(baseDir, subDir = '') {
+  const files = {};
+  const dir = subDir ? join(baseDir, subDir) : baseDir;
+  if (!existsSync(dir)) return files;
+
+  for (const name of readdirSync(dir)) {
+    if (name.startsWith('.')) continue;
+    const full = join(dir, name);
+    const rel = subDir ? `${subDir}/${name}` : name;
+    if (statSync(full).isDirectory()) {
+      Object.assign(files, collectFiles(baseDir, rel));
+    } else {
+      files[rel] = readFileSync(full, 'utf-8');
+    }
+  }
+  return files;
+}
+
+/**
+ * Simple line-based diff between two strings.
+ * Returns { added: string[], removed: string[], unchanged: number }
+ */
+function lineDiff(a, b) {
+  const aLines = new Set((a || '').split('\n'));
+  const bLines = new Set((b || '').split('\n'));
+  const added = [];
+  const removed = [];
+  let unchanged = 0;
+
+  for (const line of bLines) {
+    if (!aLines.has(line)) added.push(line);
+    else unchanged++;
+  }
+  for (const line of aLines) {
+    if (!bLines.has(line)) removed.push(line);
+  }
+
+  return { added, removed, unchanged };
+}
+
+export default async function diff({ args, flags }) {
+  const root = flags._contextRoot;
+  const ctxDir = getContextDir(root);
+
+  const branchName = args[0];
+  if (!branchName) {
+    console.error('❌ Usage: agent-mem diff <branch>');
+    console.error("Compare a branch's context with main.");
+    process.exit(1);
+  }
+
+  const branchDir = join(ctxDir, 'branches', branchName);
+  if (!existsSync(branchDir)) {
+    console.error(`❌ Branch "${branchName}" not found.`);
+    process.exit(1);
+  }
+
+  // Branch metadata files to exclude from diff (these are branch-level, not context)
+  const BRANCH_METADATA = new Set(['purpose.md', 'commits.md', 'trace.md']);
+
+  // Collect branch files, excluding metadata
+  const rawBranchFiles = collectFiles(branchDir);
+  const branchFiles = {};
+  for (const [path, content] of Object.entries(rawBranchFiles)) {
+    if (!BRANCH_METADATA.has(path)) {
+      branchFiles[path] = content;
+    }
+  }
+
+  // Collect main-level files (memory/, system/) for comparison
+  // Use same path structure as branch files for valid comparison
+  const mainFiles = {};
+  for (const dir of ['memory', 'system']) {
+    const collected = collectFiles(join(ctxDir, dir));
+    for (const [rel, content] of Object.entries(collected)) {
+      mainFiles[`${dir}/${rel}`] = content;
+    }
+  }
+  // Also include main.md
+  const mainMd = readContextFile(ctxDir, 'main.md');
+  if (mainMd) mainFiles['main.md'] = mainMd;
+
+  // Compute diffs
+  // Branches are sparse — only compare files that exist IN the branch.
+  // Files only in main are NOT "deleted" (branches don't clone main).
+  const diffs = [];
+  let totalAdded = 0;
+  let totalRemoved = 0;
+
+  for (const path of Object.keys(branchFiles).sort()) {
+    const mainContent = path in mainFiles ? mainFiles[path] : null;
+    const branchContent = branchFiles[path];
+
+    if (mainContent === branchContent) continue; // identical
+
+    if (mainContent === null) {
+      // File exists in branch but not in main — new file
+      diffs.push({ path, status: 'added', lines: branchContent.split('\n').length });
+      totalAdded += branchContent.split('\n').length;
+    } else {
+      // File exists in both — compare
+      const { added, removed } = lineDiff(mainContent, branchContent);
+      if (added.length || removed.length) {
+        diffs.push({ path, status: 'modified', added, removed });
+        totalAdded += added.length;
+        totalRemoved += removed.length;
+      }
+    }
+  }
+
+  // Output
+  console.log(`🔀 DIFF: main ↔ ${branchName}`);
+  console.log('');
+
+  if (diffs.length === 0) {
+    console.log('No differences found.');
+    return;
+  }
+
+  for (const d of diffs) {
+    if (d.status === 'added') {
+      console.log(`  + ${d.path} (new, ${d.lines} lines)`);
+    } else if (d.status === 'removed') {
+      console.log(`  - ${d.path} (deleted, ${d.lines} lines)`);
+    } else {
+      console.log(`  ~ ${d.path} (+${d.added.length} / -${d.removed.length})`);
+      if (flags.verbose) {
+        for (const line of d.added.slice(0, 5)) {
+          console.log(`    + ${line}`);
+        }
+        for (const line of d.removed.slice(0, 5)) {
+          console.log(`    - ${line}`);
+        }
+        const moreAdded = d.added.length - 5;
+        const moreRemoved = d.removed.length - 5;
+        if (moreAdded > 0 || moreRemoved > 0) {
+          console.log(
+            `    ... and ${Math.max(0, moreAdded)} more added, ${Math.max(0, moreRemoved)} more removed`,
+          );
+        }
+      }
+    }
+  }
+
+  console.log('');
+  console.log(
+    `Summary: ${diffs.length} file${diffs.length > 1 ? 's' : ''} changed, +${totalAdded} / -${totalRemoved} lines`,
+  );
+}

package/src/commands/diff.test.js

@@ -0,0 +1,64 @@
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+
+const CLI = join(import.meta.dirname, '../../bin/agent-context.js');
+
+function run(args, cwd) {
+  return execSync(`node ${CLI} ${args}`, { cwd, encoding: 'utf-8', timeout: 10000 });
+}
+
+describe('diff', () => {
+  let dir;
+
+  before(() => {
+    dir = mkdtempSync(join(tmpdir(), 'amem-diff-'));
+    execSync('git init', { cwd: dir, stdio: 'ignore' });
+    execSync('git config user.name "test"', { cwd: dir, stdio: 'ignore' });
+    execSync('git config user.email "test@test.com"', { cwd: dir, stdio: 'ignore' });
+    run('init', dir);
+    run('branch test-feature "testing diff"', dir);
+  });
+
+  after(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('fresh branch with no context changes shows no differences', () => {
+    const out = run('diff test-feature', dir);
+    assert.match(out, /DIFF.*main.*test-feature/);
+    assert.match(out, /No differences found/);
+    // Branch metadata should NOT appear
+    assert.ok(!out.includes('purpose.md'), 'should not show branch metadata');
+    assert.ok(!out.includes('commits.md'), 'should not show branch metadata');
+    // Main files should NOT appear as deleted
+    assert.ok(!out.includes('main.md'), 'should not show main files as deleted');
+    assert.ok(!out.includes('system/'), 'should not show system files as deleted');
+  });
+
+  it('shows added files in branch', () => {
+    const branchDir = join(dir, '.context', 'branches', 'test-feature');
+    mkdirSync(join(branchDir, 'memory'), { recursive: true });
+    writeFileSync(join(branchDir, 'memory', 'experiment.md'), '# Experiment\n- new finding\n');
+
+    const out = run('diff test-feature', dir);
+    assert.match(out, /experiment\.md/);
+    assert.match(out, /\+.*experiment/);
+  });
+
+  it('shows verbose line details', () => {
+    const out = run('diff test-feature --verbose', dir);
+    assert.match(out, /DIFF/);
+  });
+
+  it('errors on nonexistent branch', () => {
+    assert.throws(() => run('diff nonexistent', dir), /not found/);
+  });
+
+  it('errors with no branch argument', () => {
+    assert.throws(() => run('diff', dir), /Usage/);
+  });
+});

package/src/commands/forget.js

@@ -0,0 +1,77 @@
+import { existsSync, unlinkSync } from 'node:fs';
+import { join, resolve, relative } from 'node:path';
+import { contextDir as getContextDir } from '../core/context-root.js';
+import { readContextFile, writeContextFile } from '../core/fs.js';
+import { commitContext } from '../core/git.js';
+
+/**
+ * Normalize and validate a relative path within .context/.
+ * Returns the normalized relative path or null if invalid.
+ */
+function safePath(ctxDir, inputPath) {
+  const fullPath = resolve(ctxDir, inputPath);
+  const rel = relative(ctxDir, fullPath);
+  // Must not escape .context/ (no leading ..)
+  if (rel.startsWith('..') || rel.startsWith('/')) return null;
+  return rel;
+}
+
+export default async function forget({ args, flags }) {
+  const root = flags._contextRoot;
+  const ctxDir = getContextDir(root);
+
+  if (!args.length) {
+    console.error('❌ Usage: agent-mem forget <path>');
+    console.error('Remove a context file. Archived first for safety.');
+    console.error('');
+    console.error('Examples:');
+    console.error('  agent-mem forget memory/notes.md');
+    console.error('  agent-mem forget memory/old-patterns.md');
+    console.error('');
+    console.error('Cannot forget pinned (system/) files — unpin first.');
+    process.exit(1);
+  }
+
+  // Normalize path to prevent traversal
+  const relPath = safePath(ctxDir, args[0]);
+  if (!relPath) {
+    console.error('❌ Invalid path — must be inside .context/');
+    process.exit(1);
+  }
+
+  // Safety: don't allow forgetting system files (normalized)
+  if (relPath.startsWith('system/') || relPath === 'system') {
+    console.error("❌ Cannot forget pinned files. Run 'agent-mem unpin' first.");
+    process.exit(1);
+  }
+
+  // Safety: don't allow forgetting config
+  if (relPath === 'config.yaml') {
+    console.error('❌ Cannot forget config.yaml.');
+    process.exit(1);
+  }
+
+  const fullPath = join(ctxDir, relPath);
+  if (!existsSync(fullPath)) {
+    console.error(`❌ File not found: .context/${relPath}`);
+    process.exit(1);
+  }
+
+  // Archive before deleting
+  const content = readContextFile(ctxDir, relPath);
+  const today = new Date().toISOString().slice(0, 10);
+  const archivePath = `archive/forgotten-${today}/${relPath}`;
+  writeContextFile(ctxDir, archivePath, content);
+
+  // Remove the file
+  unlinkSync(fullPath);
+
+  // Commit
+  const hash = commitContext(ctxDir, `forget: removed ${relPath}`);
+
+  console.log(`🗑️  FORGOT: ${relPath}`);
+  console.log(`Archived: .context/${archivePath}`);
+  if (hash) console.log(`Committed: ${hash}`);
+  console.log('');
+  console.log('To restore: agent-mem read ' + archivePath);
+}

package/src/commands/forget.test.js

@@ -0,0 +1,68 @@
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, existsSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+
+const CLI = join(import.meta.dirname, '../../bin/agent-context.js');
+
+function run(args, cwd) {
+  return execSync(`node ${CLI} ${args}`, { cwd, encoding: 'utf-8', timeout: 10000 });
+}
+
+describe('forget', () => {
+  let dir;
+
+  before(() => {
+    dir = mkdtempSync(join(tmpdir(), 'amem-forget-'));
+    execSync('git init', { cwd: dir, stdio: 'ignore' });
+    execSync('git config user.name "test"', { cwd: dir, stdio: 'ignore' });
+    execSync('git config user.email "test@test.com"', { cwd: dir, stdio: 'ignore' });
+    run('init', dir);
+
+    // Add a memory file to forget
+    const memFile = join(dir, '.context', 'memory', 'old-notes.md');
+    writeFileSync(memFile, '# Old Notes\n- outdated stuff\n');
+    execSync("git -C .context add -A && git -C .context commit -m 'add notes'", {
+      cwd: dir,
+      stdio: 'ignore',
+    });
+  });
+
+  after(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('removes file and archives it', () => {
+    const out = run('forget memory/old-notes.md', dir);
+    assert.match(out, /FORGOT.*old-notes\.md/);
+    assert.match(out, /Archived/);
+    assert.ok(!existsSync(join(dir, '.context', 'memory', 'old-notes.md')));
+    assert.ok(existsSync(join(dir, '.context', 'archive')));
+  });
+
+  it('refuses to forget pinned (system/) files', () => {
+    assert.throws(() => run('forget system/project.md', dir), /Cannot forget pinned/);
+  });
+
+  it('refuses ./system/ bypass', () => {
+    assert.throws(() => run('forget ./system/project.md', dir), /Cannot forget pinned/);
+  });
+
+  it('refuses to forget config.yaml', () => {
+    assert.throws(() => run('forget config.yaml', dir), /Cannot forget config/);
+  });
+
+  it('refuses ./config.yaml bypass', () => {
+    assert.throws(() => run('forget ./config.yaml', dir), /Cannot forget config/);
+  });
+
+  it('rejects path traversal (../)', () => {
+    assert.throws(() => run('forget ../outside.txt', dir), /Invalid path/);
+  });
+
+  it('errors on nonexistent file', () => {
+    assert.throws(() => run('forget memory/nope.md', dir), /not found/);
+  });
+});

package/src/commands/help.js

@@ -0,0 +1,99 @@
+export default async function help() {
+  console.log(
+    `
+agent-mem — Context management CLI for AI coding agents
+
+USAGE
+  agent-mem <command> [args] [flags]
+  amem <command> [args] [flags]
+
+CORE
+  init [--from-claude] [--from-codex]   Bootstrap context + auto-sync IDE rules
+  snapshot                               Context tree (agent's primary view)
+  read <path>                            Read a context file
+  write <path> [--content <text>]        Write/update a context file (reads stdin if no --content)
+  commit [message]                       Checkpoint: summarize + git commit
+  status                                 Quick status overview
+
+MEMORY
+  remember [--decision|--pattern|--mistake|--note] <text>
+                                         Add to memory (structured categories)
+  lesson <title> --problem <text> --resolution <text> [--tags <tags>]
+                                         Record a lesson learned (problem/resolution pair)
+                                         Shorthand: lesson "problem -> resolution"
+  search <query>                         Search across all context files
+  pin <path>                             Move file to system/ (always in context)
+  unpin <path>                           Move file out of system/
+  forget <path>                          Remove a memory file (archived first)
+
+BRANCHES
+  branch <name> [purpose]                Create exploration branch
+  switch <name>                          Switch active branch
+  merge <name> [summary]                 Merge branch back to main
+  branches                               List all branches
+  diff <branch>                          Compare branch context with main
+
+COMPACTION
+  compact                                Archive stale context, keep pins + recent
+  compact --dry-run                      Preview what would be archived
+  compact --hard                         Pins only, archive everything else
+
+CONFLICTS
+  resolve                                Auto-resolve .context/ merge conflicts
+  resolve --dry-run                      Preview resolution strategy per file
+
+REFLECTION
+  reflect                                Gather reflection input (default: gather)
+  reflect gather [--since <ref>] [--deep] [--compaction]
+                                         Collect recent activity for reflection
+  reflect save [--content <text>]        Save agent's reflection output
+  reflect history [--last <n>]           Show past reflections
+  reflect defrag [--dry-run]             Analyze memory health
+
+SYNC
+  sync [--claude|--gemini|--codex|--cursor|--windsurf|--all]
+                                         Export .context/ to IDE rule files
+                                         Auto-detects existing files if no flags
+
+SHARING
+  track [--enable|--disable]             Toggle .context/ in project git
+  push [--remote <url>]                  Push .context/ to its own remote
+  pull [--remote <url>]                  Pull/clone .context/ from remote
+  share [--output <path>]               Generate portable snapshot file
+  import <file>                          Import a shared snapshot
+
+CONFIG
+  config                                 Show current config
+  config set <key> <value>               Update config value
+
+FLAGS
+  --verbose                              Show detailed output
+  --help, -h                             Show this help
+
+EXAMPLES
+  agent-mem init
+  agent-mem snapshot
+  agent-mem commit "implemented auth flow"
+  agent-mem branch try-qdrant "evaluate vector search"
+  agent-mem remember --decision "chose Qdrant over Pinecone"
+  agent-mem remember --pattern "always check Grafana before fixing"
+  agent-mem remember --mistake "never force-push fix branches"
+  agent-mem lesson "API 429 -> implement exponential backoff"
+  agent-mem lesson "OOM fix" --problem "Memory leak after 1hr" --resolution "Close DB connections"
+  agent-mem search "authentication"
+  agent-mem reflect
+  agent-mem reflect save --content "## Patterns Identified..."
+  agent-mem reflect history
+  agent-mem reflect defrag --dry-run
+  agent-mem compact --dry-run         # preview compaction
+  agent-mem compact                  # archive stale, keep recent + pins
+  agent-mem compact --hard           # nuclear: pins only
+  agent-mem sync                     # auto-detect IDE files
+  agent-mem sync --claude            # export to CLAUDE.md
+  agent-mem sync --all               # export to all IDE formats
+
+MORE INFO
+  https://github.com/lmaksym/agent-mem
+`.trim(),
+  );
+}

package/src/commands/import.js

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { writeContextFile } from '../core/fs.js';
+import { initGit, commitContext } from '../core/git.js';
+
+/**
+ * Import a shared context snapshot.
+ *
+ * agent-mem import <file>            — import from snapshot file
+ * agent-mem import --merge           — merge into existing context (default: overwrite)
+ */
+export default async function importCmd({ args, flags }) {
+  if (!args.length) {
+    console.error('❌ Usage: agent-mem import <snapshot-file>');
+    console.error('Example: agent-mem import context-myproject-a1b2c3d4.json');
+    process.exit(1);
+  }
+
+  const filePath = args[0];
+
+  if (!existsSync(filePath)) {
+    console.error(`❌ File not found: ${filePath}`);
+    process.exit(1);
+  }
+
+  let snapshot;
+  try {
+    snapshot = JSON.parse(readFileSync(filePath, 'utf-8'));
+  } catch (err) {
+    console.error(`❌ Invalid snapshot file: ${err.message}`);
+    process.exit(1);
+  }
+
+  if (!snapshot.files || snapshot.version !== 1) {
+    console.error('❌ Unrecognized snapshot format.');
+    process.exit(1);
+  }
+
+  const cwd = process.cwd();
+  const ctxDir = join(cwd, '.context');
+  const isNew = !existsSync(ctxDir);
+
+  mkdirSync(ctxDir, { recursive: true });
+
+  // Write all files from snapshot
+  let written = 0;
+  let skipped = 0;
+
+  for (const [path, content] of Object.entries(snapshot.files)) {
+    if (!flags.merge) {
+      // Overwrite mode
+      writeContextFile(ctxDir, path, content);
+      written++;
+    } else {
+      // Merge mode — only write if file doesn't exist
+      const existing = join(ctxDir, path);
+      if (!existsSync(existing)) {
+        writeContextFile(ctxDir, path, content);
+        written++;
+      } else {
+        skipped++;
+      }
+    }
+  }
+
+  // Initialize git if new
+  if (isNew) {
+    initGit(ctxDir);
+  }
+
+  commitContext(
+    ctxDir,
+    `import: from ${snapshot.project || 'unknown'} (${snapshot.createdAt?.slice(0, 10) || '?'})`,
+  );
+
+  console.log(`✅ IMPORTED: ${snapshot.project || 'unknown'}`);
+  console.log(`  Files written: ${written}${skipped ? ` | Skipped (existing): ${skipped}` : ''}`);
+  console.log(
+    `  Source: ${snapshot.commits || '?'} commits, created ${snapshot.createdAt?.slice(0, 10) || '?'}`,
+  );
+  console.log('');
+  console.log('Run: agent-mem snapshot');
+}