Skip to main content

Python SDK Reference

Python The 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 memanto CLI

Installation

Quick Start

On construction, the client:
  1. Resolves your API key (see Authentication).
  2. Creates the agent if it does not exist (if auto_create is enabled — default True).
  3. Reuses the agent’s live session if there is one, otherwise activates a new session.
Sessions renew automatically while the client is in use, and they outlive the process — there is nothing to close. If the session expires while the process is idle, or another client of the same agent replaces it, the next call recovers on its own: the client adopts the agent’s current live session (or activates one) and retries once.
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:
  1. The api_key= argument
  2. The key saved by memanto setup in ~/.memanto/.env
  3. The MOORCHEH_API_KEY environment variable
The saved key wins over the environment variable because Memanto loads ~/.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

By default the agent’s memories stay in Moorcheh and come back if you create an agent with the same 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().
  • type is optional; when given, it must be one of the memory types.
  • title defaults to the first 50 characters of content.
  • provenance defaults to "explicit_statement".
  • Writes return status: "queued" and are indexed in the background: a new memory shows up in recall() and answer() typically within half a second.

Extracting from Conversations

extract() takes chat turns, uses the LLM to extract typed memories, and stores them:
With 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 empty content, 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.

License

MIT