> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memanto.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Python SDK Reference
> Full reference for the Memanto Python client — the Memanto class in the memanto package.
# 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](https://console.moorcheh.ai/api-keys)), or on-prem configured once with the `memanto` CLI
## Installation
```bash theme={null}
pip install memanto
```
## Quick Start
```python theme={null}
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:
1. Resolves your API key (see [Authentication](#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`:
```python theme={null}
memanto = Memanto(agent_id="my-agent")
```
## `Memanto` Client
### Constructor
```python theme={null}
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](#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](/guides/agent-management). |
| `session_hours` | `int \| None` | config | Lifetime of a newly activated session. Defaults to the configured session duration. |
### Memory Write Methods
```python theme={null}
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
```python theme={null}
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](/reference/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
```python theme={null}
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](/api-reference/authentication) 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:
```python theme={null}
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`:
```python theme={null}
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](/sdk/typescript).
## License
MIT
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.