feat(memory): implement xMemory 4-layer hierarchical integration

- Add L3 Theme layer with ThemeManager (assimilate, split, merge, KNN)
- Add HierarchicalMemoryGraph for 4-level relationship management
- Add AdaptiveSearch with top-down retrieval and token budgeting
- Add FileSystem abstraction for dependency injection testing
- Update CLI with --level theme and --no-expand options (AC7, AC8)
- Add themes/ template directory with index.yaml + embeddings.json

Technical highlights:
- Lazy loading of embeddings for fast startup
- Cosine similarity with centroid-based theme matching
- Configurable thresholds (attach: 0.62, merge: 0.78, expand: 0.75)

Tests: 201 passed (+54 new tests for xMemory modules)
Coverage: theme-manager 92%, hierarchy-graph 99%, adaptive-search 85%

Closes: xMemory Hierarchical Integration tech-spec

Author: Alenryuichi

_bmad-output/implementation-artifacts/tech-spec-xmemory-hierarchical-integration.md

@@ -0,0 +1,12 @@
+# cli - Agent Instructions
+
+<!-- OpenMemory Plus Integration -->
+
+## 🚨 MANDATORY - BEFORE ANY OUTPUT
+
+**Load `_omp/AGENTS.md` NOW and follow all instructions.**
+
+If file not found, report error: "OpenMemory Plus not initialized. Run: npx openmemory-plus install"
+
+---
+*Generated by OpenMemory Plus on 2026-02-28 for: augment*

_bmad-output/planning-artifacts/research/technical-xMemory-integration-research-2026-02-28.md

@@ -48,7 +48,8 @@
     "commander": "^12.0.0",
     "inquirer": "^9.2.0",
     "ora": "^8.0.0",
-    "which": "^4.0.0"
+    "which": "^4.0.0",
+    "yaml": "^2.8.2"
   },
   "devDependencies": {
     "@types/inquirer": "^9.0.7",

cli/AGENTS.md

@@ -1,9 +1,13 @@
 import chalk from 'chalk';
 import ora from 'ora';
+import * as path from 'node:path';
+import { ThemeManager, nodeFs, DEFAULT_THEME_CONFIG } from '../lib/memory/index.js';
 
 interface SearchOptions {
   limit?: number;
   json?: boolean;
+  level?: 'theme' | 'semantic' | 'all';
+  expand?: boolean; // AC8: --no-expand option
 }
 
 interface MemoryResult {
@@ -133,3 +137,74 @@ export async function searchCommand(query: string, options: SearchOptions): Prom
   });
 }
 
+// ============ Theme Search (xMemory L3) ============
+
+export async function searchThemesCommand(query: string, options: SearchOptions): Promise<void> {
+  if (!query || query.trim() === '') {
+    console.log(chalk.red('❌ 请提供搜索关键词'));
+    console.log(chalk.gray('用法: openmemory-plus search <query> --level theme'));
+    return;
+  }
+
+  console.log(chalk.cyan.bold('\n🔍 搜索主题记忆\n'));
+
+  // Generate embedding
+  const spinner = ora('生成语义向量...').start();
+  const embedding = await getEmbedding(query);
+
+  if (!embedding) {
+    spinner.fail('无法生成语义向量');
+    console.log(chalk.yellow('请确保 Ollama 正在运行且 BGE-M3 已安装:'));
+    console.log(chalk.gray('  ollama serve'));
+    console.log(chalk.gray('  ollama pull bge-m3'));
+    return;
+  }
+
+  // Load theme manager
+  spinner.text = '搜索主题...';
+  const storageDir = path.join(process.cwd(), '_omp', 'memory');
+
+  // Check if memory directory exists
+  if (!nodeFs.existsSync(storageDir)) {
+    spinner.fail('记忆目录不存在');
+    console.log(chalk.yellow('请先运行: npx openmemory-plus install'));
+    return;
+  }
+
+  const themeManager = new ThemeManager(storageDir, 'default', DEFAULT_THEME_CONFIG, nodeFs);
+  themeManager.loadThemes();
+
+  const limit = options.limit || 5;
+  const results = themeManager.searchThemes(embedding, limit);
+  spinner.stop();
+
+  if (results.length === 0) {
+    console.log(chalk.yellow('未找到相关主题'));
+    console.log(chalk.gray(`搜索词: "${query}"`));
+    console.log(chalk.gray('提示: 主题会在记忆积累后自动形成'));
+    return;
+  }
+
+  if (options.json) {
+    const jsonResults = results.map(r => ({
+      themeId: r.theme.themeId,
+      summary: r.theme.summary,
+      score: r.score,
+      memberCount: r.theme.memberCount,
+    }));
+    console.log(JSON.stringify(jsonResults, null, 2));
+    return;
+  }
+
+  console.log(chalk.green(`找到 ${results.length} 个相关主题:\n`));
+
+  results.forEach((result, index) => {
+    const { theme, score } = result;
+    const scoreStr = chalk.gray(`(${(score * 100).toFixed(1)}%)`);
+    const memberStr = chalk.blue(`[${theme.memberCount} 条记忆]`);
+
+    console.log(chalk.bold(`${index + 1}. ${scoreStr} ${memberStr}`));
+    console.log(`   ${theme.summary}`);
+    console.log('');
+  });
+}

cli/package-lock.json

@@ -15,7 +15,7 @@ import {
   depsLogsCommand,
   depsPullModelCommand,
 } from './commands/deps.js';
-import { searchCommand } from './commands/search.js';
+import { searchCommand, searchThemesCommand } from './commands/search.js';
 import {
   memoryListCommand,
   memoryDeleteCommand,
@@ -117,16 +117,26 @@ deps
   .description('手动下载 BGE-M3 模型')
   .action(depsPullModelCommand);
 
-// Search command (Issue #10)
+// Search command (Issue #10) with xMemory hierarchical support
 program
   .command('search <query>')
   .description('🔍 语义搜索记忆')
   .option('-l, --limit <number>', '返回结果数量', '10')
   .option('--json', '以 JSON 格式输出')
-  .action((query, options) => searchCommand(query, {
-    limit: parseInt(options.limit, 10),
-    json: options.json,
-  }));
+  .option('--level <level>', '搜索层级: theme | semantic (默认: semantic)', 'semantic')
+  .option('--no-expand', '禁用主题展开到语义层 (仅在 --level theme 时有效)')
+  .action((query, options) => {
+    const searchOptions = {
+      limit: parseInt(options.limit, 10),
+      json: options.json,
+      level: options.level as 'theme' | 'semantic' | 'all',
+      expand: options.expand !== false, // --no-expand sets this to false
+    };
+    if (options.level === 'theme') {
+      return searchThemesCommand(query, searchOptions);
+    }
+    return searchCommand(query, searchOptions);
+  });
 
 // Memory command group (Issue #11)
 const memory = program