Projects and sessions — organizing your chats

3-level structure: Project > Session > Message. Project shares instructions + memory facts (max 20). Sessions favoritable + shareable (read default).

Written By Salvatore Sinigaglia

Last updated About 5 hours ago

3-level structure: Project > Session > Message. Project shares instructions + memory facts (max 20). Sessions favoritable + shareable (read default).

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):

FieldWhat
instructionsUser-level custom instructions
preferred_languageDefault auto
preferred_modelDefault per workspace
toneBrief / detailed / analytical
response_formatMarkdown / plain / structured
metricsPriority KPI list
currencyDisplay currency
memory_enabledToggle
memory_opted_out_atTimestamp

Edit at /settings → AI preferences.

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

Organizational patterns

Agency: per-client project

Project: ClientAProject: ClientBProject: ClientC (paused)Project: Internal

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

In-house: per-initiative

Project: Q1 launchProject: Always-on optimizationProject: Brand campaignsProject: Experiments

Solo: per-domain

Project: Analytics + reportingProject: Creative + draftsProject: Rules + automation

Pick a model + commit. Mixing models destroys findability.

When to start a new session vs project

ScenarioAction
Different clientNew project
Different initiative for same clientNew session in same project
Different topic mid-conversationNew session in same project
Multi-week recurring (weekly review)One session per week, same project
One-off questionQuick chat in default / "scratch" 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

FAQ

How are Wavo chats organized?

Wavo chats in Wevion use a three-level structure: Project > Session > Message. A Project holds shared instructions, a color, memory facts, and files. A Session is a single conversation that can be favorited, archived, and shared. A Message is one streaming turn with feedback, follow-ups, and tool calls. These map to the chat_project, chat_session, and chat_message models.

How many memory facts can a Wavo project store?

A Wevion project holds a maximum of 20 memory facts, set by MAX_PROJECT_MEMORY_FACTS. Wavo extracts facts during conversation, such as a client target ROAS or a preferred metric, and persists them per project. When facts exceed 20, the oldest or lowest-confidence facts may be evicted. Facts do not migrate between projects.

What happens when I share a Wavo session?

Sharing a session grants read permission by default. From a session's action menu, choose Share and enter a teammate's email; the recipient sees it in their Shared with me view. It is read-only, so they cannot edit or reply. For collaborative work, the recipient should fork the session, copy and start new, then continue from there.

When should I start a new project instead of a new session?

Create a new project for a different client, and a new session for a different initiative or topic within the same client. Project instructions apply client-specific context like currency and KPI targets to every session inside them, so agencies use a project per client while in-house teams often use a project per initiative.

How do I stop Wavo from remembering facts?

Turn memory off in Wevion's AI preferences. Go to Settings, then AI preferences, and toggle Memory off; this sets user_ai_preferences.memory_opted_out_at and stops new facts from being saved for you. Existing facts are not deleted automatically, so clear them manually via DELETE /api/v1/ai-memory/facts if you want them gone.