AiAkiv Memory

List the projects the signed-in account can save to or read. Use this when the user asks which projects they have, which one they are saving to, or wants to move their saves elsewhere. Do not use it to perform the switch — no tool can move the account-wide target; the user's click on a project's `switch_link` is the switch. Read-only. Returns: `{projects: [{project, team, save_domain, save_group, is_main, is_this_connection, read_only?, switch_url, switch_link}], main_project, display, note}`. Each `switch_link` is a clickable link; the user's click on it performs the switch. `is_main` marks the account-wide target; `is_this_connection` marks the project this connection is folder-bound to. Entries with `read_only` are public targets the account can read without owning a preset, such as a shared demo. A wanted memory is located by its `team`, not by an exact project name.

Return events in chronological order for an entity, tag group, or domain. Use this when the user asks how something developed over time, or what happened in a period. Do not use it to rank by relevance to a question; use `search_memory` for that. Read-only. The domain is decided by the server and reported in `searched_scope`. Args: entity_id: Return events involving this entity, from `find_memories_by_entity`. cg_id: Return events carrying this tag group, named by the group ids in a search response's `hint.categories`. days: Restrict to the last N days. limit: 1-200 (default 20). Returns: `{mode, anchor, events, total, truncated, searched_scope}`. With neither `entity_id` nor `cg_id`, the flow covers the whole domain.

List the org links the caller can read through, and whether each works now. Use this when the user asks which partner teams they can read, or when a link tool returned an error and the reason needs checking. Do not use it to read partner content; the `mweft_link_*` tools do that. Read-only and local: it keeps answering while the partner org is down, which is when its answer matters most. Returns: `{status, count, links: [{link_id, partner_org_id, status, usable, blocked_reason, contract_version, reconsent: {mine, partner}, expires_at, created_at}]}`. `link_id` is what every `mweft_link_*` tool takes, and `usable` says which links will answer. `blocked_reason` names what to fix: `link_not_active` (suspended, pending, or revoked), `contract_version_too_old` (both owners re-consent — `reconsent` says who is missing), `principal_not_active` (this direction is closed), or `we_are_provider` (links run one way and this side issued the invite, so the other team reads our memory and there is nothing here to read). An empty list is an honest empty, not an error.

Run a read-only SQL query against the memory database. Use this when the user wants exact counts, aggregates, or table-level facts that a semantic search cannot give. Do not use it to change data: SELECT and WITH statements only. Read-only. Access control is applied by the server, so rows outside the caller's permissions never appear. A LIMIT and a statement timeout are applied automatically. Args: sql: A SELECT or WITH statement. `describe_memory_schema` returns the table and column names to write it against. max_rows: Automatic LIMIT cap, preserved when the query already sets one. Default 10000. timeout_ms: Postgres statement timeout in milliseconds. Default 5000.

Run a graph query, in a Cypher subset, over the caller's own memory graph. Use this when the user wants a structured traversal — shared-entity counts, paths between events, tag membership — that a text query cannot express. Do not use it for relational table facts; use `query_memories_with_sql` for that. Do not use it when the starting point is a sentence and no pattern is stated; use `find_memory_connections` for that. Read-only. The subset: a query opens with `START a = events(text: "..." | entity: "name or id" | ids: [...], k: n)`, so the anchor set is always events. Events reach events through `SHARES` (shared entities), `SIMILAR` and `FAR` (vector), and `NEXT`; entities through `PARTICIPATED_IN`, tags through `MEMBER_OF`. There is no `WITH` — conditions go in relation parameters such as `{min: 3}`. The rest is ordinary Cypher: `MATCH`, `WHERE`, `RETURN [DISTINCT]`, `ORDER BY`, `LIMIT`, aggregates in `RETURN`, `$name` parameters, and `cos(a, b)`. Example: `START a = events(text: $q, k: 3) MATCH (a)-[:PARTICIPATED_IN]-(e) -[:PARTICIPATED_IN]-(b) RETURN b, count(DISTINCT e) AS shared ORDER BY shared DESC LIMIT 20` Args: query: The graph query text. params: Values for `$name` references (strings, numbers, lists). Returns: `{columns, rows, row_count, start, partial, truncated, plan, budget, notes}`. Rows are projected: an Event to `{id, summary, timestamp, order_index}`, an Entity to `{id, name, type}`, a Tag to `{id, name}`. Budget caps are reported in `truncated`, never applied silently. Rejections come back as `{error, blocked_by: syntax|grammar|params, hint?, allowed_*}`.

Run the same graph query language across the caller's org and a partner org. Use this when the user asks how their own memory relates to a linked partner team's. Do not use it to read the partner alone; use `search_partner_memory` for that. Do not use it when the starting point is a sentence and no pattern is stated; use `find_partner_memory_connections` for that. Reads the partner org and writes nothing to either side. Calls are handled one at a time per org: a second link call issued while one is in flight comes back with `reason: busy` without running. Args: link_id: Which link to read through, from `list_partner_links`. query: The graph query text, same grammar and vocabulary as `query_memory_graph`. `START` resolves in the caller's org only; the walk crosses into the partner's events through entities the link has aliased, which count as one entity for `PARTICIPATED_IN` and `SHARES`. `NEXT`, `MEMBER_OF`, and `CONNECTED` stay within a side. params: Values for `$name` references. Returns: `{status, link_id, remote_org, columns, rows, row_count, start, partial, truncated, plan, budget, notes}`, or `{status: error, error, reason, detail}` where `error` repeats the reason code. A query the grammar rejects also carries `{blocked_by: syntax|grammar|params, hint?, allowed_*}`, as on the home path. Returned events carry `side` (`remote` = partner), and partner content opens with `get_partner_memory_content`. A `reason` names the state of the link, not a failure of the caller's own memory.

Create or query data in an AiAkiv app. Use this when the user asks to make or look up something in an AiAkiv app, for example a card built from a memory they already have. Do not use it to save a memory; use `save_memory` for that. Writes when `action="create"`. Some apps publish the result to the open web: the returned link is live the moment it comes back — unlisted, but reachable by anyone holding the address — and that publication cannot be undone from here. The content is written by the caller from memory the user can already read; the server never calls a model. Args: app: The app name. An unknown one returns `available_apps`. action: `"describe"` returns the app's field list and limits, which is how the exact input shape for an app is established; `"create"` writes. Apps may define further read actions, which `describe` lists. data: The app's payload — a JSON object, or a JSON string holding one. The string form survives transports that mangle long multi-line fields. Returns: `{ok, app, key, url, notice?}` on create, or `{error, hint}`. The returned `url` is the link to the created item. A `notice` is the app stating what just became public and how to undo it, which is information the user needs to see rather than a detail to compress away. On a shape error the app names the offending field.

Save a piece of conversation content to memory. Use this when the user explicitly asks to save or record something. Do not use it on a bare "remember this" or a request to summarize; those are not save requests. Writes a new record. The destination project and folder come from the active target and cannot be set from here. Args: payload: Alternative call form bundling {summary, entities, content, tags} into this one argument, as a JSON object or a JSON string. The other arguments are ignored when it is given. summary: The retrieval surface, required unless `payload`, up to 500 characters. Searches rank against this rather than the content, so exact identifiers kept verbatim and the acting party named in the first sentence are what make the record findable later. entities: NER results [{name, type}, ...], required unless `payload`. One canonical spelling per entity; records connect on shared names. tags: List of short slash-paths. Reusing the closest paths from a prior response's `suggested_tags` or `tag_tree` keeps them consistent. Ids, hashes, and dates are soft-rejected. content: The original text, required unless `payload`, up to 50000 characters. Longer text is split across calls, each passing the previous `event_id` as `prev_event_id`, with its own summary. prev_event_id: The prior call's `event_id` when this save continues it. allow_truncation_marker: Content carrying a truncation marker left by upstream tooling is refused with `truncation_marker_detected`, since nothing downstream can distinguish a cut body from a whole one. Set it True when the marker is part of what is being recorded. assert_project: The server refuses the save if the resolved target differs from this project name. It blocks, never redirects. timestamp: ISO 8601; defaults to the current time. source: Upstream origin `{provider, address, version?}` when the content came from outside this conversation. Returns: `{event_id, tags, tag_tree, suggested_tags?, saved_entities, rejected_tags?, continuation_hint, edit_command, active_target}`. `saved_entities` and `rejected_tags` let the user correct a wrong entity or a dropped tag through `update_memory`. `suggested_entities` is advisory — a literal name match does not establish that it denotes the same thing here.

Find stored memories that answer a question. Use this when the user asks about something that may already be recorded, or refers back to an earlier conversation, decision, or document. Do not use it to explore what surrounds an answer; use `find_related_memories` for that. Read-only. Scope is decided by the server from the signed-in account and reported in `searched_scope`. Args: query: One self-contained sentence. Resolving referents from the conversation and keeping exact identifiers intact both help it rank. top_k: Max hits (1-50, clamped). mode: `"hybrid"` (events + entities), `"events"`, or `"entities"`. principal: Restrict to content attributed to one user or team — a handle (email or team name) or a principal id, not a name to match. More than one match returns `principal_candidates` to re-call with. offset: How many top-ranked results to skip, for reading further down the same ranking. Defaults to 0, and is clamped to 200. A response that has more behind it names the continuing offset in `continuation`. Returns: `{query, mode, hits, total, hint, searched_scope}`. `hint` is a connection map over all results (threads, entities, categories, clusters, available_channels). Event hits may carry `connections.sequential {prev, next}`.

Search a linked partner org's memory. Use this when the user asks what a partner team has recorded about something. Do not use it to search the caller's own memory; use `search_memory` for that. Reads the partner org and writes nothing; a link is a read capability both orgs agreed to rather than a project to switch into, so the caller's own scope is untouched and `link_id` is passed per call. Results are the partner's events and stay theirs. Calls are handled one at a time per org: a second link call issued while one is in flight comes back with `reason: busy` without running. Args: sentence: One complete sentence, not keywords. link_id: Which link to read through, from `list_partner_links`. top_n: Max hits (server-capped at 50). domain: An optional single remote domain to narrow to. Returns: `{status, link_id, remote_org, hits: [{event_id, domain, summary, timestamp, distance, link_id}], count}`. With `status="error"` the `reason` (`no_links`, `contract_version_too_old`, `busy`, ...) describes the state of the link, not a failure of the caller's own memory. `event_id` feeds `get_partner_memory_content`.

Correct the entities, tags, and order links on a saved event. Use this when the user says a saved memory has a wrong or missing entity or tag, or that two saves belong in sequence. Do not use it to change the saved text; the stored content is never modified. Writes to an existing record. Args: event_id: The event to correct. remove_entities: Entity names or ids to unlink; orphans are deprecated. add_entities: New entities [{name, type}, ...]; creates one when the exact spelling does not exist. add_entity_ids: Existing entity ids to link, never creating. Each is re-validated; failures come back in `rejected_entity_ids`. Idempotent. add_tags: Tag paths to attach (same rules as `save_memory`). remove_tags: Tag leaf names or group ids to detach. add_prev_events: Event ids that come before this one, linking `other -> event_id`, for saves that belong together but were not chained at save time. remove_prev_events: Event ids to unlink from the front of this event. Links carrying document structure from ingestion are refused as `protected_source` and cannot be rebuilt. The direction is always "prev", so cutting a link on the other side means running this on the later event. An id in both lists is refused as `conflicting_request` and neither operation runs. Returns: `{event_id, removed_count, added_count, now_linked_entities, orphaned_entities, added_tags?, removed_tags?, rejected_tags?, rejected_entity_ids?, added_prev_events?, removed_prev_events?, rejected_prev_events?, graph_delta?}`. `graph_delta` reports the derived-layer re-sync when participation or tags actually changed; a link-only edit feeds no derived layer and carries none.