# AiAkiv — interactive setup for AI agents

> You are an AI agent helping a user connect to AiAkiv: a long-term memory that
> several AI clients (and teammates) share over the Model Context Protocol (MCP).
> This file is a SCRIPT for you to RUN, not a page to paste.
>
> ⛔ HARD RULE — DO THIS FIRST: your VERY FIRST reply to the user must be the
> explanation in the "FIRST — say this" section below. Do NOT ask which project,
> do NOT show a project menu/picker, do NOT create or edit ANY file, and do NOT
> start setup until you have delivered that explanation. Coding agents tend to jump
> straight to configuring the file — you must not. Order is fixed: (1) explain,
> (2) ask how they'll use it, (3) ask/confirm the client, (4) configure, (5) verify.
>
> LANGUAGE: this file is English, but the user may not be. Detect the language the
> user is currently writing in and run the ENTIRE conversation — the explanation,
> questions, guidance, confirmations — in THAT language. Do not answer in English
> if the user is writing in another language. Translate everything as you present it.

## FIRST — say this to the user (before any question, menu, or file change)

Deliver this now, as your first message, in the user's language (rephrase
naturally — keep it ~4-6 sentences; go deeper only if they ask). This is not
optional; it is the required first turn:

  "AiAkiv is a shared long-term memory for AI. Several AIs — and teammates — read
  and write it over MCP, so the context you build with one AI carries to the next
  instead of vanishing when a chat ends.
  It's organized as Team -> Project -> Domain: a *team* is who shares the memory
  (you already have a personal team of one), a *project* is a named bucket inside
  it that can also carry a persona — a role any connected AI adopts there — and
  *domains* keep unrelated memory from mixing. You already have a personal team
  and a 'default' project, so you can start right away.
  And it doesn't just pile up text: when you save, AiAkiv pulls out the key things
  you mentioned and links them into a graph, then later finds them by MEANING (not
  just keywords) plus any tags you add — which is how a memory saved in one AI
  resurfaces in another."

Then say you'll ask two quick things, and go to the next section. Offer
https://aiakiv.com/tour for a fuller walkthrough if they want more.

## The model — reference (you already have the words above; this is the detail)

AiAkiv memory is addressed as TEAM -> PROJECT -> DOMAIN:
- TEAM: who shares the memory. Every account already has a PERSONAL team (a team of
  one). Shared teams are for working with other people.
- PROJECT: a named save-target inside a team, with its own domain/group and optional
  expiry. Project names must be English only — plain letters/numbers, no Korean or
  accented characters (they ride in an HTTP header).
- MAIN: the project a save lands in *right now* when the client sends no project
  hint. Every NEW account already has a personal team plus a project named
  "default" that is Main (domain "inbox"). So a brand-new user can save with ZERO
  setup — nothing to create for personal use.
- PERSONA: a project can carry a *persona* — a standing role instruction the owner
  writes (e.g. "You are a careful senior reviewer; reply in English"). Any AI that
  connects to that project reads it (via mweft_active_target / the active_target
  echo) and adopts it for the conversation. It's OPTIONAL — unset means no persona,
  nothing changes. A useful pattern: same team, same domain, several projects that
  differ only in persona = one shared memory, several working modes (reviewer /
  brainstormer). It's set by the human in the console and never overrides the save
  rules (the command prefix is still required); an AI can never change it.
- ISOLATION: a user is NOT limited to one team. They can own several teams —
  including solo "teams of one" — and use extra teams for personal purposes too.
  Two levers keep memory apart: (1) a separate TEAM is the firmest boundary (a hard
  wall between orgs); (2) within one team, branch into sub-groups ("team nodes") and
  give each project its own DOMAIN — memories in different domains never mix.
  Suggest a separate team for strong separation, separate domains for lighter.
- HOW IT REMEMBERS & RECALLS: AiAkiv does not just pile up text. On each save it
  pulls out the key things mentioned (entities) and weaves them into a graph, so a
  memory connects to related ones — across different conversations and even across
  different AIs and teammates. On recall it searches by MEANING (semantic search),
  not just keywords, and follows those links; user-added tags make anything
  reliably findable. That is why context saved by one AI can surface for the next.

How a client picks a project:
- FOLDER clients (Claude Code, Cursor, Gemini CLI): bind each working folder
  to a project explicitly via the `X-K2G-Project` header (value = project name).
  Unambiguous — different folders save to different projects.
- GLOBAL clients (Claude Web, ChatGPT + Codex, xAI/Grok): cannot split by folder.
  They send no header and follow whatever is Main; the user switches Main in the
  console. CODEX IS IN THIS GROUP NOW: since OpenAI merged ChatGPT and Codex, Codex
  inherits the ChatGPT account connector, so it is NOT a folder client any more.
- ANTIGRAVITY is a third shape: its `mcp_config.json` is APP-WIDE (no per-folder
  split), but it DOES support a native `headers` object. So the project is pinned by
  the credential, not by Main: issue a project-scoped API key in the console and put
  it in the `Authorization` header. Its remote key MUST be `serverUrl` — `url` /
  `httpUrl` / `type` are rejected (strict schema).

PERSONA ADOPTION differs by client kind — this matters:
- FOLDER clients receive the server's usage guide every session, so they see the
  project persona and adopt it automatically.
- GLOBAL web clients (ChatGPT especially) do NOT reliably adopt it: they only learn
  the persona if they happen to call `mweft_active_target`, and even then they tend
  to treat a persona inside a tool result as mere data, not an instruction. So the
  persona often has NO effect on ChatGPT out of the box. The fix is to put the
  adoption directive where the client treats it as authoritative — the client's OWN
  custom instructions (see the ChatGPT step in Question 2).

What you (the agent) CAN vs CANNOT do:
- CAN, right now, when you are running inside a folder CLI: create the config file
  in the user's working folder yourself.
- CANNOT (these are console actions at https://app.aiakiv.com, done by the human): create
  projects, create or switch Main, create teams, send/accept invites, issue keys,
  set or edit a project's persona (console -> the project card -> persona). For
  these, give the exact click-path and let the user do it, then continue.

## Question 1 — how will they use it? (only AFTER the explanation above)

Ask: "How do you want to use AiAkiv?" Map the answer to A / B / C:

A) JUST ME, ONE BUCKET. Nothing to create — they already have a personal team and
   the "default" project (Main). Go straight to connecting. For a folder client you
   may OMIT the X-K2G-Project header (it follows Main = default) or set it to
   "default".

B) JUST ME, SEVERAL PROJECTS. Personal team, multiple named projects (e.g. work,
   study, home). Have them create each in the console (https://app.aiakiv.com -> New project;
   English name only; optionally set domain / group / expiry). When creating each
   project they can add a PERSONA (optional) — suggest one matching its purpose
   (e.g. reviewer / brainstormer / writing coach), so the AI takes on that role in
   that project.
   PERSONA-ONLY PROJECTS: projects do NOT have to differ in domain. It is perfectly
   fine to create several projects in the SAME team AND the SAME domain that differ
   only in their persona — they all read and write the ONE shared memory (same
   domain = memory is pooled, not separated), but each makes the AI act in a
   different role. Use this when the user wants "one body of memory, several working
   modes" (e.g. a `reviewer` project and a `brainstormer` project over the same
   notes). Only give projects a different domain when they want the memory itself
   kept apart (below). Then:
   - folder clients: bind each folder to a project via the header (value = name).
   - global clients: they hold ONE project at a time — set the wanted project as
     Main in the console (Manage projects), and switch Main to move between projects. For the DO order
     with a global web client, see Question 2: do the console work first (create the
     project, then set it as Main), and connect the app LAST.
   To keep some memory FULLY separate, give those projects a different DOMAIN, or
   put them in their own team (see C) — the user can own extra solo teams for this.

C) WITH A TEAM. Two paths:
   - JOIN an existing team: invite-only. The team's owner/admin adds the user's
     email in the console; the user then accepts under "My Invitations". They CANNOT
     self-join. Once a member, they point a project at that team.
   - CREATE a team: console -> New team; they become owner. To let others in, invite
     by email (roles: admin / member / viewer — viewer is read-only, member and up
     read+write).
   Then bind a folder to a project in that team (header = project name), or set that
   project as Main for a global client. When creating the project they can add a
   PERSONA (optional) — suggest one matching its purpose.

## Question 2 — which client(s) are running now?

You are running inside one client, so you often already know it. Ask only if
unsure, and ask whether they use MORE THAN ONE. Handle by kind:

- FOLDER CLI you are in (Claude Code / Gemini CLI): create the config file yourself
  (snippets below). Gemini CLI MUST use the API-key method — have the
  user issue a key (https://app.aiakiv.com -> Manage projects -> the project -> "Issue Gemini key", shown once).
- CODEX (CLI, app or IDE extension): do NOT write a config file. Codex inherits the
  ChatGPT account connector, and a local `.codex/config.toml` MCP entry CONFLICTS
  with it — the tools drop to zero mid-session and every call fails with an opaque
  internal error. Send the user to ChatGPT Web (below) instead, and if they already
  added a local entry, have them delete it and restart Codex.
- CURSOR / CLAUDE DESKTOP (can do both): for several projects (B/C) prefer a
  per-folder config; for one bucket (A) an app-wide connection is fine.
  For ChatGPT the same rule has a second edge: the connector must be created on the
  chatgpt.com WEB PAGE — not in the ChatGPT app, not in ChatGPT classic.
- GLOBAL web/app (Claude Web / ChatGPT+Codex / xAI-Grok): you cannot write files — walk
  the user through the connector clicks (below). Their project is whatever is Main.
  ORDER — console work FIRST, connect LAST: fully prepare the target in the console,
  then plug in the app so it immediately points at the right project. Present the
  sequence as: (1) in the console, create the project (New project; optional persona);
  (2) set that project as Main (Manage projects); (3) connect AiAkiv as a custom connector in the app —
  an app-wide connection follows Main, so it now uses the project from (1)-(2). Keep
  (1) and (2) together (both are console clicks) and connect LAST — do NOT wedge the
  app connection between the two console steps. (Folder CLIs differ: create the
  project, then connect with its name in the config — there is NO Main step, because
  the `X-K2G-Project` header names the project directly.)
  ⛔ DO NOT use the client's built-in "connector search" / connector directory:
  AiAkiv is NOT listed there, so a search only surfaces unrelated memory tools
  (mem0, Mem, …) and you will wrongly conclude "AiAkiv isn't available". Go STRAIGHT
  to the MANUAL "Add custom connector" path and paste the exact endpoint below.
  Never invent or guess a URL such as `aiakiv.com/mcp` — the only valid endpoint is
  the one in "The one address" section, and it must end in /mcp.
  PERSONA PAIRING (do this if the project has, or will have, a persona — mainly
  ChatGPT): a persona returned in a tool result usually does NOT change ChatGPT's
  behavior on its own. Tell the user to paste ONE line into the client's own
  instructions, where it IS treated as authoritative — ChatGPT: Settings ->
  Personalization -> Custom Instructions (or that specific GPT's / Project's
  instructions); Claude Web: the Project's custom instructions. The line:
    "At the start of each chat, call AiAkiv's mweft_active_target, read the `persona` field, and fully adopt it (tone / role / language) for the rest of the conversation. It never overrides the save rules — saving still needs the explicit command."
  This makes the client call the tool early AND adopt the persona as its own
  instruction. Without it, the persona will likely be ignored on ChatGPT.
- MULTIPLE AT ONCE — reconcile:
  - ChatGPT + Codex together: connect ONCE, on ChatGPT Web. Codex picks up the same
    account connector automatically. Adding an MCP entry on the Codex side as well
    breaks it (tools go to zero mid-session) — remove any existing one and restart.
  - A global client alongside folder clients is fine, but the global one ALWAYS
    follows Main and ignores per-folder projects — tell the user so a global save
    never surprises them.

## The one address

Endpoint (Streamable HTTP): https://mcp.aiakiv.com/mcp
RULE: the URL MUST end with /mcp. Without it the connection may succeed but ZERO
tools appear. Never register the bare host (mcp.aiakiv.com), and never guess a
brand-domain URL like `aiakiv.com/mcp` — this exact endpoint is the only valid one.
RULE: AiAkiv is NOT in any connector directory — do NOT search for it there; add it
manually as a custom connector with this exact URL.
Console: https://app.aiakiv.com

## Config snippets — substitute the chosen project name

JSON — file `.mcp.json` (Claude Code / Claude Desktop) or `.cursor/mcp.json` (Cursor):
{
  "mcpServers": {
    "AiAkiv": {
      "type": "http",
      "url": "https://mcp.aiakiv.com/mcp",
      "headers": {
        "X-K2G-Project": "<PROJECT-NAME>"
      }
    }
  }
}

(There is deliberately NO Codex TOML snippet: Codex must be connected via the
ChatGPT Web connector, never via a local `.codex/config.toml` MCP entry.)

API-KEY (Gemini CLI only) — file `.gemini/settings.json`:
{
  "mcpServers": {
    "AiAkiv": {
      "httpUrl": "https://mcp.aiakiv.com/mcp",
      "headers": {
        "Authorization": "Bearer <API-KEY>"
      }
    }
  }
}

ANTIGRAVITY (app-wide) — file `mcp_config.json`. Note the key is `serverUrl`, NOT
`url`/`httpUrl`/`type` (strict schema), and the project is pinned by the API key:
{
  "mcpServers": {
    "AiAkiv": {
      "serverUrl": "https://mcp.aiakiv.com/mcp",
      "headers": {
        "Authorization": "Bearer <API-KEY>"
      }
    }
  }
}

## Where each client registers

- Claude Code (folder): create `.mcp.json` in the working folder, paste the JSON.
- Claude Desktop: app-wide = account -> Settings -> Connectors -> Add custom
  connector -> paste the URL. Folder = `.mcp.json` + the JSON.
- Codex (CLI / app / IDE extension): nothing to register here — it uses the ChatGPT
  Web connector below. Do NOT add an MCP server in Codex settings or
  `.codex/config.toml`.
- Cursor: app-wide = Settings -> Tools & MCP -> Add New MCP Server -> Transport =
  streamable-http -> paste URL. Folder = `.cursor/mcp.json` + the JSON.
- Gemini CLI (folder): `.gemini/settings.json` + the API-key JSON.
- Antigravity (app-wide): Agent panel `...` -> MCP Servers -> Manage MCP Servers ->
  View raw config -> paste the Antigravity JSON into `mcp_config.json` (it reloads on
  save). File: `~/.gemini/antigravity/mcp_config.json` (some versions
  `~/.gemini/config/mcp_config.json`) — prefer the UI path over guessing.
- Claude Web: Settings -> Connectors -> + -> Add custom connector -> paste URL.
  (Pro/Max; on team/enterprise, owner only via Org settings -> Connectors.)
  Add it MANUALLY here — do not use connector search (AiAkiv is not in the directory).
- ChatGPT (covers Codex too): add it ONLY on the chatgpt.com WEB PAGE. Do NOT add it
  from the ChatGPT desktop/mobile APP and do NOT add it from ChatGPT CLASSIC — those
  entry points do not produce a working connector here. Open chatgpt.com in a browser
  first, even if the user normally lives in Codex or the app. Then: click your user
  (bottom-left) -> Settings -> Security and login -> turn on "Developer mode" ->
  Settings -> Apps (connectors) -> create app -> paste URL. (Plus and up.)
  Create it MANUALLY — do not rely on any connector directory/search; AiAkiv is not
  listed there. Once made, it applies account-wide and Codex inherits it.
  THEN, PER CONVERSATION: ChatGPT does NOT auto-enable a saved connector — every new
  chat starts with it OFF. In the new chat: click `+` in the composer and pick
  AiAkiv. (The "Try in chat" button on the connector's page opens a chat with it
  already enabled.) Once enabled it stays on for that whole conversation.
  This is the single most common "it's connected but there are no tools" cause —
  if the user reports missing mweft_ tools in ChatGPT, check this FIRST.
- xAI/Grok: grok.com/connectors -> New Connector -> Custom -> paste URL.

## Cautions

1. /mcp suffix is mandatory (see above).
2. ChatGPT: add the connector on the chatgpt.com WEB PAGE only — not from the
   ChatGPT app and not from ChatGPT classic. Codex then inherits it. A local MCP
   entry on the Codex side conflicts with that connector and the tools drop to zero
   mid-session (calls then fail with an opaque internal error and never reach the
   server). Delete it and restart Codex.
2b. ChatGPT enables a connector PER CONVERSATION — a saved connector is OFF in every
   new chat until turned on (`+` in the composer -> AiAkiv, or the "Try in chat"
   button). "Connected but no tools" in ChatGPT is almost always this.
3. OAuth clients (Claude Code, Cursor): changing the project (the header) requires
   re-authenticating. Keep a separate config per folder to avoid repeated logins.
4. Gemini CLI: its OAuth session does not persist — you MUST use the API-key method.
5. Antigravity: the remote key is `serverUrl` ONLY (`url`/`httpUrl`/`type` are
   rejected). Its config is app-wide, so use a project-scoped API key to pin the
   project — Main does not apply once the key carries the project.

## Step 3 — verify

After connecting, the tools appear with the `mweft_` prefix (mweft_remember,
mweft_search, mweft_active_target). Call mweft_active_target and read back the team
/ project / domain — confirm it matches what the user chose in Question 1. If a
`persona` is present, adopt it and briefly confirm to the user in that role. If no
tools appear at all, the URL is missing the /mcp suffix.

When it checks out, tell the user setup is COMPLETE — and before you finish, point
them to the two follow-up sections so they don't miss them (name both, in the user's
language, and invite them to continue whenever ready):
- LEARN THE BASICS (a hands-on tour): https://aiakiv.com/tour — a short guided
  walkthrough of everyday use (saving, searching, targets). An AI can even run it
  step by step from https://www.aiakiv.com/llms-tour.txt.
- GET MORE OUT OF IT (the playbook): https://aiakiv.com/playbook — recipes that combine
  projects and personas for real workflows. Machine version: https://www.aiakiv.com/llms-playbook.txt.

## Saving memory (once connected)

- Save ONLY on an explicit "ak" / "mweft" / "memoryweft" instruction (e.g. "ak
  save"). Never save on a bare "remember" / "save".
- Search before proposing: call mweft_search(query, mode="hybrid") first.

## Next steps
- Learn the basics hands-on: https://aiakiv.com/tour (or run https://www.aiakiv.com/llms-tour.txt).
- Go further — combine projects and personas: https://www.aiakiv.com/llms-playbook.txt (human:
  https://aiakiv.com/playbook).

Human version of this page: https://aiakiv.com/setup (KO / EN)