<!-- Generated by scripts/generate-llms.mjs from docs/memories/mcp-server.md. Do not edit. -->

Source: https://qbash.com/docs/memories/mcp-server

# Distribution

A memory folder can be used by several applications, agents, and tasks at once. A task might save campaign results that an analyst reads in Claude, or a developer might leave investigation notes for the next Claude Code session. Each works with the documents stored in qbash, rather than a separate copy for each application.

## MCP and AI applications

Add the folder to an [MCP server](https://qbash.com/docs-markdown/mcp-servers/overview.md) to use it from Claude, ChatGPT, Grok Bot, Claude Code, Codex, Cursor, or another MCP client. Choose which [memory tools](https://qbash.com/docs-markdown/memories/mcp-server.md#memory-tools) to include: a reference library might need only reading and search, while a shared working folder also needs tools to create and update documents. The same server can include tasks and connector tools.

The [MCP server guide](https://qbash.com/docs-markdown/mcp-servers/overview.md#package) covers adding a folder, selecting its tools, and connecting your applications. You do not need RAG enabled to retrieve known documents or save notes. Enable it when you want agents to run vector search on the folder.

## Using memories with agents

An agent can use memories as shared reference material and as a record of its work. Connecting the folder makes its tools available, but the agent still needs to know when to read or update a document. It does not automatically synchronize conversation transcripts or load every document into each session.

### Session handoffs

Give ongoing work a stable document name, such as **Checkout incident investigation**. Ask the agent to read it before continuing and update it at useful checkpoints. For example, include this in the agent's instructions:

```text
Before investigating checkout errors, read "Checkout incident investigation"
from the Engineering memory tools. Check the date, affected release, and
evidence before relying on earlier findings.

After a test run or a useful finding, update the same document with the
current conclusion, evidence, unresolved questions, and next action.
Preserve relevant findings from other contributors. If the write needs
review, report that it is pending rather than saying it is published.
```

A short handoff document is often enough:

```markdown
# Checkout incident investigation

Updated: <date and time>
Release or commit: <version examined>

## Current finding
<What the evidence supports, and what remains uncertain.>

## Evidence
<Tests, results, relevant logs, and links to source material.>

## Next action
<The next check, its purpose, and any constraints.>

## Changes since the last update
<New findings and any earlier conclusion they replace.>
```

The agent can use `read_memories` to read the document by name or id, or `list_memories` to browse. To change part of it, `edit_memories` takes find-and-replace `edits`. Each old text must appear exactly once in the current document, so changes another contributor made elsewhere stay in place. To add to the end, `append` puts the text on a new line and needs no version. Replacing the whole body needs `base_version`, the version the agent read. If the document has changed since then, the edit is refused with the current version, and the agent reads it again. The document id keeps updates attached to the same document even if its name changes.

For related runbooks or past incidents, [enable RAG](https://qbash.com/docs-markdown/memories/overview.md#enabling-rag) and include `grep_memories` on the server. With `vector: true`, it searches the handoff documents by meaning once they are indexed.

If the folder requires review, a write opens a review instead of publishing. The result says `pending_review` and gives a `review_id`. Readers keep receiving accepted content until a person accepts the change. Writing or editing the same document again while that review is open updates it. `memory_reviews` with `mine: true` lists the agent's open reviews, and `edit_memories` with `withdraw_review: true` withdraws one. See [Task and agent writes](https://qbash.com/docs-markdown/memories/reviewing-changes.md#task-and-agent-writes).

## Using memories in tasks

In the task editor, open **Resources → Memory** and attach a folder. Enable **Read-only** for reference material, or allow writes when the task needs to save results. Save the task to keep the attachment.

Use the attached folder's name in `folder=`. For example, create a **Reporting** folder containing a **Metric definitions** document, then attach it to a task with `figures` and `week` inputs. The task can read the definitions and earlier reports, write this week's report, and save it for future runs:

```python title="main.py"
definitions = qbash.memories.get("Metric definitions", folder="Reporting")
previous_reports = qbash.memories.query(
    metadata={"report_type": "weekly"},
    folder="Reporting",
)

report = qbash.ai.raw(
    f"Write this week's report using these metric definitions:\n"
    f"{definitions['content']}\n\n"
    f"Previous reports:\n{previous_reports}\n\n"
    f"This week's figures:\n{qbash.inputs.get('figures')}"
)

result = qbash.memories.store(
    name=f"Weekly report - {qbash.inputs.get('week')}",
    content=report,
    metadata={"report_type": "weekly"},
    folder="Reporting",
)

if result.get("status") == "pending_review":
    print("Report submitted for review:", result["pull_request_id"])
```

`store` creates a document, and `update` changes an existing one by ID. Use `update` when maintaining the same document between runs. `store(file=...)` accepts a qbash file reference instead of Markdown content.

A memory-folder input can supply `folder_id=` at runtime when each person running the task should choose their own folder. Use either `folder` or `folder_id`, not both. Full signatures and response fields are in the [SDK reference](https://qbash.com/docs-markdown/tasks/sdk-reference.md#module-memories).

The task's bundled Markdown files are separate from shared memory folders. A read without a folder targets those files. Writes require an explicit folder.

### Reading and searching

Use the method that matches what you know about the document:

| What you know | Task SDK | Result |
|---|---|---|
| Its exact name | `qbash.memories.get(name, folder=...)` | One document and its content |
| Its metadata | `qbash.memories.query(metadata={...}, folder=...)` | Documents matching every supplied field |
| A word or phrase | `qbash.memories.search(query, folder=...)` | Whole documents matching the keyword |
| The subject or question | `qbash.memories.vector_search(query, folder=...)` | Relevant chunks with similarity scores |

Exact lookup, metadata filters, listing, and keyword search work without RAG enabled. Metadata filters compare exact values and types. Keyword search covers names, metadata, attached filenames, and Markdown bodies. Use semantic search to find passages in uploaded files.

For example, attach **Support knowledge** with **Searchable by AI** enabled, then retrieve passages to supply to a prompt:

```python
context = qbash.memories.vector_search(
    query="How do we handle duplicate billing?",
    folder="Support knowledge",
    limit=5,
)
```

Semantic search returns chunks, so several matches may come from the same document. Start with the default similarity threshold and retrieve the source document when a passage needs more context.

## Memory tools

On a custom server, a memory folder's tools are limited to that folder, so calls don't name a folder. The server's owner chooses which tools to include and can rename them. Use the names and argument schemas shown in the connected client's tool list. The [official MCP server](https://qbash.com/docs-markdown/mcp-servers/official-mcp-server.md) serves the same tools for every folder you can access, and there each call names its folders.

| Tool | Arguments and result |
|---|---|
| `list_memories` | Lists documents without their bodies: id, name, metadata, version, and when and by whom each was last changed. Filter on metadata with a value, a list of values, a range, or whether a key exists. Sort by name, `updated_at`, or a metadata key. Results come a page at a time, with `limit` and `cursor`. |
| `grep_memories` | Returns the lines that contain `pattern`, with each document's id, name, and line number. Set `regex` for a regular expression, `context` for surrounding lines, or `output` to `names` or `count`. In a folder with **Searchable by AI** enabled, `vector: true` treats `pattern` as a question or topic and returns matching documents with a snippet and a score. |
| `read_memories` | Reads up to 20 documents by id, or by exact name. Returns content, metadata, `version`, and `open_review_id` when you have a review open on it. Pass `version` for an earlier version, or `lines` (such as `120-240`) for part of a long document. |
| `write_memories` | Creates up to 100 Markdown documents, each with a name not already used in the folder. Returns each document's id and version, or `pending_review` with a `review_id` when the folder requires review. |
| `edit_memories` | Changes up to 100 documents by id with find-and-replace `edits`, a new `content` body, text to `append` on a new line, `metadata` to merge (a null value removes a key), or a new `name`. Replacing the body or renaming needs `base_version`. `archived` archives or restores a document, and `withdraw_review` withdraws your open review. |
| `memory_history` | Lists a document's versions with author, time, and what changed. `from` and `to` return a diff, and `to: "review:<id>"` compares an open review with the current version. |
| `memory_reviews` | Lists reviews in the folder, open ones by default, or only yours with `mine: true`. With `id`, it shows one review's changes as diffs. Only a person in qbash can accept or reject a review. |

For a document made from an uploaded file, `grep_memories` matches its name, file name, and metadata. Vector search uses its indexed contents. Vector results may lag behind a published edit while indexing runs.