agent-working-memory 0.6.0 → 0.6.1

package/src/adapters/claude-code.ts

@@ -0,0 +1,234 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Claude Code adapter — writes .mcp.json, CLAUDE.md, and hooks.
+ *
+ * This is a direct extraction of the original setup() behavior.
+ * Zero behavioral change from the monolithic version.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+import type { CLIAdapter, SetupContext, DiagnosticResult } from './types.js';
+import { resolveMcpCommand, homedir, AWM_INSTRUCTION_CONTENT } from './common.js';
+
+const adapter: CLIAdapter = {
+  id: 'claude-code',
+  name: 'Claude Code',
+  supportsProjectScope: true,
+  supportsGlobalScope: true,
+
+  writeMcpConfig(ctx: SetupContext): string {
+    const mcpCmd = resolveMcpCommand(ctx);
+    const mcpConfig = { ...mcpCmd, env: ctx.envVars };
+
+    // Global: ~/.mcp.json (standard MCP location, all projects)
+    // Project: .claude/mcp.json (Claude Code's native project scope)
+    const mcpJsonPath = ctx.isGlobal
+      ? join(homedir(), '.mcp.json')
+      : join(ctx.cwd, '.claude', 'mcp.json');
+
+    const mcpDir = dirname(mcpJsonPath);
+    if (!existsSync(mcpDir)) {
+      mkdirSync(mcpDir, { recursive: true });
+    }
+
+    let existing: any = {};
+    if (existsSync(mcpJsonPath)) {
+      try {
+        existing = JSON.parse(readFileSync(mcpJsonPath, 'utf-8'));
+      } catch {
+        existing = {};
+      }
+    }
+    if (!existing.mcpServers) existing.mcpServers = {};
+
+    existing.mcpServers['agent-working-memory'] = mcpConfig;
+    writeFileSync(mcpJsonPath, JSON.stringify(existing, null, 2) + '\n');
+    return `MCP config: ${mcpJsonPath}`;
+  },
+
+  writeInstructions(ctx: SetupContext, skip: boolean): string {
+    const claudeMdPath = ctx.isGlobal
+      ? join(homedir(), '.claude', 'CLAUDE.md')
+      : join(ctx.cwd, 'CLAUDE.md');
+
+    if (skip) return 'CLAUDE.md: skipped (--no-instructions)';
+
+    // Ensure parent directory exists
+    const dir = dirname(claudeMdPath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+
+    if (existsSync(claudeMdPath)) {
+      const content = readFileSync(claudeMdPath, 'utf-8');
+      if (content.includes('## Memory (AWM)')) {
+        return 'CLAUDE.md: already has AWM section (skipped)';
+      }
+      writeFileSync(claudeMdPath, content.trimEnd() + '\n\n' + AWM_INSTRUCTION_CONTENT);
+      return 'CLAUDE.md: appended AWM workflow section';
+    }
+
+    const title = ctx.isGlobal ? '# Global Instructions' : `# ${basename(ctx.cwd)}`;
+    writeFileSync(claudeMdPath, `${title}\n\n${AWM_INSTRUCTION_CONTENT}`);
+    return 'CLAUDE.md: created with AWM workflow section';
+  },
+
+  writeHooks(ctx: SetupContext, skip: boolean): string {
+    if (skip) return 'Hooks: skipped (--no-hooks)';
+
+    const settingsPath = join(homedir(), '.claude', 'settings.json');
+    let settings: any = {};
+    if (existsSync(settingsPath)) {
+      try {
+        settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+      } catch {
+        settings = {};
+      }
+    }
+    if (!settings.hooks) settings.hooks = {};
+
+    const hookUrl = `http://127.0.0.1:${ctx.hookPort}/hooks/checkpoint`;
+
+    // Stop — remind Claude to write/recall/switch tasks
+    settings.hooks.Stop = [{
+      matcher: '',
+      hooks: [{
+        type: 'command',
+        command: 'echo "MEMORY: (1) Did you learn anything new? Call memory_write. (2) Are you about to work on a topic you might have prior knowledge about? Call memory_recall. (3) Switching tasks? Call memory_task_begin."',
+        timeout: 5,
+        async: true,
+      }],
+    }];
+
+    // Multi-port fallback for separate memory pools
+    const altPort = ctx.hookPort === '8401' ? '8402' : '8401';
+    const hookUrlAlt = `http://127.0.0.1:${altPort}/hooks/checkpoint`;
+    const buildHookCmd = (event: string, maxTime: number) => {
+      const primary = `curl -sf -X POST ${hookUrl} -H "Content-Type: application/json" -H "Authorization: Bearer ${ctx.hookSecret}" -d "{\\"hook_event_name\\":\\"${event}\\"}" --max-time ${maxTime}`;
+      const fallback = `curl -sf -X POST ${hookUrlAlt} -H "Content-Type: application/json" -H "Authorization: Bearer ${ctx.hookSecret}" -d "{\\"hook_event_name\\":\\"${event}\\"}" --max-time ${maxTime}`;
+      return `${primary} || ${fallback}`;
+    };
+
+    // PreCompact — auto-checkpoint before context compaction
+    settings.hooks.PreCompact = [{
+      matcher: '',
+      hooks: [{
+        type: 'command',
+        command: buildHookCmd('PreCompact', 5),
+        timeout: 10,
+      }],
+    }];
+
+    // SessionEnd — auto-checkpoint on session close
+    settings.hooks.SessionEnd = [{
+      matcher: '',
+      hooks: [{
+        type: 'command',
+        command: buildHookCmd('SessionEnd', 2),
+        timeout: 5,
+      }],
+    }];
+
+    const settingsDir = dirname(settingsPath);
+    if (!existsSync(settingsDir)) {
+      mkdirSync(settingsDir, { recursive: true });
+    }
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+
+    return `Hooks: Stop + PreCompact + SessionEnd (port ${ctx.hookPort})`;
+  },
+
+  diagnose(ctx: SetupContext): DiagnosticResult[] {
+    const results: DiagnosticResult[] = [];
+
+    // Check MCP config — Claude Code reads from both locations, check all
+    const globalPath = join(homedir(), '.mcp.json');
+    const projectPath = join(ctx.cwd, '.claude', 'mcp.json');
+    const candidates = [projectPath, globalPath];
+
+    let foundConfig = false;
+    for (const mcpJsonPath of candidates) {
+      if (!existsSync(mcpJsonPath)) continue;
+      try {
+        const config = JSON.parse(readFileSync(mcpJsonPath, 'utf-8'));
+        if (config.mcpServers?.['agent-working-memory']) {
+          results.push({ check: 'MCP config', status: 'ok', message: `AWM registered in ${mcpJsonPath}` });
+          foundConfig = true;
+          break;
+        }
+      } catch { /* not valid JSON, skip */ }
+    }
+    if (!foundConfig) {
+      results.push({
+        check: 'MCP config',
+        status: 'fail',
+        message: 'No AWM MCP config found',
+        fix: `Run: awm setup claude-code${ctx.isGlobal ? ' --global' : ''}`,
+      });
+    }
+
+    // Check MCP entrypoint
+    if (ctx.hasDist) {
+      results.push({ check: 'MCP entrypoint', status: 'ok', message: `dist/mcp.js exists` });
+    } else {
+      results.push({
+        check: 'MCP entrypoint',
+        status: 'warn',
+        message: 'dist/mcp.js not found — using dev mode (npx tsx)',
+        fix: 'Run: npm run build',
+      });
+    }
+
+    // Check database
+    if (existsSync(ctx.dbPath)) {
+      results.push({ check: 'Database', status: 'ok', message: ctx.dbPath });
+    } else {
+      results.push({ check: 'Database', status: 'warn', message: `${ctx.dbPath} not found (will be created on first use)` });
+    }
+
+    // Check CLAUDE.md
+    const claudeMdPath = ctx.isGlobal
+      ? join(homedir(), '.claude', 'CLAUDE.md')
+      : join(ctx.cwd, 'CLAUDE.md');
+    if (existsSync(claudeMdPath)) {
+      const content = readFileSync(claudeMdPath, 'utf-8');
+      if (content.includes('## Memory (AWM)')) {
+        results.push({ check: 'Instructions', status: 'ok', message: `CLAUDE.md has AWM section` });
+      } else {
+        results.push({
+          check: 'Instructions',
+          status: 'warn',
+          message: `CLAUDE.md exists but missing AWM section`,
+          fix: `Run: awm setup claude-code${ctx.isGlobal ? ' --global' : ''}`,
+        });
+      }
+    } else {
+      results.push({ check: 'Instructions', status: 'warn', message: `CLAUDE.md not found` });
+    }
+
+    // Check hooks
+    const settingsPath = join(homedir(), '.claude', 'settings.json');
+    if (existsSync(settingsPath)) {
+      try {
+        const settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+        const hasHooks = settings.hooks?.PreCompact && settings.hooks?.SessionEnd;
+        if (hasHooks) {
+          results.push({ check: 'Hooks', status: 'ok', message: 'PreCompact + SessionEnd configured' });
+        } else {
+          results.push({ check: 'Hooks', status: 'warn', message: 'Hooks partially configured' });
+        }
+      } catch {
+        results.push({ check: 'Hooks', status: 'warn', message: 'settings.json is not valid JSON' });
+      }
+    } else {
+      results.push({ check: 'Hooks', status: 'warn', message: 'No hooks configured (auto-checkpoint disabled)' });
+    }
+
+    return results;
+  },
+};
+
+export default adapter;

package/src/adapters/codex.ts

@@ -0,0 +1,262 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Codex CLI adapter — writes TOML config, AGENTS.md instructions.
+ *
+ * Codex stores MCP config in ~/.codex/config.toml (global only).
+ * Uses snake_case [mcp_servers.name] sections.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+import type { CLIAdapter, SetupContext, DiagnosticResult } from './types.js';
+import { resolveMcpCommand, homedir, AWM_INSTRUCTION_CONTENT } from './common.js';
+
+// ─── Minimal TOML read/write ──────────────────────────
+// Only handles the flat structure Codex uses: [section.name] with key = "value" or key = ["array"]
+
+interface TomlSection {
+  [key: string]: string | string[];
+}
+
+interface TomlDoc {
+  /** Sections: key is the full dotted section name */
+  sections: Map<string, TomlSection>;
+  /** Lines before the first section (top-level keys, comments) */
+  preamble: string[];
+}
+
+function parseTOML(content: string): TomlDoc {
+  const doc: TomlDoc = { sections: new Map(), preamble: [] };
+  let currentSection = '';
+  const lines = content.split('\n');
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Section header
+    const sectionMatch = trimmed.match(/^\[([^\]]+)\]$/);
+    if (sectionMatch) {
+      currentSection = sectionMatch[1];
+      if (!doc.sections.has(currentSection)) {
+        doc.sections.set(currentSection, {});
+      }
+      continue;
+    }
+
+    // Skip comments and empty lines
+    if (!trimmed || trimmed.startsWith('#')) {
+      if (!currentSection) doc.preamble.push(line);
+      continue;
+    }
+
+    // Key = value
+    const eqIdx = trimmed.indexOf('=');
+    if (eqIdx === -1) {
+      if (!currentSection) doc.preamble.push(line);
+      continue;
+    }
+
+    const key = trimmed.slice(0, eqIdx).trim();
+    const rawVal = trimmed.slice(eqIdx + 1).trim();
+
+    if (!currentSection) {
+      if (!doc.sections.has('')) doc.sections.set('', {});
+      doc.sections.get('')![key] = parseTomlValue(rawVal);
+      continue;
+    }
+
+    if (!doc.sections.has(currentSection)) {
+      doc.sections.set(currentSection, {});
+    }
+    doc.sections.get(currentSection)![key] = parseTomlValue(rawVal);
+  }
+
+  return doc;
+}
+
+function parseTomlValue(raw: string): string | string[] {
+  // Array: ["a", "b"]
+  if (raw.startsWith('[')) {
+    const inner = raw.slice(1, raw.lastIndexOf(']'));
+    return inner.split(',')
+      .map(s => s.trim().replace(/^["']|["']$/g, ''))
+      .filter(s => s.length > 0);
+  }
+  // Quoted string
+  return raw.replace(/^["']|["']$/g, '');
+}
+
+function serializeTOML(doc: TomlDoc): string {
+  const lines: string[] = [];
+
+  // Preamble (top-level content before any section)
+  if (doc.preamble.length > 0) {
+    lines.push(...doc.preamble);
+    if (lines.length > 0 && lines[lines.length - 1].trim() !== '') {
+      lines.push('');
+    }
+  }
+
+  for (const [section, values] of doc.sections) {
+    if (section === '') continue; // already in preamble
+    lines.push(`[${section}]`);
+    for (const [key, val] of Object.entries(values)) {
+      if (Array.isArray(val)) {
+        const items = val.map(v => `"${v}"`).join(', ');
+        lines.push(`${key} = [${items}]`);
+      } else {
+        lines.push(`${key} = "${val}"`);
+      }
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+// ─── Adapter ──────────────────────────────────────────
+
+const adapter: CLIAdapter = {
+  id: 'codex',
+  name: 'Codex',
+  supportsProjectScope: false,
+  supportsGlobalScope: true,
+
+  writeMcpConfig(ctx: SetupContext): string {
+    if (!ctx.isGlobal) {
+      console.log('  Note: Codex only supports global MCP config. Using --global automatically.');
+    }
+
+    const configPath = join(homedir(), '.codex', 'config.toml');
+    const mcpCmd = resolveMcpCommand(ctx);
+
+    // Read existing config or start fresh
+    let doc: TomlDoc;
+    if (existsSync(configPath)) {
+      doc = parseTOML(readFileSync(configPath, 'utf-8'));
+    } else {
+      doc = { sections: new Map(), preamble: [] };
+      mkdirSync(dirname(configPath), { recursive: true });
+    }
+
+    // Write the MCP server section
+    const sectionName = 'mcp_servers.agent-working-memory';
+    doc.sections.set(sectionName, {
+      command: mcpCmd.command,
+      args: mcpCmd.args,
+    });
+
+    // Write env vars in a sub-section
+    const envSection = `${sectionName}.env`;
+    const envEntries: TomlSection = {};
+    for (const [key, val] of Object.entries(ctx.envVars)) {
+      envEntries[key] = val;
+    }
+    doc.sections.set(envSection, envEntries);
+
+    writeFileSync(configPath, serializeTOML(doc));
+    return `MCP config: ${configPath}`;
+  },
+
+  writeInstructions(ctx: SetupContext, skip: boolean): string {
+    const agentsMdPath = join(ctx.cwd, 'AGENTS.md');
+
+    if (skip) return 'AGENTS.md: skipped (--no-instructions)';
+
+    if (existsSync(agentsMdPath)) {
+      const content = readFileSync(agentsMdPath, 'utf-8');
+      if (content.includes('## Memory (AWM)')) {
+        return 'AGENTS.md: already has AWM section (skipped)';
+      }
+      writeFileSync(agentsMdPath, content.trimEnd() + '\n\n' + AWM_INSTRUCTION_CONTENT);
+      return 'AGENTS.md: appended AWM workflow section';
+    }
+
+    const title = `# ${basename(ctx.cwd)} — Agent Instructions`;
+    writeFileSync(agentsMdPath, `${title}\n\n${AWM_INSTRUCTION_CONTENT}`);
+    return 'AGENTS.md: created with AWM workflow section';
+  },
+
+  writeHooks(_ctx: SetupContext, _skip: boolean): string {
+    return 'Hooks: not supported by Codex (auto-checkpoint unavailable)';
+  },
+
+  diagnose(ctx: SetupContext): DiagnosticResult[] {
+    const results: DiagnosticResult[] = [];
+
+    // Check TOML config
+    const configPath = join(homedir(), '.codex', 'config.toml');
+    if (!existsSync(configPath)) {
+      results.push({
+        check: 'MCP config',
+        status: 'fail',
+        message: `${configPath} not found`,
+        fix: 'Run: awm setup codex',
+      });
+    } else {
+      try {
+        const doc = parseTOML(readFileSync(configPath, 'utf-8'));
+        if (doc.sections.has('mcp_servers.agent-working-memory')) {
+          results.push({ check: 'MCP config', status: 'ok', message: `AWM registered in ${configPath}` });
+
+          // Verify the command points to a real file
+          const section = doc.sections.get('mcp_servers.agent-working-memory')!;
+          const args = section.args;
+          if (Array.isArray(args) && args.length > 0) {
+            const entrypoint = args[args.length - 1];
+            if (existsSync(entrypoint)) {
+              results.push({ check: 'MCP entrypoint', status: 'ok', message: entrypoint });
+            } else {
+              results.push({
+                check: 'MCP entrypoint',
+                status: 'fail',
+                message: `Configured entrypoint not found: ${entrypoint}`,
+                fix: 'Run: npm run build (in AWM package) then awm setup codex',
+              });
+            }
+          }
+        } else {
+          results.push({
+            check: 'MCP config',
+            status: 'fail',
+            message: 'config.toml exists but missing agent-working-memory section',
+            fix: 'Run: awm setup codex',
+          });
+        }
+      } catch {
+        results.push({ check: 'MCP config', status: 'fail', message: `${configPath} could not be parsed` });
+      }
+    }
+
+    // Check database
+    if (existsSync(ctx.dbPath)) {
+      results.push({ check: 'Database', status: 'ok', message: ctx.dbPath });
+    } else {
+      results.push({ check: 'Database', status: 'warn', message: `${ctx.dbPath} not found (will be created on first use)` });
+    }
+
+    // Check AGENTS.md
+    const agentsMdPath = join(ctx.cwd, 'AGENTS.md');
+    if (existsSync(agentsMdPath)) {
+      const content = readFileSync(agentsMdPath, 'utf-8');
+      if (content.includes('## Memory (AWM)')) {
+        results.push({ check: 'Instructions', status: 'ok', message: 'AGENTS.md has AWM section' });
+      } else {
+        results.push({
+          check: 'Instructions',
+          status: 'warn',
+          message: 'AGENTS.md exists but missing AWM section',
+          fix: 'Run: awm setup codex',
+        });
+      }
+    } else {
+      results.push({ check: 'Instructions', status: 'warn', message: 'AGENTS.md not found' });
+    }
+
+    return results;
+  },
+};
+
+export default adapter;

package/src/adapters/common.ts

@@ -0,0 +1,172 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Shared utilities for CLI adapters.
+ *
+ * Extracted from the original setup() in cli.ts — path resolution, secrets,
+ * environment variables, MCP command building, and the AWM instruction snippet.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { resolve, join, dirname, basename } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { homedir as osHomedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import type { SetupContext } from './types.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/** Resolve the AWM package root (where src/ and dist/ live). */
+export function resolvePackageRoot(): string {
+  // __dirname is src/adapters/ at dev time, dist/adapters/ at build time
+  return resolve(__dirname, '..', '..');
+}
+
+/** Resolve the database path — default to <packageRoot>/data/memory.db. */
+export function resolveDbPath(packageRoot: string, explicit?: string | null): string {
+  const dbPath = explicit ?? join(packageRoot, 'data', 'memory.db');
+  const dbDir = dirname(dbPath);
+  if (!existsSync(dbDir)) {
+    mkdirSync(dbDir, { recursive: true });
+  }
+  return dbPath;
+}
+
+/** Read or generate the hook secret token. */
+export function resolveHookSecret(dbPath: string): string {
+  const secretPath = join(dirname(dbPath), '.awm-hook-secret');
+  if (existsSync(secretPath)) {
+    const existing = readFileSync(secretPath, 'utf-8').trim();
+    if (existing) return existing;
+  }
+  const secret = randomBytes(32).toString('hex');
+  mkdirSync(dirname(secretPath), { recursive: true });
+  writeFileSync(secretPath, secret + '\n');
+  return secret;
+}
+
+/** Build environment variables for the MCP server process. */
+export function buildEnvVars(
+  dbPath: string,
+  agentId: string,
+  hookPort: string,
+  hookSecret: string,
+  isWindows: boolean,
+): Record<string, string> {
+  return {
+    AWM_DB_PATH: isWindows ? dbPath.replace(/\\/g, '/') : dbPath,
+    AWM_AGENT_ID: agentId,
+    AWM_HOOK_PORT: hookPort,
+    AWM_HOOK_SECRET: hookSecret,
+  };
+}
+
+/**
+ * Resolve the MCP server command + args.
+ *
+ * Prefers absolute path to dist/mcp.js (works from any cwd).
+ * Falls back to npx tsx src/mcp.ts for dev mode.
+ */
+export function resolveMcpCommand(ctx: SetupContext): {
+  command: string;
+  args: string[];
+} {
+  if (ctx.hasDist) {
+    return {
+      command: 'node',
+      args: [ctx.mcpDist.replace(/\\/g, '/')],
+    };
+  }
+  // Dev fallback
+  if (ctx.isWindows) {
+    return {
+      command: 'cmd',
+      args: ['/c', 'npx', 'tsx', ctx.mcpScript.replace(/\\/g, '/')],
+    };
+  }
+  return {
+    command: 'npx',
+    args: ['tsx', ctx.mcpScript],
+  };
+}
+
+/** Build a full SetupContext from parsed CLI flags. */
+export function buildSetupContext(opts: {
+  agentId?: string;
+  dbPath?: string | null;
+  isGlobal: boolean;
+  hookPort: string;
+}): SetupContext {
+  const cwd = process.cwd();
+  const projectName = basename(cwd).toLowerCase().replace(/[^a-z0-9-]/g, '-');
+  const packageRoot = resolvePackageRoot();
+  const mcpScript = join(packageRoot, 'src', 'mcp.ts');
+  const mcpDist = join(packageRoot, 'dist', 'mcp.js');
+  const hasDist = existsSync(mcpDist);
+  const isWindows = process.platform === 'win32';
+
+  const agentId = opts.agentId ?? (opts.isGlobal ? 'claude' : projectName);
+  const dbPath = resolveDbPath(packageRoot, opts.dbPath);
+  const hookSecret = resolveHookSecret(dbPath);
+  const envVars = buildEnvVars(dbPath, agentId, opts.hookPort, hookSecret, isWindows);
+
+  return {
+    cwd,
+    projectName,
+    agentId,
+    dbPath,
+    packageRoot,
+    mcpDist,
+    mcpScript,
+    hasDist,
+    hookSecret,
+    hookPort: opts.hookPort,
+    isGlobal: opts.isGlobal,
+    isWindows,
+    envVars,
+  };
+}
+
+/** Home directory. */
+export function homedir(): string {
+  return osHomedir();
+}
+
+// ─── Instruction content ────────────────────────────────
+
+/**
+ * Core AWM instruction snippet — shared across all adapters.
+ * Each adapter wraps this in the appropriate file format.
+ */
+export const AWM_INSTRUCTION_CONTENT = `
+## Memory (AWM)
+You have persistent memory via the agent-working-memory MCP server.
+
+### Lifecycle (always do these)
+- Session start: call memory_restore to recover previous context
+- Starting a task: call memory_task_begin (checkpoints + recalls relevant memories)
+- Finishing a task: call memory_task_end with a summary
+- Auto-checkpoint: hooks handle compaction, session end, and 15-min timer (no action needed)
+
+### Write memory when:
+- A project decision is made or changed
+- A root cause is discovered after debugging
+- A reusable implementation pattern is established
+- A user preference, constraint, or requirement is clarified
+- A prior assumption is found to be wrong
+- A significant piece of work is completed
+
+### Recall memory when:
+- Starting work on a new task or subsystem
+- Re-entering code you haven't touched recently
+- After a failed attempt — check if there's prior knowledge
+- Before refactoring or making architectural changes
+- When a topic comes up that you might have prior context on
+
+### Also:
+- After using a recalled memory: call memory_feedback (useful/not-useful)
+- To correct wrong info: call memory_retract or memory_supersede
+- To track work items: memory_task_add, memory_task_update, memory_task_list, memory_task_next
+`.trimStart();