# 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://www.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 get_save_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 classic, xAI/Grok): cannot split by folder.
  They send no header and follow whatever is Main; the user switches Main in the
  console.
- THE CHATGPT APP IS ITS OWN SHAPE. OpenAI ships two apps side by side: `ChatGPT`
  (what used to be Codex) and `ChatGPT classic` (the original chat app). The names in
  older material are the reverse of today's, so always go by the app the user sees.
  The ChatGPT app CANNOT do OAuth — neither a custom connector nor the
  `X-K2G-Project` folder header takes hold there. It attaches ONLY with a
  project-scoped API key in `.codex/config.toml` (the config path kept the old name).
  The key carries the project, so it is pinned regardless of Main. The classic
  connector may stay in place at the same time — see the CHATGPT bullet below.
- 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 `get_save_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).

FINDING IT IN THE OFFICIAL MCP REGISTRY — AiAkiv is published at
registry.modelcontextprotocol.io as `com.aiakiv/memory`, so a client that can search
the registry finds it by name ("aiakiv") or by keyword ("memory") and can register
the endpoint from the listing. The listing carries the same URL used below, so the
result is identical either way — the registry only saves you from typing it.
- Registry search is NAME-based. `com.aiakiv/memory` matches both "aiakiv" and
  "memory"; a description-only word will not match.
- Whatever the route, the endpoint is the same and the sign-in step below still
  applies. Being listed does not skip authentication.
- CHATGPT CANNOT DO THIS. Its app has no registry search and cannot write an MCP
  config itself, and — decisive — it does not complete our OAuth sign-in: it reads
  the 401 and asks for a bearer token in an env var instead of opening the sign-in
  window. So do NOT tell a ChatGPT user to "install it from the registry". Route
  them to the connector UI step in Question 2 instead, and if their build offers no
  sign-in there, have them issue a project-scoped API key in the console and paste
  that. (Claude Code and other clients that follow the 401's `WWW-Authenticate`
  header do open the sign-in window normally.)

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 -> Manage projects -> that project ->
  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).
- CHATGPT app (also its CLI and IDE extension — the config path is `.codex/`):
  write `.codex/config.toml` with the project-pinned API-key TOML below. This is the
  ONLY way in: OAuth does not attach here, so do NOT offer a custom connector and do
  NOT offer the `X-K2G-Project` header form — neither takes hold. Have the user issue
  a project-scoped key in the console (https://app.aiakiv.com -> Manage projects -> the project
  -> issue key, shown once). The key carries the project coordinates itself, so saves
  land in that project regardless of Main.
  NAME THE SERVER SOMETHING ELSE THAN `AiAkiv` — the snippet below uses
  `AiAkiv-proj`. If the user also keeps the ChatGPT classic account connector (which
  is allowed and works), identical names make the tool names identical too, and then
  neither the user nor you can say which one to save through.
  Prefer ONE of the two paths. If both are in use, tell the user to name the target
  explicitly and to call `get_save_target` before trusting where a save landed.
- 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 classic the same rule has a second edge: the connector must be created
  on the chatgpt.com WEB PAGE — it cannot be created from inside either app.
- GLOBAL web/app (Claude Web / ChatGPT classic / 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 get_save_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 + ChatGPT classic together: two different paths, and BOTH may be live.
    The classic connector is made once on ChatGPT Web and applies account-wide, so
    the ChatGPT app sees it too; the ChatGPT app additionally reads a folder
    `.codex/config.toml` when work starts in that folder. Recommend ONE path. If
    both are wanted, the folder entry MUST use a different server name
    (`AiAkiv-proj`, not `AiAkiv`) or the tool names collide and no one can pick a
    side — and then call `get_save_target` before trusting a save target.
  - 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>"
      }
    }
  }
}

API-KEY TOML (the ChatGPT app, per folder) — file `.codex/config.toml`. This is the
only way that app attaches; the key pins the project, so there is no
`X-K2G-Project` header and no OAuth. The server name is deliberately NOT `AiAkiv`
(see the CHATGPT bullet):
[mcp_servers.AiAkiv-proj]
url = "https://mcp.aiakiv.com/mcp"
http_headers = { "Authorization" = "Bearer <API-KEY>" }

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.
- ChatGPT app (also its CLI / IDE extension): `.codex/config.toml` + the API-key
  TOML above — that is the only way in, since OAuth does not attach here. Do not
  offer a custom connector or the `X-K2G-Project` header form. Name the server
  `AiAkiv-proj` so it does not collide with a ChatGPT classic connector, which may
  stay in place alongside it.
- 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 classic: add it ONLY on the chatgpt.com WEB PAGE. A connector cannot be
  created from inside either app — open chatgpt.com in a browser first, even if the
  user normally lives in an 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.) Developer mode is needed only until AiAkiv
  is listed in OpenAI's plugin directory (as of 2026-08); if the user balks, route
  them to the ChatGPT app's folder + API-key path instead.
  Create it MANUALLY — do not rely on any connector directory/search; AiAkiv is not
  listed there. Once made, it applies account-wide and the ChatGPT app sees it too.
  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 AiAkiv 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 classic: add the connector on the chatgpt.com WEB PAGE only — it cannot
   be created from inside either app. Once made it applies account-wide, so the
   ChatGPT app sees it too. Turning on developer mode is required only until AiAkiv
   is listed in OpenAI's plugin directory (as of 2026-08); if the user balks at that,
   route them to the ChatGPT app's folder + API-key path instead.
2a. Keeping the classic connector AND a folder `.codex/config.toml` key at the same
   time is fine. Give them DIFFERENT server names (`AiAkiv` vs `AiAkiv-proj`),
   otherwise the tool names collide and there is no way to pick a side. Recommend one
   path; if both are live, call `get_save_target` before trusting a save target.
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 tool list shows `save_memory`, `search_memory` and
`get_save_target`. Call get_save_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://www.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://www.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 search_memory(query, mode="hybrid") first.

## Next steps
- Learn the basics hands-on: https://www.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://www.aiakiv.com/playbook).

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