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

No tool can 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. 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 find_related_memories
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 Asking about relationships in a query language directly (Cypher subset, read-only) 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. Call describe first, and pass the response's notice before anything else. You cannot delete or edit → Cards §8 run_aiakiv_app_action(app="card", …)

Some may not be visible. find_related_memories, 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.

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