131 lines
4.9 KiB
TypeScript
131 lines
4.9 KiB
TypeScript
/**
|
|
* 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
|