Python SDK Reference

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

pip install memanto

Quick Start

import time

from memanto import Memanto

memanto = Memanto(agent_id="my-agent")

memanto.remember("Alex prefers oat milk.", type="preference")
time.sleep(1)  # new memories become searchable in under a second

result = memanto.recall("what does Alex drink?")
print(result["memories"])

result = memanto.answer("Does Alex drink dairy?")
print(result["answer"])

On construction, the client:

Resolves your API key (see Authentication).
Creates the agent if it does not exist (if auto_create is enabled — default True).
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:

The api_key= argument
The key saved by memanto setup in ~/.memanto/.env
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 = Memanto(agent_id="my-agent")

`Memanto` Client

Constructor

Memanto(
    agent_id: str,
    *,
    api_key: str | None = None,
    auto_create: bool = True,
    pattern: str = "tool",
    session_hours: int | None = None,
)

Argument	Type	Default	Description
`agent_id`	`str`	—	Required. Agent identifier (letters, digits, `-`, `_`).
`api_key`	`str \| None`	`None`	Moorcheh API key. Falls back to the saved key, then `MOORCHEH_API_KEY` (see Authentication). Not needed on-prem.
`auto_create`	`bool`	`True`	Create the agent if it does not exist. When `False`, a missing agent raises `AgentNotFoundError`.
`pattern`	`str`	`"tool"`	Pattern for an auto-created agent: `"tool"`, `"support"`, or `"project"`. See Agent Patterns.
`session_hours`	`int \| None`	config	Lifetime of a newly activated session. Defaults to the configured session duration.

Memory Write Methods

memanto.remember(content, *, type=None, title=None, confidence=0.8, tags=None, source="user", provenance=None)
memanto.batch_remember(memories)            # list of dicts, up to 100; same keys as remember()
memanto.update_memory(memory_id, **updates) # title, content, type, confidence, tags, source
memanto.delete_memory(memory_id)

Deleting the Agent

memanto.delete_agent()                      # memories are kept in Moorcheh
memanto.delete_agent(delete_memories=True)  # memories are deleted permanently

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.

Memory Read Methods

memanto.recall(query, *, limit=None, type=None, tags=None, min_similarity=None)  # tags: only memories carrying all of them
memanto.recall_as_of(as_of, *, limit=None, type=None, tags=None)          # point-in-time
memanto.recall_changed_since(since, *, limit=None, type=None, tags=None)  # what changed after
memanto.recall_recent(*, limit=None, type=None, tags=None)                # newest-first
memanto.answer(question, *, limit=None, threshold=None, temperature=None, ai_model=None, kiosk_mode=None)

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, conversation extraction, daily summaries, conflicts, memory policies, and export — use the underlying client on memanto.client. Its methods take agent_id as the first argument:

memanto.client.upload_file("my-agent", "notes.pdf")
memanto.client.extract_memories_from_conversation("my-agent", messages)
memanto.client.generate_conflict_report("my-agent")
memanto.client.list_agents()

Errors

Validation problems (an empty content, an unknown type, an out-of-range confidence) raise ValueError. Memanto-specific errors live in memanto.app.utils.errors:

from memanto.app.utils.errors import AgentNotFoundError, SessionError

Python vs. TypeScript SDK

	Python (`memanto`)	TypeScript (`@moorcheh-ai/memanto`)
Runs	In-process	Spawns `uvx memanto serve`, talks HTTP
Needs `uv`	No	Yes
Method names	`snake_case` (`recall_recent`)	`camelCase` (`recallRecent`)

The method names map one-to-one. See the TypeScript SDK Reference.

License

MIT

​Python SDK Reference

​Prerequisites

​Installation

​Quick Start

​Authentication

​Memanto Client

​Constructor

​Memory Write Methods

​Deleting the Agent

​Memory Read Methods

​Everything Else: memanto.client

​Errors

​Python vs. TypeScript SDK

​License

Python SDK Reference

Prerequisites

Installation

Quick Start

Authentication

`Memanto` Client

Constructor

Memory Write Methods

Deleting the Agent

Memory Read Methods

Everything Else: `memanto.client`

Errors

Python vs. TypeScript SDK

License