agentic-qe 3.10.6 → 3.10.8

package/dist/init/opencode-installer.d.ts

@@ -2,8 +2,20 @@
  * OpenCode Platform Installer
  * ADR-025: Enhanced Init with Self-Configuration
  *
- * Installs OpenCode agents, skills, tools, and permissions to user projects
- * when --with-opencode flag is used. Follows the N8n installer pattern.
+ * Installs OpenCode agents and skills to user projects in OpenCode's NATIVE
+ * on-disk format (validated against OpenCode CLI v1.17.x):
+ *   - agents -> .opencode/agent/<name>.md   (markdown + YAML frontmatter; body = system prompt)
+ *   - skills -> .opencode/skills/<name>/SKILL.md  (frontmatter name+description; body = instructions)
+ *   - MCP    -> opencode.json (mcp.agentic-qe local server)
+ *
+ * The shipped source assets under <pkg>/.opencode/{agents,skills} use AQE's own
+ * YAML schema (name/description/model/systemPrompt/tools/permissions). OpenCode
+ * does NOT load that schema, so this installer CONVERTS them at install time.
+ *
+ * Tools are intentionally NOT installed: AQE's .opencode/tools/*.ts use a custom
+ * `{name, parameters, execute}` shape and call ctx.callTool('mcp:agentic-qe:*'),
+ * which is incompatible with OpenCode's `tool()` API and redundant once the MCP
+ * server is connected (the underlying tools are exposed directly).
  */
 export interface OpenCodeInstallerOptions {
     /** Project root directory */
@@ -12,10 +24,21 @@ export interface OpenCodeInstallerOptions {
     installAgents?: boolean;
     /** Install OpenCode skill definitions (default: true) */
     installSkills?: boolean;
-    /** Install OpenCode tool wrappers (default: true) */
+    /**
+     * Install AQE tool wrappers. Default false — AQE's tool .ts files are not in
+     * OpenCode's `tool()` format and are redundant with the MCP server. Kept as an
+     * option only for backward compatibility; enabling it copies incompatible files.
+     */
     installTools?: boolean;
     /** Overwrite existing files (default: false) */
     overwrite?: boolean;
+    /**
+     * Memory backend the generated opencode.json MCP server should use at runtime.
+     * 'memory' => fully database-free install: AQE_MEMORY_BACKEND=memory and no
+     * AQE_MEMORY_PATH, so the MCP server keeps everything in-memory and writes
+     * nothing under .agentic-qe/. Default (undefined) preserves persistent SQLite.
+     */
+    memoryBackend?: 'memory' | 'sqlite' | 'agentdb' | 'hybrid';
 }
 export interface OpenCodeInstallResult {
     success: boolean;
@@ -32,7 +55,7 @@ export declare class OpenCodeInstaller {
     private sourceDir;
     constructor(options: OpenCodeInstallerOptions);
     /**
-     * Find the source .opencode/ directory containing agents/skills/tools to install.
+     * Find the source .opencode/ directory containing agents/skills to install.
      * Resolves relative to the package installation directory (not CWD) so that
      * globally-installed and bundled CLI paths all work correctly (#361).
      */
@@ -43,27 +66,26 @@ export declare class OpenCodeInstaller {
      */
     private isValidSourceDir;
     /**
-     * Install OpenCode agents, skills, tools, and permissions
+     * Install OpenCode agents, skills, and MCP config (native OpenCode format).
      */
     install(): Promise<OpenCodeInstallResult>;
     /**
-     * Install agent YAML files from .opencode/agents/
+     * Load the shipped permissions.yaml (defaults + per-agent overrides). Returns
+     * { defaults, agents } or empty maps if the file is missing/unparseable.
      */
-    private installAgents;
+    private loadPermissionsYaml;
     /**
-     * Install skill YAML files from .opencode/skills/
+     * Build an OpenCode-valid `permission` frontmatter object by merging
+     * defaults -> agent.permissions (from agent yaml) -> permissions.yaml override,
+     * remapping keys and dropping anything OpenCode does not understand.
      */
+    private buildPermission;
+    private installAgents;
     private installSkills;
+    /** Render a frontmatter object as a `---`-delimited YAML block. */
+    private renderFrontmatter;
     /**
-     * Install tool wrapper files from .opencode/tools/
-     */
-    private installTools;
-    /**
-     * Install permissions.yaml to target .opencode/ directory
-     */
-    private installPermissions;
-    /**
-     * Generate opencode.json MCP config if it does not already exist
+     * Generate opencode.json MCP config if it does not already exist.
      */
     private generateOpenCodeConfig;
 }

package/dist/init/opencode-installer.js

@@ -2,13 +2,39 @@
  * OpenCode Platform Installer
  * ADR-025: Enhanced Init with Self-Configuration
  *
- * Installs OpenCode agents, skills, tools, and permissions to user projects
- * when --with-opencode flag is used. Follows the N8n installer pattern.
+ * Installs OpenCode agents and skills to user projects in OpenCode's NATIVE
+ * on-disk format (validated against OpenCode CLI v1.17.x):
+ *   - agents -> .opencode/agent/<name>.md   (markdown + YAML frontmatter; body = system prompt)
+ *   - skills -> .opencode/skills/<name>/SKILL.md  (frontmatter name+description; body = instructions)
+ *   - MCP    -> opencode.json (mcp.agentic-qe local server)
+ *
+ * The shipped source assets under <pkg>/.opencode/{agents,skills} use AQE's own
+ * YAML schema (name/description/model/systemPrompt/tools/permissions). OpenCode
+ * does NOT load that schema, so this installer CONVERTS them at install time.
+ *
+ * Tools are intentionally NOT installed: AQE's .opencode/tools/*.ts use a custom
+ * `{name, parameters, execute}` shape and call ctx.callTool('mcp:agentic-qe:*'),
+ * which is incompatible with OpenCode's `tool()` API and redundant once the MCP
+ * server is connected (the underlying tools are exposed directly).
  */
-import { existsSync, mkdirSync, readdirSync, writeFileSync, copyFileSync, } from 'fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from 'fs';
 import { join } from 'path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import { toErrorMessage } from '../shared/error-utils.js';
 import { findPackageRoot } from './find-package-root.js';
+// OpenCode-valid per-agent permission keys. AQE keys outside this set are dropped
+// or remapped (see PERM_KEY_MAP). In particular `mcp:agentic-qe:*` patterns are
+// dropped — OpenCode does not interpret MCP tool patterns in the permission block.
+const VALID_PERMISSION_KEYS = new Set([
+    'read', 'edit', 'glob', 'grep', 'list', 'bash', 'task',
+    'external_directory', 'todowrite', 'webfetch', 'websearch',
+    'lsp', 'skill', 'question', 'doom_loop',
+]);
+// Remap AQE permission keys to OpenCode equivalents.
+const PERM_KEY_MAP = {
+    fetch: 'webfetch',
+    write: 'edit', // OpenCode has no separate 'write' permission; file writes are 'edit'
+};
 // ============================================================================
 // OpenCode Installer Class
 // ============================================================================
@@ -21,7 +47,7 @@ export class OpenCodeInstaller {
         this.options = {
             installAgents: true,
             installSkills: true,
-            installTools: true,
+            installTools: false,
             overwrite: false,
             ...options,
         };
@@ -31,7 +57,7 @@ export class OpenCodeInstaller {
     // Source Directory Detection
     // ==========================================================================
     /**
-     * Find the source .opencode/ directory containing agents/skills/tools to install.
+     * Find the source .opencode/ directory containing agents/skills to install.
      * Resolves relative to the package installation directory (not CWD) so that
      * globally-installed and bundled CLI paths all work correctly (#361).
      */
@@ -40,20 +66,16 @@ export class OpenCodeInstaller {
         const pkgRoot = findPackageRoot(import.meta.url);
         const possiblePaths = [];
         if (pkgRoot) {
-            // OpenCode assets live at the package root .opencode/ directory
             possiblePaths.push(join(pkgRoot, '.opencode'));
         }
-        // Local install: in node_modules
         possiblePaths.push(join(this.projectRoot, 'node_modules/agentic-qe/.opencode'));
         for (const path of possiblePaths) {
-            // Never use the target directory as the source
             if (path === targetDir)
                 continue;
             if (this.isValidSourceDir(path)) {
                 return path;
             }
         }
-        // Return the first package path even if not found — install() will report the error
         return possiblePaths[0] ?? join(this.projectRoot, 'node_modules/agentic-qe/.opencode');
     }
     /**
@@ -69,7 +91,7 @@ export class OpenCodeInstaller {
     // Installation
     // ==========================================================================
     /**
-     * Install OpenCode agents, skills, tools, and permissions
+     * Install OpenCode agents, skills, and MCP config (native OpenCode format).
      */
     async install() {
         const targetDir = join(this.projectRoot, '.opencode');
@@ -88,29 +110,22 @@ export class OpenCodeInstaller {
                 result.success = false;
                 return result;
             }
-            // Install agents
+            // Per-agent permission overrides shipped in permissions.yaml (defaults +
+            // per-agent). Merged with each agent's own `permissions` field.
+            const permissionsYaml = this.loadPermissionsYaml();
             if (this.options.installAgents) {
-                const agentResult = this.installAgents(targetDir);
+                const agentResult = this.installAgents(targetDir, permissionsYaml);
                 result.agentsInstalled = agentResult.installed;
                 result.errors.push(...agentResult.errors);
+                // Per-agent permissions are folded into each agent's frontmatter.
+                result.permissionsInstalled = result.agentsInstalled.length > 0;
             }
-            // Install skills
             if (this.options.installSkills) {
                 const skillResult = this.installSkills(targetDir);
                 result.skillsInstalled = skillResult.installed;
                 result.errors.push(...skillResult.errors);
             }
-            // Install tools
-            if (this.options.installTools) {
-                const toolResult = this.installTools(targetDir);
-                result.toolsInstalled = toolResult.installed;
-                result.errors.push(...toolResult.errors);
-            }
-            // Install permissions
-            const permResult = this.installPermissions(targetDir);
-            result.permissionsInstalled = permResult.installed;
-            result.errors.push(...permResult.errors);
-            // Generate opencode.json MCP config if not exists
+            // Generate opencode.json MCP config if not present.
             this.generateOpenCodeConfig();
         }
         catch (error) {
@@ -119,14 +134,58 @@ export class OpenCodeInstaller {
         }
         return result;
     }
+    // ==========================================================================
+    // Permission helpers
+    // ==========================================================================
     /**
-     * Install agent YAML files from .opencode/agents/
+     * Load the shipped permissions.yaml (defaults + per-agent overrides). Returns
+     * { defaults, agents } or empty maps if the file is missing/unparseable.
      */
-    installAgents(targetDir) {
+    loadPermissionsYaml() {
+        const empty = { defaults: {}, agents: {} };
+        const file = join(this.sourceDir, 'permissions.yaml');
+        if (!existsSync(file))
+            return empty;
+        try {
+            const parsed = parseYaml(readFileSync(file, 'utf-8'));
+            return { defaults: parsed?.defaults ?? {}, agents: parsed?.agents ?? {} };
+        }
+        catch {
+            return empty;
+        }
+    }
+    /**
+     * Build an OpenCode-valid `permission` frontmatter object by merging
+     * defaults -> agent.permissions (from agent yaml) -> permissions.yaml override,
+     * remapping keys and dropping anything OpenCode does not understand.
+     */
+    buildPermission(agentName, agentPerms, permissionsYaml) {
+        const merged = {
+            ...permissionsYaml.defaults,
+            ...(agentPerms ?? {}),
+            ...(permissionsYaml.agents[agentName] ?? {}),
+        };
+        const out = {};
+        for (const [rawKey, value] of Object.entries(merged)) {
+            // Drop MCP tool patterns and any other unsupported key.
+            if (rawKey.includes(':'))
+                continue;
+            const key = PERM_KEY_MAP[rawKey] ?? rawKey;
+            if (!VALID_PERMISSION_KEYS.has(key))
+                continue;
+            // 'allow' | 'ask' | 'deny' (string) or object map for bash etc.
+            out[key] = value;
+        }
+        return out;
+    }
+    // ==========================================================================
+    // Agents: <name>.yaml -> .opencode/agent/<name>.md
+    // ==========================================================================
+    installAgents(targetDir, permissionsYaml) {
         const installed = [];
         const errors = [];
         const sourceAgentsDir = join(this.sourceDir, 'agents');
-        const targetAgentsDir = join(targetDir, 'agents');
+        const targetAgentsDir = join(targetDir, 'agent'); // OpenCode native: singular 'agent'
         if (!existsSync(sourceAgentsDir)) {
             errors.push(`Source agents directory not found: ${sourceAgentsDir}`);
             return { installed, errors };
@@ -134,26 +193,37 @@ export class OpenCodeInstaller {
         if (!existsSync(targetAgentsDir)) {
             mkdirSync(targetAgentsDir, { recursive: true });
         }
-        const files = readdirSync(sourceAgentsDir).filter(f => f.endsWith('.yaml'));
-        for (const file of files) {
-            const sourceFile = join(sourceAgentsDir, file);
-            const targetFile = join(targetAgentsDir, file);
-            if (existsSync(targetFile) && !this.options.overwrite) {
-                continue;
-            }
+        for (const file of readdirSync(sourceAgentsDir).filter(f => f.endsWith('.yaml'))) {
             try {
-                copyFileSync(sourceFile, targetFile);
-                installed.push(file.replace('.yaml', ''));
+                const data = parseYaml(readFileSync(join(sourceAgentsDir, file), 'utf-8'));
+                const name = data.name || file.replace(/\.yaml$/, '');
+                const targetFile = join(targetAgentsDir, `${name}.md`);
+                if (existsSync(targetFile) && !this.options.overwrite)
+                    continue;
+                const frontmatter = {
+                    description: (data.description || name).replace(/\s+/g, ' ').trim(),
+                    mode: 'subagent',
+                };
+                // NOTE: `model` is intentionally omitted so agents inherit the user's
+                // default OpenCode model. AQE ships model "claude-sonnet-4-6" which may
+                // not resolve in OpenCode's provider registry; inheriting avoids
+                // hard-failing the agent at invocation time.
+                const permission = this.buildPermission(name, data.permissions, permissionsYaml);
+                if (Object.keys(permission).length > 0)
+                    frontmatter.permission = permission;
+                const body = (data.systemPrompt || '').trimEnd() + '\n';
+                writeFileSync(targetFile, this.renderFrontmatter(frontmatter) + '\n' + body);
+                installed.push(name);
             }
             catch (error) {
-                errors.push(`Failed to install agent ${file}: ${toErrorMessage(error)}`);
+                errors.push(`Failed to convert agent ${file}: ${toErrorMessage(error)}`);
             }
         }
         return { installed, errors };
     }
-    /**
-     * Install skill YAML files from .opencode/skills/
-     */
+    // ==========================================================================
+    // Skills: <name>.yaml -> .opencode/skills/<name>/SKILL.md
+    // ==========================================================================
     installSkills(targetDir) {
         const installed = [];
         const errors = [];
@@ -166,97 +236,79 @@ export class OpenCodeInstaller {
         if (!existsSync(targetSkillsDir)) {
             mkdirSync(targetSkillsDir, { recursive: true });
         }
-        const files = readdirSync(sourceSkillsDir).filter(f => f.endsWith('.yaml'));
-        for (const file of files) {
-            const sourceFile = join(sourceSkillsDir, file);
-            const targetFile = join(targetSkillsDir, file);
-            if (existsSync(targetFile) && !this.options.overwrite) {
-                continue;
-            }
+        for (const file of readdirSync(sourceSkillsDir).filter(f => f.endsWith('.yaml'))) {
             try {
-                copyFileSync(sourceFile, targetFile);
-                installed.push(file.replace('.yaml', ''));
+                const data = parseYaml(readFileSync(join(sourceSkillsDir, file), 'utf-8'));
+                const name = (data.name || file.replace(/\.yaml$/, '')).toLowerCase();
+                // OpenCode requires: ^[a-z0-9]+(-[a-z0-9]+)*$ and name === directory.
+                if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name)) {
+                    errors.push(`Skipped skill with non-conforming name: ${name}`);
+                    continue;
+                }
+                const skillDir = join(targetSkillsDir, name);
+                const targetFile = join(skillDir, 'SKILL.md');
+                if (existsSync(targetFile) && !this.options.overwrite)
+                    continue;
+                if (!existsSync(skillDir))
+                    mkdirSync(skillDir, { recursive: true });
+                let description = (data.description || name).replace(/\s+/g, ' ').trim();
+                if (description.length > 1024)
+                    description = description.slice(0, 1021) + '...';
+                let body = '';
+                for (const step of data.steps ?? []) {
+                    body += `## ${step.name || 'step'}\n\n`;
+                    const text = (step.prompt || step.description || '').trimEnd();
+                    if (text)
+                        body += `${text}\n\n`;
+                }
+                if (!body.trim())
+                    body = `${data.description || name}\n`;
+                writeFileSync(targetFile, this.renderFrontmatter({ name, description }) + '\n' + body.trimEnd() + '\n');
+                installed.push(name);
             }
             catch (error) {
-                errors.push(`Failed to install skill ${file}: ${toErrorMessage(error)}`);
+                errors.push(`Failed to convert skill ${file}: ${toErrorMessage(error)}`);
             }
         }
         return { installed, errors };
     }
-    /**
-     * Install tool wrapper files from .opencode/tools/
-     */
-    installTools(targetDir) {
-        const installed = [];
-        const errors = [];
-        const sourceToolsDir = join(this.sourceDir, 'tools');
-        const targetToolsDir = join(targetDir, 'tools');
-        if (!existsSync(sourceToolsDir)) {
-            errors.push(`Source tools directory not found: ${sourceToolsDir}`);
-            return { installed, errors };
-        }
-        if (!existsSync(targetToolsDir)) {
-            mkdirSync(targetToolsDir, { recursive: true });
-        }
-        const files = readdirSync(sourceToolsDir).filter(f => f.endsWith('.ts'));
-        for (const file of files) {
-            const sourceFile = join(sourceToolsDir, file);
-            const targetFile = join(targetToolsDir, file);
-            if (existsSync(targetFile) && !this.options.overwrite) {
-                continue;
-            }
-            try {
-                copyFileSync(sourceFile, targetFile);
-                installed.push(file.replace('.ts', ''));
-            }
-            catch (error) {
-                errors.push(`Failed to install tool ${file}: ${toErrorMessage(error)}`);
-            }
-        }
-        return { installed, errors };
-    }
-    /**
-     * Install permissions.yaml to target .opencode/ directory
-     */
-    installPermissions(targetDir) {
-        const errors = [];
-        const sourceFile = join(this.sourceDir, 'permissions.yaml');
-        const targetFile = join(targetDir, 'permissions.yaml');
-        if (!existsSync(sourceFile)) {
-            return { installed: false, errors: [] };
-        }
-        if (existsSync(targetFile) && !this.options.overwrite) {
-            return { installed: false, errors: [] };
-        }
-        try {
-            if (!existsSync(targetDir)) {
-                mkdirSync(targetDir, { recursive: true });
-            }
-            copyFileSync(sourceFile, targetFile);
-            return { installed: true, errors: [] };
-        }
-        catch (error) {
-            errors.push(`Failed to install permissions.yaml: ${toErrorMessage(error)}`);
-            return { installed: false, errors };
-        }
+    // ==========================================================================
+    // Frontmatter rendering
+    // ==========================================================================
+    /** Render a frontmatter object as a `---`-delimited YAML block. */
+    renderFrontmatter(obj) {
+        return `---\n${stringifyYaml(obj).trimEnd()}\n---\n`;
     }
+    // ==========================================================================
+    // opencode.json MCP config
+    // ==========================================================================
     /**
-     * Generate opencode.json MCP config if it does not already exist
+     * Generate opencode.json MCP config if it does not already exist.
      */
     generateOpenCodeConfig() {
         const configPath = join(this.projectRoot, 'opencode.json');
-        if (existsSync(configPath)) {
+        if (existsSync(configPath))
             return;
-        }
+        // Database-free install: in-memory backend => no AQE_MEMORY_PATH, set
+        // AQE_MEMORY_BACKEND=memory so the MCP server writes nothing to disk.
+        // Otherwise preserve the historical persistent SQLite path.
+        const environment = this.options.memoryBackend === 'memory'
+            ? { AQE_MEMORY_BACKEND: 'memory', AQE_V3_MODE: 'true' }
+            : { AQE_MEMORY_PATH: '.agentic-qe/memory.db', AQE_V3_MODE: 'true' };
         const config = {
+            $schema: 'https://opencode.ai/config.json',
             mcp: {
                 'agentic-qe': {
                     type: 'local',
-                    command: ['npx', 'agentic-qe', 'mcp'],
-                    environment: {
-                        AQE_MEMORY_PATH: '.agentic-qe/memory.db',
-                        AQE_V3_MODE: 'true',
-                    },
+                    // Use the dedicated `aqe-mcp` bin, which runs the MCP server bundle
+                    // directly. The `agentic-qe mcp` subcommand instead double-spawns the
+                    // server (stdio:'inherit'), which corrupts stdin delivery and makes
+                    // OpenCode's client fail with "Failed to get tools". A higher timeout
+                    // accommodates the server's subsystem boot.
+                    command: ['aqe-mcp'],
+                    environment,
+                    enabled: true,
+                    timeout: 60000,
                 },
             },
         };

package/dist/init/orchestrator.js

@@ -49,6 +49,7 @@ export class ModularInitOrchestrator {
                 wizardAnswers: options.wizardAnswers,
                 noGovernance: options.noGovernance,
                 noMcp: options.noMcp,
+                memoryBackend: options.memoryBackend,
             },
             config: {},
             enhancements: {

package/dist/init/phases/04-database.d.ts

@@ -29,6 +29,11 @@ export declare class DatabasePhase extends BasePhase<DatabaseResult> {
     readonly order = 40;
     readonly critical = true;
     readonly requiresPhases: readonly ["configuration"];
+    /**
+     * Database-free mode (`--no-database` / memoryBackend: 'memory'): skip the
+     * SQLite database entirely. Nothing is written under .agentic-qe/.
+     */
+    shouldRun(context: InitContext): Promise<boolean>;
     protected run(context: InitContext): Promise<DatabaseResult>;
 }
 //# sourceMappingURL=04-database.d.ts.map

package/dist/init/phases/04-database.js

@@ -26,6 +26,13 @@ export class DatabasePhase extends BasePhase {
     order = 40;
     critical = true;
     requiresPhases = ['configuration'];
+    /**
+     * Database-free mode (`--no-database` / memoryBackend: 'memory'): skip the
+     * SQLite database entirely. Nothing is written under .agentic-qe/.
+     */
+    async shouldRun(context) {
+        return context.options.memoryBackend !== 'memory';
+    }
     async run(context) {
         const { projectRoot } = context;
         // Issue #399 / ADR-090: warn on stale ./vectors.db cruft.

package/dist/init/phases/05-learning.js

@@ -16,6 +16,9 @@ export class LearningPhase extends BasePhase {
     critical = false;
     requiresPhases = ['database', 'configuration'];
     async shouldRun(context) {
+        // Database-free mode has no persistent store to seed patterns into.
+        if (context.options.memoryBackend === 'memory')
+            return false;
         const config = context.config;
         return config?.learning?.enabled ?? true;
     }

package/dist/init/phases/06-code-intelligence.js

@@ -84,6 +84,12 @@ export class CodeIntelligencePhase extends BasePhase {
      *     for the case where the corpus misses something in the wild.
      */
     async shouldRun(context) {
+        // Database-free mode: the knowledge graph is persisted to the SQLite DB,
+        // which does not exist here. Build it later with `aqe code index`.
+        if (context.options.memoryBackend === 'memory') {
+            context.services.log('  Code intelligence skipped (database-free mode)');
+            return false;
+        }
         const envSkip = process.env.AQE_SKIP_CODE_INDEX;
         if (envSkip === '1' || envSkip === 'true') {
             context.services.log('  Code intelligence skipped (AQE_SKIP_CODE_INDEX=1)');

package/dist/init/phases/09-assets.js

@@ -169,8 +169,12 @@ export class AssetsPhase extends BasePhase {
                 projectRoot,
                 installAgents: true,
                 installSkills: true,
-                installTools: true,
+                // AQE tool .ts files are not in OpenCode's tool() format and are
+                // redundant with the MCP server — never install them.
+                installTools: false,
                 overwrite: shouldOverwrite,
+                // Database-free install => MCP server configured to run in-memory.
+                memoryBackend: options.memoryBackend === 'memory' ? 'memory' : undefined,
             });
             const ocResult = await openCodeInstaller.install();
             openCodeAgents = ocResult.agentsInstalled.length;

package/dist/init/phases/10-workers.js

@@ -18,6 +18,10 @@ export class WorkersPhase extends BasePhase {
     critical = false;
     requiresPhases = ['configuration'];
     async shouldRun(context) {
+        // Background workers persist to the SQLite DB, which is absent in
+        // database-free mode.
+        if (context.options.memoryBackend === 'memory')
+            return false;
         const config = context.config;
         return config?.workers?.daemonAutoStart && (config?.workers?.enabled?.length ?? 0) > 0;
     }

package/dist/init/phases/12-verification.js

@@ -23,11 +23,13 @@ export class VerificationPhase extends BasePhase {
         const config = context.config;
         const { projectRoot } = context;
         const checks = [];
-        // Check database exists
+        // Database-free mode: there is no SQLite database to verify or write to.
+        const memOnly = context.options.memoryBackend === 'memory';
+        // Check database exists (in-memory mode has none — treated as satisfied).
         const dbPath = join(projectRoot, '.agentic-qe', 'memory.db');
         checks.push({
-            name: 'Database exists',
-            passed: existsSync(dbPath),
+            name: memOnly ? 'Database (in-memory mode)' : 'Database exists',
+            passed: memOnly || existsSync(dbPath),
         });
         // Check .agentic-qe directory
         checks.push({
@@ -42,8 +44,11 @@ export class VerificationPhase extends BasePhase {
             name: 'Config saved',
             passed: existsSync(configPath),
         });
-        // Write version marker
-        const versionWritten = await this.writeVersionToDb(config.version, projectRoot);
+        // Write version marker. Skipped in database-free mode — there is no
+        // memory.db; the version is still recorded in config.yaml above.
+        const versionWritten = memOnly
+            ? true
+            : await this.writeVersionToDb(config.version, projectRoot);
         checks.push({
             name: 'Version marker',
             passed: versionWritten,

package/dist/init/phases/phase-interface.d.ts

@@ -131,6 +131,12 @@ export interface InitOptions {
     noMcp?: boolean;
     /** @deprecated Use default behavior instead — MCP is now enabled by default */
     withMcp?: boolean;
+    /**
+     * Memory backend for this install. 'memory' => database-free: the SQLite
+     * database phase is skipped and any MCP config is written to run in-memory.
+     * Undefined preserves the default persistent backend. Set via `--no-database`.
+     */
+    memoryBackend?: 'memory' | 'sqlite' | 'agentdb' | 'hybrid';
 }
 /**
  * V2 installation detection result

package/dist/integrations/ruvector/rvf-native-adapter.js

@@ -368,6 +368,14 @@ export function openRvfStoreReadonly(path) {
 }
 /** Check whether the native binding is loadable on this platform */
 export function isRvfNativeAvailable() {
+    // Database-free mode (#534): report RVF as unavailable so every consumer
+    // (RVF pattern store, dual-writer, agent memory branches) takes its existing
+    // "no native RVF" degraded path and writes nothing to disk — no patterns.rvf,
+    // brain.rvf, or branches/*.rvf. This is the single central gate for all
+    // on-disk RVF stores.
+    if (process.env.AQE_MEMORY_BACKEND === 'memory') {
+        return false;
+    }
     return getNative() !== null;
 }
 //# sourceMappingURL=rvf-native-adapter.js.map

package/dist/integrations/ruvector/shared-rvf-dual-writer.js

@@ -50,6 +50,11 @@ export async function getSharedRvfDualWriter() {
             if (rvfMode === 'sqlite-only') {
                 return null;
             }
+            // Database-free mode (#534): no on-disk RVF store (brain.rvf). The unified
+            // DB is already in-memory, so there is nothing to dual-write to disk.
+            if (process.env.AQE_MEMORY_BACKEND === 'memory') {
+                return null;
+            }
             // Auto-detect native availability (dynamic import to avoid bundling .node files)
             const { isRvfNativeAvailable } = await import('./rvf-native-adapter.js');
             if (!isRvfNativeAvailable()) {