This is the full developer documentation for Membase Docs
# Membase Docs
> Create memory from your material, use it in your AI apps, or build an integration with the API. Start with the task you want to finish.
Create memory from your material, use it in your AI apps, or build an integration with the API. Start with the task you want to finish.
Membase keeps memory from your notes, files and conversations so you can use it with your assistant and the AI apps you connect. You choose what each app can read and can revoke access at any time.
## What do you want to do?
[Section titled “What do you want to do?”](#what-do-you-want-to-do)
[Use Membase](/use/getting-started/quickstart/)Create a Memory, add your material, run it, and ask a question about what it learned.
[Connect your AI](/connect/)Use your memory in Claude, ChatGPT, Cursor or another AI. Choose MCP or a skill, set it up, and verify access.
[Build with Membase](/build/getting-started/api-quickstart/)Use Python, TypeScript or REST to add a document, wait for learning, and search the result.
New to the product? Read [Concepts](/concepts/), or go straight to the [quickstart](/use/getting-started/quickstart/).
## Common tasks
[Section titled “Common tasks”](#common-tasks)
| I want to | Start here |
| --------------------------------------------- | -------------------------------------------------------------- |
| bring in files, Notion pages or conversations | [Sources](/use/bring-your-material-in/bring-material-in/) |
| keep a Memory up to date | [Schedules](/use/automate-and-troubleshoot/schedules/) |
| chat with my assistant from Telegram | [Telegram](/use/use-your-assistant/telegram/) |
| change what an app or key may use | [Connect and developer keys](/use/manage-your-memory/connect/) |
| understand a failed run | [Activity](/use/automate-and-troubleshoot/activity/) |
| put memory behind my own model | [Build with Membase](/build/) |
[Open Membase](https://app.membase.com) · [FAQ](/faq/) · [What’s new](/whats-new/)
Note
For AI readers, [`/llms.txt`](/llms.txt) points to the full and abridged text: [`/llms-full.txt`](/llms-full.txt) has all of it in one file, [`/llms-small.txt`](/llms-small.txt) a compact version.
# Build with Membase
> Start with one working API call sequence, then learn memory operations, integrate your model, and look up SDK and API details.
Start with one working API call sequence, then learn memory operations, integrate your model, and look up SDK and API details.
Use Membase from code to add material to a person’s memory and retrieve it for your app. Calls use that person’s developer key and the Memories they grant it. Python, TypeScript and REST all reach the same service at `https://api.app.membase.com`.
**Start with the [quickstart](/build/getting-started/api-quickstart/).** It creates one document, waits for learning to finish, and searches the result. The example includes the checks needed to distinguish an empty Memory from a failed search.
## Choose your next task
[Section titled “Choose your next task”](#choose-your-next-task)
| Task | Guide |
| -------------------------------------------------------------------- | ----------------------------------------------------------- |
| Add facts or documents, search, keep profile facts, forget or delete | [Memory operations](/build/guides/memory-operations/) |
| Serve multiple people | [Multi-user isolation](/build/guides/multi-user-isolation/) |
| Configure timeouts, retries or SDK methods | [SDKs](/build/reference/sdk-quickstart/) |
| Set access and reach, rotate or revoke a credential | [Authentication](/build/reference/authentication/) |
| Look up an endpoint or response shape | [API reference](/build/reference/api-reference/) |
| Fix a failed request or unread document | [API troubleshooting](/build/reference/troubleshooting/) |
## Integrations
[Section titled “Integrations”](#integrations)
| Your application | Guide |
| --------------------------------------------------- | ------------------------------------------------------------ |
| Claude API | [Claude API](/build/integrations/claude-api/) |
| OpenAI API or a function-calling model | [OpenAI API](/build/integrations/openai-api/) |
| An agent framework that speaks MCP | [MCP frameworks](/build/integrations/mcp-frameworks/) |
| A coding assistant building the integration for you | [AI coding assistants](/build/integrations/ai-coding-tools/) |
If you want to give an existing AI app your memory without building an integration, use [Connect your AI](/connect/).
## Understand the model
[Section titled “Understand the model”](#understand-the-model)
A **Memory** is a named space of memory in the app; a **memory** (`mem_…`) is a fact it learned, a **document** (`doc_…`) is material handed in, **media** (`med_…`) a photo or video. No request names a Memory: a credential reads every Memory it reaches and writes to the one it reaches. A Memory is a topic, not an end user.
[Platform overview](/build/concepts/platform-overview/) maps these objects to the app. [How Membase works](/build/concepts/how-membase-works/) explains learning, retrieval and model requirements. The [engine benchmark report](/evaluation/benchmarks/) is separate from API setup and performance guidance.
# How Membase works
> How documents become memory, how search behaves, and how models and access settings affect API calls.
How documents become memory, how search behaves, and how models and access settings affect API calls.
This page describes the behavior an integration needs to handle: learning from documents, searching memory, choosing a model and checking access.
## Accounts and Memories
[Section titled “Accounts and Memories”](#accounts-and-memories)
Each account owns its Memories, sources and access settings. No API request names a Memory: a credential reads every Memory the owner let it reach, and writes land in the one text Memory it reaches. Answers name the Memory they came from (`memory_name`). Use the account owner’s credentials; do not use Memories as isolation boundaries between different users. [Multi-user isolation](/build/guides/multi-user-isolation/).
## Material becomes memory in a learning turn
[Section titled “Material becomes memory in a learning turn”](#material-becomes-memory-in-a-learning-turn)
A **Memory** has an instruction describing what to retain and sources containing material to process. Adding or syncing a source does not mean the Memory has learned its contents.

Select **Update now** in the app or configure a schedule to process sources. The API’s `add_document` also requests learning and returns `202`; this acknowledges acceptance, not completed learning. Wait until the document’s `learning` status reads `succeeded` before searching for the new content. If processing fails, resolve the reported issue and update the Memory again. [Memory operations](/build/guides/memory-operations/).
## A search is a turn
[Section titled “A search is a turn”](#a-search-is-a-turn)
`search_memories` retrieves relevant passages from every Memory the credential reaches. Each result names its Memory (`memory_name`). `ask_memory` returns one answer the memory engine writes from the Memories in reach, with no agent and no tools; today only a marketplace buyer’s credential holds it.
* **Allow time for startup and retrieval.** A request after inactivity can take longer. The SDKs default to a 90-second timeout; some requests may need longer.
* **Check partial failures.** An HTTP `200` can still name Memories in `partial`. Do not report an empty search as “nothing found” until you have checked them.
* **Check what the limit left out.** A Memory in `partial` with `reason: "truncated"` had passages that did not fit `limit`; its silence is about the budget, not about what it knows. Raise `limit` to hear it.
* **Use the supported search fields.** Search accepts `q`, a `limit` and a `mode` (`full` or `fast`). Metadata filters are not supported, and an unknown field is refused; include relevant constraints in the query.
See [API troubleshooting](/build/reference/troubleshooting/) for timeouts and unavailable Memories.
## The profile
[Section titled “The profile”](#the-profile)
The profile holds standing statements about the user (`pf_…`: name, role, lasting preferences) separately from topic-specific Memories. Each says where it came from (`source_kind`: `user_stated`, `imported` or `model_generated`). List it with `list_profile_facts` when the credential grants profile access; a key whose level allows writes may also keep a statement (`add_profile_fact`) and, at Full access, forget one (`forget_profile_fact`, with `confirm=true`). There is no editing: a correction is a new statement and the old one forgotten.
## Models
[Section titled “Models”](#models)

Learning, hosted search and assistant replies require an available model. The account owner configures supported providers or subscriptions in **AI Setup** and selects the assistant’s model source in its settings.
When a model is unavailable, stored memory remains, but learning or search may fail. A turn can return `422` with `code: capability_unavailable`; search may instead name each affected Memory in `partial` with `reason: "error"`. A document can remain unread until the issue is resolved and learning completes. A free-plan account whose free allowance is used gets the same `422 · capability_unavailable`, with `details.reason: "dormant"`. Follow the returned recovery guidance.
## Access and confirmation
[Section titled “Access and confirmation”](#access-and-confirmation)
Developer keys have an access level, selected Memories and an expiry. MCP consent grants read access to the Memories the owner approves. Profile access is a separate setting. Changes to permissions apply to subsequent requests using the credential.
`forget_memory`, `delete_document`, `delete_media` and `forget_profile_fact` require Full access and `confirm=true`; without it nothing changes and the answer is `428 confirmation_required`. Obtain the owner’s confirmation before submitting one. Revoking a credential prevents future access through it; it does not erase results already received by an external client. [Authentication](/build/reference/authentication/) describes the permission rules.
## Where to go next
[Section titled “Where to go next”](#where-to-go-next)
| Task | Guide |
| -------------------------------- | ------------------------------------------------------- |
| Make a first call | [Quickstart](/build/getting-started/api-quickstart/) |
| Add, retrieve or remove content | [Memory operations](/build/guides/memory-operations/) |
| Look up an operation | [API reference](/build/reference/api-reference/) |
| Map the app to API concepts | [Platform overview](/build/concepts/platform-overview/) |
| Connect an AI app | [Connect your AI](/connect/) |
| Review engine evaluation results | [Benchmarks](/evaluation/benchmarks/) |
# Platform overview
> The hosted Membase at app.membase.com as your code meets it: the nouns, what each screen of the app is to the API, credentials, one account per person, limits, the Marketplace, and what can be undone.
The hosted Membase at app.membase.com as your code meets it: the nouns, what each screen of the app is to the API, credentials, one account per person, limits, the Marketplace, and what can be undone.
The Memory Platform is the hosted Membase at `https://app.membase.com`. A person hands it material once; it keeps a living memory of that material; every AI they connect, and every key they mint, reads the same memory. The mechanism is on [How Membase works](/build/concepts/how-membase-works/); this page is the product around it, written for someone whose code will meet what the person sees. The screens themselves, one page each, are in the **Use Membase** tab.
## The nouns
[Section titled “The nouns”](#the-nouns)
| API | In the app | What it is |
| ------------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Memory** (`memory_name` in answers) | a *Memory* | one named space of memory, with the agent that keeps it and the material it reads. Named in answers, never addressed in a request |
| **memory** (`mem_…`) | an item on a Memory’s page | one fact a Memory learned |
| **document** (`doc_…`) | a row under a Memory’s sources | one piece of material handed in: a file or a page (`kind: file`), or a fact as it was said (`kind: note`) |
| **media** (`med_…`) | a photo or video in a media Memory | what was seen or said in it, with its moments |

Plain verbs: `list`, `search`, `get`, `add`, `delete`, `forget`, `ask`. [Memory operations](/build/guides/memory-operations/) walks them; the [API reference](/build/reference/api-reference/) has every operation.
A **profile** sits beside the Memories: standing statements about the user (`pf_…`), each with where it came from (`source_kind`). `list_profile_facts` reads it; `add_profile_fact` and `forget_profile_fact` keep and forget one, on a key whose level allows it.
A credential reads every Memory it reaches; a write lands in the one text Memory it reaches, and a credential that reaches several is refused with `422 write_target_required`.
## The screens
[Section titled “The screens”](#the-screens)
| Screen | The person uses it to | Your code meets it as |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| [Home](/use/use-your-assistant/home/) | talk to the assistant, the one agent that is theirs by default; reach it on Telegram | the profile facts it records (`source_kind: model_generated`); the assistant’s own memory is not a Memory here |
| [Memory](/use/manage-your-memory/memory/) | make, run and inspect Memories | `search_memories`, `list_memories`, `get_memory`, the facts `forget_memory` removes; a document’s `learning` turning `succeeded` after a run |
| [Files](/use/bring-your-material-in/files/) | keep files, and hand folders, uploads, Notion pages and captured conversations to a Memory | `add_document`, `list_documents`, `get_document`, `delete_document` |
| [Studio](/use/advanced/studio/) | edit a Memory’s pipeline canvas | nothing |
| [Agents](/use/advanced/agents/) | build agents beyond the assistant | nothing; the memory API reaches Memories, not agents |
| [Schedules](/use/automate-and-troubleshoot/schedules/) | run Memories on a cadence | a document’s `learning` turning `succeeded` without a call of yours |
| [Activity](/use/automate-and-troubleshoot/activity/) | see what ran | the run a `202` from `add_document` started; a key’s own calls are on the key’s page |
| [AI Setup](/use/account-and-models/ai-setup/) | choose the account’s model | `422 · capability_unavailable` when there is none |
| [Connect](/use/manage-your-memory/connect/) | let an AI app read Memories, mint keys | consent tokens and developer keys: [Authentication & Scopes](/build/reference/authentication/) |
| [Marketplace](/use/share-and-trade/marketplace/) | sell and buy access to a Memory | a buyer’s credential, `ask_memory` |
| [Settings](/use/account-and-models/settings/) | plan, export, delete | `422 · capability_unavailable` with `details.reason: "dormant"` on a free plan whose turns are spent |
## Credentials
[Section titled “Credentials”](#credentials)
Every call carries a bearer: a **developer key** the owner minted, or a **consent token** an app received on the OAuth consent screen. A key has a level (Read, Read & write, Full access), a reach (the Memories it may use) and an expiry; a consent token is read-only and reaches what the user ticked. Both are managed by the account owner in **Connect**. [Authentication & Scopes](/build/reference/authentication/) has the whole model; the keys screen is under [Connect](/use/manage-your-memory/connect/#developer-keys) in the user guide.
A key’s calls are on the key’s page, not on Activity: **Usage** (calls in the last 30 or 7 days, how many were *refused*, the tool it calls most) and **Recent activity** (each call: tool, Memory, what came back, when; a refused call in red with the reason). The same numbers are on `GET /v1/keys/{id}/usage` with the owner’s session.
## One account per person
[Section titled “One account per person”](#one-account-per-person)
The account is the tenant. A Memory is a topic, not an end user. A product that serves many people gives each of them their own Membase account, and reads their memory with their own key or their own consent; there are no application-wide keys and no sub-tenant tags. [Multi-user isolation](/build/guides/multi-user-isolation/) has the patterns.
## Models
[Section titled “Models”](#models)
Every learning turn, every search and every assistant answer needs a model. The account chooses it under AI Setup: a key of its own for a provider, or a Claude or ChatGPT subscription. Follow the connection and verification steps shown in **AI Setup**. An account with no working model keeps its stored memory, but learning and hosted search need working agent turns. A search may name the Memories that could not answer in `partial`; documents can remain unread. [How Membase works](/build/concepts/how-membase-works/#models).
## Limits and errors
[Section titled “Limits and errors”](#limits-and-errors)
Search and every list name the Memories that could not answer in `partial` on an HTTP `200`. Check that field before treating an empty result as “nothing found.” [API troubleshooting](/build/reference/troubleshooting/) covers partial failures, deferred learning and timeouts.
| Status | Code | When |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| 400 | `validation` | an empty `q`, both or neither of `content` and `url`, a `limit` out of range |
| 401 | `unauthenticated` | no bearer token on the request |
| 403 | `unauthorized` | an invalid, expired or revoked key, or a verb above its level |
| 404 | `not_found` | an id that is not this credential’s to read: outside its reach, deleted, or not one of ours |
| 422 | `validation` | a missing, mistyped or unknown body field (`container` included); read `code` to tell it from the rows below |
| 422 | `write_target_required` | a write from a credential that reaches several Memories |
| 428 | `confirmation_required` | a delete or forget without `confirm=true`; nothing changed (a credential that holds no destructive verb gets `403` first) |
| 422 | `capability_unavailable` | the account’s memory cannot run a turn here (no agent container, no model) |
| 422 | `capability_unavailable` | with `details.reason: "dormant"`: a free-plan account whose free turns are spent |
| 429 | `rate_limited` | the account’s concurrent-turn budget, or the token’s per-minute request limit; retry later |
Uploads through `add_document` are capped at 32 MiB per file, on every plan. An account on the free plan whose free turns are spent keeps its memory but cannot run turns until it brings a model of its own under AI Setup or moves to a paid plan.
## Marketplace
[Section titled “Marketplace”](#marketplace)
What is sold is a Memory, as answers (listing kind `memory`). The buyer’s credential reaches that one Memory and holds only `ask_memory`: answers, never the passages, documents, facts or the seller’s profile, and never a write. Every call re-checks the purchase and takes one call of the period’s allowance. A listing sold earlier as an agent endpoint is answered by its Memory the same way; the other listing kinds are retired, and existing purchases are served until they end. Check the listing’s **Included access** section. [Marketplace](/use/share-and-trade/marketplace/).
## Stopping and undoing
[Section titled “Stopping and undoing”](#stopping-and-undoing)
Revoking a key or disconnecting an app changes subsequent access. It does not erase content already received by the client. Pausing a schedule stops future scheduled runs; subscription changes follow the terms and dates shown for that purchase or plan.
Deleting a Memory removes its stored content. Deleting a conversation removes the transcript but retains information already saved to memory. Deleting account data retains the sign-in identity. Review the confirmation and export data you want to keep before deleting. [Concepts](/concepts/#stopping-and-undoing).
# API quickstart
> Use Python, TypeScript or curl to add a document, wait until the Memory has learned it, and search the result.
Use Python, TypeScript or curl to add a document, wait until the Memory has learned it, and search the result.
This walkthrough adds one note to a Memory, waits for learning to finish, and searches for what it said. Choose Python, TypeScript or curl; each follows the same sequence.
You need a Membase account, a Memory you can write to, and a working model with available turns. Create a Memory in the [app quickstart](/use/getting-started/quickstart/) and check [AI Setup](/use/account-and-models/ai-setup/) if a run cannot use a model.
## 1. Create a key
[Section titled “1. Create a key”](#1-create-a-key)
In the app, open **Connect › Skills › Manage keys › Create key**. Name the key, choose **Read & write**, and select exactly one Memory under **Memory access** for this walkthrough. Choose an expiry and create the key. Copy the token while it is shown; it is shown only once. The profile permission is optional and is not needed for this example.
One Memory matters: no request names a Memory, so a write lands in the key’s write target, the one text Memory it reaches. A key that reaches several is refused with `422 write_target_required` and nothing is written.
```bash
export MEMBASE_API_KEY="mbk_…"
```
The [key guide](/use/manage-your-memory/connect/#developer-keys) explains rotation and revocation. The curl example and the SDKs call `https://api.app.membase.com`. Point either SDK elsewhere with `base_url` / `baseUrl` or `MEMBASE_BASE_URL`.
## 2. Add, wait, then search
[Section titled “2. Add, wait, then search”](#2-add-wait-then-search)
`add` returns `202` with a receipt (`{id, kind, status, learning}`) when material is accepted; it does not promise that learning has finished. Read `documents.get(id)` until every entry of its `learning` is `succeeded` before searching for the new content. The status is `pending` while it waits for a run, `processing` while one reads it and `failed` when the run failed. The examples stop on a failed learning run and have a polling limit, so they cannot wait indefinitely.
* Python
Install with `pip install unibaseio-membase` (0.4.0 or newer), save this as `quickstart.py`, and run `python quickstart.py` in the shell where you exported the key.
```python
import time
from membase import Membase
client = Membase()
custom_id = "quickstart-ledger-v1"
added = client.add(
"We chose Postgres for the Lumen ledger.",
title="Lumen decision",
custom_id=custom_id,
)
document_id = added["id"]
if not document_id:
raise RuntimeError("Accepted, but the document id is pending. See API troubleshooting.")
for _ in range(60):
learning = client.documents.get(document_id).get("learning") or []
statuses = {entry["status"] for entry in learning}
if learning and statuses == {"succeeded"}:
break
if "failed" in statuses:
raise RuntimeError("Learning failed. Open the Memory's Report in the app.")
time.sleep(5)
else:
raise TimeoutError("Still unread. Check the Memory's Report and model settings before retrying.")
found = client.search("Which database did we choose for the Lumen ledger?")
errors = [p for p in found["partial"] if p["reason"] == "error"]
if errors:
raise RuntimeError(f"Some Memories could not answer: {errors}")
for hit in found["items"]:
print(hit["memory_name"], "·", hit["content"])
if not found["items"]:
print("No matching passages. Inspect the Memory and its latest Report in the app.")
```
* TypeScript
Install with `npm install @unibaseio/membase` (0.4.0 or newer) and run this in a server-side TypeScript project on Node 18 or newer. The package is ESM-only and the example uses top-level `await`, so the project must be an ES module: `"type": "module"` in `package.json`, or save the file as `quickstart.mts`. Keep the key on the server, outside browser bundles.
```ts
import { Membase } from "@unibaseio/membase";
const client = new Membase();
const customId = "quickstart-ledger-v1";
const added = await client.add({
content: "We chose Postgres for the Lumen ledger.",
title: "Lumen decision", customId,
});
const documentId = added.id;
if (!documentId) throw new Error("Accepted; document id pending. See API troubleshooting.");
let learned = false;
for (let attempt = 0; attempt < 60; attempt++) {
const { learning = [] } = await client.documents.get(documentId);
if (learning.length && learning.every(entry => entry.status === "succeeded")) { learned = true; break; }
if (learning.some(entry => entry.status === "failed")) {
throw new Error("Learning failed. Open the Memory's Report in the app.");
}
await new Promise(resolve => setTimeout(resolve, 5000));
}
if (!learned) throw new Error("Still unread. Check the Memory's Report and model settings.");
const found = await client.search({ q: "Which database did we choose for the Lumen ledger?" });
const errors = found.partial.filter(p => p.reason === "error");
if (errors.length) throw new Error(JSON.stringify(errors));
for (const hit of found.items) console.log(hit.memory_name, "·", hit.content);
if (!found.items.length) console.log("No matching passages. Inspect the Memory and its Report.");
```
* curl
Requires Bash, curl and `jq`. Save this as `quickstart.sh` and run `bash quickstart.sh` in the shell where you exported the key. A failed HTTP request stops the script.
```bash
set -euo pipefail
BASE=https://api.app.membase.com
AUTH="Authorization: Bearer $MEMBASE_API_KEY"
custom_id=quickstart-ledger-v1
payload=$(jq -n --arg id "$custom_id" \
'{content: "We chose Postgres for the Lumen ledger.", title: "Lumen decision", custom_id: $id}')
added=$(curl --fail-with-body -sS "$BASE/v1/documents/add" -H "$AUTH" \
-H 'Content-Type: application/json' -d "$payload")
document_id=$(jq -r '.id // empty' <<< "$added")
if [ -z "$document_id" ]; then
echo "Accepted, but document id pending. See API troubleshooting." >&2
exit 1
fi
learned=false
for ((attempt=0; attempt<60; attempt++)); do
document=$(curl --fail-with-body -sS "$BASE/v1/documents/$document_id" -H "$AUTH")
if jq -e '(.learning | length > 0) and all(.learning[]; .status == "succeeded")' <<< "$document" >/dev/null; then
learned=true
break
fi
if jq -e 'any(.learning[]; .status == "failed")' <<< "$document" >/dev/null; then
echo "Learning failed. Open the Memory's Report in the app." >&2
exit 1
fi
sleep 5
done
if [ "$learned" != true ]; then
echo "Still unread. Check the Memory's Report and model settings." >&2
exit 1
fi
payload=$(jq -n '{q: "Which database did we choose for the Lumen ledger?"}')
found=$(curl --fail-with-body -sS "$BASE/v1/search" -H "$AUTH" \
-H 'Content-Type: application/json' -d "$payload")
jq -e 'if any(.partial[]; .reason == "error") then error("A Memory could not answer; inspect partial") else . end' <<< "$found"
```
## 3. Check the result
[Section titled “3. Check the result”](#3-check-the-result)
Expect a passage naming Postgres and the Memory it came from. The exact wording can vary. An empty `items` list is not enough to diagnose a problem: inspect `partial` first (a Memory named there with `reason: "error"` could not answer), then the Memory’s learned content and latest **Report**.
Re-running this example with the same `custom_id` does not add a second copy: the receipt names the document already there. If learning was deferred or failed, fix the cause and run **Update now** in the app; resending the same document is not a way to force another learning run. See [API troubleshooting](/build/reference/troubleshooting/).
## Next steps
[Section titled “Next steps”](#next-steps)
* [Memory operations](/build/guides/memory-operations/): facts, profile facts, documents, search and deletion.
* [SDKs](/build/reference/sdk-quickstart/): configuration, errors and method signatures.
* [Authentication](/build/reference/authentication/): permissions, reach and expiry.
* [Integrations](/build/#integrations): put these calls behind your model or framework.
# Memory operations
> Every verb of the agent protocol end to end: Memories, search, facts, profile facts, documents, media, ask, forget and delete, what a run does to them, and what code sees when the app does something.
Every verb of the agent protocol end to end: Memories, search, facts, profile facts, documents, media, ask, forget and delete, what a run does to them, and what code sees when the app does something.
The API has a handful of nouns and verbs. This page walks them in the order a program meets them, says what each does inside the user’s account, and what code sees when the person, a schedule or the app does something on its side. Every snippet is the Python SDK; the TypeScript and REST shapes are on the [SDKs](/build/reference/sdk-quickstart/) and the [API reference](/build/reference/api-reference/).
| Noun | In the app | What it is | Id |
| ---------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| **Memory** | a *Memory* | one named space of memory, with the agent that keeps it and the material it reads; `text` or `media`. Named in answers (`memory_name`), never addressed in a request | — |
| **memory** | an item on a Memory’s page | one fact a Memory learned | `mem_…` |
| **profile fact** | a line under Settings › Your profile | one standing statement about the person (name, role, a lasting preference); the account’s, not a Memory’s | `pf_…` |
| **document** | a row under a Memory’s sources | one piece of raw material a Memory read: a file or page (`kind: file`), or a fact as it was said (`kind: note`) | `doc_…` |
| **media** | a photo or video in a media Memory | one photo or video, with its moments | `med_…` |
Ids are typed and opaque. An id outside the key’s reach, an id of the wrong type and a string that is not one of ours all answer `404`. Every list is `{items, has_more, partial}`: the newest `limit` (1–1000, default 100), whether more were left out, and the Memories that could not answer; there is no paging.

## Memories
[Section titled “Memories”](#memories)
```python
caps = client.capabilities()
caps["memories"] # [{"name": "Project decisions", "kind": "text"}, …]: what the key reaches
caps["actions"] # ["search", "memories.list", "memories.add", …]: what it may do
```
No request names a Memory. Reads (search, lists, ids) cover every Memory the key reaches; writes land in the key’s **write target**, the one text Memory it reaches. A key that reaches several text Memories is refused on a write with `422 write_target_required` (`WriteTargetRequiredError`) and nothing is written somewhere by guess. Sending a `container` is a `422` too: the API refuses fields it does not know. `capabilities()` names the Memories in reach by name and kind, never by id; it is not permission, and every call is still checked when made. A Memory outside the reach cannot be told apart from one that does not exist. The assistant’s own memory is not a Memory here: code meets what it knows about the person as profile facts.
What a Memory’s tile says in the app, and what it means to code:
| Tile word | Meaning | In the API |
| -------------- | ---------------------------------- | -------------------------------------------------------------- |
| *Add a source* | reads nothing yet | in reach, `list_documents` lists nothing from it |
| *On sale* | listed on the Marketplace | buyers hold credentials that `ask_memory` it, and nothing else |
| *Subscribed* | bought from someone else | `ask_memory` only; no passages, no documents, no writes |
| no word | yours, reading at least one source | in reach; searches answer from what its runs learned |
Renaming a Memory changes the `memory_name` answers carry; ids never change. Deleting a Memory is the owner’s, in the app, and has no agent-protocol verb.
## Search
[Section titled “Search”](#search)
```python
hits = client.search("what did we decide about the ledger", limit=5)
for h in hits["items"]:
print(h["memory_name"], "·", h["content"])
```
A search covers every Memory in reach at once, and each passage names its Memory (`memory_name`). Passages come most relevant first: `type: "memory"` is a learned fact and carries its `mem_` id (read it again with `memories.get(id)`), `type: "document"` is a passage from a document. `limit` is how many in all (1–50), not per Memory. `partial` names each Memory that could not answer (`reason: "error"`) or whose passages all lost to `limit` (`reason: "truncated"`); the others still answered. `mode="fast"` is one round of retrieval with no model call, for recall before every turn of an agent whose own model judges what it is handed; the default `full` is the engine’s whole retrieval.
A search is a **turn** inside the account’s container, not a query on an index. The first one after a quiet spell includes runtime startup; the SDKs default to 90 seconds per request, which is configurable and is not a latency guarantee. There are no metadata filters, because there is no server-side index to apply them to: put what matters in the content. Search is retrieval; `ask` is an answer.
A Memory with no learned content may return no results. Check `partial` before interpreting an empty result: an unavailable model is a failed search, not evidence that no matching memory exists. Search is not held to the two-turns-at-once limit, but like every call it can answer `429` when the token exceeds its per-minute request limit.
## Facts
[Section titled “Facts”](#facts)
```python
facts = client.memories.list(limit=20) # the newest facts, newest by when they happened
for f in facts["items"]:
print(f["id"], f["memory_name"], f["content"], f["source_time"])
client.memories.get("mem_…") # one fact, at any age
```
`memories.list` shows the facts the Memories in reach learned, newest by when they happened, each with its `mem_` id, `memory_name`, `source_time` (when it happened) and `recorded_at`. `memories.get` reads one, however old: a search can name one older than any list shows. Listing facts stands on the search grant, so any key that may search may list.
## Profile facts
[Section titled “Profile facts”](#profile-facts)
```python
facts = client.profile_facts.list(limit=50)
for f in facts["items"]:
print(f["id"], f["source_kind"], f["content"]) # "pf_…", "user_stated", "Prefers dark mode."
kept = client.profile_facts.add("Works in Lisbon, UTC+0.")
kept["id"], kept["created"] # "pf_…", True; the same statement again: False
client.profile_facts.forget("pf_…", confirm=True) # {"id": "pf_…", "status": "forgotten"}
```
The profile sits beside the Memories: a list of standing statements about the person, newest first. Each has its `pf_` id, `content`, `recorded_at` and `source_kind`, which says where it came from: `user_stated` (the owner or one of their keys said it), `imported`, or `model_generated` (the assistant recorded it in a conversation). The service sets `source_kind`; a request cannot.
`profile_facts.list` needs the profile tick on the key. With the tick, what else the key may do follows its level: a Read & write key may `add` a statement, a Full access key may also `forget` one, with the same confirmation rule as forgetting a memory (`428` without `confirm=true`). Without the tick no profile operation is offered at all. Adding a statement that is already there keeps the one there (`created: false`). There is no editing: a correction is a new statement and the old one forgotten. List the profile once, near the start of a conversation.
## Add a memory
[Section titled “Add a memory”](#add-a-memory)
```python
receipt = client.memories.add("We settled on Postgres for the ledger.")
receipt # {"id": "doc_…", "kind": "note", "status": "processing", "learning": [{"memory_name": "Project decisions", "status": "processing"}]}
```
One fact, into the key’s write target. It is written as a note the Memory reads, and this call starts its learning run asynchronously: it answers `202` with the note’s receipt, a document of kind `note`. Poll `documents.get(receipt["id"])` as for a document write; acceptance is not completion. To remove the note, pass its `doc_` id to `delete_document`; `forget_memory` takes the `mem_` id of a fact the Memory learned. Needs a Read & write key.
## Add a document
[Section titled “Add a document”](#add-a-document)
```python
doc = client.add("…the text…", title="Call with Acme", custom_id="call-2026-09-24")
doc["status"] # "pending" or "processing"
doc["id"] # "doc_…": poll documents.get(id)["learning"]
```
The text (or a public `url` to fetch, one or the other) lands in the write target’s upload folder in the account’s Files, is connected as a source on the spot, and a learning run starts on its own; the call answers `202` with the receipt `{id, kind: "file", status, learning}`. The same `custom_id` again names the document already there and starts nothing, so retries are safe. `id` can be `null` on the `202` when the folder sync had not written the row yet; list the documents a moment later. Uploads are capped at 32 MiB per file, on every plan.
### What the `202` becomes
[Section titled “What the 202 becomes”](#what-the-202-becomes)
When a learning run starts, it appears on the account’s Activity page. `learning` on the receipt and on `documents.get(id)` names each Memory with its status: `pending` (waiting for the next run; the one in flight starts it when it ends), `processing` (a run is reading it now), `succeeded` or `failed`. After a successful run over that material, search can retrieve what it learned. A `202` alone does not guarantee that a run started: it can be deferred while the agent is paused or capacity is unavailable. If it ends `failed`, the document is still listed and still unread, and the Memory’s Report says why; usually the account has no working model under AI Setup, or a source needs reauthorization.
### Documents
[Section titled “Documents”](#documents)
```python
docs = client.documents.list(kind="file")["items"] # newest first; kind is "file" or "note"
for d in docs:
detail = client.documents.get(d["id"])
print(d["id"], d["memory_name"], d["title"], [e["status"] for e in detail.get("learning") or []])
client.documents.delete("doc_…", confirm=True) # Full access
```
A document is one piece of raw material a Memory has read or will read: a file in a folder source, an uploaded file, a Notion page, a conversation the browser extension captured, or what `add_document` handed in, or the note `add_memory` wrote. Its `learning` reads `succeeded` once a run has committed it; it is the field to poll after a write. It is computed per source, not per document: succeeded when the Memory’s last successful run is at or after the source’s current version, under the Memory’s current instruction. So when a new file lands in the same upload folder, every document in that folder reads `pending` again until the next run, and changing the Memory’s instruction makes every document in it read `pending` until it has run again.
### Sync and run are two different things
[Section titled “Sync and run are two different things”](#sync-and-run-are-two-different-things)

A **sync** fetches raw material and stops. It runs no model, reads nothing into memory and never changes what a search answers. A **run** (the learning turn) is what reads the unread material. In the app the Memory’s button says **Update now** while a source holds material it has not read; a schedule does the same on a cadence; `add_document` starts a run itself. “Unread” is decided by versions, not clocks: a sync that changed nothing, or a run on another Memory, cannot make this one look up to date.
`add_document` normally starts learning without a schedule; if it is deferred, use the Memory’s next run after fixing the cause. A schedule matters for material that arrives without a call: a folder the person keeps adding to, a Notion selection that changes. When a schedule fires, nothing changes in the API except the memory itself: `learning` turns `succeeded` and the next search answers from what the run learned. There is no agent-protocol verb to create or pause a schedule; it is the owner’s, in the app.
## Media
[Section titled “Media”](#media)
```python
client.media.list(limit=20) # photos and videos, newest first, each with a one-sentence summary
hits = client.media.search("someone skiing", kind="video")
for m in hits["items"]:
print(m["memory_name"], m["filename"], [(x["t"], x["text"]) for x in m["moments"]])
client.media.get("med_…") # one item with all its moments
client.media.delete("med_…", confirm=True) # Full access
```
A media Memory holds photos and videos, apart from documents and facts: `search` and the fact and document lists do not read them. Each item has a `summary`, a `file_url` and a `thumb_url` (routes on the API, read with the same bearer; a `Range` header answers `206` with that part). `media.get` and `media.search` add its `moments`: a video’s shots and spoken lines, each with `t`/`end` in seconds, `speaker` and `thumb_url`. Adding media over the API is not offered yet; it arrives through the Memory’s sources in the app.
## Ask
[Section titled “Ask”](#ask)
```python
out = client.ask("Summarise what the seller learned about Postgres RLS.")
out["answer"] # one answer, written from the Memories in reach
out["citations"] # [{"memory_name": "Postgres notes"}]: the Memory, never the passages
out["partial"] # the Memories that could not answer
```
`ask` is the other kind of read next to search: the memory engine reads the Memories in reach and writes one answer, with no agent, no tools and no session. `citations` name the Memory the answer came from, never a passage. A `model` field is refused (`422`), like any field the API does not know.
`ask_memory` is held only when a credential’s tool list names it, and today only a marketplace buyer’s credential does: it reaches the one Memory bought, holds nothing else, and every call takes one call of the period’s allowance. A developer key does not hold it at any level, and the call is refused with `403 · unauthorized`. A product that wants to put a model over the person’s memory uses search and its own model ([Claude API](/build/integrations/claude-api/), [OpenAI API](/build/integrations/openai-api/)).
## Forget and delete
[Section titled “Forget and delete”](#forget-and-delete)
```python
from membase import ConfirmationRequiredError
try:
client.memories.forget("mem_…")
except ConfirmationRequiredError as e:
print(e.details) # {"id": "mem_…", "verb": "forget_memory", "content": "…", "how": "…"}
client.memories.forget("mem_…", confirm=True) # {"id": "mem_…", "status": "forgotten"}
client.documents.delete("doc_…", confirm=True) # {"id": "doc_…", "status": "deleted"}
```
`forget_memory` takes the `mem_` id of a learned fact, from `memories.list`, `memories.get` or a search hit of `type: "memory"`. A note added with `add_memory` is a document; remove it with `delete_document`.
Both need a Full access key (as do `media.delete` and `profile_facts.forget`, the latter with the profile tick), and even then they do not run on a bare call: without `confirm=true` nothing changes and the answer is `428 confirmation_required` (`ConfirmationRequiredError`), naming the target by its public id and carrying a `how` sentence to relay to the person. Pass `confirm=true` only after they agreed; from a developer key that counts as the owner’s confirmation. Forgetting a fact leaves the material it was learned from; deleting a document withdraws it and what every Memory learned from it (the file goes to the Files trash). A consent-minted client is never offered these verbs at all: its token is read-only, so from an AI app the call is refused with `403 · unauthorized · token missing required scope`, not answered with the sentence. What is forgotten or deleted is gone from the next search; nothing on the platform caches it.
Deleting a Memory, a source’s imported material or the account has no agent-protocol verb; those are the owner’s, in the app.
## Rules
[Section titled “Rules”](#rules)
```python
client.capabilities()["rules"]
```
`GET /v1/capabilities` carries the standing rules for this credential under `rules` (`citation_required`, `retention_notice`, `version`): what the skill tells an AI about behaving beneath the ceiling the server enforces. Over MCP the same answer is `get_capabilities`; there is no separate rules call.
## What code sees when the app does something
[Section titled “What code sees when the app does something”](#what-code-sees-when-the-app-does-something)
| The person | Code sees |
| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| selects **Update now**, or a schedule fires | documents’ `learning` turns `succeeded`; the next search answers from the run |
| switches a Memory off for the key under **Use in** | on the very next call, same token, searches and lists leave it out and its ids answer `404`; if the key is left with one text Memory, that one becomes its write target |
| lowers the key’s access | `403 · not in this agent's capability profile` on the verbs above it |
| revokes the key, or it expires | `403 · unauthorized` on every call; mint another |
| removes a source | its documents stop being listed; what was learned stays until the Memory is deleted |
| deletes the Memory | its `memory_name` no longer appears; searches no longer answer from it |
| has no working model for its agent | a failed turn, surfaced as `422 · capability_unavailable` or a search entry in `partial` (`reason: "error"`); stored memory remains, documents may wait unread. Read `code` on a `422`: `validation` there is a request the API cannot take, and `write_target_required` a write with nowhere to land, not a model problem |
| is on the free plan with its free turns spent | `422 · capability_unavailable` with `details.reason: "dormant"` until they bring a model or move to a paid plan |
| already has two agent turns running, or a token exceeds its per-minute request limit | `429 · rate_limited`. The turn limit hits agent turns (search is not held to it; `add_document` never is, its learning waits as `pending`); the per-minute limit hits any call, search and `add_document` included. No `Retry-After` is sent; the SDK backs off and retries twice |
## Rules of the road
[Section titled “Rules of the road”](#rules-of-the-road)
* **Profile once, search per question.** The profile facts are few and standing; search is a turn inside the user’s memory.
* **Cite the Memory.** Every hit names its Memory (`memory_name`); say where an answer came from.
* **Save what the user supplied,** in their words, and only when they asked or plainly meant to.
* **Never confirm on your own.** A delete or forget without `confirm=true` changes nothing and answers `428` with a `how` sentence; relay it and stop.
* **Treat `403` as withdrawn access.** The owner narrowed or revoked the key; do not retry with it.
* **Allow for cold starts.** Configure a suitable timeout and inspect `partial`; see [API troubleshooting](/build/reference/troubleshooting/).
* **Do not store to filter later.** There are no server-side metadata filters; use `custom_id` for your own bookkeeping.
* **The token stays out of logs.** Log the key’s hint (`mbk_7f3a92d1…`), never the token.
# Multi-user isolation
> The account is the tenant. What that means for a product that serves many people, and the three ways to reach each person's memory with their own credential.
The account is the tenant. What that means for a product that serves many people, and the three ways to reach each person’s memory with their own credential.
In Membase **the person owns the memory**, not the application. There is no application-wide key, no master credential and no per-user tag inside a shared store. Every credential belongs to one account, reaches only that account’s Memories, and was minted by that account’s owner.
If you have used a memory API where you tag content with a *user id* or *container tag* and one key reaches them all: that is not this. Here a Memory is one of the person’s own (a topic such as *Project decisions*), not a tenant, and no request names one.
## The boundary
[Section titled “The boundary”](#the-boundary)
| Layer | How it is separated |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Memory** | every account has its own agent container, a small VM with its own volume. Its files, documents and learned memory live there and nowhere else. A search is a turn inside that container. |
| **Control plane** | accounts, credentials, bindings, billing and raw source bytes are rows keyed by the account, under forced row-level security in Postgres. A query cannot see another account’s rows even with the platform’s own connection. |
| **Credentials** | a developer key or a consent token carries its account. It cannot be widened from the calling side, only on the Connect page by the owner. |
| **Model calls** | a turn goes through the platform’s inference service under the account’s own model policy; a model credential never enters an agent container. |
| **Deletion** | revoking, narrowing or deleting takes effect on the next call, ahead of any cache, projection or issued credential. |
An id outside a credential’s reach reads the same as one that does not exist (`404`), so a caller cannot even enumerate what it may not read.
## A product that serves many people
[Section titled “A product that serves many people”](#a-product-that-serves-many-people)
Give each person their own Membase account, and reach their memory with a credential that person minted or approved. Three shapes fit most products.

### Your product is an MCP client
[Section titled “Your product is an MCP client”](#your-product-is-an-mcp-client)
If your product can act as an MCP client (an agent framework, a desktop app, anything that speaks Streamable HTTP and OAuth), point it at `https://api.app.membase.com/mcp-http`. Each user completes the consent screen once; your product holds one consent token per user and gets the read tools (`search_memories`, the fact list, the media reads) and, when the user ticked it, `list_profile_facts`. It cannot write and cannot see a Memory the user did not tick. The flow is in [Authentication & Scopes](/build/reference/authentication/#oauth-for-an-app-that-connects-over-mcp) and the client side in [Any MCP client](/connect/clients/membase-mcp/).
This is the shape to prefer: the user never handles a token, and can turn your product off on the Connect page.
### Your product holds a key per user
[Section titled “Your product holds a key per user”](#your-product-holds-a-key-per-user)
If your product needs to write (save what a conversation produced) or is not an MCP client, each user mints a developer key under **Connect › Developer keys**, chooses its level and reach, and pastes it into your product. Store it per user, encrypted at rest, and send it as that user’s bearer and nobody else’s.
```python
from membase import Membase
def load_user_key(user_id: str) -> str:
... # your encrypted per-user store; returns the mbk_… token this user pasted
def memory_for(user) -> Membase:
return Membase(api_key=load_user_key(user.id)) # that user's key, never another's
memory_for(alice).search("what did we decide about the ledger")
```
Two rules follow. A key is refused with `403` the moment its owner revokes it or lowers its level, so treat `PermissionDeniedError` as *this user withdrew access*, not as a bug; a Memory the owner switches off for the key drops out of its searches and lists on the next call. And never route one user’s request through another user’s key: the platform cannot tell, but the memory it answers from is the wrong person’s.
### Your Memory answers people you sell it to
[Section titled “Your Memory answers people you sell it to”](#your-memory-answers-people-you-sell-it-to)
The reverse case: you hold the memory (a support corpus, a product’s knowledge) and many people ask it. List that Memory on the Marketplace; what is sold is the Memory, as answers. Each subscriber receives a credential of their own that holds only `ask_memory`: the memory engine answers from what the Memory learned, and the passages, documents and files never leave your account. Lapsing a subscription stops access at once. See [Platform overview](/build/concepts/platform-overview/#marketplace).

## What is not isolation
[Section titled “What is not isolation”](#what-is-not-isolation)
* **Memories are not users.** Making one Memory per end user inside one account puts every user’s material behind one owner’s credentials and one agent. Nothing stops it, and nothing protects it either.
* **Metadata is not a filter.** Search has no metadata filters and `add_document` refuses a `metadata` field (`422`); `custom_id` is your own bookkeeping and cannot separate people.
* **Reach is not a secret.** A key with *All memories* reaches Memories the user makes later. Say so when you ask for one.
## Checking it
[Section titled “Checking it”](#checking-it)
The negative cases are the ones to test:
| Try | Expect |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------- |
| a `doc_…` or `mem_…` id from another account, with your key | `404 · not_found` |
| a Memory the owner switched off for the key | on the very next call, searches and lists leave it out and its ids answer `404` |
| a revoked key | `403 · unauthorized` on every call, at once |
| `delete_document` on a Read & write key | `403 · unauthorized · not in this agent's capability profile` |
| `delete_document` on a Full access key without `confirm` | `428 · confirmation_required`; nothing changed |
| `add_memory` on a key that reaches several text Memories | `422 · write_target_required`; nothing written |
# AI coding assistants
> Ask a coding assistant to build a Membase integration, with checks for learning completion, permissions and search failures.
Ask a coding assistant to build a Membase integration, with checks for learning completion, permissions and search failures.
Use this recipe when a coding assistant is implementing Membase in your application. To give the coding assistant your memory for its own work, follow its client guide under [Connect your AI](/connect/) instead.
Install the Membase skill using your client’s setup guide ([Claude Code](/connect/clients/claude-code/), [Codex](/connect/clients/codex/), [Cursor](/connect/clients/cursor/), [Kimi Code](/connect/clients/kimi-code/)). Then give it the integration task below.
## Let the agent build the integration
[Section titled “Let the agent build the integration”](#let-the-agent-build-the-integration)
The same skill carries the API reference, the SDK guide, the MCP setup and the use cases, so an agent that has it can write the integration for you. Install it once, then prompt:
> Add Membase memory to this app. Read the membase skill first. Use the SDK; list the profile facts once per session when granted, search before answering about past work, and save only what the user supplied. Wait for learning before searching newly added documents and check `partial`. Never pass `confirm` on your own. Keep the key in the environment.
What the skill teaches, so you can check the result:
| The agent should | Because |
| ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| call `list_profile_facts` once, near the start, when granted | the profile is small and standing: who the user is |
| call `search_memories` before answering about past work, decisions or preferences | search is retrieval inside the user’s own memory |
| cite `memory_name` | every hit says which Memory it came from, over REST and MCP alike |
| use `add_memory` for a fact, `add_document` for text or a URL, with `custom_id`, and never send a `container` | writes land in the key’s write target; documents are raw material until the Memory’s run; the same `custom_id` twice is a no-op |
| pass `confirm=true` only after the person agreed | on a Full access key, a delete or forget without it changes nothing and answers with a `how` sentence (`428 confirmation_required` over REST), not an action |
| treat `403` as withdrawn access and stop | the owner narrowed or revoked the key on Connect |
| use a suitable timeout and inspect `partial` | a cold runtime or failed search must not be reported as an empty Memory |
The skill is served at `https://app.membase.com/skill` (its `SKILL.md` with the install preamble) and as a zip at `https://app.membase.com/plugin/membase-skill.zip`. Its files are under `https://app.membase.com/plugin/skills/membase/`: `SKILL.md`, `README.md` and `references/api-reference.md`, `references/sdk-guide.md`, `references/mcp-setup.md`, `references/quickstart.md`, `references/use-cases.md`. That directory address itself is not a listing; fetch the files by name, or take the zip.
## Without the skill
[Section titled “Without the skill”](#without-the-skill)
Any agent can be handed the OpenAPI document instead. It types the request bodies only: every response is an untyped JSON object, and it names no server or auth scheme, so the generated code must set the base URL (`https://api.app.membase.com`) and the `Authorization: Bearer` header by hand. The command below generates TypeScript types; OpenAPI Generator makes a client for another language:
```bash
curl -s https://app.membase.com/plugin/openapi/agent-protocol.json -o agent-protocol.json
npx openapi-typescript agent-protocol.json -o membase.d.ts
```
Three requests cover most integrations: `GET /v1/profile-facts`, `POST /v1/search` with `{"q": …}` and `POST /v1/memories/add` with `{"content": …}`, each with the bearer header. No request names a Memory; a write lands in the key’s write target. [API reference](/build/reference/api-reference/) has every operation.
# Claude API
> The user's memory behind Claude: point the request at Membase's MCP server with the key as its token, or wrap the SDK in your own tools and let the tool runner loop.
The user’s memory behind Claude: point the request at Membase’s MCP server with the key as its token, or wrap the SDK in your own tools and let the tool runner loop.
Two shapes. The first needs no tool code: the Claude API calls Membase’s MCP server for you. The second wraps the SDK in tools of your own, when you want to shape what the model sees.
Everything below assumes `MEMBASE_API_KEY` in the environment, minted at **Read & write** with **Your profile** ticked ([Authentication & Scopes](/build/reference/authentication/)), and your model provider’s key beside it. The loop is the same in every harness:

## Membase as a remote MCP server
[Section titled “Membase as a remote MCP server”](#membase-as-a-remote-mcp-server)
The Claude API can call a remote MCP server on your behalf. Name Membase’s server, hand it the developer key as the authorization token, and Claude gets the key’s tools without a line of tool code:
* Python
```python
import os
import anthropic
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
betas=["mcp-client-2025-11-20"],
mcp_servers=[{
"type": "url",
"url": "https://api.app.membase.com/mcp-http",
"name": "membase",
"authorization_token": os.environ["MEMBASE_API_KEY"],
}],
tools=[{"type": "mcp_toolset", "mcp_server_name": "membase"}],
system="Call list_profile_facts first. Use search_memories before answering about the "
"user's past work or decisions, and cite the memory_name of anything you use.",
messages=[{"role": "user", "content": "What did we decide about the ledger, and why?"}],
)
for block in response.content:
if block.type == "text":
print(block.text)
```
* TypeScript
```ts
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const response = await client.beta.messages.create({
model: "claude-opus-5-5",
max_tokens: 16000,
betas: ["mcp-client-2025-11-20"],
mcp_servers: [{
type: "url",
url: "https://api.app.membase.com/mcp-http",
name: "membase",
authorization_token: process.env.MEMBASE_API_KEY!,
}],
tools: [{ type: "mcp_toolset", mcp_server_name: "membase" }],
system: "Call list_profile_facts first. Use search_memories before answering about the " +
"user's past work or decisions, and cite the memory_name of anything you use.",
messages: [{ role: "user", content: "What did we decide about the ledger, and why?" }],
});
for (const block of response.content) if (block.type === "text") console.log(block.text);
```
The tool list Claude sees is the key’s: a Read key offers `get_capabilities`, `search_memories`, `list_memories`, `get_memory`, `list_documents`, `get_document`, `list_media`, `get_media`, `search_media` and, with **Your profile** ticked, `list_profile_facts`; a Read & write key adds `add_memory`, `add_document` and, with the tick, `add_profile_fact`. No tool takes a Memory. To keep a conversation read-only, mint a Read key for it.
## Your own tools over the SDK
[Section titled “Your own tools over the SDK”](#your-own-tools-over-the-sdk)
When you want to shape what the model sees (a smaller tool surface, your own descriptions, a result format of your choosing), wrap the SDK and let the tool runner drive the loop:
* Python
```python
import anthropic
from anthropic import beta_tool
from membase import Membase
memory = Membase() # MEMBASE_API_KEY
claude = anthropic.Anthropic()
@beta_tool
def search_memories(q: str) -> str:
"""Search the user's memory. Use it before answering anything about their past work,
decisions or preferences.
Args:
q: the question, in natural language.
"""
hits = memory.search(q, limit=5)["items"]
return "\n".join(f"[{h['memory_name']}] {h['content']}" for h in hits) or "nothing found"
@beta_tool
def remember(content: str) -> str:
"""Save one fact the user asked to remember, in their own words.
Args:
content: the fact.
"""
memory.memories.add(content)
return "saved"
profile = memory.profile_facts.list()["items"]
runner = claude.beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=16000,
system="Standing facts about the user: " + "; ".join(f["content"] for f in profile),
tools=[search_memories, remember],
messages=[{"role": "user", "content": "Remind me why we picked Postgres, then note that we'll revisit it in Q1."}],
)
final = runner.until_done()
print(next(b.text for b in final.content if b.type == "text"))
```
* TypeScript
```ts
import Anthropic from "@anthropic-ai/sdk";
import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
import { z } from "zod";
import { Membase } from "@unibaseio/membase";
const memory = new Membase(); // MEMBASE_API_KEY
const claude = new Anthropic();
const searchMemories = betaZodTool({
name: "search_memories",
description: "Search the user's memory. Use it before answering anything about their past work, decisions or preferences.",
inputSchema: z.object({ q: z.string().describe("the question, in natural language") }),
run: async ({ q }) => {
const { items } = await memory.search({ q, limit: 5 });
return items.map((h) => `[${h.memory_name}] ${h.content}`).join("\n") || "nothing found";
},
});
const remember = betaZodTool({
name: "remember",
description: "Save one fact the user asked to remember, in their own words.",
inputSchema: z.object({ content: z.string() }),
run: async ({ content }) => { await memory.memories.add({ content }); return "saved"; },
});
const { items: profile } = await memory.profileFacts.list();
const final = await claude.beta.messages.toolRunner({
model: "claude-opus-5-5",
max_tokens: 16000,
system: "Standing facts about the user: " + profile.map((f) => f.content).join("; "),
tools: [searchMemories, remember],
messages: [{ role: "user", content: "Remind me why we picked Postgres, then note that we'll revisit it in Q1." }],
});
for (const block of final.content) if (block.type === "text") console.log(block.text);
```
`remember` calls `memories.add`, which lands in the key’s write target: the one text Memory it reaches. A key that reaches several is refused with `WriteTargetRequiredError` (`422 write_target_required`) and nothing is written, so mint the key for the Memory this assistant should write to.
## Rules that hold in every shape
[Section titled “Rules that hold in every shape”](#rules-that-hold-in-every-shape)
The same rules, with the reasons, are on [Memory operations](/build/guides/memory-operations/#rules-of-the-road).
* **Profile once, search per question.** The profile facts are few and standing; search is a turn inside the user’s memory.
* **Cite the Memory.** Every hit names the Memory it came from (`memory_name`, over REST, MCP and the SDKs alike); say where an answer came from.
* **Save what the user supplied,** in their words, and only when they asked or plainly meant to.
* **Never confirm on your own.** A delete or forget without `confirm=true` changes nothing and answers `428 confirmation_required` with a `how` sentence; relay it and stop.
* **Treat `403` as withdrawn access.** The owner narrowed or revoked the key; do not retry with it.
* **Expect the first search to be slow.** Up to a minute after a quiet spell; keep the SDK’s timeout.
# MCP frameworks
> An agent framework with an MCP client needs no Membase-specific code: the server URL and the key as a header, and it discovers the tools. Without a framework, the OpenAPI document generates TypeScript types or a client for another language.
An agent framework with an MCP client needs no Membase-specific code: the server URL and the key as a header, and it discovers the tools. Without a framework, the OpenAPI document generates TypeScript types or a client for another language.
## Give the framework the server
[Section titled “Give the framework the server”](#give-the-framework-the-server)
A framework with an MCP client (LangChain’s MCP adapters, the OpenAI Agents SDK, Pydantic AI, Mastra, and most others) needs no Membase-specific code. Give it the server as a Streamable HTTP endpoint with the key in the header:
```json
{ "url": "https://api.app.membase.com/mcp-http",
"headers": { "Authorization": "Bearer mbk_…" } }
```
It discovers the key’s tools with `tools/list` and calls them by the names in the [API Reference](/build/reference/api-reference/): the same operations, arguments and answers as REST, and no tool takes a Memory. Where the framework’s own MCP client speaks OAuth, leave the header out and the user consents in the browser instead; the connection is then read-only, which is what a user-facing agent usually wants.
A user-facing agent whose end users each hold their own Membase account connects by consent instead, one account at a time; [Multi-user isolation](/build/guides/multi-user-isolation/) has the patterns.
## Without an SDK
[Section titled “Without an SDK”](#without-an-sdk)
Any HTTP client works. The OpenAPI document generates TypeScript types, or a client for another language with OpenAPI Generator. It types the request bodies only: every response is an untyped JSON object, and it names no server or auth scheme, so set the base URL (`https://api.app.membase.com`) and the `Authorization: Bearer` header by hand:
```bash
curl -s https://app.membase.com/plugin/openapi/agent-protocol.json -o agent-protocol.json
npx openapi-typescript agent-protocol.json -o membase.d.ts
```
Three requests cover most integrations: `GET /v1/profile-facts`, `POST /v1/search` with `{"q": …}` and `POST /v1/memories/add` with `{"content": …}`, each with the bearer header. No request names a Memory: a search answers `{items, partial}` across every Memory the key reaches, each passage naming its `memory_name`, and a write lands in the key’s write target (a key that reaches several text Memories is refused with `422 write_target_required`).
## Rules that hold in every shape
[Section titled “Rules that hold in every shape”](#rules-that-hold-in-every-shape)
* **Profile once, search per question.** The profile facts are few and standing; search is a turn inside the user’s memory.
* **Cite the Memory.** Every hit names the Memory it came from (`memory_name`, over REST, MCP and the SDKs alike); say where an answer came from.
* **Save what the user supplied,** in their words, and only when they asked or plainly meant to.
* **Never confirm on your own.** On a Full access key, a delete or forget without `confirm=true` changes nothing and answers `428 confirmation_required` with a `how` sentence; relay it and stop.
* **Treat `403` as withdrawn access.** The owner narrowed or revoked the key; do not retry with it.
* **Expect the first search to be slow.** Up to a minute after a quiet spell; keep the SDK’s timeout.
The same rules, with the reasons, are on [Memory operations](/build/guides/memory-operations/#rules-of-the-road).
# OpenAI API
> The user's memory behind the OpenAI API or any function-calling model: declare search_memories and add_memory as functions and call the SDK when the model asks.
The user’s memory behind the OpenAI API or any function-calling model: declare search_memories and add_memory as functions and call the SDK when the model asks.
Everything below assumes `MEMBASE_API_KEY` in the environment, minted at **Read & write** with **Your profile** ticked ([Authentication & Scopes](/build/reference/authentication/)), and your model provider’s key beside it. The loop is the same in every harness:

## The tool-calling loop
[Section titled “The tool-calling loop”](#the-tool-calling-loop)
Declare the two verbs as functions and call the SDK when the model asks. The shape is the Chat Completions tool-calling loop; any provider with the same loop takes the same two definitions.
```ts
import OpenAI from "openai";
import { Membase } from "@unibaseio/membase";
const memory = new Membase();
const openai = new OpenAI();
const tools: OpenAI.Chat.Completions.ChatCompletionTool[] = [
{ type: "function", function: {
name: "search_memories",
description: "Search the user's memory. Use it before answering anything about their past work, decisions or preferences.",
parameters: { type: "object", properties: { q: { type: "string" } }, required: ["q"] } } },
{ type: "function", function: {
name: "add_memory",
description: "Save one fact the user asked to remember, in their own words.",
parameters: { type: "object", properties: { content: { type: "string" } }, required: ["content"] } } },
];
async function runTool(name: string, args: Record): Promise {
if (name === "search_memories") {
const { items } = await memory.search({ q: args.q, limit: 5 });
return JSON.stringify(items.map((h) => ({ memory: h.memory_name, content: h.content })));
}
await memory.memories.add({ content: args.content });
return "saved";
}
const { items: profile } = await memory.profileFacts.list();
const messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
{ role: "system", content: "Standing facts about the user: " + profile.map((f) => f.content).join("; ") },
{ role: "user", content: "What did we decide about the ledger?" },
];
for (;;) {
const turn = await openai.chat.completions.create({ model: process.env.OPENAI_MODEL!, messages, tools });
const reply = turn.choices[0].message;
messages.push(reply);
if (!reply.tool_calls?.length) { console.log(reply.content); break; }
for (const call of reply.tool_calls) {
if (call.type !== "function") continue; // tool_calls is a union; custom tool calls carry no `function`
const content = await runTool(call.function.name, JSON.parse(call.function.arguments));
messages.push({ role: "tool", tool_call_id: call.id, content });
}
}
```
The same loop in Python is the SDK’s `client.search(...)` and `client.memories.add(...)` behind two function definitions; nothing else changes. `add_memory` lands in the key’s write target, so mint the key for the one Memory it should write to: a key that reaches several is refused with `422 write_target_required`.
## Rules that hold in every shape
[Section titled “Rules that hold in every shape”](#rules-that-hold-in-every-shape)
* **Profile once, search per question.** The profile facts are few and standing; search is a turn inside the user’s memory.
* **Cite the Memory.** Every hit names the Memory it came from (`memory_name`); say where an answer came from.
* **Save what the user supplied,** in their words, and only when they asked or plainly meant to.
* **Never confirm on your own.** A delete or forget without `confirm=true` changes nothing and answers `428 confirmation_required` with a `how` sentence; relay it and stop.
* **Treat `403` as withdrawn access.** The owner narrowed or revoked the key; do not retry with it.
* **Expect the first search to be slow.** Up to a minute after a quiet spell; keep the SDK’s timeout.
The same rules, with the reasons, are on [Memory operations](/build/guides/memory-operations/#rules-of-the-road).
# Memory API — reference
> Every operation of the agent protocol with its access level, parameters and response shape, rendered from the tool table and the OpenAPI document.
Every operation of the agent protocol with its access level, parameters and response shape, rendered from the tool table and the OpenAPI document.
*Generated by `scripts/gen_skill_reference.py` from `docs/openapi/agent-protocol.json` and the tool table. Do not edit by hand.*
Base URL `https://api.app.membase.com`. Every request: `Authorization: Bearer `. MCP endpoint `https://api.app.membase.com/mcp-http` (Streamable HTTP): the same tools by the same names, with the same arguments and answers. No request names a Memory.
## Access levels
[Section titled “Access levels”](#access-levels)
| Level | Tools |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Read (`read`) | `search_memories`, `list_memories`, `get_memory`, `list_profile_facts`, `list_documents`, `get_document`, `list_media`, `get_media`, `search_media`, `ask_memory` |
| Read & write (`suggest`) | `search_memories`, `list_memories`, `get_memory`, `add_memory`, `list_profile_facts`, `add_profile_fact`, `list_documents`, `get_document`, `add_document`, `list_media`, `get_media`, `search_media`, `ask_memory` |
| Full access (`manage`) | `search_memories`, `list_memories`, `get_memory`, `add_memory`, `forget_memory`, `list_profile_facts`, `add_profile_fact`, `forget_profile_fact`, `list_documents`, `get_document`, `add_document`, `delete_document`, `list_media`, `get_media`, `search_media`, `delete_media`, `ask_memory` |
A level is the ceiling of what a credential of that kind may hold. The profile tools and `ask_memory` are held only when a credential’s tool list names them: a developer key gets the profile when the owner ticks it — reading at Read, keeping a statement at Read & write, forgetting one at Full access; `ask_memory` is what a marketplace buyer holds, and only that. A consent-minted client holds `search_memories` (the fact list and reads stand on it), the media reads (`list_media`, `get_media`, `search_media`) and, when ticked, `list_profile_facts` — nothing else. A verb outside a credential’s tools is not offered in `tools/list` and is refused with `403` when called.
## Tools and endpoints
[Section titled “Tools and endpoints”](#tools-and-endpoints)
### `get_capabilities` — What this connection can do
[Section titled “get_capabilities — What this connection can do”](#get_capabilities--what-this-connection-can-do)
any credential; read-only.
`GET /v1/capabilities`
The actions this credential holds (`actions`: `search`, `memories.list`, `profile_facts.list`, …), the Memories it reaches (`memories`, by name and kind, never by id), the standing rules for using them (`rules`: `citation_required`, `retention_notice`, `version`) and the features on here. It is not permission: every call is still checked when made.
### `search_memories` — Search memories
[Section titled “search_memories — Search memories”](#search_memories--search-memories)
level **Read**; read-only.
`POST /v1/search`
Passages the Memories in reach hold on a question, most relevant first. A Memory that could not answer, or whose passages all lost to `limit`, is named in `partial`.
| Field | Type | Required | Description |
| ------- | --------------- | -------- | ----------------------------------------------------------------------- |
| `limit` | integer or null | no | How many passages in all. |
| `mode` | string | no | `full`: the engine’s whole retrieval. `fast`: one round, no model call. |
| `q` | string | yes | The question, in natural language. |
### `list_memories` — List memories
[Section titled “list_memories — List memories”](#list_memories--list-memories)
level **Read**; read-only.
`GET /v1/memories`
The newest facts the Memories in reach hold — newest by when it happened, the engine’s own order. `has_more` says more were left out; a Memory that could not answer is named in `partial` and the others are still listed.
| Field | Type | Required | Description |
| --------------- | --------------- | -------- | -------------------------------------------- |
| `limit (query)` | integer or null | no | How many, newest first: 1–1000, default 100. |
### `get_memory` — Get one memory
[Section titled “get_memory — Get one memory”](#get_memory--get-one-memory)
level **Read**; read-only.
`GET /v1/memories/{memory_id}`
One fact, of any age — a search can name one older than any list shows.
| Field | Type | Required | Description |
| ------------------ | ------ | -------- | ----------- |
| `memory_id (path)` | string | yes | |
### `add_memory` — Add a memory
[Section titled “add_memory — Add a memory”](#add_memory--add-a-memory)
level **Read & write**.
`POST /v1/memories/add`
Save one fact into this credential’s write target. The answer is the note it was written as — a document of kind `note`; poll `GET /v1/documents/{id}` for its learning.
| Field | Type | Required | Description |
| --------- | ------ | -------- | ------------------ |
| `content` | string | yes | The fact, as said. |
| `title` | string | no | |
### `forget_memory` — Forget a memory
[Section titled “forget_memory — Forget a memory”](#forget_memory--forget-a-memory)
level **Full access**; **destructive** — `confirm=true` from a developer key, or a request.
`POST /v1/memories/{memory_id}/forget`
Forget one learned fact; the material it was learned from stays.
| Field | Type | Required | Description |
| ------------------ | ------- | -------- | --------------------------------------------------- |
| `memory_id (path)` | string | yes | |
| `confirm (query)` | boolean | no | True to carry it out (a Full access developer key). |
### `list_profile_facts` — List the user’s profile
[Section titled “list_profile_facts — List the user’s profile”](#list_profile_facts--list-the-users-profile)
level **Read**; read-only; held only when named.
`GET /v1/profile-facts`
Who the user is: their standing statements, newest first, each with where it came from (`source_kind`: `user_stated`, `imported` or `model_generated`).
| Field | Type | Required | Description |
| --------------- | --------------- | -------- | -------------------------------------------- |
| `limit (query)` | integer or null | no | How many, newest first: 1–1000, default 100. |
### `add_profile_fact` — Add a profile fact
[Section titled “add_profile_fact — Add a profile fact”](#add_profile_fact--add-a-profile-fact)
level **Read & write**; held only when named.
`POST /v1/profile-facts/add`
Keep one standing statement about the user. The same statement again keeps the one already there (`created: false`).
| Field | Type | Required | Description |
| --------- | ------ | -------- | -------------------------------------- |
| `content` | string | yes | One standing statement about the user. |
### `forget_profile_fact` — Forget a profile fact
[Section titled “forget_profile_fact — Forget a profile fact”](#forget_profile_fact--forget-a-profile-fact)
level **Full access**; **destructive** — `confirm=true` from a developer key, or a request; held only when named.
`POST /v1/profile-facts/{fact_id}/forget`
Forget one profile fact. There is no editing one: to correct it, add the new statement and forget the old.
| Field | Type | Required | Description |
| ----------------- | ------- | -------- | --------------------------------------------------- |
| `fact_id (path)` | string | yes | |
| `confirm (query)` | boolean | no | True to carry it out (a Full access developer key). |
### `list_documents` — List documents
[Section titled “list_documents — List documents”](#list_documents--list-documents)
level **Read**; read-only.
`GET /v1/documents`
The material the Memories in reach were given, newest first; every kind unless `kind` narrows it (a kind added later is listed too).
| Field | Type | Required | Description |
| --------------- | --------------- | -------- | ------------------------------------------------------------------ |
| `kind (query)` | string or null | no | `file` (a file or page) or `note` (a fact as said); omit for both. |
| `limit (query)` | integer or null | no | How many, newest first: 1–1000, default 100. |
### `get_document` — Get one document
[Section titled “get_document — Get one document”](#get_document--get-one-document)
level **Read**; read-only.
`GET /v1/documents/{document_id}`
One document, with how far each Memory got in learning it.
| Field | Type | Required | Description |
| -------------------- | ------ | -------- | ----------- |
| `document_id (path)` | string | yes | |
### `add_document` — Add a document
[Section titled “add_document — Add a document”](#add_document--add-a-document)
level **Read & write**.
`POST /v1/documents/add`
Hand in a document (text or a url) to this credential’s write target.
| Field | Type | Required | Description |
| ----------- | -------------- | -------- | -------------------------------------------------------- |
| `content` | string or null | no | The document’s full text. |
| `custom_id` | string | no | Your own id; adding the same custom_id again is a no-op. |
| `title` | string | no | |
| `url` | string or null | no | A public web address to fetch instead. |
### `delete_document` — Delete a document
[Section titled “delete_document — Delete a document”](#delete_document--delete-a-document)
level **Full access**; **destructive** — `confirm=true` from a developer key, or a request.
`POST /v1/documents/{document_id}/delete`
Withdraw a document and what every Memory learned from it.
| Field | Type | Required | Description |
| -------------------- | ------- | -------- | --------------------------------------------------- |
| `document_id (path)` | string | yes | |
| `confirm (query)` | boolean | no | True to carry it out (a Full access developer key). |
### `list_media` — List photos and videos
[Section titled “list_media — List photos and videos”](#list_media--list-photos-and-videos)
level **Read**; read-only.
`GET /v1/media`
The photos and videos the media Memories in reach hold, newest first.
| Field | Type | Required | Description |
| --------------- | --------------- | -------- | -------------------------------------------- |
| `limit (query)` | integer or null | no | How many, newest first: 1–1000, default 100. |
### `get_media` — Get one photo or video
[Section titled “get_media — Get one photo or video”](#get_media--get-one-photo-or-video)
level **Read**; read-only.
`GET /v1/media/{media_id}`
One photo or video with its moments: shots and spoken lines with their times, speakers and thumbnails.
| Field | Type | Required | Description |
| ----------------- | ------ | -------- | ----------- |
| `media_id (path)` | string | yes | |
### `search_media` — Search photos and videos
[Section titled “search_media — Search photos and videos”](#search_media--search-photos-and-videos)
level **Read**; read-only.
`POST /v1/media/search`
Photos and videos matching what was seen or said, best first, each with the moments that matched (a shot or a spoken line, its time and speaker).
| Field | Type | Required | Description |
| ------- | --------------- | -------- | --------------------------------------- |
| `kind` | string or null | no | Omit for both. |
| `limit` | integer or null | no | How many items in all. |
| `q` | string | yes | What was seen or said, in any language. |
### `delete_media` — Delete a photo or video
[Section titled “delete_media — Delete a photo or video”](#delete_media--delete-a-photo-or-video)
level **Full access**; **destructive** — `confirm=true` from a developer key, or a request.
`POST /v1/media/{media_id}/delete`
Forget a photo or video and remove its file.
| Field | Type | Required | Description |
| ----------------- | ------- | -------- | --------------------------------------------------- |
| `media_id (path)` | string | yes | |
| `confirm (query)` | boolean | no | True to carry it out (a Full access developer key). |
### `ask_memory` — Ask the memory
[Section titled “ask_memory — Ask the memory”](#ask_memory--ask-the-memory)
level **Read**; read-only; held only when named.
`POST /v1/ask`
One answer from the memory itself — the engine reads the Memories in reach and answers once, with no agent and no tools. The citations name the Memory the answer came from, never the passages.
| Field | Type | Required | Description |
| --------- | ------ | -------- | ----------------------- |
| `message` | string | yes | The question to answer. |
## Retired names
[Section titled “Retired names”](#retired-names)
Grant names credentials minted earlier still hold; each covers its current name.
| Retired | Current |
| --------------------- | -------------------- |
| `memory_recall` | `search_memories` |
| `memory_remember` | `add_memory` |
| `memory_ingest` | `add_document` |
| `memory_list_sources` | `list_documents` |
| `memory_forget` | `delete_document` |
| `get_profile` | `list_profile_facts` |
| `ask_agent` | `ask_memory` |
| `agent_invoke` | `ask_memory` |
## Errors
[Section titled “Errors”](#errors)
| Status | Code | When |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| 400 | `validation` | an empty `q`; both or neither of `content` and `url`; a `limit` out of range |
| 403 | `unauthorized` | a verb above the credential’s access level, or one it does not hold at all (a consent client’s delete, a buyer’s search) |
| 404 | `not_found` | an id that is not this credential’s to read: outside its reach, deleted, or not one of ours |
| 422 | `validation` | a malformed body: a field missing, of the wrong type, or unknown (`container` included) |
| 422 | `write_target_required` | a write from a credential that reaches several Memories |
| 422 | `capability_unavailable` | the account’s memory cannot run a turn here (no model) |
| 428 | `confirmation_required` | a destructive verb without `confirm=true`; nothing changed, and `details.id` names the target |
| 429 | `rate_limited` | the account’s concurrent-turn budget, or too many requests on one credential |
Read `code`, not only the status: `422` is several.
# Authentication & Scopes
> Every call carries a bearer. What the credentials are, what an access level grants, what reach and the profile tick add, and how a key ends.
Every call carries a bearer. What the credentials are, what an access level grants, what reach and the profile tick add, and how a key ends.
Every request to `https://api.app.membase.com` carries one header:
```plaintext
Authorization: Bearer
```
There is no API-wide key, no client secret and no signature. The credential itself says who the caller is, which Memories it may touch, and what it may do to them. Both kinds of credential are minted by the account’s owner and can be narrowed or revoked by them at any time; the change applies on the credential’s next call.
## The credentials
[Section titled “The credentials”](#the-credentials)
| | Developer key | Consent token |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Minted by | the owner, under **Connect › Developer keys** | the owner, approving an app on the OAuth consent screen |
| Held by | code the owner runs: a script, a server, an SDK, an AI running the skill | an AI app: Claude, ChatGPT, Cursor, Codex, Grok, Kimi… |
| Shape | `mbk__`, shown once; the key’s page keeps a hint such as `mbk_7f3a92d1…c91e` | opaque; the app stores it |
| Access | **Read**, **Read & write** or **Full access**, chosen at creation; it can be lowered in place, but a Read key cannot be raised to write (create a new key) | read-only, always |
| Reach | the Memories ticked on the key, or *all, including later ones* | the Memories ticked on consent |
| Profile | when **Your profile** is ticked: read at Read, keep a statement at Read & write, forget one at Full access | read only, when **Profile access** is ticked at consent; to change it, disconnect and authorize again |
| Can confirm a removal | yes, with `confirm=true` | never |
| Expires | never, 30 days, 90 days or a year | at the end of the token’s lifetime; there is no refresh, the app authorizes again and the owner re-approves |
Which one you need: if your code holds the credential, a developer key. If the user’s AI app holds it, consent through MCP, and your code never sees a token at all. The [Connect your AI](/connect/) tab is the consent path; the rest of this page is mostly about keys.
A third credential exists but is not minted by the owner: buying a Memory on the Marketplace gives the buyer one. It reaches that one Memory and holds only `ask_memory`: answers, never the passages, documents, facts or the seller’s profile, and never a write. Every call re-checks the purchase and takes one call of the period’s allowance.
## Access levels
[Section titled “Access levels”](#access-levels)
A level is a set of operations. Each level adds to the one before it.
| Level | Grant | Operations |
| ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Read** | `read` | `search_memories`, `list_memories`, `get_memory`, `list_documents`, `get_document`, `list_media`, `get_media`, `search_media`; `list_profile_facts` with the profile tick |
| **Read & write** | `suggest` | Read, plus `add_memory`, `add_document`; `add_profile_fact` with the profile tick |
| **Full access** | `manage` | Read & write, plus `forget_memory`, `delete_document`, `delete_media`, and `forget_profile_fact` with the profile tick, each only with `confirm=true` |
`GET /v1/capabilities` names the actions a credential holds (`actions`), the Memories it reaches (`memories`) and the standing rules for using them (`rules`). It is not permission: every call is still checked when made.
`ask_memory` is on no developer key, at any level: today only a marketplace buyer’s credential holds it, and from a key the call is refused with `403` like any verb outside its grant. The profile tools and `ask_memory` are *explicit*: a credential holds them only when its tool list names them, never from its level alone. The [API reference](/build/reference/api-reference/) lists each level’s ceiling from the tool table itself, which is why `ask_memory` appears under Read there; a key never reaches it.
A call above the key’s level is refused with `403` and `code: unauthorized`, and the key’s page counts it as a *refused* call. Lowering the level on the key’s page applies on the key’s next call, with the same token. Raising it does not give a **Read** key the right to write: its token was minted read-only, so its writes keep failing with `token missing required scope`. To write, create a new key at **Read & write** or **Full access**.
## Reach
[Section titled “Reach”](#reach)
Reach is the list of Memories a credential may use. It is switched on the Connect page, on the key’s page under **Memory access**, or on a Memory’s own page under **Use in**; all three are the same switch. A key created with *All memories, including ones you make later* reaches every Memory the account has now or later.

No request names a Memory. Searches and lists cover every Memory in reach and leave the others out; an id from a Memory outside the reach reads exactly like one that does not exist: `404 · not_found`. `GET /v1/capabilities` (over MCP, `get_capabilities`) never names a Memory outside the reach, so a client cannot tell withheld from absent.
Writes land in the key’s **write target**: the one text Memory it reaches. A key that reaches several text Memories is refused on `add_memory` and `add_document` with `422 write_target_required`, and nothing is written somewhere by guess. To write, mint the key for the Memory its writes should go to.
## The profile tick
[Section titled “The profile tick”](#the-profile-tick)
The profile is a list of standing statements about the person (`pf_…`): their name, role, lasting preferences. It is the account’s, not part of any Memory, so reach does not cover it. A credential reaches it only when the owner ticked **Your profile** on the key or **Profile access** on consent; without the tick no profile operation is offered at all.
What the tick grants follows the key’s level:
| Level | With the profile tick |
| ---------------- | ----------------------------------------------- |
| **Read** | `list_profile_facts` |
| **Read & write** | also `add_profile_fact` |
| **Full access** | also `forget_profile_fact`, with `confirm=true` |
A consent token with the tick holds `list_profile_facts` only. A key minted before the profile became a list of facts holds the read only, under its retired name `get_profile`, until the owner changes the key. On a consent connection the tick is set only at consent; to change it, the owner disconnects the app and authorizes it again.
## Destructive operations
[Section titled “Destructive operations”](#destructive-operations)
`forget_memory`, `delete_document`, `delete_media` and `forget_profile_fact` need Full access, and even then they do not run on their own: a call without `confirm=true` changes nothing and answers `428 confirmation_required`, naming the target by its public id:
```json
{ "error": { "code": "confirmation_required", "message": "Pass confirm=true to forget this memory.",
"details": { "id": "mem_…", "verb": "forget_memory", "content": "…", "how": "…" },
"retryable": false, "trace_id": "…" } }
```
The `how` sentence is what to relay to the person. Pass `confirm=true` only after they agreed; from a developer key that counts as the owner’s confirmation. A consent token is never offered these verbs at all and is read-scoped, so from an AI app the call is refused with `unauthorized · token missing required scope`, not answered with the sentence. A **Read & write** key gets `403 · unauthorized · tool 'delete_document' is not in this agent's capability profile`.
## Expiry, rotation, revocation
[Section titled “Expiry, rotation, revocation”](#expiry-rotation-revocation)
* **Expiry** is chosen at creation (never, 30 days, 90 days or a year in the app; any 1–3650 days through the API) and cannot be extended on an existing key; rotate instead. An expired key answers `403` with `code: unauthorized`, and its row moves to **Expired**.
* **Rotate…** pre-fills a new key with the old key’s level, reach, profile tick and the same expiry duration counted from now, and asks what to do with the old one. By default the old one keeps working until you revoke it, so you can swap the value in your environment first. From the API you pass those fields yourself; `replaces: ` only records the lineage.
* **Revoke…** ends a key at once. Every holder of the token fails on its next call. The key stays listed under **Revoked** for thirty days so you can see what it was.
* **Disconnect…** on an app’s page revokes every consent token that app holds. Removing the connector inside the app does not tell Membase; revoke on Connect to be sure.
Revocation and permission changes apply to subsequent requests. They do not remove content already received or stored by an external client.
## What a wrong credential looks like
[Section titled “What a wrong credential looks like”](#what-a-wrong-credential-looks-like)
| Answer | Meaning |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401` | no bearer at all (REST; the MCP endpoint differs, below) |
| `403 · unauthorized` | an unknown, expired or revoked token, or a verb above the level. The message says which. |
| `403 · unauthorized · token missing required scope` | a write verb (`add_memory`, `add_document`, `delete_document`, `forget_memory`) from a **Read** key or a consent token |
| `403 · unauthorized · not in this agent's capability profile` | a verb the token may call but the level does not grant: `delete_document` or `forget_memory` from a **Read & write** key, `list_profile_facts` without the profile tick |
| `404 · not_found` | an id outside the reach, deleted, of the wrong type or not one of ours: all answer alike |
On the REST endpoints the status is `403` and not `401` for a bad token on purpose: the request was authenticated as *some* caller (the key id is in the token) and that caller is not allowed. Only a request with no bearer is `401`.
The MCP endpoint (`/mcp-http`) follows the OAuth convention instead and answers `401` in both cases, with a flat body rather than the `{"error": {"code", …}}` envelope:
* **No bearer:** `WWW-Authenticate: Bearer resource_metadata="https://api.app.membase.com/.well-known/oauth-protected-resource/mcp-http"` and `{"error": "unauthorized", "error_description": "…"}`.
* **An invalid, expired or revoked bearer:** `WWW-Authenticate: Bearer error="invalid_token", resource_metadata="…"` and the RFC 6750 body `{"error": "invalid_token", "error_description": "…"}`.
## Managing keys from code
[Section titled “Managing keys from code”](#managing-keys-from-code)
Keys are managed with the owner’s own session, the credential the Membase app holds after sign-in, and never with a developer key: a key cannot mint, widen or revoke another key. The screen for the same operations is [Connect › Developer keys](/use/manage-your-memory/connect/#developer-keys).
| Call | Does |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /v1/keys/create` | mint a key: `name`, `profile` (`read`, `suggest` or `manage` for Read, Read & write, Full access), `view_ids` (its Memories) or `all_views: true`, `profile_access`, `expires_in_days` (1–3650; omit for never), `replaces` (the key it rotates out) |
| `POST /v1/keys/{id}/update` | change `name`, `profile`, `profile_access` or `all_views`; the next call reads the new grant, except that raising a **Read** key’s `profile` does not let it write (create a new key) |
| `POST /v1/access/{id}/memories/set` | change its Memory list |
| `GET /v1/keys/{id}/usage` | calls per day, refusals, per tool, the last twenty |
| `POST /v1/access/{id}/revoke` | revoke it, at once |
## OAuth, for an app that connects over MCP
[Section titled “OAuth, for an app that connects over MCP”](#oauth-for-an-app-that-connects-over-mcp)
The MCP server at `https://api.app.membase.com/mcp-http` advertises its authorization the standard way, so any MCP client that speaks OAuth connects without a Membase-specific step:
1. An unauthenticated request answers `401` with a `WWW-Authenticate` pointing at the protected-resource metadata (`/.well-known/oauth-protected-resource/mcp-http`, RFC 9728).
2. The protected-resource metadata names the authorization server; the authorization-server metadata (`/.well-known/oauth-authorization-server`, RFC 8414) names the registration endpoint (`/oauth/register`). The client registers itself dynamically (RFC 7591) and starts the authorization code flow with PKCE (S256).
3. The browser opens Membase’s consent screen. The owner ticks the Memories the app may use and **Profile access** if it may read their profile, and approves.
4. The client receives a token good for exactly that. `tools/list` on that token offers `get_capabilities`, `search_memories`, `list_memories`, `get_memory`, `list_media`, `get_media`, `search_media` and, when ticked, `list_profile_facts`: nothing that writes. The token is not refreshed (`grant_types_supported` is `authorization_code` only): when its lifetime ends the app authorizes again and the owner re-approves.
A client that cannot do OAuth sends a developer key in the same `Authorization` header instead, and gets the key’s level.
## Keep the token out of the open
[Section titled “Keep the token out of the open”](#keep-the-token-out-of-the-open)
* Read the key from the environment (`MEMBASE_API_KEY`), never from source.
* Log the hint from the key’s page, never the token.
* Do not put a key in a config file you commit or publish; the ready-made client configs Membase serves carry no header for that reason.
* One key per thing that holds it, named after it, so a revocation stops one thing.
# SDKs
> The Python and TypeScript clients. One client, one key, your memory.
The Python and TypeScript clients. One client, one key, your memory.
For your first working example, follow the [quickstart](/build/getting-started/api-quickstart/). This page is client reference: installation, configuration, methods and errors.
The SDK is a thin client over the Membase API. Every method is one operation of the [API reference](/build/reference/api-reference/), and the access level, reach and confirmation rules are enforced server-side, so the SDK cannot do anything the key cannot.
## Install
[Section titled “Install”](#install)
* Python
```bash
pip install unibaseio-membase
```
Version 0.4.0 or newer. Python 3.10 or newer for the hosted client. One dependency, `httpx`.
For local mode, `pip install 'unibaseio-membase[local]'` on Python 3.12 or 3.13. It installs the `unibaseio-membase-core` engine and runs memory on your machine; the engine calls a model provider, by default OpenAI (`OPENAI_API_KEY`).
Local search returns results in retrieval order. To rerank them, set `MEMBASE_RERANK`:
* `llm`: one scoring call on your model provider, with the model you name in `MEMBASE_RERANK_LLM_MODEL`. Results that do not answer the question are dropped (`MEMBASE_RERANK_MIN_SCORE`, 0 to 10, default 3).
* `cross-encoder`: a local model you name in `MEMBASE_RERANK_CE_MODEL`, after `pip install sentence-transformers` (it installs torch).
To keep everything on the machine, point the engine at a local OpenAI-compatible server such as [Ollama](https://ollama.com), for both chat and embeddings:
```bash
ollama pull qwen2.5:7b && ollama pull nomic-embed-text
export MEMBASE_LLM_PROVIDER=openai-compat
export MEMBASE_LLM_ENDPOINT=http://127.0.0.1:11434/v1
export MEMBASE_EMBED_MODEL=nomic-embed-text MEMBASE_EMBED_DIM=768
export OPENAI_API_KEY=ollama # the client needs a value; Ollama ignores it
for stage in READER RERANK EPISODE DECIDER AGENT KNOWLEDGE MULTIMODAL; do
export MEMBASE_${stage}_MODEL=qwen2.5:7b
done
```
* Use `openai-compat`, not `MEMBASE_LLM_PROVIDER=ollama`: embeddings follow the endpoint only with `openai-compat`, and otherwise still go to OpenAI and need a real `OPENAI_API_KEY`.
* `MEMBASE_EMBED_DIM` must match the embedding model, and a store keeps the width it was created with: switching embedding models means a new store.
* Every stage defaults to an OpenAI model name, so set each one, as above.
* Small models (around 3B) run but tend to embellish what they store; a 7B or larger instruct model keeps memories faithful.
With these set, `add`, `search`, `ask` and `membase --local mcp` make no calls beyond the endpoint you named.
* TypeScript
```bash
npm install @unibaseio/membase
```
Version 0.4.0 or newer. Node 18 or newer (global `fetch`), Deno or Bun. Zero dependencies; responses are typed. The package is ESM only: from a CommonJS project, use an `.mts` file or set `"type": "module"`.
## Who owns the memory
[Section titled “Who owns the memory”](#who-owns-the-memory)
In Membase **the person owns the memory**, not the app. A developer key is minted by the account’s owner under **Connect › Developer keys**, and it carries what they chose: an access level, the Memories it may reach, whether it may read their profile, and when it expires. The SDK takes that key and nothing else.
If you have used a memory API where you tag content with a *container tag* per end user and one master key reaches them all: that is not this. No request names a Memory. Reads cover every Memory the key reaches, and writes land in the key’s **write target**: the one text Memory it reaches. A Memory is one of the person’s own topics, not a tenant, and answers name it only for attribution (`memory_name`). A product that serves many people gives each of them their own Membase account, and reaches their memory with their own key or their own consent. See [Multi-user Isolation](/build/guides/multi-user-isolation/).
## Create a client
[Section titled “Create a client”](#create-a-client)
* Python
```python
from membase import Membase
client = Membase() # MEMBASE_API_KEY from the environment
client = Membase(api_key="mbk_…") # or explicit
client = Membase(local=True) # local mode, in ~/.membase (MEMBASE_LOCAL=1 when no key is set)
```
* TypeScript
```ts
import { Membase } from "@unibaseio/membase";
const client = new Membase(); // MEMBASE_API_KEY from the environment
const explicit = new Membase({ apiKey: "mbk_…" }); // or explicit
const local = new Membase({ apiKey: "local", baseUrl: "http://127.0.0.1:8787" }); // `membase --local serve`
```
| Setting | Python | TypeScript | Default |
| --------------- | ------------------- | -------------------------- | ------------------------------------------------------ |
| Request timeout | `timeout` (seconds) | `timeoutMs` (milliseconds) | 90 seconds |
| Retry limit | `max_retries` | `maxRetries` | 2 |
| API origin | `base_url` | `baseUrl` | `MEMBASE_BASE_URL`, else `https://api.app.membase.com` |
Releases before 0.4.0 speak the API this one replaced (they pass a `container` and read `results`); upgrade both packages to 0.4.0 or newer.
A client for an API origin always needs a key: without `api_key` or `MEMBASE_API_KEY` the constructor raises (`ValueError` in Python, `Error` in TypeScript), even when a base URL is given. To talk to `membase --local serve` from either language, pass any key with `http://127.0.0.1:8787`, or the value of `MEMBASE_LOCAL_TOKEN` when the server sets one.
Local memory (`Membase(local=True)` or `membase --local serve`) answers the same routes with the same shapes. Its writes land in the store’s write target, and a store with several Memories needs `MEMBASE_WRITE_TARGET` set to the one writes go to.
Retries cover connection errors, timeouts, 408, 409, 429 and 5xx, with exponential backoff; a numeric `Retry-After` is honoured when present (the server sends none today). A cold runtime can take longer than the default timeout. See [API troubleshooting](/build/reference/troubleshooting/). The method snippets below are independent examples; follow the quickstart to wait for an accepted document to become searchable.
## The four verbs
[Section titled “The four verbs”](#the-four-verbs)
* Python
```python
# add: a document (its text, or a public url) into the key's write target. Answers 202 at once; learned in the background.
doc = client.add("Call notes with Acme: they want SSO before the pilot.",
title="Call with Acme", custom_id="call-2026-09-24")
doc["id"], doc["status"] # "doc_…", "pending" or "processing"; the same custom_id again starts nothing
# search: passages across every Memory in reach, most relevant first, each naming its Memory
hits = client.search("what does Acme need before the pilot", limit=5)
for h in hits["items"]:
print(h["memory_name"], "·", h["content"])
hits["partial"] # the Memories that could not answer
# profile facts: who the user is (needs the profile tick on the key)
for f in client.profile_facts.list()["items"]:
print(f["source_kind"], "·", f["content"])
# ask: one answer from the memory (a credential that holds ask_memory: today, a marketplace buyer's)
out = client.ask("Summarise what the seller learned about Postgres RLS.")
out["answer"], out["citations"] # citations name the Memory, never a passage
```
* TypeScript
```ts
const doc = await client.add({ content: "Call notes with Acme: they want SSO before the pilot.",
title: "Call with Acme", customId: "call-2026-09-24" });
doc.id; doc.status; // "doc_…", "pending" or "processing"
const hits = await client.search({ q: "what does Acme need before the pilot", limit: 5 });
for (const h of hits.items) console.log(h.memory_name, "·", h.content);
hits.partial; // the Memories that could not answer
const { items: facts } = await client.profileFacts.list();
for (const f of facts) console.log(f.source_kind, "·", f.content);
const out = await client.ask({ message: "Summarise what the seller learned about Postgres RLS." });
out.answer; out.citations; // citations name the Memory, never a passage
```
`add` hands raw material to the write target’s folder and starts its learning; poll `documents.get(id)` until every entry of its `learning` reads `succeeded` if you need to know. `search` is retrieval, not an answer; `ask` is one answer the memory engine writes, and only a credential that holds `ask_memory` may call it (a developer key does not). `search` takes `mode="fast"` for one round of retrieval with no model call, for recall before every turn of an agent whose own model judges what it is handed. What each verb does inside the account, and what code sees when the person does something in the app, is on [Memory operations](/build/guides/memory-operations/).
## The resources
[Section titled “The resources”](#the-resources)
Every list answers `{items, has_more, partial}`: the newest `limit` (1–1000, default 100), whether more were left out, and the Memories that could not answer. Ids are typed and opaque: `mem_…` a fact, `pf_…` a profile fact, `doc_…` a document, `med_…` a photo or video.
* Python
```python
client.capabilities() # {"actions": ["search", "memories.list", …], "memories": [{name, kind}], "rules": {…}, "features": […]}
client.memories.list(limit=20) # the newest facts, each with its mem_ id and memory_name
client.memories.get("mem_…")
client.memories.add("We settled on Postgres.") # a fact; the receipt is the note it was written as (doc_…, kind "note")
client.memories.forget("mem_…", confirm=True)
client.profile_facts.list(limit=50) # the profile tick on the key; newest first, each with source_kind
client.profile_facts.add("Prefers dark mode.") # Read & write; the fact, and created: false if it was already there
client.profile_facts.forget("pf_…", confirm=True) # Full access
client.documents.list(kind="file") # newest first; kind is "file" or "note"
client.documents.get("doc_…") # with learning: [{memory_name, status}]
client.documents.delete("doc_…", confirm=True)
client.media.list() # photos and videos in the media Memories in reach
client.media.search("someone skiing", kind="video")
client.media.get("med_…") # with its moments
client.media.file("med_…", range="bytes=0-1023") # its bytes (MediaFile: content, content_type, status)
client.media.delete("med_…", confirm=True)
```
* TypeScript
```ts
await client.capabilities();
await client.memories.list({ limit: 20 });
await client.memories.get("mem_…");
await client.memories.add({ content: "We settled on Postgres." });
await client.memories.forget("mem_…", { confirm: true });
await client.profileFacts.list({ limit: 50 });
await client.profileFacts.add({ content: "Prefers dark mode." });
await client.profileFacts.forget("pf_…", { confirm: true });
await client.documents.list({ kind: "file" });
await client.documents.get("doc_…");
await client.documents.delete("doc_…", { confirm: true });
await client.media.list();
await client.media.search({ q: "someone skiing", kind: "video" });
await client.media.get("med_…");
await client.media.file("med_…", { range: "bytes=0-1023" }); // { content, contentType, status }
await client.media.delete("med_…", { confirm: true });
```
The standing rules for this credential (`citation_required`, `retention_notice`, `version`) are `rules` in `capabilities()`; there is no separate rules call.
`memories.add` answers the note it was written as (a `doc_…` of kind `note`): remove a note with `documents.delete`. `memories.forget` takes the `mem_…` id of a learned fact, from `memories.list`, `memories.get` or a search hit of `type: "memory"`; the material it was learned from stays.
`delete` and `forget` need a key at **Full access** (`profile_facts.forget` also the profile tick). Without `confirm` nothing changes and the call raises `ConfirmationRequiredError` (HTTP `428 confirmation_required`), whose `details` name the target (`id`, `verb`, …) and carry a `how` sentence to relay to the person. Pass `confirm` only after they agreed; from a developer key that counts as the owner’s confirmation.
## Errors
[Section titled “Errors”](#errors)
One class per HTTP status, all carrying the API’s error envelope: `code` (which rule refused), `message`, `details`, `retryable` and `trace_id` (quote it when reporting a problem).
| Status | Class | When |
| ------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400 | `BadRequestError` | `code: validation`, from the service’s own checks: an empty `q`, both or neither of `content` and `url`, a list `limit` outside 1–1000 |
| 401 | `AuthenticationError` | no bearer at all |
| 403 | `PermissionDeniedError` | `code: unauthorized`: an unknown, expired or revoked key, or a verb above its level |
| 404 | `NotFoundError` | an id that is not this key’s to read: unknown, deleted, outside its reach or of the wrong type all answer alike |
| 409 | `ConflictError` | a conflicting write; retried automatically, then raised |
| 422 | `WriteTargetRequiredError` | `code: write_target_required`: a write from a key that reaches several text Memories and has no write target. Nothing was written; the key’s owner decides where its writes go, no request can |
| 422 | `UnprocessableEntityError` | `code: validation` for a body the API cannot take: an unknown field (a `container`, a `metadata`), a missing or mistyped field, a search `limit` outside 1–50. `code: capability_unavailable`: the account’s memory cannot run a turn here (no agent container, no model). Read `code`, not only the status |
| 428 | `ConfirmationRequiredError` | `code: confirmation_required`: a removal without `confirm`; nothing changed |
| 429 | `RateLimitError` | the account’s concurrent-turn cap (two agent turns at once), the service-wide ceiling on turns running at once (`details.scope: "process"`), or the per-token request limiter (`details.limit_per_min`); no `Retry-After` is sent; retried automatically with backoff, then raised. The per-token limiter covers every call, `search` and `add` included; the two-turn cap does not reach them. `add` and `memories.add` also raise it with `code: quota_exceeded` when the account’s storage is full or its plan is not active; retrying does not help |
| 5xx | `InternalServerError` | retried automatically, then raised |
| — | `APIConnectionError`, `APITimeoutError` | the request never got an answer |
* Python
```python
from membase import ConfirmationRequiredError, WriteTargetRequiredError
try:
client.memories.forget("mem_…")
except ConfirmationRequiredError as e:
print(e.code, e.details["how"], e.trace_id) # confirmation_required Pass confirm=true … …
try:
client.memories.add("We settled on Postgres.")
except WriteTargetRequiredError as e:
print(e.message) # the key reaches several Memories and has no write target
```
* TypeScript
```ts
import { ConfirmationRequiredError, WriteTargetRequiredError } from "@unibaseio/membase";
try {
await client.memories.forget("mem_…");
} catch (e) {
if (e instanceof ConfirmationRequiredError) console.log(e.code, e.details, e.traceId);
}
try {
await client.memories.add({ content: "We settled on Postgres." });
} catch (e) {
if (e instanceof WriteTargetRequiredError) console.log(e.message);
}
```
## Rules of the road
[Section titled “Rules of the road”](#rules-of-the-road)
* **Reach is account state.** The Memories a key may use are switched on the Connect page. A key narrowed there stops reading a Memory on its very next call, with the same token: searches and lists leave it out, and its ids answer `404`.
* **No request names a Memory.** There is no `container` to pass; sending one is a `422`. Writes go to the key’s write target.
* **Confirm means the person agreed.** Never pass `confirm` on your own initiative.
* **Writes are raw material.** `add` hands bytes to the write target’s folder; its agent reads them in the next learning turn.
* **Do not store to filter later.** There are no server-side metadata filters on search; put what matters in the content, and use `custom_id` for your own bookkeeping.
* **The token stays out of logs.** Log the key’s hint (`mbk_7f3a92d1…`) from the key’s page, never the token.
## Method map
[Section titled “Method map”](#method-map)
| SDK | REST | Protocol tool | Level |
| ---------------------------------------- | --------------------------------------------------- | --------------------- | --------------------------- |
| `search(q, limit=, mode=)` | `POST /v1/search` | `search_memories` | Read |
| `add(...)`, `documents.add(...)` | `POST /v1/documents/add` | `add_document` | Read & write |
| `ask(message)` | `POST /v1/ask` | `ask_memory` | marketplace buyer only |
| `capabilities()` | `GET /v1/capabilities` (actions, Memories, `rules`) | `get_capabilities` | any credential |
| `memories.list(limit=)` | `GET /v1/memories` | `list_memories` | Read |
| `memories.get(id)` | `GET /v1/memories/{id}` | `get_memory` | Read |
| `memories.add(content, title=)` | `POST /v1/memories/add` | `add_memory` | Read & write |
| `memories.forget(id, confirm=True)` | `POST /v1/memories/{id}/forget` | `forget_memory` | Full access |
| `profile_facts.list(limit=)` | `GET /v1/profile-facts` | `list_profile_facts` | Read + profile tick |
| `profile_facts.add(content)` | `POST /v1/profile-facts/add` | `add_profile_fact` | Read & write + profile tick |
| `profile_facts.forget(id, confirm=True)` | `POST /v1/profile-facts/{id}/forget` | `forget_profile_fact` | Full access + profile tick |
| `documents.list(kind=, limit=)` | `GET /v1/documents` | `list_documents` | Read |
| `documents.get(id)` | `GET /v1/documents/{id}` | `get_document` | Read |
| `documents.delete(id, confirm=True)` | `POST /v1/documents/{id}/delete` | `delete_document` | Full access |
| `media.list(limit=)` | `GET /v1/media` | `list_media` | Read |
| `media.get(id)` | `GET /v1/media/{id}` | `get_media` | Read |
| `media.file(id, thumb=, range=)` | `GET /v1/media/{id}/file`, `…/thumbs/{name}` | — (REST only) | Read |
| `media.search(q, kind=, limit=)` | `POST /v1/media/search` | `search_media` | Read |
| `media.delete(id, confirm=True)` | `POST /v1/media/{id}/delete` | `delete_media` | Full access |
The TypeScript names are the same in camelCase (`profileFacts.list`). The MCP server offers the same operations under the protocol tool names, with the same arguments and answers, so a model that learned `search_memories` in Claude is calling what your code calls `search`. No tool takes a Memory, over MCP or REST.
## Without the SDK
[Section titled “Without the SDK”](#without-the-sdk)
Any HTTP client works. The OpenAPI document types the request bodies only: every response is an untyped JSON object, and it names no server or auth scheme, so set the base URL (`https://api.app.membase.com`) and the `Authorization: Bearer` header yourself:
```bash
npx openapi-typescript https://app.membase.com/plugin/openapi/agent-protocol.json -o membase.d.ts
```
# API troubleshooting
> Diagnose API authentication errors, unread documents, partial search failures, model availability and timeouts.
Diagnose API authentication errors, unread documents, partial search failures, model availability and timeouts.
Start with the HTTP status and response body. For searches and lists, also inspect `partial`: a `200` response can name Memories that could not answer alongside the results.
## A document was accepted but search cannot find it
[Section titled “A document was accepted but search cannot find it”](#a-document-was-accepted-but-search-cannot-find-it)
`202` means accepted, not learned. Poll `GET /v1/documents/{id}` until its `learning` status is `succeeded`. If the receipt’s `id` is null, the source sync may still be creating its row: wait and list the documents. A delayed row may not yet carry your `custom_id` or custom title.
The status says where learning stands: `processing` (a run is reading it now), `pending` (waiting for the next run, which the one in flight starts when it ends) or `failed`: inspect the Memory’s **Report** in the app. Adding the same `custom_id` again is a no-op and does not force a new learning run. The [quickstart](/build/getting-started/api-quickstart/) includes bounded polling and failure handling.
## Search returns no results
[Section titled “Search returns no results”](#search-returns-no-results)
1. Inspect `partial`. A Memory named there could not answer (no model, dormant, unreachable) or lost every passage to `limit`; do not treat it as proof that no relevant memory exists. Fix the model or run error before retrying.
2. Check reach: `GET /v1/capabilities` names the Memories the key reaches (`memories`). Search considers only those.
3. Check that the document is learned, then inspect the Memory in the app and try a question that names something specific from the source.
Search runs an agent turn in the hosted service and needs a working model. Stored content is retained when a model is unavailable, but that does not make hosted search model-free.
## Authentication and access errors
[Section titled “Authentication and access errors”](#authentication-and-access-errors)
| Response | Meaning | Next step |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `401` | On REST: no bearer credential was supplied. On `/mcp-http`, a missing bearer answers `401` with `WWW-Authenticate: Bearer resource_metadata="…"` and `{"error": "unauthorized", …}`; an invalid, expired or revoked one answers `401` with `WWW-Authenticate: Bearer error="invalid_token", resource_metadata="…"` and `{"error": "invalid_token", …}`. | Check the Authorization header or `MEMBASE_API_KEY`; over MCP, `invalid_token` means the token is no longer valid: authorize again. |
| `403 · unauthorized` | The token is invalid, expired or revoked, or the requested access is outside its grant. | Read the error and inspect the key in Connect. |
| `404 · not_found` on an id | The id is outside the key’s reach, deleted, or not one of ours. | Check `memories` in `GET /v1/capabilities` and **Memory access** on the key. |
| `403 · token missing required scope` | A write operation from a read-scoped credential: a **Read** key or an app’s consent token. | Create a new key at **Read & write** or above; raising an existing **Read** key does not let it write. Consent tokens never write. |
| `403 · not in this agent's capability profile` | The operation is not granted to this credential, for example a delete or forget from a **Read & write** key. | Have the owner adjust the access level if appropriate. |
| `428 · confirmation_required` | A destructive call has not been confirmed; nothing changed. | Ask the owner before calling with `confirm=true`; the key still needs Full access. |
| `422 · write_target_required` | A write from a key that reaches several Memories. | Use a key that reaches the one Memory writes should go to. |
| `403 · unauthorized` on `ask_memory` | From a developer key: keys do not hold `ask_memory`. From a marketplace credential: the purchase is not active, the listing is suspended, or the period’s calls are used up (`details.calls_limit`, `period_end`). | Search with a key and answer with your own model; a buyer renews or waits for the next period. |
A `403` is the API’s refusal convention; it does not prove that the supplied secret was valid. Do not retry refused requests unchanged. [Authentication](/build/reference/authentication/) explains the credential model.
## Model, capacity and timeout errors
[Section titled “Model, capacity and timeout errors”](#model-capacity-and-timeout-errors)
| Symptom | Next step |
| --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400 · validation` or `422 · validation` | `400` is the service’s own check: an empty `q`, both or neither of `content` and `url`, a `limit` out of range. `422 · validation` is a missing, mistyped or unknown body field (a `container` included). Read `code`, not only the status. |
| `422 · capability_unavailable`, or a Memory in `partial` with reason `error` | Check AI Setup and the Memory agent’s model setting; inspect its Report. |
| `422 · capability_unavailable` with `details.reason: dormant` (in a search, the Memory is named in `partial` with reason `error`) | The free account needs available turns, its own model, or a paid plan. Follow the account’s recovery choices. |
| `429 · rate_limited` | The account already has two agent turns running, the service is running as many agent turns as it can at once (`details.scope: "process"`), or the token exceeded its per-minute limit (`details.limit_per_min`). The per-minute limit applies to every `/v1` call, search and `add_document` included; only the two-turn limit spares them (`add_document` defers its learning instead). No `Retry-After` is sent; back off exponentially, as the SDK does. Do not start a parallel retry loop. |
| `429 · quota_exceeded` | `add_document` or `add_memory` when the account’s storage is full (`details.meter: "storage"`) or its plan is not active (`details.meter: "plan"`). Retrying does not help; free space in Files, get more storage or renew the plan. |
| Request timeout | The account may be waking or an agent turn may still be running. Inspect the run before resubmitting writes. |
The SDK defaults to 90 seconds per request and retries some transient failures. That is a client setting, not a promise that every cold request finishes in 90 seconds. Configure `timeout` in Python or `timeoutMs` in TypeScript for your workload. Use `custom_id` for retryable document writes; an unkeyed write should not be replayed blindly. Both SDKs retry every request, POSTs included, on a timeout, a connection error, `409`, `429` and `5xx`. For a write without `custom_id` (`memories.add`, `ask`), turn that off with `max_retries=0` in Python or `maxRetries: 0` in TypeScript and decide yourself whether to resend.
## Can search filter on metadata?
[Section titled “Can search filter on metadata?”](#can-search-filter-on-metadata)
Search accepts a question, a limit and a mode. `custom_id` is a document bookkeeping field, not a search filter, and a `metadata` field is refused. Put information needed for recall in the content. See [Memory operations](/build/guides/memory-operations/).
## Can one application key serve all my users?
[Section titled “Can one application key serve all my users?”](#can-one-application-key-serve-all-my-users)
There is no application-wide credential or sub-tenant tag. Each person’s account owns its memory and grants access through that person’s credential. A Memory is a topic inside an account, not an end user. See [Multi-user isolation](/build/guides/multi-user-isolation/).
# Concepts
> Understand Memories, sources, files, connected apps and agents, and manage access or deletion.
Understand Memories, sources, files, connected apps and agents, and manage access or deletion.
Membase turns your material into memory that your assistant and connected AI apps can use.

**Assistant.** Your built-in assistant, available on Home and through a connected Telegram chat. It can use the memories and skills selected in its settings.
**Memory.** A named collection of information about a topic, such as project decisions or reading notes. Set what it should retain, add sources, and choose a schedule if needed.
**Source.** Material a Memory learns from: a folder in Files, uploaded documents, selected Notion pages, or conversations imported through the Membase browser extension.
**Files.** Your file manager. Organize documents into folders and connect a folder to a Memory. System folders such as Generated, Assets and Trash have separate purposes and controls.
**Connect.** Manage access for external AI apps and developer keys. Choose the Memories each connection can use and revoke access when it is no longer needed.
**Agents.** Additional agents you configure for specific tasks. Use Studio to build their workflows and Agents to manage their settings and runs.
**Marketplace.** Browse skills and memory listings. A memory listing sells a Memory as answers: a buyer asks it and gets answers, never its documents or files. Check its **Included access** before purchasing.
## What runs when
[Section titled “What runs when”](#what-runs-when)
Adding or syncing a source makes material available to a Memory. Select **Update now** to process it, or configure a schedule. Check the run’s **Report** to see whether it completed. A document added through the API with `add_document` starts learning on its own; poll the document until its `learning` status reads `succeeded`.
## Stopping and undoing
[Section titled “Stopping and undoing”](#stopping-and-undoing)
Access controls, deletion and billing have different effects. Read the confirmation for the selected action; subscription timing is shown in the relevant plan or purchase details.
| Action | Effect | Recovery |
| ------------------------------------ | ------------------------------------------------------------------------------- | ------------------------- |
| Switch off a Memory under **Use in** | removes that connection’s access to the Memory | switch it on again |
| **Disconnect…** an app | revokes its Membase approvals | authorize the app again |
| **Revoke…** a developer key | stops subsequent requests using that key | create a new key |
| **Remove** a source from a Memory | stops that Memory reading the source | add the source again |
| **Pause** a schedule | stops future scheduled runs | resume the schedule |
| **End** a conversation | keeps its transcript readable and stops new turns | start a new conversation |
| **Delete…** a Memory | permanently removes its stored content and affects dependent agents or listings | cannot restore from Trash |
| **Delete conversation** | removes the transcript; previously saved memory is retained | cannot undo |
| **Delete everything** in Settings | removes account data; retains the sign-in identity | cannot undo |
Changing access does not remove content an external app has already received. Removing a source from a Memory does not by itself erase information previously learned from it. Review and edit learned content on the Memory page when needed.
### Before deleting
[Section titled “Before deleting”](#before-deleting)
Read the affected items in the confirmation, including dependent agents, workflows and subscriber access. Download data you want to keep and check for export warnings before continuing. The account-data deletion flow requires typing `delete everything`. [Export and account-data deletion](/use/account-and-models/settings/).
# Connect your AI
> Choose MCP for read-only access through consent, or a skill with a developer key for an AI that needs to write. Then follow your client’s setup guide.
Choose MCP for read-only access through consent, or a skill with a developer key for an AI that needs to write. Then follow your client’s setup guide.
Connect an AI you already use to your Membase memory. You need a Memory with material it has learned; start with the [app quickstart](/use/getting-started/quickstart/) if you have not made one yet.
Choose a connection method, follow your client’s guide, then ask a question about a known fact in your Memory to verify the result.
## Two ways in
[Section titled “Two ways in”](#two-ways-in)

| | For | How it authenticates | What it gets |
| ------------------------------ | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **MCP with consent** | an AI app the person uses: Claude, ChatGPT, Cursor, Codex, Grok, Kimi, VS Code, Windsurf… | the app discovers OAuth, the browser opens Membase’s consent screen, the person ticks the Memories the app may use and whether it may read their profile | search and the read tools (`search_memories`, `list_memories`, `get_memory`, the media reads) and, when ticked, `list_profile_facts`. Read-only by design. |
| **Skill with a developer key** | an AI that reads pages and runs commands: Claude Code, Codex, Cursor’s agent, Kimi Code | a developer key the person minted | the key’s access level, up to Full access |
The account owner can change or revoke either connection from the **Connect** page, and the change applies on the credential’s next call. [Access control](/connect/manage-access/access-control/) has the rules.
### MCP server address
[Section titled “MCP server address”](#mcp-server-address)
Paste this into your client’s remote MCP setup:
```text
https://api.app.membase.com/mcp-http
```
The transport is Streamable HTTP. Supported clients open a browser for consent; the [client guides](#the-pages) show their setup steps. Some clients also accept a developer key in an Authorization header, with the permissions of that key.
### The skill, in one sentence
[Section titled “The skill, in one sentence”](#the-skill-in-one-sentence)
Tell the AI:
> Install Membase from using key mbk\_…
That address is the skill’s `SKILL.md` with an install preamble. The AI fetches the folder, keeps the key as `MEMBASE_API_KEY` and calls the REST API with it. Connect’s **Skills** tab writes the sentence for you, key included. An AI that already has Membase MCP tools uses those and keeps the skill for its rules.
## The pages
[Section titled “The pages”](#the-pages)
Every client page has the same shape: before you start, set up, with a developer key, what it can do, which Memories it uses, remove it, and what to do when something looks wrong.
| Page | For |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [ChatGPT](/connect/clients/chatgpt/) | the Plugins dialog (account and workspace policies apply), `@` in a new conversation |
| [Claude](/connect/clients/claude/) | the custom connector on claude.ai and the desktop app |
| [Claude Code](/connect/clients/claude-code/) | `claude mcp add`, a key in the header, the skill |
| [Cursor](/connect/clients/cursor/) | `mcp.json`, project or global |
| [Codex](/connect/clients/codex/) | `codex mcp add`, `config.toml`, the IDE extension |
| [Grok](/connect/clients/grok/) | a custom connector on grok.com; no tile of its own, listed under **Other apps** after consent |
| [Kimi Code](/connect/clients/kimi-code/) | `mcp.json` and `/mcp-config`; no tile of its own, listed under **Other apps** after consent |
| [Any MCP client](/connect/clients/membase-mcp/) | the server itself: discovery, the header alternative, what `tools/list` shows, the ready-made config files, VS Code, Windsurf, Devin and every client without a page |
| [Access control](/connect/manage-access/access-control/) | consent vs key, reach, the profile tick, confirmation, revocation |
| [Troubleshooting](/connect/manage-access/troubleshooting/) | every word and status a client can show, and what to do |
## What connecting looks like
[Section titled “What connecting looks like”](#what-connecting-looks-like)
1. The person pastes the URL into the app, or runs the app’s `mcp add` command.
2. The app answers with a browser window: Membase’s consent card, listing the Memories with a tick each and **Profile access** for the profile.
3. The person presses **Approve access**. The app’s tile on Connect says *Authorized · awaiting first use*; its page lists what it **Uses**. An app without a tile in the catalog (Grok, Kimi Code, any other MCP client) appears under **Other apps** once the consent completed, and only then has a page.
4. In a chat, the person asks *“Which Membase memories can you use?”* Check that it names the Memory you granted. Then ask about a specific fact from its material and check the answer. An empty list means no Memory is switched on for this connection yet.
Connecting is the account’s, once. Which Memories an app uses is the Memory’s, and the switch on the app’s page and the switch on the Memory’s **Use in** card are the same switch. The Connect page itself, tab by tab, is on [Connect](/use/manage-your-memory/connect/) in the user guide.
## Related tasks
[Section titled “Related tasks”](#related-tasks)
* To import conversations into memory, use the [browser extension](/use/bring-your-material-in/browser-extension/).
* To talk to your Membase assistant from Telegram, with your own bot, see [Telegram](/use/use-your-assistant/telegram/).
* To build your own integration, use the [API quickstart](/build/getting-started/api-quickstart/).
# ChatGPT
> Membase as a ChatGPT plugin, through the Plugins dialog, with OAuth consent in the browser.
Membase as a ChatGPT plugin, through the Plugins dialog, with OAuth consent in the browser.
ChatGPT connects to Membase as a custom MCP server and reads the Memories you switch on for it.
## Before you start
[Section titled “Before you start”](#before-you-start)
* A ChatGPT account that may add custom MCP servers: account and workspace policies apply to adding and using them.
* A Membase account with at least one Memory that has run once.
## Set up
[Section titled “Set up”](#set-up)
1. Open **ChatGPT Plugins** (`https://chatgpt.com/plugins`), press **+** and choose **Add custom MCP server**. Fill the dialog:
* a name (*Membase*) and a description;
* **Connection**: choose the public endpoint;
* the complete URL, path included: `https://api.app.membase.com/mcp-http`;
* **Authentication**: *OAuth*. Leave Client ID and Secret empty: ChatGPT registers itself with the server.
2. Review the risk warning, select **I understand and want to continue**, then **Create as a plugin**.
3. The browser opens Membase’s consent screen. Tick the Memories ChatGPT may use, and **Profile access** if it may read the profile. Press **Approve access**. The last page you should see is ChatGPT’s own; if you end up on Membase instead, ChatGPT did not receive the code: retry the connection from ChatGPT.
4. Back in ChatGPT, review the tools and metadata it discovered. If the list looks stale later, open the plugin’s connection on ChatGPT Plugins, select **Refresh**, and start a new conversation.
5. Install the plugin, then start a new conversation, type `@` in the prompt box and select Membase.
Then ask *“Which Membase memories can you use?”*
## What it can do
[Section titled “What it can do”](#what-it-can-do)
Read. `get_capabilities`, `search_memories`, `list_memories`, `get_memory`, `list_media`, `get_media`, `search_media` and, when ticked, `list_profile_facts`. It cannot add, delete or forget anything, and cannot see a Memory that is not switched on for it. The writing and destructive tools are not in its tool list at all: `tools/list` does not offer them, and a call to one comes back as a tool error (*token missing required scope*). ChatGPT has no way to send a developer key, so the consent path is the only one.
## Which Memories it uses
[Section titled “Which Memories it uses”](#which-memories-it-uses)
An empty list of memories means no Memory is switched on for this connection yet. Switch one on under **Uses** on ChatGPT’s page in Connect, or under **Use in** on the Memory; the two are the same switch, and off takes effect on the next question.
Two things worth knowing:
* ChatGPT registers itself under the same client name as the Codex CLI. Membase tells them apart and shows them as two tiles on Connect; do not be surprised to see both after setting up both.
* Profile access is decided on the consent screen only; ChatGPT’s page in Connect has no profile switch. To change it, **Disconnect…** and set the plugin up again.
## Remove it
[Section titled “Remove it”](#remove-it)
Remove the plugin in ChatGPT, and **Disconnect…** on ChatGPT’s page in Membase’s Connect. ChatGPT does not tell the server when a plugin is removed.
## If something looks wrong
[Section titled “If something looks wrong”](#if-something-looks-wrong)
| It says | What it means | Do |
| ------------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| ChatGPT does not offer **Add custom MCP server** | your account or workspace policy does not allow custom MCP servers | ask your workspace admin |
| the plugin is created but never appears in a chat | it is not added to this conversation | start a new conversation, type `@` and select Membase |
| *No memory access* on ChatGPT’s page in Connect | authorized, no Memory switched on | switch one on under **Uses** |
| the consent screen never opens | the URL has a typo, or misses the path (a bare domain, `/mcp`) | paste `https://api.app.membase.com/mcp-http` exactly |
| the model answers from nothing about you | **Profile access** was not ticked at consent | **Disconnect…** on ChatGPT’s page in Connect, set the plugin up again and tick it |
# Claude
> Membase in Claude on the web and the desktop app, as a custom connector, with OAuth consent in the browser or a developer key in a request header.
Membase in Claude on the web and the desktop app, as a custom connector, with OAuth consent in the browser or a developer key in a request header.
Claude (claude.ai and the desktop app) takes Membase as a **custom connector** and reads the Memories you switch on for it. For Claude Code, the command-line agent, see [Claude Code](/connect/clients/claude-code/).
## Before you start
[Section titled “Before you start”](#before-you-start)
* A Claude plan with custom connectors: Free (one custom connector), Pro, Max, Team or Enterprise. On Team and Enterprise an Owner adds the connector first under **Organization settings → Connectors**; members then press **Connect** on it under **Customize → Connectors**.
* A Membase account with at least one Memory that has run once.
## Set up
[Section titled “Set up”](#set-up)
1. **Customize → Connectors**, then the add option → **Custom** → **Web**.
2. Paste `https://api.app.membase.com/mcp-http` and confirm.
3. Finish the authorization in the browser. On Membase’s consent screen tick the Memories Claude may use and, if it may read the profile, **Profile access**; press **Approve access**. The last page you should see is Claude’s own; if you end up on Membase instead, Claude did not receive the code: retry the connection from Claude.
4. In a chat, open **+ → Connectors** and switch Membase on, then ask *“Which Membase memories can you use?”*
## With a developer key
[Section titled “With a developer key”](#with-a-developer-key)
Request-header authentication is a beta that Claude offers to a limited set of organizations; if the custom connector form shows no **Request headers** section, use the consent path above. Where it is offered, choose **No sign-in** for authentication (a header named `Authorization` cannot be set on an OAuth connection), then add `Authorization` with the value `Bearer mbk_…`. A valid key passes without the consent screen, and the key’s level and reach apply, up to Full access. The authentication settings cannot be edited after the connector is added: to change the key, remove the connector and add it again.
## What it can do
[Section titled “What it can do”](#what-it-can-do)
With consent: `get_capabilities`, `search_memories`, `list_memories`, `get_memory`, `list_media`, `get_media`, `search_media` and, when ticked, `list_profile_facts`. Nothing that writes: the saving, deleting and forgetting tools are not in its tool list, and a call to one comes back as a tool error (*token missing required scope*). With a key in **Request headers**: the key’s level. Profile access is decided on the consent screen only; to change it, **Disconnect…** on Claude’s page in Connect and add the connector again (with a key, it is **Your profile** on the key’s page).
## Which Memories it uses
[Section titled “Which Memories it uses”](#which-memories-it-uses)
An empty list of memories means no Memory is switched on for this connection. Switch one on under **Uses** on Claude’s page in Connect (with a key: on the key’s page), or under **Use in** on the Memory. Off takes effect on Claude’s next question.
## Remove it
[Section titled “Remove it”](#remove-it)
Remove the connector on the same Connectors page, and **Disconnect…** on Claude’s page in Membase’s Connect too, or **Revoke…** the key: the client does not tell the server.
## If something looks wrong
[Section titled “If something looks wrong”](#if-something-looks-wrong)
| It says | What it means | Do |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| the connector never finishes authorizing | the URL has a typo or misses the path, or the consent tab was closed | paste the URL exactly; add the connector again |
| *Which memories can you use?* answers none | connected, no Memory switched on | **Uses** on Claude’s page in Connect |
| the last step lands on the Membase app | Claude did not receive the authorization code | retry the connection from Claude |
| the model says a Memory “could not answer yet” | the memory was asleep; the first search wakes it | ask again in a moment |
| the connector with a key in **Request headers** cannot connect | the key is unknown, expired or revoked: the server answers `401 invalid_token` to every request | mint a new key, remove the connector and add it again with the new key |
| the model answers from nothing about you | **Profile access** was not ticked at consent | **Disconnect…** on Claude’s page in Connect, add the connector again and tick it |
# Claude Code
> Membase in Claude Code: over MCP with consent, over MCP with a developer key, or as the skill alone.
Membase in Claude Code: over MCP with consent, over MCP with a developer key, or as the skill alone.
Claude Code reads pages and runs commands, so it can take Membase three ways: over MCP with consent, over MCP with a developer key, or as the skill alone. Pick by what you want it to be able to do.
## Before you start
[Section titled “Before you start”](#before-you-start)
* Claude Code 2.1.186 or later for `claude mcp login`; older versions authorize with `/mcp` inside a session.
* For anything that writes, a developer key from **Connect › Developer keys › Create key** at Read & write or Full access.
## Set up
[Section titled “Set up”](#set-up)
### Over MCP, with consent
[Section titled “Over MCP, with consent”](#over-mcp-with-consent)
```bash
claude mcp add --transport http --scope user membase https://api.app.membase.com/mcp-http
claude mcp login membase
```
`--scope user` makes the server available in every project. The browser opens Membase’s consent screen; tick the Memories Claude Code may use and, if it may read the profile, **Profile access**. Then ask *“Which Membase memories can you use?”* This connection is read-only.
## With a developer key
[Section titled “With a developer key”](#with-a-developer-key)
No OAuth round-trip, and the key’s level applies, up to Full access:
```bash
claude mcp add --transport http --scope user membase https://api.app.membase.com/mcp-http \
--header "Authorization: Bearer ${MEMBASE_API_KEY}"
```
The token screen right after **Connect › Developer keys › Create key** writes this command with the key filled in, on its **Claude Code** tab. The key’s page later shows no snippets, and a key created from the **Skills** tab shows only the sentence below.
Or the skill alone, with no MCP server at all. Paste the sentence from Connect’s **Skills** tab:
> Install Membase from using key mbk\_…
Claude Code fetches the skill folder into `~/.claude/skills/membase/`, stores the key as `MEMBASE_API_KEY` in the `env` block of `~/.claude/settings.json`, checks it with one call and reports which Memories it can use. If it already has the MCP tools it uses those and keeps the skill for its rules.
## What it can do
[Section titled “What it can do”](#what-it-can-do)
Over MCP, `tools/list` shows only what the credential holds. No tool takes a Memory: reads cover every Memory in reach, and a write lands in the one text Memory the key reaches.
| Way in | Tools |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| consent | `get_capabilities`, `search_memories`, `list_memories`, `get_memory`, `list_media`, `get_media`, `search_media`; `list_profile_facts` when **Profile access** was ticked. Read-only |
| a Read key | `get_capabilities`, `search_memories`, `list_memories`, `get_memory`, `list_documents`, `get_document`, `list_media`, `get_media`, `search_media`; `list_profile_facts` with **Your profile** ticked |
| a Read & write key | plus `add_memory`, `add_document`; `add_profile_fact` with the profile tick |
| a Full access key | plus `forget_memory`, `delete_document`, `delete_media`; `forget_profile_fact` with the profile tick; each only with `confirm=true` after you agreed |
The skill alone gets the same operations over REST, at the key’s level.
## Which Memories it uses
[Section titled “Which Memories it uses”](#which-memories-it-uses)
With consent: the Memories ticked on the consent screen, switchable later under **Uses** on Claude Code’s page in Connect. With a key: the key’s reach, switchable on the key’s page or under **Use in** on the Memory. An empty `memories` list from `get_capabilities` means nothing is switched on yet.
## Remove it
[Section titled “Remove it”](#remove-it)
`claude mcp remove membase`. Then **Disconnect…** on Claude Code’s page in Connect, or **Revoke…** the key: the client does not tell the server.
## If something looks wrong
[Section titled “If something looks wrong”](#if-something-looks-wrong)
| It says | What it means | Do |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `claude mcp list` shows membase as *needs authentication* | consent not completed | `claude mcp login membase`, or `/mcp` in a session |
| *Which memories can you use?* answers none | connected, no Memory switched on | **Uses** on Claude Code’s page in Connect, or **Use in** on the Memory |
| the skill says it has no access | no key, or the key reaches nothing | Skills tab › **Create key**; or switch a Memory on for the key |
| a write comes back as a tool error, *token missing required scope* | the connection is consent-minted (read-only), or the key is Read | use a Read & write key |
| the first search takes a minute | the memory was asleep | nothing; the next one is quick |
| the model asks me to confirm a delete | a Full access key called delete or forget without `confirm=true` and got its `how` sentence | decide; only a Full access key can pass `confirm=true` |
# Codex
> Membase in the Codex CLI and IDE extension over MCP, with consent or a developer key, and the skill beside AGENTS.md.
Membase in the Codex CLI and IDE extension over MCP, with consent or a developer key, and the skill beside AGENTS.md.
Codex, the CLI and the IDE extension, reads Membase over MCP, and can take the skill as well.
## Before you start
[Section titled “Before you start”](#before-you-start)
* Codex CLI with `codex mcp`, or the IDE extension; they share one configuration.
* For a write-capable connection, a developer key from **Connect › Developer keys › Create key**.
## Set up
[Section titled “Set up”](#set-up)
```bash
codex mcp add membase --url https://api.app.membase.com/mcp-http
codex mcp login membase
codex mcp list
```
`codex mcp login` opens the browser on Membase’s consent screen; tick the Memories Codex may use and, if it may read the profile, **Profile access**. `codex mcp list` shows the server and whether it is authorized.
In the IDE extension: the gear menu → *MCP servers* → add the same server, then *Restart extension* and *Authenticate*. A server added on one side appears on the other.
## With a developer key
[Section titled “With a developer key”](#with-a-developer-key)
Have Codex send the key from an environment variable instead of logging in. In `~/.codex/config.toml`:
```toml
[mcp_servers.membase]
url = "https://api.app.membase.com/mcp-http"
bearer_token_env_var = "MEMBASE_API_KEY"
```
Codex reads the variable from the environment it starts in, so `export MEMBASE_API_KEY=mbk_…` in your shell profile. The key’s level applies, up to Full access. `http_headers` (static values) and `env_http_headers` (values taken from environment variables) under the same table set other headers. The snippet Membase serves at `https://app.membase.com/plugin/clients/codex.toml` is the server alone, without the key line.
Or the skill:
> Install Membase from using key mbk\_…
Codex installs the folder beside `AGENTS.md` and points to it from there. The key has to reach the commands Codex runs in later sessions: keep `MEMBASE_API_KEY` in the environment Codex starts from, or under `set` in `[shell_environment_policy]` in `config.toml` (its `config.toml` has no top-level `env` table). With the MCP tools already present it uses those and keeps the skill for its rules.
## What it can do
[Section titled “What it can do”](#what-it-can-do)
With consent: `get_capabilities`, `search_memories`, `list_memories`, `get_memory`, `list_media`, `get_media`, `search_media` and, when ticked, `list_profile_facts`; nothing that writes. With a key: the key’s level, up to Full access; the tools per level are on [Any MCP client](/connect/clients/membase-mcp/#what-a-connected-client-sees).
## Which Memories it uses
[Section titled “Which Memories it uses”](#which-memories-it-uses)
An empty list of memories means no Memory is switched on for this connection. Switch one on under **Uses** on Codex’s page in Connect (with a key: on the key’s page), or under **Use in** on the Memory.
Codex and the ChatGPT connector register with Membase under the same client name. Membase tells them apart and shows two tiles on Connect; each has its own **Uses** switches and its own **Disconnect…**.
## Remove it
[Section titled “Remove it”](#remove-it)
`codex mcp remove membase`, then **Disconnect…** on Codex’s page in Connect or **Revoke…** the key.
## If something looks wrong
[Section titled “If something looks wrong”](#if-something-looks-wrong)
| It says | What it means | Do |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `codex mcp list` shows the server without authorization | consent not completed | `codex mcp login membase` |
| it can use no memories | connected, no Memory switched on | **Uses** on Codex’s page in Connect |
| a write is refused | the connection is consent-minted (read-only), or the key is Read | give Codex a Read & write key through `bearer_token_env_var` or the skill |
| Membase fails to connect with `bearer_token_env_var` | `MEMBASE_API_KEY` is not set where Codex starts, or the key is unknown, expired or revoked: the server answers `401 invalid_token` to every request | export the variable; or mint a new key and update it |
| the extension does not see the server | it was added before the extension restarted | *Restart extension*, then *Authenticate* |
# Cursor
> Membase in Cursor through mcp.json, in one project or globally, with consent or a developer key.
Membase in Cursor through mcp.json, in one project or globally, with consent or a developer key.
Cursor reads Membase over MCP from a JSON file, in one project or for every project, and its agent can take the skill as well.
## Before you start
[Section titled “Before you start”](#before-you-start)
* Cursor with MCP enabled under **Customize** in the sidebar.
* For a write-capable connection, a developer key from **Connect › Developer keys › Create key**.
## Set up
[Section titled “Set up”](#set-up)
`.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` for every project:
```json
{ "mcpServers": { "membase": { "url": "https://api.app.membase.com/mcp-http" } } }
```
Open **Customize** in the sidebar, enable Membase and complete the OAuth prompt: the browser opens Membase’s consent screen, where you tick the Memories Cursor may use and, if it may read the profile, **Profile access**. Check that its tools appear under **Available Tools** in chat, then ask *“Which Membase memories can you use?”*.
## With a developer key
[Section titled “With a developer key”](#with-a-developer-key)
Add the header; the key’s level applies, up to Full access:
```json
{ "mcpServers": { "membase": {
"url": "https://api.app.membase.com/mcp-http",
"headers": { "Authorization": "Bearer mbk_…" } } } }
```
The token screen right after **Connect › Developer keys › Create key** writes this block with the key filled in, on its **Cursor / VS Code** tab; the key’s page later shows no snippets. Keep a file that holds a key out of version control; the consent form of the file is safe to commit.
Or the skill: paste the sentence from Connect’s **Skills** tab and Cursor’s agent installs the skill folder in the project, points to it from the rules file and keeps the key. With the MCP tools already present it uses those and keeps the skill for its rules.
## What it can do
[Section titled “What it can do”](#what-it-can-do)
With consent: `get_capabilities`, `search_memories`, `list_memories`, `get_memory`, `list_media`, `get_media`, `search_media` and, when ticked, `list_profile_facts`, and nothing that writes. With a key: the key’s level; the tools per level are on [Any MCP client](/connect/clients/membase-mcp/#what-a-connected-client-sees).
## Which Memories it uses
[Section titled “Which Memories it uses”](#which-memories-it-uses)
An empty list of memories means no Memory is switched on for this connection. Switch one on under **Uses** on Cursor’s page in Connect, or on the key’s page, or under **Use in** on the Memory.
## Remove it
[Section titled “Remove it”](#remove-it)
Delete the entry from `mcp.json`, then **Disconnect…** on Cursor’s page in Connect or **Revoke…** the key.
## If something looks wrong
[Section titled “If something looks wrong”](#if-something-looks-wrong)
| It says | What it means | Do |
| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| the server shows red under MCP | the URL is wrong, or consent was not completed | check the URL is the exact address, path included; retry the prompt; the Output panel’s MCP Logs has the error |
| Membase cannot connect, or asks to authenticate, with a key in `headers` | the key is unknown, expired or revoked: the server answers `401 invalid_token` to every request, so no tools load | mint a new key and update the file |
| it can use no memories | connected, no Memory switched on | **Uses** on Cursor’s page in Connect |
| a project file with a key was committed | the token is public | **Revoke…** it now and mint another |
# Grok
> Membase in Grok on grok.com, as a custom connector with OAuth consent in the browser.
Membase in Grok on grok.com, as a custom connector with OAuth consent in the browser.
Grok takes custom MCP servers as **connectors**, added at `grok.com/connectors`. The menus are the vendor’s own and move with its releases; the Membase side, the URL, the consent screen and the app’s page on Connect, is the same as for every other client. Grok has no tile of its own in Connect’s client catalog: it appears under **Other apps**, with a monogram, once the consent completed.
## Before you start
[Section titled “Before you start”](#before-you-start)
* A Grok plan that allows connectors. On a Business or Enterprise plan a team admin provisions them first.
* A Membase account with at least one Memory that has run once.
## Set up
[Section titled “Set up”](#set-up)
1. Open `grok.com/connectors`.
2. **New Connector → Custom**.
3. Enter the server URL, `https://api.app.membase.com/mcp-http`, and complete the authentication: the browser opens Membase’s consent screen. Tick the Memories Grok may use and, if it may read the profile, **Profile access**; press **Approve access**.
4. Grok discovers the tools the server exposes for that consent. Ask *“Which Membase memories can you use?”*
## With a developer key
[Section titled “With a developer key”](#with-a-developer-key)
Grok’s connector dialog has no header field, so a person’s Grok connects by consent only. Grok’s **API** also takes remote MCP servers as tools on a request; that is a developer integration rather than a plugin, and it works with a developer key in the server’s `Authorization` header the way [MCP frameworks](/build/integrations/mcp-frameworks/) describes.
## What it can do
[Section titled “What it can do”](#what-it-can-do)
`get_capabilities`, `search_memories`, `list_memories`, `get_memory`, `list_media`, `get_media`, `search_media` and, when ticked, `list_profile_facts`. Nothing that writes.
## Which Memories it uses
[Section titled “Which Memories it uses”](#which-memories-it-uses)
An empty list of memories means no Memory is switched on for this connection. Switch one on under **Uses** on Grok’s page in Connect, or under **Use in** on the Memory. Grok’s page exists under **Other apps** on Connect once the consent completed, whatever Grok’s own screen says; like every other app’s page it has **Uses** and **Disconnect…**, and **Approvals** once Grok holds more than one credential.
## Remove it
[Section titled “Remove it”](#remove-it)
Remove the connector on the same page, and **Disconnect…** on Grok’s page in Membase’s Connect; the client does not tell the server.
## If something looks wrong
[Section titled “If something looks wrong”](#if-something-looks-wrong)
| It says | What it means | Do |
| ----------------------------------- | -------------------------------------------------------------------- | ----------------------------------- |
| the connector never authorizes | the URL has a typo or misses the path, or the consent tab was closed | paste the URL exactly; add it again |
| it can use no memories | connected, no Memory switched on | **Uses** on Grok’s page in Connect |
| no **New Connector** on a team plan | connectors are provisioned by the admin | ask the admin to add the URL |
# Kimi Code
> Membase in the Kimi Code CLI over Streamable HTTP, with OAuth consent or a developer key in the header, and the skill.
Membase in the Kimi Code CLI over Streamable HTTP, with OAuth consent or a developer key in the header, and the skill.
**Kimi Code CLI** connects to remote MCP servers over Streamable HTTP, and reads pages and runs commands, so it can take the skill as well.
## Before you start
[Section titled “Before you start”](#before-you-start)
* Kimi Code CLI. It has no `kimi mcp` command: MCP servers are declared in `mcp.json`, or added with `/mcp-config` inside a session.
* For a write-capable connection, a developer key from **Connect › Developer keys › Create key**.
## Set up
[Section titled “Set up”](#set-up)
Add the server to `~/.kimi-code/mcp.json` for every project, or to `.kimi-code/mcp.json` in one project:
```json
{ "mcpServers": { "membase": { "url": "https://api.app.membase.com/mcp-http" } } }
```
`/mcp-config` in a session adds the same entry without editing the file. A server added while a session is open joins only the sessions started after it. In a new session run:
```text
/mcp-config login membase
```
The browser opens Membase’s consent screen. Tick the Memories Kimi Code may use and, if it may read the profile, **Profile access**. `/mcp` shows the server’s connection status. Kimi Code has no tile of its own in Connect’s client catalog: it appears under **Other apps** once the consent completed.
## With a developer key
[Section titled “With a developer key”](#with-a-developer-key)
Name an environment variable that holds the key, instead of logging in:
```json
{ "mcpServers": { "membase": {
"url": "https://api.app.membase.com/mcp-http",
"bearerTokenEnvVar": "MEMBASE_API_KEY" } } }
```
and `export MEMBASE_API_KEY=mbk_…` in the shell that starts Kimi Code. A static `"headers": { "Authorization": "Bearer mbk_…" }` works too; keep a file that holds a key out of version control. The key’s level applies, up to Full access. The skill sentence from Connect’s **Skills** tab works as well: Kimi Code installs the folder and keeps the key as `MEMBASE_API_KEY`.
## What it can do
[Section titled “What it can do”](#what-it-can-do)
With consent: `get_capabilities`, `search_memories`, `list_memories`, `get_memory`, `list_media`, `get_media`, `search_media` and, when ticked, `list_profile_facts`; nothing that writes. With a key: the key’s level; the tools per level are on [Any MCP client](/connect/clients/membase-mcp/#what-a-connected-client-sees).
## Which Memories it uses
[Section titled “Which Memories it uses”](#which-memories-it-uses)
An empty list of memories means no Memory is switched on for this connection. Switch one on under **Uses** on Kimi Code’s page in Connect (under **Other apps**), or under **Use in** on the Memory.
## Remove it
[Section titled “Remove it”](#remove-it)
Delete the `membase` entry from `mcp.json`, or remove it with `/mcp-config`; sessions already open list it as `removed` until they end. Then **Disconnect…** on Kimi Code’s page in Connect or **Revoke…** the key. A consent token Kimi Code still holds stops working once you disconnect.
## If something looks wrong
[Section titled “If something looks wrong”](#if-something-looks-wrong)
| It says | What it means | Do |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `/mcp` shows Membase not authorized | consent not completed | `/mcp-config login membase` |
| `/mcp` does not list Membase | the entry was added while this session was open | start a new session |
| it can use no memories | connected, no Memory switched on | **Uses** on Kimi Code’s page in Connect |
| a write is refused | the connection is consent-minted (read-only), or the key is Read | use a Read & write key through `bearerTokenEnvVar` or `headers` |
| Membase fails to connect with a key | `MEMBASE_API_KEY` is not set in Kimi Code’s environment, or the key is unknown, expired or revoked: the server answers `401 invalid_token` to every request, so no tools load | set the variable; or mint a new key, update `MEMBASE_API_KEY` (or the header) and start a new session |
# Any MCP client
> The MCP server itself: how a client discovers it, the two ways to authenticate, what a connected client sees, the ready-made config files, and the clients without a page of their own.
The MCP server itself: how a client discovers it, the two ways to authenticate, what a connected client sees, the ready-made config files, and the clients without a page of their own.
```plaintext
https://api.app.membase.com/mcp-http
```
One URL for every client. Streamable HTTP, JSON responses, with or without a trailing slash (both answer the same; what fails is a wrong path such as `/mcp`). The server speaks the current MCP specification and advertises its authorization the standard way, so a client that can add “a remote MCP server with OAuth” can add Membase without a special step. The SDK also ships a local stdio server, `membase --local mcp` (from `unibaseio-membase[local]`); see the [SDK quickstart](/build/reference/sdk-quickstart/).
## Two ways to authenticate
[Section titled “Two ways to authenticate”](#two-ways-to-authenticate)
**OAuth consent**, for the person’s own AI apps. An unauthenticated request answers `401` with `WWW-Authenticate` pointing at `https://api.app.membase.com/.well-known/oauth-protected-resource/mcp-http` (RFC 9728). The metadata names the authorization server and its registration endpoint; the client registers itself (RFC 7591) and runs the authorization code flow with PKCE. The browser opens Membase’s consent screen; the person ticks the Memories the app may use and whether it may read their profile; the client receives a token good for that and nothing else.
**A developer key in the header**, for a client that can send a static header and a person who prefers a key they minted:
```plaintext
Authorization: Bearer mbk_…
```
No consent round-trip; the key’s access level and reach apply, up to Full access. An unknown, expired or revoked key gets `401` with `WWW-Authenticate: Bearer error="invalid_token"` on every request, `initialize` and `tools/list` included, so the client reports that it cannot connect or needs authentication rather than showing tools. The ready-made config files carry no header, so a key never ends up in a public file.
## What a connected client sees
[Section titled “What a connected client sees”](#what-a-connected-client-sees)
The tools are the memory API’s operations under their tool names, with the same arguments and the same answers as REST ([API reference](/build/reference/api-reference/)). No tool takes a Memory: reads cover every Memory the credential reaches, and a write lands in the one text Memory it reaches. `tools/list` is filtered per caller and shows only what the credential holds.
| Credential | Tools offered |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| consent token | `get_capabilities`, `search_memories`, `list_memories`, `get_memory`, `list_media`, `get_media`, `search_media`; `list_profile_facts` when the person ticked **Profile access**. Read-only: it never writes and never confirms |
| developer key, Read | `get_capabilities`, `search_memories`, `list_memories`, `get_memory`, `list_documents`, `get_document`, `list_media`, `get_media`, `search_media`; `list_profile_facts` with **Your profile** ticked |
| developer key, Read & write | plus `add_memory`, `add_document`; `add_profile_fact` with the profile tick |
| developer key, Full access | plus `forget_memory`, `delete_document`, `delete_media`; `forget_profile_fact` with the profile tick; each only with `confirm=true` |
| a marketplace buyer’s credential | `get_capabilities` and `ask_memory`, on the one Memory bought: answers, never passages |
A call to a tool outside the caller’s list is refused as a tool error (HTTP `200`, `isError: true`), not an HTTP status: *token missing required scope* when a read-only credential (a consent token or a Read key) calls a writing tool, *tool ‘…’ is not in this agent’s capability profile* when the tool is above a key’s level otherwise. A consent-minted client cannot write, delete or forget at all. The REST API answers the same refusals with `403 unauthorized`. A Full access key that calls a destructive tool without `confirm=true` gets a tool error with `confirmation_required` and a `how` sentence for the model to relay; nothing changed. `get_capabilities` names what the connection holds, the Memories it reaches and the person’s standing rules (`rules`); there is no separate rules tool.
The protocol before this one had `list_containers`, `memory_rules`, `get_profile`, `ask_agent`, `workflow_invoke`, a `container` argument and the `memory_*` names. None of them is offered any more, and a `container` argument is refused like any unknown field.
A search is a turn inside the person’s memory. The first one after a quiet spell can take up to a minute; the answer names in `partial` any Memory that could not answer yet, and the model should say so rather than answer from nothing.
## Ready-made config files
[Section titled “Ready-made config files”](#ready-made-config-files)
Use these published configuration files and references for your client:
| File | For |
| ------------------------------------------------------------ | ------------------------------------------------------ |
| `https://app.membase.com/plugin/mcp.json` | the server in the `mcpServers` shape most clients read |
| `https://app.membase.com/plugin/clients/vscode.mcp.json` | VS Code’s `servers` shape |
| `https://app.membase.com/plugin/clients/codex.toml` | Codex’s `config.toml` snippet |
| `https://app.membase.com/plugin/membase-skill.zip` | the skill folder |
| `https://app.membase.com/plugin/openapi/agent-protocol.json` | the OpenAPI document |
| `https://app.membase.com/skill` | the skill’s `SKILL.md` with its install preamble |
## Other clients
[Section titled “Other clients”](#other-clients)
The clients with a page of their own are [ChatGPT](/connect/clients/chatgpt/), [Claude](/connect/clients/claude/), [Claude Code](/connect/clients/claude-code/), [Cursor](/connect/clients/cursor/), [Codex](/connect/clients/codex/), [Grok](/connect/clients/grok/) and [Kimi Code](/connect/clients/kimi-code/). Everything else takes the same URL.
### VS Code (Copilot agent mode)
[Section titled “VS Code (Copilot agent mode)”](#vs-code-copilot-agent-mode)
Command palette → *MCP: Add Server* → *HTTP* → the URL → complete the OAuth prompt, or in `.vscode/mcp.json`:
```json
{ "servers": { "membase": { "type": "http", "url": "https://api.app.membase.com/mcp-http" } } }
```
### Windsurf
[Section titled “Windsurf”](#windsurf)
`~/.codeium/windsurf/mcp_config.json`, in the `mcpServers` shape:
```json
{ "mcpServers": { "membase": { "serverUrl": "https://api.app.membase.com/mcp-http" } } }
```
Then refresh the MCP list in Windsurf’s settings and complete the OAuth prompt.
### Devin
[Section titled “Devin”](#devin)
```bash
devin mcp add --scope user membase https://api.app.membase.com/mcp-http
devin mcp login membase
```
### Any `mcpServers`-shaped client
[Section titled “Any mcpServers-shaped client”](#any-mcpservers-shaped-client)
Merge `https://app.membase.com/plugin/mcp.json` into the client’s configuration:
```json
{ "mcpServers": { "membase": { "type": "http", "url": "https://api.app.membase.com/mcp-http" } } }
```
Claude Desktop’s `claude_desktop_config.json` is for local servers it launches itself; add Membase in Claude as a custom connector instead, as [Claude](/connect/clients/claude/) describes.
### Any other client, or your own
[Section titled “Any other client, or your own”](#any-other-client-or-your-own)
Use the same URL. The server advertises OAuth discovery on a `401`, accepts a bearer developer key in `Authorization`, and speaks Streamable HTTP. An agent framework without an MCP client can take `SKILL.md` as instructions and the REST API directly; [MCP frameworks](/build/integrations/mcp-frameworks/) and [AI coding tools](/build/integrations/ai-coding-tools/) have the shapes.
## Verifying and revoking
[Section titled “Verifying and revoking”](#verifying-and-revoking)
The **Connect** page shows every authorized client with its last activity. A client’s page has the per-Memory switch (*Uses*), the credential list (*Approvals*, shown when there is more than one) and **Disconnect…** for all of them. A client without a tile of its own is listed under **Other apps** once authorized. Removing a connector inside the client does not notify Membase: revoke on Connect to be sure access has stopped. Revocation takes effect on the credential’s next call.
# Access control
> What a connected client may do, decided by its credential and by the switches on Connect: reach, level, the profile tick, confirmation, and revocation.
What a connected client may do, decided by its credential and by the switches on Connect: reach, level, the profile tick, confirmation, and revocation.
A connected AI can do exactly what its credential allows, and the credential is the person’s: they minted it or approved it, and they change it on the **Connect** page without touching the client. Every rule below is enforced on the server, on the credential’s next call; nothing here depends on the client behaving.
## Two credentials, two ceilings
[Section titled “Two credentials, two ceilings”](#two-credentials-two-ceilings)
| | Consent (an app connected over MCP) | Developer key (the skill, a header, code) |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Ceiling | read-only, always | the key’s level: Read, Read & write, Full access |
| Reach | the Memories ticked on consent, switchable later | the Memories ticked on the key, or all including later ones |
| Profile | read, when **Profile access** was ticked on the consent screen | when **Your profile** was ticked: read, and at higher levels keep or forget a statement |
| Confirmation | is not offered a delete or forget at all | can, with `confirm=true` at Full access |
| Ends | **Disconnect…** on the app’s page, per credential under **Approvals**, or expiry after 90 days (the tile then says *Approval expired · authorize again*) | **Revoke…**, or expiry |
An app that needs to write does not get a wider consent; the person mints a key for it instead, and the key says how wide.
## Reach
[Section titled “Reach”](#reach)
Reach is the list of Memories a credential may use. It has one state and three views of it: the **Uses** card on the client’s page in Connect, the **Use in** card on the Memory’s page, and the **Memory access** switches on a key’s page. Off takes effect on the very next call.

No call names a Memory: searches and lists cover the Memories in reach and leave the others out, and an id from a Memory outside the reach answers `404`, the same as one that does not exist, over MCP and REST alike. `get_capabilities` (`GET /v1/capabilities`) does not list it. A client cannot tell withheld from absent, and cannot ask for more; only the person can switch it on.
## The tool list is the grant
[Section titled “The tool list is the grant”](#the-tool-list-is-the-grant)
`tools/list` is filtered per caller. A consent-minted client is offered `get_capabilities`, `search_memories`, `list_memories`, `get_memory`, the media reads and, when ticked, `list_profile_facts`, and nothing that writes; a key is offered the tools of its level; a marketplace buyer’s credential is offered `get_capabilities` and `ask_memory` alone. A model cannot call what it was not offered, and a call that bypasses the list is refused anyway: over MCP as a tool error (*token missing required scope*, or *not in this agent’s capability profile*), over REST as `403 unauthorized`. The table per credential is on [Any MCP client](/connect/clients/membase-mcp/#what-a-connected-client-sees), and per level on [Authentication & Scopes](/build/reference/authentication/#access-levels).
## Destructive verbs
[Section titled “Destructive verbs”](#destructive-verbs)
`forget_memory`, `delete_document`, `delete_media` and `forget_profile_fact` exist only at Full access, and even there they do not execute on a bare call: without `confirm=true` nothing changes and the answer is `428 confirmation_required` (over MCP, a tool error with the same code) with a `how` sentence for the model to relay. A consent-minted client is never offered these verbs, and a call is refused (a tool error, *token missing required scope*; `403` over REST) rather than answered with the sentence. From a Full access key, `confirm=true` counts as the owner’s confirmation, which is why the skill tells the AI to pass it only after the person agreed.
Deleting a Memory, a source’s material or the account has no agent-protocol verb at all; those belong to the owner’s session, in the app.
## The profile
[Section titled “The profile”](#the-profile)
The profile is about the person, not a topic, so it is granted separately from reach. It is a list of standing statements (name, role, lasting preferences). A client offered `list_profile_facts` reads them; one that was not ticked is not offered any profile tool. On a key the tick is **Your profile**, changeable later on the key’s page, and what it grants follows the key’s level: reading at Read, keeping a statement (`add_profile_fact`) at Read & write, forgetting one (`forget_profile_fact`, with `confirm=true`) at Full access. A key minted before the profile became a list holds the read only until the owner changes the key. On a consent connection it is **Profile access**, set only on the consent screen: to change it, **Disconnect…** the app and authorize it again.
## Revocation
[Section titled “Revocation”](#revocation)
* **Disconnect…** on a client’s page revokes every credential that client holds, at once.
* **Revoke** under **Approvals** ends one credential when a client holds several.
* **Revoke…** on a key ends it at once; it stays listed for thirty days.
* Removing the connector inside the client does not tell Membase. Revoke on Connect to be sure.
Revocation and permission changes apply to subsequent requests. They do not remove content an external client has already received. A revoked key must be replaced with a new key; reconnecting an app requires a new authorization.
## Seeing what a client did
[Section titled “Seeing what a client did”](#seeing-what-a-client-did)
A client’s page on Connect shows its last activity. A key’s page shows **Usage** (calls, refusals, the tool it calls most) and **Recent activity** (each call: tool, Memory, what came back, when; a refused call in red with the reason). A refusal is the sign that a client asked for a Memory or a verb it does not have, which is usually the person’s cue to widen it or to leave it.
## Rules the skill teaches the model
[Section titled “Rules the skill teaches the model”](#rules-the-skill-teaches-the-model)
Because the server enforces the ceiling, the skill’s rules are about behaving well beneath it: list the profile facts first when they are granted; search before answering about the person’s past work; cite the Memory a result came from (`memory_name`); save only what the person supplied; never pass `confirm` on the model’s own initiative; treat `403` as withdrawn access and ask the person rather than retry.
# Troubleshooting
> Every word and status a connected client, the Connect page or the API can show, and what to do about it.
Every word and status a connected client, the Connect page or the API can show, and what to do about it.
Look up the word on screen, or the status in the answer.
## On the Connect page
[Section titled “On the Connect page”](#on-the-connect-page)
| It says | What it means | Do |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| *Set up* on a tile | this app is not connected | pick the tile and follow the steps |
| *No memory access* (amber) on an app’s page | connected, but no Memory switched on | turn a switch on under **Uses** |
| the app cannot see a Memory | its switch is off | Memory page › **Use in** |
| I removed the app in Claude or ChatGPT but it still shows *Authorized* | the app did not tell Membase | **Disconnect…** on the app’s page |
| *The MCP address is unavailable* | the page could not ask the server for it | reload; the sentence for your AI still works |
| my AI installed the skill but says it has no access | the skill needs a developer key | Skills tab › **Create key**, and paste the sentence |
| a key’s row says *Expired* | its token has lapsed | **⋯ › Create a similar key** |
| an app’s tile says *Approval expired · authorize again* | its consent approval lapsed: an approval lasts 90 days and is not renewed automatically, and the MCP endpoint now answers it `401 invalid_token` | run the client’s login again, or remove and re-add the connector, and approve |
| two tiles for ChatGPT and Codex | they register under one client name; Membase tells them apart | nothing |
## In the client
[Section titled “In the client”](#in-the-client)
| It says | What it means | Do |
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| the server never authorizes | the URL has a typo or a wrong path (`/mcp`, a bare domain), or the consent tab was closed | paste `https://api.app.membase.com/mcp-http` exactly; run the login again |
| *Which memories can you use?* answers none | connected, no Memory switched on | **Uses** on the client’s page, or **Use in** on the Memory |
| the client cannot connect, or says it needs authentication, with a key in its header | the key is unknown, expired or revoked: the MCP endpoint answers `401 invalid_token` to every request, `initialize` and `tools/list` included, so no tools load | mint a new key and update the client’s configuration |
| a write is refused (a tool error, *token missing required scope*) | the connection is consent-minted (read-only), or the key is Read | mint a Read & write key and use it instead |
| the model says a Memory “could not answer yet” | the memory was asleep; the first search after a quiet spell wakes it | ask again in a moment |
| the model answers from nothing about the person | the profile tick is off | an app: **Disconnect…** and authorize again with **Profile access** ticked; a key: **Your profile** on the key’s page |
| the model asks me to confirm a delete | a Full access key called delete or forget without `confirm=true` and got its `how` sentence | decide; only a Full access key can pass `confirm=true` |
| a tool the model names is missing (`list_containers`, `get_profile`, `memory_rules`…) | the client cached the tool list of the protocol before this one | restart the client to refresh `tools/list`; the current names are on [Any MCP client](/connect/clients/membase-mcp/#what-a-connected-client-sees) |
## In the API answer
[Section titled “In the API answer”](#in-the-api-answer)
| Answer | Meaning | Do |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| `401 · unauthenticated` | REST: no bearer at all | send `Authorization: Bearer …` |
| `401 · unauthorized` on the MCP URL | no bearer: the OAuth discovery challenge, normal before consent | complete the client’s login |
| `401 · invalid_token` on the MCP URL | an unknown, expired or revoked token; the MCP endpoint answers every request this way, `initialize` and `tools/list` included | mint a new key, or authorize the app again; do not retry with this one |
| `403 · unauthorized` | REST: an unknown or expired token (*invalid token*), a revoked one (*token revoked or unknown*), or a suspended account (*account suspended*) | mint a new key; do not retry with this one |
| `404 · not_found` | an id outside the key’s reach, deleted, or not one of ours; a Memory switched off also drops out of searches and lists | switch the Memory on under **Memory access**; `GET /v1/capabilities` names the Memories in reach |
| `403 · unauthorized · token missing required scope` | a read-only credential (consent, or a Read key) called a tool that writes; over MCP the same text comes back as a tool error | mint a Read & write key |
| `403 · unauthorized · not in this agent's capability profile` | the tool is above this credential’s grant (a key’s level, or a consent connection calling a key-only read tool); over MCP the same text comes back as a tool error | raise the key’s level, or mint a higher key; a consent connection needs a developer key for it |
| `403 · unauthorized` on `ask_memory` | a developer key (keys do not hold it), or a marketplace purchase that is not active or whose calls for the period are used up | search instead; a buyer renews or waits for the next period |
| `428 · confirmation_required` | a Full access key’s destructive verb without `confirm=true`; nothing changed; over MCP the same code comes back as a tool error | pass `confirm=true` after the person agreed |
| `400 · validation` | an empty `q`, both or neither of `content` and `url`, a `limit` out of range | fix the request |
| `422 · validation` | a required field is missing or has the wrong type, or a field the API does not know (a `container`, a `model` on ask); `details.fields` names it | fix the request |
| `422 · write_target_required` | a write from a key that reaches several text Memories; nothing was written | use a key that reaches the one Memory writes should go to |
| `422 · capability_unavailable · no model` | the account has no working model | [AI Setup](/use/account-and-models/ai-setup/) |
| `422 · capability_unavailable · no agent containers` | the memory service is unavailable | contact support with the error and trace ID |
| `422 · reason: dormant` | a free-plan account whose free turns are spent | bring a model, or a paid plan |
| `429 · rate_limited` | the account’s concurrent-turn budget | retry later; the SDK retries twice with backoff |
| `202` with `id: null` | the folder sync had not written the row yet | list the documents in a moment |
| a search takes a minute | the memory was asleep | allow time for startup; check for errors if the request times out |
| `405 · method_not_allowed` on the MCP URL | the URL misses the MCP path: a bare domain or `/mcp` is the web app, which answers a browser with the app page and a client’s `POST` with `405` | use `https://api.app.membase.com/mcp-http` exactly; a trailing slash is fine |
| `invalid_target` when the client authorizes | a path below the endpoint, e.g. `/mcp-http/v1`: it answers `401` like the right URL, then the authorization refuses it | use `https://api.app.membase.com/mcp-http` exactly |
## On the extension
[Section titled “On the extension”](#on-the-extension)
| It says | What it means | Do |
| --------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
| **Install** never becomes **Use here** | the page cannot see the extension; it can only tell by what reached the wallet | sign the extension in with the same wallet, have a conversation, reload |
| *Reading* but the Memory learns nothing | nothing uploaded yet, or the Memory has not run | check the extension’s log, then select **Update now** on the Memory |
| the Memory reads like a log | the instruction is a topic | rewrite it as a filter on the chats |
## Reporting a problem
[Section titled “Reporting a problem”](#reporting-a-problem)
Every error envelope carries a `trace_id`. Quote it, with the key’s hint (never the token), the tool, and the time.
# Benchmarks
> LoCoMo, LongMemEval_S and DMR results for the local Membase engine (unibaseio-membase-core), with the method behind each number.
LoCoMo, LongMemEval_S and DMR results for the local Membase engine (unibaseio-membase-core), with the method behind each number.
This report covers `unibaseio-membase-core`, the engine that `pip install 'unibaseio-membase[local]'` runs on your machine. The hosted Membase service does not run this engine today, so these scores and latency figures are not measurements of the hosted Membase API, account startup, or an end-to-end app task. For hosted search behavior and timeouts, see [How Membase works](/build/concepts/how-membase-works/) and [API troubleshooting](/build/reference/troubleshooting/).
The engine is measured on three public long-term-memory benchmarks: **LoCoMo**, **LongMemEval\_S** and **DMR**. Each accuracy number below is one pass over the full question set, graded by a gpt-4o-mini judge with one prompt per benchmark; the latency and context-token rows come from the timing samples noted under the latency table. Powered by episodic extraction and multi-round retrieval that sends the reader a few thousand tokens instead of the whole history.
| | LoCoMo | LongMemEval_S | DMR |
| --------------------------------------------------------- | ------------ | ------------- | ----------- |
| **Accuracy** | **93.1%** | **92.6%** | **92.2%** |
| Questions | 1,540 | 500 | 500 |
| Context tokens per question (mean over the timing sample) | 6,562 | 8,970 | 1,602 |
| Full history per question | \~20k | \~103k | — |
| Token reduction | 3× | 11× | — |
| Reader model | gpt-4.1-mini | gpt-5.5 | gpt-4o-mini |
## LoCoMo
[Section titled “LoCoMo”](#locomo)
1,540 questions in four categories: single-hop, multi-hop, open-domain and temporal recall across multi-session conversations spanning months.
| Category | Questions | Accuracy |
| ----------- | --------- | --------- |
| single-hop | 841 | 94.6% |
| multi-hop | 282 | 93.6% |
| temporal | 321 | 91.6% |
| open-domain | 96 | 83.3% |
| **overall** | **1,540** | **93.1%** |
Mean context over the 40-question timing sample: 6,562 tokens, three times below the full history. 98.1% of the evidence sessions reach the reader. Swapping the reader model moves the score by less than 0.1 points.
## LongMemEval_S
[Section titled “LongMemEval_S”](#longmemeval_s)
500 questions in six types. Each question comes with its own 103k-token, roughly 50-session history; the reader sees only what memory retrieves.
| Question type | Questions | Accuracy |
| ------------------------- | --------- | --------- |
| single-session preference | 30 | 100% |
| single-session user | 70 | 98.6% |
| knowledge update | 78 | 97.4% |
| temporal reasoning | 133 | 92.5% |
| multi-session | 133 | 88.0% |
| single-session assistant | 56 | 85.7% |
| **overall** | **500** | **92.6%** |
Mean context over the 30-question timing sample: 8,970 tokens, eleven times below the full history. 99.95% of the evidence sessions are retrieved, and 99.8% of questions get every one of theirs. 29 of the 30 unanswerable questions were correctly abstained.
## DMR
[Section titled “DMR”](#dmr)
MemGPT’s Deep Memory Retrieval set: 500 questions, five sessions each, run in Zep’s harness with MemGPT’s judge prompt and gpt-4o-mini as reader and judge.
| Outcome | Questions | Share |
| --------------------------- | --------- | ----- |
| correct | 461 | 92.2% |
| abstained | 4 | 0.8% |
| lost a detail in extraction | 35 | 7.0% |
Mean context over the 30-question timing sample: 1,602 tokens.
## Latency and tokens
[Section titled “Latency and tokens”](#latency-and-tokens)
| | LoCoMo | LongMemEval_S | DMR |
| ---------------------------------- | --------------- | --------------- | --------------- |
| search latency, p50 / p95 | 1.67 s / 7.02 s | 2.53 s / 6.11 s | 1.13 s / 1.71 s |
| end-to-end, p50 / p95 | 8.30 s / 18.0 s | 14.7 s / 30.2 s | 3.21 s / 6.34 s |
| context tokens per question (mean) | 6,562 | 8,970 | 1,602 |
The latency and context-token rows were measured on samples, not the full sets: 40 LoCoMo questions, 30 LongMemEval_S and 30 DMR, timed serially on 2026-09-21. In these runs, search takes 1.1 to 2.5 s at the median, including one to three decider rounds. End to end is 3 to 15 s at the median depending on the reader model. These figures exclude hosted runtime wake-up and are not a service latency guarantee.
## Why the numbers look this way
[Section titled “Why the numbers look this way”](#why-the-numbers-look-this-way)
Each score traces back to a specific part of the architecture.
* **Recall correctness.** Every session is narrated into timestamped episodes that keep who, what and when together, so a fact is retrieved with its context. The retrieval decider reads the first hits and asks follow-up questions before settling, which is why 99.95% of LongMemEval_S evidence sessions are in context.
* **Context footprint.** Keyword and vector search are fused by reciprocal rank and only the top twenty episodes enter the prompt. That keeps a LongMemEval_S call at about 9,000 tokens against a 103k-token history, and a LoCoMo call at about 6,500 against 20k.
* **Response time.** One to three decider rounds per search, each a short call; the reader model dominates end-to-end time.
## What is inside
[Section titled “What is inside”](#what-is-inside)
Four pieces working together.
| | |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Boundary detection** | An LLM pass splits each session into topical cells before extraction, so one episode never straddles two subjects. |
| **Episodic extraction** | Each cell becomes a titled, timestamped narrative from the user’s point of view. Optional profile, fact and foresight layers sit beside it. |
| **Multi-round retrieval** | Hybrid search per sub-query, fused by reciprocal rank; a decider marks core evidence and issues new queries for up to three rounds. |
| **Local-first store** | SQLite and FAISS on disk, scoped per user, with any OpenAI-compatible model for extraction, retrieval and answering. |
## Method
[Section titled “Method”](#method)
* **Grading.** gpt-4o-mini judges every benchmark, with one prompt each: Memori’s CORRECT/WRONG prompt for LoCoMo, the same prompt plus LongMemEval’s official per-type rules for LongMemEval_S, and MemGPT’s prompt in Zep’s harness for DMR. Every question in the set is counted once; a failed call is graded wrong.
* **No re-runs.** Each accuracy number is one pass over the full question set. No best-of-N, no merging of re-runs. Each benchmark has one answer prompt; none carries rules for individual questions.
* **Models.** OpenAI only: gpt-4.1-mini for extraction and retrieval decisions, text-embedding-3-small for vectors, and the reader listed per benchmark. The same stores answer with any OpenAI-compatible model.
* **Reproducing.** The harness, dataset loaders, judge configuration and run commands live in [membase-bench](https://github.com/unibaseio/membase-bench), pinned to `unibaseio-membase-core==0.3.0`. The published numbers come from runs on 18–21 September 2026, before any engine release; 0.3.0 was released on 11 October.
## Which benchmark matters
[Section titled “Which benchmark matters”](#which-benchmark-matters)
LoCoMo tests recall across a long two-person history. LongMemEval_S tests finding one fact in a 103k-token haystack and updating or abstaining correctly. DMR tests the fidelity of what was extracted. A memory system needs all three, which is why each is reported separately.
## How this differs from RAG over the transcript
[Section titled “How this differs from RAG over the transcript”](#how-this-differs-from-rag-over-the-transcript)
Raw chunks lose who said what and when. Episodes are written with speaker, time and context attached, and retrieval can ask follow-up questions instead of taking the first top-k.
*Benchmark report, September 2026.*
# FAQ
> Answers about memories, connected apps, models, exports and deleting data.
Answers about memories, connected apps, models, exports and deleting data.
## What is a Memory?
[Section titled “What is a Memory?”](#what-is-a-memory)
A Memory organizes information about a topic, such as project decisions, reading notes or customers. Choose its sources, describe what it should retain, and update it manually or on a schedule. You control which apps and keys can access it. [Concepts](/concepts/).
## I added a folder. Why does my AI not know about it yet?
[Section titled “I added a folder. Why does my AI not know about it yet?”](#i-added-a-folder-why-does-my-ai-not-know-about-it-yet)
Adding a source makes its content available for processing. Select **Update now** on the Memory page, or wait for its scheduled update, to learn from that content. Check the run’s **Report** if the update fails. [Bring your material in](/use/bring-your-material-in/bring-material-in/).
## Why can the first search take longer?
[Section titled “Why can the first search take longer?”](#why-can-the-first-search-take-longer)
A search after a period of inactivity may take longer to start. Search also uses a model to find relevant information. If the request fails, check the model configuration and the error before assuming the Memory is empty. [Search behavior](/build/concepts/how-membase-works/#a-search-is-a-turn).
## Where can I manage and export my data?
[Section titled “Where can I manage and export my data?”](#where-can-i-manage-and-export-my-data)
Manage your material in **Files**, review learned content in **Memory**, and choose which apps can access it in **Connect**. Download an export from **Settings › Data & export**. If the export warning says agent memory files are missing, export again before relying on it as a backup. [Export and deletion](/use/account-and-models/settings/).
## What can a connected app do?
[Section titled “What can a connected app do?”](#what-can-a-connected-app-do)
An app authorized through the MCP consent screen can read the Memories you select. Profile access is a separate choice. For an integration that needs to add or remove content, create a developer key with the appropriate access level. [Access control](/connect/manage-access/access-control/).
## How do I stop an app accessing my memory?
[Section titled “How do I stop an app accessing my memory?”](#how-do-i-stop-an-app-accessing-my-memory)
Switch off a Memory under **Use in**, or use **Disconnect…** on the app’s page in **Connect** to revoke its approvals. These changes apply to subsequent requests. They do not remove content the external app has already received. Removing a connector only inside that app does not revoke its Membase authorization.
## Which model does it use? Do I need my own key?
[Section titled “Which model does it use? Do I need my own key?”](#which-model-does-it-use-do-i-need-my-own-key)
Use **AI Setup** to connect a supported provider key or subscription. A free account includes an initial allowance of chat turns. When that allowance is used, stored memories remain; continuing to run the assistant requires an available model source or a suitable plan. [AI Setup](/use/account-and-models/ai-setup/).
## What is the profile?
[Section titled “What is the profile?”](#what-is-the-profile)
The profile is a list of standing statements about you, such as your name, role and lasting preferences. Each says where it came from: you stated it, it was imported, or the assistant recorded it. You can grant access to it separately from access to individual Memories.
## What cannot be undone?
[Section titled “What cannot be undone?”](#what-cannot-be-undone)
Deleting a Memory removes its stored content. Deleting a conversation removes its transcript; information already saved to memory is retained. **Delete everything** in Settings removes account data while retaining your sign-in identity. Review each confirmation and download any data you want to keep before proceeding. [Deletion and access controls](/concepts/#stopping-and-undoing).
## How is this different from searching my files?
[Section titled “How is this different from searching my files?”](#how-is-this-different-from-searching-my-files)
A Memory processes source material and retains information for later retrieval. Updating a source and updating its Memory are separate actions. The [benchmarks](/evaluation/benchmarks/) measure the local memory engine (`unibaseio-membase[local]`), not hosted Memories or the hosted API.
Questions about API status codes, metadata filters or serving multiple users are covered in [API troubleshooting](/build/reference/troubleshooting/).
# Use Membase
> Start with a working Memory, then import more material, use your assistant, connect apps, and keep your memory up to date.
Start with a working Memory, then import more material, use your assistant, connect apps, and keep your memory up to date.
Start with the [quickstart](/use/getting-started/quickstart/): create a Memory, add a file, run it, and ask your assistant a question. You can connect another AI after that first success.
A **Memory** is a named collection of what Membase has learned about a topic. A **source** is the material it reads. Adding a source and learning from it are separate steps. [Concepts](/concepts/) explains the other product terms.

## Find your task
[Section titled “Find your task”](#find-your-task)
| I want to | Guide |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| sign in or replay the setup tour | [Sign in](/use/getting-started/sign-in/) · [Setup guide](/use/getting-started/first-run-guide/) |
| import my material | [Sources](/use/bring-your-material-in/bring-material-in/) · [Files](/use/bring-your-material-in/files/) · [Notion](/use/bring-your-material-in/notion/) · [Browser extension](/use/bring-your-material-in/browser-extension/) |
| create, update, inspect or edit a Memory | [Memory](/use/manage-your-memory/memory/) |
| talk to my assistant | [Home](/use/use-your-assistant/home/) · [Telegram](/use/use-your-assistant/telegram/) |
| let another AI use my memory | [Connect your AI](/connect/) |
| change access or manage developer keys | [Connect](/use/manage-your-memory/connect/) |
| update automatically or investigate a failure | [Schedules](/use/automate-and-troubleshoot/schedules/) · [Activity](/use/automate-and-troubleshoot/activity/) |
| buy or sell access to a Memory | [Marketplace](/use/share-and-trade/marketplace/) |
| choose a model or manage my account | [AI Setup](/use/account-and-models/ai-setup/) · [Settings](/use/account-and-models/settings/) |
| customize an agent or its workflow | [Studio](/use/advanced/studio/) · [Agents](/use/advanced/agents/) |
To use memory from code, start with the [API quickstart](/build/getting-started/api-quickstart/).
# AI Setup
> Where the account's model comes from: your own provider key or a Claude or ChatGPT subscription, verified before use.
Where the account’s model comes from: your own provider key or a Claude or ChatGPT subscription, verified before use.
AI Setup is where the account’s model comes from.

Two ways in:
* **Bring your own key** for a provider (OpenAI, Anthropic, Gemini, DeepSeek, Moonshot (Kimi), Alibaba Qwen, OpenRouter, or OpenAI-compatible for any other endpoint). Press **Connect**, paste the key, pick a model from the list the key returns. A key with no model is not saved.
* **A Claude or ChatGPT subscription.** Press **Connect** on the subscription card and sign in with that provider. Turns are then billed to the subscription.
The **Connected** tab lists what you have set up; one of them is marked **Default provider**. **Use this** on another row, or **Set as default provider** once a new key verifies, moves it there. The default provider answers everything that is not an agent turn. Which source *the assistant* runs on is the assistant’s own field, in its settings on Home.
## Where the call goes
[Section titled “Where the call goes”](#where-the-call-goes)

Your agent never holds the key or the subscription. It asks Membase for a turn, and Membase makes the call to the provider under this page’s settings. Without a model here, memory stays but nothing can run.
## Verify
[Section titled “Verify”](#verify)
Each connection is verified with one short real request before it is used. A key that fails verification is never used, and the row says why.
## If something looks wrong
[Section titled “If something looks wrong”](#if-something-looks-wrong)
Look up the word on screen.
| It says | What it means | Do |
| -------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| *Not connected* on a subscription card | you have not signed in with that provider | **Connect** and finish the provider’s sign-in |
| a failure reason on a key’s row | the one test request with that key did not succeed; the key is not used | check the key, then **Retry**, or change the model and **Save & verify** |
| everything works except agent turns | the account’s default provider is set, the assistant’s own model source is not | Home › ⚙ **Assistant settings** (beside **Remote**) › model card |
# Settings
> Manage your account, plan, payments, your profile, exports and account-data deletion.
Manage your account, plan, payments, your profile, exports and account-data deletion.
Manage your account, plan, transactions, profile and data.

## Account
[Section titled “Account”](#account)
View or edit your display name, check your sign-in identity, and copy your account identifier when contacting support. **Sign out** ends your current session.
## Plan & usage
[Section titled “Plan & usage”](#plan--usage)
Review your storage usage, quota and free chat turns. Select **Change plan** to view available plans and their terms. Check the confirmation before making a payment or changing your plan.
* An upgrade applies after payment succeeds.
* A scheduled downgrade keeps the current plan until the date shown. **Keep current plan** cancels that scheduled change.
* **Cancel subscription** stops renewal and pauses metered usage at once. The paid period’s storage is kept until it ends, with no refund for the rest of it. The page shows the period end and any pending change.
* If usage exceeds the new storage quota, additional writes may be blocked. Files are not automatically compressed to fit. Export data you want to keep before removing files.
## Transactions
[Section titled “Transactions”](#transactions)
Review payments sent and received, including plan payments and marketplace purchases. Where available, open the linked block explorer to inspect an on-chain settlement.
## Your profile
[Section titled “Your profile”](#your-profile)
Who you are, as your memory keeps it: standing statements such as your name, your role or a lasting preference. Your assistant reads them, and so does every connection you allowed to read your profile. Each row says where it came from: *You said*, *Imported* or *From a conversation*.
Type a statement and select **Add** to keep it; adding one that is already there keeps the existing one. There is no editing: to correct a statement, add the new one and **Forget** the old. **Forget** asks you to confirm; once you do, your assistant and your connections stop seeing it at once.
## Data & export
[Section titled “Data & export”](#data--export)
Select **Download** beside **Export account data** to download a ZIP archive of available account data and agent memory files.
Check the result message. If it says **Export downloaded without agent memory files**, the archive is incomplete: wait briefly and export again to include those files. Check the archive contains the data you need before using it as a backup.
If export is unavailable or fails, resolve the error before deleting data you want to retain.
## Delete everything
[Section titled “Delete everything”](#delete-everything)
**Delete everything** under **Delete account data** opens a two-step confirmation. It removes your agent and memory, files including Trash, sources and their credentials, and connected apps and their access. The dialog also identifies affected marketplace subscribers. Your sign-in identity is retained.
1. Review the consequences and select **Download** to save an export. An export missing agent memory files is not marked as a completed backup in this flow. Export again to include them, or explicitly choose **Continue without downloading** if you do not need a backup.
2. Continue to the final confirmation, type `delete everything`, then select **Delete everything**.
> Account-data deletion cannot be undone. Keep and verify any export you need before confirming.
# Agents
> Create a custom agent, edit it in Studio, run it, inspect results, and pause or delete it.
Create a custom agent, edit it in Studio, run it, inspect results, and pause or delete it.
Use Agents when you need a custom agent or workflow beyond the assistant you talk to on Home. To give Claude or another external AI access to memory, use [Connect](/use/manage-your-memory/connect/).

## Create and edit an agent
[Section titled “Create and edit an agent”](#create-and-edit-an-agent)
1. Open **Agents** and press **Create agent**. Studio opens an unsaved draft, *Untitled agent*; nothing is created until its first **Save**.
2. Set its instructions and the workflow it should run. [Studio](/use/advanced/studio/) explains the canvas and the difference between saving a draft and deploying a version.
3. Save the draft. Return to **Agents** and open the agent’s row to see its controls and recent runs.
An agent that uses a model needs a working model source. Check [AI Setup](/use/account-and-models/ai-setup/) and the agent’s settings if its run reports that no model is available.
## Run and inspect the result
[Section titled “Run and inspect the result”](#run-and-inspect-the-result)
1. Expand the agent’s row and press **Run now**.
2. Wait for the result. If it is still running, use **View all runs** to follow its status.
3. Open a failed run’s details before trying again. [Activity](/use/automate-and-troubleshoot/activity/) helps you find the error and distinguish a refused run from a failed execution.
Use **Edit in Studio** to change a custom agent. The account’s default assistant has a **Settings** control instead, leading to its settings on Home.
## Pause or delete
[Section titled “Pause or delete”](#pause-or-delete)
**Pause** keeps a custom agent and its configuration; **Resume** enables it again. For a specific cadence, also check its row on [Schedules](/use/automate-and-troubleshoot/schedules/).
> **Delete** removes the custom agent. Confirm the browser prompt — Delete “”? Its run history is kept. — before continuing.
The account’s default assistant has no Pause or Delete button on this page.
## If something looks wrong
[Section titled “If something looks wrong”](#if-something-looks-wrong)
| What you see | What to do |
| ---------------------------------------------------- | ---------------------------------------------------------------------------- |
| *No agents yet. Select Create agent to get started.* | Press **Create agent** to make a custom one. |
| No agents match | Clear the search or filters; use **Create agent** to create a custom one. |
| A run is still in progress | Open **View all runs**; do not repeatedly start the same work. |
| Run failed | Inspect the run error, correct the model, input or workflow, then run again. |
| An external AI is missing | Manage connected AI apps on [Connect](/use/manage-your-memory/connect/). |
# Studio
> The workflow canvas behind a memory update: one pipeline per memory, the blocks you can add, and what saving changes.
The workflow canvas behind a memory update: one pipeline per memory, the blocks you can add, and what saving changes.
Studio is the canvas where an agent is drawn. Most people reach it one way: a memory’s **Open in Studio**, under Advanced in its Settings. That opens the memory’s own pipeline.

A memory has exactly one canvas. A fresh one holds two blocks, **Start** and the memory’s **Agent**, and runs exactly what **Update now** on the Memory page runs. On the canvas you can add what a button cannot express: a **Source** block to read something else, a **Memory** block, a **Save to memory** block, a **Condition**, or a **Schedule** block.
Things that are the same object as on the memory’s page:
* Renaming the memory renames its canvas and its agent.
* The Schedule block writes the same cadence as **Add schedule** in the memory’s Settings and the row on the Schedules page.
* Deleting the memory archives its canvas.
**Save** keeps the draft your own runs execute. **Deploy** pins a version that schedules, webhooks and marketplace subscribers run. The breadcrumb leads back to the memory.
You only need Studio for a memory that should do more than read its sources. If you are not sure you need it, you do not.
# Activity
> Find a run, inspect its status and error, and decide what to fix before trying again.
Find a run, inspect its status and error, and decide what to fix before trying again.
Activity shows what ran in your account and how it ended. Use it when a Memory did not update, an agent failed, or a scheduled task did not produce the expected result.

## Find a run
[Section titled “Find a run”](#find-a-run)
1. Open **Activity** and choose **Logs**. **Dashboard** summarizes activity across runs.
2. Set a **Time range** that includes the attempt. Narrow by **Status**, **Kind** or **Run source**, or search for the run you need.
3. Select a row to open its details. Check the status, timing, **Ran by** and the available result or error.
4. Use **Refresh** if you are following a recent run. **Export** downloads the displayed selection of activity as CSV.
A Memory’s **Report** and an agent’s **View all runs** also help you locate their runs. A developer key’s own request history is on [the key’s page](/use/manage-your-memory/connect/#a-keys-page).
## Read the status
[Section titled “Read the status”](#read-the-status)
| Status | What to do |
| --------- | ----------------------------------------------------------------------------- |
| *Pending* | The run has not finished starting; wait and refresh. |
| *Running* | Work is in progress. Check again before starting a duplicate. |
| *Success* | Open the result and check that it did the work you expected. |
| *Error* | Read the error, fix its cause, then retry from the Memory, agent or workflow. |
| *Refused* | Check the reason and the relevant access or account setting before retrying. |
A successful source sync means material arrived. It does not mean a Memory learned it; return to the [Memory](/use/manage-your-memory/memory/) and run **Update now** if needed.
## Troubleshoot a failed update
[Section titled “Troubleshoot a failed update”](#troubleshoot-a-failed-update)
* If the error names the model, check [AI Setup](/use/account-and-models/ai-setup/) and the agent’s model setting.
* If it names a source or its authorization, open that source and restore access, then sync it.
* If a scheduled run never appeared, check that the [schedule](/use/automate-and-troubleshoot/schedules/) is enabled and that you are reading its UTC time correctly.
* If the list is empty, widen the time range and clear the filters before concluding no run exists.
A scheduled run can finish even if its Telegram delivery fails. Inspect the run first, then check the connected chat using the [Telegram guide](/use/use-your-assistant/telegram/).
# Schedules
> Every scheduled task in one place: a memory's cadence, pause and resume, UTC times.
Every scheduled task in one place: a memory’s cadence, pause and resume, UTC times.
Every scheduled task in one place.

The page has **Calendar** and **List** tabs; the **List** tab holds **New schedule**. A memory’s cadence, set in its Settings, appears here; so does any agent you put on a schedule. Each row offers **Pause** / **Resume**, **Edit cadence** and **Run now**. **Edit cadence** takes effect at once, but the next deploy of the agent’s canvas restores the canvas’s own schedule. Pausing is how a memory’s or workflow’s schedule stops: it has no delete verb, so the row says *paused* rather than pretending it is gone. A job the agent created for itself has **Delete** instead (“Delete this agent schedule? This cannot be undone.”).
Cadences are picked, not typed: hourly, daily, weekly, monthly, or Custom cron. Times are UTC.
## If something looks wrong
[Section titled “If something looks wrong”](#if-something-looks-wrong)
Look up the word on screen.
| It says | What it means | Do |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| *No schedules yet* | nothing is scheduled | **List** › **New schedule**, or add a Schedule block in Studio and deploy the agent |
| *paused* | the schedule exists and does not fire | **Resume** |
| the time looks wrong | schedules run in UTC, and the picker shows UTC only | convert to your time zone, or **Edit cadence** |
| a scheduled result never reached Telegram | only the assistant’s own scheduled runs go to Telegram, and only to a chat bound to it; a Memory’s schedule never does | Home › Remote › **Connect Telegram** |
# Bring your material in
> Choose how to bring in files, Notion pages or captured conversations, and learn when a Memory reads them.
Choose how to bring in files, Notion pages or captured conversations, and learn when a Memory reads them.
Choose the source that fits your material. Files, uploads, Notion and captured conversations feed a Memory through its Add card; the Memory learns from them when you run it. Talking to your assistant follows a different path: it can save what matters during the conversation.

| Way in | Good for | Where |
| ------------------------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------- |
| A folder in your Files | a project, a vault, anything already on disk | memory page › Add card › **Your Files › Choose** |
| Upload | a handful of files | memory page › Add card › **Upload files › Upload** |
| [Notion](/use/bring-your-material-in/notion/) | pages and databases | memory page › Add card › **Notion** (where available) |
| [Browser extension](/use/bring-your-material-in/browser-extension/) | your chats with other assistants | memory page › Add card › **Membase extension** |
| Talking to your assistant | what you tell it, decide with it, ask it | Home, or Telegram |
## A folder in your Files
[Section titled “A folder in your Files”](#a-folder-in-your-files)
Press **Choose** on *Your Files*. The Files browser opens inside the dialog: browse, tick one or more folders, and confirm in the footer. The folder is read in place, so anything you later add to it is picked up on the memory’s next run. A folder the memory already reads says *reading*.
If the files are not in your Files yet, put them there first from the Files page, or upload.
## Upload
[Section titled “Upload”](#upload)
Press **Upload** on *Upload files* and drop the files. They land in a folder named “ uploads” (“… uploads (2)” if that name is taken) at the top of your Files, which is connected as a source on the spot. Accepted: text formats (`.md`, `.markdown`, `.mdown`, `.txt`, `.csv`, `.json`, `.jsonl`, `.yaml`, `.yml`); PDFs and images once a model is set up in [AI Setup](/use/account-and-models/ai-setup/); and `.zip` archives, which are unpacked into a folder. Office files (`.docx`, `.xlsx`, `.pptx` …) are refused: convert them to PDF or Markdown first. Each file can be up to 32 MiB. The dialog tells you before sending if a file is not accepted.
## Notion
[Section titled “Notion”](#notion)
Connect a workspace, select the pages or databases the Memory should read, and add them. A sync fetches those pages; the Memory still needs a run to learn from them. Follow the [Notion guide](/use/bring-your-material-in/notion/) for authorization, page selection, updates and disconnection.
## Membase extension
[Section titled “Membase extension”](#membase-extension)
The Membase browser extension captures your conversations with other assistants and hands them to a memory as a source.
1. Press **Install** on *Membase extension*. A **Connect Membase extension** dialog opens; if the extension is not installed yet, use its **Install browser extension** link and sign the extension in with the same wallet.
2. Press **Connect wallet** and approve the two signatures. The door says *Added* and the source appears in the Add card; syncing continues in the background.
3. When the sync finishes, select **Update now**.
If your account already has this connection (another memory uses it, say), the door says **Use here**; press it to add the same source to this memory.
A memory over your conversations keeps memory about *you*: what you asked, decided, adopted. It does not restate what an assistant explained. Its instruction is a filter on the chats, not a subject: *unibase* keeps what the chats say that bears on Unibase, not a description of Unibase.
## Talking to your assistant
[Section titled “Talking to your assistant”](#talking-to-your-assistant)
Your assistant can retain relevant information from conversations on Home or Telegram. A *Saved to memory* indication shows when information has been saved. Review the assistant’s memory on the Memory page; do not assume every message has been stored as a memory entry.
The [browser extension guide](/use/bring-your-material-in/browser-extension/) covers setup and missing conversations.
## Then run
[Section titled “Then run”](#then-run)
After adding a source, select **Update now** on the Memory page or configure a schedule in **Settings**. See [Memory](/use/manage-your-memory/memory/).
# Browser extension
> The Membase browser extension, which captures the person's conversations with other assistants and hands them to a Memory as a source.
The Membase browser extension, which captures the person’s conversations with other assistants and hands them to a Memory as a source.
**Membase extension** is a browser extension. It captures the person’s conversations with other AI assistants as they happen and hands them to Membase, where a Memory reads them as a source. Use this to bring conversations into memory. To let an AI app read existing memory, follow [Connect your AI](/connect/).
* Chrome Web Store: [Membase](https://chromewebstore.google.com/detail/edmncknbiihfoakimejbepnaeemaaamf)
## What it captures
[Section titled “What it captures”](#what-it-captures)
Conversations the person has with assistants in the browser. The capture is encrypted with the person’s wallet key before it leaves the browser, and it is the person’s wallet that Membase uses to read it back, so the platform sees nothing it was not handed. Which assistants are captured is the extension’s own setting.
## Connecting it to a Memory
[Section titled “Connecting it to a Memory”](#connecting-it-to-a-memory)
In the app, on a Memory’s page, the Add card has a door for it:
1. Press **Install** on *Membase extension*. A **Connect Membase extension** dialog opens. If the extension is not installed yet, use the dialog’s **Install browser extension** link and sign the extension in with the same wallet as the app.
2. Press **Connect wallet** and approve the two signatures in your wallet (an embedded wallet signs automatically). The source is added to this Memory at once: the door says *Added* and the source appears in the Add card.
3. Syncing continues in the background; you can close the dialog. When the sync finishes, press **Update now**.
If the account already has this connection, for example because another Memory uses it, the door says **Use here** instead of **Install**; pressing it adds the same source to this Memory.
From then on the captured conversations reach the source; the Memory reads them on its next run (**Update now** or its schedule). The source’s own page shows a status word (*Syncing…*, *Sync failed*, *Needs reauthorization*) and **Sync now** (**Retry** after a failed sync), **Reauthorize** or **Reconnect** when they apply, plus **Manage…** and **Delete…**; see [Bring your material in](/use/bring-your-material-in/bring-material-in/).
## Writing the instruction
[Section titled “Writing the instruction”](#writing-the-instruction)
A Memory over conversations keeps memory about *the person*: what they asked, decided, adopted. It does not restate what an assistant explained. Its instruction is a **filter on the chats, not a subject**: *unibase* keeps what the chats say that bears on Unibase, not a description of Unibase. An instruction written as a topic produces a log; written as a filter it produces the standing facts the person would want any other assistant to know.
## If something looks wrong
[Section titled “If something looks wrong”](#if-something-looks-wrong)
| It says | What it means | Do |
| ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| *Added*, but the dialog says “No conversations have synced yet. Check that the extension uses this wallet…” | nothing has been uploaded for this wallet yet | make sure the extension is signed in with the same wallet as the app and has captured conversations, then press **Sync now** on the source page |
| *Added* but the Memory learns nothing | no conversation has been uploaded yet, or the Memory has not run | check the extension’s own log; press **Update now** |
| the Memory reads like a log of what assistants said | the instruction is a topic | rewrite it as a filter on the chats |
| *Needs reauthorization* | the extension’s credential expired | **Reauthorize** on the source page |
# Files
> Your files as a real folder tree the assistant shares with you, and how a folder becomes a source.
Your files as a real folder tree the assistant shares with you, and how a folder becomes a source.
Files is your files: a real folder tree the assistant shares with you.

1. **Upload.** Files land in the folder you are in.
2. **New folder.** Any folder can later become a source.
The root is your own tree. The locked system folders `generated`, `assets`, `sources` and `trash` sit at the top of it, each badged *System*; you cannot create or upload anything in them. Files are read from your memory’s storage, so the first open can take a few seconds while it wakes.
Right-click a row for rename, move, delete and download. Documents (Markdown pages, whether written here or uploaded) and folders go to `trash`, where you can restore them. Other files, such as uploaded PDFs or images, and assets are deleted permanently; the confirmation says “This is permanent — it does not go to Trash.”
## Making a folder a source
[Section titled “Making a folder a source”](#making-a-folder-a-source)
You do not do it here. Open the memory that should read the folder and press **Choose** on *Your Files* in its Add card. The same browser opens inside the dialog, with a footer that connects the ticked folders. A folder the memory already reads says *reading*.
# Notion
> Connect a Notion workspace, choose pages for a Memory, learn from them, and manage updates or disconnect the workspace.
Connect a Notion workspace, choose pages for a Memory, learn from them, and manage updates or disconnect the workspace.
Use Notion pages and databases as a Memory’s sources. Connecting a workspace gives Membase permission to find pages; choosing pages imports them; running the Memory learns from them.
You need a Memory and permission to share the Notion pages you want it to read.
## Connect and choose pages
[Section titled “Connect and choose pages”](#connect-and-choose-pages)
1. Open the Memory. Under **Add to this memory**, press **Connect** on **Notion**. If a workspace is already connected, the button says **Add pages**.
2. Press **Connect Notion** and finish the authorization screen. Back in Membase, the picker shows the workspace and the pages available to it.
3. Tick the pages or databases to read. Use **Search pages, or paste a Notion link** to find a specific page. Choose whether **Include subpages** should be on.
4. Press **Add to** followed by the Memory’s name. The picker closes and the source appears under the Memory’s Add card.
5. Open the source and wait for its files to arrive. Return to the Memory and press **Update now**. When the run finishes, inspect **Your memory** or ask about the material.
If your deployment does not offer the Notion card, use [Files](/use/bring-your-material-in/files/) to import an export instead. You can also connect with a Notion integration token: use **Use a token instead** under **Connect Notion** or in the workspace’s **⋯** menu (where Notion sign-in is not set up, the token form is shown directly). The token must have access to the pages you select.
## Update the selection
[Section titled “Update the selection”](#update-the-selection)
Open the source from the Memory. The **Pages** row shows the selected pages and whether it includes subpages. Press **Change…**, adjust the selection, then **Save pages**.
If a page is missing, open the workspace’s **⋯** menu and choose **Update page access** for an OAuth connection, then **Refresh list**. A newly shared page may take a moment to appear. Pasting a link does not grant access to a page that the connection cannot read.
## Keep it up to date
[Section titled “Keep it up to date”](#keep-it-up-to-date)
**Sync now** fetches the current Notion content. It does not update what the Memory knows; press **Update now** on the Memory afterwards, or let its [schedule](/use/automate-and-troubleshoot/schedules/) run. **Pause** on the source stops its syncing; **Resume** starts it again. Pausing a source and pausing a Memory’s schedule are separate controls.
## Disconnect a workspace
[Section titled “Disconnect a workspace”](#disconnect-a-workspace)
In the page picker, open **⋯** and choose **Disconnect** followed by the workspace name. Read the confirmation: it names the affected Memories. Confirm only if those sources should stop syncing. Imported material and what the Memories already learned remain.
To remove learned content, use the [Memory’s editing and deletion controls](/use/manage-your-memory/memory/). Disconnecting Notion is not a request to forget what it previously supplied.
## If something looks wrong
[Section titled “If something looks wrong”](#if-something-looks-wrong)
| What you see | What to do |
| ------------------------------------------ | ------------------------------------------------------------------------------- |
| No pages shared with Membase yet | Use **Update page access**, share the required pages, then refresh the list. |
| A page is absent | Check the selected workspace and that the connection has permission to read it. |
| Files arrived but answers have not changed | Run the Memory; syncing alone does not teach it. |
| Needs reauthorization | Use **Reauthorize** on the source and finish authorization again. |
| Sync failed | Open the source’s error, check page access, and press **Retry** on the source. |
# Setup guide
> The Setup guide on a new account: create a memory, add a source, connect an AI tool, one lit control at a time.
The Setup guide on a new account: create a memory, add a source, connect an AI tool, one lit control at a time.
On a new account the product dims the page and lights the one control to press next. That is the **Setup guide**. It has three steps, the same three this documentation follows:
1. Create a memory
2. Add a source
3. Connect an AI tool

The guide opens on a card titled **Set up your first memory**, with the three steps in a rail on its left, that asks for your display name. (On a narrow screen it is a smaller card at the foot of the screen, **Set your display name**.) Press **Continue** and the first real control lights up, with a small card beside it saying what to do.

A few things worth knowing:
* Completed steps are marked in the guide. Select **Next** to continue. The third step completes when an app is approved on Connect, not by asking on Home; the closing card then says “ is connected. Send a query to verify access.”
* A step you have not done holds until you do it. You can close the guide any time with the X on its card.
* It opens by itself once per browser session on an account with no memories and no connected apps. After that, the **Setup guide** button (the compass icon at the top right of a Home conversation) starts it again from the name card.
* On a page without the step’s control, the guide shows a centred card with one button to the right page, such as **Open Memory** or **Open Connect**. On a narrow screen, or while the control is not on screen yet, a small card stands at the corner instead.
# Your first Memory
> Create a Memory, add your notes, run it, and verify what it learned before connecting another AI.
Create a Memory, add your notes, run it, and verify what it learned before connecting another AI.
By the end of this page you will have a Memory that has learned from your own notes, and you will know how to use it in an AI.
You need a Membase account and a small Markdown or text file with a fact you can check, such as “The Lumen launch is on 15 October.” Learning needs a working model and available turns. If a run reports that no model is available, follow [AI Setup](/use/account-and-models/ai-setup/). Connecting Claude at the end is optional and requires a Claude account.
## 1. Create a memory
[Section titled “1. Create a memory”](#1-create-a-memory)
1. Open **Memory** in the left rail. Before you have any, the page shows only the Assistant’s own memory.
2. Press **Create memory** ①.

3. Give it a name ①. Under *Information to retain*, leave **Anything useful** or pick a preset. Press **Create memory** ②.

You are on the memory’s page. Its hero shows the name, an **Update now** button that is still disabled, **Settings** and **Delete…**.
## 2. Add something to it
[Section titled “2. Add something to it”](#2-add-something-to-it)
The **Add to this memory** card ③ includes **Upload files**, **Your Files** and **Membase extension**. Where available, **Notion** is another option; this walkthrough uses a file.

1. Press **Choose** on *Your Files*. The Files browser opens inside the dialog.
2. Tick the folder that holds your project files and confirm in the footer. If your files are not in Files yet, press **Upload** on *Upload files* instead; they land in a folder named “ uploads”.
3. The Add card now lists the folder. A toast tells you adding does not run the memory.
4. Press **Update now** ① in the hero. The status line under the name says *Running…*, then *Updated just now · Report*.
> Adding a source does not process it. Select **Update now** or configure a schedule to update the Memory from its sources.
## 3. Use it in your AI
[Section titled “3. Use it in your AI”](#3-use-it-in-your-ai)
First, check **Your memory** below the Add card. Open a result and confirm it reflects your notes. On **Home**, ask the assistant a specific question, such as “When is the Lumen launch?” If that Memory is not available to the assistant, select it in the assistant’s settings on Home (the ⚙ **Assistant settings** button beside **Remote**, at the foot of the conversation rail). Check the answer against your file. If the run failed, open **Report** and resolve that error before connecting an external app.
### Optional: use it in Claude
[Section titled “Optional: use it in Claude”](#optional-use-it-in-claude)
For other clients, use [Connect your AI](/connect/).
1. Open **Connect** in the left rail. Apps you have not connected say **Set up** on their tiles.

2. Pick **Claude**. The connector URL and the steps for Claude unfold under the tiles.

3. Follow those steps in Claude. The third one sends you back to Membase to approve access and tick the memories Claude may read. Tick the memory you just made and press **Approve access**.
4. Back in Claude, open **+ → Connectors** in a chat and switch Membase on.
5. Ask a question about your project. Claude reaches for your memory on its own.
After approval, the Claude tile is solid and says *Authorized · awaiting first use*. After a successful tool call it shows recent usage. Authorization confirms permission; the answer from your notes confirms that the integration works. The app’s page lists the Memory under **Uses**, with a switch you can turn off at any time.
The same memory answers on Home, too. Ask your assistant and it tells you which page it read:

## What next
[Section titled “What next”](#what-next)
* [Keep it up to date on a schedule](/use/manage-your-memory/memory/#settings)
* [Use it in ChatGPT, Cursor or another app](/use/manage-your-memory/connect/)
* [Bring in more: uploads, Notion, your chats with other assistants](/use/bring-your-material-in/bring-material-in/)
* [Reach your assistant on Telegram](/use/use-your-assistant/home/#telegram)
# Sign in
> Continue with Google, X or email through Privy, or connect a wallet, then Home and the first-run guide.
Continue with Google, X or email through Privy, or connect a wallet, then Home and the first-run guide.
The sign-in gate has two buttons. **Continue with Google, X or email** opens the Privy sign-in window, where you pick how to prove who you are. **Connect a wallet** talks to your browser wallet directly.
1. Open the app and press **Continue with Google, X or email**, or **Connect a wallet**.
2. Finish that provider’s steps: the Privy window for Google, X or email, or your wallet’s own prompt.
3. You land on Home. The first-run guide opens by itself on a new account.
An invite link (`/?invite=CODE`) is applied when you sign in. Your own invite link is on the **Invitations** page, in the rail’s *Capabilities* group.
Your account is the boundary for everything: memories, sources, connected apps and deletion. There is nothing to create or name before you start.
> **Sign out** ends both the provider session and the Membase session. It is under the account disc at the foot of the left rail.
# Connect
> Let an AI read your memories: the MCP address and client catalog, the skill way with a developer key, and an app's page.
Let an AI read your memories: the MCP address and client catalog, the skill way with a developer key, and an app’s page.
Connect is where an AI gets permission to read your memories. There are two ways to connect an AI, and the page has a tab for each.

1. **The tabs.** **MCP** is for an AI app; **Skills** is for an AI that reads pages and runs commands. Each tab holds everything its way needs.
2. **The address** (MCP tab). Copy it into the app’s connector or MCP settings; the app opens your browser and you approve it on the consent card, ticking the memories it may read. An app connected this way can only read. The card says who is asking and where approving sends you: a known app by its name, a program on your own computer as such. An app that uses a known product’s name from another address is shown as *Unverified app*, with a red warning naming that address; an app Membase cannot confirm gets a warning too. Approve only a connection you started yourself.
3. **The client catalog, by purpose.** *Chat assistants* and *Coding tools*. A tile you have not set up says *Set up* and unfolds that app’s steps; a connected tile (brand-blue border) says *Authorized · awaiting first use* or *Authorized · used …* and opens the app’s page; *Approval expired · authorize again* means the app must sign in again. An app that has no tile of its own (any other MCP client) appears under *Other apps*, with a monogram, once you have approved it.

The **Skills** tab keeps setup in three steps: create a key, paste the instruction, and let your AI confirm which memories it can use. It works with coding assistants such as Claude Code, Codex and Cursor that can read pages and run commands.
1. **Create key.** Choose the access and memories your AI may use.
2. **Use an existing API key.** Expand this to copy an installation instruction without creating another key. Your AI installs the skill, then asks for your existing key.
3. **Download skill** gets the complete folder for a manual installation. **Setup guide** opens the detailed instructions.
4. **Manage keys** opens your developer keys, where you can change access or revoke a key.
## The skill way, step by step
[Section titled “The skill way, step by step”](#the-skill-way-step-by-step)
1. Press **Create key**. The **Create an API key** dialog starts with name *my AI* and access **Read & write**. Choose the memories it may reach and press **Create key**.
2. Copy the instruction on the next screen. It includes the key, which is shown only once.
3. Paste it to your AI. It installs the skill, stores the key, and reports which memories it can use. If none are selected, open **Manage keys**, choose the key, and update its memory access.
The skill uses the API with your developer key. If the AI already has Membase MCP tools, it uses those tools and keeps the skill for its rules.
Manual MCP configuration is under **MCP › Manual configuration**. The API is documented on the developer docs’ [API reference](/build/reference/api-reference/).
## Set an app up by hand
[Section titled “Set an app up by hand”](#set-an-app-up-by-hand)
Picking a tile that says *Set up* unfolds the connector URL and the steps for that app:

1. **The steps.** Written for that app’s own menus. Follow them in the app; the last one brings you back here to approve access and tick the memories the app may read.
## An app’s page
[Section titled “An app’s page”](#an-apps-page)
Once connected, the tile opens the app’s page: the hero (name, *Authorized · last activity …* or *Authorized · awaiting first use*, and the amber words *No memory access* while no memory is switched on), a **Uses** card with one row per memory and its switch, and, when there is more than one approval, an **Approvals** card with a **Revoke** per credential. **Disconnect…** in the hero revokes every approval at once.
> Connecting is the account’s, once. Which memories an app uses is the memory’s, and the switch on the app’s page and the switch on the memory’s *Use in* card are the same switch.
## What the app can do
[Section titled “What the app can do”](#what-the-app-can-do)
A connected app gets two tools: list the memories it may use, and search them. It cannot see memories you have not switched on for it, and it cannot tell that they exist. Turning a switch off takes effect on the app’s very next question. If you ticked **Profile access** when approving, it also gets your profile — the standing facts your assistant keeps about you and what changed recently. That tick lives on the consent screen only: the app’s page has no profile switch, so to change it, **Disconnect…** the app and approve it again. An app can never add, delete or forget anything.
## Developer keys
[Section titled “Developer keys”](#developer-keys)

A **developer key** is your own credential for a script, a server, an SDK or an AI that runs commands. It reaches your memory the way a connected app does, over the memories you choose, at an access level you pick, for as long as you say. Connected apps do not need one; they approve on the consent screen.
**Manage keys** on the Skills tab opens the keys page. Every key is one row: name and hint, access, reach, expiry, last use. **Active**, **Expired** and **Revoked** are the three segments; a key that has stopped working stays listed for 30 days so you can see what it was. **Create key** makes one; the name opens the key’s page; **⋯** at the end of a row holds **Rotate…** and **Revoke…**.
### Create a key
[Section titled “Create a key”](#create-a-key)

1. **Name** (1) it after what will hold it, for example *nightly-notes script*, so a revocation stops one thing.
2. Pick the **Access** (2). The level you pick shows the tools it gets:
* **Read** — search and list. It cannot change anything.
* **Read & write** — also adds a memory or a document.
* **Full access** — also deletes a document or forgets a memory. Each of those calls must still say so explicitly; a key never removes anything on its own.
3. Pick the **Memory access** (3). Nothing is ticked to begin with. Tick the memories it may use, or **All memories, including ones you make later**. **Your profile**, the standing facts your assistant keeps about you ([Settings › Your profile](/use/account-and-models/settings/#your-profile)), is the last row.
4. Pick when it **Expires** (4): never, 30 days, 90 days or a year.
5. Press **Create key** (5).

The token (1) appears once, in full. Store it now: afterwards the app shows only its hint, such as `mbk_7f3a92d1…c91e`, which is enough to tell your keys apart and never enough to use one. The same screen gives the token in six shapes (2): **Tell your AI** (the one sentence from the Skills tab), a `curl` call, Python, TypeScript, the Claude Code command, and the `mcp.json` block Cursor and VS Code read. A key created from the Skills tab’s **Create key** shows only the **Tell your AI** sentence, and a key’s page shows no snippets afterwards. **Send a test call** (3) makes one real call with the new key from your browser and reports *Verified*, and how many actions the key was granted.
Using the key from a script or an SDK is the developer [Quickstart](/build/getting-started/api-quickstart/); using it in Claude Code, Codex, Cursor or Kimi Code is on each client’s page under [Connect your AI](/connect/).
### A key’s page
[Section titled “A key’s page”](#a-keys-page)

* **Access** (1) — change the level with the segmented control; the tools it now holds are listed under it. The token stays the same. Lowering the level applies on the key’s next call, and so does raising **Read & write** to **Full access**. Raising a **Read** key to **Read & write** or **Full access** does not give it write access yet: its writes are still refused, so create a new key at the higher level instead.
* **Memory access** (2) — a switch per memory, one for *All memories, including ones you make later*, and one for *Your profile*. Off takes effect on the key’s next call.
* **Expiry** (3) — when the token stops working. It cannot be extended; to change it, rotate.
* **Usage** (4) — calls in the last 30 or 7 days, how many were **refused** (the key asked for a memory or a verb it does not have), and the tool it calls most.
* **Recent activity** (5) — the last calls one by one: tool, memory, what came back, when. A refused call is red and says why.
Click the name to rename the key. Which memories a key reaches can also be switched on the memory’s own page under **Use in**, where keys are listed after the apps.
### Rotate and revoke
[Section titled “Rotate and revoke”](#rotate-and-revoke)
**Rotate…** (6) makes a new key with the same access, reach and expiry, and asks what to do with the current one. By default it keeps working until you revoke it, so you can swap the value in your environment first; or revoke it on the spot.
**Revoke…** (7) ends a key at once: every script holding the token fails on its next call. The dialog shows the key’s hint and warns when the key was used in the last week. A revoked key stays listed under **Revoked** for 30 days.
Removing the connector inside Claude or ChatGPT does not tell Membase. To be sure access has stopped, open the app’s page here and **Disconnect…**.
## If something looks wrong
[Section titled “If something looks wrong”](#if-something-looks-wrong)
Look up the word on screen.
| It says | What it means | Do |
| ----------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- |
| *Set up* | this app is not connected | pick the tile and follow the steps |
| *No memory access* (amber) on an app’s page | connected, but no memory switched on | turn a switch on under **Uses** |
| the app cannot see a memory | its switch is off | memory page › **Use in** |
| I removed the app in Claude but it still shows *Authorized* | the app did not tell Membase | **Disconnect…** on the app’s page |
| *The MCP address is unavailable* | the page could not ask the server for it | reload; the sentence for your AI still works |
| my AI installed the skill but says it has no access | the skill needs a developer key | Skills tab › **Create key**, and paste the sentence to the AI |
| a key’s row says *Expired* | its token has lapsed | **⋯ › Create a similar key** on the Developer keys page |
| *in 6 days* on a key’s row (amber) | the key expires within a week | **Rotate…** and swap the value |
| *refused* in a key’s Recent activity | the key asked for something it does not have | the row says which memory or verb; adjust **Memory access** or **Access** |
| I already have a key | you can reuse it | Skills tab › **Use an existing API key** |
# Memory
> The Memory page as one drive: tiles, a memory's page, the status line, Settings, a source's page, and what each word means.
The Memory page as one drive: tiles, a memory’s page, the status line, Settings, a source’s page, and what each word means.
The Memory page is one drive. Its root shows your memories as tiles; each memory opens as a page with the same anatomy.
## The home page
[Section titled “The home page”](#the-home-page)

1. **A memory tile.** Glyph, name, and a state word only when there is one: *Add a source* (reads nothing yet), *On sale*, *Subscribed*.
2. **Create memory.** Opens the Create memory dialog. **Marketplace** beside it opens memories other people sell.
The Assistant’s own memory is always the first tile. The home page lists the Memories before reading their contents.
## A memory’s page
[Section titled “A memory’s page”](#a-memorys-page)

1. **Name.** Click to rename in place.
2. **Update now.** Process the Memory’s sources manually. The button is disabled while an update is running or when the sources are not ready.
3. **Settings.** Configure the name, instructions, sources, schedule and sharing in one dialog.
4. **Delete…** Says first the one irreversible thing (everything the memory learned goes with it), then what depends on it. A memory on sale is taken off the market with it, and its subscribers lose access at once.
5. **Add to this memory.** Choose Membase extension, Upload files, Your Files, or Notion where available. Sources you added are listed below with a **Remove** per row. [Sources](/use/bring-your-material-in/bring-material-in/) explains each option.
Under the Add card:
* **Your memory.** What this memory currently knows: search, a kind filter and the list. Once the memory has memory files, the list splits into two lanes, **Memory entries** and **Memory files**. Click an item to read it in the right column.
* **Use in.** One switch per app you have connected. **Connect an app** when there is none.

1. **An item.** One thing the memory keeps, with its kind and when it was last updated. The list contains what the Memory learned and any corrections you made through **Edit**.
2. **The right column.** The item’s full text, its tags, and **Edit** / **Forget…** for that one item.
### The status line
[Section titled “The status line”](#the-status-line)
The line under the name is the memory’s state and nothing else:
| It says | Meaning |
| ------------------------------------ | ----------------------------------------------------------------------------- |
| *Not run yet* | never run |
| *Checking…* | the page is reading the state |
| *thinking… 8s*, then *Running · 20s* | a run is queued or running, with the time since it started; survives a reload |
| *Updated 3h ago · Report* | the last run read the current sources; **Report** opens what it did |
| *Run failed* | the last run failed; open the report, fix, run again |
| *Run refused* | the last run was refused before it did any work; **Report** says why |
| *Run canceled* | the last run was canceled |
| *Starting memory…* | the memory’s store is waking up |
| *Unable to check this memory: …* | the page could not read the state; the reason follows |
“Unread” is decided by versions, not clocks. A sync that changed nothing, or a run on another memory, cannot make this memory look up to date.
## Settings
[Section titled “Settings”](#settings)

Every field saves as it changes. There is no Save button. The dialog has its own **Update now** at the top.
The **Memory** section starts with the **Name**.
1. **Instructions.** What the memory keeps. For a memory over your conversations, the instructions filter what the chats say, they are not a subject to write about.
2. **Schedule.** *Manual* until you **Add schedule**; then **Change**, **Pause** and **Resume**. Cadences are picked, not typed: hourly, daily, weekly, monthly, or a custom cron. Times are UTC.
Between them, **Sources** shows your sources as pills; a highlighted pill is one this memory reads. Clicking a pill adds that source to this memory or removes it, so clicking a highlighted pill stops this memory reading it. The pills do not open a source’s page.
Below: **Sharing** (apps as switches, what depends on this memory, **Sell** / **Unlist…**) and **Advanced** (model, skills, its agent, **Open in Studio**).
## A source’s page
[Section titled “A source’s page”](#a-sources-page)

Each source has its own page, opened from its row under the Add card.
1. **Hero.** The source and its path. A folder in your Files is read in place, so there is nothing to sync, and **Disconnect…** is its one verb. A connector source (Notion, Membase extension) shows a status word here instead, with **Sync now** (**Retry** after a failed sync), **Reauthorize** or **Reconnect** when they apply, plus **Manage…** and **Delete…**.
2. **Read by.** Which memories learn from this source.
A folder source lists its files below, as an in-place workbench: open, rename, move, upload. A conversation source lists its transcripts.
## If something looks wrong
[Section titled “If something looks wrong”](#if-something-looks-wrong)
Look up the word on screen.
### On the memory
[Section titled “On the memory”](#on-the-memory)
| It says | What it means | Do |
| -------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **Update now** is disabled | the memory has no source yet, or its state is still loading | add a source; wait for *Checking…* to finish |
| **Update now** | starts a manual update from the sources | select it to update the Memory |
| *Run failed* | the last run did not finish | open **Report**; usually the model source is off or a source needs reauthorization |
| *Not run yet* | never run | select **Update now** |
| *Run refused* | the run was refused before it started | open **Report**; usually no model source or no turns left |
| *Add a source* on the tile | reads nothing yet | Add card |
### On a source
[Section titled “On a source”](#on-a-source)
| It says | What it means | Do |
| --------------------------------- | ----------------------------------- | --------------------------------------------------- |
| *Queued* / *Syncing…* | fetching raw material | wait; the memory reads it on its next run |
| *Sync failed* | the last fetch failed | **Retry**; if it repeats, the source may have moved |
| *Needs reauthorization* | the source’s own credential expired | **Reauthorize** |
| *Access revoked* / *Disconnected* | the source no longer grants access | **Reconnect** or remove it |
# Marketplace
> Browse skills and memory listings, manage purchases and subscriptions, and publish a memory listing.
Browse skills and memory listings, manage purchases and subscriptions, and publish a memory listing.
Browse published skills and memories. Check the listing type, included access, price and usage allowance before purchasing.

1. **Browse.** Search the catalog and open a listing to review its details.
2. **Your listings.** Manage the memories you offer. **List a memory** creates a listing.
3. **Purchases & subscriptions.** View what you have bought or subscribed to.
The **Skills | Memory** switch selects the catalog.
## Memory listings
[Section titled “Memory listings”](#memory-listings)
A listing sells a **Memory, as answers**. The buyer’s AI asks it questions and gets answers written from what the Memory knows. It never sees the Memory’s files, documents or facts, never writes to it, and reaches no other Memory of the seller’s. Two earlier kinds are no longer offered but still show for the people who bought them:
| Type | What you receive |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Memory (answers) | A credential that may only ask that one Memory: `ask_memory` over MCP, `POST /v1/ask` over REST. Answers, never files. Valid 30 days per payment, with the number of questions per period shown on the listing; renew to continue |
| Snapshot (no longer offered) | A copy of the listed items at purchase time; later seller edits do not update it |
| Live memory (no longer offered) | Read access to the seller’s memory for the subscription period |

Every question checks the purchase: it must be active and unexpired, the listing not suspended, and the period’s questions not used up. If any of these fails, the question is refused. A listing bought earlier as an agent endpoint is now answered by its Memory the same way.
Open a listing and read **Included access** for its specific terms. Live access can be revoked by the seller; a paid period does not guarantee access after the seller revokes it.
### Buying
[Section titled “Buying”](#buying)
Choose the purchase or subscription action shown on the listing. Review the confirmation, including any usage limit. Paid listings open your wallet for payment; the purchase is complete only after payment succeeds. Live paid access is valid for the period shown, and renewal requires another payment.

Use **Purchases & subscriptions** to review status and access dates, open snapshot items, or manage an available credential. Use the actions offered for that listing type.
A subscription also appears as a *Subscribed* tile on your Memory page:

Its page shows the seller and access period. **Read by** selects which one of your agents may consult it; switching on another agent moves the subscription to that agent. **Read from an app** provides connection details when available. You cannot edit the seller’s memory. Review the confirmation before unsubscribing.
### Selling
[Section titled “Selling”](#selling)
1. Select **List a memory**, or **Sell** under Settings › Sharing › Marketplace on a Memory.
2. Select the Memory and fill in the **Listing name**, **Description** and sample content.
3. Set the price and usage allowance. A paid listing requires a receiving wallet.
4. Review the details, then select **Publish** to make the listing discoverable.

Manage listings under **Your listings**. Each row offers **Edit**, **Subscribers**, **View as a buyer** and **Delete**, plus **Publish** on a *draft* or **Make private** on a *live* listing; on the Memory’s side, Settings › Sharing › Marketplace offers **Unlist…**. Deleting or unlisting a listing cuts its subscribers off at once, so review who it affects first. Deleting the Memory itself also takes it off the market: every listing selling it goes, and every subscriber loses access at once.
## Skills
[Section titled “Skills”](#skills)
**Browse** lists published skills. **Your skills** lists installed or published skills. Review a skill before installing it for use by an agent.
# Home
> Your conversation with the Assistant: the rail, the entry cards, the composer, and the remote channel.
Your conversation with the Assistant: the rail, the entry cards, the composer, and the remote channel.
Home is your conversation with the Assistant. Everything else in the product feeds this page.

1. **Navigation.** The left rail. Flat items first, then a *Capabilities* group.
2. **New conversation.** Starts a draft row at the top of the rail. The first message turns it into the real conversation.
3. **Entry cards.** **Create memory**, **Marketplace**, **Connect AI** and **View agents** open their respective pages or setup steps. **Quick actions** below them provides shortcuts for adding content and using your memory.
4. **The composer.** The conversation box; its placeholder reads *Message …* and `@` mentions a memory or file. Enter sends, Shift+Enter breaks a line.
5. **Setup guide.** Replays the first-run guide from its name card.
## The conversation rail
[Section titled “The conversation rail”](#the-conversation-rail)
The rail lists your conversations grouped by day: Today, Yesterday, Previous 7 days, Older. Each row’s menu offers **Rename**, **Branch** and **End**. Ended conversations fold away at the bottom; they stay readable and the assistant can still search them, but they take no more turns. Their menu offers **Delete conversation**, which asks for confirmation.
At the foot of the rail, **Remote** holds the assistant’s Telegram chat. **Connect Telegram** opens the connection steps; once connected, the row opens a read-only view of that chat. See [Telegram](#telegram) below.
## The box
[Section titled “The box”](#the-box)
The three things you change mid-conversation sit along the bottom edge of the box: the model source, the memories to consult, and the skills. Send is at the right.
| Key | Does |
| ----------- | ------------------------- |
| Enter | send |
| Shift+Enter | new line |
| ↑ | recall your last question |
| Esc | stop the current reply |
| ⌘⇧O | new conversation |
## The transcript
[Section titled “The transcript”](#the-transcript)

1. **Your message.** In a bubble on the right, beside your account disc.
2. **The answer.** Rendered under the assistant’s mark and name. When it comes from your memory, the assistant says so and names the page it read.
3. **Activity.** Folded under the answer: which tools ran, including the memory it recalled.
A day separator heads each day; answers also show their time beside the assistant’s name. Hovering a message shows **Copy**, **Retry**, **Edit & resend** and **Branch**. Under an answer you may also see memory traces such as *Saved to memory* or *Recalled an earlier conversation*. A *New reply* pill appears when an answer lands while you have scrolled up.
## Assistant settings
[Section titled “Assistant settings”](#assistant-settings)
The ⚙ **Assistant settings** button beside **Remote**, at the foot of the conversation rail, opens its settings as a dialog over the conversation (`/?settings=assistant` opens it too). One scroll, no tabs, every field saved as it changes: name, instructions, memories, skills, its Telegram chat, and the model card (which source answers and which model).
## Telegram
[Section titled “Telegram”](#telegram)
Use the **Remote** row below the conversation list to open a connected Telegram chat or connect a new one. It shares the assistant’s memory but keeps a separate conversation. The [Telegram guide](/use/use-your-assistant/telegram/) covers setup, scheduled results and disconnection.
## Three verbs
[Section titled “Three verbs”](#three-verbs)
| Verb | Effect | Reversible |
| ----------------------- | ----------------------------------------------------------- | ------------- |
| **New conversation** | opens a conversation | – |
| **End** | closes it; still readable and searchable | no more turns |
| **Delete conversation** | deletes the transcript; previously saved memory is retained | **no** |
## If something looks wrong
[Section titled “If something looks wrong”](#if-something-looks-wrong)
Look up the word on screen.
| It says | What it means | Do |
| ------------------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
| *AI is unavailable* | no model source | press **Open AI Setup**, then **Connect** a key or a subscription |
| the reply spins | first reply after a quiet period wakes the assistant | wait; if it does not land, **Retry** |
| *New reply* pill | an answer landed while you scrolled up | click it |
# Telegram
> Connect Telegram to your assistant, receive scheduled results, and manage or remove a connected chat.
Connect Telegram to your assistant, receive scheduled results, and manage or remove a connected chat.
The assistant that answers on Home can live in a Telegram chat as well. The same memory answers in both places, and when the assistant finishes a scheduled run its result is delivered to that chat. Telegram is not an MCP client: it is a second door to the one assistant, not a reader of your Memories from outside.
## Before you start
[Section titled “Before you start”](#before-you-start)
* Telegram on your phone.
* An account whose assistant has a working model under AI Setup; the chat answers with the same model as Home.
## Set up
[Section titled “Set up”](#set-up)
Membase connects Telegram through a bot you own.
1. In Telegram, open @BotFather, send it `/newbot` and copy the bot token it gives you.
2. On Home, at the foot of the conversation rail under **Remote**, press **Connect Telegram**.
3. Paste the bot token. If you want a **Webhook secret token**, fill it in now, before **Save**: it is the `secret_token` you pass to Telegram’s `setWebhook` in the next step, and once set Membase accepts only updates that carry it. Then press **Save**; Membase checks the token with Telegram before it keeps it.
4. Register the webhook. Membase does not poll Telegram and does not call `setWebhook` for your bot, so the bot hears nothing until you do. After **Save** the dialog shows the address once, as **Webhook URL**; copy it, then open `https://api.telegram.org/bot/setWebhook?url=` with your bot token and that address (add `&secret_token=` if you set one).
5. Press **Generate QR code**. Scan the QR with your phone’s camera, or press **Copy link** and open the link in Telegram. Either way Telegram opens your bot with a one-time code already filled in; send it.
6. Back in the dialog press **Check connection**. The chat appears under **Connected chats**, and the **Remote** row on Home now opens that chat.
The code is single-use, valid for 15 minutes and tied to your account. Nothing is connected until the bot actually receives it from your phone.
## What it can do
[Section titled “What it can do”](#what-it-can-do)
* **Talk to the assistant.** Ask anything you would ask on Home. It reads the same Memories and keeps the same instructions.
* **Receive scheduled results.** When the assistant finishes a scheduled run, its result is sent to this chat. A Memory’s scheduled update runs its own agent, not the assistant, so it is not sent here.
* **Read it on Home.** The **Remote** row opens a read-only view of the Telegram chat’s last 8 turns, so what you said recently on your phone is there when you are back at your desk.
The Telegram chat is its own conversation. It does not appear in the day-grouped list on Home, and Home’s conversations do not appear in Telegram; the memory is what they share.
## Which Memories it uses
[Section titled “Which Memories it uses”](#which-memories-it-uses)
The assistant’s: the Memories listed in the assistant’s own settings on Home (the ⚙ **Assistant settings** button beside **Remote**, at the foot of the conversation rail). There is no switch on Connect for Telegram, because Telegram is the assistant, not an app reading it.
## Remove it
[Section titled “Remove it”](#remove-it)
Open **Assistant settings** (the ⚙ beside **Remote**) and press **Disconnect** in its Telegram section. The connection dialog (Home’s **Connect Telegram** quick action) also lists **Connected chats** with a **Delete** per chat. The bot stops answering that chat at once, and scheduled results stop going there.
## If something looks wrong
[Section titled “If something looks wrong”](#if-something-looks-wrong)
| It says | What it means | Do |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| the bot never answers anything | its webhook is not registered with Telegram | register the **Webhook URL** with `setWebhook` (step 4) |
| *That bind code is invalid or expired* | the code expired (15 minutes) or was already used | generate a new QR |
| the chat answers on the phone but nothing shows under **Remote** | the dialog has not re-read the connection yet | press **Check connection** |
| a scheduled result never reached Telegram | only the assistant’s own scheduled runs are delivered, and only to a chat bound to it | Home › Remote › **Connect Telegram**; a Memory’s schedule is not delivered to Telegram |
| the chat replies with an error instead of an answer | the assistant’s run failed, for example because no model is available (on Home: *AI is unavailable*) | on Home press **Open AI Setup**, then **Connect** a key or a subscription |
# What's new
> New features and significant updates for Membase users and developers.
New features and significant product changes, newest first.
## October 2026
[Section titled “October 2026”](#october-2026)
**SDK packages renamed (11 Oct).** The Python SDK is now `unibaseio-membase` on PyPI and the TypeScript SDK `@unibaseio/membase` on npm, both from 0.3.0. The Python package includes the `membase` command line; `@unibaseio/membase-cli` provides the same command for the hosted API without Python. `pip install 'unibaseio-membase[local]'` adds an MCP server (`membase mcp`) and, on Python 3.12 or 3.13, runs the memory engine on your machine: `Membase(local=True)` in Python, or `membase --local serve` for the same API over local HTTP. [SDKs](/build/reference/sdk-quickstart/).
## September 2026
[Section titled “September 2026”](#september-2026)
**Python and TypeScript SDKs (28 Sep).** Integrate Membase into your application with the Python or TypeScript SDK, now on PyPI and npm. Add documents, search memories and retrieve a profile with a developer key, or ask an agent with a subscription credential. [Get started with the SDKs](/build/reference/sdk-quickstart/).
**Notion sources (22 Sep).** Connect Notion and select the pages to use in a Memory. After syncing your sources, select **Update now** to process their content. [Connect Notion](/use/bring-your-material-in/notion/).
**AI options after the free allowance (22 Sep).** Your memories remain available when your free chat turns are used. To continue running your assistant, connect your own model in **AI Setup** or choose a paid plan.
**Developer keys and AI connections (17 Sep).** Create keys with specific permissions, memory access and expiry dates. Manage or revoke access at any time. In **Connect**, use the **MCP** tab for supported AI apps or the **Skills** tab for agents that can run commands. [Connect your AI](/connect/).
**Memory access through MCP and REST (17 Sep).** Apps connected through MCP can list and search the Memories you approved, and read your profile when you tick **Profile access**. Developer keys add document reading at **Read**, adding content at **Read & write**, and removing documents or memory entries at **Full access**, where each removal needs explicit confirmation. [API reference](/build/reference/api-reference/).
**Invitations (16 Sep).** Share your invitation link to invite others to Membase.
**Separate Home and Telegram conversations (8 Sep).** Use the same assistant memory in Home and Telegram while keeping their conversation histories separate. Ending or deleting one conversation does not remove the other.