@lmaksym/agent-mem 0.1.0

package/src/commands/init.js

@@ -0,0 +1,269 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, cpSync } from 'node:fs';
+import { join, basename, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execSync } from 'node:child_process';
+import { writeContextFile, readContextFile } from '../core/fs.js';
+import { writeConfig } from '../core/config.js';
+import { initGit, commitContext } from '../core/git.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PACKAGE_ROOT = join(__dirname, '..', '..');
+
+export default async function init({ args, flags }) {
+  const cwd = process.cwd();
+  const contextDir = join(cwd, '.context');
+
+  if (existsSync(contextDir) && !flags.force) {
+    console.log(`⚠️  .context/ already exists. Use --force to reinitialize.`);
+    return;
+  }
+
+  console.log(`🔍 Scanning project...`);
+
+  // Detect project info
+  const projectName = basename(cwd);
+  const projectInfo = detectProject(cwd);
+
+  // Create directory structure
+  mkdirSync(join(contextDir, 'system', 'humans'), { recursive: true });
+  mkdirSync(join(contextDir, 'memory'), { recursive: true });
+  mkdirSync(join(contextDir, 'branches'), { recursive: true });
+  mkdirSync(join(contextDir, 'reflections'), { recursive: true });
+
+  // Generate main.md
+  writeContextFile(
+    contextDir,
+    'main.md',
+    [
+      `# ${projectName}`,
+      '',
+      '## Goals',
+      '- [ ] Define project goals',
+      '',
+      '## Milestones',
+      '- [ ] Define milestones',
+      '',
+      '## Status',
+      `Initialized: ${new Date().toISOString().slice(0, 10)}`,
+      '',
+    ].join('\n'),
+  );
+
+  // Generate system/project.md
+  writeContextFile(
+    contextDir,
+    'system/project.md',
+    [
+      '---',
+      `description: "${projectInfo.description || `Project: ${projectName}`}"`,
+      'limit: 10000',
+      '---',
+      '',
+      `# ${projectName}`,
+      '',
+      projectInfo.description ? `${projectInfo.description}\n` : '',
+      projectInfo.stack ? `## Stack\n${projectInfo.stack}\n` : '',
+      projectInfo.structure ? `## Structure\n${projectInfo.structure}\n` : '',
+    ].join('\n'),
+  );
+
+  // Generate system/conventions.md
+  writeContextFile(
+    contextDir,
+    'system/conventions.md',
+    [
+      '---',
+      'description: "Coding conventions and style rules"',
+      'limit: 5000',
+      '---',
+      '',
+      '# Conventions',
+      '',
+      'Add project-specific coding conventions here.',
+      '',
+    ].join('\n'),
+  );
+
+  // Import from CLAUDE.md if it exists
+  if (flags['from-claude'] || existsSync(join(cwd, 'CLAUDE.md'))) {
+    importClaudeMd(cwd, contextDir);
+  }
+
+  // Import session histories
+  if (flags['from-claude']) {
+    const { importClaudeHistory } = await import('../core/importers.js');
+    importClaudeHistory(cwd, contextDir);
+  }
+
+  if (flags['from-codex']) {
+    const { importCodexHistory } = await import('../core/importers.js');
+    importCodexHistory(cwd, contextDir);
+  }
+
+  // Write default config
+  writeConfig(contextDir, {
+    auto_commit: false,
+    auto_commit_interval: 10,
+    reflection: {
+      trigger: 'manual',
+      frequency: 5,
+      model: null,
+    },
+    system_files_max: 10,
+    memory_files_max: 25,
+    branch: 'main',
+  });
+
+  // Install agent skill to detected IDE directories
+  const installedSkills = installSkills(cwd);
+
+  // Initialize git
+  initGit(contextDir);
+  const hash = commitContext(contextDir, 'init: bootstrap context');
+
+  // Auto-sync to detected IDE rule files
+  const syncMod = await import('./sync.js');
+  await syncMod.default({ args: [], flags: { ...flags, _contextRoot: cwd } });
+
+  // Output
+  const systemFiles = readdirSync(join(contextDir, 'system')).filter((f) => !f.startsWith('.'));
+  console.log(
+    `
+✅ INITIALIZED: .context/
+Project: ${projectName}
+${projectInfo.stack ? `Stack: ${projectInfo.stack.split('\n')[0]}` : ''}
+
+Files created:
+  main.md — project roadmap
+  system/project.md — project overview
+  system/conventions.md — coding conventions
+  config.yaml — settings
+  memory/ — learned context (empty)
+  branches/ — exploration branches (empty)
+${installedSkills.length ? `\nSkill installed to:\n${installedSkills.map((s) => `  ${s}`).join('\n')}` : ''}
+${hash ? `\nGit commit: ${hash}` : ''}
+
+Next steps:
+  agent-mem snapshot    — view your context
+  agent-mem write system/conventions.md — add your coding rules
+  agent-mem commit "added conventions"  — checkpoint
+`.trim(),
+  );
+}
+
+/**
+ * Install the agent-mem skill to the 3 universal Agent Skills directories.
+ * These cover ~14 of the 16 tools that support the agentskills.io standard:
+ *
+ *   .claude/skills/   — Claude Code, Goose, Amp, OpenCode, Cline
+ *   .agents/skills/   — Codex CLI, Gemini CLI, Amp, OpenCode, Warp, Roo Code, Goose
+ *   .github/skills/   — VS Code Copilot, GitHub Copilot
+ */
+function installSkills(cwd) {
+  const sourceDir = join(PACKAGE_ROOT, '.claude', 'skills', 'agent-mem');
+  if (!existsSync(sourceDir)) return [];
+
+  const targets = [
+    '.claude/skills/agent-mem',
+    '.agents/skills/agent-mem',
+    '.github/skills/agent-mem',
+  ];
+
+  const installed = [];
+
+  for (const skills of targets) {
+    const targetDir = join(cwd, skills);
+
+    try {
+      cpSync(sourceDir, targetDir, { recursive: true });
+      installed.push(skills);
+    } catch {
+      // Silent fail — permissions or other issues
+    }
+  }
+
+  return installed;
+}
+
+/**
+ * Detect project type, stack, and structure from common files.
+ */
+function detectProject(cwd) {
+  const info = { description: '', stack: '', structure: '' };
+
+  // package.json
+  const pkgPath = join(cwd, 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      info.description = pkg.description || '';
+      const deps = Object.keys({ ...pkg.dependencies, ...pkg.devDependencies });
+      const stackItems = [];
+
+      if (deps.includes('next')) stackItems.push('Next.js');
+      if (deps.includes('react')) stackItems.push('React');
+      if (deps.includes('vue')) stackItems.push('Vue');
+      if (deps.includes('svelte') || deps.includes('@sveltejs/kit')) stackItems.push('Svelte');
+      if (deps.includes('express')) stackItems.push('Express');
+      if (deps.includes('fastify')) stackItems.push('Fastify');
+      if (deps.includes('typescript')) stackItems.push('TypeScript');
+      if (deps.includes('tailwindcss')) stackItems.push('Tailwind CSS');
+      if (deps.includes('prisma') || deps.includes('@prisma/client')) stackItems.push('Prisma');
+      if (deps.includes('drizzle-orm')) stackItems.push('Drizzle');
+
+      if (stackItems.length) info.stack = stackItems.join(', ');
+    } catch {}
+  }
+
+  // pyproject.toml / requirements.txt
+  if (existsSync(join(cwd, 'pyproject.toml')) || existsSync(join(cwd, 'requirements.txt'))) {
+    const stackItems = ['Python'];
+    try {
+      const content = existsSync(join(cwd, 'pyproject.toml'))
+        ? readFileSync(join(cwd, 'pyproject.toml'), 'utf-8')
+        : readFileSync(join(cwd, 'requirements.txt'), 'utf-8');
+
+      if (content.includes('fastapi')) stackItems.push('FastAPI');
+      if (content.includes('django')) stackItems.push('Django');
+      if (content.includes('flask')) stackItems.push('Flask');
+      if (content.includes('langchain')) stackItems.push('LangChain');
+      if (content.includes('langgraph')) stackItems.push('LangGraph');
+      if (content.includes('sqlalchemy') || content.includes('alembic'))
+        stackItems.push('SQLAlchemy');
+
+      info.stack = (info.stack ? info.stack + ', ' : '') + stackItems.join(', ');
+    } catch {}
+  }
+
+  // Top-level structure
+  try {
+    const items = readdirSync(cwd)
+      .filter(
+        (n) =>
+          !n.startsWith('.') &&
+          !['node_modules', '__pycache__', 'venv', '.venv', 'dist', 'build'].includes(n),
+      )
+      .slice(0, 20);
+    info.structure = items.map((n) => `- ${n}/`).join('\n');
+  } catch {}
+
+  return info;
+}
+
+/**
+ * Import existing CLAUDE.md into context.
+ */
+function importClaudeMd(cwd, contextDir) {
+  const claudePath = join(cwd, 'CLAUDE.md');
+  if (!existsSync(claudePath)) return;
+
+  const content = readFileSync(claudePath, 'utf-8');
+  writeContextFile(
+    contextDir,
+    'memory/imported-claude-md.md',
+    ['---', 'description: "Imported from CLAUDE.md"', '---', '', content].join('\n'),
+  );
+
+  console.log(`  📥 Imported CLAUDE.md → memory/imported-claude-md.md`);
+}

package/src/commands/init.test.js

@@ -0,0 +1,80 @@
+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('init', () => {
+  let dir;
+
+  before(() => {
+    dir = mkdtempSync(join(tmpdir(), 'amem-test-init-'));
+    writeFileSync(
+      join(dir, 'package.json'),
+      JSON.stringify({
+        name: 'test-proj',
+        dependencies: { next: '15', react: '19', typescript: '5' },
+      }),
+    );
+  });
+
+  after(() => rmSync(dir, { recursive: true, force: true }));
+
+  it('creates .context/ directory', () => {
+    const out = run('init', dir);
+    assert.ok(existsSync(join(dir, '.context')));
+    assert.ok(out.includes('INITIALIZED'));
+  });
+
+  it('detects stack from package.json', () => {
+    const project = readFileSync(join(dir, '.context/system/project.md'), 'utf-8');
+    assert.ok(project.includes('Next.js'));
+    assert.ok(project.includes('React'));
+    assert.ok(project.includes('TypeScript'));
+  });
+
+  it('creates required files', () => {
+    assert.ok(existsSync(join(dir, '.context/main.md')));
+    assert.ok(existsSync(join(dir, '.context/config.yaml')));
+    assert.ok(existsSync(join(dir, '.context/system/project.md')));
+    assert.ok(existsSync(join(dir, '.context/system/conventions.md')));
+  });
+
+  it('initializes git repo', () => {
+    assert.ok(existsSync(join(dir, '.context/.git')));
+  });
+
+  it('refuses reinit without --force', () => {
+    const out = run('init', dir);
+    assert.ok(out.includes('already exists'));
+  });
+
+  it('reinitializes with --force', () => {
+    const out = run('init --force', dir);
+    assert.ok(out.includes('INITIALIZED'));
+  });
+});
+
+describe('init --from-claude', () => {
+  let dir;
+
+  before(() => {
+    dir = mkdtempSync(join(tmpdir(), 'amem-test-claude-'));
+    writeFileSync(join(dir, 'package.json'), '{}');
+    writeFileSync(join(dir, 'CLAUDE.md'), '# Project Rules\n\nAlways use TypeScript.\n');
+  });
+
+  after(() => rmSync(dir, { recursive: true, force: true }));
+
+  it('imports CLAUDE.md', () => {
+    const out = run('init --from-claude', dir);
+    assert.ok(out.includes('Imported CLAUDE.md'));
+    const imported = readFileSync(join(dir, '.context/memory/imported-claude-md.md'), 'utf-8');
+    assert.ok(imported.includes('Always use TypeScript'));
+  });
+});

package/src/commands/lesson.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 LESSON_FILE = 'memory/lessons.md';
+const LESSON_TITLE = 'Lessons Learned';
+const LESSON_DESC = 'Lessons learned — problem/resolution pairs';
+
+/**
+ * Resolve memory file path based on active branch.
+ * On main: memory/lessons.md
+ * On branch: branches/<name>/memory/lessons.md
+ */
+function resolvePath(target, branch) {
+  if (branch && branch !== 'main') {
+    return target.replace(/^memory\//, `branches/${branch}/memory/`);
+  }
+  return target;
+}
+
+export default async function lesson({ args, flags }) {
+  const root = flags._contextRoot;
+  const ctxDir = getContextDir(root);
+
+  if (!args.length && !flags.problem) {
+    console.error(
+      '❌ Usage: agent-mem lesson <title> --problem <text> --resolution <text> [--tags <tags>]',
+    );
+    console.error('');
+    console.error('Or use shorthand with -> separator:');
+    console.error('  agent-mem lesson "Hit 429 rate limit -> implement exponential backoff"');
+    console.error('');
+    console.error('Examples:');
+    console.error(
+      '  agent-mem lesson "API backoff" --problem "Hit 429 on rapid calls" --resolution "Added exponential backoff"',
+    );
+    console.error('  agent-mem lesson "VAD fix -> Lower threshold to 0.3" --tags "voice, audio"');
+    process.exit(1);
+  }
+
+  const config = readConfig(ctxDir);
+  const branch = config.branch || 'main';
+  const target = resolvePath(LESSON_FILE, branch);
+  const text = args.join(' ');
+  const date = new Date().toISOString().slice(0, 10);
+  const time = new Date().toISOString().slice(11, 16);
+
+  let title, problem, resolution, tags;
+
+  if (flags.problem && flags.resolution) {
+    title = text || flags.problem;
+    problem = typeof flags.problem === 'string' ? flags.problem : '';
+    resolution = typeof flags.resolution === 'string' ? flags.resolution : '';
+    tags = typeof flags.tags === 'string' ? flags.tags : null;
+  } else if (text.includes('->')) {
+    const sepIdx = text.indexOf('->');
+    const before = text.slice(0, sepIdx).trim();
+    const after = text.slice(sepIdx + 2).trim();
+    if (!before || !after) {
+      console.error('❌ Both sides of -> must have content.');
+      console.error('  Example: "Hit 429 rate limit -> implement exponential backoff"');
+      process.exit(1);
+    }
+    title = text.replace('->', '—');
+    problem = before;
+    resolution = after;
+    tags = typeof flags.tags === 'string' ? flags.tags : null;
+  } else {
+    console.error('❌ Lessons need a problem and resolution.');
+    console.error('  Use --problem and --resolution flags, or -> shorthand:');
+    console.error('  agent-mem lesson "problem -> resolution"');
+    process.exit(1);
+  }
+
+  // Build lesson block
+  let block = `\n### [${date} ${time}] ${title}\n`;
+  block += `**Problem:** ${problem}\n`;
+  block += `**Resolution:** ${resolution}\n`;
+  if (tags) block += `**Tags:** ${tags}\n`;
+
+  let existing =
+    readContextFile(ctxDir, target) ||
+    ['---', `description: "${LESSON_DESC}"`, '---', '', `# ${LESSON_TITLE}`, ''].join('\n');
+
+  existing += block;
+
+  writeContextFile(ctxDir, target, existing);
+  const branchLabel = branch !== 'main' ? ` [branch: ${branch}]` : '';
+  console.log(`✅ LESSON${branchLabel} → .context/${target}`);
+  console.log(`  "${title}"`);
+
+  // Auto-commit if enabled
+  const { maybeAutoCommit } = await import('../core/auto-commit.js');
+  maybeAutoCommit(ctxDir, 'lesson learned');
+}

package/src/commands/lesson.test.js

@@ -0,0 +1,93 @@
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, readFileSync, mkdirSync, writeFileSync } 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('lesson', () => {
+  let dir;
+
+  before(() => {
+    dir = mkdtempSync(join(tmpdir(), 'amem-test-lesson-'));
+    writeFileSync(join(dir, 'package.json'), '{}');
+    run('init', dir);
+  });
+
+  after(() => rmSync(dir, { recursive: true, force: true }));
+
+  it('creates lesson with --problem and --resolution flags', () => {
+    run(
+      'lesson "API backoff" --problem "Hit 429 rate limit" --resolution "Added exponential backoff"',
+      dir,
+    );
+    const content = readFileSync(join(dir, '.context/memory/lessons.md'), 'utf-8');
+    assert.ok(content.includes('API backoff'));
+    assert.ok(content.includes('**Problem:** Hit 429 rate limit'));
+    assert.ok(content.includes('**Resolution:** Added exponential backoff'));
+  });
+
+  it('creates lesson with -> shorthand', () => {
+    run('lesson "Voice cut off -> Lower VAD threshold to 0.3"', dir);
+    const content = readFileSync(join(dir, '.context/memory/lessons.md'), 'utf-8');
+    assert.ok(content.includes('**Problem:** Voice cut off'));
+    assert.ok(content.includes('**Resolution:** Lower VAD threshold to 0.3'));
+  });
+
+  it('includes tags when provided', () => {
+    run(
+      'lesson "Memory leak" --problem "OOM after 1hr" --resolution "Close DB connections" --tags "infra, database"',
+      dir,
+    );
+    const content = readFileSync(join(dir, '.context/memory/lessons.md'), 'utf-8');
+    assert.ok(content.includes('**Tags:** infra, database'));
+  });
+
+  it('appends multiple lessons to same file', () => {
+    const content = readFileSync(join(dir, '.context/memory/lessons.md'), 'utf-8');
+    const headings = content.split('\n').filter((l) => l.startsWith('### ['));
+    assert.ok(headings.length >= 3, `Expected at least 3 lessons, got ${headings.length}`);
+  });
+
+  it('has correct frontmatter and title', () => {
+    const content = readFileSync(join(dir, '.context/memory/lessons.md'), 'utf-8');
+    assert.ok(content.includes('# Lessons Learned'));
+    assert.ok(content.includes('description:'));
+  });
+
+  it('fails without problem/resolution or -> separator', () => {
+    assert.throws(() => run('lesson "just some text"', dir));
+  });
+
+  it('fails with empty -> sides', () => {
+    assert.throws(() => run('lesson "-> only resolution"', dir));
+  });
+});
+
+describe('lesson on branch', () => {
+  let dir;
+
+  before(() => {
+    dir = mkdtempSync(join(tmpdir(), 'amem-test-lesson-branch-'));
+    writeFileSync(join(dir, 'package.json'), '{}');
+    run('init', dir);
+    run('branch test-branch exploring', dir);
+  });
+
+  after(() => rmSync(dir, { recursive: true, force: true }));
+
+  it('saves lesson to branch-scoped path', () => {
+    run('lesson "Branch fix -> Applied workaround"', dir);
+    const content = readFileSync(
+      join(dir, '.context/branches/test-branch/memory/lessons.md'),
+      'utf-8',
+    );
+    assert.ok(content.includes('Branch fix'));
+    assert.ok(content.includes('**Problem:** Branch fix'));
+    assert.ok(content.includes('**Resolution:** Applied workaround'));
+  });
+});

package/src/commands/merge.js

@@ -0,0 +1,105 @@
+import { contextDir as getContextDir } from '../core/context-root.js';
+import { readContextFile, writeContextFile, listFiles } 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 merge({ args, flags }) {
+  const root = flags._contextRoot;
+  const ctxDir = getContextDir(root);
+
+  if (!args.length) {
+    console.error('❌ Usage: agent-mem merge <branch-name> [summary]');
+    process.exit(1);
+  }
+
+  const name = args[0];
+  const summary = args.slice(1).join(' ') || '';
+  const branchDir = join(ctxDir, 'branches', name);
+
+  if (!existsSync(branchDir)) {
+    console.error(`❌ Branch "${name}" not found.`);
+    process.exit(1);
+  }
+
+  // Read branch files
+  const purpose = readContextFile(ctxDir, `branches/${name}/purpose.md`) || '';
+  const commits = readContextFile(ctxDir, `branches/${name}/commits.md`) || '';
+  const trace = readContextFile(ctxDir, `branches/${name}/trace.md`) || '';
+
+  // Append to memory/decisions.md
+  const date = new Date().toISOString().slice(0, 10);
+  const decisionEntry = [
+    `\n## [${date}] Merged branch: ${name}`,
+    '',
+    purpose.trim() ? `### Purpose\n${purpose.replace(/^#.*\n/, '').trim()}` : '',
+    summary ? `### Summary\n${summary}` : '',
+    commits.trim() ? `### Commits\n${commits.replace(/^#.*\n/, '').trim()}` : '',
+    '',
+  ]
+    .filter(Boolean)
+    .join('\n');
+
+  let decisions =
+    readContextFile(ctxDir, 'memory/decisions.md') ||
+    [
+      '---',
+      'description: "Architectural decisions and branch merge outcomes"',
+      '---',
+      '',
+      '# Decisions',
+      '',
+    ].join('\n');
+
+  decisions += decisionEntry;
+  writeContextFile(ctxDir, 'memory/decisions.md', decisions);
+
+  // Merge branch-scoped memory into main memory
+  const branchMemDir = join(ctxDir, 'branches', name, 'memory');
+  let mergedCount = 0;
+  if (existsSync(branchMemDir)) {
+    const branchMemFiles = listFiles(ctxDir, `branches/${name}/memory`);
+    for (const memFile of branchMemFiles) {
+      if (!memFile.endsWith('.md')) continue;
+      const branchContent = readContextFile(ctxDir, `branches/${name}/memory/${memFile}`);
+      if (!branchContent) continue;
+
+      // Extract entries (lines starting with "- [")
+      const branchEntries = branchContent.split('\n').filter((l) => /^- \[/.test(l));
+      if (!branchEntries.length) continue;
+
+      const mainPath = `memory/${memFile}`;
+      let mainContent = readContextFile(ctxDir, mainPath);
+
+      if (!mainContent) {
+        // Create the main file with branch content header
+        const headerMatch = branchContent.match(/^---\n[\s\S]*?\n---\n[\s\S]*?(?=\n- \[)/);
+        mainContent = headerMatch ? headerMatch[0] : `# ${memFile.replace('.md', '')}\n`;
+      }
+
+      // Deduplicate: only append entries not already in main
+      const mainLines = new Set(mainContent.split('\n'));
+      const newEntries = branchEntries.filter((e) => !mainLines.has(e));
+
+      if (newEntries.length) {
+        mainContent += '\n' + newEntries.join('\n');
+        writeContextFile(ctxDir, mainPath, mainContent);
+        mergedCount += newEntries.length;
+      }
+    }
+  }
+
+  // Switch back to main
+  const config = readConfig(ctxDir);
+  config.branch = 'main';
+  writeConfig(ctxDir, config);
+
+  console.log(`✅ MERGED: ${name} → main`);
+  if (summary) console.log(`Summary: ${summary}`);
+  console.log(`Branch findings saved to memory/decisions.md`);
+  if (mergedCount > 0) {
+    console.log(`Merged ${mergedCount} branch memory entries into main memory`);
+  }
+  console.log(`Switched to: main`);
+  console.log(`\nNote: branch files preserved at branches/${name}/ for reference.`);
+}

package/src/commands/pin.js

@@ -0,0 +1,34 @@
+import { contextDir as getContextDir } from '../core/context-root.js';
+import { moveContextFile, readContextFile } from '../core/fs.js';
+import { existsSync } from 'node:fs';
+import { join, basename } from 'node:path';
+
+export default async function pin({ args, flags }) {
+  const root = flags._contextRoot;
+  const ctxDir = getContextDir(root);
+
+  if (!args.length) {
+    console.error('❌ Usage: agent-mem pin <path>');
+    console.error('Example: agent-mem pin memory/decisions.md');
+    console.error("Moves the file into system/ so it's always in agent context.");
+    process.exit(1);
+  }
+
+  const relPath = args[0];
+  if (relPath.startsWith('system/')) {
+    console.log('ℹ️  Already pinned (in system/).');
+    return;
+  }
+
+  const name = basename(relPath);
+  const dest = `system/${name}`;
+
+  if (!existsSync(join(ctxDir, relPath))) {
+    console.error(`❌ File not found: .context/${relPath}`);
+    process.exit(1);
+  }
+
+  moveContextFile(ctxDir, relPath, dest);
+  console.log(`📌 PINNED: ${relPath} → ${dest}`);
+  console.log(`This file will now always be included in agent context.`);
+}