> 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/getting-started/your-first-memory.md). # Your first memory A hands-on walkthrough of storing, changing, removing, and recalling facts, with the MCP tool call and the real return behind each step. **Store a fact, change it, remove one, and read the history, with the MCP tool call and Vayl's return for each step.** In a chat client you just talk and the model makes these calls. To make them yourself, see [Calling Vayl from code](/vayl-docs/documentation/getting-started/calling-vayl-from-code.md). {% hint style="info" %} `remember`, `forget`, and `history` returns below are Vayl's exact output. Two things come from the model and can differ for you: the **subject names** (`plan`, `primary_database`) are chosen by the extracting LLM, and **`recall` answers** are free text written by the answering LLM. {% endhint %} ## Store facts > **You:** The customer is on the Pro plan, and their primary database is Postgres. ```json {"name": "remember", "arguments": {"text": "The customer is on the Pro plan, and their primary database is Postgres.", "user_id": "cust_1"}} ``` ``` Stored: [ADD] plan = Pro; [ADD] primary_database = Postgres ``` One message, two facts, both active. `user_id` picks the memory space; leave it out and the space is `default`. ## Supersede: a value changes > **You:** Actually, the customer moved to the Free plan. ```json {"name": "remember", "arguments": {"text": "Customer moved to the Free plan", "user_id": "cust_1"}} ``` ``` Stored: [SUPERSEDE] plan = Free ``` `plan` is now Free. Pro is marked `SUPERSEDED` and kept in history; it is no longer an active fact. ## Retract: a value is removed > **You:** We dropped the Postgres database. ```json {"name": "forget", "arguments": {"text": "We dropped the Postgres database", "user_id": "cust_1"}} ``` ``` Retracted (retained in history for audit): primary_database = Postgres ``` If nothing active matches, `forget` changes nothing and says so: ``` Nothing matching to retract (that fact isn't currently stored). ``` ## Ask what's true now ```json {"name": "recall", "arguments": {"question": "what plan is the customer on?", "user_id": "cust_1"}} ``` A model-generated answer from the active facts, for example `The customer is on the Free plan.` Asked about the database, it answers along the lines of "I don't know": the retracted fact is not loaded. ## See the provenance ```json {"name": "recall", "arguments": {"question": "what plan?", "user_id": "cust_1", "explain": true}} ``` The answer (model-generated), then the exact facts it was given, in Vayl's format: ``` The customer is on the Free plan. Based on these facts: • #3 plan = Free [conf 0.95, supersedes #1] ``` Each line shows the memory id, the fact, the extractor's confidence, the source if one was recorded, and what it superseded. ## Ask what changed ```json {"name": "history", "arguments": {"subject": "plan", "user_id": "cust_1"}} ``` ``` History for 'plan' (oldest → newest): 1. Pro [SUPERSEDED] 2. Free [ACTIVE] ``` For a question in plain language, `recall` with `"include_history": true` lets the model answer from retired facts too ("They were on Pro, then moved to Free."). It is off by default, which is why a normal recall cannot return a stale value. ## Next steps

:code: Calling Vayl from code

Make these calls from Python, TypeScript, or raw MCP.Calling Vayl from code

:book: Reconciliation

Every action and status, including flag and coexist.Reconciliation

:database: Memory tools

Full arguments and returns for each tool.Memory
--- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://vayl.gitbook.io/vayl-docs/documentation/getting-started/your-first-memory.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.