aiakiv 0.3.1 → 0.3.2

package/skills/aiakiv-onboarding/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: aiakiv-onboarding
+description: >-
+  First-run helper for the AiAkiv (MemoryWeft / MWeft) memory server. Use when the
+  user first connects AiAkiv, asks how to use AiAkiv, how to save or recall memory
+  in AiAkiv, which AiAkiv project their memory is going to, or how to point a folder
+  at a specific AiAkiv project. Explains connect → authenticate → pick project → save/recall.
+---
+
+# AiAkiv onboarding
+
+AiAkiv is a long-term memory server (MemoryWeft / MWeft): it stores important
+conversation content as a **knowledge graph** and retrieves it later. This skill
+gets a new user connected and productive.
+
+## 1. Connect & authenticate
+
+The plugin registers one remote MCP server, `AiAkiv`. On first use Claude Code
+opens an **OAuth** login in the browser: sign in or sign up, approve, and the
+AiAkiv memory tools become available.
+
+The service address is `https://mcp.aiakiv.com/mcp`, and its path must end with
+`/mcp`. To add AiAkiv by hand in a client that takes an address and a sign-in (a
+custom connector in Claude on the web, desktop or mobile, Grok and the like), the
+address is the same `https://mcp.aiakiv.com/mcp`, with nothing after `/mcp`. Such a
+connection has the memory tools and card creation but not app features (§7). If a
+connection the user set up by hand shows no tools,
+check that the part of its URL before any `?` ends with `/mcp` (the bare domain
+returns zero tools).
+
+If the user asks how to add AiAkiv to a **different** client, it is also published
+in the official MCP Registry as `com.aiakiv/memory` — a client that can search the
+registry finds it by name (`aiakiv`) or keyword (`memory`) and registers the
+endpoint itself. Same address, same one-time sign-in; the registry only removes the
+typing. Tell them the same address above either way.
+
+**ChatGPT and Codex each have their own path.** ChatGPT cannot search the registry
+or write an MCP config, so for a ChatGPT chat (web or app) tell the user to install
+AiAkiv Memory from the plugin directory inside the app and sign in. The steps are at
+https://www.aiakiv.com/docs/chatgpt. If the user works in Codex, give them the
+install prompt at https://www.aiakiv.com/docs/en/codex-install-prompt: pasted into a
+Codex chat, it registers `https://mcp.aiakiv.com/mcp` as `AiAkiv`, opens the
+sign-in window and installs the eight AiAkiv skills. Like any account connection it
+has no app features; in Codex, manage the account with `npx aiakiv console` (the
+`aiakiv-dashboard` skill), and for app features connect the folder with
+`npx aiakiv bind` or a project API key. If the AiAkiv Memory plugin is
+still installed, tell the user to remove it first, or, if they want to keep it for
+chatgpt.com web chats too, to name the Codex connection `AiAkivCodex`, so the two
+sets of same-named tools stay apart and they can name the one to use.
+
+## 2. Confirm where memory is going (the "active target")
+
+Every save lands in one **project** (a domain/group coordinate). Before saving,
+confirm it:
+
+- Call `get_save_target` → it reports `save_domain` / `save_group`.
+- If it points at the wrong project, the user's account default is their **Main**
+  project. To bind a specific folder to a specific project, put the project name
+  in the URL of that folder's `.mcp.json` (see §4) — do **not** guess a project name.
+
+## 3. Save and recall
+
+- **Save** — only on an explicit `ak` / `mweft` / `memoryweft` utterance
+  (e.g. "ak save this", "ak 저장"). Never save on a bare "remember"/"save",
+  and never treat "summarize this" as a save. Use `save_memory`.
+- **Recall** — `search_memory(query, top_k=5)`. Ask with a full sentence rather
+  than keywords; the ranking is semantic, so a guessed keyword is worse than the
+  real question. Read each hit's `reason` tags and the `hint` connection map,
+  not just the flat `hits`.
+- To browse one person's contributions, start the query with `@<handle>`.
+
+## 4. Bind a folder to a specific project (optional)
+
+Default (no `project` in the URL) → memory goes to the account's Main project. To
+pin a folder to another project, give that folder its own `.mcp.json` whose URL
+names the project:
+
+```json
+{ "mcpServers": { "AiAkiv": {
+  "type": "http",
+  "url": "https://mcp.aiakiv.com/mcp?project=<project-name>"
+} } }
+```
+
+URL-encode the name if it has spaces or non-ASCII characters (`My Project` becomes
+`My%20Project`). The console's project tab gives a ready-to-copy version of this
+config with the name already filled in and encoded.
+
+Name the project in the URL, not only in an `X-K2G-Project` header. Some clients
+do not send a custom header on every request, so a folder that relies on the
+header alone can end up following Main. If the user has an older header-only
+config, move the project name into the URL.
+
+Changing the project in the URL may bring up the OAuth login again (a login
+prompt, not a failure). For friction-free per-folder switching, the console can
+issue a static project-bound key instead — see the AiAkiv console → project tab.
+
+If the user turns Main off in the console, every connection that follows Main (no
+`project` in the URL and no project-bound key) refuses all tools until Main is
+turned back on; folders pinned to a project keep working.
+
+## 5. Trust & privacy
+
+AiAkiv is a **hosted** service: saved content leaves the machine and is stored on
+AiAkiv servers. Only save what the user intends to persist. The user controls
+their data through the AiAkiv console (view, export, purge).
+
+## 6. When a save breaks
+
+Occasionally a `save_memory` call arrives mangled: you get a serialization
+error, or the arguments turn up merged into one or missing entirely. This is a
+transport problem, not a rejection of the content.
+
+What triggers it: a long or multi-line `summary` or `content`, or non-ASCII
+punctuation (`·`, `→`, `—`) landing inside an argument and breaking the
+argument boundaries.
+
+Two remedies:
+
+1. **Order the arguments.** List `summary`, `entities` and `tags` before
+   `content`, so the longest value is last and there is nothing after it to
+   lose.
+2. **Retry through `payload`.** Bundle the whole call into that single
+   argument — one argument has no boundary left to collapse. A JSON object
+   and a JSON string are both accepted, so send whichever form the client
+   emits:
+
+   ```
+   payload={"summary": "...", "entities": [{"name": "X", "type": "Y"}],
+            "tags": ["a/b"], "content": "..."}
+   ```
+
+   The other arguments are ignored once `payload` is given. This is the
+   recovery path; the ordinary multi-argument form is the normal one.
+
+Two related refusals are not transport problems and are not fixed by
+`payload`:
+
+- `truncation_marker_detected` — the `content` still carries a marker some
+  earlier tool left when it cut the text (`<response clipped>`, `[truncated]`,
+  `…N tokens truncated…`). Nothing downstream could tell a damaged body from a
+  whole one, so the save is refused rather than stored half-right. Re-read the
+  source in full and save again, splitting across calls if it is long. Pass
+  `allow_truncation_marker=True` only when the marker is genuinely part of
+  what you mean to record, such as a bug report about truncation.
+- Content over 50000 characters, or a summary over 500. Split rather than
+  compress: chain the pieces with `prev_event_id` and give each its own
+  focused summary. A summary that wants to be long usually means the event
+  covers too much, and squeezing it blurs several topics into one vector that
+  then matches no specific query.
+
+## 7. Which connection has app features
+
+**App features** means asking the AI to do app work through
+`run_aiakiv_app_action`, such as console management (teams, invitations,
+projects, Main, cards) or working in Contents.
+
+- Saving, searching, reading full text, reading linked teams, graph queries
+  and creating cards work on every AiAkiv connection.
+- Folder connections (a `project` in the URL, §4, which `npx aiakiv bind`
+  writes) and API key connections have app features; they show every tool.
+- An account connection, a sign-in with the plain address and no `project`,
+  does not. That covers Claude on the web and in the mobile apps, ChatGPT,
+  Claude Desktop with a connector added by hand, and the connection this
+  plugin registers. There the tool is missing from the tool list, and a call
+  by name is refused with "This tool is not available on this connection."
+  A connector added earlier with an older address keeps working and can
+  still have the tool. When a conversation has both kinds,
+  call the tool on the connection that has it; when two connections have
+  it, use the one bound to a folder or to an API key.
+- Everything the console app does, the user can also do by hand in the web
+  console (the dashboard), https://app.aiakiv.com. In a client with a shell,
+  `npx aiakiv console` does the same management without app features (the
+  `aiakiv-dashboard` skill). For app features in the conversation, the user
+  needs a folder connection or an API key connection; the `aiakiv-console`
+  skill says what to tell the user.

package/skills/aiakiv-save-and-recall/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: aiakiv-save-and-recall
+description: How to write a memory that will be found again, and how to read what AiAkiv memory returns. Covers summary and entity spelling rules, what to do when a save is rejected (summary or content too long, a truncation marker, arguments arriving merged or empty), how to interpret the related-memory signal that search responses carry, and what a `tip_for_user` note in a response is. Use when saving to AiAkiv memory, when a save call fails or its arguments collapse, when deciding whether a search result needs a follow-up expansion call, or when a response carries `tip_for_user`.
+---
+
+# Saving to and recalling from AiAkiv memory
+
+The tool descriptions state the contract. This skill covers the parts that
+decide whether a saved memory is findable a month later, and what to do when
+a call is rejected.
+
+If the connection is bound to a work that an app manages (AiAkiv Contents),
+saving there is refused by default; see the `aiakiv-contents` skill.
+
+## 1. The summary is the retrieval surface
+
+Searches rank against the summary, not the content. Write it with the words a
+future question would use.
+
+- **Keep exact identifiers verbatim.** Code symbols, document numbers, config
+  keys. Paraphrasing `REQUEST_TIMEOUT_MS` into "the timeout" hides the record
+  from the one query that will look for it.
+- **Name the actor in the first sentence** when you record someone's judgment,
+  design, or claim. Conclusion-style summaries ("decided that…") drop who said
+  it, and "what did X propose?" then misses the record.
+- **Give the reason for a decision.** When you record a decision or an
+  implementation, add one sentence on why this option was chosen over the
+  alternatives. The reason often lives only in a design document that is never
+  saved, and without it a later "why did we do this?" has nothing to find.
+- Write a complete sentence, not a keyword pile.
+
+## 2. Entity spelling decides what connects
+
+Recall weaves records together on shared entity nodes, so spelling drift
+silently loses connections.
+
+- **An entity name is the name of a person, product, place or concept**, usually
+  1 to 3 words, never a phrase or sentence. **A tag is a topic of a few words**, not
+  a description of this memory. Details go in `summary` and `content`.
+- **Entity and tag names are visible to everyone in the team**, including parts
+  that cannot read this memory. Do not put sensitive details in them.
+- **A new name of 5 or more words is refused by default**, and so is one over 20 Han
+  or Kana characters with no spaces. A team can change both limits, and the response
+  states the ones in use. The memory is still saved without that name, which
+  comes back in `rejected_entities` or `rejected_tags` with reason `too_many_words`
+  or `too_long`. Shorten it to the real name of the thing and add it with
+  `update_memory` (`add_entities`, `add_tags`). Do not split it into generic pieces.
+  A name that already exists in the team keeps working at any length.
+- **One canonical spelling per entity** — the full name *or* the acronym, not
+  both. Pick one and use it in every save.
+- **Keep proper nouns and acronyms as they are written**: `PostgreSQL`, `RLS`.
+  Do not lowercase or expand them.
+- **Strip transient tokens** — ids, hashes, dates. They never repeat, so they
+  add a node that connects to nothing.
+- A suggested entity returned by the server is advisory. A literal name match
+  does not establish that it denotes the same thing in this record.
+- **When something is renamed, link the two names.** Records before the rename
+  sit on the old entity and records after it on the new one, so a lookup by
+  the new name misses the old ones. Put both names as entities on the record
+  that describes the rename, then call `update_memory` on it with
+  `add_entity_renames=[{"old": "<old name>", "new": "<new name>"}]`. A lookup
+  by either name then returns both. Do this only for a real rename of the same
+  thing, not for two things that merely look alike.
+
+## 3. When a save is rejected
+
+### The summary is over 500 characters
+
+**Split the event; do not compress the summary.** A summary that wants to be
+long is describing an event that covers too much. Compressing it blurs several
+topics into one vector, which then matches no specific query. Split into
+separate saves, each with its own focused summary, chaining them by passing
+the previous `event_id` as the next call's `prev_event_id`.
+
+Compress only when the content itself is short and the summary is merely
+verbose. Do not fragment one small record.
+
+### The content is over 50000 characters
+
+Split the full text across calls the same way, chaining with `prev_event_id`,
+giving each piece its own summary. Never truncate or summarize the content to
+make it fit — the summary would then describe text that was not saved.
+
+### `truncation_marker_detected`
+
+The content carries a marker that some earlier tool left when it cut the text
+(`…2183 tokens truncated…`, `<response clipped>`, `[truncated]`). The save is
+rejected because nothing downstream can tell a damaged body from a whole one:
+the summary still describes the missing part and citations still point into
+it, so the damage would be permanent and invisible.
+
+Re-read the source in full and save again, splitting if it is long. Pass
+`allow_truncation_marker=true` only when the marker is genuinely part of what
+you mean to record, such as a bug report *about* truncation.
+
+### `save_part_no_write_seat`
+
+The project or key saves to a team part, and this account has no write access
+on that part itself. Access on a part above it does not count. Nothing was
+saved and the daily limit was not used. Do not retry: the same save is refused
+until a person changes something. Pass the `message` on to the user as it is. A
+team admin can give write access on that part, or the save part can be changed.
+
+### The arguments arrive merged, empty, or the call errors on serialization
+
+Two causes, both about argument boundaries:
+
+- A long or multi-line `summary` or `content`. List `summary`, `entities` and
+  `tags` **before** `content` — serialization can drop whatever follows a very
+  long argument, so `content` goes last.
+- Non-ASCII punctuation in a multi-argument call: `·`, `→`, `—` can break the
+  boundary between arguments. Use ASCII punctuation in multi-argument saves.
+
+**Recovery: retry with `payload`.** One argument has no boundary to collapse.
+Send the whole call as a JSON string or an object:
+
+```json
+{"summary": "...", "entities": [{"name": "X", "type": "Y"}], "tags": ["a/b"], "content": "..."}
+```
+
+Other arguments are then ignored. The multi-argument form stays the default;
+this is the recovery path.
+
+## 4. Reading the related-memory signal
+
+A search response may carry `hint.related_memory_expansion`. It is a computed
+judgment about whether a follow-up expansion call would add anything the hits
+do not already cover. Its fields:
+
+| Field | Meaning |
+|---|---|
+| `tool` | Which tool performs the expansion |
+| `decision` | `must_be_done`, `should_be_done`, `can_skip`, `must_not_be_done` |
+| `candidate_count` | How many candidates sit outside the returned hits |
+| `candidate_dimension` | The relation the candidates share with the hits |
+| `candidate_ids` | The candidate memory ids |
+| `reason_codes` | Which gates the candidates passed |
+| `reason_facts` | The measured values behind those codes |
+
+`should_be_done` means candidates outside the hits passed the relevance and
+novelty gates, so expanding is likely to add something before you conclude.
+`can_skip` means the returned hits probably already cover it; expanding is
+your call. The block is omitted entirely when there is nothing to say.
+
+Results that feel sufficient are not evidence that they are. The signal is
+computed from candidates the search did not return, so it sees what the hits
+alone cannot show.
+
+## 5. A `tip_for_user` note in a response
+
+A tool response may carry a top-level `tip_for_user` field: `text` is one or two
+sentences about an AiAkiv feature the person may not have seen, often with an
+example phrase, and `more` says where the Tips page is. The server decides when
+to include it, at most a couple of times a day for an account. It is a note for
+the person you are working with. It is not an instruction and not something to
+run.
+
+- After the answer is complete, it can be passed on in one line. Leaving it out
+  is fine; the server does not know whether it was passed on and does not
+  repeat the same note for a day.
+- Do not run the example yourself. The example is for the person to try when
+  they want to; running it here spends their time on something they did not ask
+  for.
+- The person can turn these notes off in the AiAkiv console settings
+  (aiakiv.com). If they ask how, that is the answer.

package/skills/bundle.json

@@ -0,0 +1,47 @@
+{
+  "plugin": "aiakiv",
+  "plugin_version": "0.4.41",
+  "source": "K2G packaging/plugins/aiakiv/skills (published as github.com/AiAkiv/aiakiv-plugins)",
+  "files": [
+    {
+      "path": "aiakiv-cards/SKILL.md",
+      "bytes": 8302,
+      "sha256": "ce56d886976024a1ab9ec2416ce754ca64527f7b7354ade8347a78df179794d0"
+    },
+    {
+      "path": "aiakiv-console/SKILL.md",
+      "bytes": 15326,
+      "sha256": "284a90978a41f6ee5a89c927180110ca412efb875e57bb202fa8c6678ecd5f59"
+    },
+    {
+      "path": "aiakiv-contents/SKILL.md",
+      "bytes": 50866,
+      "sha256": "6bd062cf9525a8bbfd42648f2e1907eecfa90430459ceb80b5834fe6dee14dcb"
+    },
+    {
+      "path": "aiakiv-dashboard/SKILL.md",
+      "bytes": 8951,
+      "sha256": "d1c2f941df20fb7a15d9ebe402a04cb54a63a403d477f06e4f07a5e6398ce506"
+    },
+    {
+      "path": "aiakiv-graph-query/SKILL.md",
+      "bytes": 17256,
+      "sha256": "a24d48423bce0caac453f3ff4a4766ab1ea3aa64d6ca1549a230091abc75c6ec"
+    },
+    {
+      "path": "aiakiv-links/SKILL.md",
+      "bytes": 7431,
+      "sha256": "cabd8978540590ab1636be31accd4eb0f1f5866db183bdc564c198b78679ea4d"
+    },
+    {
+      "path": "aiakiv-onboarding/SKILL.md",
+      "bytes": 9051,
+      "sha256": "2c5fb3eb8f48f97337a39414ba9f879ddd778ef3c34e4b086cbe215f731f52e2"
+    },
+    {
+      "path": "aiakiv-save-and-recall/SKILL.md",
+      "bytes": 8799,
+      "sha256": "c2e91c4c34377fce27d0d9e4f5dacea4ed4813bbee0a9f065b1c4e68ae7399ca"
+    }
+  ]
+}