# The MCP tools list: five memory, seven knowledge

Docs · Human page: https://quelvio.com/docs/tools · Machine view: https://quelvio.com/ai/docs/tools

## Tool definitions

The twelve tools of the server "quelvio": five `memory_*` and seven `knowledge_*`. A person's own assistant is offered the seven `knowledge_*` tools only.

## The twelve tools

Over MCP each tool returns a text block; the HTTP route at `https://api.quelvio.com` returns the JSON. The text holds only the sources' or the people's words, fixed lines and fields. Its first line inside the block says the words are records, not instructions.

| Tool | Returns | Runs |
| --- | --- | --- |
| `memory_start` | The session id, then the rules block and the chosen memories | 0 |
| `memory_recall` | The memories for a question and a step | 0 |
| `memory_save_turn` | For a request: its id and context. For a reply: ok | 0 |
| `memory_end` | ok | 0 |
| `memory_trace` | A memory's Memory trace: what happened to it, line by line, oldest first | 0 |
| `knowledge_scope` | The repositories the key may read, and until when | 0 |
| `knowledge_ask` | The answer: outcome, evidence, notes and the other lists | 1 |
| `knowledge_search` | The passages that match, in search order, with no judging | 1 |
| `knowledge_open` | One passage by id, or a section's passages, each with whether it is still live and what replaced it | 0 |
| `knowledge_changes` | Every change since a time, with a `served` flag | 1 |
| `knowledge_propose` | A proposed correction, which changes nothing until a person accepts it | 0 |
| `knowledge_trace` | An answer's Answer trace, by its answer id: how the answer was made, line by line | 0 |

- Every tool takes `session_id`, the Quelvio session id from the line "Quelvio session: {id}" or from memory_start.
- Every answer also holds `consent`: "none", "serve_only" or "full".
- A run is one call to `knowledge_ask`, `knowledge_search` or `knowledge_changes`, answered. The other nine tools are free.
- A person's own assistant signs in as that person, and is offered the seven `knowledge_*` tools only.

## memory_start

Opens a session and returns the person's rules, then the memories for the request. A hook agent doesn't call it: memories already arrive at each prompt.

**Arguments**

| Argument | Type | Cap | If missing |
| --- | --- | --- | --- |
| `prompt` | string | The request, word for word | Required |
| `project` | string | The project id | The agent's default project |
| `parent` | string | The parent session id | No parent |
| `session_id` | string | On every call after the first | A new session |

**Returns:** `session_id`, issued by the server; `prompt_id`; `text`, the whole rules block, then the chosen memories; `degraded`, and `reason` if degraded.

**Runs:** 0

## memory_recall

Asks memory a short question before a step. Rules not yet delivered come first. A question repeated within 10 minutes gets the same answer.

**Arguments**

| Argument | Type | Cap | If missing |
| --- | --- | --- | --- |
| `query` | string | A short question | Required |
| `step` | string | What the agent is about to do | Required |
| `session_id` | string | The session id | Required |

**Returns:** `text` and `degraded`. With nothing to add: "Nothing new in memory for this."

**Runs:** 0

## memory_save_turn

For agents without hooks: passes each request and each final reply. Where hooks capture the session, it stores nothing.

**Arguments**

| Argument | Type | Cap | If missing |
| --- | --- | --- | --- |
| `session_id` | string | The session id | Required |
| `kind` | string | prompt or reply | Required |
| `speaker` | string | person or agent | Required |
| `text` | string | The words, exactly as received or given | Required |
| `reply_to` | string | For a reply: the id of the prompt it answers | Required for a reply |

**Returns:** For a prompt: the prompt's id, `text` and `degraded`. For a reply: ok.

**Runs:** 0

## memory_end

For agents without hooks: closes the session.

**Arguments**

| Argument | Type | Cap | If missing |
| --- | --- | --- | --- |
| `session_id` | string | The session id | Required |

**Returns:** ok

**Runs:** 0

## memory_trace

Returns a memory's Memory trace: what happened to it, line by line, oldest first, in fixed words, then the numbers under Details. It is built when it is opened, and asks no model anything. It answers only for a memory in the session's audience; any other reference, a deleted or erased memory's included, gets the not-found sentence. On a hooks connection it answers, as memory_recall does.

**Arguments**

| Argument | Type | Cap | If missing |
| --- | --- | --- | --- |
| `session_id` | string | The session id | Required |
| `memory` | string | The reference at the end of a memory's label, such as #k3x9vq, or the memory's id | Required |
| `from` | integer | The line to start at | 1 |

**Returns:** `text`: one `<quelvio-trace>` block, the lines, then their Details, at most 2,000 tokens, ending "More: lines {n} to {m}. Call memory_trace with from {n}." when there is more. Over MCP, beside it, the same answer as structured content: `records_notice`, `id`, `consent`, `lines` and `more`. With no trace to show: "Quelvio has no trace of {ref} for this session."

**Runs:** 0

## knowledge_scope

Lists the repositories the key may read, and until when.

**Arguments**

| Argument | Type | Cap | If missing |
| --- | --- | --- | --- |
| `session_id` | string | One id | The text block has no id |

**Returns:** `id`; `acting_for`, a person or no one; `agent`, the key's agent; `repositories`, each with its `id`, `name`, `via` (person or grant) and `until`.

**Runs:** 0

## knowledge_ask

Returns the answer to a question. The answer is evidence, in the sources' own words.

**Arguments**

| Argument | Type | Cap | If missing |
| --- | --- | --- | --- |
| `question` | string | 2,000 characters | 422 |
| `repositories` | array of repository ids | 20 ids | Every repository the key may read |
| `as_of` | date, YYYY-MM-DD | Not after today | The time is read from the question |
| `session_id` | string | One id | The text block has no id |

**Returns:** `id`; `outcome`: answered, partly answered, possible or not found; `evidence`, the passages that answer, each with its words, highlighted sentences, document, section, dates, status, authority and link; `notes`; `related`, the passages that may answer, or the nearest ones; `documents`; `changes`; `search`: full, or keywords only.

**Runs:** 1

## knowledge_search

Returns the passages that match, in search order, with no judging.

**Arguments**

| Argument | Type | Cap | If missing |
| --- | --- | --- | --- |
| `query` | string | 2,000 characters | 422 |
| `repositories` | array of repository ids | 20 ids | Every repository the key may read |
| `as_of` | date | Not after today | Live passages, and passages not yet in effect |
| `limit` | integer | 1 to 40 | 10 |
| `session_id` | string | One id | The text block has no id |

**Returns:** `id`; `search`: full, or keywords only; `passages`, in search order.

**Runs:** 1

## knowledge_open

Opens one passage by id, or the passages of one section of a document. This is how an agent checks that something still stands before acting on it.

**Arguments**

| Argument | Type | Cap | If missing |
| --- | --- | --- | --- |
| `passage` | string, a passage id | One id | Give this, or document with section |
| `document` | string, a document id | One id | As above |
| `section` | array of strings, a heading path | 10 headings | The whole document |
| `limit` | integer | 1 to 50 | 50 |
| `cursor` | string | From the previous answer | The first page |
| `session_id` | string | One id | The text block has no id |

**Returns:** `id`; `passages`, each with its place in the version, what replaced it and when, when it was removed, and since when a newer version has waited for approval; `reading`; `cursor`.

**Runs:** 0

## knowledge_changes

Lists every change since a time in the documents the key may read, newest first. `served` says whether this agent was served the old text. Nothing is pushed: each agent asks.

**Arguments**

| Argument | Type | Cap | If missing |
| --- | --- | --- | --- |
| `since` | date-time | Not in the future | 422 |
| `repositories` | array of repository ids | 20 ids | Every repository the key may read |
| `limit` | integer | 1 to 50 | 50 |
| `cursor` | string | From the previous answer | The first page |
| `session_id` | string | One id | The text block has no id |

**Returns:** `id`; `changes`, each with its time, document, kind (reworded, changed, added, removed, moved, or a document added, removed, withdrawn or expired), the old and new words, `served` and `withheld`; `until`; `cursor`.

**Runs:** 1

## knowledge_propose

Proposes a correction to the sentences of one passage. It becomes a "Proposed by an agent" item for the repository's approvers and owners, and changes nothing until a person accepts it. An agent may have 20 open proposals in one repository.

**Arguments**

| Argument | Type | Cap | If missing |
| --- | --- | --- | --- |
| `passage` | string, a passage id | One id | 422 |
| `text` | string: the right words | 8,000 characters | 422 |
| `reason` | string | 1,000 characters | 422 |
| `request_id` | string | 64 characters | A new call |
| `session_id` | string | One id | The text block has no id |

**Returns:** `id`; `received`: true; `proposal`, its id; `status`: waiting for a person; `redacted`: true when scrubbing removed something.

**Runs:** 0

## knowledge_trace

Returns an answer's Answer trace: how it was made, line by line, oldest first, in fixed words, then the numbers under Details. It is built when it is opened, and asks no model anything. An answer id that is unknown, erased, or not the caller's to see gets what an unknown one gets.

**Arguments**

| Argument | Type | Cap | If missing |
| --- | --- | --- | --- |
| `answer` | string, the answer id: the JSON's `id`, and the `answer` attribute of the answer's block | One id | 422 |
| `from` | integer, the line to start at | At least 1 | 1 |
| `session_id` | string | One id | The text block has no id |

**Returns:** `id`; `lines`, each `{n, at, kind, words, details}`, oldest first; `more`, the next line's number, or null at the end. The text is one `<quelvio-knowledge>` block of at most 2,000 tokens, ending "More: lines {n} to {m}. Call knowledge_trace with from {n}." when there is more. With no trace to show: an empty `lines`, and "Quelvio has no trace of {answer id} for you."

**Runs:** 0

## Related

- [Human view of this page](https://quelvio.com/docs/tools)
- [Everything for agents: llms.txt](https://quelvio.com/llms.txt)