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. It does not perform the switch: 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, main_paused?, 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. `main_paused`, when present, means the user switched Main off in the console. A wanted memory is located by its `team`, not by an exact project name.

list_memory_projects

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_memory_timeline

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 partner tools (`search_partner_memory`, `find_partner_memory_connections`, `query_partner_memory_graph`, `get_partner_memory_content`) 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, provided_link_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 partner 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), `link_expired`, `remote_org_unavailable`, or `principal_not_active` (this direction is closed). Links run one way, and the ones **this** org provides are not listed: they open our memory to the other team, so there is nothing here to read and nothing to fix. `provided_link_count` (sent with the list) says how many exist — they are managed in the console, not through these tools. Passing one of their ids to a remote tool is refused with `principal_not_active`. An empty list is an honest empty, not an error.

list_partner_links

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.

query_memories_with_sql

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. `k` defaults to 5 and by default goes up to 20, or 200 with `entity:` alone. Events reach events through `SHARES` (shared entities), `SIMILAR` and `FAR` (vector), `NEXT`, and `RESOLVED_BY`, which runs `(plan)-[:RESOLVED_BY]->(evidence)` from a plan or expectation to the memory that realized it and carries `r.relation` and `r.asserted_at`; revoked links never appear. Events reach entities through `PARTICIPATED_IN` and tags through `MEMBER_OF`; entities reach entities through `CONNECTED` (stored co-occurrence) and `SAME_AS` (stored alias). 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)`. Without `LIMIT`, rows stop at 20; `LIMIT` goes up to 200. Name match: `WHERE e.name CONTAINS $part` keeps the rows whose `Entity.name` or `Tag.name` holds that piece, ignoring letter case and full-width forms. A piece that is all ASCII needs two characters; one Hangul or Han character is enough. It runs on the rows the walk already returned, so when `truncated` is non-empty an empty result means the piece was not seen in what was reached, not that no such name exists. Scoped start: `events(entity: $name, text: $q, k: n)` ranks, by closeness to `$q`, just the events that entity takes part in; `tag: $t, text: $q` does the same inside a tag, and `tag:` alone gives its newest events. A list, `entity: ["A", "B"]`, keeps events with any of the names; `entity_all:` or `tag_all:` keeps events with all of them; `entity:` with `tag:` keeps events matching both. Every part must hold and any name holds a part; there are no brackets, no negation and no entity-or-tag choice. Up to 10 names in all; `start.unresolved` lists the `{kind, name}` not found, and a part with no name found gives no rows. The combined starts take `k` up to 20 and `tag:` alone up to 200 by default; a server can set other caps, and `budget.caps` in the response shows the ones in force. Names match exactly, up to 20 entities or tags; `start.entities_truncated` or `tags_truncated` says more matched. `a.score` is the start event's cosine to the start text, null when there is no text and on events reached by a hop; nulls sort last, so use `ORDER BY a.score DESC, a.id` for a stable order. `start.scoped_mode` is `exact` or `filtered_ann` (a large scope searched through the vector index). `exact` measures every candidate's distance but returns only the top `k`; `start.has_more: true` says the scope holds more candidates than came back. A scope not fully covered (`filled: false` or a names cap) adds a `stage: start` entry to `truncated` and sets `partial` whatever the row count; 0 rows then means not confirmed, not absent. `MATCH` can be left out when the start itself is the answer: `START a = events(entity: $name, text: $q, k: 20) RETURN a, a.score ORDER BY a.score DESC, a.id`. An arrow left off a directed relation is filled in, with a line in `notes`, when the end labels allow one way only, as `(a)-[:MEMBER_OF]-(t)` from an event reads `->`; `NEXT` and `RESOLVED_BY` join two events and still need their arrow. 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, including a START cut short (`stage: start`), are reported in `truncated`, never applied silently. Rejections come back as `{error, blocked_by: syntax|grammar|params, hint?, allowed_*}`.

query_memory_graph

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. Name match: `WHERE e.name CONTAINS $part` works here too, on `Entity.name` and `Tag.name`, ignoring letter case and full-width forms, two characters for a piece that is all ASCII and one for Hangul or Han. It runs on the rows the walk already returned, so an empty result over a `truncated` walk means the piece was not seen, not that it is absent. Entities the link has aliased fold into one node under the home spelling, so the partner's own spelling of a name is not what this compares against. Scoped start: `entity:` or `tag:` together with `text:`, and `tag:` alone, work here too and resolve in the caller's org only, as do name lists (any), `entity_all:` or `tag_all:` (all) and `entity:` with `tag:` (both), with nothing beyond that shape. `a.score`, `scoped_mode`, `filled`, `has_more`, `unresolved`, `entities_truncated` and `budget.caps` mean what they mean on `query_memory_graph`. `exact` measures every candidate but returns only the top `k`, and `has_more: true` says more candidates remain in scope. An uncovered scope adds `stage: start` to `truncated`, and `a.score` is null on hop-reached events and sorts last, so use `ORDER BY a.score DESC, a.id` for a stable order. 0 rows with `filled: false` means not confirmed, not absent. `MATCH` can be left out when the start itself is the answer, as in `START a = events(entity: $name, text: $q, k: 20) RETURN a, a.score ORDER BY a.score DESC, a.id`; with no walk it returns only the caller's own events. A missing arrow on a directed relation is filled in as on `query_memory_graph`, with a line in `notes`. 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`, `CONNECTED`, and `RESOLVED_BY` 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.

query_partner_memory_graph

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 follow connections out from the memories it returns; use `query_memory_graph` 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"` (default) or `"events"` — both return event hits. `"entities"` is no longer supported and returns an error; to look an entity up by name call `find_memories_by_entity`. 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}`. Event hits may also carry `tags`: the memory's tags that narrow a search. To search within one, use `query_memory_graph` with `events(tag: <name>, text: <query>)`. `hint.categories` lists tags shared by two or more results; an entry may carry `total`, the number of memories with that tag.

search_memory

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`.

search_partner_memory

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, that two saves belong in sequence, or that something was renamed. 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: Tags to attach, existing or new, when the user asks for them. Same name rules as `save_memory`, with no limit on new tags. 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. add_resolved_by: Evidence events that resolved this one — items are `{"event_id": "...", "relation": "realization"}`, where `relation` defaults to `realization`. The direction is the opposite of `add_prev_events`: this event is the plan or intent, and each listed event is the evidence. Write access is needed on this event and read access on the peer. For `realization` this event must come from a registered app (`#plan`, `#novel`, ...) and both ends must sit in the same team part. revoke_resolved_by: Same item shape, taking the edge down. The revoke is soft: the assertion is preserved, and re-adding the same pair later revives it rather than creating a second edge. The same pair in both lists is refused as `conflicting_request`. add_entity_renames: Pairs `{"old": "...", "new": "..."}` (entity names or ids) recording that an entity was renamed, so a lookup by either name also returns the other. Both must already exist in this event's team; each pair also links both entities to this event. Idempotent; failures come back in `rejected_entity_renames`. remove_entity_renames: Same shape, removing such a pair. Entity links stay. A pair in both lists is refused as `conflicting_request`. 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?, added_resolved_by?, already_linked_resolved_by?, revoked_resolved_by?, rejected_resolved_by?, added_entity_renames?, removed_entity_renames?, rejected_entity_renames?, 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.

update_memory

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.