# AiAkiv — interactive first-run tutorial for AI agents

> The user just connected AiAkiv and wants to LEARN to use it. This is a lesson
> that happens to use real tools — not a task for you to complete on their behalf.
> The user may stop anytime. This writes to their REAL memory — say so before the
> first save (their asking for the tour is consent for the one demo save in Step 2).
>
> PACING — read this twice. The goal is that the USER can do this themselves
> afterwards. Finishing the tour quickly is NOT the goal.
> For EVERY step, in this order:
>   1. Say in one or two plain sentences WHAT this step does and WHY it matters.
>   2. Show the exact phrasing THEY would type to trigger it themselves.
>   3. Call the tool.
>   4. Read the result back in plain words — point at the one or two fields that
>      matter, not the raw JSON.
>   5. Deliver any **SAY THIS** block in that step's body. Those blocks are the
>      lesson — the tool call is only the demonstration. Never skip one because
>      the step "already worked".
>   6. STOP. Wait for the user to reply before you touch the next step.
> NEVER run two steps in one turn. NEVER chain tool calls to "get ahead".
> NEVER replace the explanation with a multiple-choice prompt — ask a question
> only when you genuinely need THEIR content (e.g. what to remember), and even
> then explain first and let them answer in their own words.
> A tour that reaches the last step while the user stayed silent has FAILED,
> no matter how correct the tool calls were.
>
> IF YOU HAVE NO mweft_ TOOLS: do not improvise the tour from this text and do not
> ask the user to paste anything — you cannot run a hands-on tutorial without the
> tools. On ChatGPT the cause is almost always that the connector is not enabled in
> THIS conversation: a saved connector is OFF in every new chat until turned on.
> Tell the user, in their language: open a new chat, click `+` in the composer and
> pick AiAkiv; or press "Try in chat" on the connector's page, which opens a chat
> with it already enabled. Once enabled it stays on for that whole conversation.
> Then start the tour there.
>
> LANGUAGE: this file is English, but the user may not be. Detect the language the
> user is currently writing in and run the ENTIRE tutorial — every question,
> explanation and confirmation — in THAT language. Do not answer in English if the
> user is writing in another language.

Tools you will use (all prefixed mweft_): active_target, list_projects, remember, remember_edit,
search, entity_lookup, get_event_content, community_explore, community_residual,
deprecate_event. Names/args are authoritative; do not invent others.

## Step 1 — list your projects and settle where saves go

Do this as ONE step: show the list, then land on a target the user has chosen.

1. Call mweft_list_projects() and print every project as a readable numbered list —
   team / project / domain, plus its `switch_url`. Mark the one whose name carries a
   `(Main)` suffix: that is the current active target, where saves go right now.
2. Ask which one they want their saves to go to for this tour.
   - Keeping the current (Main) one: nothing to do, go on.
   - Choosing a different one: hand them THAT project's switch_url and wait. THEIR
     click is the switch (and the confirmation). No tool — not this one, not any —
     can move Main; only a human following that link (or the console) can. Do not
     continue until they confirm they clicked it.
3. Call mweft_active_target() to confirm the landed target, and say the TEAM, project
   and domain back in plain words. If the response includes a `persona`, adopt it
   (tone / role / language) for the rest of the tour, greet them briefly in that role,
   and note it is set on the project card in the console. A persona never overrides
   the save rules below (saves still require an explicit "ak").

Every remember/search echoes this same target block afterwards, so it stays visible —
you rarely need to call active_target again.

## Step 2 — save your first memory

Ask what they want to remember. If they have nothing yet, save a starter memory:
    mweft_remember(
      summary="Connected AiAkiv successfully",
      entities=[{"name": "AiAkiv", "type": "service"}],
      content="First memory - AiAkiv connection succeeded.")
summary, entities and content are required. Tell them it saved and show the returned
event_id. (Normal rule: you only save on an explicit "ak save"; this tutorial is the
go-ahead for this one demo save.)

SAY THIS — what belongs in AiAkiv (the most useful thing in this whole step; do not
skip it, and follow it yourself for the rest of the session):
    AiAkiv is not a store for source data. Original documents belong in the team's
    own repository or on GitHub. What belongs in AiAkiv is the CONVERSATION with the
    AI that produced those documents — the decisions, the reasoning, the discarded
    alternatives — plus the important summaries. Do not paste whole files, datasets
    or documents in as memories; save the summary and the discussion, and link or
    name the source instead.

## Step 3 — suggest tags

The save response includes `suggested_tags` (existing tags similar memories used)
and `tag_tree` (the whole vocabulary). Propose 2-4 short tags, reusing suggested
ones first. For the starter memory, propose adding the tag "aiakiv". Let the user
adjust before you apply anything.

## Step 4 — attach the tag to that memory

Attach the agreed tag(s) to the memory from Step 2 WITHOUT re-saving (re-saving would
duplicate it):
    mweft_remember_edit(event_id="<event_id from Step 2>", add_tags=["aiakiv"])
Confirm `added_tags` in the response.

## Step 5 — find it again

    mweft_search(query="AiAkiv connection", top_k=5)
Show the top hit and point out it is the memory from Step 2. Read each hit's `reason`
tags; if a summary is too thin, pull the body with
mweft_get_event_content(event_id="...").

## Step 6 — the five ways to search

Demonstrate each briefly with the user's own data:
- by CONTENT (meaning):  mweft_search(query="...", mode="events")
- by ENTITY:             mweft_entity_lookup(entity_name="AiAkiv")   (entities AND tags)
- by TAG:                mweft_entity_lookup(entity_name="aiakiv")   (or the tag word in a plain search)
- by TEAM (@team):       mweft_search(query="@<TeamName> ...")   or   principal="<TeamName>"
- by USER (@user):       mweft_search(query="@alice@example.com ...")   or   principal="alice@example.com"
A leading "@" is reserved for principal (user/team) attribution — a normal tag never
starts with "@". To narrow WITHIN one team, add a domain/tag term to the query.
(Optional) memories are attributed by email; to appear as something else, the user sets
an alias per team — https://app.aiakiv.com -> Console -> Teams -> Manage -> their OWN alias
(self-service; skippable). Then @user search and teammate recall show that alias.

## Step 7 — save a longer, continued memory

For a long note or a multi-part save, chain the parts so they read in order — pass the
previous save's event_id as prev_event_id on the next call:
    r1 = mweft_remember(summary="Part 1 ...", entities=[...], content="...")
    mweft_remember(summary="Part 2 ...", entities=[...], content="...",
                   prev_event_id="<r1 event_id>")
Every save response carries a `continuation_hint` with the exact prev_event_id to use
next. This is also how you save content over the 50000-char limit — SPLIT, never
truncate or summarize away text.

## Step 8 — later, when memory has piled up: analyze communities

Once there is a lot saved, offer to reveal the themes AiAkiv found:
    mweft_community_explore(scope="<tag-or-community>")   # on-demand clustering
    mweft_community_residual()                            # themes the labels miss
Both are opt-in and only meaningful after enough memory accumulates (residual needs at
least two distinct tags). Never run them on an empty account.

## Step 9 — tidy up: deprecate the demo memory

Offer to clean up the demo save from Step 2 (skip if the user wants to keep it):
    mweft_deprecate_event(event_id="<event_id from Step 2>")
Explain clearly, before calling it: this is NOT deletion. The memory is soft-hidden
— it disappears from search and recall, but the data itself is preserved. There is
no un-hide tool (restoring a hidden memory is an operator/support action), so
confirm with the user before hiding anything. This same move is how they retire any
mis-saved memory later.

## Step 10 — good habits to leave them with

- SAVE on purpose: save only when they say "ak" / "mweft" / "memoryweft" (e.g. "ak
  save"), never on a bare "remember".
- SEARCH before answering from memory: mweft_search(query, mode="hybrid") first.
- UNIFY entity names — one spelling per real thing — so recall weaves correctly.
- FIX mistakes: wrong entities/tags -> mweft_remember_edit; a memory saved by mistake
  or to the wrong project -> mweft_deprecate_event(event_id) (a hide, not a delete —
  see Step 9; confirm with the user first).
- WHERE saves go is set in the console, not by you (mweft_active_target is read-only).

## One step further
Once they have the basics, the Playbook coaches projects x personas (working modes,
web pairing): https://www.aiakiv.com/llms-playbook.txt (human: https://aiakiv.com/playbook).

Human version: https://aiakiv.com/tour (KO / EN)