π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
fix(cli): pin @claude-flow/memory exactly and warn in doctor on a stale copy (#3392)
ruv6ff6fded33ad
diff --git a/v3/@claude-flow/cli/__tests__/doctor-memory-version-3392.test.ts b/v3/@claude-flow/cli/__tests__/doctor-memory-version-3392.test.tsnew file mode 100644index 0000000000..1f94229409--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/doctor-memory-version-3392.test.ts@@ -0,0 +1,69 @@+/**+ * #3392: `npx @claude-flow/cli@latest` reuses one npx cache directory across CLI+ * versions, and npm keeps an installed dependency that still satisfies a caret+ * range β so a stale @claude-flow/memory survived a CLI upgrade with no error.+ * The fix is twofold: cli pins memory exactly (so a stale copy can no longer+ * satisfy the spec), and doctor reports when the loaded copy drifts from it.+ */+import { describe, expect, it } from 'vitest';+import { readFileSync } from 'node:fs';+import { fileURLToPath } from 'node:url';+import { evaluateMemoryPackageVersion, checkMemoryPackageVersion } from '../src/commands/doctor.js';++const pkg = JSON.parse(+ readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf-8'),+) as { dependencies?: Record<string, string>; optionalDependencies?: Record<string, string> };++describe('#3392 evaluateMemoryPackageVersion', () => {+ it('passes when the installed version satisfies an exact pin', () => {+ expect(evaluateMemoryPackageVersion('3.0.0-alpha.25', '3.0.0-alpha.25').status).toBe('pass');+ });++ it('fails on a stale copy that a caret range would have accepted', () => {+ const check = evaluateMemoryPackageVersion('3.0.0-alpha.25', '3.0.0-alpha.24');+ expect(check.status).toBe('fail');+ expect(check.message).toContain('3.0.0-alpha.24');+ expect(check.fix).toContain('_npx');+ expect(check.fix).toContain('@claude-flow/[email protected]');+ });++ it('treats prerelease versions inside a prerelease range as satisfying', () => {+ expect(evaluateMemoryPackageVersion('^3.0.0-alpha.23', '3.0.0-alpha.25').status).toBe('pass');+ });++ it('warns, not fails, when the optional package is absent', () => {+ const check = evaluateMemoryPackageVersion('3.0.0-alpha.25', null);+ expect(check.status).toBe('warn');+ expect(check.fix).toContain('--include=optional');+ });++ it('warns when the declared range cannot be read or compared', () => {+ expect(evaluateMemoryPackageVersion(null, '3.0.0-alpha.25').status).toBe('warn');+ expect(evaluateMemoryPackageVersion('not a range', '3.0.0-alpha.25').status).toBe('warn');+ expect(evaluateMemoryPackageVersion('3.0.0-alpha.25', 'garbage').status).toBe('warn');+ });+});++describe('#3392 cli declares an exact @claude-flow/memory pin', () => {+ it.each(['dependencies', 'optionalDependencies'] as const)('%s pins memory to one exact version', (field) => {+ const spec = pkg[field]?.['@claude-flow/memory'];+ expect(spec, `${field} should declare @claude-flow/memory`).toBeDefined();+ // Exact semver: no range operators, so a cached older copy cannot satisfy it.+ expect(spec).toMatch(/^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/);+ });++ it('declares the same pin in both fields (npm lets optionalDependencies win)', () => {+ expect(pkg.optionalDependencies?.['@claude-flow/memory']).toBe(pkg.dependencies?.['@claude-flow/memory']);+ });+});++describe('#3392 checkMemoryPackageVersion (real resolution)', () => {+ it('reports the copy this CLI actually loads against its own pin', async () => {+ const check = await checkMemoryPackageVersion();+ expect(check.name).toBe('@claude-flow/memory version');+ // In a healthy install the loaded copy satisfies the pin; a warn is only+ // acceptable when the optional package is genuinely not installed.+ expect(['pass', 'warn']).toContain(check.status);+ if (check.status === 'pass') expect(check.message).toContain(pkg.dependencies!['@claude-flow/memory']);+ });+});diff --git a/v3/@claude-flow/cli/package.json b/v3/@claude-flow/cli/package.jsonindex b7c53aa7de..fa9dda7298 100644--- a/v3/@claude-flow/cli/package.json+++ b/v3/@claude-flow/cli/package.json@@ -125,11 +125,11 @@"ws": "^8.21.0","yaml": "^2.8.0","zod": "^3.22.0",- "@claude-flow/memory": "^3.0.0-alpha.23"+ "@claude-flow/memory": "3.0.0-alpha.25"},"optionalDependencies": {"@agntcy/slim-bindings": "2.0.0-alpha.5",- "@claude-flow/memory": "^3.0.0-alpha.23",+ "@claude-flow/memory": "3.0.0-alpha.25","@metaharness/darwin": "~0.10.2","@metaharness/flywheel": "~0.1.10","@metaharness/radio": "~0.1.0",diff --git a/v3/@claude-flow/cli/src/commands/doctor.ts b/v3/@claude-flow/cli/src/commands/doctor.tsindex bffc410c9f..24926442ee 100644--- a/v3/@claude-flow/cli/src/commands/doctor.ts+++ b/v3/@claude-flow/cli/src/commands/doctor.ts@@ -15,8 +15,10 @@ import { execSync, exec } from 'child_process';import { promisify } from 'util';import { decodeKey, isEncryptionEnabled } from '../encryption/vault.js';import { isEncryptedBlob } from '../encryption/vault.js';+import * as semver from 'semver';import {resolveMemoryPackageFromProject,+ resolveMemoryPackageFromCli,readMemoryPackageVersion,recordMemoryPackagePath,} from '../init/memory-package-resolver.js';@@ -1040,6 +1042,72 @@ async function checkLearningBridge(): Promise<HealthCheck> {};}+/**+ * #3392: pure verdict for "does the @claude-flow/memory the CLI loads satisfy+ * the range the CLI declares?". `npx @claude-flow/cli@latest` reuses one npx+ * cache directory across CLI versions, and npm keeps an already-installed+ * dependency that still satisfies a caret range, so a stale memory could+ * survive a CLI upgrade with no error. Exported for unit testing.+ */+export function evaluateMemoryPackageVersion(declared: string | null, installed: string | null): HealthCheck {+ const NAME = '@claude-flow/memory version';+ if (!declared) {+ return { name: NAME, status: 'warn', message: 'could not read the @claude-flow/memory range declared by @claude-flow/cli' };+ }+ if (!installed) {+ return {+ name: NAME,+ status: 'warn',+ message: `@claude-flow/memory is not resolvable from the CLI (declared ${declared}) β memory features fall back to degraded paths`,+ fix: `npm install @claude-flow/memory@${declared} --include=optional`,+ };+ }+ if (!semver.validRange(declared) || !semver.valid(installed)) {+ return { name: NAME, status: 'warn', message: `cannot compare installed ${installed} against declared ${declared}` };+ }+ if (semver.satisfies(installed, declared, { includePrerelease: true })) {+ return { name: NAME, status: 'pass', message: `v${installed} satisfies declared ${declared}` };+ }+ return {+ name: NAME,+ status: 'fail',+ message: `installed v${installed} does not satisfy declared ${declared} β a stale cached copy is running, so fixes shipped in a newer @claude-flow/memory are silently absent`,+ fix: `rm -rf "$(npm config get cache)/_npx" && npx @claude-flow/cli@latest doctor # or: npm install @claude-flow/memory@${declared}`,+ };+}++export async function checkMemoryPackageVersion(): Promise<HealthCheck> {+ try {+ // Walk up from this module to the CLI package root (npx cache, global,+ // project-local and monorepo dev all resolve the same way).+ let declared: string | null = null;+ let dir = dirname(fileURLToPath(import.meta.url));+ for (let i = 0; i < 8 && declared === null; i++) {+ const pj = join(dir, 'package.json');+ if (existsSync(pj)) {+ try {+ const pkg = JSON.parse(readFileSync(pj, 'utf-8')) as {+ name?: string;+ dependencies?: Record<string, string>;+ optionalDependencies?: Record<string, string>;+ };+ if (pkg.name === '@claude-flow/cli') {+ declared = pkg.optionalDependencies?.['@claude-flow/memory'] ?? pkg.dependencies?.['@claude-flow/memory'] ?? null;+ break;+ }+ } catch { /* keep walking */ }+ }+ dir = dirname(dir);+ }+ // Resolve exactly as the CLI's own runtime does (its module context),+ // not from process.cwd() β that would report the project's copy instead.+ const distPath = resolveMemoryPackageFromCli();+ return evaluateMemoryPackageVersion(declared, distPath ? readMemoryPackageVersion(distPath) : null);+ } catch (err) {+ return { name: '@claude-flow/memory version', status: 'warn', message: `check failed: ${err instanceof Error ? err.message : String(err)}` };+ }+}+// Check API keysasync function checkApiKeys(): Promise<HealthCheck> {const keys = ['ANTHROPIC_API_KEY', 'CLAUDE_API_KEY', 'OPENAI_API_KEY'];@@ -2439,6 +2507,7 @@ export const doctorCommand: Command = {checkMemoryStructuralIntegrity, // #2737 β bounded, native quick_check on every default runcheckMemoryPersistenceDriver, // #2968/#3321 β read-only native capability probecheckLearningBridge, // #2545 β can the auto-memory hook actually load @claude-flow/memory?+ checkMemoryPackageVersion, // #3392 β loaded @claude-flow/memory must satisfy the CLI's declared rangecheckApiKeys,checkMcpServers,checkMcpSchemaOverhead, // #2726 β fixed tools/list prompt cost@@ -2477,11 +2546,13 @@ export const doctorCommand: Command = {checkMemoryDatabase, // existing: exists + statable (unchanged)checkMemoryIntegrity, // #2677 check 1: sql.js open + PRAGMA integrity_checkcheckMemoryPersistenceDriver, // #2968/#3321: read-only native capability probe+ checkMemoryPackageVersion, // #3392: loaded memory package satisfies the declared rangecheckMemoryContent, // #2677 check 2: memory_entries content coveragecheckMemoryEmbeddingCoverage, // #2677 check 3: vector coverage on populated rowscheckMemoryReflexionCoverage, // #2677 check 6: episodes are retrievablecheckMemoryCritiqueCoverage, // #2677 check 6: feedback carries lessons],+ 'memory-package': checkMemoryPackageVersion, // #3392'learning': checkLearningBridge, // #2545'learning-bridge': checkLearningBridge, // #2545'api': checkApiKeys,diff --git a/v3/pnpm-lock.yaml b/v3/pnpm-lock.yamlindex 95fb976b9d..d63b871b64 100644--- a/v3/pnpm-lock.yaml+++ b/v3/pnpm-lock.yaml@@ -209,8 +209,8 @@ importers:specifier: 2.0.0-alpha.5version: 2.0.0-alpha.5'@claude-flow/memory':- specifier: ^3.0.0-alpha.23- version: 3.0.0-alpha.24(@types/[email protected])([email protected])+ specifier: 3.0.0-alpha.25+ version: 3.0.0-alpha.25(@types/[email protected])([email protected])'@metaharness/darwin':specifier: ~0.10.2version: 0.10.2@@ -936,6 +936,25 @@ packages:- supports-color- zod+ resolution: {integrity: sha512-yjeFlIlUkAE0jBUTx4ocvqWm71CsJEhps8gz0tU1Kl0POelxOsLsEUVQUCQ2E4ZEuQ0xii12K8+3tzK2hvWD3g==}+ cpu: [x64, arm64]+ os: [darwin, linux, win32]+ dependencies:+ '@claude-flow/security': 3.0.0-alpha.12+ agentdb: 3.0.0-alpha.17(@types/[email protected])([email protected])+ sql.js: 1.14.1+ optionalDependencies:+ better-sqlite3: 12.9.0+ transitivePeerDependencies:+ - '@cfworker/json-schema'+ - '@types/node'+ - bare-abort-controller+ - bare-buffer+ - react-native-b4a+ - supports-color+ - zod+/@claude-flow/[email protected]:resolution: {integrity: sha512-/b1V6zXOhFSs+Y8UztyPFHqkNjDKslwpAn9+KJFWHqZMwnnPnBnW0WQHoZAGx+5+rewI619pVT9gIANkyt3luQ==}dependencies: