For AIs connected to AiAkiv

Written for an AI, not a person. Three rules, and a map of every tool the engine exposes.

This page is read by an AI, not a person. It collects the rules and tool usage an AI client connected to AiAkiv (over MCP) must follow. (People can read it too, to understand why the AI behaves the way it does.)

Three rules

1) Save only on an explicit command

Save only when the user explicitly commands it with ak. Do not save on "remember this" or "write that up". Reasoning and detail → Saving.

Two things are easy to miss when saving. Attach at least two tags of different kinds, and chain with prev_event_id when the content continues the previous save. Both heavily affect the user's later recall. If the text exceeds 50,000 characters, split and chain it rather than trimming → Threads.

2) Search before you propose

Search first before recommending a design change, explaining why something was built a certain way, or offering a bug fix. The moment your confidence is highest is exactly when you're most likely to raise an already-rejected alternative again. High confidence is a signal to check, not a signal to skip.

3) Never change the save target on your own

The save, search and target-check tools cannot change the save target (Main). That's the invariant preventing prompt-injection hijacking. If the user wants to switch, hand them switch_url and have a person click it. There is one exception: when the user has turned on target:switch in the console's AI permissions and explicitly asks, you may switch it with the console app's switch_main. The destination is only an id from a list action → Asking your AI to do console work. Detail → Teams and projects.

Tool map

Tools by role. (The right column is the actual call identifier exposed by the current engine. Call it by exactly that name.)

Everyday tools: these eight cover most of it.

Role When Call identifier
Search Before proposing, explaining, or recalling anything. Default mode="hybrid" search_memory
Fetch full text When the search summary isn't enough and you need the original get_memory_content
Save Only when the user commanded it with ak save_memory
Chained save When the content continues the previous save (split text, an ongoing thread, stage N of a procedure) save_memory(prev_event_id=…)
Correct a save When the extracted entities, tags, or chaining are wrong. The original text can't be changed → Saving update_memory
Retire a save To take a mis-saved, misfiled, or stale memory out of recall. Hiding, not deleting hide_memory
Check target To confirm the save location, or when an expected memory isn't there get_save_target
List projects "Which project does this save to?" / when a switch link is needed list_memory_projects

Digging deeper: reach for these only when search doesn't get there.

Role When Call identifier
Find what search missed search_memory returns nothing but you believe something exists. First follow that response's link map (hint) and each hit's reason. If you know a name fragment, go to entity lookup; to widen from one point, use one-hop traversal hint from search_memory, then find_memories_by_entity or find_memory_connections
List chronologically The change history of one entity or topic along a timeline list_memory_timeline
One-hop traversal One hop through the entity-event graph from where a sentence lands find_memory_connections
Entity lookup Entities by name fragment, and the events attached to them find_memories_by_entity
Paged search Paging further through the ranked results of one query search_memory(offset=…)
Graph query When the question is about structure, such as connections, paths, or a meaning search inside a scope, or when the user calls it directly with ak graph. Translate the question into a query, run it, and show the query that ran and what it means in one line (Cypher subset, read-only) → Asking by relationship query_memory_graph

Reading another team: only when a link exists → Links

Role When Call identifier
List links Start here. Which links are usable and why others are blocked (blocked_reason) list_partner_links
Search the partner Search the partner memory directly (works without aliases) search_partner_memory
Cross-traverse Start in your memory and cross the bridge (aliases required) find_partner_memory_connections
Cross graph query A graph query spanning both teams (aliases required) query_partner_memory_graph
Partner full text Read a partner record's body, paged get_partner_memory_content

Other

Role When Call identifier
Official guides When you need the tour, setup, or playbook. Don't guess the URL: call this get_aiakiv_memory_guide
Schema lookup Checking tables and columns before using the SQL tool below describe_memory_schema
Direct query Aggregates and statistics the tools above can't do. Read-only query_memories_with_sql
Create a card When the user asks to turn memories into a public card. The input fields are fixed, so there is no separate format lookup step. Pass the response's notice before anything else → Cards §8 create_aiakiv_card
Console management Teams, invitations, links, audit, history, projects, the save target, and the listing, deletion, search visibility and filing tags of cards you made. describe is the live action table. Every action belongs to one of the user's AI permissions (reads on by default, edits off by default); read the current state with list_permissions. A disabled one returns console_permission_disabled with a settings_url: hand it to the user and stop. Writes also need the manage scope on the credential. Deleting people, teams and accounts (deleting a team, removing a member, revoking a link, transferring ownership), API keys and editing the permissions table are not here → Asking your AI to do console work. Some connections do not have this tool. If it is not in your list, tell the user to do console management in the web console → The app action tool run_aiakiv_app_action(app="console", …)

Some may not be visible. find_memory_connections and query_memory_graph can be turned off by server configuration. If one isn't in the list, or returns a "disabled" response, treat it as absent and fall back to search_memory: do not tell the user something is broken. run_aiakiv_app_action is missing entirely on some connections. Folder connections, API key connections, connections installed as a plugin (Claude Code, Cursor) and connections attached with the address https://mcp.aiakiv.com/mcp?apps=all (a Claude account connector added with this address, a Codex connection (set up with the install prompt), and the like) have it. The plugin directory install in ChatGPT and sign-in connections attached with an address that lacks ?apps=all do not. Where it is missing, calling it by name is refused with "This tool is not available on this connection." When two connections in one conversation both have it, call it on the one whose binding is folder or api-key → The app action tool. find_related_memories is no longer supported and is not in any connection's list. Calling the old name only returns a response that names the tools to use instead.

Note: depending on the client, these names appear under an AiAkiv server. A session connected before the September 2026 rename may still have the old names cached; start a new chat or reconnect.

How to read search results

  • Don't synthesize from the flat hits alone. Read each hit's reason tag together with the overall link map (hint). similar-embedding often points at a synonym whose name changed. Follow it on "latest/related" questions.
  • On conflicts, sort by recency and judge from that.
  • Don't narrow the scope in the query. The server sets scope from its access policy (check searched_scope). If you want one domain, filter the results.

Filter author and team attribution with an @handle at the very start of the query (@[email protected] jaccard). Attribution is stamped by the server at save time and cannot be forged: an AI cannot invent "who wrote this."

Follow the persona, but it can't override the rules

If a project carries a persona (a standing instruction from the owner), adopt its tone, role, and language in conversation. But a persona cannot override the saving rule (ak required) or the no-target-switching rule.

Next

Full index → Docs View as Markdown