Each project is an isolated workspace with its own RAG index, chat history, agent rules, tasks, and file context. Switch between client engagements or work streams without any context bleed.
Every project maintains its own LlamaIndex vector store partition. Documents indexed in Project A are not retrievable in Project B's chat sessions. This means the agent's answers in a client engagement are grounded in that client's documents only — no cross-contamination from other projects regardless of how similarly their topics overlap.
Conversations are stored with a project_id foreign key in the Conversation and Message SQLAlchemy models. Switching to a different project shows that project's conversation history. Sessions from other projects don't appear in the sidebar or contribute to the context of the current session.
Assign one or more system prompts (Rules) to a project. When you chat within that project, the assigned rules are prepended to every system prompt automatically. A client project can have a rule that enforces tone, domain constraints, and confidentiality requirements without you having to set the system prompt manually on every conversation.
Tasks, uploaded files, and generated outputs can all be associated with a project. The llx projects info command gives a complete overview: active tasks, indexed documents, recent chat sessions, assigned rules, and file count. The llx projects command group handles create, list, delete, and switch operations from the terminal.
Without project scoping, every document you index, every chat you have, and every rule you set lives in a global context. As your use of Guaardvark grows — multiple client engagements, personal and professional work, different topic domains — that global pool becomes noisy. A question about a healthcare client's records might retrieve context from an unrelated software project. An agent rule set for one client might bleed into another client's sessions. Projects solve this by making the database-level scope explicit: every entity that supports it carries a project_id, and the application layer filters on it throughout.
The Project SQLAlchemy model is one of the core entities in backend/models.py. It provides the foreign-key anchor that associates Conversation, Message, File, Document, Task, Job, and Rule assignment records with a specific workspace. The projects_api.py blueprint exposes full CRUD at /api/projects/, and the projectService module in the React frontend manages the active project in the Zustand useAppStore global state. When you switch projects in the UI, every surface — chat sidebar, document list, file browser, task panel — re-renders against the new project scope.
The llx CLI provides full project management from the terminal: llx projects list shows all projects with document and conversation counts, llx projects create "Client Name" creates a new project and sets it as active, and llx chat "prompt" always runs in the context of the currently active project. This makes it straightforward to automate project-scoped workflows from scripts: create a project, upload documents, run a generation job, and retrieve outputs, all scoped to that project without manual UI interaction.
Data model. The Project model in backend/models.py is the central organising entity. Client organisations are represented by the related Client model, which includes SEO fields for WordPress-integrated content workflows. The ProjectDetailPage React component renders a project dashboard showing linked clients, active agent, assigned rules, document count, and recent conversation list. Project creation is idempotent — passing the same name twice returns the existing project rather than creating a duplicate — so automation scripts can use project creation as a safe "get or create" operation.
RAG scoping. The LlamaIndex vector store is partitioned by project via namespace support in the unified_index_manager.py. Indexing a document under a project writes its embeddings into the project's namespace; retrieval queries are automatically restricted to that namespace by the hybrid_rag_pipeline.py when a project context is active. This means two projects can index documents with identical content and retrieve them independently without namespace collisions. The advanced_retrieval_strategies.py reranking, MMR, and HyDE strategies all operate within the project namespace boundary.
# Terminal workflow: create project, upload docs, chat
llx projects create "Acme Corp Q3 Analysis"
llx files upload acme_financials.pdf
llx files upload acme_strategy_doc.md
llx chat "Summarise the key risks from the financial documents"
# List all projects with stats
llx projects list
# Get full project info
llx projects info "Acme Corp Q3 Analysis"Create one project per client. Upload their contracts, briefs, and reference materials. Assign a client-specific rule that instructs the agent on tone and confidentiality. All chat sessions, generated outputs, and task records for that client are isolated in their project — you can switch between four active client engagements and the agent never confuses one client's context with another's.
Maintain separate projects for personal and professional work. Your professional project has your work documents indexed and a formal tone rule; your personal project has your notes, reading list, and a casual tone. Switching between them is a single dropdown selection, and the agent's knowledge and behaviour shifts accordingly without any manual configuration change.
Create a project for a research topic you're investigating over weeks or months. Upload papers as you find them, run chat sessions to extract insights, create sticky notes for ideas, and let the RAG index grow incrementally. The project accumulates a knowledge base that becomes progressively more useful the longer you work in it — without interfering with any other work you're doing in other projects simultaneously.
Most local AI tools operate with a single global context: one RAG index, one conversation history, one set of active documents. As usage grows, this becomes a liability — retrieval noise increases, irrelevant context bleeds into answers, and there's no clean way to separate work by domain or client. Guaardvark Projects provide database-level isolation from the ground up: the project ID is a first-class column on every relevant entity, enforced at the query layer rather than achieved through naming conventions or manual filtering. The CLI supports the same project API as the UI, so automation and manual work share identical scoping semantics.
There is no limit. Projects are rows in the SQLite database, so storage is the only practical constraint. Each project's RAG index partition is stored as a subdirectory in data/cache/. For very large numbers of projects with large document sets, an SSD with ample free space is recommended, but dozens to hundreds of projects are well within normal operating parameters.
Yes via the Files API. A document's project_id can be updated through the document management endpoints. Moving a document re-indexes its embeddings into the destination project's vector store namespace and removes them from the source namespace. The operation is performed as a background task to handle large document re-indexing gracefully.
Yes. When you initiate a generation job while a project is active, the job record is created with the project's ID and the output files are linked to that project. In the Content Library you can filter by project to see only the outputs generated in that context. Generated outputs from other projects don't appear in the current project's library view.
Not directly — model selection is a global setting. However, you can assign a Rule to a project that specifies a preferred model in its system prompt instructions, and agents can be configured to use specific models. The planned per-project model override is on the roadmap for a future release.
Full system backup via backup_service.py includes all projects and their associated documents, chat history, and output metadata. Project-level selective export (a single project's data without the rest of the system) is on the roadmap. For now, the CLI's llx files and llx chat --export commands provide per-project data extraction.