---
slug: for-ai-agents
title: "For AIs connected to AiAkiv"
description: "Written for an AI, not a person. Three rules, and a map of every tool the engine exposes."
lang: en
---


# For AIs connected to AiAkiv

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](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](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](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](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](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](cards) | `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.**

## Attribution search

Filter author and team attribution with an `@handle` at the **very start** of the
query (`@alice@example.com 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

- Working with several AIs → [Working with several AIs](working-with-ais)
- Troubleshooting → [Common problems](faq)