moflo 4.8.19 → 4.8.20

package/.claude/guidance/shipped/moflo.md

@@ -31,6 +31,51 @@ npx flo doctor --fix  # Verify everything is working
 
 ---
 
+## Building from Source
+
+Moflo is a TypeScript monorepo using **project references** (`tsc -b`). The root `tsconfig.json` is a solution-style config that delegates to `src/tsconfig.json`, which references all 17 `@claude-flow/*` sub-packages.
+
+### Build Commands
+
+```bash
+npm run build          # Runs tsc -b (project references build)
+npm run build:ts       # Build @claude-flow/cli only (legacy shortcut)
+npm run build:guidance # Build @claude-flow/guidance only (legacy shortcut)
+```
+
+### Architecture
+
+```
+tsconfig.json              → Solution root (references src/)
+  src/tsconfig.json        → References all @claude-flow/* packages
+    src/tsconfig.base.json → Shared compilerOptions (ES2022, bundler, composite)
+    src/@claude-flow/shared/    → Base types (no deps)
+    src/@claude-flow/cli/       → CLI + MCP server (depends on shared, swarm)
+    src/@claude-flow/hooks/     → Hook system (depends on shared, neural, memory)
+    src/@claude-flow/memory/    → Memory backends (no deps)
+    src/@claude-flow/guidance/  → Guidance indexing (depends on hooks)
+    src/@claude-flow/testing/   → Regression tests (depends on shared, memory, swarm)
+    ... (17 packages total)
+```
+
+### Important Rules
+
+1. **Always build from root** — `npm run build` (which runs `tsc -b`) builds all packages in dependency order. Do NOT build individual packages in isolation unless you know what you're doing.
+2. **Never bypass the build** — The `dist/` directories contain compiled JS that ships with `npm publish`. If you edit `.ts` source, you MUST rebuild before publishing.
+3. **Do not work around build errors** — If `tsc -b` fails, fix the type errors. Do not manually compile individual packages to skip errors, as this leads to drift between source and compiled output.
+4. **Sub-packages need `composite: true`** — Every sub-package tsconfig must have `"composite": true` in compilerOptions for project references to work.
+5. **Cross-package imports need `paths`** — If package A imports from `@claude-flow/B`, package A's tsconfig needs both a `"references"` entry and a `"paths"` mapping pointing to B's source.
+
+### Publishing
+
+```bash
+npm version patch      # Bump version (auto-syncs cli sub-package version)
+npm run build          # MUST succeed with zero errors
+npm publish --otp=XXX  # Requires 2FA OTP
+```
+
+---
+
 ## Session Start Automation
 
 When a Claude Code session starts, moflo automatically runs three background indexers:

package/.claude/helpers/statusline.cjs

@@ -24,7 +24,7 @@ const CONFIG = {
   maxAgents: 15,
 };
 
-const CWD = process.cwd();
+const CWD = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 
 // Load status_line config from moflo.yaml (show/hide individual items)
 function loadStatusLineConfig() {

package/.claude/workflow-state.json

@@ -0,0 +1,9 @@
+{
+  "tasksCreated": true,
+  "taskCount": 4,
+  "memorySearched": true,
+  "memoryRequired": true,
+  "interactionCount": 6,
+  "sessionStart": null,
+  "lastBlockedAt": "2026-03-24T01:45:34.050Z"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.8.19",
+  "version": "4.8.20",
   "description": "MoFlo — AI agent orchestration for Claude Code. Forked from ruflo/claude-flow with patches applied to source, plus feature-level orchestration.",
   "main": "dist/index.js",
   "type": "module",
@@ -47,7 +47,7 @@
   ],
   "scripts": {
     "dev": "tsx watch src/index.ts",
-    "build": "tsc",
+    "build": "tsc -b",
     "build:ts": "cd src/@claude-flow/cli && npm run build || true",
     "build:guidance": "cd src/@claude-flow/guidance && npx tsc -p tsconfig.json || true",
     "prepublishOnly": "npm run build:ts && npm run build:guidance",

package/src/@claude-flow/cli/dist/src/init/statusline-generator.js

@@ -47,7 +47,7 @@ const CONFIG = {
   maxAgents: ${maxAgents},
 };
 
-const CWD = process.cwd();
+const CWD = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 
 // ANSI colors
 const c = {

package/src/@claude-flow/cli/dist/src/services/agentic-flow-bridge.js

@@ -7,9 +7,11 @@
  *
  * @module agentic-flow-bridge
  */
-// Suppress agentic-flow's agentdb-runtime-patch warning. The patch targets
-// agentdb v1.x (dist/controllers/) but v3+ uses dist/src/controllers/ and
-// already ships with correct .js extensions — the patch is unnecessary.
+// Suppress the agentic-flow agentdb-runtime-patch warning.
+// The patch targets agentdb v1.3.9 (dist/controllers/index.js) but
+// agentdb v3+ moved to dist/src/controllers/ and already ships with
+// correct .js extensions. The patch is unnecessary and prints a
+// confusing "[AgentDB Patch] Controller index not found" warning.
 if (typeof process !== 'undefined' && !process.env.SKIP_AGENTDB_PATCH) {
     process.env.SKIP_AGENTDB_PATCH = '1';
 }

package/src/@claude-flow/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moflo/cli",
-  "version": "4.8.19",
+  "version": "4.8.20",
   "type": "module",
   "description": "MoFlo CLI — AI agent orchestration with specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",

package/src/@claude-flow/memory/dist/agent-memory-scope.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Agent-Scoped Memory - Support for Claude Code's 3-scope agent memory directories
+ *
+ * Claude Code organizes agent memory into three scopes:
+ * - **project**: Shared across all collaborators (checked into git)
+ * - **local**: Machine-specific, not shared (gitignored)
+ * - **user**: Global per-user, spans all projects
+ *
+ * Each scope stores agent-specific memory in a named subdirectory,
+ * enabling isolated yet transferable knowledge between agents.
+ *
+ * @module @claude-flow/memory/agent-memory-scope
+ */
+import type { IMemoryBackend } from './types.js';
+import { AutoMemoryBridge } from './auto-memory-bridge.js';
+import type { AutoMemoryBridgeConfig, InsightCategory } from './auto-memory-bridge.js';
+/** Claude Code's 3-scope agent memory system */
+export type AgentMemoryScope = 'project' | 'local' | 'user';
+/** Configuration for agent-scoped memory bridge */
+export interface AgentScopedConfig extends AutoMemoryBridgeConfig {
+    /** Agent name (used in directory path) */
+    agentName: string;
+    /** Memory scope */
+    scope: AgentMemoryScope;
+}
+/** Options for knowledge transfer between agents */
+export interface TransferOptions {
+    /** Source namespace to transfer from */
+    sourceNamespace: string;
+    /** Minimum confidence to include (default: 0.8) */
+    minConfidence?: number;
+    /** Maximum entries to transfer (default: 20) */
+    maxEntries?: number;
+    /** Filter by categories */
+    categories?: InsightCategory[];
+}
+/** Result of a knowledge transfer */
+export interface TransferResult {
+    /** Number of entries transferred */
+    transferred: number;
+    /** Number of entries skipped (below threshold or duplicate) */
+    skipped: number;
+}
+/**
+ * Resolve the agent memory directory for a given agent name, scope, and working directory.
+ *
+ * Path resolution matches Claude Code binary behavior:
+ * ```
+ * project: <gitRoot>/.claude/agent-memory/<agentName>/
+ * local:   <gitRoot>/.claude/agent-memory-local/<agentName>/
+ * user:    ~/.claude/agent-memory/<agentName>/
+ * ```
+ *
+ * Agent names are sanitized to prevent path traversal attacks.
+ *
+ * @param agentName - The agent identifier
+ * @param scope - Memory scope: project, local, or user
+ * @param workingDir - Working directory for git root detection (defaults to cwd)
+ * @returns Absolute path to the agent's memory directory
+ */
+export declare function resolveAgentMemoryDir(agentName: string, scope: AgentMemoryScope, workingDir?: string): string;
+/**
+ * Create an AutoMemoryBridge configured for a specific agent scope.
+ *
+ * This is the primary factory for creating scoped bridges. It resolves
+ * the correct memory directory based on agent name and scope, then
+ * delegates to AutoMemoryBridge for the actual sync logic.
+ *
+ * @param backend - The AgentDB memory backend
+ * @param config - Agent-scoped configuration
+ * @returns A configured AutoMemoryBridge instance
+ *
+ * @example
+ * ```typescript
+ * const bridge = createAgentBridge(backend, {
+ *   agentName: 'coder',
+ *   scope: 'project',
+ *   syncMode: 'on-write',
+ * });
+ * await bridge.recordInsight({ ... });
+ * ```
+ */
+export declare function createAgentBridge(backend: IMemoryBackend, config: AgentScopedConfig): AutoMemoryBridge;
+/**
+ * Transfer knowledge from a source backend namespace into a target bridge.
+ *
+ * Queries high-confidence entries from the source and records them as
+ * insights in the target bridge. Useful for cross-agent knowledge sharing
+ * or promoting learnings from one scope to another.
+ *
+ * @param sourceBackend - Backend to query entries from
+ * @param targetBridge - Bridge to record insights into
+ * @param options - Transfer options (namespace, filters, limits)
+ * @returns Transfer result with counts of transferred and skipped entries
+ *
+ * @example
+ * ```typescript
+ * const result = await transferKnowledge(sourceBackend, targetBridge, {
+ *   sourceNamespace: 'learnings',
+ *   minConfidence: 0.9,
+ *   maxEntries: 10,
+ *   categories: ['architecture', 'security'],
+ * });
+ * console.log(`Transferred ${result.transferred}, skipped ${result.skipped}`);
+ * ```
+ */
+export declare function transferKnowledge(sourceBackend: IMemoryBackend, targetBridge: AutoMemoryBridge, options: TransferOptions): Promise<TransferResult>;
+/**
+ * List all agent scopes and their agents for the current project.
+ *
+ * Scans the three scope directories (project, local, user) and returns
+ * the agent names found in each. Useful for discovery and diagnostics.
+ *
+ * @param workingDir - Working directory for git root detection (defaults to cwd)
+ * @returns Array of scope/agents pairs
+ *
+ * @example
+ * ```typescript
+ * const scopes = listAgentScopes('/workspaces/my-project');
+ * // [
+ * //   { scope: 'project', agents: ['coder', 'tester'] },
+ * //   { scope: 'local', agents: ['researcher'] },
+ * //   { scope: 'user', agents: ['planner'] },
+ * // ]
+ * ```
+ */
+export declare function listAgentScopes(workingDir?: string): Array<{
+    scope: AgentMemoryScope;
+    agents: string[];
+}>;
+//# sourceMappingURL=agent-memory-scope.d.ts.map

package/src/@claude-flow/memory/dist/agent-memory-scope.js

@@ -0,0 +1,223 @@
+/**
+ * Agent-Scoped Memory - Support for Claude Code's 3-scope agent memory directories
+ *
+ * Claude Code organizes agent memory into three scopes:
+ * - **project**: Shared across all collaborators (checked into git)
+ * - **local**: Machine-specific, not shared (gitignored)
+ * - **user**: Global per-user, spans all projects
+ *
+ * Each scope stores agent-specific memory in a named subdirectory,
+ * enabling isolated yet transferable knowledge between agents.
+ *
+ * @module @claude-flow/memory/agent-memory-scope
+ */
+import * as path from 'node:path';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { AutoMemoryBridge } from './auto-memory-bridge.js';
+// ===== Internal Helpers =====
+/**
+ * Find the git root directory by walking up from a starting directory.
+ * Synchronous variant for path resolution (no async needed for stat checks).
+ */
+function findGitRootSync(dir) {
+    let current = path.resolve(dir);
+    const root = path.parse(current).root;
+    while (current !== root) {
+        if (existsSync(path.join(current, '.git'))) {
+            return current;
+        }
+        current = path.dirname(current);
+    }
+    return null;
+}
+/**
+ * List agent subdirectories inside a given directory.
+ * Returns an empty array if the directory does not exist or is unreadable.
+ */
+function listAgentsInDir(dir) {
+    if (!existsSync(dir))
+        return [];
+    try {
+        return readdirSync(dir).filter((name) => {
+            try {
+                return statSync(path.join(dir, name)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}
+// ===== Public Functions =====
+/**
+ * Resolve the agent memory directory for a given agent name, scope, and working directory.
+ *
+ * Path resolution matches Claude Code binary behavior:
+ * ```
+ * project: <gitRoot>/.claude/agent-memory/<agentName>/
+ * local:   <gitRoot>/.claude/agent-memory-local/<agentName>/
+ * user:    ~/.claude/agent-memory/<agentName>/
+ * ```
+ *
+ * Agent names are sanitized to prevent path traversal attacks.
+ *
+ * @param agentName - The agent identifier
+ * @param scope - Memory scope: project, local, or user
+ * @param workingDir - Working directory for git root detection (defaults to cwd)
+ * @returns Absolute path to the agent's memory directory
+ */
+export function resolveAgentMemoryDir(agentName, scope, workingDir) {
+    // Sanitize agent name to prevent path traversal
+    const safeName = agentName.replace(/[^a-zA-Z0-9_-]/g, '_');
+    if (scope === 'user') {
+        const home = process.env.HOME
+            || process.env.USERPROFILE
+            || (process.env.HOMEDRIVE && process.env.HOMEPATH ? process.env.HOMEDRIVE + process.env.HOMEPATH : '');
+        if (!home) {
+            throw new Error('Cannot determine home directory: HOME, USERPROFILE, and HOMEDRIVE+HOMEPATH are all undefined');
+        }
+        return path.join(home, '.claude', 'agent-memory', safeName);
+    }
+    // For project and local scopes, find git root
+    const effectiveDir = workingDir || process.cwd();
+    const gitRoot = findGitRootSync(effectiveDir);
+    const baseDir = gitRoot || effectiveDir;
+    if (scope === 'local') {
+        return path.join(baseDir, '.claude', 'agent-memory-local', safeName);
+    }
+    // scope === 'project'
+    return path.join(baseDir, '.claude', 'agent-memory', safeName);
+}
+/**
+ * Create an AutoMemoryBridge configured for a specific agent scope.
+ *
+ * This is the primary factory for creating scoped bridges. It resolves
+ * the correct memory directory based on agent name and scope, then
+ * delegates to AutoMemoryBridge for the actual sync logic.
+ *
+ * @param backend - The AgentDB memory backend
+ * @param config - Agent-scoped configuration
+ * @returns A configured AutoMemoryBridge instance
+ *
+ * @example
+ * ```typescript
+ * const bridge = createAgentBridge(backend, {
+ *   agentName: 'coder',
+ *   scope: 'project',
+ *   syncMode: 'on-write',
+ * });
+ * await bridge.recordInsight({ ... });
+ * ```
+ */
+export function createAgentBridge(backend, config) {
+    const memoryDir = resolveAgentMemoryDir(config.agentName, config.scope, config.workingDir);
+    return new AutoMemoryBridge(backend, {
+        ...config,
+        memoryDir,
+    });
+}
+/**
+ * Transfer knowledge from a source backend namespace into a target bridge.
+ *
+ * Queries high-confidence entries from the source and records them as
+ * insights in the target bridge. Useful for cross-agent knowledge sharing
+ * or promoting learnings from one scope to another.
+ *
+ * @param sourceBackend - Backend to query entries from
+ * @param targetBridge - Bridge to record insights into
+ * @param options - Transfer options (namespace, filters, limits)
+ * @returns Transfer result with counts of transferred and skipped entries
+ *
+ * @example
+ * ```typescript
+ * const result = await transferKnowledge(sourceBackend, targetBridge, {
+ *   sourceNamespace: 'learnings',
+ *   minConfidence: 0.9,
+ *   maxEntries: 10,
+ *   categories: ['architecture', 'security'],
+ * });
+ * console.log(`Transferred ${result.transferred}, skipped ${result.skipped}`);
+ * ```
+ */
+export async function transferKnowledge(sourceBackend, targetBridge, options) {
+    const { sourceNamespace, minConfidence = 0.8, maxEntries = 20, categories, } = options;
+    let transferred = 0;
+    let skipped = 0;
+    // Query high-confidence entries from source (fetch extra to allow for filtering)
+    const entries = await sourceBackend.query({
+        type: 'hybrid',
+        namespace: sourceNamespace,
+        tags: ['insight'],
+        limit: maxEntries * 2,
+    });
+    for (const entry of entries) {
+        if (transferred >= maxEntries)
+            break;
+        const confidence = entry.metadata?.confidence || 0;
+        if (confidence < minConfidence) {
+            skipped++;
+            continue;
+        }
+        // Filter by category if specified
+        const entryCategory = entry.metadata?.category;
+        if (categories &&
+            categories.length > 0 &&
+            entryCategory &&
+            !categories.includes(entryCategory)) {
+            skipped++;
+            continue;
+        }
+        // Record as insight in target bridge
+        const insight = {
+            category: entryCategory || 'project-patterns',
+            summary: entry.metadata?.summary || entry.content.split('\n')[0],
+            detail: entry.content,
+            source: `transfer:${sourceNamespace}`,
+            confidence,
+            agentDbId: entry.id,
+        };
+        await targetBridge.recordInsight(insight);
+        transferred++;
+    }
+    return { transferred, skipped };
+}
+/**
+ * List all agent scopes and their agents for the current project.
+ *
+ * Scans the three scope directories (project, local, user) and returns
+ * the agent names found in each. Useful for discovery and diagnostics.
+ *
+ * @param workingDir - Working directory for git root detection (defaults to cwd)
+ * @returns Array of scope/agents pairs
+ *
+ * @example
+ * ```typescript
+ * const scopes = listAgentScopes('/workspaces/my-project');
+ * // [
+ * //   { scope: 'project', agents: ['coder', 'tester'] },
+ * //   { scope: 'local', agents: ['researcher'] },
+ * //   { scope: 'user', agents: ['planner'] },
+ * // ]
+ * ```
+ */
+export function listAgentScopes(workingDir) {
+    const effectiveDir = workingDir || process.cwd();
+    const gitRoot = findGitRootSync(effectiveDir);
+    const baseDir = gitRoot || effectiveDir;
+    const home = process.env.HOME
+        || process.env.USERPROFILE
+        || (process.env.HOMEDRIVE && process.env.HOMEPATH ? process.env.HOMEDRIVE + process.env.HOMEPATH : '')
+        || '';
+    const projectDir = path.join(baseDir, '.claude', 'agent-memory');
+    const localDir = path.join(baseDir, '.claude', 'agent-memory-local');
+    const userDir = path.join(home, '.claude', 'agent-memory');
+    return [
+        { scope: 'project', agents: listAgentsInDir(projectDir) },
+        { scope: 'local', agents: listAgentsInDir(localDir) },
+        { scope: 'user', agents: listAgentsInDir(userDir) },
+    ];
+}
+//# sourceMappingURL=agent-memory-scope.js.map

package/src/@claude-flow/memory/dist/agent-memory-scope.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tests for Agent-Scoped Memory
+ *
+ * TDD London School (mock-first) tests for the 3-scope agent memory system.
+ * Uses vi.mock for ESM-compatible fs mocking.
+ */
+export {};
+//# sourceMappingURL=agent-memory-scope.test.d.ts.map