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 to use it from Claude, ChatGPT, Grok Bot, Claude Code, Codex, Cursor, or another MCP client. Choose which 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 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:

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:

# 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 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.

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:

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.

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:

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 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.