@claude-flow/memory 3.0.0-alpha.1 → 3.0.0-alpha.7

package/dist/agent-memory-scope.js

@@ -0,0 +1,215 @@
+/**
+ * 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 || '~';
+        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 || '~';
+    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/dist/agent-memory-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-memory-scope.js","sourceRoot":"","sources":["../src/agent-memory-scope.ts"],"names":[],"mappings":"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"}

package/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

package/dist/agent-memory-scope.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-memory-scope.test.d.ts","sourceRoot":"","sources":["../src/agent-memory-scope.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}