Skip to content
Membase Docs

API quickstart

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 and check AI Setup if a run cannot use a model.

1. Create a key

Section titled “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.

Terminal window
export MEMBASE_API_KEY="mbk_…"

The key guide explains rotation and revocation. The examples call https://api.app.membase.io.

Section titled “2. Add, wait, then search”

add returns 202 when material is accepted; it does not promise that learning has finished. Check documents.get(id).learned before searching for the new content. The examples stop on a failed learning run and have a polling limit, so they cannot wait indefinitely.

Install with pip install membase-sdk, save this as quickstart.py, and run python quickstart.py in the shell where you exported the key.

import time
from membase import Membase


client = Membase()
containers = client.containers.list()["containers"]
if len(containers) != 1:
    raise RuntimeError("For this example, select exactly one Memory on the key's Reach page.")
container = containers[0]["id"]
custom_id = "quickstart-ledger-v1"


added = client.add(
    "We chose Postgres for the Lumen ledger.",
    container=container,
    title="Lumen decision",
    custom_id=custom_id,
)
document_id = added.get("document_id")
if not document_id:
    raise RuntimeError(f"Accepted at {added.get('path')}, but the document id is pending. See API troubleshooting.")


for _ in range(60):
    document = client.documents.get(document_id)
    if document.get("learned"):
        break
    status = (document.get("learning_run") or {}).get("status")
    if status in {"failed", "canceled"}:
        raise RuntimeError("Learning stopped. 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?", container=container)
errors = [c for c in found["containers"] if c.get("error")]
if errors:
    raise RuntimeError(f"Some Memories could not answer: {errors}")
for hit in found["results"]:
    print(hit["container_name"], "·", hit["content"])
if not found["results"]:
    print("No matching passages. Inspect the Memory and its latest Report in the app.")

3. Check the result

Section titled “3. Check the result”

Expect a passage naming Postgres and the Memory it came from. The exact wording can vary. An empty results list is not enough to diagnose a problem: inspect containers[].error first, then the Memory’s learned content and latest Report.

Re-running this example with the same custom_id does not add a second copy. 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.

Next steps

Section titled “Next steps”