> 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/calling-vayl-from-code.md). # Calling Vayl from code Vayl is an **MCP server**: its tools are invoked over the Model Context Protocol — almost always by the **LLM in your agent or client**. When you want to drive it from your own code, use the small **Python or TypeScript client**, or a raw MCP client for any other language. ## The usual path: your agent calls the tools In a chat client (Claude Desktop, Cursor) or an agent framework, you don't call Vayl directly. You configure the server once (see the [Quickstart](/vayl-docs/documentation/getting-started/quickstart.md)); the model then calls `remember`, `recall`, and the rest as it needs them, from the tool descriptions Vayl advertises. > **You:** Remember we switched to Zustand. Behind the scenes the client issues an MCP tool call: ```json { "method": "tools/call", "params": { "name": "remember", "arguments": { "text": "We switched to Zustand", "user_id": "proj_7" } } } ``` You write the prompt; the model fills in the arguments. ## From Python — the `vayl` client `pip install vayl-mcp` ships a small **synchronous** client that wraps the MCP boilerplate, so you call methods instead of writing `tools/call` JSON: ```python from vayl import Vayl with Vayl(user_id="proj_7") as m: # local: spawns vayl-mcp over stdio m.remember("We use Postgres") print(m.recall("what database do we use?")) # -> "Postgres" # a shared team server (authenticated streamable-HTTP): # with Vayl(url="https://memory.example.com/mcp", api_key="vayl_sk_…") as m: ... ``` `remember` / `recall` / `forget` are named methods; **any** other tool is `m.call("check_before_act", subject="…")`. A default `user_id` / `agent_id` / `run_id` set on the client is sent on every call (only to tools that accept it). ## From TypeScript — the `vayl` client The same surface for TS/JS agents (`npm install vayl`): ```ts import { Vayl } from "vayl"; const m = await Vayl.connect({ userId: "proj_7" }); // stdio: spawns vayl-mcp await m.remember("We use Postgres"); console.log(await m.recall("what database do we use?")); // -> "Postgres" await m.close(); ``` `m.remember` / `m.recall` / `m.forget`, and `m.call(tool, args)` for any other tool. ## Raw MCP client (any language, no SDK) The clients above wrap a standard MCP session. In another language, or for direct control, talk MCP yourself. Python over **stdio**: ```python import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client params = StdioServerParameters( command="vayl-mcp", env={"OPENAI_API_KEY": "sk-…", "VAYL_DB": "/abs/vayl.db"}, ) async def main(): async with stdio_client(params) as (read, write), ClientSession(read, write) as session: await session.initialize() await session.call_tool("remember", {"text": "We use Postgres", "user_id": "proj_7"}) res = await session.call_tool("recall", {"question": "what database do we use?", "user_id": "proj_7"}) print(res.content[0].text) # -> "Postgres" asyncio.run(main()) ``` Against a **team server** (HTTP + Bearer): ```python from mcp import ClientSession from mcp.client.streamable_http import streamablehttp_client async def main(): headers = {"Authorization": "Bearer vayl_sk_…"} async with streamablehttp_client("https://memory.example.com/mcp", headers=headers) as (r, w, _), ClientSession(r, w) as session: await session.initialize() res = await session.call_tool("recall", {"question": "what plan is the customer on?", "user_id": "cust_5521"}) print(res.content[0].text) ``` Or a raw JSON-RPC call for a quick check: ```bash curl -sN https://memory.example.com/mcp \ -H "Authorization: Bearer vayl_sk_…" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call", "params":{"name":"recall","arguments":{"question":"what plan?","user_id":"cust_5521"}}}' ``` {% hint style="info" %} The tool names and arguments are identical across every path — the SDKs, raw stdio, raw HTTP, and the model's own calls. Only the transport and auth differ. {% endhint %} ## Discovering the exact schema Signatures in these docs are a guide. For the exact, always-current arguments of every tool, call `tools/list` from any MCP client: ```python tools = await session.list_tools() for t in tools.tools: print(t.name, t.inputSchema) ``` ## Next steps

:database: Memory tools

Every tool you'll call — arguments and returns./pages/atmh20zKFo3dWE6nALWX

:plug: The MCP interface

Transports, the call envelope, annotations, and errors./pages/81aEMdYPcN3Gx3TwvNGx

:wrench: Troubleshooting

When a call fails./pages/mfZYQlnK9vTGam5NpiLs
--- # 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/getting-started/calling-vayl-from-code.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.