Skill instructions
aiakiv-cards7 KB
View saved version →
---
name: aiakiv-cards
description: >-
Create a public AiAkiv card from the user's memory with create_aiakiv_card.
Use when the user asks to make a card, share a memory as a link or page,
publish a summary card, or asks what AiAkiv cards are or how to fix or delete
one. A card is a one-page public site (card.aiakiv.com) written by YOU from
memory search results and baked by the card service. It is live on the open
web the moment it is created.
---
# AiAkiv cards
<!-- shared-create-section: begin. This block is identical in every edition of the aiakiv-cards skill. -->
A **card** is a one-page public summary of the user's AiAkiv memory: a title,
3 to 5 bullets, a one-line conclusion and an optional longer body, plus two
share images (a square one and a wide 1200x630 one) with the short address
stamped in. Anyone with the address can view it, no login. You create it with
`create_aiakiv_card`. The server never calls a model: **you write the
content**.
## The one fact that governs everything
**Creating IS publishing.** The card page and both images are live on the open
web the instant `create_aiakiv_card` returns. The card is unlisted (nobody
finds it without the address) but NOT private. There is no draft state, no
editing and no undo except deleting the card (see "Managing cards" below). So
filter before you create, and relay the response's `notice` to the user first,
verbatim.
## Procedure
1. **Search memory first** (`search_memory`, then `get_memory_content` when a
summary is not enough). The card summarizes what is actually stored; do not
invent content. Set `source_count` to the number of memories you actually
used.
2. **Filter for sensitivity**: personal names, emails, internal addresses,
decisions not yet public.
3. **Get consent to publish.** A request to make a card is consent to publish
that card. If the content touches anything sensitive, or you had to choose
what to leave out, show the user the draft and wait for an explicit yes
before creating.
4. **Write to fit the images, not just the limits** (see "Fitting the images").
Aim to fit on the first try: creating again makes a NEW card at a new
address and leaves the first one published, and counted against the user's
card quota, until the user deletes it.
5. **Create** with `create_aiakiv_card`, passing the fields below directly.
There is no format lookup step before it.
## Fields and limits
The card service checks these after it trims whitespace and drops empty items.
- `title`: one line, up to 80 characters. Required.
- `bullets`: 3 to 5 key points, one line each, up to 120 characters each. Required.
- `conclusion`: one line, up to 200 characters. Required.
- `source_count`: how many memories the card was written from, an integer of 0 or more. Defaults to 0.
- `tags`: up to 3 search terms for card.aiakiv.com, up to 20 characters each. They are drawn into the images and **cannot be changed later**. Defaults to none.
- `body`: optional longer text shown on the page but not in the images, up to 30,000 characters of restricted markdown: paragraphs, `##` headings, `-` and `1.` lists, `>` quotes, inline and fenced code, bold, italic, http(s) links and `---`. Anything else shows as plain text.
Title, bullets, conclusion and tags are single lines: line breaks in them
collapse to spaces.
## Fitting the images
Bullets share one fixed block of vertical space, so their count and length
trade against each other. A line holds about 31 Korean characters (Latin
letters and spaces fit more) and each bullet gets up to 3 lines, but when the
total does not fit, every bullet is cut to fewer lines and shortened with an
ellipsis. Staying under 120 characters is not enough.
What fits both images: a title of up to about 20 Korean characters, a
conclusion of up to about 30 Korean characters, and 3 or 4 bullets of up to
about 40 Korean characters each. With 5 bullets the last one is left out of
the wide image. The page always shows the f
Preview of the first 4,000 characters. Read full instructions →
aiakiv-graph-query17 KB
View saved version →
---
name: aiakiv-graph-query
description: >-
Write graph queries (Cypher subset) against AiAkiv/MWeft memory with
query_memory_graph (and query_partner_memory_graph across a link). Use when the
user asks HOW memories are connected — shared entities, bridges, threads,
multi-hop paths, co-occurrence, meaning search inside one entity or tag —
whether or not they say the request phrase "ak graph" / "ak 그래프"; the
phrase is a direct way to ask. Lower priority: a search hint block carrying a
`graph_query` example. Not for plain recall (use search_memory).
---
# AiAkiv graph query
`query_memory_graph` runs a **read-only Cypher subset** over the user's memory
graph. It answers *structure* questions that flat search cannot: which events
share entities, what bridges two topics, what happened next in a thread, what
is semantically far but structurally connected.
**When to reach for it** — when the question is about structure (how memories
connect, a path between two things, the entities they share, what came next in
a thread, or a meaning search inside one entity or tag), pick the graph query on
your own judgment; no phrase is needed. The user can also ask directly with
`ak graph` (`ak 그래프`), usually followed by a question in their own words:
then the user chose the graph query, and the work is translating it faithfully
(next section). Lower priority: `hint.graph_query.example` in a search response
can be run as-is, then adapted.
**When not to** — plain recall ("what did we decide about X") starts with
`search_memory`; exact counts and table facts go to `query_memories_with_sql`,
which supports simple read queries only (filters, joins, counts, sums,
grouping; its tool description lists the rest).
If the tool is not in the list, the server has it disabled; say so.
## Translating a request (with or without `ak graph`)
1. **Translate.** "Among memories about <name>, the ones about <topic>" is
`events(entity: $name, text: $q, k: 20)`; "in the <tag> tag, …" uses `tag:`;
"A or B", "A and B both appear" and "names containing …" are recipes below.
Names match exactly (`find_memories_by_entity` shows the stored spelling).
A request for "all", "every" or "the full list" is not a closeness ranking:
it takes the listing path — `tag:` or `entity:` alone with `k: 200`, an
explicit `LIMIT`, and a `CONTAINS` or name filter when the request names
one. If `start.hub` is still `true`, the answer says there are more than 200
and not all of them were seen.
2. **Run it**, then **show the query that ran and what it means in one line**,
next to the answer, in the user's language (for the first example below:
the query, then "the 20 BP-7 memories closest in meaning to q").
3. **Put the completeness markers into the user's words** ("Reading the
response"): "could not confirm" and "none" are different answers, and
"the closest 20 of 224" is not "all 224".
4. **On a rejection**, read `hint` and `allowed_*` and fix the query once. On
"scoped match is off", fall back to `text:` or `entity:` alone (for "both",
the older `MATCH` recipe below, with its limit said) and tell the user the
new syntax is off on this server.
5. **The phrase alone** gets three example requests back, like these, adapted to
names from the user's memory and written in the user's language:
```
ak graph among the memories linked to BP-7, the discussion that set plan pricing
START a = events(entity: "BP-7", text: $q, k: 20) RETURN a, a.score
params {"q": "the discussion that set plan pricing"}
ak graph inside the ops tag, the records of a backup restore drill
START a = events(tag: "ops", text: $q, k: 20) RETURN a, a.score
params {"q": "the records of a backup restore drill"}
ak graph every entity that shares a memory with Redis and has cache in its name
START a = events(entity: "Redis", k: 200) MATCH (a)-[:PARTICIPATED_IN]-(n)
WHERE n.name CONTAINS "cache" RETURN DISTINCT n.name LIMIT 200
```
The third uses `k: 200` bPreview of the first 4,000 characters. Read full instructions →
aiakiv-links7.26 KB
View saved version →
---
name: aiakiv-links
description: >-
Read a LINKED partner org's memory through the partner memory tools. Use when
the user asks what a partner/linked org/team knows, wants to compare their
memory with a partner's, mentions a link or partner org, or when a probe
candidate carries side=remote. Covers choosing between search_partner_memory,
find_partner_memory_connections and query_partner_memory_graph, reading results, and what each error reason
means. Also covers public attaches (public memory attached to the user's
team, listed under public_attaches with __public: ids).
---
# AiAkiv links (partner-org memory)
A **link** is a read capability two orgs agreed to — not a project you switch
into. You pass `link_id` per call; your own scope is untouched. Everything is
read-only: you can never write into a partner org.
**Always start with `list_partner_links`.** It is local (works even when the
partner is down) and tells you which links are `usable` before you spend a
remote call. If the tools are absent from the tool list, the server has links
disabled — say so.
Links run **one way**, and the list holds the ones whose reading direction
points at the user's org — blocked ones included, with `usable` saying which
answer right now. Links their org **provides** (their team issued the invite, so
the link opens their memory to the partner) are left out entirely — nothing to
read, nothing to fix; `provided_link_count` says how many exist, and they are
managed in the console.
**Call link tools one at a time.** Your org may have only one link call in
flight at once. Two link tools issued in the same batch — the habit that serves
you well everywhere else — means the second returns `error: busy` without
running, even on a completely idle server. Await each call before starting the
next; `list_partner_links` is local and does not count.
## Public attaches (`public_attaches`)
`list_partner_links` also returns `public_attaches`: public memory the user's
team attached to itself in the console (team "Links" page, "Public attach"
section). There is no contract and no partner on the other side. A public org
is open to read anyway; the attach only adds name bridges (aliases) so walks
and graph queries can cross into it. Each row has `kind: "public"`, a
`link_id` of the form `__public:<org_id>`, `partner_name`, `usable`,
`blocked_reason` and `alias_count`.
- A `usable` public attach works in the same four tools with that `link_id`,
exactly like a link. Results carry `side: "remote"` the same way, and the
same rule applies: keep them labelled as the public org's, not the user's.
- The section comes back to **every member** of the team (any role), together
with the link list. A `caller_not_member` error means the user is not a
member of the active team, so neither the links nor the public attaches are
visible from it.
- A member who is not placed in any part of the team yet still gets the list,
but every link and public attach says `usable: false` with
`blocked_reason: "caller_not_placed"` (see below).
- `blocked_reason: "attach_not_enabled"`, or a `__public:` id that is not
listed, means the attach is off or the org is no longer public. Turning it
on is a console action by the team owner; do not retry.
- `alias_count: 0` means searches and bodies still work but walks and graph
queries stay home-only (no bridge). Say so instead of reporting absence.
## Which tool for which question
| Question shape | Tool |
|---|---|
| "What does the partner know about X?" — search THEIR memory directly | `search_partner_memory(sentence, link_id)` — entry happens on their side; results are their events only |
| "From what WE know, what connects to their side?" — walk from your context across shared ground | `find_partner_memory_connections` — entry in YOUR org, expansion crosses through **aliased entities** (entities the link declared "same thing on both sides") |
| Explicit relations across both orgs (shared entities, vecto
Preview of the first 4,000 characters. Read full instructions →
aiakiv-save-and-recall8.63 KB
View saved version →
---
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 project that an app manages, saving there is
refused by default. The refusal says what the user can turn on in the console;
an AI cannot turn it on.
## 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, noPreview of the first 4,000 characters. Read full instructions →