@lmaksym/agent-mem 0.1.0

package/bin/agent-context.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+/**
+ * agent-mem — Context management CLI for AI coding agents
+ *
+ * Usage:
+ *   agent-mem init          Bootstrap context from codebase
+ *   agent-mem snapshot      Get context tree (agent's primary view)
+ *   agent-mem read <path>   Read a specific context file
+ *   agent-mem write <path>  Write/update a context file
+ *   agent-mem commit [msg]  Checkpoint progress
+ *   agent-mem status        Quick status overview
+ *   agent-mem remember      Quick-add to memory
+ *   agent-mem search        Search across context
+ *   agent-mem branch        Create exploration branch
+ *   agent-mem switch        Switch active branch
+ *   agent-mem merge         Merge branch back
+ *   agent-mem branches      List branches
+ *   agent-mem pin           Move file to system/ (always loaded)
+ *   agent-mem unpin         Move file out of system/
+ *   agent-mem config        Show/set configuration
+ *   agent-mem help          Show help
+ */
+
+import { resolve } from 'node:path';
+import { parseArgs } from './parse-args.js';
+import { findContextRoot } from '../src/core/context-root.js';
+
+const COMMANDS = {
+  init: () => import('../src/commands/init.js'),
+  snapshot: () => import('../src/commands/snapshot.js'),
+  read: () => import('../src/commands/read.js'),
+  write: () => import('../src/commands/write.js'),
+  commit: () => import('../src/commands/commit.js'),
+  status: () => import('../src/commands/status.js'),
+  remember: () => import('../src/commands/remember.js'),
+  search: () => import('../src/commands/search.js'),
+  branch: () => import('../src/commands/branch.js'),
+  switch: () => import('../src/commands/switch.js'),
+  merge: () => import('../src/commands/merge.js'),
+  branches: () => import('../src/commands/branches.js'),
+  pin: () => import('../src/commands/pin.js'),
+  unpin: () => import('../src/commands/unpin.js'),
+  reflect: () => import('../src/commands/reflect.js'),
+  compact: () => import('../src/commands/compact.js'),
+  resolve: () => import('../src/commands/resolve.js'),
+  diff: () => import('../src/commands/diff.js'),
+  forget: () => import('../src/commands/forget.js'),
+  lesson: () => import('../src/commands/lesson.js'),
+  sync: () => import('../src/commands/sync.js'),
+  track: () => import('../src/commands/track.js'),
+  push: () => import('../src/commands/push.js'),
+  pull: () => import('../src/commands/pull.js'),
+  share: () => import('../src/commands/share.js'),
+  import: () => import('../src/commands/import.js'),
+  config: () => import('../src/commands/config.js'),
+  help: () => import('../src/commands/help.js'),
+};
+
+async function main() {
+  const { command, args, flags } = parseArgs(process.argv.slice(2));
+
+  if (!command || command === 'help' || flags.help || flags.h) {
+    const mod = await COMMANDS.help();
+    await mod.default({ args, flags });
+    process.exit(0);
+  }
+
+  if (!(command in COMMANDS)) {
+    console.error(`❌ Unknown command: ${command}`);
+    console.error(`Run 'agent-mem help' for available commands.`);
+    process.exit(1);
+  }
+
+  // All commands except init, help, pull, import require an existing .context/
+  if (!['init', 'help', 'pull', 'import'].includes(command)) {
+    const root = findContextRoot(process.cwd());
+    if (!root) {
+      console.error(`❌ No .context/ found. Run 'agent-mem init' first.`);
+      process.exit(1);
+    }
+    flags._contextRoot = root;
+  }
+
+  try {
+    const mod = await COMMANDS[command]();
+    await mod.default({ args, flags });
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    if (flags.verbose) console.error(err.stack);
+    process.exit(1);
+  }
+}
+
+main();

package/bin/parse-args.js

@@ -0,0 +1,85 @@
+/**
+ * Minimal argument parser. Zero deps.
+ *
+ * parseArgs(["init", "--from-claude", "--verbose"])
+ * → { command: "init", args: [], flags: { "from-claude": true, verbose: true } }
+ *
+ * parseArgs(["read", "memory/decisions.md"])
+ * → { command: "read", args: ["memory/decisions.md"], flags: {} }
+ *
+ * parseArgs(["commit", "implemented auth flow"])
+ * → { command: "commit", args: ["implemented", "auth", "flow"], flags: {} }
+ */
+
+export function parseArgs(argv) {
+  const flags = {};
+  const args = [];
+  let command = null;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    if (!command && !arg.startsWith('-')) {
+      command = arg;
+      continue;
+    }
+
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const eqIdx = key.indexOf('=');
+      if (eqIdx !== -1) {
+        flags[key.slice(0, eqIdx)] = key.slice(eqIdx + 1);
+      } else {
+        // Boolean-only flags (never consume next arg as value)
+        const BOOLEAN_FLAGS = new Set([
+          'help',
+          'h',
+          'verbose',
+          'force',
+          'deep',
+          'compare',
+          'landscape',
+          'from-claude',
+          'from-codex',
+          'json',
+          'no-fetch',
+          'decision',
+          'pattern',
+          'mistake',
+          'note',
+          'all',
+          'claude',
+          'gemini',
+          'codex',
+          'cursor',
+          'windsurf',
+          'enable',
+          'disable',
+          'merge',
+          'dry-run',
+          'dry-run',
+          'compaction',
+          'hard',
+        ]);
+        if (BOOLEAN_FLAGS.has(key)) {
+          flags[key] = true;
+        } else {
+          // Check if next arg is a value
+          const next = argv[i + 1];
+          if (next && !next.startsWith('-')) {
+            flags[key] = next;
+            i++;
+          } else {
+            flags[key] = true;
+          }
+        }
+      }
+    } else if (arg.startsWith('-') && arg.length === 2) {
+      flags[arg.slice(1)] = true;
+    } else {
+      args.push(arg);
+    }
+  }
+
+  return { command, args, flags };
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@lmaksym/agent-mem",
+  "version": "0.1.0",
+  "description": "Persistent, git-backed memory for AI coding agents.",
+  "type": "module",
+  "bin": {
+    "agent-mem": "./bin/agent-context.js",
+    "amem": "./bin/agent-context.js"
+  },
+  "scripts": {
+    "start": "node bin/agent-context.js",
+    "test": "node --test src/**/*.test.js",
+    "format": "prettier --write 'src/**/*.js' 'bin/**/*.js'",
+    "format:check": "prettier --check 'src/**/*.js' 'bin/**/*.js'",
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "*.js": "prettier --write"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "context",
+    "memory",
+    "cli",
+    "claude-code",
+    "codex",
+    "cursor",
+    "coding-agent",
+    "agent-skills"
+  ],
+  "author": "Maksym Lypivskyi",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lmaksym/agent-context.git"
+  },
+  "homepage": "https://github.com/lmaksym/agent-context",
+  "bugs": {
+    "url": "https://github.com/lmaksym/agent-context/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    ".claude/commands/",
+    ".claude/skills/",
+    "LICENSE",
+    "README.md"
+  ],
+  "devDependencies": {
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.8.1"
+  }
+}

package/src/commands/branch.js

@@ -0,0 +1,57 @@
+import { contextDir as getContextDir } from '../core/context-root.js';
+import { writeContextFile, readContextFile } from '../core/fs.js';
+import { readConfig, writeConfig } from '../core/config.js';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export default async function branch({ args, flags }) {
+  const root = flags._contextRoot;
+  const ctxDir = getContextDir(root);
+
+  if (!args.length) {
+    console.error('❌ Usage: agent-mem branch <name> [purpose]');
+    console.error('Example: agent-mem branch try-qdrant "evaluate vector search"');
+    process.exit(1);
+  }
+
+  const name = args[0];
+  const purpose = args.slice(1).join(' ') || '';
+  const branchDir = join(ctxDir, 'branches', name);
+
+  if (existsSync(branchDir)) {
+    console.error(`❌ Branch "${name}" already exists.`);
+    process.exit(1);
+  }
+
+  const date = new Date().toISOString().slice(0, 10);
+
+  writeContextFile(
+    ctxDir,
+    `branches/${name}/purpose.md`,
+    [`# Branch: ${name}`, '', purpose || 'Purpose not specified.', '', `Created: ${date}`, ''].join(
+      '\n',
+    ),
+  );
+
+  writeContextFile(
+    ctxDir,
+    `branches/${name}/commits.md`,
+    [`# Commits: ${name}`, '', 'Milestone log for this branch.', ''].join('\n'),
+  );
+
+  writeContextFile(
+    ctxDir,
+    `branches/${name}/trace.md`,
+    [`# Trace: ${name}`, '', 'Fine-grained execution log.', ''].join('\n'),
+  );
+
+  // Switch to new branch
+  const config = readConfig(ctxDir);
+  config.branch = name;
+  writeConfig(ctxDir, config);
+
+  console.log(`✅ BRANCHED: ${name}`);
+  if (purpose) console.log(`Purpose: ${purpose}`);
+  console.log(`Switched to branch: ${name}`);
+  console.log(`Files: branches/${name}/{purpose,commits,trace}.md`);
+}

package/src/commands/branch.test.js

@@ -0,0 +1,91 @@
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync, existsSync, readFileSync } 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');
+const run = (args, cwd) =>
+  execSync(`node ${CLI} ${args}`, { cwd, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+
+describe('branch / switch / merge / branches', () => {
+  let dir;
+
+  before(() => {
+    dir = mkdtempSync(join(tmpdir(), 'amem-test-branch-'));
+    writeFileSync(join(dir, 'package.json'), '{}');
+    run('init', dir);
+  });
+
+  after(() => rmSync(dir, { recursive: true, force: true }));
+
+  it('creates a branch with purpose', () => {
+    const out = run('branch try-redis "evaluate Redis for caching"', dir);
+    assert.ok(out.includes('BRANCHED: try-redis'));
+    assert.ok(existsSync(join(dir, '.context/branches/try-redis/purpose.md')));
+    assert.ok(existsSync(join(dir, '.context/branches/try-redis/commits.md')));
+    assert.ok(existsSync(join(dir, '.context/branches/try-redis/trace.md')));
+  });
+
+  it('switches config to new branch', () => {
+    const config = readFileSync(join(dir, '.context/config.yaml'), 'utf-8');
+    assert.ok(config.includes('branch: try-redis'));
+  });
+
+  it('lists branches', () => {
+    const out = run('branches', dir);
+    assert.ok(out.includes('try-redis'));
+    assert.ok(out.includes('evaluate Redis'));
+  });
+
+  it('switches back to main', () => {
+    const out = run('switch main', dir);
+    assert.ok(out.includes('SWITCHED'));
+    assert.ok(out.includes('main'));
+  });
+
+  it('refuses duplicate branch', () => {
+    assert.throws(() => run('branch try-redis', dir));
+  });
+
+  it('merges branch back', () => {
+    const out = run('merge try-redis "Redis too complex, using in-memory cache"', dir);
+    assert.ok(out.includes('MERGED: try-redis'));
+    assert.ok(existsSync(join(dir, '.context/memory/decisions.md')));
+    const decisions = readFileSync(join(dir, '.context/memory/decisions.md'), 'utf-8');
+    assert.ok(decisions.includes('Redis too complex'));
+  });
+
+  it('switches to main after merge', () => {
+    const config = readFileSync(join(dir, '.context/config.yaml'), 'utf-8');
+    assert.ok(config.includes('branch: main'));
+  });
+});
+
+describe('pin / unpin', () => {
+  let dir;
+
+  before(() => {
+    dir = mkdtempSync(join(tmpdir(), 'amem-test-pin-'));
+    writeFileSync(join(dir, 'package.json'), '{}');
+    run('init', dir);
+    run('remember --decision "test decision"', dir);
+  });
+
+  after(() => rmSync(dir, { recursive: true, force: true }));
+
+  it('pins a memory file to system/', () => {
+    const out = run('pin memory/decisions.md', dir);
+    assert.ok(out.includes('PINNED'));
+    assert.ok(existsSync(join(dir, '.context/system/decisions.md')));
+    assert.ok(!existsSync(join(dir, '.context/memory/decisions.md')));
+  });
+
+  it('unpins a system file to memory/', () => {
+    const out = run('unpin system/decisions.md', dir);
+    assert.ok(out.includes('UNPINNED'));
+    assert.ok(existsSync(join(dir, '.context/memory/decisions.md')));
+    assert.ok(!existsSync(join(dir, '.context/system/decisions.md')));
+  });
+});

package/src/commands/branches.js

@@ -0,0 +1,34 @@
+import { contextDir as getContextDir } from '../core/context-root.js';
+import { listFiles, readContextFile } from '../core/fs.js';
+import { readConfig } from '../core/config.js';
+
+export default async function branches({ args, flags }) {
+  const root = flags._contextRoot;
+  const ctxDir = getContextDir(root);
+  const config = readConfig(ctxDir);
+  const current = config.branch || 'main';
+
+  const branchNames = listFiles(ctxDir, 'branches');
+
+  console.log(`📂 BRANCHES:`);
+  console.log(`  ${current === 'main' ? '* ' : '  '}main (default)`);
+
+  if (!branchNames.length) {
+    console.log('\n  No exploration branches yet.');
+    console.log('  Create one: agent-mem branch <name> "purpose"');
+    return;
+  }
+
+  for (const name of branchNames) {
+    const purpose = readContextFile(ctxDir, `branches/${name}/purpose.md`);
+    const purposeLine =
+      purpose
+        ?.split('\n')
+        .find(
+          (l) =>
+            l.trim() && !l.startsWith('#') && !l.startsWith('---') && !l.startsWith('Created:'),
+        ) || '';
+    const marker = current === name ? '* ' : '  ';
+    console.log(`  ${marker}${name} — ${purposeLine.trim() || '(no purpose)'}`);
+  }
+}

package/src/commands/commit.js

@@ -0,0 +1,55 @@
+import { contextDir as getContextDir } from '../core/context-root.js';
+import { commitContext, hasChanges, commitCount, commitCountSince } from '../core/git.js';
+import { readConfig } from '../core/config.js';
+import { readContextFile } from '../core/fs.js';
+import { acquireLock } from '../core/lock.js';
+
+export default async function commit({ args, flags }) {
+  const root = flags._contextRoot;
+  const ctxDir = getContextDir(root);
+  const releaseLock = acquireLock(root);
+
+  try {
+    if (!hasChanges(ctxDir)) {
+      console.log('ℹ️  No changes to commit.');
+      return;
+    }
+
+    const message = args.length
+      ? args.join(' ')
+      : `checkpoint ${new Date().toISOString().slice(0, 16)}`;
+    const hash = commitContext(ctxDir, message);
+
+    if (!hash) {
+      console.log('ℹ️  No changes to commit.');
+      return;
+    }
+
+    const count = commitCount(ctxDir);
+    console.log(`✅ COMMITTED: "${message}"`);
+    console.log(`Commit: ${hash} | Total: ${count}`);
+
+    // Check if reflection is due (auto-commit trigger)
+    const config = readConfig(ctxDir);
+    if (config.reflection?.trigger === 'auto-commit') {
+      const freq = config.reflection?.frequency || 5;
+      // Find last reflection's commit hash
+      let sinceRef = null;
+      const stateRaw = readContextFile(ctxDir, '.reflect-state.json');
+      if (stateRaw) {
+        try {
+          sinceRef = JSON.parse(stateRaw).last_commit_hash;
+        } catch {}
+      }
+      const sinceLast = sinceRef ? commitCountSince(ctxDir, sinceRef) : count;
+      if (sinceLast >= freq) {
+        console.log('');
+        console.log(
+          `📌 REFLECTION DUE: ${sinceLast} commits since last reflection. Run: amem reflect`,
+        );
+      }
+    }
+  } finally {
+    releaseLock();
+  }
+}