agent-working-memory 0.14.6 → 0.15.5

package/src/cli.ts

@@ -47,6 +47,7 @@ AgentWorkingMemory — Cognitive memory for AI agents
 
 Usage:
   awm setup [target] [options]                      Configure AWM for an AI CLI
+  awm plugin                                        Install as a Claude Code plugin (local, no GitHub)
   awm doctor [target|--all]                         Validate AWM integrations
   awm mcp                                           Start MCP server (stdio)
   awm serve [--port <port>]                         Start HTTP API server
@@ -145,7 +146,8 @@ async function setup() {
   // Build context. A previous install's values survive unless a flag overrides them
   // (0.14.6) — an upgrade must never repoint the database or rename the agent.
   const existingEnv = adapter.readExistingEnv?.(isGlobal, process.cwd()) ?? null;
-  const ctx = buildSetupContext({ agentId, dbPath, isGlobal, hookPort, hookPortRange, installPrime, existingEnv });
+  // `awm setup claude-code` -> client=claude-code, cursor -> client=cursor, and so on.
+  const ctx = buildSetupContext({ agentId, dbPath, isGlobal, hookPort, hookPortRange, installPrime, existingEnv, client: target });
 
   // Run adapter
   const configAction = adapter.writeMcpConfig(ctx);
@@ -172,6 +174,58 @@ Next steps:
 `.trim());
 }
 
+// ─── PLUGIN ──────────────────────────────────────
+
+/**
+ * Print the two lines that install AWM as a Claude Code plugin FROM THIS INSTALL.
+ *
+ * Most users are on Windows and will never clone the repository, so
+ * `/plugin marketplace add CompleteIdeas/agent-working-memory` — which needs GitHub — is the
+ * wrong default for them. npm has already put a complete marketplace on their disk; they
+ * just have no way to know where it is. This tells them, with the real resolved path.
+ */
+function pluginInfo(): void {
+  // dist/cli.js -> package root
+  const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+  const marketplace = join(pkgRoot, '.claude-plugin', 'marketplace.json');
+
+  if (!existsSync(marketplace)) {
+    console.log(`
+AWM ${VERSION} — plugin not found in this install
+
+  Looked for: ${marketplace}
+
+  This happens when AWM is running from a source checkout that has not been built,
+  or from a package published before the plugin was bundled (< 0.15.3).
+
+  From a checkout:  npm run build && npm run build:plugin
+  Otherwise:        npm install -g agent-working-memory@latest
+`.trimStart());
+    return;
+  }
+
+  console.log(`
+AWM ${VERSION} — install as a Claude Code plugin
+
+  Paste these two lines into Claude Code:
+
+    /plugin marketplace add ${pkgRoot}
+    /plugin install awm@agent-working-memory
+
+  Then restart Claude Code. You get 19 memory tools, the session hooks, and the
+  usage guidance as a skill.
+
+  No GitHub access needed — the marketplace is this npm install, already on disk.
+
+  The store defaults to the same file \`awm setup --global\` uses, so a plugin
+  install and a CLI install share one memory rather than quietly keeping two.
+
+  Check it worked:  awm doctor claude-code
+  More:             https://github.com/CompleteIdeas/agent-working-memory/blob/master/docs/plugin.md
+`.trimStart());
+}
+
+
 // ─── DOCTOR ──────────────────────────────────────
 
 async function doctor() {
@@ -803,6 +857,9 @@ switch (command) {
   case 'setup':
     await setup();
     break;
+    case 'plugin':
+      pluginInfo();
+      break;
   case 'doctor':
     await doctor();
     break;

package/src/core/write-pipeline.ts

@@ -491,6 +491,24 @@ async function createNewEngram(
 
   const tags = [...(input.tags ?? [])];
   if (isLowSalience && !tags.includes('low-salience')) tags.push('low-salience');
+
+  // Which CLIENT wrote this: `client=claude-code`, `client=claude-desktop`, `client=cursor`.
+  //
+  // Deliberately not called `surface`: memory_whoami already reports a `surface` field
+  // meaning the TRANSPORT (mcp | http), and one word for two concepts is how you lose an
+  // hour six months from now. Transport is how the request arrived; client is which
+  // application it arrived from.
+  // AWM_CLIENT is set by the thing that launches the server (the Claude Code plugin, the
+  // Desktop extension, `awm setup`), never by the caller, so it records where a memory came
+  // from rather than what the writer claims.
+  //
+  // Captured by default rather than behind a flag, because provenance is one-way: a tag can
+  // be ignored or stripped later, but the origin of a memory written without one is gone for
+  // good. An explicit `client=` in the caller's tags always wins.
+  const client = (process.env.AWM_CLIENT ?? '').trim();
+  if (client && !tags.some(t => t.toLowerCase().startsWith('client='))) {
+    tags.push(`client=${client}`);
+  }
 
   // Auto-tag meta-tags (default-OFF, AWM_AUTOTAG=1). extractMetaTags emits
   // `entity:<ProperNoun>` and `cat:<category>` tags from concept+content. These

package/src/plugin/awm-mcp-launcher.cjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+//
+// Entry point for the Claude Code plugin's MCP server.
+//
+// This is a REAL source file, not a string inside the generator, because it is real code:
+// it gets syntax-checked, linted and tested like everything else. `npm run build:plugin`
+// copies it to plugin/bin/ and substitutes __AWM_VERSION__.
+//
+// Two jobs a bare `mcpServers` entry in plugin.json cannot do:
+//
+//   1. Default the store to ~/.awm/memory.db — the SAME file `awm setup --global` writes.
+//      Without this the plugin opens its own empty database and "your memory follows you
+//      between Claude Code, Desktop and Cowork" is simply false.
+//
+//   2. Find the server. A plugin does not know whether the package is installed globally,
+//      sits in a local node_modules, or is a checkout on disk.
+//
+// Fails loudly on stderr. A silent exit here looks like "the memory tools just aren't there",
+// which is the least debuggable failure this could have.
+'use strict';
+
+const { join, resolve, sep } = require('node:path');
+const { homedir } = require('node:os');
+const { existsSync } = require('node:fs');
+const { pathToFileURL } = require('node:url');
+const { spawn, execFileSync } = require('node:child_process');
+
+const NL = '\n';
+
+// Claude Desktop substitutes user_config values into env, and a field the user cleared
+// arrives as an empty string rather than being absent. An empty AWM_AGENT_ID would override
+// the server's directory-derived default with nothing, so drop empties before anything reads
+// them and let the normal defaults apply.
+for (const k of ['AWM_DB_PATH', 'AWM_AGENT_ID', 'AWM_HOOK_PORT', 'AWM_PACKAGE_ROOT']) {
+  if (process.env[k] !== undefined && String(process.env[k]).trim() === '') delete process.env[k];
+}
+
+// An explicit AWM_DB_PATH always wins, so per-project pools still work.
+if (!process.env.AWM_DB_PATH) {
+  process.env.AWM_DB_PATH = join(homedir(), '.awm', 'memory.db').split(sep).join('/');
+}
+
+const tried = [];
+function candidate(p) {
+  if (!p) return null;
+  tried.push(p);
+  return existsSync(p) ? p : null;
+}
+
+// In priority order. npx is last: on a cold cache it rebuilds better-sqlite3, which takes
+// minutes and is indistinguishable from a hang.
+let found =
+  // 1. An explicit override.
+  candidate(process.env.AWM_PACKAGE_ROOT && join(process.env.AWM_PACKAGE_ROOT, 'dist', 'mcp.js')) ||
+  // 2. The plugin sitting inside an AWM checkout (plugin/bin -> ../../dist).
+  candidate(resolve(__dirname, '..', '..', 'dist', 'mcp.js')) ||
+  // 3. A local dependency of the project being worked on.
+  candidate(join(process.cwd(), 'node_modules', 'agent-working-memory', 'dist', 'mcp.js'));
+
+// 4. A global install. require.resolve does not search global roots, so ask npm once.
+if (!found) {
+  try {
+    const isWin = process.platform === 'win32';
+    const root = execFileSync(isWin ? 'npm.cmd' : 'npm', ['root', '-g'], {
+      encoding: 'utf-8',
+      shell: isWin,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    found = candidate(root && join(root, 'agent-working-memory', 'dist', 'mcp.js'));
+  } catch {
+    /* npm not on PATH — fall through */
+  }
+}
+
+// 5. Anywhere node can resolve it from here.
+if (!found) {
+  try {
+    found = require.resolve('agent-working-memory/dist/mcp.js');
+  } catch {
+    /* not installed where this script can see it */
+  }
+}
+
+if (found) {
+  // dist/ is ESM ("type": "module"), so import() — require() throws ERR_REQUIRE_ESM.
+  import(pathToFileURL(found).href).catch((e) => {
+    process.stderr.write('[awm] failed to load ' + found + ': ' + e.message + NL);
+    process.exit(1);
+  });
+} else {
+  // Last resort, pinned so the tools match the hook scripts shipped beside them.
+  // shell:true on Windows: spawning npx.cmd directly throws EINVAL since Node 18.20/20.12.
+  const isWin = process.platform === 'win32';
+  const child = spawn(
+    isWin ? 'npx.cmd' : 'npx',
+    ['-y', '-p', 'agent-working-memory@__AWM_VERSION__', 'awm', 'mcp'],
+    { stdio: 'inherit', env: process.env, shell: isWin }
+  );
+  child.on('error', (e) => {
+    process.stderr.write('[awm] could not start the MCP server: ' + e.message + NL);
+    process.stderr.write('[awm] looked in:' + NL);
+    for (const t of tried) process.stderr.write('  ' + t + NL);
+    process.stderr.write('[awm] fix: npm install -g agent-working-memory' + NL);
+    process.exit(1);
+  });
+  child.on('exit', (code) => process.exit(code == null ? 0 : code));
+}

package/src/storage/factory.ts

@@ -49,13 +49,25 @@ export type StoreBackend = 'sqlite' | 'pglite' | 'postgres';
 function detectBackendFromDisk(): StoreBackend | null {
   // If AWM_DB_PATH is set, infer from its shape.
   const explicitPath = process.env.AWM_DB_PATH;
-  if (explicitPath && existsSync(explicitPath)) {
-    try {
-      const stat = statSync(explicitPath);
-      if (stat.isDirectory()) return 'pglite'; // PGlite uses a directory
-      if (stat.isFile()) return 'sqlite';      // SQLite is a single file
-    } catch { /* fall through */ }
-  }
+  if (explicitPath) {
+    if (existsSync(explicitPath)) {
+      try {
+        const stat = statSync(explicitPath);
+        if (stat.isDirectory()) return 'pglite'; // PGlite uses a directory
+        if (stat.isFile()) return 'sqlite';      // SQLite is a single file
+      } catch { /* fall through to the default below */ }
+    }
+    // The caller named a path that does not exist yet — a brand-new store. Default it to
+    // SQLite and STOP: falling through to the cwd conventions below would pick the backend
+    // from files that have nothing to do with the path that was asked for.
+    //
+    // Not hypothetical. Running from a checkout containing a `memory-pglite/` directory
+    // made a fresh AWM_DB_PATH=/tmp/new-store.db resolve to PGlite, which is
+    // single-process — so two surfaces pointed at 'the same store' would have had the
+    // second refuse to start. Found by the cross-surface end-to-end test.
+    // PGlite at a new path is still reachable via AWM_STORE_BACKEND=pglite.
+    return 'sqlite';
+  }
 
   // Otherwise look for the conventional defaults in cwd.
   // PGlite directory wins over SQLite file when both exist — assume the