@framers/agentos 0.1.0

package/dist/core/agency/AgencyMemoryManager.d.ts

@@ -0,0 +1,300 @@
+/**
+ * @file AgencyMemoryManager.ts
+ * @description Manages shared RAG memory for Agency (multi-GMI) collectives.
+ * Enables GMIs within an agency to share context, collaborate effectively,
+ * and maintain collective memory across conversations.
+ *
+ * @module AgentOS/Agency
+ * @version 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const memoryManager = new AgencyMemoryManager(vectorStoreManager, logger);
+ *
+ * // Initialize shared memory for an agency
+ * await memoryManager.initializeAgencyMemory(agencySession);
+ *
+ * // Ingest document to shared memory
+ * await memoryManager.ingestToSharedMemory(agencyId, {
+ *   content: 'Important context from GMI-1',
+ *   contributorGmiId: 'gmi-1',
+ *   contributorRoleId: 'researcher',
+ * });
+ *
+ * // Query shared memory
+ * const results = await memoryManager.querySharedMemory(agencyId, {
+ *   query: 'What did the researcher find?',
+ *   requestingGmiId: 'gmi-2',
+ *   requestingRoleId: 'analyst',
+ * });
+ * ```
+ */
+import type { ILogger } from '../../logging/ILogger';
+import type { IVectorStoreManager } from '../../rag/IVectorStoreManager';
+import type { AgencySession, AgencyMemoryConfig, AgencyMemoryOperationResult, AgencyMemoryQueryOptions } from './AgencyTypes';
+/**
+ * Input for ingesting documents to agency shared memory.
+ */
+export interface AgencyMemoryIngestInput {
+    /** Document content */
+    content: string;
+    /** GMI that contributed this content */
+    contributorGmiId: string;
+    /** Role of the contributing GMI */
+    contributorRoleId: string;
+    /** Document category */
+    category?: 'communication' | 'finding' | 'decision' | 'summary' | 'context';
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /** Optional pre-computed embedding */
+    embedding?: number[];
+}
+/**
+ * Retrieved chunk from agency shared memory.
+ */
+export interface AgencyMemoryChunk {
+    /** Chunk ID */
+    chunkId: string;
+    /** Document ID */
+    documentId: string;
+    /** Content text */
+    content: string;
+    /** Similarity score */
+    score: number;
+    /** Contributing GMI */
+    contributorGmiId: string;
+    /** Contributing role */
+    contributorRoleId: string;
+    /** Document category */
+    category: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of querying agency shared memory.
+ */
+export interface AgencyMemoryQueryResult {
+    /** Whether query succeeded */
+    success: boolean;
+    /** Retrieved chunks */
+    chunks: AgencyMemoryChunk[];
+    /** Total matching results */
+    totalResults: number;
+    /** Query processing time in ms */
+    processingTimeMs: number;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Statistics for agency memory.
+ */
+export interface AgencyMemoryStats {
+    /** Total documents in shared memory */
+    totalDocuments: number;
+    /** Total chunks */
+    totalChunks: number;
+    /** Documents by role */
+    documentsByRole: Record<string, number>;
+    /** Documents by category */
+    documentsByCategory: Record<string, number>;
+    /** Last ingestion timestamp */
+    lastIngestionAt?: string;
+}
+/**
+ * Manages shared RAG memory for Agency collectives.
+ *
+ * @remarks
+ * This manager provides:
+ * - Initialization of dedicated data sources for agencies
+ * - Ingestion with role-based access control
+ * - Cross-GMI context queries with permission checks
+ * - Memory lifecycle management (retention, eviction)
+ *
+ * Architecture:
+ * ```
+ * AgencyMemoryManager
+ *         │
+ *         ├─► VectorStoreManager (storage backend)
+ *         │
+ *         ├─► AgencyRegistry (session state)
+ *         │
+ *         └─► Per-Agency Collections
+ *              └─► agency-{agencyId}-shared
+ * ```
+ */
+export declare class AgencyMemoryManager {
+    private readonly vectorStoreManager;
+    private readonly logger?;
+    /** Collection name prefix for agency shared memory */
+    private static readonly COLLECTION_PREFIX;
+    /** Default memory configuration */
+    private static readonly DEFAULT_CONFIG;
+    /** Tracks initialized agencies */
+    private readonly initializedAgencies;
+    /**
+     * Creates a new AgencyMemoryManager instance.
+     *
+     * @param vectorStoreManager - Vector store manager for RAG operations
+     * @param logger - Optional logger for diagnostics
+     */
+    constructor(vectorStoreManager: IVectorStoreManager | null, logger?: ILogger | undefined);
+    /**
+     * Initializes shared memory for an agency.
+     * Creates dedicated collection and applies configuration.
+     *
+     * @param session - Agency session to initialize memory for
+     * @returns Operation result
+     */
+    initializeAgencyMemory(session: AgencySession): Promise<AgencyMemoryOperationResult>;
+    /**
+     * Ingests a document to agency shared memory.
+     *
+     * @param agencyId - Target agency
+     * @param input - Document to ingest
+     * @param config - Agency memory configuration
+     * @returns Operation result
+     */
+    ingestToSharedMemory(agencyId: string, input: AgencyMemoryIngestInput, config?: AgencyMemoryConfig): Promise<AgencyMemoryOperationResult>;
+    /**
+     * Queries agency shared memory.
+     *
+     * @param agencyId - Target agency
+     * @param options - Query options
+     * @param config - Agency memory configuration
+     * @returns Query result with retrieved chunks
+     */
+    querySharedMemory(agencyId: string, options: AgencyMemoryQueryOptions, config?: AgencyMemoryConfig): Promise<AgencyMemoryQueryResult>;
+    /**
+     * Gets statistics for agency shared memory.
+     *
+     * @param agencyId - Target agency
+     * @returns Memory statistics
+     */
+    getStats(agencyId: string): Promise<AgencyMemoryStats | null>;
+    /**
+     * Cleans up agency memory when agency is removed.
+     *
+     * @param agencyId - Agency to clean up
+     * @returns Operation result
+     */
+    cleanupAgencyMemory(agencyId: string): Promise<AgencyMemoryOperationResult>;
+    /**
+     * Gets the collection ID for an agency's shared memory.
+     */
+    private getCollectionId;
+    /**
+     * Resolves configuration with defaults.
+     */
+    private resolveConfig;
+    /**
+     * Checks if agency memory is initialized.
+     */
+    isInitialized(agencyId: string): boolean;
+    /**
+     * Broadcasts context from one GMI to all others in the agency.
+     * This is useful for sharing discoveries, decisions, or important updates.
+     *
+     * @param agencyId - Target agency
+     * @param input - Broadcast input
+     * @param config - Agency memory configuration
+     * @returns Operation result with broadcast metadata
+     *
+     * @example
+     * ```typescript
+     * await memoryManager.broadcastToAgency(agencyId, {
+     *   content: 'Found critical security vulnerability in auth module',
+     *   senderGmiId: 'security-analyst-gmi',
+     *   senderRoleId: 'security-analyst',
+     *   broadcastType: 'finding',
+     *   priority: 'high',
+     * });
+     * ```
+     */
+    broadcastToAgency(agencyId: string, input: {
+        content: string;
+        senderGmiId: string;
+        senderRoleId: string;
+        broadcastType: 'finding' | 'decision' | 'update' | 'request' | 'alert';
+        priority?: 'low' | 'normal' | 'high' | 'critical';
+        targetRoles?: string[];
+        metadata?: Record<string, unknown>;
+    }, config?: AgencyMemoryConfig): Promise<AgencyMemoryOperationResult>;
+    /**
+     * Gets recent context contributions from specific roles.
+     * Enables GMIs to selectively query context from collaborators.
+     *
+     * @param agencyId - Target agency
+     * @param options - Query options with role filtering
+     * @param config - Agency memory configuration
+     * @returns Query result filtered by contributor roles
+     *
+     * @example
+     * ```typescript
+     * // Get recent findings from the researcher role
+     * const findings = await memoryManager.getContextFromRoles(agencyId, {
+     *   fromRoles: ['researcher', 'analyst'],
+     *   categories: ['finding', 'summary'],
+     *   requestingGmiId: 'coordinator-gmi',
+     *   requestingRoleId: 'coordinator',
+     *   limit: 10,
+     * });
+     * ```
+     */
+    getContextFromRoles(agencyId: string, options: {
+        fromRoles: string[];
+        categories?: ('communication' | 'finding' | 'decision' | 'summary' | 'context')[];
+        requestingGmiId: string;
+        requestingRoleId: string;
+        limit?: number;
+        minScore?: number;
+    }, config?: AgencyMemoryConfig): Promise<AgencyMemoryQueryResult>;
+    /**
+     * Shares a synthesis or summary across all GMIs in the agency.
+     * Typically used by coordinator or synthesizer roles.
+     *
+     * @param agencyId - Target agency
+     * @param summary - Summary content and metadata
+     * @param config - Agency memory configuration
+     * @returns Operation result
+     */
+    shareSynthesis(agencyId: string, summary: {
+        content: string;
+        synthesizerId: string;
+        synthesizerRoleId: string;
+        sourceRoles?: string[];
+        summaryType: 'interim' | 'final' | 'action_items' | 'consensus';
+        metadata?: Record<string, unknown>;
+    }, config?: AgencyMemoryConfig): Promise<AgencyMemoryOperationResult>;
+    /**
+     * Records a decision made by the agency for future reference.
+     *
+     * @param agencyId - Target agency
+     * @param decision - Decision details
+     * @param config - Agency memory configuration
+     * @returns Operation result
+     */
+    recordDecision(agencyId: string, decision: {
+        content: string;
+        decisionMakerId: string;
+        decisionMakerRoleId: string;
+        decisionType: 'consensus' | 'delegation' | 'escalation' | 'resolution';
+        affectedRoles?: string[];
+        rationale?: string;
+        metadata?: Record<string, unknown>;
+    }, config?: AgencyMemoryConfig): Promise<AgencyMemoryOperationResult>;
+    /**
+     * Gets all decisions made by the agency.
+     *
+     * @param agencyId - Target agency
+     * @param options - Query options
+     * @param config - Agency memory configuration
+     * @returns Query result with decision chunks
+     */
+    getDecisions(agencyId: string, options: {
+        requestingGmiId: string;
+        requestingRoleId: string;
+        decisionTypes?: ('consensus' | 'delegation' | 'escalation' | 'resolution')[];
+        limit?: number;
+    }, config?: AgencyMemoryConfig): Promise<AgencyMemoryQueryResult>;
+}
+//# sourceMappingURL=AgencyMemoryManager.d.ts.map

package/dist/core/agency/AgencyMemoryManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgencyMemoryManager.d.ts","sourceRoot":"","sources":["../../../src/core/agency/AgencyMemoryManager.ts"],"names":[],"mappings":"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"}