> For the complete documentation index, see [llms.txt](https://vayl.gitbook.io/vayl-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vayl.gitbook.io/vayl-docs/documentation/mcp-tools/memory.md). # Memory Store facts in plain language, then ask what's true now — these are Vayl's core reconciling-memory tools. `user_id?`, `agent_id?`, and `run_id?` are the optional memory-space keys (a `?` marks an optional argument). ## remember ```python remember(text, user_id?, agent_id?, run_id?, metadata?, source?) ``` Store fact(s) from a natural-language statement. Vayl extracts one or more structured facts and reconciles each — a new value **supersedes** the old, a removal **retracts**, and multiple facts in one message are all captured. | Argument | Description | | ---------- | ----------------------------------------------------------------------------- | | `text` | the statement (may contain several facts) | | `metadata` | tags applied to the facts stored in this call, e.g. `{"category": "allergy"}` | | `source` | who/what asserted it — belief provenance and source-aware reconciliation | **Returns** a summary of the reconciliation actions taken (supersede / retract / add / flag / dedup). **Example** ```json {"name": "remember", "arguments": {"text": "We switched from Redux to Zustand", "user_id": "proj_7"}} ``` ``` Stored: [SUPERSEDE] state = Zustand ``` ## recall ```python recall(question, user_id?, agent_id?, run_id?, explain?, include_history?, critical_categories?) ``` Answer a question using hybrid semantic + lexical retrieval over the **active** set. Returns the current value, or **"I don't know"** rather than guessing. | Argument | Description | | --------------------- | --------------------------------------------------------------------------------------------------- | | `question` | natural-language question | | `explain` | also return provenance — the exact facts used, each with source, confidence, and what it superseded | | `include_history` | reach retired facts, for questions about the past | | `critical_categories` | comma-separated categories forced into the answer regardless of ranking | **Example** ```json {"name": "recall", "arguments": {"question": "what state library do we use?", "user_id": "proj_7"}} ``` ``` Zustand ``` With `explain: true`, the answer is followed by the facts behind it: ``` Zustand Based on these facts: • #7 state = Zustand [conf 0.95, from alice, supersedes #3] ``` ## recall\_related ```python recall_related(question, user_id?, agent_id?, run_id?) ``` Answer deep / relational / multi-hop questions via the optional entity graph. Falls back to `recall` when the graph isn't enabled. ## history ```python history(subject, user_id?, agent_id?, run_id?) ``` Return the full change-log for a subject — every value it has held, oldest to newest, with status (ACTIVE / SUPERSEDED / RETRACTED). ## get\_memory ```python get_memory(memory_id, user_id?, agent_id?, run_id?) ``` Return one memory's structured detail: value, status, scope, confidence, `supersedes`, and metadata. Ids are shown as `#id` by `list_memories`. ## update\_memory ```python update_memory(memory_id, new_value, user_id?, agent_id?, run_id?) ``` Correct a memory by id — **audit-preserving**. The old value is retired to history and `new_value` becomes active. The human-edit path, distinct from the LLM-driven `remember`. ## forget ```python forget(text, user_id?, agent_id?, run_id?) ``` Retract a fact (*"we dropped Sentry"*). The fact is retired but **kept in history** for audit — a recall never returns it as current again. ## list\_memories ```python list_memories(user_id?, agent_id?, run_id?) ``` List the current active facts (each with its `#id`) plus a history block of what was superseded or retracted. ## Next steps

:compass: Your first memory

These tools in a hands-on walkthrough — store, correct, retract, recall./pages/c3101d8e098a6f696c75f6bda47d0ea5fdade1e5

:shield-halved: Safety and gating

Gate irreversible actions before your agent acts on a memory./pages/FXBBWNQcHGSp5V9G057o

:file-signature: Accountability

Snapshot what the agent believed and did, on a signed audit chain./pages/R2NPTpA8ljGHbWMvp6xn
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://vayl.gitbook.io/vayl-docs/documentation/mcp-tools/memory.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.