projects.md
1 --- 2 title: Projects 3 sidebar_position: 270 4 --- 5 6 # Projects 7 8 Projects are a powerful organizational feature in Agent Mesh that enable users to group related chat sessions, manage artifacts and maintain context across multiple conversations. They provide a workspace-like environment for managing AI interactions around specific topics, tasks, or domains. 9 10 :::tip[In one sentence] 11 Projects are organizational containers that group related chat sessions and knowledge artifacts together, enabling better context management and collaboration across multiple AI conversations. 12 ::: 13 14 ## Key Features 15 16 1. **Session Organization**: Group related chat sessions under a single project for better organization and context management. 17 18 2. **Knowledge Management**: Store and manage files, documents, and other artifacts that can be referenced across all sessions within a project. 19 20 3. **Custom Instructions**: Define project-specific instructions (system prompt) that apply to all chat sessions within the project, ensuring consistent AI behavior. 21 22 4. **Default Agent Configuration**: Set a default agent for the project, streamlining the chat creation process. 23 24 5. **Soft Delete**: Projects and sessions can be safely deleted with the ability to recover them if needed (logical delete). 25 26 6. **Search Capabilities**: Search chat titles within a project or across all projects to quickly find relevant conversations. 27 28 7. **Session Mobility**: Move chat sessions between projects to reorganize your work as needs evolve. 29 30 ## How Projects Work 31 32 Projects provide a hierarchical structure for organizing your AI interactions. Each project contains: 33 34 - **Project Metadata**: Name, description, system prompt, and default agent configuration 35 - **Chat Sessions**: Multiple conversation threads that inherit project settings 36 - **Project Knowledge**: Files and documents accessible across all sessions 37 38 ## Project Components 39 40 ### Project Metadata 41 42 Each project contains the following metadata: 43 44 - **Name**: A descriptive name for the project (required) 45 - **Description**: Optional detailed description of the project's purpose 46 - **System Prompt**: Custom instructions that apply to all chat sessions in the project 47 - **Default Agent**: The agent that will be used by default for new sessions in this project 48 - **Created/Updated Timestamps**: Automatic tracking of project creation and modification times 49 50 ### Chat Sessions 51 52 Projects can contain multiple chat sessions, each representing a separate conversation thread. Sessions within a project: 53 54 - Inherit the project's instructions (if defined) 55 - Use the project's default agent (if specified) 56 - Can access project-level artifacts 57 - Can be moved between projects 58 - Can be searched and filtered 59 60 ### Knowledge (Artifacts) 61 62 Projects support two types of knowledge artifacts: 63 64 1. **Project-Level Knowledge**: Files attached to the project itself (shown in the "Knowledge" section), accessible by all sessions 65 2. **Session-Level Artifacts**: Files attached to specific chat sessions within the project 66 67 Knowledge artifacts can include: 68 - Documents (PDF, DOCX, TXT, MD) 69 - Images (PNG, JPG, GIF) 70 - Code files 71 - Data files (JSON, CSV, YAML) 72 - Any other file type supported by the system 73 74 ## Configuration 75 76 ### Disabling Projects 77 78 Projects require SQL database persistence to function. Configure persistence in your `shared_config.yaml`: 79 80 ```yaml 81 session_service: 82 type: sql 83 database_url: "sqlite:///./data/sessions.db" 84 ``` 85 86 Projects are enabled by default when persistence is configured. To disable the feature: 87 88 ```yaml 89 # Disable projects explicitly 90 projects: 91 enabled: false 92 ``` 93 94 ### Feature Flag Control 95 96 You can also control projects via feature flags: 97 98 ```yaml 99 frontend_feature_enablement: 100 projects: false # Disable projects 101 taskLogging: true 102 ``` 103 104 :::note[Configuration Priority] 105 The feature flag resolution follows this priority: 106 1. **Persistence Check**: If persistence is disabled, projects are disabled (non-negotiable) 107 2. **Explicit Config**: `projects.enabled` setting 108 3. **Feature Flag**: `frontend_feature_enablement.projects` setting 109 4. **Default**: Enabled (if persistence is enabled and no explicit disable) 110 ::: 111 112 ### Soft Delete Pattern 113 114 Projects and sessions use a soft delete pattern for data preservation: 115 116 - Deleted items are marked with `deleted_at` timestamp 117 - Deleted items are automatically filtered from queries 118 - Data remains in database for audit trails 119 - Can be recovered if needed 120 121 ## Best Practices 122 123 ### Project Organization 124 125 1. **Use Descriptive Names**: Give projects clear, descriptive names that reflect their purpose 126 2. **Define Instructions**: Set project-specific instructions (system prompts) to ensure consistent AI behavior 127 3. **Organize by Topic**: Group related conversations under the same project 128 4. **Regular Cleanup**: Periodically review and delete unused projects 129 130 ### Knowledge Management 131 132 1. **Upload Relevant Files**: Only upload files that are relevant to the project in the Knowledge section 133 2. **Use Metadata**: Add descriptions to knowledge artifacts for better organization 134 3. **File Naming**: Use clear, descriptive filenames 135 4. **Size Considerations**: Be mindful of file sizes for performance 136 137 ### Session Management 138 139 1. **Move Sessions**: Reorganize sessions between projects as needs evolve 140 2. **Use Search**: Leverage search to find relevant conversations quickly 141 3. **Delete Unused Sessions**: Clean up old or irrelevant sessions 142 4. **Consistent Naming**: Use clear session names for easier searching 143 144 ## Troubleshooting 145 146 ### Projects Not Visible 147 148 If projects are not showing up in the UI: 149 150 1. **Check Persistence Configuration**: 151 ```yaml 152 session_service: 153 type: sql # Must be 'sql', not 'memory' 154 ``` 155 156 2. **Check if Projects are Explicitly Disabled**: 157 ```yaml 158 projects: 159 enabled: false # Remove this line or set to true 160 ``` 161 162 3. **Check Feature Flags**: 163 ```yaml 164 frontend_feature_enablement: 165 projects: true # Should be true or omitted 166 ``` 167 168 4. **Verify Config Endpoint**: 169 ```bash 170 curl http://localhost:8000/api/v1/config | jq '.frontend_feature_enablement.projects' 171 ``` 172 173 ### API Returns 501 Error 174 175 When project endpoints return 501 Not Implemented: 176 177 - **Persistence disabled**: Configure `session_service.type: sql` 178 - **Explicitly disabled**: Remove `projects.enabled: false` or set to `true` 179 - **Feature flag disabled**: Set `frontend_feature_enablement.projects: true` 180 181 182 ## Performance Considerations 183 184 ### Database Optimization 185 186 - **Indexes**: Projects use indexes on `user_id`, `deleted_at`, and search columns 187 - **Eager Loading**: Related data is loaded efficiently to prevent N+1 queries 188 - **Pagination**: Search results are paginated to handle large datasets 189 190 ### Artifact Storage 191 192 Project artifacts use the configured artifact store. See [Configurations - Artifact Service](../installing-and-configuring/configurations.md#artifact-service) for more details. 193 194 ## Security 195 196 ### Authorization 197 198 - All project operations validate user ownership 199 - Sessions can only be moved to projects owned by the user 200 - Knowledge artifacts are scoped to user and project/session context 201 202 ### Data Privacy 203 204 - Soft-deleted data remains in database (consider retention policies) 205 - User ID tracked for all operations 206 - Consider implementing hard delete for GDPR compliance 207 208 ## Related Documentation 209 210 - [Gateways](./gateways.md) - Learn about gateway configuration 211 - [Agents](./agents.md) - Configure agents for your projects