@claude-flow/cli 3.7.0-alpha.7 → 3.7.0-alpha.71

package/dist/src/mcp-tools/memory-tools.js

@@ -12,6 +12,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
 import { join, resolve } from 'path';
+import { createHash } from 'crypto';
 import { validateIdentifier } from './validate-input.js';
 // #1604: Align with memory-initializer.ts — single source of truth is .swarm/memory.db
 const MEMORY_DIR = '.swarm';
@@ -37,6 +38,11 @@ function ensureMemoryDir() {
 const MAX_KEY_LENGTH = 1024;
 const MAX_VALUE_SIZE = 1024 * 1024; // 1MB
 const MAX_QUERY_LENGTH = 4096;
+// #1425 — single source of truth for the dangerous-character set rejected by
+// validateMemoryInput. Imported by sanitizeMemoryKey so write-side sanitization
+// and read-side rejection can never drift apart (the symmetry bug behind #1884).
+const DANGEROUS_KEY_CHARS = /[;&|`$(){}[\]<>!#\\\0]|\.\.[/\\]/g;
+const DANGEROUS_KEY_PATTERN = /[;&|`$(){}[\]<>!#\\\0]|\.\.[/\\]/;
 function validateMemoryInput(key, value, query, namespace) {
     if (key && key.length > MAX_KEY_LENGTH) {
         throw new Error(`Key exceeds maximum length of ${MAX_KEY_LENGTH} characters`);
@@ -48,14 +54,104 @@ function validateMemoryInput(key, value, query, namespace) {
         throw new Error(`Query exceeds maximum length of ${MAX_QUERY_LENGTH} characters`);
     }
     // Reject path traversal and shell metacharacters in keys/namespaces (#1425)
-    const dangerousPattern = /[;&|`$(){}[\]<>!#\\\0]|\.\.[/\\]/;
-    if (key && dangerousPattern.test(key)) {
+    if (key && DANGEROUS_KEY_PATTERN.test(key)) {
         throw new Error('Key contains disallowed characters');
     }
-    if (namespace && dangerousPattern.test(namespace)) {
+    if (namespace && DANGEROUS_KEY_PATTERN.test(namespace)) {
         throw new Error('Namespace contains disallowed characters');
     }
 }
+// #1884 — sanitize a key produced from arbitrary input (markdown headings,
+// frontmatter names, file names) so it survives validateMemoryInput on the
+// read/delete path. Replaces every dangerous char with `_`. Truncates to
+// MAX_KEY_LENGTH so the bound check in validateMemoryInput also passes.
+// Keep this in sync with DANGEROUS_KEY_PATTERN — they share DANGEROUS_KEY_CHARS.
+function sanitizeMemoryKey(key) {
+    const safe = key.replace(DANGEROUS_KEY_CHARS, '_');
+    return safe.length > MAX_KEY_LENGTH ? safe.slice(0, MAX_KEY_LENGTH) : safe;
+}
+// #1937 — minimal glob → RegExp helper for memory_import_claude exclusion
+// patterns. Anchored. Supports the three operators the issue's voice-fidelity
+// workflow needs:
+//   `**` — any chars including path separators
+//   `*`  — any chars except path separators
+//   `?`  — exactly one char except a path separator
+// Everything else is regex-escaped. Used to match absolute file paths.
+function globToRegex(pattern) {
+    // Tokenize so we can replace `**` before `*` without overlap.
+    let out = '';
+    for (let i = 0; i < pattern.length; i++) {
+        const c = pattern[i];
+        if (c === '*' && pattern[i + 1] === '*') {
+            out += '.*';
+            i++;
+        }
+        else if (c === '*') {
+            out += '[^/\\\\]*';
+        }
+        else if (c === '?') {
+            out += '[^/\\\\]';
+        }
+        else if (/[.+^$|(){}\[\]\\]/.test(c)) {
+            out += '\\' + c;
+        }
+        else {
+            out += c;
+        }
+    }
+    return new RegExp('^' + out + '$');
+}
+// #1883 — resolve the Claude-Code project memory directory for the *current*
+// project. Claude Code hashes the project path differently per host OS, and
+// our previous logic only POSIX-slash-replaced cwd, which breaks for:
+//   - WSL bridges where cwd is `/mnt/<drive>/...` but Claude Code is on Windows
+//   - paths containing spaces (Claude Code replaces spaces with dashes)
+//   - any leading slash on POSIX (Claude Code strips it)
+// Strategy: try several candidate hashes and return the first one with a
+// memory dir that exists. An explicit `projectPathOverride` short-circuits
+// the heuristics for callers that know the canonical project path.
+function resolveProjectMemoryDir(claudeProjectsDir, projectPathOverride) {
+    const candidates = new Set();
+    const sources = [];
+    if (projectPathOverride && projectPathOverride.length > 0) {
+        sources.push(projectPathOverride);
+    }
+    else {
+        sources.push(process.cwd());
+    }
+    for (const source of sources) {
+        // Candidate 1: legacy POSIX hash — what shipped before #1883
+        candidates.add(source.replace(/\//g, '-'));
+        // Candidate 2: WSL `/mnt/<drive>/...` translated to Claude-Code Windows hash
+        // e.g. `/mnt/c/Users/x/Project Name` → `C--Users-x-Project-Name`
+        const wsl = source.match(/^\/mnt\/([a-z])(\/.*)?$/i);
+        if (wsl) {
+            const drive = wsl[1].toUpperCase();
+            const rest = (wsl[2] ?? '').replace(/\//g, '-').replace(/ /g, '-');
+            candidates.add(`${drive}-${rest}`);
+        }
+        // Candidate 3: POSIX hash with leading dash stripped (Claude Code on macOS/Linux)
+        const stripped = source.replace(/\//g, '-').replace(/^-+/, '');
+        candidates.add(stripped);
+        // Candidate 4: spaces replaced with dashes (Claude Code's space rule)
+        candidates.add(source.replace(/\//g, '-').replace(/ /g, '-'));
+        // Candidate 5 (#1939): native Win32 path on a Win32 Claude Code install.
+        // `C:\Users\tobia\OneDrive\Desktop\Claude Stuff` →
+        // `C--Users-tobia-OneDrive-Desktop-Claude-Stuff`. Claude Code's on-disk
+        // slug replaces drive-colon AND backslashes AND whitespace with `-`.
+        // The earlier candidates only handled forward slashes, so a Win32+Win32
+        // setup never matched.
+        if (/^[A-Za-z]:[\\/]/.test(source)) {
+            candidates.add(source.replace(/[:\\/]/g, '-').replace(/\s+/g, '-'));
+        }
+    }
+    for (const projectHash of candidates) {
+        const memDir = join(claudeProjectsDir, projectHash, 'memory');
+        if (existsSync(memDir))
+            return { memDir, projectHash };
+    }
+    return null;
+}
 /**
  * Check if legacy JSON store exists in old .claude-flow/memory/ location
  */
@@ -310,57 +406,81 @@ export const memoryTools = [
             validateMemoryInput(undefined, undefined, query);
             const startTime = performance.now();
             try {
+                // #1846: feature-detect smartSearch on the resolved memory package.
+                // The export landed in @claude-flow/memory@>3.0.0-alpha.14 — older
+                // installs pin to a build that exposes search/store/retrieve but
+                // not smartSearch. Throwing `is not a function` is hostile; instead
+                // detect at runtime and gracefully fall through to plain semantic
+                // search with an explicit fallback note.
+                let smartFallbackReason;
                 if (input.smart) {
-                    // SmartRetrieval pipeline (ADR-090)
-                    const { smartSearch } = await import('@claude-flow/memory');
-                    // Adapt searchEntries to the SearchFn interface
-                    const rawSearch = async (req) => {
-                        const r = await searchEntries({
-                            query: req.query,
-                            namespace: req.namespace || namespace,
-                            limit: req.limit || limit * 3,
-                            threshold: req.threshold ?? threshold,
-                        });
-                        return {
-                            results: r.results.map(e => ({
-                                id: e.id,
-                                key: e.key,
-                                content: e.content,
-                                score: e.score,
-                                namespace: e.namespace,
-                            })),
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    let memMod;
+                    try {
+                        memMod = await import('@claude-flow/memory');
+                    }
+                    catch (err) {
+                        smartFallbackReason = `@claude-flow/memory failed to load: ${err.message}`;
+                    }
+                    const smartSearch = memMod && typeof memMod.smartSearch === 'function'
+                        ? memMod.smartSearch
+                        : undefined;
+                    if (smartSearch) {
+                        // SmartRetrieval pipeline (ADR-090)
+                        const rawSearch = async (req) => {
+                            const r = await searchEntries({
+                                query: req.query,
+                                namespace: req.namespace || namespace,
+                                limit: req.limit || limit * 3,
+                                threshold: req.threshold ?? threshold,
+                            });
+                            return {
+                                results: r.results.map(e => ({
+                                    id: e.id,
+                                    key: e.key,
+                                    content: e.content,
+                                    score: e.score,
+                                    namespace: e.namespace,
+                                })),
+                            };
                         };
-                    };
-                    const smartResult = await smartSearch(rawSearch, {
-                        query,
-                        namespace,
-                        limit,
-                        threshold,
-                    });
-                    const duration = performance.now() - startTime;
-                    const results = smartResult.results.map(r => {
-                        let value = r.content;
-                        try {
-                            value = JSON.parse(r.content);
-                        }
-                        catch { /* keep as string */ }
+                        const smartResult = await smartSearch(rawSearch, {
+                            query,
+                            namespace,
+                            limit,
+                            threshold,
+                        });
+                        const duration = performance.now() - startTime;
+                        const results = smartResult.results.map((r) => {
+                            let value = r.content;
+                            try {
+                                value = JSON.parse(r.content);
+                            }
+                            catch { /* keep as string */ }
+                            return {
+                                key: r.key,
+                                namespace: r.namespace,
+                                value,
+                                similarity: r.score,
+                            };
+                        });
                         return {
-                            key: r.key,
-                            namespace: r.namespace,
-                            value,
-                            similarity: r.score,
+                            query,
+                            results,
+                            total: results.length,
+                            searchTime: `${duration.toFixed(2)}ms`,
+                            backend: 'SmartRetrieval (RRF + MMR + Recency)',
+                            stats: smartResult.stats,
                         };
-                    });
-                    return {
-                        query,
-                        results,
-                        total: results.length,
-                        searchTime: `${duration.toFixed(2)}ms`,
-                        backend: 'SmartRetrieval (RRF + MMR + Recency)',
-                        stats: smartResult.stats,
-                    };
+                    }
+                    // smart=true but smartSearch unavailable on installed package.
+                    // Fall through to plain search with an explicit warning.
+                    smartFallbackReason = smartFallbackReason
+                        ?? 'smartSearch is not exported by the installed @claude-flow/memory build (likely a release lag — see #1846). Falling back to standard semantic search.';
                 }
-                // Original non-smart path (unchanged)
+                // Original non-smart path (unchanged) — also reached when smart was
+                // requested but unavailable. We attach `smartFallback` to the
+                // response so callers can see the degradation explicitly.
                 const result = await searchEntries({
                     query,
                     namespace,
@@ -390,6 +510,7 @@ export const memoryTools = [
                     total: results.length,
                     searchTime: `${duration.toFixed(2)}ms`,
                     backend: 'HNSW + sql.js',
+                    ...(smartFallbackReason ? { smartFallback: smartFallbackReason } : {}),
                 };
             }
             catch (error) {
@@ -501,7 +622,7 @@ export const memoryTools = [
     },
     {
         name: 'memory_stats',
-        description: 'Get memory storage statistics including HNSW index status',
+        description: 'Get memory storage statistics including HNSW index status Use when native Read/Write is wrong because you need (a) cross-session retrieval by semantic similarity (vector embeddings) not by file path, (b) namespacing across projects without managing directory layout, or (c) the .swarm/memory.db audit trail. For one-shot file I/O, native Read/Write is fine.',
         category: 'memory',
         inputSchema: {
             type: 'object',
@@ -548,7 +669,7 @@ export const memoryTools = [
     },
     {
         name: 'memory_migrate',
-        description: 'Manually trigger migration from legacy JSON store to sql.js',
+        description: 'Manually trigger migration from legacy JSON store to sql.js Use when native Read/Write is wrong because you need (a) cross-session retrieval by semantic similarity (vector embeddings) not by file path, (b) namespacing across projects without managing directory layout, or (c) the .swarm/memory.db audit trail. For one-shot file I/O, native Read/Write is fine.',
         category: 'memory',
         inputSchema: {
             type: 'object',
@@ -587,13 +708,24 @@ export const memoryTools = [
     // ===== Claude Code Memory Bridge Tools =====
     {
         name: 'memory_import_claude',
-        description: 'Import Claude Code auto-memory files into AgentDB with ONNX vector embeddings. Reads ~/.claude/projects/*/memory/*.md files, parses YAML frontmatter, splits into sections, and stores with 384-dim embeddings for semantic search. Use allProjects=true to import from ALL Claude projects.',
+        description: 'Import Claude Code auto-memory files into AgentDB with ONNX vector embeddings. Reads ~/.claude/projects/*/memory/*.md files, parses YAML frontmatter, splits into sections, and stores with 384-dim embeddings for semantic search. Use allProjects=true to import from ALL Claude projects. Pass projectPath to override cwd-based detection (#1883 — required when Ruflo runs in WSL but Claude Code is on Windows). Pass excludeFilePatterns (glob list) or excludeFiles (absolute path list) to skip voice-load-bearing, PII, or persona-restricted files (#1937). Use when native Read/Write is wrong because you need (a) cross-session retrieval by semantic similarity (vector embeddings) not by file path, (b) namespacing across projects without managing directory layout, or (c) the .swarm/memory.db audit trail. For one-shot file I/O, native Read/Write is fine.',
         category: 'memory',
         inputSchema: {
             type: 'object',
             properties: {
                 allProjects: { type: 'boolean', description: 'Import from all Claude projects (default: current project only)' },
                 namespace: { type: 'string', description: 'Target namespace (default: "claude-memories")' },
+                projectPath: { type: 'string', description: '#1883 — explicit project path to hash, used when cwd does not match Claude Code\'s view (e.g. WSL bridge to Windows host). Pass the canonical project root as Claude Code sees it.' },
+                excludeFilePatterns: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: '#1937 — glob patterns matched against the absolute file path. Files matching ANY pattern are skipped. Supports `*` (any chars within a path segment), `**` (any chars including separators), and `?` (single char). Examples: `**/voice-*.md`, `**/persona-*.md`. Combine with excludeFiles for explicit paths.',
+                },
+                excludeFiles: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: '#1937 — absolute file paths to skip verbatim. Faster than a pattern when the list is known ahead of time (operator captured baselines). Combine with excludeFilePatterns.',
+                },
             },
         },
         handler: async (input) => {
@@ -606,9 +738,20 @@ export const memoryTools = [
                     return { success: false, imported: 0, error: vNs.error };
             }
             const allProjects = input.allProjects;
+            const projectPathOverride = input.projectPath;
             const claudeProjectsDir = join(homedir(), '.claude', 'projects');
+            // #1937 — voice-fidelity / persona-restricted exclusion.
+            const excludeFilePatterns = Array.isArray(input.excludeFilePatterns) ? input.excludeFilePatterns : [];
+            const excludeFilesList = Array.isArray(input.excludeFiles) ? new Set(input.excludeFiles) : new Set();
+            const excludeRegexes = excludeFilePatterns.map(globToRegex);
+            const isExcluded = (absPath) => {
+                if (excludeFilesList.has(absPath))
+                    return true;
+                return excludeRegexes.some(re => re.test(absPath));
+            };
             // Find memory files
             const memoryFiles = [];
+            let excludedByPattern = 0;
             if (allProjects) {
                 // Scan all projects
                 if (existsSync(claudeProjectsDir)) {
@@ -620,7 +763,12 @@ export const memoryTools = [
                             if (!existsSync(memDir))
                                 continue;
                             for (const file of readdirSync(memDir).filter((f) => f.endsWith('.md'))) {
-                                memoryFiles.push({ path: join(memDir, file), project: project.name, file });
+                                const absPath = join(memDir, file);
+                                if (isExcluded(absPath)) {
+                                    excludedByPattern++;
+                                    continue;
+                                }
+                                memoryFiles.push({ path: absPath, project: project.name, file });
                             }
                         }
                     }
@@ -628,14 +776,18 @@ export const memoryTools = [
                 }
             }
             else {
-                // Current project only — find by CWD hash
-                const cwd = process.cwd();
-                const projectHash = cwd.replace(/\//g, '-');
-                const memDir = join(claudeProjectsDir, projectHash, 'memory');
-                if (existsSync(memDir)) {
+                // #1883 — current project: try multiple candidate hashes (POSIX, WSL-translated,
+                // leading-dash-stripped, space-replaced). Caller can pass projectPath to override.
+                const resolved = resolveProjectMemoryDir(claudeProjectsDir, projectPathOverride);
+                if (resolved) {
                     try {
-                        for (const file of readdirSync(memDir).filter((f) => f.endsWith('.md'))) {
-                            memoryFiles.push({ path: join(memDir, file), project: projectHash, file });
+                        for (const file of readdirSync(resolved.memDir).filter((f) => f.endsWith('.md'))) {
+                            const absPath = join(resolved.memDir, file);
+                            if (isExcluded(absPath)) {
+                                excludedByPattern++;
+                                continue;
+                            }
+                            memoryFiles.push({ path: absPath, project: resolved.projectHash, file });
                         }
                     }
                     catch { /* scan error */ }
@@ -646,11 +798,28 @@ export const memoryTools = [
             }
             let imported = 0;
             let skipped = 0;
+            // #1791.8 — Claude Code's `~/.claude/projects/` accumulates historical
+            // project_id directories (truncated forms, sandbox cwds, renamed
+            // workspaces) that all contain copies of the same memory files. The
+            // previous import indexed each copy under a different `project_id`
+            // prefix, producing 5–8x duplication on long-lived homes. Dedupe by
+            // file content hash so the same memory is imported once even if it
+            // appears under several project directories.
+            const seenContentHashes = new Set();
+            let duplicatesSkipped = 0;
             const projects = new Set();
             for (const memFile of memoryFiles) {
                 projects.add(memFile.project);
                 try {
                     const content = readFileSync(memFile.path, 'utf-8');
+                    // #1791.8 — Skip if we've already imported this exact content under
+                    // a different project_id directory.
+                    const contentHash = createHash('sha256').update(content).digest('hex').slice(0, 16);
+                    if (seenContentHashes.has(contentHash)) {
+                        duplicatesSkipped++;
+                        continue;
+                    }
+                    seenContentHashes.add(contentHash);
                     const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
                     let name = memFile.file.replace('.md', '');
                     let body = content;
@@ -664,7 +833,10 @@ export const memoryTools = [
                     // Split into sections for granular search
                     const sections = body.split(/^(?=## )/m).filter(s => s.trim().length > 20);
                     if (sections.length === 0 && body.length > 10) {
-                        await storeEntry({ key: `claude:${memFile.project}:${name}`, value: body.slice(0, 4096), namespace: ns, generateEmbeddingFlag: true });
+                        // #1884 — sanitize key so memory_delete can later remove it. Without
+                        // this, dangerous chars from frontmatter `name` strand the key.
+                        const key = sanitizeMemoryKey(`claude:${memFile.project}:${name}`);
+                        await storeEntry({ key, value: body.slice(0, 4096), namespace: ns, generateEmbeddingFlag: true });
                         imported++;
                     }
                     else {
@@ -674,7 +846,10 @@ export const memoryTools = [
                             const sectionBody = section.replace(/^##\s+.+\n/, '').trim();
                             if (sectionBody.length < 10)
                                 continue;
-                            await storeEntry({ key: `claude:${memFile.project}:${name}:${sectionTitle.slice(0, 50)}`, value: sectionBody.slice(0, 4096), namespace: ns, generateEmbeddingFlag: true });
+                            // #1884 — sanitize so any dangerous chars in the heading don't
+                            // produce keys memory_delete will reject.
+                            const key = sanitizeMemoryKey(`claude:${memFile.project}:${name}:${sectionTitle.slice(0, 50)}`);
+                            await storeEntry({ key, value: sectionBody.slice(0, 4096), namespace: ns, generateEmbeddingFlag: true });
                             imported++;
                         }
                     }
@@ -687,6 +862,8 @@ export const memoryTools = [
                 success: true,
                 imported,
                 skipped,
+                duplicatesSkipped,
+                excludedByPattern,
                 files: memoryFiles.length,
                 projects: projects.size,
                 namespace: ns,
@@ -696,7 +873,7 @@ export const memoryTools = [
     },
     {
         name: 'memory_bridge_status',
-        description: 'Show Claude Code memory bridge status — AgentDB vectors, SONA learning, intelligence patterns, and connection health.',
+        description: 'Show Claude Code memory bridge status — AgentDB vectors, SONA learning, intelligence patterns, and connection health. Use when native Read/Write is wrong because you need (a) cross-session retrieval by semantic similarity (vector embeddings) not by file path, (b) namespacing across projects without managing directory layout, or (c) the .swarm/memory.db audit trail. For one-shot file I/O, native Read/Write is fine.',
         category: 'memory',
         inputSchema: { type: 'object', properties: {} },
         handler: async () => {
@@ -723,14 +900,34 @@ export const memoryTools = [
                 catch { /* ignore */ }
             }
             // AgentDB status
+            // #1940: previously used `allEntries.entries.length` for the totals,
+            // but `listEntries({})` returns the first 20 entries with a separate
+            // `total` field for the full row count. So `memory_bridge_status`
+            // reported `totalEntries: 0`...20 even when the DB had hundreds of
+            // rows. Use `.total` for the count, and surface the namespaces with
+            // entries so the report matches what's actually in the store.
             let agentdbEntries = 0;
             let claudeMemoryEntries = 0;
+            const namespaceCounts = {};
             try {
                 const { listEntries } = await getMemoryFunctions();
                 const allEntries = await listEntries({});
-                agentdbEntries = allEntries?.entries?.length ?? 0;
+                agentdbEntries = allEntries?.total
+                    ?? allEntries?.entries?.length ?? 0;
                 const claudeEntries = await listEntries({ namespace: 'claude-memories' });
-                claudeMemoryEntries = claudeEntries?.entries?.length ?? 0;
+                claudeMemoryEntries = claudeEntries?.total
+                    ?? claudeEntries?.entries?.length ?? 0;
+                // Per-namespace counts for the namespaces the reporter referenced
+                // (#1940). Best-effort — a namespace with 0 entries is omitted.
+                for (const ns of ['default', 'patterns', 'claude-memories', 'auto-memory', 'tasks', 'feedback', 'pretrain']) {
+                    try {
+                        const r = await listEntries({ namespace: ns });
+                        const t = r?.total ?? r?.entries?.length ?? 0;
+                        if (t > 0)
+                            namespaceCounts[ns] = t;
+                    }
+                    catch { /* skip per-namespace failure */ }
+                }
             }
             catch { /* ignore */ }
             // Intelligence status
@@ -744,15 +941,18 @@ export const memoryTools = [
             catch { /* not initialized */ }
             return {
                 claudeCode: { memoryFiles: claudeFiles, projects: claudeProjects },
-                agentdb: { totalEntries: agentdbEntries, claudeMemoryEntries, backend: 'sql.js + ONNX' },
+                agentdb: { totalEntries: agentdbEntries, claudeMemoryEntries, namespaces: namespaceCounts, backend: 'sql.js + ONNX' },
                 intelligence,
-                bridge: { status: claudeMemoryEntries > 0 ? 'connected' : 'not-synced', embedding: 'all-MiniLM-L6-v2 (384-dim)' },
+                // #1940: report 'connected' whenever ANY namespace has imported
+                // content, not just `claude-memories` — the bridge can be in active
+                // use from other import paths (e.g. plugin namespaces, task memory).
+                bridge: { status: agentdbEntries > 0 ? 'connected' : 'not-synced', embedding: 'all-MiniLM-L6-v2 (384-dim)' },
             };
         },
     },
     {
         name: 'memory_search_unified',
-        description: 'Search across both Claude Code memories and AgentDB entries using semantic vector similarity. Returns merged, deduplicated results from all namespaces.',
+        description: 'Search across both Claude Code memories and AgentDB entries using semantic vector similarity. Returns merged, deduplicated results from all namespaces. Use when native Read/Write is wrong because you need (a) cross-session retrieval by semantic similarity (vector embeddings) not by file path, (b) namespacing across projects without managing directory layout, or (c) the .swarm/memory.db audit trail. For one-shot file I/O, native Read/Write is fine.',
         category: 'memory',
         inputSchema: {
             type: 'object',
@@ -814,5 +1014,227 @@ export const memoryTools = [
             };
         },
     },
+    {
+        // #1916: `ruflo status memory` (the detailed view) referenced an
+        // unregistered `memory_detailed-stats` tool. memory_stats returns a
+        // different shape; this returns what the CLI renders.
+        name: 'memory_detailed-stats',
+        description: 'Detailed memory-store report — backend, entry count, total bytes, per-namespace counts, and (placeholder) perf metrics. Use when native Read/Glob is wrong because the data lives in .swarm/memory.db, not files, and you want an aggregate health view. For a quick count use memory_stats; for "what is in memory" use memory_list.',
+        category: 'memory',
+        inputSchema: { type: 'object', properties: {} },
+        handler: async () => {
+            await ensureInitialized();
+            const { listEntries } = await getMemoryFunctions();
+            const all = await listEntries({ limit: 100000 });
+            const nsCounts = {};
+            let bytes = 0;
+            for (const e of all.entries) {
+                nsCounts[e.namespace] = (nsCounts[e.namespace] || 0) + 1;
+                bytes += e.size || 0;
+            }
+            return {
+                backend: 'sql.js + HNSW',
+                entries: all.total ?? all.entries.length,
+                size: bytes,
+                namespaces: Object.entries(nsCounts).map(([name, entries]) => ({ name, entries })),
+                performance: { avgSearchTime: 0, avgWriteTime: 0, cacheHitRate: 0, hnswEnabled: true },
+                note: 'perf metrics are placeholders; HNSW is always enabled in the sql.js backend',
+            };
+        },
+    },
+    {
+        // #1916: `ruflo memory cleanup` referenced an unregistered `memory_cleanup`
+        // tool. Removes entries whose TTL has expired. Defaults to a dry run —
+        // pass dryRun:false to actually delete.
+        name: 'memory_cleanup',
+        description: 'Prune memory entries whose TTL has expired (dry run by default; pass dryRun:false to delete). Use when native rm is wrong because the entries are rows in .swarm/memory.db, not files. For removing a specific known key use memory_delete. Stale/low-quality pruning is delegated to the agentdb consolidation curator (#1916 follow-up).',
+        category: 'memory',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                dryRun: { type: 'boolean', description: 'Only report candidates, do not delete (default true)' },
+                namespace: { type: 'string', description: 'Limit cleanup to one namespace' },
+            },
+        },
+        handler: async (input) => {
+            await ensureInitialized();
+            const { listEntries, deleteEntry } = await getMemoryFunctions();
+            const dryRun = input.dryRun !== false; // default true
+            const namespace = input.namespace ? String(input.namespace) : undefined;
+            if (namespace) {
+                const v = validateIdentifier(namespace, 'namespace');
+                if (!v.valid)
+                    throw new Error(v.error);
+            }
+            const all = await listEntries({ limit: 100000, namespace });
+            const now = Date.now();
+            const expired = all.entries.filter(e => {
+                const exp = e.expiresAt;
+                if (!exp)
+                    return false;
+                const t = typeof exp === 'number' ? exp : Date.parse(String(exp));
+                return Number.isFinite(t) && t < now;
+            });
+            let freedBytes = 0;
+            let deleted = 0;
+            if (!dryRun) {
+                for (const e of expired) {
+                    try {
+                        await deleteEntry({ key: e.key, namespace: e.namespace });
+                        freedBytes += e.size || 0;
+                        deleted++;
+                    }
+                    catch { /* ignore individual delete errors */ }
+                }
+            }
+            else {
+                freedBytes = expired.reduce((s, e) => s + (e.size || 0), 0);
+            }
+            return {
+                dryRun,
+                candidates: { expired: expired.length, stale: 0, lowQuality: 0, total: expired.length },
+                deleted: { entries: dryRun ? 0 : deleted, vectors: 0, patterns: 0 },
+                freed: { bytes: freedBytes },
+                note: dryRun ? 'dry run — re-run with dryRun:false to delete' : undefined,
+            };
+        },
+    },
+    {
+        // #1916: `ruflo memory compress` referenced an unregistered tool. The
+        // sql.js backend has no on-disk compression; this reports current sizes.
+        name: 'memory_compress',
+        description: 'Report memory-store size breakdown (the sql.js backend has no on-disk compression — entries are already stored compactly; quantized embeddings via RaBitQ are configured elsewhere). Use when native du is wrong because the data is in .swarm/memory.db. For pruning expired entries use memory_cleanup.',
+        category: 'memory',
+        inputSchema: { type: 'object', properties: {} },
+        handler: async () => {
+            await ensureInitialized();
+            const { listEntries } = await getMemoryFunctions();
+            const all = await listEntries({ limit: 100000 });
+            const bytes = all.entries.reduce((s, e) => s + (e.size || 0), 0);
+            const human = `${bytes}B`;
+            const sizes = { totalSize: human, vectorsSize: 'n/a', textSize: human, patternsSize: 'n/a', indexSize: 'n/a' };
+            return {
+                before: sizes,
+                after: sizes,
+                compression: { ratio: 1, savedBytes: 0, method: 'none' },
+                note: 'sql.js backend has no on-disk compression; nothing to compress. (RaBitQ embedding quantization is a separate feature.)',
+            };
+        },
+    },
+    {
+        // #1916: `ruflo memory export -o <file>` referenced an unregistered tool.
+        // Dumps entry metadata (and values when the backend returns them) to JSON.
+        name: 'memory_export',
+        description: 'Export memory entries to a JSON file (keys, namespaces, timestamps, and values when available). Use when native Write is wrong because the data is rows in .swarm/memory.db, not a file you can copy. For ingesting an export elsewhere use memory_import. (CSV output and embedding-vector export are follow-ups.)',
+        category: 'memory',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                outputPath: { type: 'string', description: 'File path to write the JSON export to' },
+                format: { type: 'string', enum: ['json', 'csv'], description: 'Export format (csv falls back to json today)' },
+                namespace: { type: 'string', description: 'Limit export to one namespace' },
+                includeVectors: { type: 'boolean', description: 'Include embedding vectors (advisory — not exported yet)' },
+            },
+            required: ['outputPath'],
+        },
+        handler: async (input) => {
+            await ensureInitialized();
+            const { listEntries } = await getMemoryFunctions();
+            const outputPath = String(input.outputPath ?? '');
+            if (!outputPath)
+                return { error: 'outputPath is required' };
+            const namespace = input.namespace ? String(input.namespace) : undefined;
+            if (namespace) {
+                const v = validateIdentifier(namespace, 'namespace');
+                if (!v.valid)
+                    throw new Error(v.error);
+            }
+            const all = await listEntries({ limit: 100000, namespace });
+            const payload = {
+                schema: 'ruflo-memory-export/v1',
+                exportedAt: new Date().toISOString(),
+                namespace: namespace ?? null,
+                count: all.entries.length,
+                entries: all.entries.map(e => ({
+                    key: e.key, namespace: e.namespace, value: e.value ?? null,
+                    createdAt: e.createdAt, updatedAt: e.updatedAt, accessCount: e.accessCount, hasEmbedding: e.hasEmbedding, size: e.size,
+                })),
+            };
+            try {
+                writeFileSync(outputPath, JSON.stringify(payload, null, 2), 'utf-8');
+            }
+            catch (e) {
+                return { error: `Could not write ${outputPath}: ${e.message}` };
+            }
+            const vectorsWithEmb = all.entries.filter(e => e.hasEmbedding).length;
+            return {
+                outputPath,
+                format: input.format || 'json',
+                exported: { entries: all.entries.length, vectors: vectorsWithEmb, patterns: 0 },
+                fileSize: `${Buffer.byteLength(JSON.stringify(payload))}B`,
+                note: input.format === 'csv' ? 'CSV not implemented yet — wrote JSON' : undefined,
+            };
+        },
+    },
+    {
+        // #1916: `ruflo memory import <file>` referenced an unregistered tool.
+        // Reads a ruflo-memory-export JSON and re-stores each entry.
+        name: 'memory_import',
+        description: 'Import memory entries from a JSON export file (produced by memory_export) into .swarm/memory.db, re-embedding values. Use when native Read is wrong because the data must be re-stored as memory rows (with new embeddings), not just read. For importing Claude Code\'s own memory files use memory_import_claude. Pair with memory_export on the source.',
+        category: 'memory',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                inputPath: { type: 'string', description: 'Path to the JSON export file' },
+                merge: { type: 'boolean', description: 'Merge into existing entries (upsert) vs. fail on conflict (default true)' },
+                namespace: { type: 'string', description: 'Override the namespace for all imported entries' },
+            },
+            required: ['inputPath'],
+        },
+        handler: async (input) => {
+            await ensureInitialized();
+            const { storeEntry } = await getMemoryFunctions();
+            const t0 = Date.now();
+            const inputPath = String(input.inputPath ?? '');
+            if (!inputPath || !existsSync(inputPath))
+                return { error: `File not found: ${inputPath || '(empty)'}` };
+            let doc;
+            try {
+                doc = JSON.parse(readFileSync(inputPath, 'utf-8'));
+            }
+            catch (e) {
+                return { error: `Invalid export JSON: ${e.message}` };
+            }
+            const entries = Array.isArray(doc.entries) ? doc.entries : [];
+            const nsOverride = input.namespace ? String(input.namespace) : undefined;
+            if (nsOverride) {
+                const v = validateIdentifier(nsOverride, 'namespace');
+                if (!v.valid)
+                    throw new Error(v.error);
+            }
+            let imported = 0;
+            let skipped = 0;
+            for (const e of entries) {
+                if (!e || typeof e.key !== 'string') {
+                    skipped++;
+                    continue;
+                }
+                const value = typeof e.value === 'string' ? e.value : JSON.stringify(e.value ?? null);
+                try {
+                    await storeEntry({ key: e.key, value, namespace: nsOverride ?? e.namespace ?? 'default', upsert: input.merge !== false });
+                    imported++;
+                }
+                catch {
+                    skipped++;
+                }
+            }
+            return {
+                inputPath,
+                imported: { entries: imported, vectors: 0, patterns: 0 },
+                skipped,
+                duration: Date.now() - t0,
+            };
+        },
+    },
 ];
 //# sourceMappingURL=memory-tools.js.map