Python SDK
The Python SDK (emergent-memory) is a client library for the Memory API. It
mirrors the Go SDK, exposes one root Client with a sub-client per resource
area, and supports all three authentication modes plus SSE streaming.
Source: sdk/python/
Import name: emergent
Distribution name: emergent-memory
Installation
Section titled “Installation”From a clone of the repository:
git clone https://github.com/emergent-company/emergent.memory.gitcd emergent.memorypip install -e sdk/pythonRuntime requirements, from sdk/python/pyproject.toml:
| Requirement | Version |
|---|---|
| Python | >=3.10 |
httpx |
>=0.24.0 |
pydantic |
>=2.0.0 |
Quick start
Section titled “Quick start”from emergent import Client
client = Client.from_api_key("https://memory.emergent-company.ai", "<your-token>")client.set_context(org_id="org_abc123", project_id="proj_xyz789")
for project in client.projects.list(): print(project["id"], project["name"])
client.close()Use the client as a context manager to close the HTTP connection pool automatically:
from emergent import Client
with Client.from_api_key("https://memory.emergent-company.ai", "<your-token>") as client: client.set_context(org_id="org_abc123", project_id="proj_xyz789") print(client.documents.list(limit=10))Authentication
Section titled “Authentication”Client sends one of two credential headers, depending on the mode:
| Mode | Use it for | Header sent |
|---|---|---|
apikey |
Standalone / self-hosted server key | X-API-Key: <key> |
apitoken |
Project-scoped token (emt_*) |
Authorization: Bearer <token> |
oauth |
OAuth 2.0 access token you manage | Authorization: Bearer <token> |
mode="apikey" is the default. If the key starts with emt_, the SDK detects
it and switches to APITokenProvider automatically, so the same constructor
works for a server key and a project token.
from emergent import Client
# Standalone server API key (X-API-Key)client = Client.from_api_key("http://localhost:3012", "<server-api-key>")
# Project API token (emt_ prefix -> Bearer, auto-detected)client = Client.from_api_key("https://memory.emergent-company.ai", "emt_<your-token>")
# OAuth access token (the caller refreshes it)client = Client.from_oauth_token( "https://memory.emergent-company.ai", access_token="<your-access-token>",)Automatic discovery with Client.from_env()
Section titled “Automatic discovery with Client.from_env()”from emergent import Client
client = Client.from_env()Configuration is merged in this order, lowest priority first:
~/.memory/config.yaml(server_url,api_key,project_token,org_id,project_id).env(walked up from the current directory).env.local(walked up from the current directory)MEMORY_*environment variables
Recognised environment variables:
| Variable | Meaning |
|---|---|
MEMORY_SERVER_URL |
Server URL (MEMORY_API_URL is an alias) |
MEMORY_ACCOUNT_API_KEY |
Account-level key (MEMORY_API_KEY is a deprecated alias) |
MEMORY_PROJECT_API_KEY |
Project token (MEMORY_PROJECT_TOKEN is a deprecated alias) |
MEMORY_ORG_ID |
Default organisation ID |
MEMORY_PROJECT_ID |
Default project ID |
If MEMORY_PROJECT_API_KEY is set, it is used as the credential instead of the
account key. from_env() raises OSError when no server URL or credential can
be found.
Full configuration object
Section titled “Full configuration object”from emergent import Client, Config
client = Client( Config( server_url="https://memory.emergent-company.ai", api_key="emt_<your-token>", org_id="org_abc123", project_id="proj_xyz789", ))Config fields: server_url (required), api_key, mode, access_token,
org_id, project_id, and an optional http_client.
Organisation and project context
Section titled “Organisation and project context”Most sub-clients send X-Org-ID and X-Project-ID on every request. Set both
once; set_context propagates the values to every context-scoped sub-client
atomically.
client.set_context(org_id="org_abc123", project_id="proj_xyz789")If you manage the HTTP transport yourself, authenticate_request injects the
same auth and context headers into a plain dict:
headers = client.authenticate_request({})# {"Authorization": "Bearer <token>", "X-Org-ID": "...", "X-Project-ID": "..."}Core resources
Section titled “Core resources”Projects and organisations
Section titled “Projects and organisations”These sub-clients are not project-scoped.
projects = client.projects.list()project = client.projects.get("proj_xyz789")
created = client.projects.create({"name": "Product Research"})client.projects.update("proj_xyz789", {"name": "Renamed"})client.projects.delete("proj_xyz789")
orgs = client.orgs.list()org = client.orgs.get("org_abc123")client.orgs.create({"name": "Acme Corp"})client.orgs.delete("org_abc123")Knowledge graph
Section titled “Knowledge graph”Objects are created from a payload and returned as dictionaries.
obj = client.graph.create_object( { "type": "Person", "name": "Alice", "properties": {"role": "engineer"}, })
obj = client.graph.get_object(obj["id"])client.graph.update_object(obj["id"], {"properties": {"role": "lead"}})client.graph.delete_object(obj["id"])
page = client.graph.list_objects(type="Person", limit=50)count = client.graph.count_objects(type="Person")Upserts and search:
client.graph.upsert_object( { "externalId": "user-alice", "type": "Person", "name": "Alice", })
hits = client.graph.fts_search("Alice", limit=20)similar = client.graph.find_similar(obj["id"], limit=10)
# Hybrid search with graph neighbours, and subgraph extraction, take a payloadres = client.graph.search_with_neighbors({"query": "machine learning", "limit": 5})sub = client.graph.subgraph({"object_ids": [obj["id"]], "depth": 2})Relationships take a payload with type, src_id, and dst_id. Optional keys
include properties, weight, and branch_id.
rel = client.graph.create_relationship( { "type": "KNOWS", "src_id": "obj_1", "dst_id": "obj_2", "properties": {"since": "2024"}, })
client.graph.list_relationships(type="KNOWS", limit=50)client.graph.count_relationships(type="KNOWS")client.graph.get_relationship_history(rel["id"])client.graph.restore_relationship(rel["id"])Objects can be moved between branches:
client.graph.move_object("obj_id", target_branch_id="branch_2")Documents
Section titled “Documents”docs = client.documents.list(limit=50, offset=0)doc = client.documents.get("doc_id")
# Upload a local file; extraction is enabled by defaultresult = client.documents.upload("/path/to/report.pdf", auto_extract=True)
# Signed download URL (the server redirects; this returns the target)url = client.documents.download_url("doc_id")
client.documents.bulk_delete(["doc_1", "doc_2"])summary = client.documents.get_extraction_summary("doc_id")upload() returns {"document": ..., "isDuplicate": bool, "existingDocumentId": ...}.
Pass file_name="..." to override the uploaded file name.
Unified search
Section titled “Unified search”results = client.search.search( "machine learning", limit=10, strategy="hybrid", result_types="both",)
graph_only = client.search.graph_search("neural networks", limit=5)text_only = client.search.text_search("neural networks", limit=5)search() returns {"results": [...], "metadata": {...}}; the two convenience
methods return the result list directly.
Chat and streaming
Section titled “Chat and streaming”chat.stream() is a generator of typed SSE events. The message is the first
positional argument.
from emergent import Client, DoneEvent, MetaEvent, TokenEvent
with Client.from_api_key("https://memory.emergent-company.ai", "<your-token>") as client: client.set_context(org_id="org_abc123", project_id="proj_xyz789")
for event in client.chat.stream("What is a knowledge graph?"): if isinstance(event, TokenEvent): print(event.token, end="", flush=True) elif isinstance(event, MetaEvent): print("\nCitations:", event.citations) elif isinstance(event, DoneEvent): breakContinue an existing conversation with conversation_id:
conv = client.chat.create_conversation(title="My chat", message="Hello")for event in client.chat.stream("Summarise the graph", conversation_id=conv.id): if event.type == "token": print(event.token, end="")chat.ask() streams an answer through the project ask endpoint, and
chat.ask_collect() blocks and returns the accumulated text as a string:
answer = client.chat.ask_collect("Summarise the project goals")print(answer)
for event in client.chat.ask("Summarise project goals"): if event.type == "token": print(event.token, end="")SSE event classes:
| Class | type |
Key attributes |
|---|---|---|
MetaEvent |
"meta" |
conversation_id, citations, graph_objects |
TokenEvent |
"token" |
token (text delta) |
MCPToolEvent |
"mcp_tool" |
tool, status, result, error |
ErrorEvent |
"error" |
error |
DoneEvent |
"done" |
— |
UnknownEvent |
any other value | raw |
Agents
Section titled “Agents”agents = client.agents.list()agent = client.agents.get("agent_id")
run = client.agents.trigger("agent_id")run = client.agents.get_project_run(run["runId"])
client.agents.respond_to_question("<question-id>", "yes")Other sub-clients
Section titled “Other sub-clients”| Attribute | Purpose |
|---|---|
client.branches |
List, create, update, fork, and delete graph branches |
client.tasks |
Project and cross-project background tasks |
client.schemas |
Schema packs: list available/installed, assign |
client.skills |
Project skills CRUD |
client.agent_definitions |
Agent definition templates |
client.api_tokens |
Project and account API tokens |
client.mcp |
MCP JSON-RPC client (list_tools, call_tool, …) |
Error handling
Section titled “Error handling”HTTP errors are raised as APIError. The exception carries status_code,
code, message, and details, plus predicate properties:
from emergent import APIError
try: obj = client.graph.get_object("nonexistent")except APIError as e: if e.is_not_found: print("Object not found") elif e.is_unauthorized: print("Check the credential") else: print(f"API error {e.status_code}: {e.message}")Other exported exceptions are EmergentError (base class), AuthError, and
StreamError.
Closing the client
Section titled “Closing the client”client.close()If you supplied http_client in Config, the SDK does not close it; you own
that client’s lifecycle.
Next steps
Section titled “Next steps”- Go SDK — the reference client this SDK mirrors
- Knowledge Graph — objects, relationships, and branches
- Documents — ingestion and extraction
- Memory CLI — the command-line interface for the same API
- API Reference — raw REST endpoints