Python SDK Reference
memanto package on PyPI ships a Python client alongside the CLI. It runs in-process: there is no server to start, no uvx, and no HTTP hop. The Memanto class talks to your configured backend (Moorcheh Cloud or on-prem) directly.
Prerequisites
- Python 3.10+
- A backend: a Moorcheh API key for the cloud (free key), or on-prem configured once with the
memantoCLI
Installation
Quick Start
- Resolves your API key (see Authentication).
- Creates the agent if it does not exist (if
auto_createis enabled — defaultTrue). - Reuses the agent’s live session if there is one, otherwise activates a new session.
Memanto allows one session per agent. Activating a session signs out every other client of that agent (the CLI, MCP, IDE hooks). That is why the client adopts an existing live session instead of activating a new one, so it never signs out the CLI or another process that is using the agent. Use one
Memanto instance per agent; an instance is not thread-safe.Authentication
The API key is resolved in this order:- The
api_key=argument - The key saved by
memantosetup in~/.memanto/.env - The
MOORCHEH_API_KEYenvironment variable
~/.memanto/.env over the environment. On a server or in CI, either export MOORCHEH_API_KEY and don’t run memanto setup there, or pass api_key= explicitly.
An explicit api_key= applies to that instance only; it never changes the key other Memanto instances in the same process resolve.
On the on-prem backend no key is needed — run memanto once, choose On-Prem, then construct the client without api_key:
Memanto Client
Constructor
Memory Write Methods
Deleting the Agent
agent_id again. With delete_memories=True they are deleted first; if that fails, the agent is left intact and NamespaceError is raised, so you can retry. The instance cannot be used after delete_agent().
typeis optional; when given, it must be one of the memory types.titledefaults to the first 50 characters ofcontent.provenancedefaults to"explicit_statement".- Writes return
status: "queued"and are indexed in the background: a new memory shows up inrecall()andanswer()typically within half a second.
Extracting from Conversations
extract() takes chat turns, uses the LLM to extract typed memories, and stores them:
dry_run=True it returns the candidates without storing them. Otherwise the result also holds the batch outcome (successful, failed, results, …), as in Extract Memories.
When the conversation holds nothing worth remembering, extract() raises NothingToExtractError and writes nothing. It is a subclass of ValueError, so you can tell it apart from unusable LLM output (a plain ValueError) while an except ValueError still catches both.
Memory Read Methods
type and tags filters take one value or a list: type="fact" or type=["fact", "decision"]. as_of and since accept an ISO date ("2026-03-01") or datetime.
Every method returns a dict with the same shape as the matching REST endpoint response — for example recall() returns {"memories": [...], ...} and answer() returns {"answer": "...", ...}.
Everything Else: memanto.client
The wrapper covers the everyday memory calls. For the full surface — agent management, file upload, daily summaries, conflicts, memory policies, and export — use the underlying client on memanto.client. Its methods take agent_id as the first argument:
Errors
Validation problems (an emptycontent, an unknown type, an out-of-range confidence) raise ValueError. extract() raises NothingToExtractError (a ValueError, importable from memanto) when there is nothing to store. Memanto-specific errors live in memanto.app.utils.errors:
Python vs. TypeScript vs. Go SDK
The method names map one-to-one. See the TypeScript SDK Reference and the Go SDK Reference.