docs: merge the two getting-started pages and update the workspaces guide (P2.4)
docs/GETTING-STARTED.md and docs/guides/getting-started.md covered the same ground; keep one guide in docs/guides that follows the current setup flow, the two model paths, memory on mem0 and the real keyboard shortcuts. Drop the product tiers, the signed-Windows-only install, the .mind files, install.sh and the external coding-agent sign-in. The workspaces guide loses team workspaces, the .mind files, FTS5 search and the knowledge graph, and describes virtual and local storage, the shipped personas and what deleting a workspace removes.
This commit is contained in:
@@ -1,97 +0,0 @@
|
||||
# Getting Started with Waggle
|
||||
|
||||
Welcome to Waggle — your AI operating system with persistent memory.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Install Waggle for Windows
|
||||
|
||||
Use only the signed Windows Solo `.exe` installer and SHA-256 identified by a **GO** [launch recommendation](production-readiness/09-LAUNCH_RECOMMENDATION.md). If that recommendation is not GO, no packaged desktop artifact is release-approved; use the source-development instructions in the repository instead. macOS desktop packaging and certification remain roadmap work.
|
||||
|
||||
Run the installer and launch Waggle. The Windows Solo release contract does not require developer Node.js, Docker, Python, LiteLLM, administrator access, or a separate Ollama installation.
|
||||
|
||||
### 2. Connect a model
|
||||
|
||||
The first-launch wizard offers two supported paths:
|
||||
|
||||
- **Private local model:** open **Local model**, choose **Install private runtime**, then download and verify the recommended model. Waggle keeps the managed runtime and model in its private data directory; no system Ollama or Docker installation is required.
|
||||
- **Cloud provider:** open **API key**, choose a provider, and paste your own provider API key. Waggle validates it live when the provider is reachable, labels any unverified result, and stores it encrypted in Vault.
|
||||
|
||||
At least one working local model or cloud provider is needed for chat. You can choose **I'll do this later**, but chat remains unavailable until a model is configured.
|
||||
|
||||
External coding-agent authentication is separate from Waggle's model setup. Install each supported client yourself and use its own sign-in flow: Claude Code (`claude auth login --claudeai`), Codex (`codex login`), and Hermes' built-in provider OAuth (`hermes auth add openai-codex --type oauth`). Waggle uses the client's existing user session; do not paste or copy those credentials into Waggle.
|
||||
|
||||
### 3. Create Your First Workspace
|
||||
- Choose a template (Sales, Research, Legal, etc.) or start blank
|
||||
- Pick a persona (Researcher, Writer, Analyst, etc.)
|
||||
- Name your workspace
|
||||
|
||||
### 4. Start Working
|
||||
Type anything in the chat. Your agent can:
|
||||
- Search the web (works immediately, no setup)
|
||||
- Create Word documents with professional formatting
|
||||
- Read and write files in your workspace
|
||||
- Run shell commands (sandboxed)
|
||||
- Run 15 workflow commands (type `/` to see them)
|
||||
- Remember everything across sessions
|
||||
|
||||
### 5. The Memory Magic
|
||||
After your first conversation, try closing and reopening the workspace.
|
||||
Type: "What do you remember about our discussion?"
|
||||
Your agent remembers everything — decisions, context, preferences.
|
||||
|
||||
## Key Features
|
||||
|
||||
### Workflow Commands
|
||||
Type `/` in chat to see all commands:
|
||||
- `/research [topic]` — deep web research with synthesis
|
||||
- `/draft [type]` — create documents with professional formatting
|
||||
- `/plan [goal]` — structured planning with steps
|
||||
- `/catchup` — get a summary of where things stand
|
||||
- `/decide [question]` — structured decision analysis
|
||||
- `/review [topic]` — review work or documents
|
||||
- `/spawn [task]` — delegate work to a sub-agent
|
||||
- `/skills` — browse and install new capabilities
|
||||
- `/status` — workspace health and statistics
|
||||
- `/memory` — explore what your agent remembers
|
||||
- `/focus` — set the current work focus
|
||||
- `/now` — quick workspace snapshot
|
||||
- `/help` — see all available commands
|
||||
|
||||
### Personas
|
||||
Press `Ctrl+Shift+P` to switch personas. Each changes how your agent thinks:
|
||||
- **Researcher**: deep investigation with citations
|
||||
- **Writer**: document creation with formatting
|
||||
- **Analyst**: data analysis with structured output
|
||||
- **Planner**: project planning and task breakdown
|
||||
- ...and more
|
||||
|
||||
### Keyboard Shortcuts
|
||||
- `Ctrl+K` — search everything
|
||||
- `Ctrl+Shift+1` through `Ctrl+Shift+7` — switch views
|
||||
- `Ctrl+Shift+P` — switch persona
|
||||
- `/` — workflow commands
|
||||
|
||||
### Memory View
|
||||
Press `Ctrl+Shift+5` to browse everything your agent remembers.
|
||||
Search, filter by type, and explore the knowledge graph.
|
||||
|
||||
### Workspace Home
|
||||
When you open a workspace, you see the "Workspace Now" overview:
|
||||
- A summary of where things stand
|
||||
- Recent decisions and open items
|
||||
- Recent conversation threads
|
||||
- Key memories
|
||||
|
||||
Once you start chatting, click the **Workspace Overview** toggle above the messages to return to this view at any time.
|
||||
|
||||
## Product Scopes
|
||||
|
||||
Waggle uses four product tiers:
|
||||
- **Trial** — 15 days of the Team experience, then Solo
|
||||
- **Solo (Free)** — personal productivity with persistent memory
|
||||
- **Team** — shared workspaces, WaggleDance, and governance
|
||||
- **Enterprise** — sovereign KVARK deployment, compliance, and audit trails
|
||||
|
||||
## Need Help?
|
||||
Type `/help` in chat for a full command reference.
|
||||
@@ -1,211 +1,131 @@
|
||||
# Getting Started with Waggle
|
||||
# Getting started
|
||||
|
||||
This guide walks you through installing Waggle, configuring your API key, creating your first workspace, having your first conversation, and understanding how memory works.
|
||||
This guide takes you from a fresh install to your first conversation, and explains how Waggle
|
||||
remembers things between chats.
|
||||
|
||||
## Prerequisites
|
||||
## 1. Install
|
||||
|
||||
- **Node.js 20+** (for local server and CLI)
|
||||
- **An LLM API key** (Anthropic recommended; OpenAI, Google, and 100+ others supported)
|
||||
- **Rust toolchain** (only if building the desktop app from source)
|
||||
Install the desktop app or the server installer as described in [install.md](../install.md). Then
|
||||
open Waggle: start the desktop app, or run `waggle-server`, which opens
|
||||
http://localhost:3333 in your browser.
|
||||
|
||||
## Installation
|
||||
## 2. Go through the setup
|
||||
|
||||
### Option 1: One-line self-host (Linux / macOS)
|
||||
The first launch walks you through a short setup:
|
||||
|
||||
Best for a VPS or homelab, where you want a headless server rather than the desktop app:
|
||||
1. **Who are you**: your name, role and the kind of work you do. Waggle keeps this in your profile
|
||||
on this computer and uses it to tailor answers.
|
||||
2. **Model**: add a model (next section). You can skip this, but chat stays unavailable until a
|
||||
model is set up.
|
||||
3. **Pick a starting point**: a template for your first workspace, such as Research Hub, Sales
|
||||
Pipeline, Engineering or Legal & Compliance, or **Blank Workspace**. Each template comes with a
|
||||
matching persona.
|
||||
4. **What's first?**: type a first task for the agent, or pick a suggestion.
|
||||
|
||||
```bash
|
||||
curl -fsSL <repository-raw-url>/main/install.sh | bash # the public repository location is not decided yet
|
||||
```
|
||||
## 3. Connect a model
|
||||
|
||||
The installer checks prerequisites (Node.js 20+, git — no sudo), clones the repo, builds the packages and web UI, then starts the sidecar and prints its URL (`http://127.0.0.1:3333`). A short wizard (all Enter-defaulted) lets you change the install dir, port, and data dir; add `--yes` to accept every default non-interactively. It boots in echo mode with zero API keys, so the UI works right away — add a provider key later under **Settings → API Keys**.
|
||||
Waggle needs at least one working model. Choose one of two ways, in the setup or later in
|
||||
**Settings** → **Models**:
|
||||
|
||||
Manage the server afterward with `scripts/waggle-server.sh {start|stop|status|logs}`. Windows users should use the desktop app (Option 2) — the one-line installer targets Linux and macOS only.
|
||||
- **API key**: choose a provider (Anthropic, OpenAI, Google, DeepSeek, xAI, Mistral, Alibaba
|
||||
Qwen, MiniMax, Zhipu GLM, Moonshot Kimi, Perplexity or OpenRouter) and paste your key. Waggle
|
||||
checks it with the provider when it can reach it, and stores it encrypted in the **Vault** on
|
||||
this computer.
|
||||
- **Local model**: choose **Install private runtime**. Waggle downloads the official Ollama
|
||||
runtime, checks it and runs it from its own data directory. Then download a model; Waggle
|
||||
suggests one that fits your computer. No separate Ollama install, Docker or administrator
|
||||
rights are needed. If you already run Ollama, Waggle finds it.
|
||||
|
||||
### Option 2: Desktop App (Recommended)
|
||||
In **Settings** → **Models** you also choose the default model, a fallback model and an optional
|
||||
daily budget.
|
||||
|
||||
Download the latest release for your platform from the repository's Releases page (the public repository location is not decided yet).
|
||||
## 4. Your first conversation
|
||||
|
||||
**Windows**: Run the `.msi` installer. Waggle appears in your Start menu.
|
||||
Type in the chat. The agent streams its answer, and you see what it does along the way:
|
||||
|
||||
**macOS**: Open the `.dmg` and drag Waggle to Applications.
|
||||
- **Tool steps**, such as reading a file, searching the web or saving a memory.
|
||||
- **Approval requests** for actions that change something outside the chat, such as writing a
|
||||
file or sending a message. The agent waits until you approve or deny. Settings →
|
||||
**Permissions** sets how often Waggle asks.
|
||||
- **Memory**: when you tell the agent something worth keeping, it saves it.
|
||||
|
||||
The desktop app bundles a Node.js sidecar that runs the local server automatically.
|
||||
Good first messages:
|
||||
|
||||
### Option 3: CLI / Web
|
||||
|
||||
If you prefer a browser-based interface or want to run Waggle without the desktop shell:
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone <repository-url> waggle
|
||||
cd waggle
|
||||
npm install
|
||||
|
||||
# Start the local server
|
||||
cd packages/server
|
||||
npx tsx src/local/start.ts
|
||||
```
|
||||
|
||||
The server starts on http://localhost:3333. Open it in any browser.
|
||||
|
||||
### Option 4: CLI REPL
|
||||
|
||||
For a terminal-native experience:
|
||||
|
||||
```bash
|
||||
cd packages/cli
|
||||
npx tsx src/index.ts
|
||||
```
|
||||
|
||||
## Step 1: Add Your API Key
|
||||
|
||||
Waggle needs at least one LLM provider key to function. Anthropic (Claude) is recommended.
|
||||
|
||||
### Desktop / Web UI
|
||||
|
||||
1. Open **Settings** (gear icon in the sidebar or press `Ctrl+,`)
|
||||
2. Go to the **Models** tab
|
||||
3. Click **Add Provider**
|
||||
4. Select **Anthropic** and paste your API key (starts with `sk-ant-`)
|
||||
5. Click **Save**
|
||||
|
||||
Your key is stored in the local vault (AES-256-GCM encrypted), never sent to Waggle's servers.
|
||||
|
||||
### CLI / Config File
|
||||
|
||||
Edit `~/.waggle/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"defaultModel": "claude-sonnet-4-6",
|
||||
"providers": {
|
||||
"anthropic": {
|
||||
"apiKey": "sk-ant-your-key-here",
|
||||
"models": ["claude-sonnet-4-6", "claude-haiku-3"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Verify Your Key
|
||||
|
||||
In Settings > Models, click **Test Key**. A green checkmark means you are ready.
|
||||
|
||||
## Step 2: Create Your First Workspace
|
||||
|
||||
Workspaces are the core organizational unit in Waggle. Each workspace has its own memory, sessions, files, and context. Think of a workspace as a dedicated brain for a project or topic.
|
||||
|
||||
1. Press **Ctrl+N** or click **New Workspace** in the sidebar
|
||||
2. Enter a name (e.g., "Product Research" or "Q1 Planning")
|
||||
3. Choose a group (e.g., "Work", "Personal", "Learning")
|
||||
4. Optionally select a persona (Researcher, Writer, Coder, etc.)
|
||||
5. Optionally link a directory on disk for file-aware operations
|
||||
6. Click **Create**
|
||||
|
||||
You land on the **Workspace Home** screen. It shows a summary, suggested prompts, and recent threads.
|
||||
|
||||
## Step 3: Your First Conversation
|
||||
|
||||
Type a message in the input area. Here are good first messages:
|
||||
|
||||
- "Tell me about this project so I can remember it"
|
||||
- "Help me think through what to work on first"
|
||||
- "Here is what this project is about: …"
|
||||
- "Help me plan what to work on first."
|
||||
- "What can you do in this workspace?"
|
||||
|
||||
The agent responds with streaming output. You will see:
|
||||
### Slash commands
|
||||
|
||||
- **Tool calls** shown as collapsible cards (file reads, web searches, memory saves)
|
||||
- **Memory saves** happening automatically when the agent learns something important
|
||||
- **Approval gates** for sensitive operations (the agent asks before executing risky actions)
|
||||
Type `/` in the chat to see the commands, for example `/catchup` for a summary of where the
|
||||
workspace stands, `/research <topic>`, `/draft <type> [topic]` or `/plan <goal>`. `/help` lists
|
||||
them all; the [commands reference](../reference/commands.md) describes each one.
|
||||
|
||||
### Try a Slash Command
|
||||
### Files
|
||||
|
||||
Type `/catchup` to get a workspace restart summary. Type `/help` to see all 14 commands.
|
||||
Attach a file to the chat to let the agent read it: PDF, Word (`.docx`), PowerPoint (`.pptx`),
|
||||
Excel (`.xlsx`), CSV, images, ZIP archives and text or code files, up to 10 MB each.
|
||||
|
||||
### Upload a File
|
||||
## 5. How memory works
|
||||
|
||||
Click the paperclip icon or drag a file into the chat. Waggle supports:
|
||||
Waggle keeps two kinds of memory, both on your computer:
|
||||
|
||||
- **Documents**: PDF, DOCX, PPTX
|
||||
- **Spreadsheets**: XLSX, CSV
|
||||
- **Images**: PNG, JPG, GIF, WebP, SVG
|
||||
- **Code**: Any text-based source file
|
||||
- **Archives**: ZIP (lists contents)
|
||||
- **Personal memory** follows you across all workspaces: who you are, your preferences, facts
|
||||
that are not tied to one project.
|
||||
- **Workspace memory** belongs to one workspace: decisions, findings and project context.
|
||||
|
||||
Files are ingested into workspace memory and available to the agent.
|
||||
Before it answers, the agent recalls what is relevant from personal memory and the current
|
||||
workspace. Memories get there in three ways:
|
||||
|
||||
## Step 4: Understanding Memory
|
||||
- **You ask**: "Remember that we chose PostgreSQL for the new service."
|
||||
- **The agent decides** something is worth keeping and saves it.
|
||||
- **Background extraction**: every few messages, Waggle picks out facts about you, such as your
|
||||
role or how you like answers, and saves them to personal memory. Turn this off in **Settings**
|
||||
→ **General** → **Memory**.
|
||||
|
||||
Memory is a core product primitive, not a side feature. Two memory layers work together:
|
||||
Open **Memory** to browse, search, correct, confirm or forget memories. `/memory <query>` searches
|
||||
from the chat. More detail: [memory.md](../memory.md).
|
||||
|
||||
### Personal Mind (`~/.waggle/default.mind`)
|
||||
## 6. Come back later
|
||||
|
||||
Your personal knowledge base. Facts about you, your preferences, recurring context. Shared across all workspaces.
|
||||
When you return to a workspace:
|
||||
|
||||
### Workspace Mind (`~/.waggle/workspaces/{id}/workspace.mind`)
|
||||
- **Home** shows recent activity and suggests where to continue;
|
||||
- `/catchup` gives a briefing on where the workspace stands;
|
||||
- your earlier chats are listed in the workspace, ready to resume;
|
||||
- the agent recalls the workspace's memory before its first answer.
|
||||
|
||||
Project-specific memory. Decisions, research findings, architectural choices, meeting notes. Scoped to one workspace.
|
||||
## Personas
|
||||
|
||||
### How Memory Works
|
||||
A persona tunes how the agent works: its instructions, preferred tools and suggested commands.
|
||||
Waggle ships with personas such as Researcher, Writer, Analyst, Coder, Project Manager, Executive
|
||||
Assistant, Marketer, Legal Counsel and General Purpose. Press `Ctrl+Shift+P` (`Cmd+Shift+P` on
|
||||
macOS) to switch. See [workspaces.md](workspaces.md#personas).
|
||||
|
||||
1. **Auto-save**: The agent automatically saves important information during conversations -- decisions, facts, preferences, and findings.
|
||||
2. **Explicit save**: You can say "Remember that we decided to use PostgreSQL" and the agent writes it to the appropriate mind.
|
||||
3. **Memory search**: The agent searches memory before responding, giving you continuity across sessions.
|
||||
4. **Memory browser**: Open the Memory tab in any workspace to browse, search, and manage stored frames.
|
||||
## Interface levels
|
||||
|
||||
### Memory Frames
|
||||
**Settings** → **General** offers three interface levels: **Essential**, **Standard** and
|
||||
**Everything**. Essential shows the basics (Home, Chat, Memory, Files, Vault, Settings).
|
||||
Everything adds agents, skills, connectors, the marketplace, automations and the system tools.
|
||||
|
||||
Each memory unit is a "frame" with:
|
||||
- **Content**: The actual information
|
||||
- **Importance**: critical, important, normal, temporary
|
||||
- **Frame type**: Information (I), Decision (D), Preference (P), etc.
|
||||
- **Timestamp**: When it was created
|
||||
- **Access count**: How often it has been retrieved
|
||||
## Keyboard shortcuts
|
||||
|
||||
## Step 5: Return Tomorrow
|
||||
|
||||
When you come back to a workspace, Waggle gives you an instant catch-up:
|
||||
|
||||
1. **Workspace Home** shows a summary of what happened, recent decisions, and suggested next prompts
|
||||
2. **Type `/catchup`** for a detailed briefing
|
||||
3. **Resume a thread** by clicking any recent session in the sidebar
|
||||
4. **Context is automatic** -- the agent loads relevant memory before its first response
|
||||
|
||||
This is the core daily-use loop:
|
||||
|
||||
> Open workspace -> instant context -> real work help -> memory-first response -> visible progress -> return later without losing thread
|
||||
|
||||
## Next Steps
|
||||
|
||||
- **[Workspaces Guide](workspaces.md)** -- Workspace types, switching, home screen, personas
|
||||
- **[Capabilities Guide](capabilities.md)** -- Install skill packs and browse the marketplace
|
||||
- **[Connectors Guide](connectors.md)** -- Connect GitHub, Slack, Google, and 26 other services
|
||||
- **[Commands Reference](../reference/commands.md)** -- All 14 slash commands with examples
|
||||
- **[Team Mode Guide](team-mode.md)** -- Set up shared workspaces for your team
|
||||
|
||||
## File Locations
|
||||
|
||||
| Item | Path |
|
||||
|------|------|
|
||||
| Config | `~/.waggle/config.json` |
|
||||
| Personal mind | `~/.waggle/default.mind` |
|
||||
| Workspace minds | `~/.waggle/workspaces/{id}/workspace.mind` |
|
||||
| Session logs | `~/.waggle/workspaces/{id}/sessions/*.jsonl` |
|
||||
| Installed skills | `~/.waggle/skills/*.md` |
|
||||
| Installed plugins | `~/.waggle/plugins/` |
|
||||
| Marketplace DB | `~/.waggle/marketplace.db` |
|
||||
| Vault (encrypted) | `~/.waggle/vault.db` |
|
||||
| Server logs | Console output (stdout) |
|
||||
|
||||
## Keyboard Shortcuts
|
||||
On macOS use `Cmd` instead of `Ctrl`.
|
||||
|
||||
| Shortcut | Action |
|
||||
|----------|--------|
|
||||
| `Ctrl+N` | New workspace |
|
||||
| `Ctrl+,` | Settings |
|
||||
| `Ctrl+K` | Quick switch workspace |
|
||||
| `Ctrl+Shift+M` | Toggle memory browser |
|
||||
| `Enter` | Send message |
|
||||
| `Shift+Enter` | Newline in message |
|
||||
| `/` | Start slash command |
|
||||
|---|---|
|
||||
| `Ctrl+K` | Search everything |
|
||||
| `Ctrl+Shift+P` | Switch persona |
|
||||
| `Ctrl+Tab` | Switch workspace |
|
||||
| `Ctrl+Shift+N` | Open the chat of the active workspace |
|
||||
| `Ctrl+/` or `?` | Show all shortcuts |
|
||||
| `Enter` / `Shift+Enter` | Send / new line |
|
||||
| `Ctrl+Shift+W` | Show or hide the desktop app window (desktop app only) |
|
||||
|
||||
## Next steps
|
||||
|
||||
- [Workspaces](workspaces.md): workspaces, sessions, personas and folders on disk
|
||||
- [Skills, plugins and the marketplace](capabilities.md)
|
||||
- [Connectors and channels](connectors.md)
|
||||
- [Troubleshooting](troubleshooting.md)
|
||||
- [Where your data lives](../install.md#where-your-data-lives)
|
||||
|
||||
@@ -1,149 +1,74 @@
|
||||
# Workspaces
|
||||
|
||||
Workspaces are the core organizational unit in Waggle. Each workspace is a dedicated brain for a project, topic, or area of work. It has its own memory, sessions, files, tasks, and optionally a linked directory on disk.
|
||||
A workspace holds one project or area of work: its chats, its files, its memory and the persona
|
||||
the agent uses there. Your personal memory is shared by all workspaces; everything else stays in
|
||||
its workspace.
|
||||
|
||||
## Creating a Workspace
|
||||
## Creating a workspace
|
||||
|
||||
Press **Ctrl+N** or click **New Workspace** in the sidebar.
|
||||
Create a workspace from **Home** or the workspace list. You choose:
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| Name | Yes | Display name (e.g., "Q1 Planning", "Product Research") |
|
||||
| Group | Yes | Category for sidebar grouping (e.g., "Work", "Personal") |
|
||||
| Icon | No | Emoji or character for visual identification |
|
||||
| Model | No | Override the default LLM model for this workspace |
|
||||
| Persona | No | Assign a specialized agent persona |
|
||||
| Directory | No | Link a folder on disk for file-aware operations |
|
||||
| Field | Description |
|
||||
|---|---|
|
||||
| Name | "What project or area is this for?", for example "Acme Client" or "Q3 Launch" |
|
||||
| Template | Optional. A starting setup with a matching persona, such as Research Hub or Engineering |
|
||||
| Group | A category for grouping workspaces in the list, such as Work or Personal |
|
||||
| Storage type | **Virtual**: Waggle keeps the workspace's files in its data directory. **Local**: the workspace uses a folder on your disk |
|
||||
| Agent | Optional. The persona to use in this workspace |
|
||||
|
||||
When you create your first workspace, Waggle auto-installs the starter skills (draft-memo, research-synthesis, extract-actions, etc.) if they are not already present.
|
||||
The first setup creates your first workspace from the template you pick.
|
||||
|
||||
## Workspace Types
|
||||
## Storage: virtual or a folder on disk
|
||||
|
||||
### Personal Workspaces
|
||||
- **Virtual** workspaces keep their files in `<data>/workspaces/<id>/files`.
|
||||
- **Local** workspaces point at a folder you choose. The agent's file tools (read, write, edit,
|
||||
search) work in that folder, and its git tools work on the repository there. Writes go
|
||||
through the approval rules in Settings → Permissions. Shell commands run with your user's
|
||||
rights and are not sandboxed; see the [threat model](../../THREAT_MODEL.md).
|
||||
|
||||
Created locally, stored on your machine. Memory lives in `~/.waggle/workspaces/{id}/workspace.mind`. Only you can access them.
|
||||
## Chats (sessions)
|
||||
|
||||
### Team Workspaces
|
||||
Each conversation in a workspace is a session. Sessions are stored as JSON Lines files in
|
||||
`<data>/workspaces/<id>/sessions/`.
|
||||
|
||||
Linked to a team server. Created from the Team panel after connecting to a team server. Team workspaces support:
|
||||
|
||||
- Shared memory that syncs between team members
|
||||
- Task boards visible to the whole team
|
||||
- Real-time presence (who is online, who is typing)
|
||||
- Admin-governed capability policies
|
||||
|
||||
A workspace's team status is indicated by a team badge in the sidebar.
|
||||
|
||||
## Workspace Home Screen
|
||||
|
||||
When you open a workspace, you see the Home screen with:
|
||||
|
||||
1. **Summary** -- a narrative description of what this workspace is about, how many memories and sessions it has, and when it was last active.
|
||||
2. **Recent Decisions** -- key decisions extracted from your conversation history.
|
||||
3. **Recent Threads** -- your last 5 sessions, clickable to resume.
|
||||
4. **Suggested Prompts** -- contextual suggestions based on workspace state:
|
||||
- New workspace: "Tell me about this project", "What can you do?"
|
||||
- Returning workspace: "Catch me up", "Continue: [last thread]", "What should I do next?"
|
||||
5. **Progress Items** -- tasks, completions, and blockers extracted from sessions.
|
||||
6. **Stats** -- memory count, session count, file count.
|
||||
|
||||
The Home screen is never a blank chat. It always gives you a reason to engage.
|
||||
|
||||
## Sessions
|
||||
|
||||
Each conversation thread is a **session**. Sessions are stored as `.jsonl` files in `~/.waggle/workspaces/{id}/sessions/`.
|
||||
|
||||
### Creating Sessions
|
||||
|
||||
- Click the **+** button in the sidebar to start a new session
|
||||
- Or just start typing -- a session is created automatically
|
||||
|
||||
### Session Metadata
|
||||
|
||||
Each session has:
|
||||
- **Title** -- derived from the first user message, or set manually
|
||||
- **Summary** -- auto-generated after 4+ messages (heuristic, no LLM needed)
|
||||
- **Outcome** -- what changed, open items, next step (extracted at session end)
|
||||
|
||||
### Renaming Sessions
|
||||
|
||||
Click the session title in the sidebar and type a new name, or use the `PATCH /api/sessions/:id` endpoint.
|
||||
|
||||
### Searching Across Sessions
|
||||
|
||||
Use the search bar in the sidebar to find messages across all sessions in the current workspace. Matches show snippets with context.
|
||||
|
||||
### Exporting Sessions
|
||||
|
||||
Right-click a session and choose **Export as Markdown** to get a clean document with timestamps and formatted messages.
|
||||
|
||||
## Switching Workspaces
|
||||
|
||||
- Click any workspace in the left sidebar
|
||||
- Press **Ctrl+K** for the quick-switch dialog
|
||||
- Workspaces are grouped by their category (Work, Personal, etc.)
|
||||
|
||||
Each workspace in the sidebar shows a hue-colored dot for visual differentiation.
|
||||
- Start a new chat from the workspace, or just type: a session is created on the first message.
|
||||
- A session is titled from its first message; you can rename it.
|
||||
- Search finds messages across the sessions of the current workspace.
|
||||
- A session can be exported as Markdown.
|
||||
|
||||
## Personas
|
||||
|
||||
Personas are specialized agent configurations. Assigning a persona to a workspace tunes the agent's behavior without changing the core capabilities.
|
||||
A persona sets how the agent works in a workspace: its instructions, the tools it prefers, the
|
||||
commands it suggests and, for some, a default workflow. Waggle ships with 22 personas: General
|
||||
Purpose, Researcher, Writer, Analyst, Coder, Planner, Verifier, Coordinator, Project Manager,
|
||||
Senior PM, Executive Assistant, Sales Rep, Marketer, Customer Support, Operations Manager, Data
|
||||
Engineer, HR Manager, Recruiter, Legal Counsel, Business Finance, Strategy Consultant and
|
||||
Creative Director.
|
||||
|
||||
| Persona | Focus | Default Workflow |
|
||||
|---------|-------|-----------------|
|
||||
| Researcher | Deep investigation, multi-source synthesis | research-team |
|
||||
| Writer | Document drafting, editing, tone adaptation | -- |
|
||||
| Coder | Software development, debugging, code review | -- |
|
||||
| Analyst | Data analysis, decision matrices, pattern recognition | -- |
|
||||
| Project Manager | Task tracking, status reports, planning | plan-execute |
|
||||
| Executive Assistant | Email drafting, meeting prep, correspondence | -- |
|
||||
| Sales Rep | Lead research, outreach, pipeline management | research-team |
|
||||
| Marketer | Content creation, campaign planning, SEO | -- |
|
||||
Switch the persona with `Ctrl+Shift+P` (`Cmd+Shift+P` on macOS). Some personas are read-only:
|
||||
they cannot use tools that write. You can also create your own agents in **Agents** (at the
|
||||
Everything interface level).
|
||||
|
||||
### Changing Persona
|
||||
## Workspace memory
|
||||
|
||||
Open workspace settings (gear icon on the workspace home) and select a different persona. The change takes effect on the next message.
|
||||
Each workspace has its own memory, separate from your personal memory:
|
||||
|
||||
### Persona Tool Presets
|
||||
- **Workspace memory** holds project context: decisions, findings, notes.
|
||||
- **Personal memory** holds what is true across workspaces: your preferences, your role,
|
||||
recurring facts.
|
||||
|
||||
Each persona has a curated tool set. The Coder persona enables git tools; the Researcher enables web search; the Executive Assistant enables document generation. All tools remain available -- the persona just adjusts defaults and suggestions.
|
||||
In a workspace the agent reads both. It does not read other workspaces' memory unless you ask
|
||||
it to search all workspaces (`/search-all <query>`). See [memory.md](../memory.md).
|
||||
|
||||
## Directory Association
|
||||
Open **Memory** to browse, search, correct, confirm or forget memories.
|
||||
|
||||
Linking a workspace to a directory on disk enables:
|
||||
## Switching workspaces
|
||||
|
||||
- `read_file`, `write_file`, `edit_file` operate relative to the linked directory
|
||||
- `search_files` and `search_content` scan the directory tree
|
||||
- `git_status`, `git_diff`, `git_log`, `git_commit` work on the repo in that directory
|
||||
- File listings appear in the workspace context
|
||||
- Pick a workspace from **Home** or the workspace list.
|
||||
- `Ctrl+Tab` opens the workspace switcher; `Ctrl+K` searches everything, workspaces included.
|
||||
|
||||
To link a directory, set it during workspace creation or update it in workspace settings.
|
||||
## Deleting a workspace
|
||||
|
||||
## Workspace Memory
|
||||
|
||||
Each workspace has its own `.mind` database separate from your personal mind.
|
||||
|
||||
- **Workspace mind** stores project-specific context: decisions, research, architecture choices
|
||||
- **Personal mind** stores cross-workspace knowledge: your preferences, name, recurring facts
|
||||
|
||||
When the agent searches memory, it queries both minds and merges results, prioritizing workspace-specific memories when relevant.
|
||||
|
||||
### Memory Browser
|
||||
|
||||
Click the **Memory** tab in the right panel to browse all frames in the current workspace. You can:
|
||||
|
||||
- Search by keyword (FTS5 full-text search)
|
||||
- Filter by importance level
|
||||
- View the knowledge graph of entities and relationships
|
||||
- Delete outdated or incorrect frames
|
||||
|
||||
## Deleting a Workspace
|
||||
|
||||
Right-click a workspace in the sidebar and choose **Delete**. This removes:
|
||||
|
||||
- The workspace entry from the workspace list
|
||||
- Session files
|
||||
- The workspace `.mind` file
|
||||
- Task and file registry data
|
||||
|
||||
Personal mind memories are not affected.
|
||||
Deleting a workspace removes its memory, its sessions and its virtual files
|
||||
(`<data>/workspaces/<id>/`). A folder on disk linked as Local storage is not deleted. Personal
|
||||
memory is not affected.
|
||||
|
||||
Reference in New Issue
Block a user