Projects and sessions — organizing your chats

Wavo chats are structured as Project > Session > Message. Project = shared instructions + color + memory facts (max 20 via MAX_PROJECT_MEMORY_FACTS) + files. Session = single conversation, favoritable + archivable + shareable (read permission default). Message = streaming UIMessage with feedback, follow-ups, tool calls. Backed by chat_session, chat_project, chat_session_share, chat_message Prisma models.

Who is this for

Anyone whose chat list has grown past 10 sessions. Especially: agencies (per-client projects), teams (shared sessions), or anyone working on multi-week initiatives.

The 3-level structure

Project (e.g. "ClientA")
  ├── Instructions: "Currency = USD, target ROAS = 3+, ignore brand campaigns"
  ├── Color: blue
  ├── Memory: 18 facts (LTV €350, top creative concept, etc.)
  ├── Files: brand-guide.pdf, target-personas.docx
  │
  ├── Session: "Weekly review — Mar 1"
  │   ├── Message 1 (user)
  │   ├── Message 2 (assistant, with tool calls)
  │   └── ...
  ├── Session: "Q1 strategy planning" (⭐ favorited)
  └── Session: "Old experiments" (archived)

Project (e.g. "ClientB")
  └── ...

Projects

Create a project

/chat → sidebar New Project → enter name + (optional) description, instructions, color.

Schema (chat_project model):

• name, description, instructions

• color (hex)

• memory_enabled (toggle)

• is_archived

• extracted_facts (JSON array, max 20)

• chat_count (count cache)

• files (related chat_project_file)

Project instructions

Custom system prompt addition. Applied to every session in this project.

Example: "Currency = USD. Target ROAS = 3+. Always cite tracker postback data (not Meta-native). Skip brand campaigns in analysis."

Wavo applies these as additional context when responding to messages in any session under this project.

Project memory (facts)

Wavo extracts facts during conversation + persists them per-project. Max 20 facts (MAX_PROJECT_MEMORY_FACTS).

Schema (project_memory_fact):

• fact_type (e.g. "client_target", "preferred_metric", "campaign_lesson")

• fact_key

• fact_value

• confidence (0..1)

• is_active (soft delete via opted_out_at)

Example facts:

• client_target: roas = 3

• preferred_metric: tracker_roas (not meta_roas)

• campaign_lesson: spring_sale_2026 worked best with lookalike audiences

Write roles (per ai-memory.service.ts): owner / admin / manager / mediabuyer.

When facts > 20: oldest / lowest-confidence may be evicted.

Manage memory

Per-user:

• GET /api/v1/ai-memory/facts — list

• POST /api/v1/ai-memory/facts — save fact manually

• GET /api/v1/ai-memory/preferences — get preferences

• PATCH /api/v1/ai-memory/preferences — update

Opt out:

• /settings → AI preferences → Memory toggle OFF

• Sets user_ai_preferences.memory_opted_out_at

• Existing facts not deleted; clear manually if desired

Project files

Upload to project (vs. one-off in a session) for persistent context:

• Brand guides

• Product specs

• Target personas

• Reference data

Wavo can reference uploaded files across sessions in the project. Same 10MB upload cap + MIME whitelist as session uploads (ai-103).

Sessions

Create a session

Implicit: open /chat + send first message → new session auto-created with title "New Chat" (auto-renamed after first turn).

Explicit: /chat → New Session within current project.

Session metadata

Schema (chat_session):

• title (auto or manual rename)

• project_id (parent)

• is_archived (hide from default list)

• is_favorite (⭐ pin to top)

• created_at, updated_at

Rename + favorite + archive

Per-session actions menu:

• Rename → PATCH session

• Favorite ⭐ → PATCH is_favorite: true

• Archive → PATCH is_archived: true (hides from main list)

• Delete → DELETE (permanent — message history removed)

Share a session

Per-session action menu → Share → enter teammate's email.

Schema (chat_session_share):

• session_id, shared_with_user_id

• permission (default read)

• Granted via POST /api/v1/chat/sessions/:id/share

Recipient sees the session in their Shared with me view. Read-only; no edits, no replies.

For collaborative editing: the recipient should fork the session (copy + start new) and continue from there.

List + search sessions

Sidebar shows:

• Favorited sessions (top, pinned)

• Recent sessions (chronological)

• Filter by project

• Archive filter (hide archived)

• Search by title or message content

Messages

Each session contains a sequence of messages (chat_message model):

• User messages

• Assistant messages (streamed UIMessage, may include tool calls + follow-up chips)

• Token usage tracked: token_usage_input, token_usage_output

• Cost tracked: credits_used

• Per-message feedback: feedback_rating (SmallInt -1..1), feedback_comment

User preferences (cross-project)

user_ai_preferences (per user, applies to all projects):

Edit at /settings → AI preferences.

User preferences are global; project instructions add per-project context on top.

Organizational patterns

Agency: per-client project

Project: ClientA
Project: ClientB
Project: ClientC (paused)
Project: Internal

Each project has client-specific instructions (currency, KPI targets, blacklist).

In-house: per-initiative

Project: Q1 launch
Project: Always-on optimization
Project: Brand campaigns
Project: Experiments

Solo: per-domain

Project: Analytics + reporting
Project: Creative + drafts
Project: Rules + automation

Pick a model + commit. Mixing models destroys findability.

When to start a new session vs project

Memory: when it shines + when it doesn't

Where memory helps

• "Last week we found audience X had the best ROAS" — Wavo remembers

• "My target ROAS is 3" — set once, applied across sessions

• "Don't suggest budget changes; that's manual review only" — preference persists

Where memory fails

• Memory > 20 facts: oldest evicted

• Cross-project: facts don't migrate

• Opt-out: facts not saved

• Conflicting facts: newer overrides (but accuracy depends on confidence)

Common mistakes

• Everything in one project: hard to find later; create per-client or per-initiative

• Never archive: list grows unbounded; archive after each closed initiative

• Forgetting to set project instructions: every session asks the same context questions

• Memory opt-out by accident: check /settings → AI preferences if Wavo "forgets" stuff

• Sharing sessions instead of forking: recipient is read-only; use fork for collaboration

Related

• Prompt tips — leverage project instructions

• Asking questions — context-aware prompting

• Feedback + improve — improve Wavo via feedback