agent-working-memory 0.6.0 → 0.7.0

package/src/adapters/cursor.ts

@@ -0,0 +1,150 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Cursor adapter — writes .cursor/mcp.json and .cursorrules.
+ *
+ * Cursor uses the same MCP config format as Claude Code (JSON with mcpServers).
+ * Instructions go in .cursorrules (project) or ~/.cursor/rules (global).
+ */
+
+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: 'cursor',
+  name: 'Cursor',
+  supportsProjectScope: true,
+  supportsGlobalScope: true,
+
+  writeMcpConfig(ctx: SetupContext): string {
+    const mcpCmd = resolveMcpCommand(ctx);
+    const mcpConfig = { ...mcpCmd, env: ctx.envVars };
+
+    const mcpJsonPath = ctx.isGlobal
+      ? join(homedir(), '.cursor', 'mcp.json')
+      : join(ctx.cwd, '.cursor', 'mcp.json');
+
+    const mcpDir = dirname(mcpJsonPath);
+    if (!existsSync(mcpDir)) {
+      mkdirSync(mcpDir, { recursive: true });
+    }
+
+    let existing: any = { mcpServers: {} };
+    if (existsSync(mcpJsonPath)) {
+      try {
+        existing = JSON.parse(readFileSync(mcpJsonPath, 'utf-8'));
+        if (!existing.mcpServers) existing.mcpServers = {};
+      } catch {
+        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 rulesPath = ctx.isGlobal
+      ? join(homedir(), '.cursor', 'rules')
+      : join(ctx.cwd, '.cursorrules');
+
+    if (skip) return '.cursorrules: skipped (--no-instructions)';
+
+    const dir = dirname(rulesPath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+
+    if (existsSync(rulesPath)) {
+      const content = readFileSync(rulesPath, 'utf-8');
+      if (content.includes('## Memory (AWM)')) {
+        return '.cursorrules: already has AWM section (skipped)';
+      }
+      writeFileSync(rulesPath, content.trimEnd() + '\n\n' + AWM_INSTRUCTION_CONTENT);
+      return '.cursorrules: appended AWM workflow section';
+    }
+
+    writeFileSync(rulesPath, AWM_INSTRUCTION_CONTENT);
+    return '.cursorrules: created with AWM workflow section';
+  },
+
+  writeHooks(_ctx: SetupContext, _skip: boolean): string {
+    return 'Hooks: not supported by Cursor (auto-checkpoint unavailable)';
+  },
+
+  diagnose(ctx: SetupContext): DiagnosticResult[] {
+    const results: DiagnosticResult[] = [];
+
+    // Check MCP config
+    const mcpJsonPath = ctx.isGlobal
+      ? join(homedir(), '.cursor', 'mcp.json')
+      : join(ctx.cwd, '.cursor', 'mcp.json');
+
+    if (!existsSync(mcpJsonPath)) {
+      results.push({
+        check: 'MCP config',
+        status: 'fail',
+        message: `${mcpJsonPath} not found`,
+        fix: `Run: awm setup cursor${ctx.isGlobal ? ' --global' : ''}`,
+      });
+    } else {
+      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}` });
+        } else {
+          results.push({
+            check: 'MCP config',
+            status: 'fail',
+            message: `${mcpJsonPath} exists but missing agent-working-memory entry`,
+            fix: `Run: awm setup cursor${ctx.isGlobal ? ' --global' : ''}`,
+          });
+        }
+      } catch {
+        results.push({ check: 'MCP config', status: 'fail', message: `${mcpJsonPath} is not valid JSON` });
+      }
+    }
+
+    // Check 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',
+        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` });
+    }
+
+    // Check instructions
+    const rulesPath = ctx.isGlobal
+      ? join(homedir(), '.cursor', 'rules')
+      : join(ctx.cwd, '.cursorrules');
+    if (existsSync(rulesPath)) {
+      const content = readFileSync(rulesPath, 'utf-8');
+      if (content.includes('## Memory (AWM)')) {
+        results.push({ check: 'Instructions', status: 'ok', message: '.cursorrules has AWM section' });
+      } else {
+        results.push({ check: 'Instructions', status: 'warn', message: '.cursorrules exists but missing AWM section' });
+      }
+    } else {
+      results.push({ check: 'Instructions', status: 'warn', message: '.cursorrules not found' });
+    }
+
+    return results;
+  },
+};
+
+export default adapter;

package/src/adapters/http.ts

@@ -0,0 +1,100 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * HTTP adapter — generic fallback for any tool that can make REST calls.
+ *
+ * Doesn't write MCP config. Prints connection instructions for the HTTP API.
+ * Optionally writes an instruction file.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import type { CLIAdapter, SetupContext, DiagnosticResult } from './types.js';
+import { AWM_INSTRUCTION_CONTENT } from './common.js';
+
+const HTTP_ADDENDUM = `
+### HTTP API (for tools without MCP support)
+
+If your tool doesn't support MCP, use the HTTP API directly:
+
+**Base URL:** \`http://127.0.0.1:8400\`
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | /memory/restore/:agentId | Restore context from prior sessions |
+| POST | /memory/activate | Cognitive recall (use \`context\` field) |
+| POST | /memory/write | Write a memory |
+| POST | /memory/feedback | Report if memory was useful |
+| POST | /memory/retract | Invalidate a wrong memory |
+| POST | /memory/checkpoint | Save execution state |
+| POST | /task/create | Create a task |
+| POST | /task/update | Update task status |
+| GET | /task/list/:agentId | List tasks |
+| GET | /task/next/:agentId | Get next actionable task |
+| GET | /health | Health check |
+
+Start the server with: \`awm serve\`
+`;
+
+const adapter: CLIAdapter = {
+  id: 'http',
+  name: 'HTTP (generic)',
+  supportsProjectScope: true,
+  supportsGlobalScope: false,
+
+  writeMcpConfig(ctx: SetupContext): string {
+    const port = process.env.AWM_PORT ?? '8400';
+    return `MCP config: N/A (HTTP mode)\n  Start server: awm serve --port ${port}\n  Base URL: http://127.0.0.1:${port}`;
+  },
+
+  writeInstructions(ctx: SetupContext, skip: boolean): string {
+    const instrPath = join(ctx.cwd, 'AWM-INSTRUCTIONS.md');
+
+    if (skip) return 'AWM-INSTRUCTIONS.md: skipped (--no-instructions)';
+
+    if (existsSync(instrPath)) {
+      const content = readFileSync(instrPath, 'utf-8');
+      if (content.includes('## Memory (AWM)')) {
+        return 'AWM-INSTRUCTIONS.md: already has AWM section (skipped)';
+      }
+      writeFileSync(instrPath, content.trimEnd() + '\n\n' + AWM_INSTRUCTION_CONTENT + HTTP_ADDENDUM);
+      return 'AWM-INSTRUCTIONS.md: appended AWM + HTTP API section';
+    }
+
+    writeFileSync(instrPath, `# Agent Working Memory\n\n${AWM_INSTRUCTION_CONTENT}${HTTP_ADDENDUM}`);
+    return 'AWM-INSTRUCTIONS.md: created with AWM + HTTP API section';
+  },
+
+  writeHooks(_ctx: SetupContext, _skip: boolean): string {
+    return 'Hooks: N/A (HTTP mode)';
+  },
+
+  diagnose(ctx: SetupContext): DiagnosticResult[] {
+    const results: DiagnosticResult[] = [];
+
+    // 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` });
+    }
+
+    // Check if HTTP server is reachable
+    // (can't do async in diagnose, so just check if the entrypoint exists)
+    if (ctx.hasDist) {
+      results.push({ check: 'Server entrypoint', status: 'ok', message: 'dist/index.js exists' });
+    } else {
+      results.push({
+        check: 'Server entrypoint',
+        status: 'warn',
+        message: 'dist/index.js not found — use: npx tsx src/index.ts',
+        fix: 'Run: npm run build',
+      });
+    }
+
+    return results;
+  },
+};
+
+export default adapter;

package/src/adapters/index.ts

@@ -0,0 +1,31 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Adapter registry — lazy-loads adapters by ID.
+ */
+
+import type { CLIAdapter } from './types.js';
+
+const adapters = new Map<string, () => Promise<CLIAdapter>>();
+
+adapters.set('claude-code', () => import('./claude-code.js').then(m => m.default));
+adapters.set('codex', () => import('./codex.js').then(m => m.default));
+adapters.set('cursor', () => import('./cursor.js').then(m => m.default));
+adapters.set('http', () => import('./http.js').then(m => m.default));
+
+// Aliases
+adapters.set('claude', () => import('./claude-code.js').then(m => m.default));
+
+export function listAdapters(): string[] {
+  return ['claude-code', 'codex', 'cursor', 'http'];
+}
+
+export async function getAdapter(id: string): Promise<CLIAdapter> {
+  const factory = adapters.get(id);
+  if (!factory) {
+    const valid = listAdapters().join(', ');
+    throw new Error(`Unknown target: "${id}". Valid targets: ${valid}`);
+  }
+  return factory();
+}

package/src/adapters/types.ts

@@ -0,0 +1,75 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Shared types for CLI adapters.
+ *
+ * Each AI CLI tool (Claude Code, Codex, Cursor, etc.) gets its own adapter
+ * that implements CLIAdapter. The setup orchestrator in cli.ts delegates to
+ * the selected adapter.
+ */
+
+export interface SetupContext {
+  /** Current working directory */
+  cwd: string;
+  /** Lowercase project name derived from cwd */
+  projectName: string;
+  /** Agent identifier for AWM */
+  agentId: string;
+  /** Absolute path to the SQLite database */
+  dbPath: string;
+  /** Absolute path to the AWM package root */
+  packageRoot: string;
+  /** Absolute path to dist/mcp.js (compiled entrypoint) */
+  mcpDist: string;
+  /** Absolute path to src/mcp.ts (dev entrypoint) */
+  mcpScript: string;
+  /** Whether dist/mcp.js exists (determines command strategy) */
+  hasDist: boolean;
+  /** Hook sidecar secret token */
+  hookSecret: string;
+  /** Hook sidecar port */
+  hookPort: string;
+  /** Whether to use global scope */
+  isGlobal: boolean;
+  /** Windows platform */
+  isWindows: boolean;
+  /** Pre-built environment variables for the MCP server */
+  envVars: Record<string, string>;
+}
+
+export interface SetupResult {
+  configAction: string;
+  instructionsAction: string;
+  hooksAction: string;
+}
+
+export interface DiagnosticResult {
+  check: string;
+  status: 'ok' | 'warn' | 'fail';
+  message: string;
+  fix?: string;
+}
+
+export interface CLIAdapter {
+  /** Short identifier: 'claude-code', 'codex', 'cursor', 'http' */
+  id: string;
+  /** Display name for output */
+  name: string;
+  /** Does this adapter support project-level scope? */
+  supportsProjectScope: boolean;
+  /** Does this adapter support global scope? */
+  supportsGlobalScope: boolean;
+
+  /** Write the MCP server config for this CLI. Returns action summary. */
+  writeMcpConfig(ctx: SetupContext): string;
+
+  /** Write/append instruction content. Returns action summary. */
+  writeInstructions(ctx: SetupContext, skip: boolean): string;
+
+  /** Configure hooks (if supported). Returns action summary. */
+  writeHooks(ctx: SetupContext, skip: boolean): string;
+
+  /** Validate that the setup is healthy. */
+  diagnose(ctx: SetupContext): DiagnosticResult[];
+}

package/src/api/routes.ts

@@ -170,6 +170,7 @@ export function registerRoutes(app: FastifyInstance, deps: MemoryDeps): void {
       useReranker?: boolean;
       useExpansion?: boolean;
       abstentionThreshold?: number;
+      workspace?: string;
     };
 
     const results = await activationEngine.activate({
@@ -181,6 +182,7 @@ export function registerRoutes(app: FastifyInstance, deps: MemoryDeps): void {
       useReranker: body.useReranker,
       useExpansion: body.useExpansion,
       abstentionThreshold: body.abstentionThreshold,
+      workspace: body.workspace,
     });
 
     // Auto-checkpoint: track recall for consolidation scheduling