Guides

Python and Node SDKs

Typed HTTP clients for the Memory API. Same mem_... key as MCP. Default base URL is https://memoria-api-jw5g.onrender.com. Published as memoria-cloud-sdk on PyPI and npm. Requires Python 3.12+ or Node 24+.

Install

Python:

bash

pip install memoria-cloud-sdk
# or
uv add memoria-cloud-sdk

Node:

bash

npm install memoria-cloud-sdk
# or
bun add memoria-cloud-sdk

Auth and env

Constructor args override env. MEMORY_API_KEY is required for writes and search. MEMORY_API_URL is optional (hosted default is used if unset). health() does not need a key.

bash

export MEMORY_API_KEY=mem_...
# optional, defaults to https://memoria-api-jw5g.onrender.com
export MEMORY_API_URL=https://memoria-api-jw5g.onrender.com

What the fields mean

Names match the HTTP API. Python uses keyword args; Node uses one object. Nothing here is SQL — q is a search question in plain language.

Field	Meaning
content	The sentence or paragraph to store. Example: `We prefer pytest`.
session_id	A label you invent for a chat, ticket, or project (for example `s1` or `cli-demo`). It is not a second tenant — the org still comes from the API key. Required on `remember` and `emit`. On `recall`, omit it to search the whole org; pass it only to narrow to one label.
memory_type	`semantic` (defaults): preferences and decisions. `episodic`: what happened in a session. `procedural`: steps that worked. See Memory types.
importance	Number from 0 to 1. Higher ranks higher in recall. Default `0.5`.
q	On `recall`: the question you would type into search. Example: `what test runner do we use?` or just `pytest`. The API embeds that text and ranks memories. It is not a keyword filter. On `list_memories`, `q` is an optional substring filter and does not run semantic search — use `recall` when you want ranked matches.
limit	Max memories to return from `recall`. Default 10.
as_of	Optional ISO timestamp. Recall using graph edges as they were at that time (historical view). Example: `2026-09-01T00:00:00Z`.
explain	If true, each hit includes `score_details` (vector vs KV vs graph). Off by default.
token_budget	Cap how much recall text comes back (rough token count). Default 2048.
event_type	For `emit`: kind of queued event, usually `message`. Also `tool_call`, `diff`, `session_end`. `emit` only queues; `remember` saves immediately.

kv_facts / kvFacts lists extracted key–value rows (entity, fact type, value). graph_edges / graphEdges lists subject–relation–object triples. Both are filled by extraction after remember/emit, not by you on every call.

Python

python

from memoria_cloud import Memoria

client = Memoria()  # reads MEMORY_API_KEY / MEMORY_API_URL

# Save a preference. session_id is a label you choose.
memory = client.remember(
    content="We prefer pytest",
    session_id="cli-demo",
    memory_type="semantic",
)

# q = the search question. Omit session_id to search the whole org.
hits = client.recall(q="what test runner do we use?", limit=5)
for row in hits.memories:
    print(row.content, row.score)

# List without embedding a query (optional substring via q=).
listed = client.list_memories(session_id="cli-demo", memory_type="semantic")

Node

import { Memoria } from "memoria-cloud-sdk";

const client = new Memoria();

await client.remember({
  content: "We prefer pytest",
  session_id: "cli-demo",
  memory_type: "semantic",
});

const hits = await client.recall({
  q: "what test runner do we use?",
  limit: 5,
});
for (const row of hits.memories) {
  console.log(row.content, row.score);
}

Methods

Python names below. Node uses camelCase for inspect helpers (listMemories, kvFacts, graphEdges). Core verbs stay remember, recall, update, forget, emit, health.

Method	What it does
remember	Save text now. Then extract KV/graph. POST /memories.
recall	Ranked search from `q`. GET /memories/search.
list_memories	Browse stored rows. No embedding. GET /memories.
kv_facts	Extracted facts for the org. GET /kv-facts.
graph_edges	Extracted triples. GET /graph-edges.
update	Patch content, importance, or type. Re-embeds. PATCH /memories/{id}.
forget	Delete one memory. DELETE /memories/{id}.
emit	Queue an event for later extraction. POST /events.
health	Liveness. GET /health. No API key.

Typed errors: 401 auth, 404 not found, 429 rate limit. Google OAuth and dashboard key admin are not in the SDK.