# Create Agent
Source: https://docs.memanto.ai/api-reference/agents/create-agent
POST /api/v2/agents
Create a new agent to establish a dedicated Moorcheh namespace for storing and retrieving memories.
## Overview
Create a new agent namespace for storing and retrieving memories. Each agent receives a unique `agent_id` which acts as an isolated context container in Moorcheh (`memanto_agent_{agent_id}`).
## Authentication
Memanto validates Moorcheh credentials **on the server** using `MOORCHEH_API_KEY` (environment / server configuration).
`Bearer ` — required unless the request originates from a loopback client. See [Management Endpoint Authentication](/api-reference/authentication#management-endpoint-authentication-agent-lifecycle).
Alternative to `Authorization: Bearer` — same credential.
Must be `application/json`
## Body
Unique agent identifier (alphanumeric, hyphens, underscores only).
Agent pattern for memory organization. One of: `support`, `project`, `tool`. Defaults to `support`.
Optional human-readable description of the agent.
```bash cURL theme={null}
curl -X POST "http://localhost:8000/api/v2/agents" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "customer-support",
"pattern": "support",
"description": "Handles customer inquiries"
}'
```
```json 201 - Created theme={null}
{
"agent_id": "customer-support",
"namespace": "memanto_agent_customer-support",
"pattern": "support",
"description": "Handles customer inquiries",
"created_at": "2026-05-04T10:30:00.000000",
"last_session": null,
"memory_count": 0,
"session_count": 0,
"status": "ready"
}
```
```json 401 - Unauthorized (Management Auth Required) theme={null}
{
"detail": "Unauthorized. Agent management endpoints require either a loopback client or a valid management credential (Authorization: Bearer or X-Api-Key)."
}
```
```json 409 - Conflict theme={null}
{
"detail": {
"error": "AgentAlreadyExists",
"message": "Agent 'customer-support' already exists",
"details": {}
}
}
```
```json 422 - Validation Error theme={null}
{
"detail": [
{
"type": "missing",
"loc": [
"body",
"agent_id"
],
"msg": "Field required",
"input": {}
}
]
}
```
```json 500 - Server Error theme={null}
{
"detail": {
"error": "InternalServerError",
"message": "An unexpected error occurred",
"details": {
"original_error": "..."
}
}
}
```
Common causes of `500` include the server missing `MOORCHEH_API_KEY`, an invalid key (Memanto may fail at startup), or failure to create the namespace in Moorcheh.
## Next Steps
After creating a new agent, you can:
* [Activate Agent](/api-reference/sessions/activate-agent) to start a session and obtain an operational token
* [List Agents](/api-reference/agents/list-agents) to verify it was created
* [Get Agent](/api-reference/agents/get-agent) to retrieve its configuration details
# Delete Agent
Source: https://docs.memanto.ai/api-reference/agents/delete-agent
DELETE /api/v2/agents/{agent_id}
Delete an agent's local metadata; optionally remove its Moorcheh namespace.
## Overview
Removes the agent record from Memanto's local store. By default, memories remain in Moorcheh under that agent's namespace. Pass `delete-backup-too=true` to also delete the namespace and its contents in Moorcheh.
Without `delete-backup-too=true`, only **local** agent metadata is removed; the cloud namespace is left intact.
## Authentication
`Bearer ` — required unless the request originates from a loopback client. See [Management Endpoint Authentication](/api-reference/authentication#management-endpoint-authentication-agent-lifecycle).
Alternative to `Authorization: Bearer` — same credential.
## Path Parameters
The unique identifier of the agent to delete.
## Query Parameters
When `true`, also deletes the agent's Moorcheh namespace (`memanto_agent_{agent_id}`) and its memories. When `false` or omitted, the namespace is not deleted. Accepts `true` or `false`.
```bash Local metadata only theme={null}
curl -X DELETE "http://localhost:8000/api/v2/agents/old-agent"
```
```bash Delete Moorcheh namespace too theme={null}
curl -X DELETE "http://localhost:8000/api/v2/agents/old-agent?delete-backup-too=true"
```
```json 200 - OK (namespace retained) theme={null}
{
"message": "Agent 'old-agent' successfully deleted (backup retained in Moorcheh)"
}
```
```json 200 - OK (namespace deleted) theme={null}
{
"message": "Agent 'old-agent' successfully deleted with all namespace memories"
}
```
```json 401 - Unauthorized (Management Auth Required) theme={null}
{
"detail": "Unauthorized. Agent management endpoints require either a loopback client or a valid management credential (Authorization: Bearer or X-Api-Key)."
}
```
```json 404 - Not Found theme={null}
{
"detail": {
"error": "AgentNotFound",
"message": "Agent 'old-agent' not found",
"details": {}
}
}
```
```json 500 - Server Error theme={null}
{
"detail": {
"error": "InternalServerError",
"message": "An unexpected error occurred",
"details": {
"original_error": "..."
}
}
}
```
## Next Steps
After deleting an agent, you can:
* [Create a new Agent](/api-reference/agents/create-agent)
* [List remaining Agents](/api-reference/agents/list-agents) to verify deletion
# Get Agent
Source: https://docs.memanto.ai/api-reference/agents/get-agent
GET /api/v2/agents/{agent_id}
Get detailed information about a specific agent.
## Overview
Returns metadata and counters for one agent registered with Memanto (namespace, pattern, sessions, etc.).
## Authentication
`Bearer ` — required unless the request originates from a loopback client. See [Management Endpoint Authentication](/api-reference/authentication#management-endpoint-authentication-agent-lifecycle).
Alternative to `Authorization: Bearer` — same credential.
## Path Parameters
The unique identifier of the agent.
```bash cURL theme={null}
curl -X GET "http://localhost:8000/api/v2/agents/customer-support"
```
```json 200 - OK theme={null}
{
"agent_id": "customer-support",
"namespace": "memanto_agent_customer-support",
"pattern": "support",
"description": "Handles customer inquiries",
"created_at": "2026-05-04T10:30:00.000000",
"last_session": "2026-05-04T14:22:00.000000",
"memory_count": 42,
"session_count": 5,
"status": "ready"
}
```
```json 401 - Unauthorized (Management Auth Required) theme={null}
{
"detail": "Unauthorized. Agent management endpoints require either a loopback client or a valid management credential (Authorization: Bearer or X-Api-Key)."
}
```
```json 404 - Not Found theme={null}
{
"detail": {
"error": "AgentNotFound",
"message": "Agent 'customer-support' not found",
"details": {}
}
}
```
```json 500 - Server Error theme={null}
{
"detail": {
"error": "InternalServerError",
"message": "An unexpected error occurred",
"details": {
"original_error": "..."
}
}
}
```
## Next Steps
Once you have verified the agent's details, you can:
* [Activate Agent](/api-reference/sessions/activate-agent) to start a session
* [List all Agents](/api-reference/agents/list-agents)
* [Delete Agent](/api-reference/agents/delete-agent) if it's no longer needed
# List Agents
Source: https://docs.memanto.ai/api-reference/agents/list-agents
GET /api/v2/agents
List all agents registered with Memanto.
## Overview
Returns every agent stored locally by Memanto, sorted by creation time (newest first). Each entry includes namespace, pattern, activity counters, and status.
## Authentication
`Bearer ` — required unless the request originates from a loopback client. See [Management Endpoint Authentication](/api-reference/authentication#management-endpoint-authentication-agent-lifecycle).
Alternative to `Authorization: Bearer` — same credential.
```bash cURL theme={null}
curl -X GET "http://localhost:8000/api/v2/agents"
```
```bash cURL (non-loopback, with credential) theme={null}
curl -X GET "https://memanto.example.com/api/v2/agents" \
-H "Authorization: Bearer $MOORCHEH_API_KEY"
```
```json 200 - OK theme={null}
{
"agents": [
{
"agent_id": "customer-support",
"namespace": "memanto_agent_customer-support",
"pattern": "support",
"description": "Handles customer inquiries",
"created_at": "2026-05-04T10:30:00.000000",
"last_session": "2026-05-04T14:22:00.000000",
"memory_count": 42,
"session_count": 5,
"status": "ready"
},
{
"agent_id": "data-analyst",
"namespace": "memanto_agent_data-analyst",
"pattern": "project",
"description": "Analyzes metrics",
"created_at": "2026-05-03T09:15:00.000000",
"last_session": null,
"memory_count": 0,
"session_count": 0,
"status": "ready"
}
],
"count": 2
}
```
```json 401 - Unauthorized (Management Auth Required) theme={null}
{
"detail": "Unauthorized. Agent management endpoints require either a loopback client or a valid management credential (Authorization: Bearer or X-Api-Key)."
}
```
```json 500 - Server Error theme={null}
{
"detail": {
"error": "InternalServerError",
"message": "An unexpected error occurred",
"details": {
"original_error": "..."
}
}
}
```
## Next Steps
After listing your agents, you can:
* [Create Agent](/api-reference/agents/create-agent) to add a new one
* [Get Agent](/api-reference/agents/get-agent) to inspect a specific agent
* [Activate Agent](/api-reference/sessions/activate-agent) to begin a session with an agent
# Generate AI Answer
Source: https://docs.memanto.ai/api-reference/ai/generate-ai-answer
POST /api/v2/agents/{agent_id}/answer
Generate an answer grounded in memory by querying the agent's context and synthesizing an LLM response.
## Overview
Answer questions using stored agent memories. This operation retrieves relevant context from the agent's Moorcheh namespace (scoped by the active session) and calls Moorcheh **answer generation** to produce a grounded reply.
## Authentication
API clients do not send an API key or `Authorization` header.
Session token from [Activate Agent](/api-reference/sessions/activate-agent). Must match `agent_id`.
Must be `application/json`
## Path Parameters
The unique identifier of the agent.
## Body
The question to answer using retrieved memories as context.
Maximum memories to use as context (`top_k`). Range `1`–`100`. If omitted, the server default applies (see deployment configuration).
LLM temperature, `0.0`–`2.0`. If omitted, the server default applies.
Model identifier for answer generation (snake\_case field name: `ai_model`). If omitted, the server default applies.
When `true`, relevance filtering uses a confidence threshold. When `false` (default), **`threshold` is ignored** and not sent to Moorcheh.
Confidence threshold (`0.0`–`1.0`). **Only used when `kiosk_mode` is `true`.** If `kiosk_mode` is `true` and `threshold` is omitted, the server uses **0.15**.
```bash cURL theme={null}
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/answer" \
-H "X-Session-Token: your_session_token" \
-H "Content-Type: application/json" \
-d '{
"question": "How should we contact the user?",
"limit": 5,
"temperature": 0.7,
"ai_model": "anthropic.claude-sonnet-4-6",
"kiosk_mode": false
}'
```
```bash cURL (kiosk mode with default threshold 0.15) theme={null}
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/answer" \
-H "X-Session-Token: your_session_token" \
-H "Content-Type: application/json" \
-d '{
"question": "How should we contact the user?",
"kiosk_mode": true
}'
```
```json 200 - OK theme={null}
{
"agent_id": "my-agent",
"session_id": "sess_123abc",
"question": "How should we contact the user?",
"answer": "Based on stored preferences, the user prefers email communication. Send email during business hours.",
"sources": [
{
"id": "3e681f12-a28c-4d1d-9632-b8dadf1f9d0c",
"score": 0.86
}
],
"namespace": "memanto_agent_my-agent"
}
```
```json 401 - Unauthorized (Missing Token) theme={null}
{
"detail": "Missing session token. Use X-Session-Token header."
}
```
```json 401 - Unauthorized (Expired Token) theme={null}
{
"detail": {
"error": "SessionExpired",
"message": "Session has expired",
"details": {}
}
}
```
```json 422 - Validation Error theme={null}
{
"detail": [
{
"type": "missing",
"loc": [
"body",
"question"
],
"msg": "Field required",
"input": {}
}
]
}
```
```json 500 - Server Error theme={null}
{
"detail": {
"error": "InternalServerError",
"message": "An unexpected error occurred",
"details": {
"original_error": "Session is for agent 'other-agent', cannot access 'my-agent'"
}
}
}
```
```json 413 - Payload Too Large (Question Too Long) theme={null}
{
"detail": {
"error": "query_too_long",
"message": "Query exceeds maximum length of 1000 characters",
"actual_length": 1500,
"max_length": 1000
}
}
```
```json 400 - Bad Request (Limit Too Large) theme={null}
{
"detail": {
"error": "k_too_large",
"message": "k exceeds maximum of 100",
"actual_k": 200,
"max_k": 100
}
}
```
## Available Models
## Next Steps
* [Recall](/api-reference/search/recall) to fetch raw memories without generating an AI answer
* [Remember](/api-reference/data/remember) to add more context to the agent
# Generate Daily Summary
Source: https://docs.memanto.ai/api-reference/ai/generate-daily-summary
POST /api/v2/agents/{agent_id}/daily-summary
Generate the on-demand daily AI summary for an agent/date.
## Overview
Generates an AI-written summary of an agent's session memories for a given date, and triggers a memory export to refresh the local `memory.md` cache. Conflict detection is a separate concern — see [Generate Conflict Report](/api-reference/data/generate-conflicts) or the [scheduled job](/cli/schedule/enable).
## Authentication
API clients do not send an API key or `Authorization` header.
Session token from [Activate Agent](/api-reference/sessions/activate-agent). Must match `agent_id`.
## Path Parameters
The unique identifier of the agent.
## Body
Date string `YYYY-MM-DD`. Defaults to **today (UTC)** on the server when omitted.
```bash cURL theme={null}
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/daily-summary" \
-H "X-Session-Token: your_session_token" \
-H "Content-Type: application/json" \
-d '{"date": "2026-05-08"}'
```
```json 200 - OK theme={null}
{
"agent_id": "my-agent",
"session_id": "sess_abc123",
"date": "2026-05-08",
"summary": {
"status": "success",
"summary_path": "~/.memanto/summaries/my-agent_2026-05-08.md"
},
"export": {
"status": "success",
"total_memories": 42
}
}
```
```json 400 - Bad Request (Invalid Identifier) theme={null}
{
"detail": "Invalid summary identifier"
}
```
```json 401 - Unauthorized (Missing Token) theme={null}
{
"detail": "Missing session token. Use X-Session-Token header."
}
```
## Next Steps
* [Generate Conflict Report](/api-reference/data/generate-conflicts) to run conflict detection for the same date
* [List Conflicts](/api-reference/data/list-conflicts) to inspect any conflicts already detected
# Authentication
Source: https://docs.memanto.ai/api-reference/authentication
How Memanto authenticates Moorcheh and authorizes memory operations through session tokens.
# Authentication
Memanto uses a **server-side Moorcheh API key** combined with **per-agent session tokens** to scope memory operations, plus a separate **management credential** that gates agent lifecycle endpoints (create/list/get/delete/activate/deactivate an agent, and the status endpoint).
Memanto reads `MOORCHEH_API_KEY` from its environment / configuration and authenticates **on the server** when calling Moorcheh.
```bash theme={null}
export MOORCHEH_API_KEY=your_moorcheh_key
```
Memory endpoints require a **session token** in the `X-Session-Token` header. Tokens are obtained by activating an agent.
```http theme={null}
X-Session-Token: your_jwt_token
```
## Server-Side Moorcheh API Key
Memanto does not accept a Moorcheh API key from clients. The key is set once on the server and is used for every Moorcheh call Memanto makes:
```bash theme={null}
# Required on the Memanto server
export MOORCHEH_API_KEY=your_moorcheh_key
```
If the key is missing or invalid, Memanto fails fast at startup with `MOORCHEH_API_KEY is not configured` or `MOORCHEH_API_KEY is invalid`.
### Getting a Moorcheh API Key
1. Go to [https://console.moorcheh.ai/api-keys](https://console.moorcheh.ai/api-keys)
2. Create a new API key
3. Configure it on the Memanto server (env var, secrets manager, etc.)
## Session Token Authentication
### When Session Tokens Are Required
Memory operations require an `X-Session-Token` header obtained from agent activation:
* `POST /api/v2/agents/{agent_id}/remember`
* `POST /api/v2/agents/{agent_id}/batch-remember`
* `PATCH /api/v2/agents/{agent_id}/memories/{memory_id}`
* `POST /api/v2/agents/{agent_id}/remember/extract`
* `POST /api/v2/agents/{agent_id}/upload-file`
* `DELETE /api/v2/agents/{agent_id}/memories/{memory_id}`
* `POST /api/v2/agents/{agent_id}/recall`
* `POST /api/v2/agents/{agent_id}/recall/as-of`
* `POST /api/v2/agents/{agent_id}/recall/changed-since`
* `POST /api/v2/agents/{agent_id}/recall/recent`
* `POST /api/v2/agents/{agent_id}/answer`
* `POST /api/v2/agents/{agent_id}/daily-summary`
* `POST /api/v2/agents/{agent_id}/conflicts/generate`
* `GET /api/v2/agents/{agent_id}/conflicts`
* `POST /api/v2/agents/{agent_id}/conflicts/resolve`
* `POST /api/v2/agents/{agent_id}/deactivate`
The session must match `agent_id` in the path; otherwise the request is rejected.
### Cookie-Based Authentication (Browser / Web UI Clients)
As an alternative to the `X-Session-Token` header, [Activate Agent](/api-reference/sessions/activate-agent) also sets an `HttpOnly`, `SameSite=Strict` cookie named `memanto_session_token`. `get_current_session` accepts **either** the header **or** the cookie — browser clients (like the built-in Web UI) never need to read the token out of JavaScript.
* The cookie is set on `POST /api/v2/agents/{agent_id}/activate` and cleared on `POST /api/v2/agents/{agent_id}/deactivate`.
* The cookie's `Secure` attribute is set **dynamically** from the actual request scheme (`Secure` when the request arrived over HTTPS, omitted over plain HTTP). Memanto binds `0.0.0.0` with no built-in TLS by default, so a hardcoded `Secure` flag would silently stop browsers from ever sending the cookie back in that default deployment — put Memanto behind an HTTPS-terminating proxy in production to get `Secure` cookies.
* If a near-expiry session is auto-renewed mid-request, the server transparently re-sets the cookie with the new token so cookie-authenticated clients don't go stale.
* API clients that use the `X-Session-Token` header (CLI, SDKs, direct API integrations) are unaffected — the cookie is purely additive for browser-based callers.
### Management Endpoint Authentication (Agent Lifecycle)
Agent-lifecycle endpoints don't take a session token (there's no session yet), but as of `v0.2.7` they **do** require authorization — either a management credential or a loopback client:
* `POST /api/v2/agents` — Create agent
* `GET /api/v2/agents` — List agents
* `GET /api/v2/agents/{agent_id}` — Get agent details
* `DELETE /api/v2/agents/{agent_id}` — Delete agent
* `POST /api/v2/agents/{agent_id}/activate` — Activate (returns the token)
* `POST /api/v2/agents/{agent_id}/deactivate` — Deactivate (also checked here, in addition to the session token above)
* `GET /api/v2/status` — Inspect the active session
Prior to `v0.2.7`, these endpoints only checked that the **server** had a configured `MOORCHEH_API_KEY` — not that the **caller** was authorized. Combined with the default `HOST=0.0.0.0` bind, any network peer could create agents, activate sessions, and obtain session tokens. Upgrade if you're running an older version and Memanto is reachable from outside `localhost`.
Access is granted when **either** of these is true:
1. **The caller presents the management credential**, matched with a constant-time comparison against the configured server credential:
```http theme={null}
Authorization: Bearer
```
or
```http theme={null}
X-Api-Key:
```
The expected credential is `MOORCHEH_API_KEY` on the **cloud** backend, or `MEMANTO_SECRET_KEY` on the **on-prem** backend (see [Session cookie hardening](#cookie-based-authentication-browser-web-ui-clients) for how that same secret is generated when unset).
2. **The request originates from the loopback interface** (`127.0.0.1` / `::1`, including IPv4-mapped IPv6) — so the local desktop CLI and Web UI keep working without attaching a key on every call.
Requests that satisfy neither condition get:
```json 401 - Unauthorized (Management Auth Required) theme={null}
{
"detail": "Unauthorized. Agent management endpoints require either a loopback client or a valid management credential (Authorization: Bearer or X-Api-Key)."
}
```
**Endpoints that remain fully open** (no management credential, no loopback requirement):
* `GET /health`, `GET /ready`, `GET /live` — [Health & Readiness](/api-reference/system/health) probes
### Getting a Session Token
1. Activate an agent (from `localhost`, no management credential needed):
```bash theme={null}
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/activate"
```
From a non-loopback host, attach the management credential:
```bash theme={null}
curl -X POST "https://memanto.example.com/api/v2/agents/my-agent/activate" \
-H "Authorization: Bearer $MOORCHEH_API_KEY"
```
2. Response contains a session token:
```json theme={null}
{
"session_id": "9f733fdb-ebf2-494e-8eb6-fb3320d6020d",
"session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"agent_id": "my-agent",
"namespace": "memanto_agent_my-agent",
"started_at": "2026-05-09T02:40:00Z",
"expires_at": "2026-05-09T08:40:00Z",
"pattern": "support",
"status": "active"
}
```
3. Use the token in subsequent requests:
```http theme={null}
X-Session-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
### Example Request with Session Token
```bash theme={null}
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/remember" \
-H "X-Session-Token: eyJhbGc..." \
-H "Content-Type: application/json" \
-d '{"content": "Hello", "type": "fact"}'
```
### In Python
```python theme={null}
import httpx
base_url = "http://localhost:8000"
# 1. Activate to get a session token
activate_resp = httpx.post(f"{base_url}/api/v2/agents/my-agent/activate")
session_token = activate_resp.json()["session_token"]
# 2. Use the session token for memory operations
headers = {
"X-Session-Token": session_token,
"Content-Type": "application/json",
}
remember_resp = httpx.post(
f"{base_url}/api/v2/agents/my-agent/remember",
headers=headers,
json={"content": "Hello", "type": "fact"},
)
```
## Session Token Details
### Token Format
Session tokens are JWT (JSON Web Tokens):
```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJhZ2VudF9pZCI6Im15LWFnZW50IiwiZXhwaXJlc19hdCI6IjIwMjYtMDUtMDlUMDg6NDA6MDBaIn0.
[signature]
```
### Token Expiration
* **Duration**: configured by the server via `SESSION_DEFAULT_DURATION_HOURS` (typically 6 hours).
* **Auto-renewal**: Memanto auto-renews sessions that are near expiry on the next memory request.
* **Renewal**: activate a new session with `POST /api/v2/agents/{agent_id}/activate`.
### Decode Token (Python)
```python theme={null}
import jwt
token = "eyJhbGc..."
payload = jwt.decode(token, options={"verify_signature": False})
print(f"Agent: {payload['agent_id']}")
print(f"Expires: {payload['expires_at']}")
```
## Common Errors
### Missing Session Token
```json theme={null}
{
"detail": "Missing session token. Use X-Session-Token header."
}
```
**Fix:** Activate the agent and include the returned token in `X-Session-Token`.
### Invalid Session Token
```json theme={null}
{
"detail": {
"error": "InvalidSessionToken",
"message": "Invalid session token: Not enough segments",
"details": {}
}
}
```
**Fix:** Re-activate the agent and use the freshly returned token.
### Session Expired
```json theme={null}
{
"detail": {
"error": "SessionExpired",
"message": "Session has expired",
"details": {}
}
}
```
**Fix:** Activate a new session with `POST /api/v2/agents/{agent_id}/activate`.
### Management Auth Required
```json theme={null}
{
"detail": "Unauthorized. Agent management endpoints require either a loopback client or a valid management credential (Authorization: Bearer or X-Api-Key)."
}
```
**Fix:** Attach `Authorization: Bearer ` or `X-Api-Key: ` (the cloud `MOORCHEH_API_KEY` or the on-prem `MEMANTO_SECRET_KEY`), or call from a loopback client. See [Management Endpoint Authentication](#management-endpoint-authentication-agent-lifecycle).
### Session / Agent Mismatch
If the session token was issued for a different agent than the one in the URL path, the server returns `500` with:
```json theme={null}
{
"detail": {
"error": "InternalServerError",
"message": "An unexpected error occurred",
"details": {
"original_error": "Session is for agent 'other-agent', cannot access 'my-agent'"
}
}
}
```
**Fix:** Activate the correct agent or call the endpoint with the matching `agent_id`.
## Best Practices
### DO
* Store `MOORCHEH_API_KEY` as a server-side secret (env var, Secrets Manager, etc.)
* Keep session tokens in memory on the client (don't persist long-term)
* Rotate the Moorcheh key periodically
* Treat session tokens as sensitive — they grant memory access for an agent
* If Memanto is reachable from outside `localhost`, attach `Authorization: Bearer ` or `X-Api-Key` on agent-lifecycle calls — don't rely on network placement alone
### DON'T
* Commit `MOORCHEH_API_KEY` to source control
* Reuse a session token across different agents
* Log session tokens (or the management credential) to files or telemetry
* Bind Memanto to `0.0.0.0` on an untrusted network without also setting a real `MOORCHEH_API_KEY` / `MEMANTO_SECRET_KEY` — that credential is what gates agent-lifecycle access for non-loopback callers
## Security
### API Key Management
**Development:**
```bash theme={null}
export MOORCHEH_API_KEY=dev_key
```
**Production (AWS Secrets Manager):**
```python theme={null}
import boto3
client = boto3.client("secretsmanager")
secret = client.get_secret_value(SecretId="moorcheh/api-key")
api_key = secret["SecretString"]
```
**Production (Environment):**
```bash theme={null}
# In your deployment platform
MOORCHEH_API_KEY=prod_key
```
### Session Token Security
* Tokens are JWT — treat as sensitive
* Don't log tokens
* Don't expose in client-side code that ships to end users
* Short-lived (configurable, default \~6 hours)
* Unique per activation
## Next Steps
* [Activate Agent](/api-reference/sessions/activate-agent) to obtain a session token
* [Get Current Session](/api-reference/sessions/get-current-session) to inspect the active session
* [Remember](/api-reference/data/remember) to start storing memories
# Batch Remember
Source: https://docs.memanto.ai/api-reference/data/batch-remember
POST /api/v2/agents/{agent_id}/batch-remember
Store up to 100 memories in one request.
## Overview
Submits multiple memories in a single JSON body. Each item uses the same shape as [Remember](/api-reference/data/remember): `content` plus optional `type`, `title`, `confidence`, `tags`, `source`, and `provenance`.
## Authentication
API clients do not send an API key or `Authorization` header.
Session token from [Activate Agent](/api-reference/sessions/activate-agent). Must match `agent_id`.
Must be `application/json`
## Path Parameters
The unique identifier of the agent.
## Body
Non-empty array of memory objects (minimum 1, maximum **100** items per request).
Each array element supports:
* **`content`** (string, required)
* **`type`** (string, optional, default `fact`)
* **`title`** (string, optional)
* **`confidence`** (number, optional, default `0.8`, range `0.0`–`1.0`)
* **`tags`** (array of strings, optional)
* **`source`** (string, optional, default `agent`) — open label for who wrote the memory (`user`, `agent`, or a specific writer like `cursor`/`codex`/`claude_code`), not a fixed enum
* **`provenance`** (string, optional, default `explicit_statement`)
```bash cURL theme={null}
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/batch-remember" \
-H "X-Session-Token: your_session_token" \
-H "Content-Type: application/json" \
-d '{
"memories": [
{
"content": "Alice prefers phone calls.",
"type": "preference"
},
{
"content": "Bob is the primary contact for billing.",
"type": "fact"
}
]
}'
```
```json 200 - OK theme={null}
{
"agent_id": "my-agent",
"session_id": "sess_982287b6a5f5",
"namespace": "memanto_agent_my-agent",
"total_submitted": 2,
"successful": 2,
"failed": 0,
"results": [
{
"id": "0ee05291-4f58-4846-9037-19a2cdc26f6e",
"status": "queued",
"action": "store",
"reason": "MVP direct store"
},
{
"id": "2607a8a4-d62f-4a1c-b368-35ba3153f5f9",
"status": "queued",
"action": "store",
"reason": "MVP direct store"
}
]
}
```
```json 401 - Unauthorized (Missing Token) theme={null}
{
"detail": "Missing session token. Use X-Session-Token header."
}
```
```json 401 - Unauthorized (Expired Token) theme={null}
{
"detail": {
"error": "SessionExpired",
"message": "Session has expired",
"details": {}
}
}
```
```json 422 - Validation Error theme={null}
{
"detail": [
{
"type": "missing",
"loc": ["body", "memories"],
"msg": "Field required",
"input": {}
}
]
}
```
```json 500 - Server Error theme={null}
{
"detail": {
"error": "InternalServerError",
"message": "An unexpected error occurred",
"details": {
"original_error": "Session is for agent 'other-agent', cannot access 'my-agent'"
}
}
}
```
## Next Steps
* [Recall](/api-reference/search/recall) to search the stored memories
* [Generate AI Answer](/api-reference/ai/generate-ai-answer) using the agent's updated context
# Delete Memory
Source: https://docs.memanto.ai/api-reference/data/delete-memory
DELETE /api/v2/agents/{agent_id}/memories/{memory_id}
Delete a single memory from the active agent's namespace.
## Overview
Deletes one memory from the agent's Moorcheh namespace, scoped by the active
session. The session must belong to the agent named in the path.
## Authentication
API clients do not send an API key or `Authorization` header.
Session token from [Activate Agent](/api-reference/sessions/activate-agent). Must match `agent_id`.
## Path Parameters
The unique identifier of the agent.
The ID of the memory to delete.
```bash cURL theme={null}
curl -X DELETE \
"http://localhost:8000/api/v2/agents/my-agent/memories/b7c3cf31-e537-49f1-abc4-c50ac6adeac5" \
-H "X-Session-Token: your_session_token"
```
```json 200 - OK theme={null}
{
"agent_id": "my-agent",
"memory_id": "b7c3cf31-e537-49f1-abc4-c50ac6adeac5",
"namespace": "memanto_agent_my-agent",
"status": "deleted"
}
```
```json 404 - Not Found theme={null}
{
"detail": "Memory 'b7c3cf31-e537-49f1-abc4-c50ac6adeac5' was not found for agent 'my-agent'"
}
```
```json 401 - Unauthorized (Missing Token) theme={null}
{
"detail": "Missing session token. Use X-Session-Token header."
}
```
```json 500 - Server Error theme={null}
{
"detail": {
"error": "InternalServerError",
"message": "An unexpected error occurred",
"details": {
"original_error": "Session is for agent 'other-agent', cannot access 'my-agent'"
}
}
}
```
## Next Steps
* [Recall](/api-reference/search/recall) to find a memory's ID before deleting it
* [Remember](/api-reference/data/remember) to store a new memory
# Edit Memory
Source: https://docs.memanto.ai/api-reference/data/edit-memory
PATCH /api/v2/agents/{agent_id}/memories/{memory_id}
Update fields on an existing memory for the active agent.
## Overview
Updates an existing memory using a delete-and-recreate pattern on Moorcheh. The memory retains its original `id` and `created_at` timestamp, but updates its `updated_at` timestamp. You must provide at least one field to update.
## Authentication
API clients do not send an API key or `Authorization` header.
Session token from [Activate Agent](/api-reference/sessions/activate-agent). Must match `agent_id`.
## Path Parameters
The unique identifier of the agent.
The ID of the memory to update.
## Body
New memory title. Max 100 characters.
New memory content. Max 10,000 characters. Must be a non-empty string if provided.
New memory type (e.g., `fact`, `preference`, `decision`, etc.).
New confidence score between 0.0 and 1.0.
List of strings representing the new tags.
New memory source string.
```bash cURL theme={null}
curl -X PATCH \
"http://localhost:8000/api/v2/agents/my-agent/memories/b7c3cf31-e537-49f1-abc4-c50ac6adeac5" \
-H "X-Session-Token: your_session_token" \
-H "Content-Type: application/json" \
-d '{
"content": "User prefers light mode (updated)",
"confidence": 0.99
}'
```
```json 200 - OK theme={null}
{
"agent_id": "my-agent",
"session_id": "sess_abc123",
"namespace": "memanto_agent_my-agent",
"memory_id": "b7c3cf31-e537-49f1-abc4-c50ac6adeac5",
"status": "updated",
"action": "updated",
"updated_fields": [
"content",
"confidence"
]
}
```
```json 400 - Bad Request theme={null}
{
"detail": "Provide at least one field to update."
}
```
```json 404 - Not Found theme={null}
{
"detail": "Memory 'b7c3cf31-e537-49f1-abc4-c50ac6adeac5' was not found."
}
```
```json 401 - Unauthorized (Missing Token) theme={null}
{
"detail": "Missing session token. Use X-Session-Token header."
}
```
## Next Steps
* [Recall](/api-reference/search/recall) to find a memory's ID before editing it
* [Delete Memory](/api-reference/data/delete-memory) to remove a memory
# Extract Memories
Source: https://docs.memanto.ai/api-reference/data/extract-memories
POST /api/v2/agents/{agent_id}/remember/extract
Extract typed memory candidates from chat-style conversation turns.
## Overview
Distills a chat-style conversation transcript into typed memory candidates, using the same Moorcheh answer-generation path as the RAG [Answer](/api-reference/ai/generate-ai-answer) endpoint. Candidates are auto-classified into valid memory types, de-duplicated, confidence-scored, and tagged `conversation-extract`. Secrets, API keys, and tokens are explicitly excluded by the extraction prompt.
When `dry_run` is `true`, candidates are returned without writing. Otherwise the candidates are persisted through the same batch memory path used by [Batch Remember](/api-reference/data/batch-remember).
## Authentication
API clients do not send an API key or `Authorization` header.
Session token from [Activate Agent](/api-reference/sessions/activate-agent). Must match `agent_id`.
## Path Parameters
The unique identifier of the agent.
## Body
Array of `{role, content}` conversation message objects. Bounded to 200 messages.
When `true`, returns extracted candidates without storing them. Defaults to `false`.
Maximum number of memories to extract. Bounded to 100.
Optional model override for extraction. If omitted, the server default applies.
```bash cURL theme={null}
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/remember/extract" \
-H "X-Session-Token: your_session_token" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{"role": "user", "content": "I prefer email over phone calls"},
{"role": "assistant", "content": "Got it, I will note that preference."}
],
"dry_run": false,
"max_memories": 20
}'
```
```json 200 - OK (dry_run: true) theme={null}
{
"agent_id": "my-agent",
"session_id": "sess_abc123",
"dry_run": true,
"candidates": [
{
"type": "preference",
"title": "Prefers email communication",
"content": "User prefers email over phone calls",
"confidence": 0.9,
"source": "conversation",
"provenance": "explicit_statement"
}
],
"count": 1
}
```
```json 200 - OK (dry_run: false) theme={null}
{
"agent_id": "my-agent",
"session_id": "sess_abc123",
"dry_run": false,
"candidates": [
{
"type": "preference",
"title": "Prefers email communication",
"content": "User prefers email over phone calls",
"confidence": 0.9,
"source": "conversation",
"provenance": "explicit_statement"
}
],
"total_submitted": 1,
"successful": 1,
"failed": 0,
"results": [
{
"id": "3e681f12-a28c-4d1d-9632-b8dadf1f9d0c",
"status": "stored"
}
]
}
```
```json 401 - Unauthorized (Missing Token) theme={null}
{
"detail": "Missing session token. Use X-Session-Token header."
}
```
## Next Steps
* [Remember](/api-reference/data/remember) to store a single memory directly
* [Batch Remember](/api-reference/data/batch-remember) to store a pre-built list of memories
* [Recall](/api-reference/search/recall) to search stored memories
# Generate Conflict Report
Source: https://docs.memanto.ai/api-reference/data/generate-conflicts
POST /api/v2/agents/{agent_id}/conflicts/generate
Generate the conflict report for an agent/date — the same work the scheduled task performs.
## Overview
Runs the LLM conflict-detection pass over an agent's session memories for a given date and writes the report that [List Conflicts](/api-reference/data/list-conflicts) and [Resolve Conflict](/api-reference/data/resolve-conflicts) read from. This is the same work Memanto's scheduled daily job performs.
## Authentication
API clients do not send an API key or `Authorization` header.
Session token from [Activate Agent](/api-reference/sessions/activate-agent). Must match `agent_id`.
## Path Parameters
The unique identifier of the agent.
## Body
Date string `YYYY-MM-DD`. Defaults to **today (UTC)** on the server when omitted.
```bash cURL theme={null}
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/conflicts/generate" \
-H "X-Session-Token: your_session_token" \
-H "Content-Type: application/json" \
-d '{"date": "2026-05-08"}'
```
```json 200 - OK (conflicts found) theme={null}
{
"agent_id": "my-agent",
"session_id": "sess_abc123",
"date": "2026-05-08",
"conflicts": {
"status": "success",
"json_path": "~/.memanto/conflicts/my-agent_2026-05-08_conflicts.json",
"conflict_count": 2
}
}
```
```json 200 - OK (no sessions for date) theme={null}
{
"agent_id": "my-agent",
"session_id": "sess_abc123",
"date": "2026-05-08",
"conflicts": {
"status": "no_sessions"
}
}
```
```json 400 - Bad Request (Invalid Identifier) theme={null}
{
"detail": "Invalid summary identifier"
}
```
```json 401 - Unauthorized (Missing Token) theme={null}
{
"detail": "Missing session token. Use X-Session-Token header."
}
```
## Next Steps
* [List Conflicts](/api-reference/data/list-conflicts) to fetch the unresolved conflicts from the generated report
* [Resolve Conflict](/api-reference/data/resolve-conflicts) to resolve a specific conflict
* [Generate Daily Summary](/api-reference/ai/generate-daily-summary) to generate the paired daily summary
# List Conflicts
Source: https://docs.memanto.ai/api-reference/data/list-conflicts
GET /api/v2/agents/{agent_id}/conflicts
List unresolved conflicts for an agent from the stored conflict report.
## Overview
Returns conflicts that are **not yet marked resolved** for the given agent and date. Memanto reads the conflict report JSON produced by the conflict-detection workflow (for example after running a daily summary that generates conflicts locally).
If no report exists for that date, the list is empty (`count: 0`).
Each conflict carries an **`index`** — its stable position in the *full* report, including already-resolved rows. Pass that value as `conflict_index` to [Resolve Conflict](/api-reference/data/resolve-conflicts); do **not** use the conflict's position in this filtered response. Because this endpoint omits resolved conflicts, the two numbering schemes diverge after the first resolution, and resolving by filtered position can act on the wrong memory.
## Authentication
API clients do not send an API key or `Authorization` header.
Session token from [Activate Agent](/api-reference/sessions/activate-agent). Must match `agent_id`.
## Path Parameters
The unique identifier of the agent.
## Query Parameters
Report date in `YYYY-MM-DD`. Defaults to **today (UTC)** on the server when omitted.
```bash cURL theme={null}
curl -X GET "http://localhost:8000/api/v2/agents/my-agent/conflicts?date=2026-05-08" \
-H "X-Session-Token: your_session_token"
```
```json 200 - OK theme={null}
{
"agent_id": "my-agent",
"session_id": "sess_982287b6a5f5",
"date": "2026-05-08",
"conflicts": [
{
"index": 2,
"type": "contradiction",
"title": "Database preference changed",
"old_memory_id": "abc-123",
"new_memory_id": "def-456",
"resolved": false
}
],
"count": 1
}
```
```json 401 - Unauthorized (Missing Token) theme={null}
{
"detail": "Missing session token. Use X-Session-Token header."
}
```
```json 500 - Server Error theme={null}
{
"detail": {
"error": "InternalServerError",
"message": "An unexpected error occurred",
"details": {
"original_error": "Session is for agent 'other-agent', cannot access 'my-agent'"
}
}
}
```
## Next Steps
* [Resolve Conflict](/api-reference/data/resolve-conflicts) to apply a resolution for one row in the report
* [Recall](/api-reference/search/recall) to inspect memories directly
# Remember
Source: https://docs.memanto.ai/api-reference/data/remember
POST /api/v2/agents/{agent_id}/remember
Store a single memory for the agent in the active session namespace.
## Overview
Stores one memory in the agent’s Moorcheh namespace scoped by the active session. Fields are sent as **JSON in the request body** only (no query-string parameters).
## Authentication
API clients do not send an API key or `Authorization` header.
Session token from [Activate Agent](/api-reference/sessions/activate-agent). Must match `agent_id`.
Must be `application/json`
## Path Parameters
The unique identifier of the agent.
## Body
Memory text to store (max length enforced by the server; typically up to 10,000 characters).
Memory category (e.g. `fact`, `preference`, `instruction`, `decision`, `goal`, …). Must be one of the supported Memanto memory types.
Optional title (max 100 characters). If omitted, a title is derived from the content.
Confidence between `0.0` and `1.0`.
Optional list of tag strings.
Open label for who wrote the memory — not a fixed enum. Use `user`, `agent`, or a specific writer such as `cursor`, `codex`, or `claude_code` for per-writer attribution. Letters, digits, `.`, `_`, `-` only, max 64 characters.
How the memory was obtained: `explicit_statement`, `inferred`, `observed`, `validated`, `corrected`, `imported`.
```bash cURL theme={null}
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/remember" \
-H "X-Session-Token: your_session_token" \
-H "Content-Type: application/json" \
-d '{
"content": "User prefers email communication",
"type": "preference",
"confidence": 0.9,
"tags": ["communication"],
"source": "agent",
"provenance": "explicit_statement"
}'
```
```json 200 - OK theme={null}
{
"memory_id": "b7c3cf31-e537-49f1-abc4-c50ac6adeac5",
"agent_id": "my-agent",
"session_id": "9f733fdb-ebf2-494e-8eb6-fb3320d6020d",
"namespace": "memanto_agent_my-agent",
"status": "queued",
"confidence": 0.9,
"provenance": "explicit_statement"
}
```
```json 401 - Unauthorized (Missing Token) theme={null}
{
"detail": "Missing session token. Use X-Session-Token header."
}
```
```json 401 - Unauthorized (Invalid or Expired Token) theme={null}
{
"detail": {
"error": "InvalidSessionToken",
"message": "Invalid session token: Not enough segments",
"details": {}
}
}
```
```json 422 - Validation Error (Missing Content) theme={null}
{
"detail": [
{
"type": "missing",
"loc": ["body", "content"],
"msg": "Field required",
"input": {}
}
]
}
```
```json 422 - Validation Error (Bad Confidence) theme={null}
{
"detail": [
{
"type": "less_than_equal",
"loc": ["body", "confidence"],
"msg": "Input should be less than or equal to 1",
"input": 1.5
}
]
}
```
```json 500 - Server Error theme={null}
{
"detail": {
"error": "InternalServerError",
"message": "An unexpected error occurred",
"details": {
"original_error": "Session is for agent 'other-agent', cannot access 'my-agent'"
}
}
}
```
```json 413 - Payload Too Large (Content Too Long) theme={null}
{
"detail": {
"error": "text_too_long",
"message": "Memory content exceeds maximum length of 10000 characters",
"actual_length": 12000,
"max_length": 10000
}
}
```
## Next Steps
* [Recall](/api-reference/search/recall) to search stored memories
* [Generate AI Answer](/api-reference/ai/generate-ai-answer) using the agent's context
# Resolve Conflict
Source: https://docs.memanto.ai/api-reference/data/resolve-conflicts
POST /api/v2/agents/{agent_id}/conflicts/resolve
Resolve one conflict from the conflict report by index.
## Overview
Applies a resolution action to a single conflict identified by its **index** in the full conflict array for that agent and date (same ordering as the JSON report file). This uses the same resolution logic as the Memanto CLI conflict flow (updates Moorcheh memories and marks the row resolved in the report).
## Authentication
API clients do not send an API key or `Authorization` header.
Session token from [Activate Agent](/api-reference/sessions/activate-agent). Must match `agent_id`.
Must be `application/json`
## Path Parameters
The unique identifier of the agent.
## Body
Zero-based index into the **full** conflicts list for that `date` (not only unresolved rows). Use the `index` field returned by [List Conflicts](/api-reference/data/list-conflicts) — not the conflict's position in that filtered response. An already-resolved index is rejected.
One of: `keep_old`, `keep_new`, `keep_both`, `remove_both`, `manual`.
Report date `YYYY-MM-DD`. Defaults to **today (UTC)** on the server when omitted.
Required when `action` is `manual`: replacement memory text (both conflicting memories are removed and this content is stored).
Optional memory type for the manual replacement (defaults follow implementation when omitted).
```bash cURL theme={null}
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/conflicts/resolve" \
-H "X-Session-Token: your_session_token" \
-H "Content-Type: application/json" \
-d '{
"date": "2026-05-08",
"conflict_index": 0,
"action": "keep_new"
}'
```
```bash cURL (manual resolution) theme={null}
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/conflicts/resolve" \
-H "X-Session-Token: your_session_token" \
-H "Content-Type: application/json" \
-d '{
"date": "2026-05-08",
"conflict_index": 0,
"action": "manual",
"manual_content": "We use PostgreSQL for OLTP and MongoDB only for analytics.",
"manual_type": "fact"
}'
```
```json 200 - OK theme={null}
{
"agent_id": "my-agent",
"session_id": "sess_982287b6a5f5",
"date": "2026-05-08",
"action": "keep_new",
"deleted": "abc-123",
"status": "resolved"
}
```
```json 401 - Unauthorized (Missing Token) theme={null}
{
"detail": "Missing session token. Use X-Session-Token header."
}
```
```json 422 - Validation Error theme={null}
{
"detail": [
{
"type": "missing",
"loc": ["body", "conflict_index"],
"msg": "Field required",
"input": {}
}
]
}
```
```json 500 - Server Error theme={null}
{
"detail": {
"error": "InternalServerError",
"message": "An unexpected error occurred",
"details": {
"original_error": "..."
}
}
}
```
Invalid `action`, missing conflict report, out-of-range index, or missing `manual_content` for `manual` typically surface as **500** with details from the underlying resolver.
## Next Steps
* [List Conflicts](/api-reference/data/list-conflicts) to fetch remaining unresolved rows
* [Recall](/api-reference/search/recall) to verify memory state after resolution
# Upload File
Source: https://docs.memanto.ai/api-reference/data/upload-file
POST /api/v2/agents/{agent_id}/upload-file
Upload a document to be processed and stored in the agent's session namespace.
## Overview
Uploads a file into the agent’s Moorcheh namespace for the active session. Moorcheh extracts text and indexes it so content can be discovered via [Recall](/api-reference/search/recall).
Supported extensions: `.pdf`, `.docx`, `.xlsx`, `.json`, `.txt`, `.csv`, `.md`. The route validates the extension before upload. Files are streamed to disk in 1 MB chunks and hard-capped at **5 GB**; anything larger is rejected mid-upload with `413`.
## Authentication
API clients do not send an API key or `Authorization` header.
Session token from [Activate Agent](/api-reference/sessions/activate-agent). Must match `agent_id`.
When using **curl** with `-F`, do **not** set `Content-Type` manually — curl sets `multipart/form-data` with the correct boundary.
## Path Parameters
The unique identifier of the agent.
## Body (multipart)
File field name must be **`file`** (FastAPI `UploadFile` parameter).
```bash cURL theme={null}
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/upload-file" \
-H "X-Session-Token: your_session_token" \
-F "file=@report.pdf"
```
```json 200 - OK theme={null}
{
"agent_id": "my-agent",
"session_id": "session_abc123",
"namespace": "memanto_agent_my-agent",
"file_name": "quarterly-report.pdf",
"file_size": 2516582,
"status": "uploaded",
"message": ""
}
```
```json 400 - Bad Request (Unsupported File Type) theme={null}
{
"detail": "File type '.exe' is not supported. Allowed types: .csv, .docx, .json, .md, .pdf, .txt, .xlsx"
}
```
```json 401 - Unauthorized (Missing Token) theme={null}
{
"detail": "Missing session token. Use X-Session-Token header."
}
```
```json 401 - Unauthorized (Expired Token) theme={null}
{
"detail": {
"error": "SessionExpired",
"message": "Session has expired",
"details": {}
}
}
```
```json 422 - Validation Error (Missing File) theme={null}
{
"detail": [
{
"type": "missing",
"loc": ["body", "file"],
"msg": "Field required",
"input": {}
}
]
}
```
```json 413 - Payload Too Large (File Exceeds 5 GB) theme={null}
{
"detail": {
"error": "file_too_large",
"message": "File exceeds the maximum upload size of 5 GB",
"max_bytes": 5368709120
}
}
```
```json 500 - Server Error theme={null}
{
"detail": {
"error": "InternalServerError",
"message": "An unexpected error occurred",
"details": {
"original_error": "Session is for agent 'other-agent', cannot access 'my-agent'"
}
}
}
```
## Next Steps
* [Recall](/api-reference/search/recall) to search across uploaded content
* [Remember](/api-reference/data/remember) to add structured memories alongside uploads
# Recall
Source: https://docs.memanto.ai/api-reference/search/recall
POST /api/v2/agents/{agent_id}/recall
Run semantic search across an agent's stored memories using natural language.
## Overview
Run semantic search across stored memories. This retrieves contextually relevant memories for the active agent based on semantic similarity to the query. Filters are sent as **JSON in the request body** only (no query-string parameters).
## Authentication
API clients do not send an API key or `Authorization` header.
Session token from [Activate Agent](/api-reference/sessions/activate-agent). Must match `agent_id`.
Must be `application/json`
## Path Parameters
The unique identifier of the agent.
## Body
Natural-language search text matched against the agent's memories (max 1000 characters).
Maximum number of results to return. Range `1`–`100`. If omitted, the server default applies (`RECALL_LIMIT`).
Minimum similarity score in the range `0.0`–`1.0` to filter out less relevant memories.
Optional list of memory type filters (e.g. `["fact", "preference"]`).
## ITS Scoring System
```bash cURL theme={null}
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/recall" \
-H "X-Session-Token: your_session_token" \
-H "Content-Type: application/json" \
-d '{
"query": "user preferences",
"limit": 10,
"min_similarity": 0.2,
"type": ["preference"]
}'
```
```json 200 - OK theme={null}
{
"agent_id": "my-agent",
"session_id": "sess_cf824a95d305",
"query": "user preferences",
"memories": [
{
"id": "3e681f12-a28c-4d1d-9632-b8dadf1f9d0c",
"title": "User Preference Note",
"content": "Prefers email communication",
"text": "[PREFERENCE] User Preference Note\n\nPrefers email communication",
"type": "preference",
"confidence": 0.98,
"status": "active",
"tags": [],
"created_at": "2026-03-26T09:00:00.000000",
"updated_at": "2026-03-26T09:00:00.000000",
"actor_id": "my-agent",
"source": "agent",
"source_ref": null,
"agent_id": "my-agent",
"score": 0.086334,
"provenance": "explicit_statement"
}
],
"count": 1
}
```
```json 401 - Unauthorized (Missing Token) theme={null}
{
"detail": "Missing session token. Use X-Session-Token header."
}
```
```json 401 - Unauthorized (Expired Token) theme={null}
{
"detail": {
"error": "SessionExpired",
"message": "Session has expired",
"details": {}
}
}
```
```json 422 - Validation Error theme={null}
{
"detail": [
{
"type": "missing",
"loc": ["body", "query"],
"msg": "Field required",
"input": {}
}
]
}
```
```json 413 - Payload Too Large (Query Too Long) theme={null}
{
"detail": {
"error": "query_too_long",
"message": "Query exceeds maximum length of 1000 characters",
"actual_length": 1500,
"max_length": 1000
}
}
```
```json 400 - Bad Request (Limit Too Large) theme={null}
{
"detail": {
"error": "k_too_large",
"message": "k exceeds maximum of 100",
"actual_k": 200,
"max_k": 100
}
}
```
```json 500 - Server Error theme={null}
{
"detail": {
"error": "InternalServerError",
"message": "An unexpected error occurred",
"details": {
"original_error": "Session is for agent 'other-agent', cannot access 'my-agent'"
}
}
}
```
## Next Steps
* [Generate AI Answer](/api-reference/ai/generate-ai-answer) to have an LLM synthesize the returned memories into a response
* [Recall Recent](/api-reference/search/recall-recent) to fetch the most recently stored memories
* [Recall As Of](/api-reference/search/recall-as-of) for point-in-time queries
* [Recall Changed Since](/api-reference/search/recall-changed-since) for differential retrieval
# Recall As Of
Source: https://docs.memanto.ai/api-reference/search/recall-as-of
POST /api/v2/agents/{agent_id}/recall/as-of
Point-in-time recall — return memories as they existed at a specified historical timestamp.
## Overview
Returns memories that were valid at the specified point in time, excluding memories created after `as_of` or expired before it. Useful for reconstructing what the agent "knew" at a given moment.
This endpoint lists memories chronologically — there is **no `query` parameter**. For semantic search, use [Recall](/api-reference/search/recall) instead.
## Authentication
API clients do not send an API key or `Authorization` header.
Session token from [Activate Agent](/api-reference/sessions/activate-agent). Must match `agent_id`.
Must be `application/json`
## Path Parameters
The unique identifier of the agent.
## Body
Point-in-time boundary. Accepts `YYYY-MM-DD` (interpreted as **end of day** UTC) or a full ISO 8601 datetime, e.g. `2026-05-01T14:30:00Z`.
Maximum number of results to return. Range `1`–`100`. If omitted, the server default applies.
Optional list of memory type filters (e.g. `["fact", "decision"]`).
```bash cURL theme={null}
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/recall/as-of" \
-H "X-Session-Token: your_session_token" \
-H "Content-Type: application/json" \
-d '{
"as_of": "2026-05-01T12:00:00Z",
"limit": 10
}'
```
```bash cURL (date-only — interpreted as end of day UTC) theme={null}
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/recall/as-of" \
-H "X-Session-Token: your_session_token" \
-H "Content-Type: application/json" \
-d '{
"as_of": "2026-05-01",
"type": ["fact", "decision"]
}'
```
```json 200 - OK theme={null}
{
"agent_id": "my-agent",
"session_id": "sess_123abc",
"as_of_date": "2026-05-01T12:00:00+00:00",
"memories": [
{
"id": "3e681f12-a28c-4d1d-9632-b8dadf1f9d0c",
"title": "Primary OLTP Database",
"content": "We use PostgreSQL for OLTP workloads.",
"text": "[FACT] Primary OLTP Database\n\nWe use PostgreSQL for OLTP workloads.",
"type": "fact",
"confidence": 0.9,
"status": "active",
"tags": [],
"created_at": "2026-04-28T18:47:46Z",
"updated_at": "2026-04-28T18:47:46Z",
"actor_id": "my-agent",
"source": "agent",
"source_ref": null,
"agent_id": "my-agent",
"score": null,
"provenance": "explicit_statement"
}
],
"count": 1,
"temporal_mode": "as_of"
}
```
```json 401 - Unauthorized (Missing Token) theme={null}
{
"detail": "Missing session token. Use X-Session-Token header."
}
```
```json 422 - Validation Error (Missing as_of) theme={null}
{
"detail": [
{
"type": "missing",
"loc": ["body", "as_of"],
"msg": "Field required",
"input": {}
}
]
}
```
```json 422 - Validation Error (Bad Date) theme={null}
{
"detail": [
{
"type": "value_error",
"loc": ["body", "as_of"],
"msg": "Value error, Invalid value '2026-13-40'. Use YYYY-MM-DD or ISO 8601 datetime.",
"input": "2026-13-40"
}
]
}
```
```json 500 - Server Error theme={null}
{
"detail": {
"error": "InternalServerError",
"message": "An unexpected error occurred",
"details": {
"original_error": "Session is for agent 'other-agent', cannot access 'my-agent'"
}
}
}
```
## Next Steps
* [Recall Changed Since](/api-reference/search/recall-changed-since) to find modifications after a specific date
* [Recall](/api-reference/search/recall) for standard semantic search
# Recall Changed Since
Source: https://docs.memanto.ai/api-reference/search/recall-changed-since
POST /api/v2/agents/{agent_id}/recall/changed-since
Differential retrieval — return memories created or updated after a specified timestamp.
## Overview
Returns memories that were created or updated after the specified `since` timestamp — useful for "what changed since last week?" workflows.
This endpoint lists memories chronologically (sorted by `updated_at` descending) — there is **no `query` parameter**. For semantic search, use [Recall](/api-reference/search/recall) instead.
## Authentication
API clients do not send an API key or `Authorization` header.
Session token from [Activate Agent](/api-reference/sessions/activate-agent). Must match `agent_id`.
Must be `application/json`
## Path Parameters
The unique identifier of the agent.
## Body
Start of the change window. Accepts `YYYY-MM-DD` (interpreted as **start of day** UTC) or a full ISO 8601 datetime, e.g. `2026-05-01T00:00:00Z`.
Maximum number of results to return. Range `1`–`100`. If omitted, the server default applies.
Optional list of memory type filters (e.g. `["fact", "decision"]`).
```bash cURL theme={null}
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/recall/changed-since" \
-H "X-Session-Token: your_session_token" \
-H "Content-Type: application/json" \
-d '{
"since": "2026-05-01",
"limit": 20,
"type": ["fact", "decision"]
}'
```
```bash cURL (date-only — interpreted as start of day UTC) theme={null}
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/recall/changed-since" \
-H "X-Session-Token: your_session_token" \
-H "Content-Type: application/json" \
-d '{
"since": "2026-05-01T00:00:00Z"
}'
```
```json 200 - OK theme={null}
{
"agent_id": "my-agent",
"session_id": "sess_123abc",
"since_date": "2026-05-01T00:00:00+00:00",
"memories": [
{
"id": "4f792e13-b39d-5e2e-a743-c9ebef2e0e1d",
"title": "System Upgrade",
"content": "System upgraded to v2.0",
"text": "[FACT] System Upgrade\n\nSystem upgraded to v2.0",
"type": "fact",
"confidence": 0.9,
"status": "active",
"tags": [],
"created_at": "2026-05-04T10:15:30Z",
"updated_at": "2026-05-04T10:15:30Z",
"actor_id": "my-agent",
"source": "agent",
"source_ref": null,
"agent_id": "my-agent",
"score": null,
"provenance": "explicit_statement",
"change_type": "created"
}
],
"count": 1,
"temporal_mode": "changed_since"
}
```
```json 401 - Unauthorized (Expired Token) theme={null}
{
"detail": {
"error": "SessionExpired",
"message": "Session has expired",
"details": {}
}
}
```
```json 422 - Validation Error (Missing since) theme={null}
{
"detail": [
{
"type": "missing",
"loc": ["body", "since"],
"msg": "Field required",
"input": {}
}
]
}
```
```json 500 - Server Error theme={null}
{
"detail": {
"error": "InternalServerError",
"message": "An unexpected error occurred",
"details": {
"original_error": "Session is for agent 'other-agent', cannot access 'my-agent'"
}
}
}
```
## Next Steps
* [Recall As Of](/api-reference/search/recall-as-of) for point-in-time queries
* [Recall Recent](/api-reference/search/recall-recent) to fetch the most recently stored memories
# Recall Recent
Source: https://docs.memanto.ai/api-reference/search/recall-recent
POST /api/v2/agents/{agent_id}/recall/recent
Return the most recently stored memories, sorted newest-first.
## Overview
Returns memories sorted by `created_at` descending (newest first). Useful when you want the latest context without running a semantic query — for example, summarizing the most recent activity for an agent.
There is **no `query` parameter** for this endpoint; results are purely chronological.
## Authentication
API clients do not send an API key or `Authorization` header.
Session token from [Activate Agent](/api-reference/sessions/activate-agent). Must match `agent_id`.
Must be `application/json`
## Path Parameters
The unique identifier of the agent.
## Body
Maximum number of results to return. Range `1`–`100`. If omitted, the server default applies (`RECALL_LIMIT`).
Optional list of memory type filters (e.g. `["fact", "preference"]`).
```bash cURL theme={null}
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/recall/recent" \
-H "X-Session-Token: your_session_token" \
-H "Content-Type: application/json" \
-d '{
"limit": 10,
"type": ["fact", "decision"]
}'
```
```bash cURL (defaults) theme={null}
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/recall/recent" \
-H "X-Session-Token: your_session_token" \
-H "Content-Type: application/json" \
-d '{}'
```
```json 200 - OK theme={null}
{
"agent_id": "my-agent",
"session_id": "sess_123abc",
"memories": [
{
"id": "3e681f12-a28c-4d1d-9632-b8dadf1f9d0c",
"title": "Latest Customer Feedback",
"content": "Customer prefers async communication on Slack.",
"text": "[PREFERENCE] Latest Customer Feedback\n\nCustomer prefers async communication on Slack.",
"type": "preference",
"confidence": 0.9,
"status": "active",
"tags": [],
"created_at": "2026-05-08T18:47:46Z",
"updated_at": "2026-05-08T18:47:46Z",
"actor_id": "my-agent",
"source": "agent",
"source_ref": null,
"agent_id": "my-agent",
"score": null,
"provenance": "explicit_statement"
}
],
"count": 1,
"temporal_mode": "recent"
}
```
```json 401 - Unauthorized (Expired Token) theme={null}
{
"detail": {
"error": "SessionExpired",
"message": "Session has expired",
"details": {}
}
}
```
```json 400 - Bad Request (Limit Too Large) theme={null}
{
"detail": {
"error": "k_too_large",
"message": "k exceeds maximum of 100",
"actual_k": 200,
"max_k": 100
}
}
```
```json 500 - Server Error theme={null}
{
"detail": {
"error": "InternalServerError",
"message": "An unexpected error occurred",
"details": {
"original_error": "Session is for agent 'other-agent', cannot access 'my-agent'"
}
}
}
```
## Next Steps
* [Recall](/api-reference/search/recall) for semantic search by query
* [Recall As Of](/api-reference/search/recall-as-of) for point-in-time queries
* [Recall Changed Since](/api-reference/search/recall-changed-since) for differential retrieval
# Activate Agent
Source: https://docs.memanto.ai/api-reference/sessions/activate-agent
POST /api/v2/agents/{agent_id}/activate
Activate an agent to start a new session and obtain a session token for memory operations.
## Overview
Starts a new session for the specified agent and returns a JWT **session token** that authorizes subsequent memory operations (`remember`, `recall`, `answer`, etc.). The session is initialized with the server's default duration (typically 6 hours) and tracked in `~/.memanto/sessions/`.
The endpoint takes **no request body**; session duration is controlled by server configuration (`SESSION_DEFAULT_DURATION_HOURS`).
In addition to returning `session_token` in the response body, this endpoint sets an `HttpOnly`, `SameSite=Strict` cookie (`memanto_session_token`) so browser clients can authenticate without reading the token from JavaScript. See [Cookie-Based Authentication](/api-reference/authentication#cookie-based-authentication-browser-web-ui-clients).
## Authentication
`Bearer ` — required unless the request originates from a loopback client. See [Management Endpoint Authentication](/api-reference/authentication#management-endpoint-authentication-agent-lifecycle).
Alternative to `Authorization: Bearer` — same credential.
## Path Parameters
The unique identifier of the agent to activate.
```bash cURL theme={null}
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/activate"
```
```json 200 - OK theme={null}
{
"session_id": "9f733fdb-ebf2-494e-8eb6-fb3320d6020d",
"session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"agent_id": "my-agent",
"namespace": "memanto_agent_my-agent",
"started_at": "2026-05-09T02:40:00.313078Z",
"expires_at": "2026-05-09T08:40:00.313078Z",
"pattern": "support",
"status": "active"
}
```
```json 401 - Unauthorized (Management Auth Required) theme={null}
{
"detail": "Unauthorized. Agent management endpoints require either a loopback client or a valid management credential (Authorization: Bearer or X-Api-Key)."
}
```
```json 404 - Not Found theme={null}
{
"detail": {
"error": "AgentNotFound",
"message": "Agent 'my-agent' not found",
"details": {}
}
}
```
```json 500 - Server Error theme={null}
{
"detail": {
"error": "InternalServerError",
"message": "An unexpected error occurred",
"details": {
"original_error": "..."
}
}
}
```
## Next Steps
After activating an agent, store the returned `session_token` and use it in the `X-Session-Token` header for:
* [Remember](/api-reference/data/remember) to store new memories
* [Recall](/api-reference/search/recall) to search stored memories
* [Generate AI Answer](/api-reference/ai/generate-ai-answer) to synthesize a grounded response
* [Get Current Session](/api-reference/sessions/get-current-session) to inspect the active session
# Deactivate Agent
Source: https://docs.memanto.ai/api-reference/sessions/deactivate-agent
POST /api/v2/agents/{agent_id}/deactivate
End the active session for an agent and return a summary.
## Overview
Terminates the current session for the specified agent and returns a summary including the start/end time, total duration, and number of memories stored during the session. If the session was authenticated via the `memanto_session_token` cookie, this call also clears that cookie.
## Authentication
Session token from [Activate Agent](/api-reference/sessions/activate-agent). Must match `agent_id`.
`Bearer ` — this endpoint additionally requires the management credential (or a loopback client), on top of the session token above. See [Management Endpoint Authentication](/api-reference/authentication#management-endpoint-authentication-agent-lifecycle).
Alternative to `Authorization: Bearer` — same credential.
## Path Parameters
The unique identifier of the agent whose session should be ended.
```bash cURL theme={null}
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/deactivate" \
-H "X-Session-Token: your_session_token"
```
```json 200 - OK theme={null}
{
"session_id": "9f733fdb-ebf2-494e-8eb6-fb3320d6020d",
"agent_id": "my-agent",
"started_at": "2026-05-09T02:40:00.313078Z",
"ended_at": "2026-05-09T03:15:00.000000Z",
"duration_hours": 0.58,
"memories_created": 3,
"summary_memory_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```
```json 401 - Unauthorized (Missing Token) theme={null}
{
"detail": "Missing session token. Use X-Session-Token header."
}
```
```json 401 - Unauthorized (Invalid or Expired Token) theme={null}
{
"detail": {
"error": "InvalidSessionToken",
"message": "Invalid session token: Not enough segments",
"details": {}
}
}
```
```json 401 - Unauthorized (Management Auth Required) theme={null}
{
"detail": "Unauthorized. Agent management endpoints require either a loopback client or a valid management credential (Authorization: Bearer or X-Api-Key)."
}
```
```json 404 - Not Found theme={null}
{
"detail": {
"error": "SessionNotFound",
"message": "Session for agent 'my-agent' not found",
"details": {}
}
}
```
```json 500 - Server Error theme={null}
{
"detail": {
"error": "InternalServerError",
"message": "An unexpected error occurred",
"details": {
"original_error": "Session is for agent 'other-agent', cannot access 'my-agent'"
}
}
}
```
## Next Steps
* [Activate Agent](/api-reference/sessions/activate-agent) to start a new session
* [List Agents](/api-reference/agents/list-agents) to view updated session counters
# Get Current Session
Source: https://docs.memanto.ai/api-reference/sessions/get-current-session
GET /api/v2/status
Inspect the currently active session, including duration, expiration, and remaining time.
## Overview
Returns metadata for the session currently marked active in Memanto's local state — useful to verify session validity before executing memory operations. The endpoint reads the active session marker on the server; **no parameters are required**.
## Authentication
No session token — Memanto resolves the active session from local server state.
`Bearer ` — required unless the request originates from a loopback client. See [Management Endpoint Authentication](/api-reference/authentication#management-endpoint-authentication-agent-lifecycle).
Alternative to `Authorization: Bearer` — same credential.
```bash cURL theme={null}
curl -X GET "http://localhost:8000/api/v2/status"
```
```json 200 - OK theme={null}
{
"session_id": "9f733fdb-ebf2-494e-8eb6-fb3320d6020d",
"agent_id": "my-agent",
"namespace": "memanto_agent_my-agent",
"started_at": "2026-05-09T02:40:00.313078Z",
"expires_at": "2026-05-09T08:40:00.313078Z",
"status": "active",
"time_remaining_seconds": 21573,
"pattern": "support"
}
```
```json 401 - Unauthorized (Management Auth Required) theme={null}
{
"detail": "Unauthorized. Agent management endpoints require either a loopback client or a valid management credential (Authorization: Bearer or X-Api-Key)."
}
```
```json 404 - Not Found (No Active Session) theme={null}
{
"detail": "No active session"
}
```
```json 500 - Server Error theme={null}
{
"detail": {
"error": "InternalServerError",
"message": "An unexpected error occurred",
"details": {
"original_error": "..."
}
}
}
```
## Next Steps
* [Activate Agent](/api-reference/sessions/activate-agent) if no session is active
* [Deactivate Agent](/api-reference/sessions/deactivate-agent) to end the session early
# Health & Readiness
Source: https://docs.memanto.ai/api-reference/system/health
Unauthenticated health, readiness, and liveness probes for monitoring and orchestration.
## Overview
Memanto exposes three unauthenticated probe endpoints at the server root (not under `/api/v2`), intended for load balancers, container orchestrators, and uptime monitoring. None require a Moorcheh API key or session token.
## Authentication
None. All three endpoints are open.
## `GET /health`
Reports whether the server can reach Moorcheh (cloud API or on-prem server, depending on the active backend).
```bash cURL theme={null}
curl -X GET "http://localhost:8000/health"
```
```json 200 - Healthy theme={null}
{
"status": "healthy",
"service": "MEMANTO",
"version": "0.2.4",
"moorcheh_connected": true
}
```
```json 200 - Unhealthy (Moorcheh unreachable) theme={null}
{
"status": "unhealthy",
"service": "MEMANTO",
"version": "0.2.4",
"moorcheh_connected": false
}
```
`moorcheh_connected: false` does not change the HTTP status code — it still returns `200`. Check the `status` and `moorcheh_connected` fields in the body, not the status code.
## `GET /ready`
Kubernetes readiness probe. Always returns `200` once the process has started; use this to gate traffic routing.
```bash cURL theme={null}
curl -X GET "http://localhost:8000/ready"
```
```json 200 - OK theme={null}
{
"status": "ready"
}
```
## `GET /live`
Kubernetes liveness probe. Always returns `200` while the process is running; use this to detect a hung process that needs restarting.
```bash cURL theme={null}
curl -X GET "http://localhost:8000/live"
```
```json 200 - OK theme={null}
{
"status": "alive"
}
```
## Next Steps
* [Kubernetes Deployment](/on-prem/kubernetes) for probe configuration in a K8s manifest
* [Self-Hosting Memanto Server](/on-prem/server-deployment) for Docker/Compose/systemd deployment
# Changelog
Source: https://docs.memanto.ai/changelog
Release notes and version history for Memanto.
# Memanto Changelog
Fixes a bug where resolving a conflict after the first resolution could delete a memory you never selected. Upgrading is strongly recommended if you use conflict resolution via the REST API or Web UI.
### Bug Fixes
#### `resolve_conflict` deleted the wrong memory after the first resolution
* **`list_conflicts` returns only *unresolved* conflicts, while `resolve_conflict` indexed into the *full* report** — the two index spaces agreed only until the first resolution, then desynced. A caller resolving by filtered-list position could delete a memory it never selected, while the conflict the user actually chose stayed unresolved.
* **`list_conflicts` now tags each conflict with its stable `index`** into the full report; the Web UI resolves by that stable index instead of on-screen position; `resolve_conflict` rejects an already-resolved index as defense in depth. See [Resolve Conflict](/api-reference/data/resolve-conflicts).
#### OKF export corrupted multi-tag memories
* **Moorcheh stores `tags` as a comma-separated string**, but the OKF renderer wrapped it in `list(tags)`, splitting the string character-by-character and emitting garbage one-character tags in the frontmatter — every multi-tag memory lost its real tags on export. Now splits-and-strips a string value and passes a list through unchanged.
* **Colliding OKF context filenames are preserved** instead of silently overwritten, and markdown-link parsing is now linear-time (was worst-case quadratic).
#### Daily analysis dates misaligned with UTC storage
* **API, CLI, and Web UI daily-analysis date defaults** are now aligned to the same UTC boundary memories are stored under, fixing off-by-one-day results near midnight depending on local timezone. Reflected in [`memanto daily-summary`](/cli/ai/daily-summary) and the conflict endpoints.
#### Conversation extraction dropped oversized messages
* **A single message exceeding the extraction character budget was dropped entirely**, sending an empty query and producing an API error or garbage results. The first message is now always included (truncated if necessary), separators count toward the budget, and the budget was raised to 120,000 characters — the old cap came from an embedding-search bottleneck that no longer applies now that extraction runs in raw-LLM mode.
#### CLI: `--min-confidence` recall filter restored
* **`memanto recall --min-confidence` had regressed to a no-op**; filtering is restored and positional recall arguments are preserved. It filters on the memory's own stored confidence, distinct from `--min-similarity`, which filters on query match score. See [`memanto recall`](/cli/search/recall).
#### Other fixes
* **FastAPI header metadata leaking into backend API keys** — an unresolved `Header(...)` default object could be forwarded to the Moorcheh SDK as if it were a real API key when the dependency was called directly rather than injected; only a genuine string is accepted now.
* **LangGraph** — fixed a key-collision case in `MemantoStore` and stale per-agent locks left behind after certain operations; legacy key tags are preserved for backward compatibility.
* **Mem0 export** now targets Mem0's v3 API, and pagination validates the `next` field instead of terminating early on a malformed page.
* **Incomplete memory exports are rejected** rather than silently accepted as complete, while still falling back to the last good export when a refresh genuinely fails.
* **Deleting an agent** now cleans up its per-agent lock instead of leaving a stale lock object behind.
### Tests
* **New** `tests/test_conflict_index_desync.py`, plus expanded `tests/test_okf.py`, `tests/test_backend.py`, `tests/test_cli.py`, `tests/test_conversation_memory_extraction.py`, and `tests/test_export_resilience.py` covering every fix above.
### New Features
#### Langfuse integration
* **New `langfuse-memanto` package** — `attach(agent_id=...)` wires into an existing Langfuse setup and turns failing or notable spans into durable Memanto memories live, so lessons from observability data don't have to be re-learned on every run. Rule-based (no LLM calls), runs off the hot path, and never breaks the traced application if a memory write fails. See [Langfuse Integration](/integrations/langfuse).
* **`memanto migrate langfuse`** adds Langfuse as a fourth migration source (alongside Mem0, Letta, Supermemory), with its own discovery step, configurable capture rules, and a sync ledger for incremental runs. See [`memanto migrate`](/cli/migrate/migrate#langfuse-sync).
* **New Langfuse tile in the Web UI's Migrate surface**, for discovering and syncing a Langfuse project without touching the CLI.
* **Live capture and batch migration share the same ledger**, so they write identical memories and never duplicate each other.
### Bug Fixes
#### `memanto-mcp` broken on MCP SDK 2.0
* **The published `memanto-mcp` 0.1.1 declared an unbounded `mcp[cli]>=1.2.0` dependency.** MCP SDK 2.0 removed `mcp.server.fastmcp`, so a fresh install silently resolved to a version the server couldn't import and failed to start. The `mcp` dependency is now pinned below 2.0, released as `memanto-mcp` 0.1.2.
#### Per-client write attribution in MCP
* **MCP-written memories now default `source` to the connected client's identity** (e.g. `cursor`, `codex`, `claude-ai`) instead of a single generic value, falling back to `mcp-agent` when the transport carries no client identity — reusing core's own source validation so the advertised tool schema matches what the write path accepts. Builds on the open `source` label introduced in `v0.2.13`.
#### Other fixes
* **Loopback client misused as a real API key** — internal/loopback UI operations were forwarding an unresolved FastAPI `Header(...)` default to the SDK as if it were a real API key, raising a `TypeError` inside httpx. Only a genuine string is treated as a supplied key now.
* **Version resolution for source-archive installs** — added a `hatch-vcs` fallback version so editable installs and installs from a source archive (e.g. a GitHub ZIP with no `.git` metadata) no longer fail version resolution at install time.
### Tests
* **New** `tests/test_langfuse_{config,discover,export,rules,state,sync}.py` and `integrations/langfuse/tests/{test_handler,test_span_mapper}.py` covering the new integration end-to-end.
* **New** `integrations/mcp/tests/test_packaging.py` guarding the SDK version pin; expanded `integrations/mcp/tests/{test_server,test_tools}.py`.
Fixes a major bug where recalling more than one memory type at once (`type: ["fact", "preference"]`) silently returned zero results. Upgrading is strongly recommended if you use multi-type filters.
### New Features
#### Open `source` label for per-writer attribution
* **`source` is no longer restricted to a fixed enum** — any writer (CLI, MCP, LangGraph, Hermes, CrewAI, conversation-extraction, migration) can now stamp its own identifying label, enabling proper per-writer attribution in recall output instead of everything collapsing into a few generic values. See [Remember](/api-reference/data/remember).
### Bug Fixes
#### Multi-type recall returned nothing
* **Requesting more than one memory type built a query** like `"#memory_type:fact #memory_type:preference"`, which Moorcheh's keyword syntax treats as an AND filter that no single document can satisfy — so multi-type recall silently returned zero results. Fixed to issue one query per type and union the results (now parallelized for latency).
#### Session storage hardening
* **Session/secret files** (which hold live bearer tokens) are now created with `0o700`/`0o600` permissions, symlinks are skipped rather than followed, and writes go through an atomic `O_EXCL` temp-file + `os.replace` pattern instead of writing in place.
* **Session lifecycle locks are now scoped per-agent** (was a single global lock), renewal is serialized against termination, concurrent auto-renewal races are fixed, and external session-marker races are tolerated instead of raising.
* **Windows-specific**: non-blocking lock retry via `msvcrt`, plus handling for additional `OSError` cases during session loading with improved error logging.
* **Sessions are now preserved across interrupted writes** instead of being left corrupted mid-write.
#### Temporal recall correctness
* **`search_as_of` (point-in-time recall)** now correctly recalls memories that were valid at the queried time but have since expired — it previously delegated to a helper that always filtered by *current* wall-clock time.
* **As-of deduplication is now version-aware**: a delete-and-recreate update that briefly exposes both the old and new document with the same id no longer causes the wrong version to win against `created_before`.
* **Date-only `as_of` cutoffs** (e.g. `"2026-06-01"`) are now detected by parsing instead of string shape, fixing rejection of valid ISO-8601 basic format dates; date-only end-of-day bounds now correctly keep the final sub-second of the day instead of dropping it.
* **"Yesterday" temporal recall** is now bounded to that calendar day instead of a rolling 24h window.
* **`expires_at` values stored as `datetime`** (not just ISO strings) are now handled correctly in the as-of expiry path.
#### Multi-line memory title corruption
* **A title containing a newline broke** the `"[TYPE] title\n\ncontent"` document round-trip — the reader's prefix regex couldn't cross the embedded newline, corrupting the parsed title/content split, and each subsequent update compounded another `"[TYPE] "` prefix onto the title until it exceeded the 100-character limit and update started failing permanently. Fixed with a partition-based parser that handles embedded newlines correctly, plus newline normalization at write time.
#### `source_ref` dropped from recall responses
* **`source_ref` is now preserved end-to-end** in recall API responses instead of being silently dropped.
#### MCP integration repairs
* **Fixed `remember`, `list_agents`, `answer`, and `recall` MCP tools** that had regressed; automatic agent creation is now restricted to avoid unexpected agent proliferation; each agent now gets an isolated session client initialized independently (was a shared/serial init path).
#### LangGraph store fixes
* **Repeated `put()` calls to the same key** now correctly upsert (including under concurrent writers) instead of duplicating; removed a local lock-striping scheme and rate-limit fallback that masked real errors.
#### Config / metadata persistence made crash-safe
* **Config writes and local agent-metadata writes are now atomic**; a corrupt local agent metadata file is treated as absent instead of breaking agent listing, and surfaces as a warning in the list payload; `connect` no longer duplicates global instruction paths; export caches are now isolated per backend (cloud vs on-prem) instead of bleeding into each other.
* **`memanto memory sync`** now refreshes the export before syncing to a project (and reports the refreshed count) instead of syncing a stale cache.
#### Claude Code integration: turn anchoring and negation
* **The `Stop` hook now distills only the current conversation turn** instead of re-processing prior turns; turn anchoring and embedding-query bounds hardened, including bounding daily-summary embedding queries.
* **Negated preferences** (e.g. "I don't like Python") are now classified as preferences instead of misfiled as instructions.
#### Other fixes
* **The Web UI's answer panel** now calls the `answer` function directly through the client rather than an intermediate path that had drifted out of sync.
* **VoltAgent `defaultLimit`** is now validated at tool-construction time instead of failing later at call time.
* **On-prem**: adapted to the reorganized package layout shipped in `moorcheh-client` 0.1.5.
### Tests
* **New** `tests/test_as_of_date_only_parsing.py`, `tests/test_as_of_expired_recall.py`, `tests/test_memory_read_multi_type.py`, `tests/test_session_summary_concurrency.py`, `tests/test_postcommit_summary_resilience.py`, `tests/test_title_newline_roundtrip.py`, `tests/test_moorcheh_user_config_compat.py`, `tests/test_daily_summary_query_length.py`, `tests/test_review_followups.py`.
* **Large expansion** of `tests/test_unit.py`, `tests/test_api.py`, and MCP/LangGraph integration test suites covering every fix above.
A large batch of validation and correctness fixes across config management, `memanto connect`/skill install, MCP session isolation, and the LangGraph/Hermes/CrewAI integrations. (`v0.2.11` was superseded by this release and is skipped.)
### Improvements
#### Config validation hardening
* **Server URLs are normalized and ports validated** before being written to config; session/answer config edits are validated against their schema; config setters now guard against malformed config sections instead of crashing.
* **Schedule times are validated** (format + range) before a scheduled job is enabled, both via the CLI and the UI — invalid times now return `400` instead of silently accepting garbage.
#### Moorcheh client cache invalidation
* **`MoorchehClientSingleton` now tracks the config it was built from** (backend, URL, timeout / API key) and rebuilds the cached client when that config changes, instead of serving a stale client after a backend or API-key switch.
#### Avoid storage writes during service initialization
* **`SessionService`/`AgentService`** no longer eagerly create directories or generate a secret key at construction time; both are now lazy (created/generated on first actual use).
#### `memanto connect` / skill install correctness
* **Fixed false-positive shared-skill detection** that could report a skill as installed for one agent when it was actually another agent's install.
* **`connect --disconnect` now preserves unmanaged rule files** (including non-UTF-8 ones) instead of deleting content Memanto didn't add, and cleans up the `SessionStart` hook entry and any permissions Memanto added — not just the instruction file and skill. See [`memanto connect remove`](/cli/connect/remove).
* **Hook-cleanup matching** (used when disconnecting) tightened to avoid removing unrelated hook entries.
#### Agent list namespace counts hardened
* **`list agents` now guards against malformed/missing** `item_count` or `namespace_name` fields in the Moorcheh namespaces response instead of raising.
#### MCP integration: per-agent session isolation
* **Concurrent MCP tool calls for different agent IDs** no longer share one `SdkClient` session — each agent gets its own isolated, cached client, with batch payload validation happening before any readiness side effects and newly created scoped clients only cached once activation actually succeeds.
* **MCP `batch_remember`** now guards against and normalizes malformed item results instead of propagating a bad shape.
#### LangGraph integration fixes
* **Non-string content values are stringified** before being written to the store (previously could raise). `min_confidence` search filtering fixed. Setup now retries after an activation failure instead of getting stuck. Input limits enforced on `remember`.
#### Hermes / CrewAI integration fixes
* **Fixed agent-id truncation collisions in Hermes** (two different agent IDs could truncate to the same internal id). Hermes memory-mirror writes on exit are now non-blocking. CrewAI `remember` now enforces the same input length limits as the core API.
#### Memory validation / parsing hardening
* **Fixed the ambiguity guard being systemically bypassed** by common auxiliary verbs (`is`/`are`/`was`/`were`) matching `STRONG_FACT_PATTERNS`.
* **Memory type is now schema-validated on write** instead of accepted as any string; `SourceType` validation is strict and rate-limiting now fails closed on error instead of open.
* **Tags and source labels are now length-bounded** before storage (applies to both `remember` and memory edits).
* **Fail-fast on malformed storage responses** in the core write path, `memanto migrate`, and MCP `batch_remember`.
#### Timestamp formatting fix
* **Epoch-integer timestamps are now coerced to ISO strings** during memory-read formatting instead of being returned as raw ints, which broke downstream date parsing.
### Tests
* **New** `tests/test_connect_engine.py`, `tests/test_connect_detection.py`, `tests/test_config_manager_setters.py`, `tests/test_schedule_time_validation.py`, `integrations/mcp/tests/test_lifecycle.py`.
* **Large expansion** of `tests/test_api.py`, `tests/test_backend.py`, `tests/test_unit.py`, and per-integration test suites covering every fix above.
### Bug Fixes
#### Agent list crash on mixed timestamps
* **Older agent JSON files stored `created_at`/`last_session` without a timezone** (e.g. `2026-04-29T03:43:11.497100`), while newer records use UTC-aware values (e.g. `2026-07-23T12:47:43.431783Z`). Sorting agents by `created_at` then raised `can't compare offset-naive and offset-aware datetimes`, so `memanto agent list` — and [List Agents](/api-reference/agents/list-agents) — failed entirely once both kinds of record existed on disk.
* **`AgentInfo` now normalizes `created_at` and `last_session`** to UTC-aware via a Pydantic validator on load, and agent listing sorts using the normalized value, so legacy and new metadata coexist safely.
### New Features
#### OKF in the Web UI
* **The Migrate tab now supports importing an OKF bundle** directly from the dashboard, alongside Mem0/Letta/Supermemory. See [OKF Integration](/integrations/okf).
### Bug Fixes
#### Content silently wiped by a false-positive "Tags:" match
* **The wire-format parser split stored memory text on every blank-line-separated chunk** and dropped any chunk starting with `"Tags: "` — so content that legitimately began a paragraph with the literal text `"Tags: "` was silently deleted on read. Parsing now partitions strictly into title/content, and only strips a trailing tags block when the record actually has tags and the last blank-line-delimited segment starts with `"Tags: "`.
#### Temporal filter fail-open
* **A silent-fail path in temporal filtering** could fall through to returning unfiltered results instead of the intended filtered set; fixed to fail closed.
#### Phantom session summaries from failed writes
* **`remember`/`batch-remember` logged a memory to the local session Markdown summary** regardless of whether the underlying Moorcheh write actually succeeded. A new shared `is_successful_write_result()` helper gates summary logging (and batch per-item reporting) on a real success status (`queued`/`success`/`ok`), so a failed write no longer produces a phantom entry in the session log.
* **Batch upload status now fails closed on unrecognized values** — previously any non-empty status from Moorcheh was treated as ambiguous; now only `queued`/`success`/`ok` count as successful and anything else is explicitly marked `"failed"` with the returned status recorded as the error.
#### Timestamp / TTL invariant violations
* **`created_at`/`updated_at` are now normalized to UTC-aware**, clamped to "now" if a caller-supplied value is in the future, and `created_at` is forced to never exceed `updated_at` — closing cases where a bad/aware timestamp from an import or manual edit could produce a memory that looks "created after it was updated" or timestamped in the future.
* **`expires_at` is now always serialized as an ISO string** on the outgoing document instead of relying on the object's default `str()`.
* **Pagination offset and aware-datetime comparison bugs** in session listing fixed as part of the same batch.
#### Tags, metadata, and provenance preservation
* **Consolidates four related fixes**: Hermes agents no longer strip tags on read; the `memanto recall` CLI display now shows tags/provenance correctly; [LangGraph](/integrations/langgraph)'s `MemantoStore` normalizes tags consistently (including a fix for comma-containing tag keys and preserving wildcard tag filters); and a trailing-`"Tags:"` suffix leak in read formatting is fixed.
* **MCP `batch_remember` tool** now normalizes tags before sending.
#### Streaming uploads
* **TypeScript SDK file uploads** are now streamed via a multipart `Readable` generator instead of buffering the whole file in memory.
* **The Claude Code integration's transcript reader** now streams the JSONL transcript line-by-line (bounded deque tail) instead of requiring `readlines()` to materialize the entire file — matters for long-running Claude Code sessions with large transcripts. Read failures during transcript parsing are now logged instead of silently swallowed.
#### Export limit validation
* **`limit_per_type` for `memanto memory export`** is now validated (integer, `1`–`100`) before querying every memory type, instead of failing deep inside the export loop on a bad value.
#### UI date formatting
* **Fixed a date-format bug** in the Memory Explorer.
### Tests
* **New** `tests/test_memory_format.py` covering the tags/content parsing fixes.
* **New** `tests/test_memory_read_confidence.py` additions, plus expanded `tests/test_api.py`, `tests/test_cli.py`, `tests/test_unit.py` for timestamp/TTL invariants, export-limit validation, and write-status gating.
* **New/expanded** test coverage in `integrations/{langgraph,mcp,hermes-agents,claudecode}/tests/`.
### New Features
#### OKF (Open Knowledge Format) export / migrate / sync
* **New `--okf` flag** on `memanto memory export` / `memanto memory sync` writes an [Open Knowledge Format](/integrations/okf) v0.1 bundle instead of the default Markdown output — one file per memory (or a stacked file per type once a type exceeds a size threshold), YAML frontmatter, grouped by memory type.
* **Memanto-only fields** (id, confidence, provenance, source, status) are preserved under a namespaced `x_memanto` frontmatter block so Memanto → OKF → Memanto round-trips are lossless; other OKF consumers ignore the unknown keys.
* **`memanto migrate` gains an OKF source**: `memanto migrate --okf ` imports an OKF bundle back into an agent, alongside the existing Mem0/Letta/Supermemory sources.
#### VoltAgent TypeScript SDK integration
* **New [`@moorcheh-ai/memanto/voltagent`](/integrations/voltagent) integration**, mirroring the existing Vercel AI SDK / Mastra / OpenAI integrations, with its own test suite and dependency wiring.
### Improvements
#### Temporal recall correctness
* **Tag filters are now actually applied** on `recall`, `recall/as-of`, `recall/changed-since`, and `recall/recent` — `tags` was accepted in the request body but silently dropped on the temporal endpoints.
* **Date-only `as-of` queries** (e.g. `2026-06-01`) now include the full day instead of being treated as midnight.
* **Malformed/unparseable timestamps** are now skipped instead of raising during temporal filtering.
* **`changed-since` sorting** no longer breaks on memories with a null `updated_at`.
* **Delete-and-recreate updates** that briefly expose both the old and new document under the same id now resolve to the newest version by timestamp (previously could return the stale duplicate).
* **The candidate pool fetched from Moorcheh is widened** when post-retrieval filters (tags, type, temporal bounds) are active, so filtering no longer starves the result set below the requested limit.
* **Temporal recall limits are validated before hitting the backend** and capped to sane defaults; boolean and non-positive limits are rejected; duplicate recall-limit validation logic was consolidated into one shared helper.
* **Session expiry** now handles timezone-aware expiry timestamps consistently, fixing spurious "session expired" states.
#### LangGraph integration
* **Refined `recall`/`remember` node behavior** with expanded test coverage.
### Tests
* **New** `tests/test_okf.py`, `tests/test_memory_read_as_of.py`, `tests/test_memory_read_temporal_recall.py`, plus expanded coverage across `tests/test_temporal_helpers.py`, `tests/test_api.py`, `tests/test_cli.py`, and `tests/test_unit.py` for every temporal-recall fix above and OKF round-tripping.
This release requires authorization on agent-lifecycle endpoints (create/list/get/delete/activate/deactivate an agent, and `/status`) for the first time. If you call these from outside `localhost`, attach `Authorization: Bearer ` or `X-Api-Key`. See [Management Endpoint Authentication](/api-reference/authentication#management-endpoint-authentication-agent-lifecycle).
### New Features
#### TypeScript SDK framework integrations
* **Three new framework integrations** ship as part of `@moorcheh-ai/memanto`, each behind its own subpath import: [`@moorcheh-ai/memanto/ai-sdk`](/integrations/vercel-ai-sdk) (Vercel AI SDK), [`@moorcheh-ai/memanto/mastra`](/integrations/mastra) (Mastra), and [`@moorcheh-ai/memanto/openai`](/integrations/openai) (OpenAI Node SDK).
* **Each exposes `recallMemory` / `rememberMemory` / `answerMemory` tools** backed by the same `Memanto` client, with a shared `MEMORY_TYPES` export so the model can only emit valid memory types.
* **Framework packages are optional peer dependencies** (`ai`, `@mastra/core`, `openai`, plus `zod`) — install only the ones you use. Node engine requirement bumped to `>=20`.
### Security
#### Management auth required for agent-lifecycle endpoints
* **`POST /agents`, `GET /agents`, `GET /agents/{agent_id}`, `DELETE /agents/{agent_id}`, `POST /agents/{agent_id}/activate`, `POST /agents/{agent_id}/deactivate`, and `GET /status`** previously only checked that the *server* had a configured `MOORCHEH_API_KEY`, not that the *caller* was authorized — with the default `HOST=0.0.0.0` bind, any network peer could create agents, activate sessions, and obtain session tokens.
* **These endpoints now require** either a matching management credential (`Authorization: Bearer ` or `X-Api-Key`) or a loopback client origin.
#### Recall filter-token injection guard
* **`memory_type`, `tag`, `status`, and metadata key/value filters** passed to Moorcheh's keyword query syntax are now validated against a strict token pattern before being interpolated, preventing query-syntax injection via crafted filter values.
#### Unique on-prem upload staging paths
* **Uploaded files on the on-prem backend** are now staged under a UUID-suffixed filename instead of the original name, preventing same-named concurrent uploads from colliding with each other's staged file.
### Improvements
#### On-prem restart and session-end no longer block the event loop
* **`restart_onprem_backend`** previously ran blocking subprocess and HTTP calls directly inside an `async def`, freezing the entire API for the whole restart window (up to several minutes). It's now fully async, and the restart itself runs as a cancellation-safe background task so a client timeout can no longer interleave concurrent restarts against the same on-prem stack.
#### Batch upload status normalization
* **Batch memory writes** now count `"ok"` (in addition to `"queued"`/`"success"`) as a successful per-item status, and count `"failed"` case-insensitively — on-prem batch uploads were previously miscounted as failed despite succeeding.
#### On-prem answer model omission
* **Conversation extraction** now omits `ai_model` when no on-prem LLM is configured, letting the server pick its own default instead of erroring — matching the existing `answer` endpoint behavior.
#### `memanto export` / `memanto memory sync` no longer overwrite a good cache on backend outage
* **`memanto memory export`** previously swallowed every per-type recall failure into an empty list and wrote it unconditionally — during a full backend outage this silently wiped the cached export (and, via `memanto memory sync`, the project's `MEMORY.md`) even though nothing was actually forgotten. It now fails loudly instead when *every* memory type fails to recall (a genuine "no memories of this type" still exports fine).
* **`memanto memory sync`** falls back to the previous export when a refresh fails and a prior export exists, instead of wiping `MEMORY.md`.
#### Memory-update metadata handling
* **`memanto edit`** now preserves extra metadata fields from the existing record (e.g. on-prem `original_id`) that aren't part of the standard memory schema — but explicitly excludes the trust fields removed on 2026-06-29 (`superseded_by`, `supersedes`, `validated_at`, `validation_count`, `contradiction_detected`) so old on-prem records don't resurrect dead schema on update.
### Tests
* **New** `tests/test_memory_read_filter_sanitization.py` and `tests/test_export_resilience.py`, plus expanded `tests/test_backend.py`, `tests/test_unit.py`, and `tests/test_api.py` covering the filter-injection guard, stale-cache export fallback, batch upload status normalization, and trust-field exclusion on update.
* **New** `sdks/typescript/test/integrations/*.test.ts` for the three new SDK integrations.
This release is also about **security hardening pass** on top of `v0.2.5`. Upgrading is strongly recommended.
### Security
#### Session cookie hardening
* **Browser UI sessions** now use an `HttpOnly`, `SameSite=Strict` cookie (`memanto_session_token`) instead of JS-readable token storage, via new `set_session_cookie()` / `clear_session_cookie()` helpers.
* **The cookie's `Secure` flag is now set dynamically** from the actual request scheme (`Secure` only over HTTPS) rather than hardcoded — Memanto defaults to plain HTTP (`0.0.0.0`, no built-in TLS), so a hardcoded `Secure=True` would have silently stopped browsers from ever sending the cookie back in that default deployment. See [Cookie-Based Authentication](/api-reference/authentication#cookie-based-authentication-browser-web-ui-clients).
* **Session renewal now correctly updates the cookie** with the new token on the response — previously a renewed session invalidated the old token without refreshing the cookie, breaking the very next request.
#### Streaming file uploads
* **`upload_file` previously buffered the entire file in memory** before writing to disk; for the documented 5 GB max, concurrent large uploads could trivially exhaust server RAM. Uploads are now streamed to disk in 1 MB chunks with the 5 GB cap enforced **during** the stream (`413` if exceeded), not after full buffering.
* **The chunk write itself is now dispatched via `asyncio.to_thread`** so large uploads no longer block the event loop on synchronous disk I/O.
#### Blank/invalid input rejected across API and CLI
* **`answer`/`recall` queries, conversation-extraction messages, and CLI batch memory content** now reject blank/whitespace-only strings via Pydantic validators instead of silently accepting empty input.
* **`remember` provenance values and `recall` memory-type filters** are now validated against the allowed enum values instead of passed through unchecked.
#### Session cleared when deleting the active agent
* **Deleting an agent now also deletes its persisted session state**, so a saved session token for a deleted agent can no longer be replayed via `X-Session-Token`.
#### TypeScript SDK: URL-encode agent/memory IDs
* **All REST paths built from `agentId`/`memoryId`** now run through `encodeURIComponent()`, preventing malformed requests or path injection when an ID contains special characters.
### Improvements
#### Timestamp normalization for imports
* **Imported memory timestamps** (e.g. from `memanto migrate`) are now preserved as source chronology while being normalized to UTC-naive values for downstream confidence calculations, via a shared `as_utc_naive()` helper (deduplicated out of `memory_write_service` into `temporal_helpers`).
* **Session-listing sort and session comparisons** now normalize datetimes consistently before comparing, avoiding naive/aware `datetime` comparison errors.
#### Error handling
* **`map_error_to_http_exception`** now passes an existing `HTTPException` through unchanged instead of re-wrapping it (e.g. avoids turning a `413` upload-too-large into a generic `500`).
#### TypeScript SDK fixes
* **Fixed `status()` session bootstrap** so a session established outside the constructor is recognized correctly.
* **Fixed a file-size fallback bug** in the upload path.
### Tests
* **Large expansion** of `tests/test_api.py`, `tests/test_cli.py`, and `tests/test_unit.py` covering session-cookie renewal (including the HTTP-vs-HTTPS `Secure` flag behavior), streaming upload limits, blank-input validators, provenance/type validation, session deletion on agent removal, and timestamp normalization.
* **Expanded `sdks/typescript/test/memanto.test.ts`** for agent-ID encoding and session bootstrap behavior.
This release is a **major security hardening pass** across the API, CLI, and Web UI. Upgrading is strongly recommended.
### Security
#### Path traversal via `agent_id` / `session_id` / dates
* **Unsanitized `agent_id` / `session_id` values** were concatenated directly into `pathlib.Path` expressions (e.g. `sessions_dir / f"{agent_id}.json"`), letting a caller escape the storage directory with input like `"../../etc/passwd"`. All filesystem call-sites now run through `validate_safe_id()`.
* **Extended the same guard** to `memory_export_service`, `daily_analysis_service` (including the date parameter used in glob patterns and JSON output paths), and the `--output-path` CLI flag (anchored to a base dir via `relative_to()` containment checks).
#### CORS reflected-origin credential exposure
* **Default `ALLOWED_ORIGINS=["*"]`** combined with `allow_credentials=True` caused Starlette to mirror any request `Origin` back in `Access-Control-Allow-Origin` while also sending `Access-Control-Allow-Credentials: true` — letting any website make credentialed cross-origin requests to the Memanto API.
* **Fixed** to stop mirroring arbitrary origins when credentials are allowed.
#### Sensitive Web UI endpoints gated to localhost-only
* **`POST /api/ui/shutdown`, `GET /api/ui/browse`, `PATCH /api/ui/config`, `PUT /api/ui/api-key`, `POST /api/ui/onprem/restart`**, plus the connections and migrate endpoints, were reachable from any network host with no authentication (remote DoS, arbitrary file listing, config/API-key overwrite).
* **Added a `_require_local()` dependency** that returns 403 for any caller that isn't `127.0.0.1` / `::1` (including IPv4-mapped IPv6 loopback), and blocked glob-pattern injection in the browse endpoint.
#### Unpredictable session secret
* **Removed the hardcoded default JWT signing secret** (`"memanto-default-secret-change-in-production"`).
* When `MEMANTO_SECRET_KEY` isn't set, a per-instance random secret is now generated (`secrets.token_hex(32)`) and persisted locally instead of falling back to a publicly-known constant.
#### Session token lifecycle hardening
* **Deactivated/terminated session tokens** are now rejected outright (401) instead of continuing to authorize writes.
* **Cross-agent session/agent mismatches** now consistently raise `AuthorizationError` → HTTP 403 (was a generic 500) across all session-scoped endpoints.
* **CLI clients** now validate cached sessions before reuse instead of trusting a stale cached token.
* **TypeScript SDK** resets its local session state after `deleteAgent()`.
### Improvements
#### Legacy scope model collapsed to `agent_id`
* **Removed the `scope_type` / `scope_id` pair** (and the underlying `MemoryScope` / namespace-parsing machinery) in favor of a single `agent_id` field; namespaces are now built by one free function (`agent_namespace(agent_id)`).
* **Dead code** from this and prior cleanups moved to `memanto/app/legacy/` (excluded from CI lint/type-check).
* **Removed orphaned "trust" fields** that were never populated by any live write/read path (`superseded_by`, `validation_count`, `contradiction_detected`, etc.) and the unused `ValidationPolicy` class.
#### Confidence filtering bug fix
* **Numeric `min_confidence` filtering** in memory search previously relied on Moorcheh keyword syntax that never matched; it's now applied as a post-filter on the numeric `confidence` field, fixing a zero-threshold edge case that silently returned nothing.
#### Manual conflict resolution validation
* **`ConflictResolveRequest`** now requires non-empty `manual_content` when `action == "manual"`, both on the API and in the UI (blank submissions show a warning toast and refocus the textarea).
#### Timestamp normalization
* **Parsed ISO timestamps** are now consistently normalized to UTC, whether the input has an explicit offset or is naive.
#### CLI: honor custom title for short memories
* **`memanto remember`** no longer overrides an explicit `--title` with an auto-truncated content snippet when the memory content is short.
#### Memory deletion response handling
* **Tightened success/failure detection** for memory deletion and update-then-delete flows so partial or malformed backend responses aren't reported as success.
#### TypeScript SDK & CI
* **Updated dependencies**, CI workflow permissions, regenerated `openapi.json`, and added an npm publishing workflow (`.github/workflows/publish.yml`).
### Tests
* **New** `tests/test_cors_fix.py`, `tests/test_output_path_traversal.py`, `tests/test_ui_auth.py`, `tests/test_remaining_ui_auth.py` covering the CORS, path-traversal, and localhost-gating fixes.
* **New** `tests/test_memory_read_confidence.py` and `tests/test_temporal_helpers.py`.
* **Expanded** `tests/test_api.py`, `tests/test_cli.py`, `tests/test_unit.py` for session-secret generation, inactive-token rejection, and deletion handling.
### New Features
#### TypeScript SDK (`sdks/typescript/`)
* **New `@moorcheh-ai/memanto` npm package** — a fully-typed client generated from the API's OpenAPI spec (`openapi-ts`), covering agents, sessions, remember, recall, answer, upload, and the extract/edit endpoints.
* **Lifecycle helpers** (`src/lifecycle.ts`) for session start/stop memory flows, plus a `doctor` command (`src/doctor.ts`) for config/connectivity checks.
* **All recently-added API features** exposed as first-class SDK methods.
* **CI workflow** `.github/workflows/sdk-typescript.yml` builds, tests (Vitest), and publishes the package; full test suite (`memanto.test.ts`, `lifecycle.test.ts`, `doctor.test.ts`).
* See the [TypeScript SDK reference](/sdk/typescript) for the full method list.
#### `memanto edit` command and PATCH endpoint
* **New `PATCH /{agent_id}/memories/{memory_id}` endpoint** with `MemoryEditRequest` for partial in-place updates.
* **CLI `memanto edit `** with `--title`, `--content`, `--type`, `--confidence`, `--tags`, `--source` options (at least one required).
* **Field validation** on both the API and direct-client paths: non-empty content with length limits, confidence range 0.0–1.0, and valid memory-type membership — matching the create-endpoint contract.
* See [`memanto edit`](/cli/data/edit) and [Edit Memory](/api-reference/data/edit-memory).
#### v2 memory route response models
* **Explicit Pydantic `response_model` schemas** added to the v2 memory routes, giving typed/validated responses and accurate OpenAPI documentation (which in turn feeds the TypeScript SDK codegen).
### Improvements
#### Local metadata logging
* **Session service** now logs memory metadata locally alongside the memory write, keeping the local session summary in sync with stored memories.
### Security
#### Cross-agent authorization returns 403
* **All 12 agent-scoped endpoints** now return HTTP 403 (not 500) when a session's `agent_id` doesn't match the URL's `agent_id`, correctly signaling an authorization failure instead of a server error.
#### Upload path-traversal fixed (CWE-22)
* **Uploaded filenames** are stripped to their basename (`Path.name`) with a defense-in-depth realpath check, preventing a crafted filename (e.g. `../../../etc/cron.d/backdoor.txt`) from escaping the temp directory.
#### Secrets removed from UI config endpoint
* **`GET /api/ui/config`** no longer returns the plaintext Moorcheh API key or session JWT; only safe metadata (`api_key_configured`, `api_key_preview`) remains, closing an unauthenticated secret-disclosure path.
### Tests
* **Expanded `tests/test_api.py` and `tests/test_cli.py`** for the edit endpoint, v2 response models, the 403 scope guard, and filename sanitization.
* **New TypeScript test suites** under `sdks/typescript/test/`.
### New Features
#### Conversation memory extraction
* **New `POST /{agent_id}/remember/extract` endpoint** that distills chat-style conversation turns into typed memory candidates, using the same Moorcheh answer-generation path as the RAG `answer` endpoint.
* **Candidates are auto-classified** into valid memory types, de-duplicated, confidence-scored, and tagged `conversation-extract`; secrets, API keys, and tokens are explicitly excluded by the extraction prompt.
* **`dry_run`** returns candidates without persisting; otherwise they're written through the standard `batch_remember` path and logged to the session summary.
* **New `ExtractMemoriesRequest` / `ConversationMessage` models** with bounded limits (≤200 messages, ≤100 memories, 12k-char cap).
* **CLI `memanto remember --from-conversation `** reads a JSON message array from a file or stdin, with `--dry-run`, `--max-memories`, and `--ai-model` flags, and renders each extracted candidate as a panel.
* **SDK and direct clients** gain `extract_memories_from_conversation()`.
### Improvements
#### Provenance metadata in recall
* **`recall` output now displays `Source`, `Ref`, and `Provenance`** for each memory (in addition to tags), unifying file-upload source names and origin (user / agent / tool) into one consistent block.
* **MCP `MemoryHit` model extended** with `status`, `source`, `source_ref`, and `provenance` fields so MCP clients receive full memory metadata.
* **Web UI memory cards** surface the same source / provenance metadata.
### Tests
* **New `tests/test_conversation_memory_extraction.py`** covering extraction, JSON parsing / normalization, validation limits, and dry-run behavior.
* **Expanded `tests/test_api.py` and `tests/test_cli.py`** for the extract endpoint and `--from-conversation` CLI flow.
### New Features
#### `memanto migrate` command suite
* **Replaces the old `analyze` command** with a full migration workflow: export a provider's data (Mem0, Letta, Supermemory), map each source row onto Memanto memory types (auto-classified via the rule-based parser), bulk-write via `batch_remember` (100 items/request), and optionally generate a storage/token/latency savings report — all in one command.
* **Provider metadata** (scope IDs, confidence scores, hashes) is preserved in a bounded `[Supporting data]` footer so nothing is lost; original `created_at` / `source` / `source_ref` map naturally onto the schema.
* **`--dry-run`** previews the mapping (types, confidence, tags) without writing. **`--report`** generates the Markdown comparison on real runs. Outputs live in `~/.memanto/migrate///` (separate from legacy `analyze/` artifacts).
* **Works on both cloud and on-prem backends**; on-prem `batch_remember` respects the same chunking.
#### `memanto forget` command and REST endpoint
* **New `DELETE /{agent_id}/memories/{memory_id}` endpoint** for single-memory deletion. Checks session scope (the session must own the agent) and removes the memory from Moorcheh.
* **CLI `memanto forget `** for quick terminal deletion.
* **UI Delete button** on each memory card in the Memory Explorer.
### Improvements
#### On-prem backend enhancements
* **Session namespace creation** now reuses an existing namespace on-prem instead of erroring when the namespace already exists (idempotent namespace setup).
* **On-prem `forget` error messages** are now clear and actionable (differentiate "memory not found" from "namespace issue").
* **On-prem threshold boundary checks** fixed (no off-by-one on min-similarity validation).
#### Mapper robustness
* **Mappers now extract all available info** from source exports, including less-common fields like interaction hashes, scope IDs, and custom metadata, preserving them in the `[Supporting data]` footer for compliance and audit trails.
#### Migrate + on-prem API key handling
* **The migrate command** correctly propagates the API key dependency for the on-prem backend (no double-init of the backend client).
### Tests
* **New `tests/test_cli.py`** coverage for the `migrate` and `forget` commands (dry-run, report generation, single-memory delete flow).
* **New `tests/test_unit.py`** coverage for mappers (all three providers) and session namespace idempotency.
* **Integration tests** expanded across CrewAI and LangGraph tooling.
### New Features
#### On-prem Moorcheh backend
* **New `MEMANTO_BACKEND` setting** (`cloud` | `on-prem`) routes every call through a backend-aware dispatcher that exposes the same `namespaces` / `documents` / `similarity_search` / `answer` / `files` / `vectors` shape regardless of target — service code never branches.
* **First-run wizard** now asks **Cloud vs On-Prem**; on-prem path installs `moorcheh-client>=0.1.3`, prompts for embedding + LLM provider (`ollama` / `openai` / `cohere`), persists choices to `~/.memanto/on-prem/state.json`, writes the full LLM block to `~/.moorcheh/config.json` before `moorcheh up`, then pulls Ollama models into the container.
* **On-prem data lives under `~/.memanto/on-prem/`** (sessions, agents, summaries) so cloud and on-prem never share local state; switching backends clears the active session.
* **New `memanto config backend [cloud|on-prem]` CLI command** for runtime switching, plus `Backend`, `MOORCHEH_ONPREM_URL` (default `http://localhost:8080`) and `MOORCHEH_ONPREM_TIMEOUT` (default `300`) rows in `memanto config show`.
* **Health check, startup validation, and the agent delete flow** are all backend-aware.
#### `memanto detect-conflicts` + scheduled job split
* **Conflict detection split out of daily-summary** into its own command, `POST /{agent_id}/conflicts/generate` REST endpoint, and `DirectClient.generate_conflict_report()` method.
* **New hidden `memanto schedule _run` entrypoint** executes daily-summary + detect-conflicts back-to-back; OS scheduler now points at it. On-prem backend short-circuits with a clear error (scheduled job depends on cloud-only LLM Answer).
* **`daily_summary_service.py` renamed** → `daily_analysis_service.py`.
#### UI: Connect tab, memory timeline, daily summary, file pagination
* **Connect tab** installs/removes Memanto skills into any registered agent (Claude Code, Cursor, etc.) via the underlying `install_agent` / `remove_agent` engine, with a `connections.json` registry tracking project-local vs global installs.
* **Memory History page** with a vertical timeline of every change (created, updated, conflict resolved) per memory.
* **Daily summary + Unreviewed conflicts widget** surfaced on the dashboard (Daily Summary tab renders the generated MD and shows days with pending conflict review).
* **Answer panel is backend-aware** — on-prem shows provider/model/api-key only (no cloud-only knobs) and writes to `~/.moorcheh/config.json` without polluting the shared cloud yaml.
* **Memory Explorer** now use cursor pagination through `documents.fetch_text_data` (`next_token` / `has_more`) instead of being capped at 100 items per namespace.
### Improvements
#### Backend-aware `recall_*` REST endpoints
* **`recall_as_of`, `recall_changed_since`, `recall_recent`** and the underlying `MemoryReadService` methods now treat `limit=None` as "fetch all" — the `CostGuard.validate_k_limit` cap is only applied when a limit is explicitly set.
* **`answer.generate`** calls route through `get_active_llm_model()` so the LLM identifier comes from cloud settings on cloud, `on-prem state.json` on on-prem, with the field omitted entirely when on-prem has no LLM configured (server picks its own default).
#### Stale active-session handling
* **`get_active_session()`** now clears the stale active marker and returns `None` when the session has expired, instead of returning an expired `Session`.
* **All datetimes** flow through a single `utc_now()` helper; Pydantic v1 `Config.json_encoders` blocks removed from session models.
#### Connect engine ↔ registry sync
* **`install_agent` / `remove_agent`** now sync their results into `~/.memanto/connections.json` so the UI's Connections page reflects what the CLI did and vice versa.
### Tests
* **New `tests/test_backend.py`** covering cloud/on-prem dispatcher behavior and `get_active_llm_model` fallbacks.
* **New `tests/test_analyze.py`** covering the Mem0/Letta/Supermemory export + compare + report flow end-to-end with mocked provider responses.
* **`tests/test_cli.py` and `tests/test_unit.py`** expanded to cover the new `detect-conflicts` / `schedule _run` paths.
### New Features
#### Recall similarity threshold
* **New `recall.min_similarity` setting** (0.0–1.0) in CLI config with validation; default `0.0`.
* **REST `POST /memories/recall`** and SDK/Direct `recall()` resolve `min_similarity` from the request, then fall back to the config value, then to unset.
* **CLI flag renamed** `--min-confidence` → `--min-similarity` on `memanto recall`.
* **`memanto config show`** surfaces the new `Min Similarity` row.
#### Agents page in the Web UI
* **New sidebar entry** listing every registered agent with status, pattern, memory and session counts; activate/deactivate from the table.
* **`GET /api/v2/agents`** and **`GET /api/v2/agents/{agent_id}`** now populate `memory_count` from the **live Moorcheh namespace document count** instead of the stale local metadata value.
#### File upload in the Playground
* **New `Upload File` tab** accepts `.pdf`, `.docx`, `.xlsx`, `.json`, `.txt`, `.csv`, `.md` (max 5 GB) and ingests into the active agent's namespace, with client-side size/extension validation.
#### Fuzzy fallback for auto memory-type parsing
* **When deterministic rules abstain**, a `rapidfuzz`-backed pass scans tokens against a curated list of long, distinctive keywords per type and picks the best match above `FUZZY_SCORE_CUTOFF = 88.0` — recovering obvious misspellings like *"decded"* → `decision`, *"crahsed"* / *"tracebck"* → `error`.
* **New runtime dependency:** `rapidfuzz>=3.0.0`.
#### Smart-parse config switch
* **New `memanto.cli.smart_parse` setting** in `config.yaml` propagates to the `AUTO_PARSE_ENABLED` env var on startup, letting users toggle auto-parsing without editing code.
### Improvements
#### CrewAI tool schema
* **`MemantoRecallTool`** now exposes `min_similarity` (0.0–1.0) to the LLM, raises the default `limit` from `5` to `10`, and enforces `ge=1, le=100` via Pydantic instead of a hardcoded `min(limit, 20)` clamp.
#### UI timestamps & filters
* **`fmtDate`** appends `Z` to naive UTC timestamps so the browser converts them to the user's locale instead of treating them as local time.
* **Memory Explorer** gains an `All Sources` filter dropdown; navigation helper `goToPage()` added; favicon shipped.
#### `memanto connect` agent templates rewritten
* **Reframed as an "active memory companion"** with five non-negotiable rules (read `MEMORY.md`, search before guessing, store proactively, always pass `--type/--confidence/--provenance/--source`, never keep mental scratchpads).
* **Adds an operations table** (`recall` vs `answer` vs `remember`), worked `memanto remember` examples per type, full memory-type/provenance/confidence references, and the new temporal flags (`--recent`, `--as-of`, `--changed-since`).
* **Cursor MDC rules file** mirrors the same content under `alwaysApply: true`.
### Tests
* **New fuzzy-fallback cases** in `tests/test_memory_parsing.py` (typo'd `decision`/`error` detection; confirms no false-fire on unrelated text).
* **`tests/conftest.py`** resets `settings.AUTO_PARSE_ENABLED = True` before every test so local `smart_parse` config can't leak into the suite.
### New Features
#### Configurable rule-based memory parsing
* **`MemoryParsingService`** (`memory_parsing_service.py`) auto-detects a memory's type at ingestion using score-based classification with priority tie-breaking across all 13 supported types — no more blind default to `fact`.
* **`MemoryRecord.type` is now optional** (`None`); the parser assigns the type when the caller omits it.
* **New `AUTO_PARSE_ENABLED` setting** (default `True`).
* **`remember` and `batch-remember`** run the parser when `type` is omitted and return the resolved `type` in the response.
* **CLI** — `memanto remember` no longer forces `--type fact`; it displays the parsed type instead.
#### MCP server integration
* **The MCP server integration is now available** — it exposes Memanto memory operations to any MCP client. Install it with:
```bash theme={null}
pip install memanto-mcp
```
* See the [Integrations](/integrations/overview) section for setup details.
#### Hermes Agents integration
* **The Hermes Agents integration is now available** — a `hermes_memanto` provider for Hermes Agents. Install it with:
```bash theme={null}
pip install hermes-memanto
```
* See the [Integrations](/integrations/overview) section for setup details.
### Improvements
#### Unified content-length cap across layers
* **SDK/Direct clients** now use `InputLimits.MAX_TEXT_LENGTH` instead of a hardcoded `500`, aligning the cap with the REST/Pydantic models (10,000 chars).
* **Removed** the unused `MAX_MEMORY_SIZE` / `MAX_TITLE_SIZE` settings.
#### Chronological `recall --recent`
* **New `recall_recent()`** on `SdkClient` and `DirectClient` returns the most recently stored memories (newest first).
* **New `memanto recall --recent` flag** — lists recent memories directly, no search query required (mutually exclusive with `--as-of` / `--changed-since`).
#### Unified `kiosk_mode` and `threshold` defaults
* **`kiosk_mode` and `threshold` defaults** now resolve from `config.yaml`.
* **`threshold`** is only applied when `kiosk_mode` is on; the kiosk-mode fallback threshold is unified to `0.15` across REST and config defaults.
#### CrewAI integration
* **Install the CrewAI integration** with:
```bash theme={null}
pip install crewai-memanto
```
* **LLM tool schemas** now enumerate all 13 memory types with definitions to guide classification.
* See the [Integrations](/integrations/crewai) section for setup details.
#### Docker
* **The Docker image can now be pulled directly:**
```bash theme={null}
docker pull moorcheh/memanto:latest
```
This release contains breaking changes to the temporal recall endpoints (`recall_as_of` and `recall_changed_since`). Remove the `query` argument from any existing callers before upgrading.
### Breaking Changes
#### Temporal endpoints no longer accept a query
Temporal endpoints now list every memory that falls inside the requested time window instead of running a similarity-matched subset.
* **API** — `POST /{agent_id}/recall/as-of` and `POST /{agent_id}/recall/changed-since` request bodies dropped the `query` field; response bodies dropped the echoed `query` field.
* **CLI** — `memanto recall --as-of …` / `--changed-since …` now errors if a `QUERY` argument is also supplied. Remove the query to list all memories for that window.
* **Python clients** — `recall_as_of()` on `DirectClient` and `SdkClient` no longer take a `query` argument.
### Improvements
#### Temporal retrieval switched to `documents.fetch_text_data`
* **New `_fetch_all_memories()` helper** (`memory_read_service.py`) paginates through Moorcheh's `fetch_text_data` endpoint across all matched namespaces, applies optional `type`/`tags` filters in-process, deduplicates by ID, and strips summary chunks.
* **Fewer round trips** — `search_as_of` and `recall_changed_since` use the fetch path instead of iterating `similarity_search.query()` per memory type, returning complete result sets within Moorcheh's 100-item-per-namespace fetch limit.
#### CrewAI integration as a publishable package
* **New `memanto-crewai` package (v0.1.0)** in `integrations/crewai/` with `pyproject.toml`, `hatchling` build backend, MIT license, Python `>=3.10`.
* **Public exports** — `MemantoSetup`, `MemantoRememberTool`, `MemantoRecallTool`, `MemantoAnswerTool`, `create_memanto_tools` from `memanto_crewai`.
This release contains breaking changes to memory endpoints, session routes, and authentication. Review all breaking changes below before upgrading.
### Breaking Changes
#### Memory endpoints migrated to POST
* **`recall`, `answer`, `recall/as-of`, `recall/changed-since`** — now accept JSON request bodies instead of query parameters.
* **`memory_types` renamed to `type`** — accepts a list of strings across all recall endpoints and CLI recall commands.
#### Session and auth changes
* **`/session/current` renamed to `/status`** — requires no session token; reads active session from local state.
* **`/session/extend` removed** — session extension is no longer supported.
* **`/sessions` list endpoint removed.**
* **`Authorization` header dropped for API key** — `MOORCHEH_API_KEY` is read from server config only; `Bearer` header auth is removed.
* **`X-Session-Token` is the only auth mechanism** for per-request memory operations.
#### Legacy routes removed
* **`/api/v1/namespaces`, `/api/v1/memory`, `/api/v2/context`** — moved to `memanto/app/legacy/`.
### New Features
#### Recall and conflict endpoints
* **`POST /{agent_id}/recall/recent`** — retrieves most recent memories without a query string; replaces `/recall/current`.
* **`GET /{agent_id}/conflicts`** — lists detected memory contradictions.
* **`POST /{agent_id}/conflicts/resolve`** — resolves a flagged contradiction.
* **`DELETE /agents/{agent_id}?delete-backup-too=true`** — optionally wipes the agent's remote Moorcheh namespace on deletion.
#### Startup validation
* **Fail-fast API key check** — server validates `MOORCHEH_API_KEY` on startup and refuses to start if missing or authentication fails.
### Improvements
#### Structured request body models
* **Pydantic models** (`RecallRequest`, `RecallAsOfRequest`, `RecallChangedSinceRequest`, `RecallRecentRequest`) with full field validation and bounds checking.
* **Smart date defaults** — date-only `as_of` defaults to end-of-day; `since` defaults to start-of-day, so full ISO datetimes are not required for daily windows.
#### Auth and session service
* **`get_moorcheh_api_key()`** reads from server config only — no per-request header parsing.
* **`verify_moorcheh_api_key()`** validates once at startup instead of on every request.
* **`extend_session()` removed**; `moorcheh_api_key` parameter removed from `create_session()`, `validate_session()`, and `renew_session()`.
#### Health check
* **`/health`** no longer requires client dependency injection.
* **Status reports `"unhealthy"`** (was `"degraded"`) when Moorcheh is unreachable.
#### CLI
* **`memanto session extend` removed.**
* **"Activation" terminology** replaces "session" across `agent create`, `agent activate`, `agent deactivate`, and `memanto status`.
* **`memanto status` panel renamed** to **Active Agent** (was "Active Session").
### UI Fixes
#### UI shutdown fix
* **Server stability** — fixed an issue where the API server would unexpectedly shut down when refreshing or closing the browser tab. The server now stays alive unless explicitly stopped or running in specific UI-only modes.
### Tests
* Added `tests/test_e2e.py` with end-to-end API coverage.
### Improvements
#### API input validation
* **Content fields** — `remember`, `recall`, `answer`, `recall/as-of`, `recall/current`, and `recall/changed-since` enforce `min_length=1` on query/content fields and `max_length=500` on `title`.
* **Numeric bounds** — `confidence`, `min_similarity`, `threshold`, and `temperature` bounded `[0.0, 1.0]`; `limit` enforced `ge=1`.
* **CostGuard** validators (`validate_text_length`, `validate_query_length`, `validate_k_limit`) applied across all memory read/write endpoints.
#### Session extension guard
* **API** — extending a session with `additional_hours <= 0` now returns HTTP 422.
* **CLI** — `memanto session extend` rejects non-positive `--hours` values before sending the request.
#### Daily summary custom output path
* **`output_path` parameter** added to `generate_summary()` and `generate_daily_summary()`.
* When provided, the summary Markdown file is written to the specified path; parent directories are created automatically.
#### Agent pattern options
* **`memanto agent create --pattern`** help text updated to list only available patterns: `project`, `support`, `tool` (removes unavailable `chat`, `research`, `custom`).
### Dependencies
* **`moorcheh-sdk`** minimum version bumped from `>=0.1.0` to `>=1.3.5`.
### Bug Fixes
#### UI dashboard authentication
* **Root cause** — the masked API key was being used for backend authentication, causing all dashboard data to fail loading after login.
* **Fix** — restored transmission of the full API key in the configuration response so the dashboard can authenticate backend requests properly.
* **Display** — `api_key_preview` remains masked (`........XXXXXX`) in the settings tab; only the backend communication is affected.
**Result:** The Web UI dashboard now correctly initializes session state upon login, resolving the "no data" issue introduced in v0.0.6.
### Tests
* Full test suite: **54 passed**. UI connectivity verified.
### Improvements
#### API key verification
* **First-run setup** — `memanto` now actively verifies the key against Moorcheh before saving; invalid keys are rejected immediately; transient network issues surface as a warning rather than blocking setup.
* **Lighter auth ping** — verification switched from `client.namespaces.list()` to `client.documents.get(...)` against a sentinel namespace. `NamespaceNotFound` is treated as success (key authenticated; namespace simply doesn't exist).
* **Clearer error codes** — auth dependency returns **401** on `AuthenticationError` and **500** on unexpected errors.
#### Server health check
* **`/health`** uses the same documents-based ping, so health reflects real authentication state.
#### Configurable summary model
* **`SUMMARY_MODEL` setting** (default `anthropic.claude-sonnet-4-6`) used for daily summary and conflict reports.
* **`~/.memanto/config.yaml`** now supports `memanto.summary.model`, `memanto.answer.model`, `temperature`, and `answer_limit` — loaded at startup so models can be swapped without code changes.
#### UI security
* **`/api/ui/config`** and the API-key update endpoint now return a masked preview (`••••••••`) instead of the raw key — plaintext key is no longer sent to the browser.
### Tests
* Full test suite: **54 passed**.
### Bug Fixes
#### Web UI authentication after CLI activation
* **Dashboard, Memory Explorer, recall, and analytics views** now load correctly after `memanto agent activate`.
* **"Session may be expired"** and **"Activate an agent via CLI to explore memories"** error states are resolved.
Existing `api_key_preview` and `has_active_session` fields are retained for backward compatibility with older UI surfaces.
### Improvements
#### Simplified first-run setup
* **Single-step onboarding** — `memanto` setup now prompts only for the Moorcheh API key.
* **Removed** the schedule time (`HH:MM`) prompt, related validation, and automatic `ScheduleManager().enable(...)` call from onboarding.
### Improvements
#### Onboarding and documentation
* **README quick start** de-emphasizes `memanto serve` as a prerequisite — users can run `memanto`, create an agent, and try memories without keeping a local API process running.
* **`memanto serve`** documented as optional, for HTTP/REST use only.
* **Agent integration guide** shortens quick start to create → remember → recall, and updates Python examples.
* **Session architecture doc** notes that `memanto agent create` auto-activates in the CLI.
#### CLI output polish
* **`memanto status` / `memanto serve`** use **Local REST API** wording; healthy API shows **online**.
* **Success messages** drop the `OK` prefix across agent create, remember, upload, and daily summary flows.
* **Welcome Quick Start** lists `memanto ui`, reorders commands, and describes `memanto serve` as starting the local REST API.
#### `memanto connect list`
* **Column renamed** to **Agent Name**; rows show agent `name` instead of `display_name`.
### Behavioral Changes
* `memanto agent create` already auto-started a session; docs and Quick Start now consistently reflect this so separate `memanto agent activate` is not shown as a required step.
* Default session/extension examples reference **6 hours** where updated.
### Tests
* Full test suite: **54 passed**.
### Improvements
#### CLI onboarding flow
* **Quick start** now shows `memanto serve` first and guides users to open a new terminal for agent commands.
* **`memanto serve`** prints a clear "next step" hint after startup.
* **`memanto agent create `** now starts a session automatically.
#### Documentation
* Updated `README.md`, `docs/CLI_USER_GUIDE.md`, `docs/CLI_INSTALLATION.md`, `docs/AGENT_INTEGRATION_GUIDE.md`.
### Behavioral Changes
* `memanto agent create` auto-activates a session — separate `memanto agent activate` is usually not required in the quick start flow.
### Tests
* Updated CLI tests for auto-session behavior. Full test suite: **54 passed**.
### Improvements
#### README branding
* **Title updated** to **Memanto - Memory that AI agents love!** to better capture what Memanto delivers to AI agents.
No functional changes in this release. All CLI commands, API endpoints, integrations, and MemantoClaw features remain unchanged from v0.0.1.
### New Features
#### Semantic memory engine
* **Agents** — persistent identity with isolated memory namespaces (e.g. `customer-support-bot`, `dev-assistant`).
* **Sessions** — 6-hour active windows; memories persist forever and remain accessible across all future sessions.
* **13 memory types** — `fact`, `preference`, `decision`, `goal`, `instruction`, `event`, and more, each stored with a confidence score.
* **Zero-indexing semantic search** — memories are available for retrieval the exact millisecond they are written; no indexing delay.
* **State-of-the-art accuracy** — 89.8% on LongMemEval, 87.1% on LoCoMo.
#### Memanto CLI
* **`pip install memanto`** — full `memanto` command-line interface with organized command groups: `agent`, `memory`, `session`, `schedule`, `config`, `connect`, and core utilities.
* **Quickstart workflow:**
```bash theme={null}
memanto # initial API key configuration
memanto agent create my-agent
memanto remember "Project kickoff is Monday" --type event
memanto recall "When is project kickoff?"
```
#### REST API
* **Full v2 HTTP API** for agent lifecycle, session management, memory read/write, recall, and generative answers.
* **Dual authentication** — `Authorization: Bearer ` for all requests; `X-Session-Token: ` for memory operations.
#### Developer integrations
* **13+ AI coding assistants and IDEs** — Claude Code, Cursor, Cline, Windsurf, Continue, GitHub Copilot, OpenCode, Goose, Roo, Antigravity, Augment, Gemini CLI, Codex.
* Connect via `memanto connect ` with project-local or `--global` scope.
#### MemantoClaw
* **Open-source reference stack** combining OpenClaw, NVIDIA OpenShell, and Memanto memory.
* **One-command provisioning** — `memantoclaw onboard` configures inference routing, credentials, and memory bridge automatically.
* **Enhanced security** — stricter seccomp/Landlock policies, credential filtering, immutable gateway config, host-bridge memory architecture.
# memanto agent bootstrap
Source: https://docs.memanto.ai/cli/agents/bootstrap
Generate an intelligence snapshot of an agent's memory.
# memanto agent bootstrap
Generate a richly formatted intelligence snapshot of an agent's memory — useful for onboarding, audits, or reviewing what the agent currently "knows."
```bash theme={null}
memanto agent bootstrap [AGENT_ID] [OPTIONS]
```
**Arguments:**
* `AGENT_ID` - Agent identifier. Optional; defaults to the currently active agent.
**Options:**
* `-o, --output PATH` - Save the snapshot to a JSON file in addition to printing the summary
**Examples:**
Snapshot the active agent:
```bash theme={null}
memanto agent bootstrap
```
Snapshot a specific agent:
```bash theme={null}
memanto agent bootstrap my-agent
```
Save the snapshot to disk:
```bash theme={null}
memanto agent bootstrap my-agent --output snapshot.json
```
**Output:**
The command prints an "Agent Bootstrap — Intelligence Snapshot" panel including the agent's pattern, description, namespace, creation date, and total stored memory count, followed by sampled memories grouped by type.
When `--output` is provided, the same data is written as JSON for downstream tooling.
**Notes:**
* If no agent is active and no `AGENT_ID` is provided, the command exits with an error and suggests activating one first
* The snapshot is read-only; it does not modify any memories
# memanto agent create
Source: https://docs.memanto.ai/cli/agents/create
Create a new agent and activate it immediately.
# memanto agent create
Create a new agent and activate it immediately.
```bash theme={null}
memanto agent create AGENT_ID [OPTIONS]
```
**Arguments:**
* `AGENT_ID` - Unique agent identifier (required, alphanumeric / hyphens / underscores)
**Options:**
* `--pattern TEXT` - Agent pattern: `project`, `support`, or `tool` (default: `tool`)
* `--description TEXT` - Optional agent description
**Examples:**
Simple creation (defaults to `tool` pattern):
```bash theme={null}
memanto agent create customer-support
```
Specify a pattern:
```bash theme={null}
memanto agent create customer-support --pattern support
```
With description:
```bash theme={null}
memanto agent create customer-support \
--pattern support \
--description "Handles customer inquiries"
```
**Output:**
```
Agent 'customer-support' created successfully!
Pattern: support
Description: Handles customer inquiries
Agent activated automatically.
Activation expires: 2026-05-10T22:30:00Z
You can now run: memanto remember "..." and memanto recall "..."
```
**Notes:**
* Agent IDs must be unique and use alphanumeric, hyphens, or underscores only — no spaces
* Creating an agent automatically activates a 6-hour session
# memanto agent delete
Source: https://docs.memanto.ai/cli/agents/delete
Permanently delete an agent, optionally purging its memory namespace from Moorcheh cloud.
# memanto agent delete
Permanently delete an agent. Optionally purges its memory namespace from Moorcheh cloud.
```bash theme={null}
memanto agent delete AGENT_ID [OPTIONS]
```
**Arguments:**
* `AGENT_ID` - Agent ID to delete (required)
**Options:**
* `-f, --force` - Skip the initial delete confirmation prompt
**Examples:**
Delete with confirmation prompts:
```bash theme={null}
memanto agent delete customer-support
```
Force delete without confirmation:
```bash theme={null}
memanto agent delete customer-support --force
```
**Interactive Flow:**
```
Delete agent 'customer-support'? This cannot be undone. [y/N]: y
Keep a copy of agent memory on Moorcheh cloud for free? [Y/n]: Y
Deleting agent 'customer-support'...
✓ Agent 'customer-support' deleted
Cloud memories preserved at console.moorcheh.ai/namespaces
```
If you choose to purge cloud memories:
```
Keep a copy of agent memory on Moorcheh cloud for free? [Y/n]: n
Deleting agent 'customer-support'...
✓ Agent 'customer-support' deleted
Purging cloud namespace 'memanto_agent_customer-support'...
✓ Cloud memories purged
```
**Notes:**
* Prompts for confirmation unless `--force` is used
* Asks whether to keep or purge cloud memories in Moorcheh
* Cloud memories default to **preserved** (free of charge)
* If the agent has an active session, it is automatically cleared
* Only removes local agent metadata by default; Moorcheh namespace deletion is your choice
* This action cannot be undone
# memanto agent list
Source: https://docs.memanto.ai/cli/agents/list
List all created agents.
# memanto agent list
List all created agents.
```bash theme={null}
memanto agent list [OPTIONS]
```
**Options:**
* None
**Examples:**
List all agents:
```bash theme={null}
memanto agent list
```
**Output:**
```
Available Agents
1. customer-support
Created: 2025-03-20 10:30:00 UTC
Status: Inactive
Memories: 42
Last Used: 2025-03-28 14:22:00 UTC
2. project-manager
Created: 2025-03-15 09:15:00 UTC
Status: Inactive
Memories: 18
Last Used: 2025-03-25 11:45:00 UTC
3. billing-bot
Created: 2025-03-10 08:00:00 UTC
Status: Inactive
Memories: 7
Last Used: 2025-03-22 16:30:00 UTC
```
# memanto answer
Source: https://docs.memanto.ai/cli/ai/answer
Get AI-powered answers grounded in the active agent's memories.
# memanto answer
Get AI-powered answers grounded in the active agent's memories.
```bash theme={null}
memanto answer QUESTION [OPTIONS]
```
**Arguments:**
* `QUESTION` - Question to answer (required)
**Options:**
* `-n, --limit INTEGER` - Number of context memories to use (default: server-configured `ANSWER_LIMIT`)
Temperature and model selection are configured server-side; the CLI does not expose `--temperature` or `--ai-model` flags.
## Available Models
**Examples:**
Simple question:
```bash theme={null}
memanto answer "How should we communicate?"
```
With custom limit:
```bash theme={null}
memanto answer "What's the customer's profile?" --limit 20
```
**Output:**
```
Based on your memories:
The customer prefers email communication and is in the PST timezone.
You should send email during business hours PST (8am-5pm).
The customer appreciates concise responses, so keep communications brief.
```
# memanto conflicts
Source: https://docs.memanto.ai/cli/ai/conflicts
Interactively resolve memory conflicts detected for an agent.
# memanto conflicts
Reads the conflict report generated by [`memanto detect-conflicts`](/cli/ai/detect-conflicts) and walks through each unresolved conflict, letting you choose how to resolve it.
```bash theme={null}
memanto conflicts [OPTIONS]
```
**Options:**
* `-d, --date TEXT` - Date in `YYYY-MM-DD` format (defaults to today, UTC)
* `-a, --agent TEXT` - Agent identifier (defaults to active agent)
* `-l, --list` - List conflicts without interactive resolution
**Examples:**
Resolve today's conflicts interactively:
```bash theme={null}
memanto conflicts
```
List conflicts for a specific date without resolving:
```bash theme={null}
memanto conflicts --date 2026-03-01 --list
```
Specific agent:
```bash theme={null}
memanto conflicts --agent customer-support
```
**Interactive Flow:**
For each unresolved conflict, Memanto shows both memories side by side with an AI recommendation, then prompts for an action:
```
Conflict 1/2
[CONTRADICTION] Database preference changed
Memory A (old): ID: abc-123 · 2026-05-01
Customer is in finance team
Memory B (new): ID: def-456 · 2026-05-08
Customer moved to marketing team
AI Recommendation: Keep B (new)
[1] Keep A (old memory)
[2] Keep B (new memory) << recommended
[3] Keep both
[4] Remove both
[5] Manual: type replacement
[s] Skip [q] Quit
Choose: 2
OK Kept B (new). Old memory deleted.
```
After any conflicts are resolved, the local `memory.md` cache is automatically re-synced.
**Notes:**
* Requires a conflict report to already exist for the date — run `memanto detect-conflicts` first (or enable `memanto schedule enable`, which runs both automatically).
* Interactive resolution requires an active agent session. `--list` mode does not.
* Backed by the [List Conflicts](/api-reference/data/list-conflicts) and [Resolve Conflict](/api-reference/data/resolve-conflicts) API endpoints.
# memanto daily-summary
Source: https://docs.memanto.ai/cli/ai/daily-summary
Generate an AI-written daily summary from an agent's session memories.
# memanto daily-summary
Generate a daily AI summary from an agent's session memories. Also triggers a memory export to keep the local `memory.md` cache in sync.
```bash theme={null}
memanto daily-summary [OPTIONS]
```
**Options:**
* `-d, --date TEXT` - Date in `YYYY-MM-DD` format (defaults to today, UTC)
* `-a, --agent TEXT` - Agent identifier (defaults to active agent)
* `-o, --output PATH` - Custom output path for the summary Markdown file
**Examples:**
Summary for current agent, today:
```bash theme={null}
memanto daily-summary
```
Summary for a specific agent and date:
```bash theme={null}
memanto daily-summary --agent customer-support --date 2026-05-08
```
Custom output path:
```bash theme={null}
memanto daily-summary --output ./reports/summary.md
```
**Output:**
```
Daily summary generated: ~/.memanto/summaries/customer-support_2026-05-08.md
Memory export generated: 42 memories saved to cache
Conflict detection runs separately. Run 'memanto detect-conflicts' or enable
the schedule with 'memanto schedule enable'.
Completed in 1.84s
```
**Notes:**
* Requires an active agent, or pass `--agent` explicitly.
* Conflict detection is a separate step — see [`memanto detect-conflicts`](/cli/ai/detect-conflicts) or [`memanto schedule enable`](/cli/schedule/enable) to run both automatically.
* Backed by the [Generate Daily Summary](/api-reference/ai/generate-daily-summary) API endpoint.
# memanto detect-conflicts
Source: https://docs.memanto.ai/cli/ai/detect-conflicts
Run the LLM conflict-detection pass over a day's session memories and write the report.
# memanto detect-conflicts
Runs the LLM conflict-detection pass over the day's session memories and writes the JSON report to `~/.memanto/conflicts/`. This is the same work the [schedule](/cli/schedule/enable) job performs. Resolve the detected conflicts interactively with [`memanto conflicts`](/cli/ai/conflicts).
```bash theme={null}
memanto detect-conflicts [OPTIONS]
```
**Options:**
* `-d, --date TEXT` - Date in `YYYY-MM-DD` format (defaults to today, UTC)
* `-a, --agent TEXT` - Agent identifier (defaults to active agent)
**Examples:**
Detect conflicts for the active agent, today:
```bash theme={null}
memanto detect-conflicts
```
Detect conflicts for a specific agent and date:
```bash theme={null}
memanto detect-conflicts --agent customer-support --date 2026-05-08
```
**Output:**
```
Conflict report generated: ~/.memanto/conflicts/customer-support_2026-05-08_conflicts.json
! 2 conflict(s) detected
Run 'memanto conflicts' to resolve interactively
Completed in 2.11s
```
If no session data exists for the date, the command reports `No sessions found for conflict detection.` instead.
**Notes:**
* Requires an active agent, or pass `--agent` explicitly.
* This command only detects and reports conflicts — it does not resolve them. Use [`memanto conflicts`](/cli/ai/conflicts) to resolve.
* Backed by the [Generate Conflict Report](/api-reference/data/generate-conflicts) API endpoint.
# memanto config backend
Source: https://docs.memanto.ai/cli/config/backend
Show or switch the active Moorcheh backend between cloud and on-prem.
# memanto config backend
Show or switch the active Moorcheh backend. Switching to a backend that has never been set up runs its first-time setup flow (API key entry for cloud, server URL/embedding provider for on-prem).
```bash theme={null}
memanto config backend [NAME]
```
**Arguments:**
* `NAME` - Backend to switch to: `cloud` or `on-prem`. Omit to show the current backend.
**Examples:**
Show the current backend:
```bash theme={null}
memanto config backend
```
Switch to on-prem:
```bash theme={null}
memanto config backend on-prem
```
Switch back to cloud:
```bash theme={null}
memanto config backend cloud
```
**Output (showing current backend):**
```
Backend
Active backend: on-prem
Server: http://localhost:8080
Embedding: ollama
```
**Output (switching backend):**
```
Switched backend to on-prem.
Active session was cleared.
```
**Notes:**
* Switching always clears the active agent session — cloud and on-prem store data in separate local directories, so sessions never cross over.
* Switching to a backend that's already active is a no-op.
* See [Backend Switching](/on-prem/backend-switching) for the full cloud ↔ on-prem migration guide.
* Reflected in [`memanto config show`](/cli/config/show) as the `Backend` row.
# memanto config show
Source: https://docs.memanto.ai/cli/config/show
Display the current CLI configuration and status.
# memanto config show
Display current configuration and status.
```bash theme={null}
memanto config show [OPTIONS]
```
**Options:**
* None
**Example:**
```bash theme={null}
memanto config show
```
**Output:**
```
═══════════════════════════════════════════════════════
Memanto Configuration
═══════════════════════════════════════════════════════
API Configuration:
├── Moorcheh API Key: ✓ Configured (****)
├── API Base URL: https://api.moorcheh.ai
└── Connection Status: ✓ Connected
Local Configuration:
├── Config File: ~/.memanto/config.json
├── Config Version: 1.0
└── Last Updated: 2025-03-30 16:30:00 UTC
Session Configuration:
├── Active Agent: customer-support
├── Active Session Token: eyJhbGc... (truncated)
├── Session Expires: 2025-03-31 22:30:00 UTC
└── Auto-Renew: ✓ Enabled
Schedule Configuration:
├── Status: ENABLED
├── Daily Summary Time: 08:00 UTC
└── Next Run: 2025-03-31 08:00:00 UTC
IDE Integrations:
├── Claude Code: ✓ Connected
├── Cursor: ✗ Not connected
└── Windsurf: ✓ Connected
```
# memanto connect
Source: https://docs.memanto.ai/cli/connect/connect
Connect Memanto to a supported AI coding tool or agent.
# memanto connect
Install Memanto into a supported AI coding tool, IDE, or agent. Each target gets a tool-specific instruction file (e.g. `CLAUDE.md`, `.cursor/rules/memanto.mdc`) and the `memanto-memory` skill.
```bash theme={null}
memanto connect TARGET [OPTIONS]
```
**Arguments:**
* `TARGET` - One of the supported target IDs below.
**Supported Targets:**
| Target | Description |
| ---------------- | ----------------------- |
| `claude-code` | Anthropic Claude Code |
| `codex` | OpenAI Codex CLI |
| `cursor` | Cursor IDE |
| `windsurf` | Windsurf IDE |
| `antigravity` | Google Antigravity |
| `gemini-cli` | Google Gemini CLI |
| `cline` | Cline VS Code extension |
| `continue` | Continue.dev |
| `opencode` | OpenCode CLI |
| `goose` | Goose AI agent |
| `roo` | Roo Code |
| `github-copilot` | GitHub Copilot |
| `augment` | Augment Code |
**Options:**
* `-p, --project-dir TEXT` - Target project directory (default: `.`)
* `-g, --global` - Install globally to the target's home directory (e.g. `~/.claude/`, `~/.cursor/`) instead of the current project
**Examples:**
Install for the current project:
```bash theme={null}
memanto connect claude-code
```
Install for a different project:
```bash theme={null}
memanto connect cursor --project-dir ./my-project
```
Install globally (system-wide):
```bash theme={null}
memanto connect claude-code --global
```
**Output (example):**
```
✓ Memanto connected to Claude Code
Scope: Local
Path: /project/.claude/
Status: Ready to use
```
**Notes:**
* Run `memanto connect list` to see which targets are detected in your project and which already have Memanto installed.
* Use `memanto connect multi` for an interactive multi-target setup.
* Use `memanto connect remove ` to disconnect.
# memanto connect list
Source: https://docs.memanto.ai/cli/connect/list
List supported targets and Memanto installation status.
# memanto connect list
List all supported targets, indicating which ones are detected in your project and which already have Memanto installed (locally or globally).
```bash theme={null}
memanto connect list [OPTIONS]
```
**Options:**
* `-p, --project-dir TEXT` - Project directory to inspect (default: `.`)
**Examples:**
```bash theme={null}
memanto connect list
memanto connect list --project-dir ./my-project
```
**Output:**
```
MEMANTO Agent Integrations
Project: /Users/me/my-project
┌─────────────────┬──────────┬───────┬────────┬─────────────────────────────┐
│ Agent Name │ Detected │ Local │ Global │ Instruction File │
├─────────────────┼──────────┼───────┼────────┼─────────────────────────────┤
│ claude-code │ ● │ ● │ ○ │ CLAUDE.md │
│ cursor │ ○ │ ○ │ ○ │ .cursor/rules/memanto.mdc │
│ windsurf │ ● │ ● │ ○ │ .windsurfrules │
│ continue │ ○ │ ○ │ ● │ .continue/rules/memanto.md │
│ ... │ │ │ │ │
└─────────────────┴──────────┴───────┴────────┴─────────────────────────────┘
Local installs: 2 | Global installs: 1
Connect an agent: memanto connect
Interactive mode: memanto connect multi
```
**Columns:**
* **Detected** - Whether the target's marker files are present in the project
* **Local** - Memanto installed in the project scope
* **Global** - Memanto installed in the user-global scope (e.g. `~/.claude/`)
# memanto connect multi
Source: https://docs.memanto.ai/cli/connect/multi
Interactive setup to connect Memanto to multiple AI coding tools at once.
# memanto connect multi
Interactive setup to connect Memanto to multiple tools at once.
```bash theme={null}
memanto connect multi [OPTIONS]
```
**Options:**
* `-g, --global` - Install globally
* `-p, --project-dir TEXT` - Target project directory (default: `.`)
**Examples:**
Interactive selection:
```bash theme={null}
memanto connect multi
```
Prompts to choose tools:
```
Select tools to connect (press Space to toggle, Enter to confirm):
[✓] Claude Code
[ ] Cursor
[✓] Windsurf
[ ] Cline
```
Global installation:
```bash theme={null}
memanto connect multi --global
```
**Output:**
```
✓ Connected to 3 tools
Claude Code: ✓ Local
Cursor: ✓ Global
Windsurf: ✓ Local
All tools now have access to Memanto
```
# memanto connect remove
Source: https://docs.memanto.ai/cli/connect/remove
Disconnect Memanto from a connected target.
# memanto connect remove
Remove the Memanto integration from one or all connected targets.
```bash theme={null}
memanto connect remove [TARGET] [OPTIONS]
```
**Arguments:**
* `TARGET` - Target name to disconnect (e.g. `claude-code`, `cursor`). Optional when `--all` is used.
**Options:**
* `-p, --project-dir TEXT` - Project directory (default: `.`)
* `-g, --global` - Remove from the global scope instead of the project
* `--all` - Remove Memanto from every supported target in the chosen scope
Either `TARGET` or `--all` must be provided.
**Examples:**
Remove a single target locally:
```bash theme={null}
memanto connect remove claude-code
```
Remove a target globally:
```bash theme={null}
memanto connect remove cursor --global
```
Remove from a specific project directory:
```bash theme={null}
memanto connect remove claude-code --project-dir ./my-project
```
Remove all integrations in the project:
```bash theme={null}
memanto connect remove --all
```
Remove all integrations globally:
```bash theme={null}
memanto connect remove --all --global
```
**Output:**
```
✓ Claude Code
Removed instruction file: CLAUDE.md
Removed skill: .claude/skills/memanto-memory
Removed MEMANTO from 1 agent(s)
```
**Notes:**
* For hook-based integrations (currently Claude Code), `connect remove` also cleans up the `SessionStart` hook entry and any permissions MEMANTO added to the agent's settings — not just the instruction file and skill.
# memanto serve
Source: https://docs.memanto.ai/cli/core/serve
Start the local Memanto REST API server.
# memanto serve
Start the local Memanto API server. Exposes REST endpoints for programmatic access.
```bash theme={null}
memanto serve [OPTIONS]
```
**Options:**
| Option | Default | Description |
| ---------------- | --------- | --------------------------- |
| `--host TEXT` | `0.0.0.0` | Server host address |
| `--port INTEGER` | `8000` | Server port |
| `--reload` | `false` | Auto-reload on code changes |
**Examples:**
Start on default port:
```bash theme={null}
memanto serve
```
**Output:**
```
INFO: Uvicorn running on http://0.0.0.0:8000
INFO: Application startup complete
```
Start on custom port:
```bash theme={null}
memanto serve --port 8001
```
Start with auto-reload (development):
```bash theme={null}
memanto serve --reload
```
Specify host and port:
```bash theme={null}
memanto serve --host 127.0.0.1 --port 9000
```
**API Documentation:**
Once server is running:
* **Swagger UI**: [http://localhost:8000/docs](http://localhost:8000/docs)
* **ReDoc**: [http://localhost:8000/redoc](http://localhost:8000/redoc)
* **OpenAPI JSON**: [http://localhost:8000/openapi.json](http://localhost:8000/openapi.json)
**Health Check:**
```bash theme={null}
curl http://localhost:8000/health
```
**Use Cases:**
* Run Memanto as a service
* Programmatic access via REST API
* Integration with external applications
* Development and testing
# memanto status
Source: https://docs.memanto.ai/cli/core/status
Display current system status, configuration, and active sessions.
# memanto status
Display current system status, configuration, and active sessions.
```bash theme={null}
memanto status
```
**Output:**
```
═══════════════════════════════════════════════════════
Memanto Status
═══════════════════════════════════════════════════════
Moorcheh API Key: ✓ Configured (****)
Moorcheh Connection: ✓ Connected
Configuration Path: ~/.memanto/config.json
Active Agent: customer-support
Active Session: session_abc123xyz
Session Token: eyJhbGc... (truncated)
Session Expires: 2025-03-31 22:30:00 UTC
Time Until Expiry: 5h 47m
```
**Use Cases:**
* Verify API key is valid
* Check active agent
* Monitor session expiry
* Troubleshoot connection issues
# memanto ui
Source: https://docs.memanto.ai/cli/core/ui
Launch the interactive web dashboard for managing agents, memories, and sessions.
# memanto ui
Launch the interactive web dashboard. Provides UI for managing agents, memories, and sessions.
```bash theme={null}
memanto ui [OPTIONS]
```
**Options:**
| Option | Default | Description |
| ---------------- | --------- | ------------------- |
| `--host TEXT` | `0.0.0.0` | Server host address |
| `--port INTEGER` | `3000` | Dashboard port |
**Examples:**
Launch dashboard on default port:
```bash theme={null}
memanto ui
```
Launch on custom port:
```bash theme={null}
memanto ui --port 8080
```
**Output:**
```
✓ Dashboard started at http://localhost:3000
✓ Opening browser...
```
Automatically opens browser to dashboard.
**Dashboard Features:**
* View all agents
* Create and view agents
* Manage sessions
* Store memories (UI form)
* Search/recall memories
* View memory statistics
* Monitor daily summaries
* View conflicts
## UI Walkthrough
The screenshots below focus on the parts of the UI that are most important for day-to-day workflow.
### Dashboard Home
The Dashboard Home provides a high-level overview of your Memanto workspace. The left sidebar is your primary navigation menu, while the main grid displays cards with key metrics and configuration summaries. For deeper agent management workflows, see [Agent Commands](/cli/agents/create).
![Memanto dashboard first page]()
1
2
3
4
1. **Active agent card**: Confirms which agent context is currently loaded.
2. **System health card**: Quick check of service and connection health.
3. **Agent profile panel**: Core metadata for the active agent.
4. **Session info panel**: Session status, timing, and namespace details.
## Additional Annotated Screens
### Agents
The Agents page allows you to view all registered agents in your workspace and activate them. Activating an agent sets it as the current context for sessions and memory operations. The main table displays all registered agents along with their metadata (memories, sessions, etc.), current readiness state, and quick actions to refresh the list or activate specific agents.
### Playground
The Playground provides an interactive testing area to manually perform memory operations without needing to use the CLI.
![Memanto playground page]()
1
2
3
4
1. **Remember**: A form to manually store memories with full metadata (type, confidence, tags, source, provenance).
2. **Answer (RAG)**: A chat interface to ask questions against the agent's memory.
3. **Recall**: Advanced search interface with limits, type filtering, and similarity thresholds.
4. **Upload File**: Interface to upload documents directly into the agent's memory namespace.
### Memory Explorer
The Memory Explorer provides a complete view of your agent's knowledge base. The main interface is a large data table displaying memory content, confidence scores, and provenance. Use the numbered controls at the top to filter and traverse this data. To perform similar queries programmatically, see the [`memanto recall` command](/cli/search/recall).
![Memanto memory explorer page]()
1
2
3
4
1. **Time machine controls**: Set a date and switch the explorer to that historical memory state.
2. **Reset to now**: Return from the historical view to the current memory state.
3. **Search and query**: Filter memories by keyword or phrase.
4. **Type filter**: Narrow memory results by category (e.g., event, fact).
### Memory History
The Memory History page combines a contribution-style heatmap with a chronological timeline so you can inspect memory activity over time. It provides summary metrics (total memories, active days, peak day count, and longest streak) alongside a visual heatmap of activity across the last year. Below the heatmap, a chronological timeline details individual memories with their type, source, tags, time, and confidence.
### Conflict Resolution
This view helps you manage contradictory memories that arise during data ingestion or scheduled scans (see [Conflict Detection](/guides/memory-operations#conflict-detection)). The layout centers around two side-by-side memory cards: the **Old Memory** (currently stored) and the **New Memory** (the incoming statement).
Below the cards are specific action buttons to resolve the conflict:
* **Keep Old**: Rejects the incoming memory and preserves the existing one.
* **Keep New**: Overwrites the existing memory with the new information.
* **Keep Both**: Accepts the new memory while retaining the old one (useful if both are contextually true, or to establish a timeline).
* **Remove Both**: Deletes the old memory and rejects the new one entirely.
* **Manual Merge**: Opens a dialog to manually draft a new memory that synthesizes both points.
For more details on managing conflicts outside of the UI, refer to the [`memanto conflicts` CLI](/cli/ai/conflicts) or the [Resolve Conflicts API](/api-reference/data/resolve-conflicts).
### Connections
Manage AI tools connected to Memanto. This page allows you to link external AI development environments to your memory agent. You can add new projects, refresh the list of connected AI tools, and manage specific workspaces or global installations for tools like Codex CLI, Claude Code, and others.
### Configuration (Top Section)
![Memanto configuration page top section]()
1
2
3
4
1. **API credentials state**: Confirms API key status and access mode.
2. **Active context**: Current active agent and session details.
3. **Connection settings**: Server host and port used by the dashboard.
4. **Session behavior**: Auto-renew policy for active sessions. For details on session lifecycles and expiration, see [Session Management](/guides/session-management).
### Configuration (Answer, Limits, and Schedule)
![Memanto configuration page answer and schedule section]()
1
2
3
4
5
1. **Answer model**: Selects the model used for AI answers. See the [Available Models guide](/cli/ai/answer#available-models).
2. **Temperature**: Controls response creativity and randomness. See the [Temperature guide](/cli/ai/answer#temperature-guide).
3. **Relevance threshold**: Minimum similarity score required for retrieving a memory. See [ITS Scoring](/cli/search/recall#its-scoring) to understand match quality.
4. **Auto-parse Uploads**: Automatically parses and extracts memory statements from uploaded files and documents directly into the active namespace.
5. **Scheduling**: Time for the daily summary and conflict scan job. To learn what these background jobs do, read [Daily Workflows](/guides/daily-workflows).
### Usage & Analytics
The Analytics page provides a visual overview of your agent's memory utilization, helping you understand how memory is being gathered and categorized.
![Memanto analytics page]()
1
2
3
4
5
6
1. **Key metrics**: High-level overview of total memories sampled, distinct types, and average confidence.
2. **Usage over time**: Tracks memory ingestion and activity trends.
3. **Memory by Source**: Visual breakdown of where memories are originating from.
4. **Memory by Type**: Distribution of memory categories (e.g., instruction, preference, decision).
5. **Confidence distribution**: Analyzes the quality and reliability scores of stored memories.
6. **Top memory tags**: Highlights the most frequently used tags to help identify prominent subjects or skills.
**Note:** Server must be running (`memanto serve`) for dashboard to function.
# memanto edit
Source: https://docs.memanto.ai/cli/data/edit
CLI command for memanto edit.
# memanto edit
Update fields on an existing memory for the active agent.
```bash theme={null}
memanto edit MEMORY_ID [OPTIONS]
```
**Arguments:**
* `MEMORY_ID` - ID of the memory to update (required)
**Options:**
* `--title TEXT` - New memory title
* `--content TEXT` - New memory content
* `-t, --type TEXT` - New memory type
* `-c, --confidence FLOAT` - New confidence score (0.0-1.0)
* `--tags TEXT` - New comma-separated tags
* `-s, --source TEXT` - New memory source
**Examples:**
Update content only:
```bash theme={null}
memanto edit mem_abc123xyz --content "User prefers light mode (updated)"
```
Update multiple fields:
```bash theme={null}
memanto edit mem_abc123xyz \
--title "Updated Decision" \
--type decision \
--confidence 0.99
```
**Notes:**
* Requires an active agent. Run `memanto agent activate ` first.
* Replaces only the specified fields, leaving other fields and the original creation timestamp untouched.
* Backed by the [Edit Memory](/api-reference/data/edit-memory) API endpoint.
# memanto memory export
Source: https://docs.memanto.ai/cli/data/export
Export all of an agent's memories to a Markdown file.
# memanto memory export
Export all agent memories to file.
```bash theme={null}
memanto memory export [OPTIONS]
```
**Options:**
* `--agent TEXT` - Specific agent (default: active)
* `--output PATH` - Output file path (a directory when `--okf` is used)
* `--limit INTEGER` - Maximum memories per type, `1`–`100` (default: `25`)
* `--okf` - Export an [OKF](/integrations/okf) bundle (a directory of markdown files) instead of a single `memory.md`
* `--split TEXT` - OKF layout: `auto` (default), `file`, or `type` (only used with `--okf`)
**Examples:**
Export to markdown:
```bash theme={null}
memanto memory export
```
Custom output:
```bash theme={null}
memanto memory export --output backup.md
```
Specific agent:
```bash theme={null}
memanto memory export --agent customer-support --output customer-support.md
```
Limit export size:
```bash theme={null}
memanto memory export --limit 100
```
Export an OKF bundle (see the [OKF integration](/integrations/okf)):
```bash theme={null}
memanto memory export --okf
```
Force one file per memory in the OKF bundle:
```bash theme={null}
memanto memory export --okf --split file
```
**Output:**
Creates file with all memories:
```markdown theme={null}
# Agent: customer-support
Date: 2025-03-30
Total Memories: 42
```
**Notes:**
* If the backend is unreachable, export now fails loudly (`ConnectionError`) instead of silently writing an empty cache — a genuine "no memories of this type" still exports fine, but a full outage no longer overwrites a good cache with an empty one.
* With `--okf`, the bundle is written to `~/.memanto/exports/_okf/` (or the `--output` directory) and nests memories under `memories/` alongside `daily-summaries/`, `sessions/`, and `metrics/` sections when that data exists locally. To place a bundle inside a project directory, use [`memanto memory sync --okf`](/cli/data/sync). See the [OKF integration](/integrations/okf) for the full bundle layout.
# memanto forget
Source: https://docs.memanto.ai/cli/data/forget
Delete a single memory from the active agent.
# memanto forget
Delete a single memory from the active agent.
```bash theme={null}
memanto forget MEMORY_ID [OPTIONS]
```
**Arguments:**
* `MEMORY_ID` - ID of the memory to delete (required)
**Options:**
* `-f, --force` - Delete without asking for confirmation
**Examples:**
Delete with a confirmation prompt:
```bash theme={null}
memanto forget b7c3cf31-e537-49f1-abc4-c50ac6adeac5
```
Delete without confirmation:
```bash theme={null}
memanto forget b7c3cf31-e537-49f1-abc4-c50ac6adeac5 --force
```
**Output:**
```
Memory deleted successfully!
Memory ID: b7c3cf31-e537-49f1-abc4-c50ac6adeac5
Agent: customer-support
Completed in 0.41s
```
**Notes:**
* Requires an active agent. Run `memanto agent activate ` first.
* Operates on the active agent's namespace.
* Prompts for confirmation unless `--force` is used.
* You can find a memory's ID in the output of [`memanto recall`](/cli/search/recall).
* Backed by the [Delete Memory](/api-reference/data/delete-memory) API endpoint.
# memanto remember
Source: https://docs.memanto.ai/cli/data/remember
Store a new memory for the active agent — single, batch, or extracted from a conversation.
# memanto remember
Store a new memory for the active agent. Supports three input modes: a single memory, a batch of memories from a JSON file, or memories auto-extracted from a conversation transcript.
```bash theme={null}
memanto remember TEXT [OPTIONS]
```
**Arguments:**
* `TEXT` - Memory content (required unless `--batch` or `--from-conversation` is used)
**Options:**
* `-t, --type TEXT` - Memory type (fact, preference, goal, decision, artifact, learning, event, instruction, relationship, context, observation, commitment, error)
* `--title TEXT` - Memory title (defaults to truncated content)
* `-c, --confidence FLOAT` - Confidence score 0.0-1.0 (default: 0.8)
* `--tags TEXT` - Comma-separated tags
* `-s, --source TEXT` - Source of the memory, e.g. `user`, `agent_name` (default: `user`)
* `-p, --provenance TEXT` - Provenance/origin of the memory, e.g. `inferred`, `corrected` (default: `explicit_statement`)
* `--batch PATH` - Path to a JSON file with an array of memory objects (batch mode)
* `--from-conversation PATH` - Path to a JSON conversation file, or `-` to read from stdin (conversation-extraction mode)
* `--dry-run` - Preview extracted conversation memories without storing them (only valid with `--from-conversation`)
* `--max-memories INTEGER` - Maximum memories to extract from a conversation (default: 20, 1-100)
* `--ai-model TEXT` - Optional model override for conversation extraction
**Examples:**
Simple memory:
```bash theme={null}
memanto remember "Paris is the capital of France"
```
With type:
```bash theme={null}
memanto remember "Customer prefers email" --type preference
```
With title:
```bash theme={null}
memanto remember "Will deliver report Friday" --type commitment --title "Delivery Deadline"
```
Lower confidence:
```bash theme={null}
memanto remember "Thinks customer is in finance" --type fact --confidence 0.7
```
With tags, source, and provenance:
```bash theme={null}
memanto remember "Customer moved to marketing team" \
--type fact \
--tags "vip,enterprise" \
--source agent \
--provenance inferred
```
Batch from file:
```bash theme={null}
memanto remember --batch batch.json
```
Extract from a conversation file:
```bash theme={null}
memanto remember --from-conversation chat.json
```
Extract from stdin:
```bash theme={null}
cat chat.json | memanto remember --from-conversation -
```
Preview extraction from conversation without storing:
```bash theme={null}
memanto remember --from-conversation chat.json --dry-run
```
Limit extracted memories and pin a model:
```bash theme={null}
memanto remember --from-conversation chat.json --max-memories 10 --ai-model anthropic.claude-sonnet-4-6
```
**Memory Types:**
`fact`, `preference`, `decision`, `commitment`, `goal`, `event`, `instruction`, `relationship`, `context`, `learning`, `observation`, `error`, `artifact`
**Notes:**
* `--from-conversation` cannot be combined with `TEXT` or `--batch` — use one input mode at a time.
* Conversation JSON must be an array of `{role, content}` message objects (up to 200 messages).
* Batch JSON must be an array of memory objects (each needs at least `content`), up to 100 items per file.
* Backed by the [Remember](/api-reference/data/remember), [Batch Remember](/api-reference/data/batch-remember), and [Extract Memories](/api-reference/data/extract-memories) API endpoints.
# memanto memory sync
Source: https://docs.memanto.ai/cli/data/sync
Sync agent memories into a project's MEMORY.md file.
# memanto memory sync
Sync memories to MEMORY.md for Claude Code integration.
```bash theme={null}
memanto memory sync [OPTIONS]
```
**Options:**
* `--agent TEXT` - Specific agent
* `--project-dir PATH` - Target project directory (default: current directory)
* `--limit INTEGER` - Maximum memories per type to include, `1`–`100` (default: `25`)
* `--okf` - Sync an [OKF](/integrations/okf) bundle into `/okf/` instead of `MEMORY.md`
* `--split TEXT` - OKF layout: `auto` (default), `file`, or `type` (only used with `--okf`)
**Examples:**
Sync active agent:
```bash theme={null}
memanto memory sync
```
Sync specific agent:
```bash theme={null}
memanto memory sync --agent customer-support
```
Sync into a specific project:
```bash theme={null}
memanto memory sync --project-dir ./my-project
```
Sync a browsable OKF bundle into a project (see the [OKF integration](/integrations/okf)):
```bash theme={null}
memanto memory sync --okf --project-dir ./my-project
```
**Output:**
```
✓ Memories synced to MEMORY.md
Agent: customer-support
Memories: 42
File: ./MEMORY.md
```
**Notes:**
* If a fresh export fails because the backend is unreachable, `sync` falls back to the previous export instead of wiping `MEMORY.md` with an empty one — the project's memory file only goes stale, never blank.
* With `--okf`, the same fallback applies: on a backend outage `sync` reuses the previous OKF bundle (reported as `stale-cache`) rather than emptying `/okf/`.
# memanto upload
Source: https://docs.memanto.ai/cli/data/upload
Upload a file directly into the active agent's memory namespace.
# memanto upload
Upload a file directly into the active agent's memory namespace. The file content is processed and embedded by Moorcheh, making it instantly searchable via `memanto recall`.
```bash theme={null}
memanto upload FILE_PATH
```
**Arguments:**
* `FILE_PATH` - Path to the file to upload (required)
**Supported Formats:**
`.pdf`, `.docx`, `.xlsx`, `.json`, `.txt`, `.csv`, `.md`
**Maximum File Size:** 5 GB
**Requirements:**
* An active agent session is required before uploading
**Examples:**
Upload a PDF report:
```bash theme={null}
memanto upload ./quarterly-report.pdf
```
Upload a CSV dataset:
```bash theme={null}
memanto upload /data/customers.csv
```
Upload a markdown knowledge base:
```bash theme={null}
memanto upload ./knowledge-base.md
```
**Output:**
```
Uploading quarterly-report.pdf (2.4 MB)...
✓ File uploaded successfully
File: quarterly-report.pdf
Size: 2.4 MB
Namespace: memanto_agent_customer-support
Time: 3.2s
File content is now searchable via 'memanto recall'.
```
**Recall Results from Uploaded Files:**
When recalling memories, file-sourced content is visually distinguished from manually stored memories:
```
Found 3 memories:
1. Q3 revenue increased 18% year-over-year · file upload · summary
Confidence: 0.95
Created: 2025-03-30 10:15:00 UTC
2. Customer churn rate dropped to 4.2% · file upload · chunk
Confidence: 0.92
Created: 2025-03-30 10:15:00 UTC
3. Customer prefers email communication · memory
Confidence: 0.98
Created: 2025-03-26 09:00:00 UTC
```
**Notes:**
* Requires an active session (`memanto agent activate`)
* Files are processed asynchronously by Moorcheh (embeddings generated server-side)
* Uploaded content is stored in the cloud namespace, not as local memories
* Unsupported file types are rejected with a clear error message
# memanto migrate
Source: https://docs.memanto.ai/cli/migrate/migrate
Migrate memories from other providers (Mem0, Letta, Supermemory), an OKF bundle, or Langfuse observability signal into Memanto.
# memanto migrate
Import your memories from another provider into a Memanto agent. Each
subcommand pulls (or loads) the provider's export, maps the source records
onto Memanto memory types, and bulk-writes them into the target agent.
```bash theme={null}
memanto migrate PROVIDER [OPTIONS]
```
**Providers:**
* `mem0` - Migrate a Mem0 account
* `letta` - Migrate Letta archival passages
* `supermemory` - Migrate a Supermemory account
* `okf` - Import an [Open Knowledge Format](/integrations/okf) bundle from disk (see [OKF import](#okf-import) below)
* `langfuse` - Sync [Langfuse](/integrations/langfuse) errors, failed evals, and latency/cost anomalies (see [Langfuse sync](#langfuse-sync) below)
**Options:**
* `--api-key TEXT` - Provider API key (saved to `~/.memanto/.env`). Can also be supplied via the provider's environment variable.
* `-f, --file PATH` - Use an existing provider export JSON instead of pulling a live export.
* `-a, --agent TEXT` - Target Memanto agent ID (defaults to the active agent).
* `--dry-run` - Preview the mapping and savings report without writing anything.
* `--report` - Also write the token/latency/storage savings report on a real run.
The API key for each provider is read from these environment variables when
`--api-key` is not passed:
| Provider | Environment variable |
| ------------- | ------------------------------------------------------------------------------------------------- |
| `mem0` | `MEM0_API_KEY` |
| `letta` | `LETTA_API_KEY` |
| `supermemory` | `SUPERMEMORY_API_KEY` |
| `langfuse` | `LANGFUSE_API_KEY` (as `public_key:secret_key`), or `LANGFUSE_PUBLIC_KEY` + `LANGFUSE_SECRET_KEY` |
If no key is found, you are prompted for one and it is saved to `~/.memanto/.env`.
## How it works
1. **Load** the provider export — either from disk (`--file`) or by pulling a live export with your API key.
2. **Map** the source records onto Memanto memory types.
3. **Import** the mapped memories into the target agent in batches of up to 100.
4. **Report** (optional) — render a token/storage/latency savings report.
Empty source records are skipped. On a real run the target agent must be
resolvable (pass `--agent` or activate one first); a dry run does not need a
target agent.
## Examples
Preview a Mem0 migration without writing anything (also renders the savings report):
```bash theme={null}
memanto migrate mem0 --dry-run
```
Migrate a previously exported file into the active agent:
```bash theme={null}
memanto migrate mem0 --file ./mem0_export.json
```
Migrate Letta into a specific agent and write the savings report:
```bash theme={null}
memanto migrate letta --agent my-agent --report
```
Migrate Supermemory, providing the API key inline:
```bash theme={null}
memanto migrate supermemory --api-key sk-...
```
## OKF import
The `okf` subcommand imports an [Open Knowledge Format](/integrations/okf)
bundle — a local directory of markdown files (or a single `.md` file) — rather
than a hosted provider account. It takes a path instead of an API key, and does
not produce a savings report.
```bash theme={null}
memanto migrate okf PATH [OPTIONS]
```
**Options:**
* `-a, --agent TEXT` - Target Memanto agent ID (defaults to the active agent).
* `--dry-run` - Preview the mapping without writing anything.
**Behavior:**
* Fields that don't map onto a Memanto column are preserved in a bounded
`[Supporting data]` footer, so nothing is lost.
* OKF's free-form `type` is auto-classified when it isn't one of Memanto's 13
types (the original value is kept in the footer).
* When the bundle has a `memories/` folder, import is scoped to it — the
`daily-summaries/`, `sessions/`, and `metrics/` context sections are ignored,
so they are never re-ingested as memories.
Examples:
```bash theme={null}
# Preview the mapping without writing
memanto migrate okf ./okf-bundle --dry-run
# Import a bundle into a specific agent
memanto migrate okf ./okf-bundle --agent my-agent
```
See the [OKF integration guide](/integrations/okf) for the bundle layout, the
field-mapping table, and round-trip behavior.
## Langfuse sync
The `langfuse` subcommand is different from the others: it is a **repeatable
sync**, not a one-shot import. Observability signal — errored spans, failed
evaluations, latency and cost anomalies — is grouped into **one memory per
error signature** rather than one per occurrence, and a ledger makes re-running
safe.
```bash theme={null}
memanto migrate langfuse [OPTIONS]
```
**Options:**
* `--discover` - Report this project's score names, latency/cost spread, and error labels. Writes nothing.
* `--save` - Store the supplied capture settings for this Langfuse project.
* `-c, --capture TEXT` - What to capture; repeatable or comma-separated: `errors`, `low-score`, `slow`, `costly`, `success`. Default `errors`.
* `--score-fail TEXT` - Rule marking a score as a failure; repeatable. e.g. `'correctness<0.7'`.
* `--score-pass TEXT` - Rule marking a score as a success; repeatable.
* `--latency-ms FLOAT` - Fixed latency budget in ms.
* `--latency-percentile FLOAT` - Latency budget as a percentile of each operation's own traffic (e.g. `95`).
* `--cost-usd FLOAT` - Fixed cost budget in USD.
* `--cost-percentile FLOAT` - Cost budget as a percentile of each operation's own traffic.
* `--group-by TEXT` - Group on a stable field instead of the error message, e.g. `metadata.error_code`.
* `--since-days INTEGER` - Look back this many days. Defaults to the last sync time, or 7 days on a first run.
* `--host TEXT` - Langfuse base URL (`LANGFUSE_HOST`). Default `https://cloud.langfuse.com`.
* `--api-key TEXT` - Langfuse keys as `'public_key:secret_key'` (`LANGFUSE_API_KEY`). The vendor-native `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` pair is also accepted.
* `-a, --agent TEXT` - Target Memanto agent ID (defaults to the active agent).
* `-f, --file PATH` - Replay an existing Langfuse export JSON.
* `--dry-run` - Preview the grouping and the write/update plan without writing.
Langfuse Cloud is **regional** and keys are not valid across regions. If your
project is on US, pass `--host https://us.cloud.langfuse.com` once (it is
remembered) or set `LANGFUSE_HOST`. A region mismatch appears as
`401 Invalid credentials`.
**Only `errors` works with no configuration** — `level` is the one field every
Langfuse project populates the same way. Score names, their value ranges, and
what counts as slow or expensive are project-specific, so those modes stay
inert until you supply a rule or a budget, and the run tells you so:
```
! 'slow' captured nothing: no latency budget set — use --latency-ms for a
fixed budget, or --latency-percentile 95 to calibrate from your own traffic
```
Start with discovery:
```bash theme={null}
memanto migrate langfuse --discover
```
```
Name Type Count Observed Suggested rule
rating NUMERIC 60 1.0 … 5.0 --score-fail 'rating<3.4'
user-thumbs BOOLEAN 3 0.0 … 1.0 --score-fail 'user-thumbs=false'
Operation Count p50 ms p95 ms p99 ms cost p95
generate-response 300 2000 2000 40000 $0.002409
```
Then configure and sync:
```bash theme={null}
# Save what you want captured for this project
memanto migrate langfuse --capture errors,slow --latency-percentile 95 --save
# Preview, then sync
memanto migrate langfuse --dry-run
memanto migrate langfuse
```
Running the sync again reports `New: 0 · Unchanged: N` — nothing is duplicated.
A recurring failure is **updated in place** with its new occurrence count.
**Settings and state:**
* `~/.memanto/migrate/langfuse/config.json` — capture settings, per Langfuse project (written by `--save` or the UI tile).
* `~/.memanto/migrate/langfuse/state.json` — the sync ledger, scoped by Langfuse project **and** destination agent.
The [`langfuse-memanto`](/integrations/langfuse) SDK shares both files, so live
capture from your app and this sync compose without duplicating.
See the [Langfuse integration guide](/integrations/langfuse) for capture modes,
score-rule syntax, and the live SDK handler.
## Output
Results are written to a timestamped run directory under
`~/.memanto/migrate///`, containing:
* `mapped_preview.json` - the mapped Memanto payloads (always written, so a dry run is fully inspectable).
* `migrate-report.md` - the savings report (written on a dry run, or on a real run with `--report`).
The command also prints a summary panel with the source record count, the
number of mapped memories, a per-type breakdown, and — on a real run — the
imported / failed / batch counts and the target agent.
**Notes:**
* The savings report includes a short LLM-written narrative generated through the active agent. If no agent is active, the narrative is skipped (the rest of the report is still produced).
* Migrating into Memanto uses the same batch import as [`memanto remember --batch`](/cli/data/remember).
* `okf` and `langfuse` produce no savings report — one is a local file format, the other an observability backend, so neither is a memory store to benchmark against. `langfuse` additionally writes `config.json` and `state.json` beside its run directories, and its summary panel reports **new / changed / unchanged** rather than imported / skipped.
# CLI Overview
Source: https://docs.memanto.ai/cli/overview
Overview of the Memanto command-line interface and available commands.
# CLI Overview
The Memanto CLI is the entry point for agent, memory, session, scheduling, configuration, and integration workflows.
## Canonical CLI Output Reference
Use command-specific CLI pages as the source of truth for expected output and option behavior.
* Core command outputs: [Core Commands](/cli/core/status)
* Agent command outputs: [Agent Commands](/cli/agents/create)
* Memory command outputs: [Memory Commands](/cli/data/remember)
* Session command outputs: [Session Commands](/cli/sessions/info)
* Schedule command outputs: [Schedule Commands](/cli/schedule/status)
* Config command outputs: [Config Commands](/cli/config/show)
* Connect command outputs: [Connect Commands](/cli/connect/connect)
## Installation
```bash theme={null}
pip install memanto
```
Verify:
```bash theme={null}
memanto --version
```
For first-run setup, see [Installation & Setup](/getting-started/installation).
## Command Pattern
```bash theme={null}
memanto [COMMAND] [SUBCOMMAND] [OPTIONS]
```
## Command Groups
| Group | Purpose | Primary page |
| ------------ | ------------------------------------ | ----------------------------------------- |
| **Core** | Basic operations | [Core Commands](/cli/core/status) |
| **agent** | Agent lifecycle and activation | [Agent Commands](/cli/agents/create) |
| **memory** | Memory CRUD and analysis | [Memory Commands](/cli/data/remember) |
| **session** | Session inspection and extension | [Session Commands](/cli/sessions/info) |
| **schedule** | Automated summaries and checks | [Schedule Commands](/cli/schedule/status) |
| **config** | Local/system configuration | [Config Commands](/cli/config/show) |
| **connect** | IDE and assistant integrations | [Connect Commands](/cli/connect/connect) |
| **migrate** | Import memories from other providers | [Migrate Command](/cli/migrate/migrate) |
## Quick Start
```bash theme={null}
# 1. Configure API access
memanto
# 2. Create an agent (automatically activates)
memanto agent create my-agent
# 3. Store and recall memory
memanto remember "Project kickoff is Monday" --type event
memanto recall "When is project kickoff?"
```
For expanded workflows, use the command pages above and related guides in [Guides](/guides/memory-operations).
## Global Options
All commands support:
* `--help` - Show command help
* `--version` - Show Memanto version
Example:
```bash theme={null}
memanto remember --help
memanto --version
```
## Related Pages
* [Installation & Setup](/getting-started/installation)
* [Memory Operations Guide](/guides/memory-operations)
* [Moorcheh Setup & Integration](/guides/moorcheh-integration)
# memanto schedule disable
Source: https://docs.memanto.ai/cli/schedule/disable
Disable the automatic daily summary and conflict-detection schedule.
# memanto schedule disable
Disable automatic daily summaries.
```bash theme={null}
memanto schedule disable [OPTIONS]
```
**Options:**
* None
**Examples:**
Disable with confirmation:
```bash theme={null}
memanto schedule disable
```
**Output:**
```
✓ Daily summaries disabled
Previous Time: 08:00 UTC
Status: No more automatic summaries
```
# memanto schedule enable
Source: https://docs.memanto.ai/cli/schedule/enable
Enable the automatic daily summary and conflict-detection schedule.
# memanto schedule enable
Enable automatic daily summaries at a specific time.
```bash theme={null}
memanto schedule enable
```
**Options:**
* None
**Examples:**
Interactive setup:
```bash theme={null}
memanto schedule enable
```
This prompts:
```
What time should daily summaries run? (HH:MM in 24-hour format, UTC)
Example: 09:00 for 9 AM UTC
Enter time: 08:00
```
If your terminal is non-interactive, Memanto may use the existing configured schedule time instead of prompting. Run `memanto schedule status` to verify the final scheduled time.
**Output:**
```
✓ Daily summaries enabled
Time: 08:00 UTC
Next Run: 2025-03-31 08:00:00 UTC
Agent: customer-support
```
**What Happens:**
Every day at the specified time:
1. Daily summary is generated
2. Conflict detection runs
3. Results are saved locally
4. Summary is available via CLI/API
# memanto schedule status
Source: https://docs.memanto.ai/cli/schedule/status
Check the current schedule status and next run time.
# memanto schedule status
Check current schedule status and next run time.
```bash theme={null}
memanto schedule status [OPTIONS]
```
**Options:**
* None
**Examples:**
Check status:
```bash theme={null}
memanto schedule status
```
**Output if enabled:**
```
Daily Summary Schedule
Status: ENABLED
Time: 08:00 UTC
Last Run: 2025-03-30 08:00:00 UTC
Next Run: 2025-03-31 08:00:00 UTC
Agent: customer-support
Timezone: UTC
Recent Runs:
- 2025-03-30 08:00:00: 42 memories processed
- 2025-03-29 08:00:00: 38 memories processed
- 2025-03-28 08:00:00: 35 memories processed
```
**Output if disabled:**
```
Daily Summary Schedule
Status: DISABLED
```
# memanto recall
Source: https://docs.memanto.ai/cli/search/recall
Retrieve memories using semantic search, with optional temporal query modes.
# memanto recall
Retrieve memories using semantic search, with optional temporal modes.
```bash theme={null}
memanto recall QUERY [OPTIONS]
```
**Arguments:**
* `QUERY` - Search query (omit when using `--as-of`, `--changed-since`, or `--recent` — those modes list memories chronologically and ignore any query)
## ITS Scoring
**Options:**
* `-t, --type TEXT` - Filter by memory type (e.g. `fact`, `preference`)
* `-n, --limit INTEGER` - Maximum number of results (default: server-configured `RECALL_LIMIT`, max: 100)
* `--min-similarity FLOAT` - Minimum similarity score, i.e. how well the memory matches the query (`0.0`–`1.0`)
* `--min-confidence FLOAT` - Minimum stored confidence score on the memory itself (`0.0`–`1.0`)
* `--tags TEXT` - Filter by tags (comma-separated)
* `--as-of DATETIME` - Point-in-time query: what was true at this date? (`YYYY-MM-DD` or ISO 8601)
* `--changed-since DATE` - Differential query: what changed since this date? (`YYYY-MM-DD` or ISO 8601)
* `--recent` - Chronological query: return the most recently stored memories (newest first). Pairs with `--limit` and `--type`; ignores `QUERY`, `--tags`, `--min-similarity`, and `--min-confidence`.
`--as-of`, `--changed-since`, and `--recent` are mutually exclusive.
**Examples:**
Basic recall:
```bash theme={null}
memanto recall "What about the customer?"
```
Filter by type:
```bash theme={null}
memanto recall "preferences" --type preference
```
Specific limit:
```bash theme={null}
memanto recall "customer info" --limit 10
```
Temporal queries (no `QUERY` — these modes list memories chronologically):
```bash theme={null}
# As of a specific moment
memanto recall --as-of "2026-05-01T12:00:00Z"
# Changed since last week
memanto recall --changed-since "2026-05-03"
# Most recently stored memories (newest first)
memanto recall --recent --limit 10
# Narrow temporal queries by type
memanto recall --changed-since "2026-05-03" --type decision
memanto recall --recent --type fact
```
Tag filter:
```bash theme={null}
memanto recall "billing" --tags "vip,enterprise"
```
**Output:**
```
Found 3 memories:
1. Customer prefers email contact
Type: preference
Confidence: 0.98
Created: 2026-05-08 09:00:00 UTC
Source: user | Provenance: explicit_statement
Tags: vip, billing
2. Will deliver report by Friday
Type: commitment
Confidence: 1.0
Created: 2026-05-08 14:30:00 UTC
Source: agent | Provenance: inferred
3. In PST timezone
Type: fact
Confidence: 0.95
Created: 2026-05-07 10:15:00 UTC
Source: agent | Provenance: explicit_statement
```
Each result also surfaces its provenance metadata when present:
* **Source** — where the memory came from: `user`, `agent`, or the uploaded file name for file-based memories.
* **Ref** — a pointer to the original record within that source (e.g. a tool-call id or migration id). Only shown when set.
* **Provenance** — how the memory was obtained: `explicit_statement`, `inferred`, `corrected`, `validated`, `observed`, or `imported`.
* **Tags** — any tags attached to the memory.
# memanto agent activate
Source: https://docs.memanto.ai/cli/sessions/activate
Start a new session for an agent.
# memanto agent activate
Start a new session for an agent. Required before storing or recalling memories.
```bash theme={null}
memanto agent activate AGENT_ID [OPTIONS]
```
**Arguments:**
* `AGENT_ID` - Agent identifier (required)
**Options:**
* `-h, --hours INTEGER` - Activation duration in hours (default: 6)
**Examples:**
Activate with default 6-hour session:
```bash theme={null}
memanto agent activate customer-support
```
Activate with a longer duration:
```bash theme={null}
memanto agent activate customer-support --hours 12
```
**Output:**
```
OK Agent 'customer-support' activated!
Activation duration: 6 hours
Activation expires: 2026-05-10T22:30:00Z
```
**Notes:**
* Session token is saved automatically and reused by other CLI commands
* Only one active session per agent at a time
* Memanto auto-renews sessions near expiry on memory requests; re-run `activate` only after a hard expiry
# memanto agent deactivate
Source: https://docs.memanto.ai/cli/sessions/deactivate
End the current session for the active agent.
# memanto agent deactivate
End the current session for the active agent.
```bash theme={null}
memanto agent deactivate [OPTIONS]
```
**Options:**
* None
**Examples:**
Deactivate current session:
```bash theme={null}
memanto agent deactivate
```
**Output:**
```
✓ Session deactivated for agent 'customer-support'
Session Summary:
- Duration: 2h 15m
- Memories Stored: 12
- Memories Retrieved: 8
```
**Notes:**
* Memories persist after deactivation
* Agent can be reactivated anytime
* Requires new activation to use again
# memanto session info
Source: https://docs.memanto.ai/cli/sessions/info
View current active session information.
# memanto session info
View current active session information.
```bash theme={null}
memanto session info [OPTIONS]
```
**Options:**
* None
**Examples:**
Check current session:
```bash theme={null}
memanto session info
```
**Output:**
```
Current Session Information
Agent: customer-support
Session ID: session_abc123xyz
Status: ACTIVE
Created At: 2025-03-30 16:30:00 UTC
Expires At: 2025-03-31 22:30:00 UTC
Time Until Expiry: 5h 47m
Session Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
# Installation & Setup
Source: https://docs.memanto.ai/getting-started/installation
Install Memanto, configure your Moorcheh API key, and verify your setup.
# Installation & Setup
Memanto requires a Moorcheh API key or run it [On-Prem](/on-prem/overview) for free. This page focuses on setup only.
For exact CLI command output and full command behavior, use the [CLI Overview](/cli/overview).
## Prerequisites
* **Python 3.10+** (for CLI and local server)
* **Node.js 18+** (for TypeScript SDK)
* **Docker** (optional, for containerized deployment)
* **Moorcheh API key** (free tier available)
Want to run everything on your own hardware without a Moorcheh API key? See the [On-Prem Quickstart](/on-prem/quickstart) — same CLI, local Moorcheh server in Docker, optional fully-local Ollama for embeddings and LLM answers.
## Step 1: Get a Moorcheh API Key
Quick path:
1. Go to [https://moorcheh.ai](https://moorcheh.ai) and create an account.
2. Open [https://console.moorcheh.ai](https://console.moorcheh.ai).
3. Go to API Keys and create a new key.
4. Copy the key immediately (it is only shown once).
This is enough to continue installation.
For advanced topics (security practices, free tier planning, multi-environment setup, and sovereign deployment), see [Moorcheh Setup & Integration](/guides/moorcheh-integration).
## Step 2: Install Memanto
Choose your preferred method:
### Option A: CLI install (recommended)
```bash theme={null}
pip install memanto
```
Or with `uv`:
```bash theme={null}
pip install uv
uv tool install memanto
```
### Option B: TypeScript / Node.js SDK
For Node.js and TypeScript projects, use the official SDK:
```bash theme={null}
npm install @moorcheh-ai/memanto
```
**Prerequisites:** Node.js 18+ and `uvx` on PATH ([install uv](https://docs.astral.sh/uv/getting-started/installation/)).
The SDK boots a local Memanto server on demand and exposes an ergonomic `Memanto` client. See the [TypeScript SDK Reference](/sdk/typescript) for full documentation.
### Option C: Install from source
For development and customization:
```bash theme={null}
git clone https://github.com/moorcheh-ai/memanto.git
cd memanto
pip install uv
uv sync
```
### Option D: Docker
**Pull the pre-built image (recommended):**
```bash theme={null}
docker pull moorcheh/memanto:latest
docker run -p 8000:8000 -e MOORCHEH_API_KEY=your_api_key moorcheh/memanto:latest
```
The server is now available at `http://localhost:8000`.
**Or build from source:**
```bash theme={null}
git clone https://github.com/moorcheh-ai/memanto.git
cd memanto
docker build -t memanto .
docker run -p 8000:8000 -e MOORCHEH_API_KEY=your_api_key memanto
```
## Step 3: Configure API Key
Recommended interactive setup:
```bash theme={null}
# Launch interactive configuration
memanto
```
Follow the prompts:
```
Enter your Moorcheh API key: your_api_key_here
[Optional] Configure daily summary schedule? (y/n): y
What time should daily summaries run? (HH:MM in 24-hour format, UTC): 09:00
```
Configuration is stored in \~/.memanto/config.json (secure, not in git).
### Manual Configuration
If you prefer to skip the interactive setup:
```bash theme={null}
# Set environment variable
export MOORCHEH_API_KEY=your_api_key
# Or create .env file in project directory
echo "MOORCHEH_API_KEY=your_api_key" > .env
```
### Confirm Configuration Is Saved
```bash theme={null}
memanto config show
```
Expected indicators:
```
Moorcheh API Key: ✓ Configured
Configuration Path: ~/.memanto/config.json
```
## Step 4: Verify Setup
```bash theme={null}
# Confirm CLI is installed
memanto --version
# Confirm key + connectivity + config
memanto status
```
Optional API/server verification:
```bash theme={null}
# Start local Memanto API server
memanto serve
```
In another terminal:
```bash theme={null}
# Verify health endpoint
curl http://localhost:8000/health
```
## Troubleshooting
* Missing API key: run `memanto` again, then check `memanto config show`.
* Connection issues: verify key in `memanto config show` and check network access.
* Port in use: run `memanto serve --port 8001`.
* Unauthorized errors from API calls: ensure you are sending the correct `X-Session-Token` header.
For full troubleshooting and expected command outputs, see:
* [CLI Overview](/cli/overview)
## Next Steps
* [Quickstart: CLI](./quickstart-cli)
* [Quickstart: REST API](./quickstart-api)
* [CLI Overview](/cli/overview)
* [API Reference](/api-reference/authentication)
# Introduction
Source: https://docs.memanto.ai/getting-started/introduction
Learn what Memanto is, how it works, and why it gives AI agents persistent memory.
# Memanto - Memory that AI Agents Love!
**Memanto** is a production-ready memory system for AI agents that gives them persistent, semantic long-term memory across conversations, sessions, and workflows.
## What Problem Does It Solve?
LLMs inherently lack persistent memory; they forget conversations between sessions. Agents need a way to:
* **Remember user preferences** across sessions
* **Track decisions and commitments** made during conversations
* **Store facts and context** for faster, smarter responses
* **Manage long-running workflows** with consistent state
* **Learn from interactions** over time
Memanto solves this with a semantic memory system built for AI agents.
## The 6 Principles of Production Agentic Memory
Based on our research and testing, we believe a robust memory system for AI agents should strive for six key characteristics:
1. **Queryable, not injectable**: Agents generally benefit from the ability to query memory based on relevance to the current task, rather than receiving a static blob of context injected at the start of a conversation. It's akin to giving an agent a librarian it can consult on demand versus a pre-assembled dossier.
2. **Temporally aware with decay**: Not all memories carry equal weight. A deadline mentioned yesterday often has a different urgency than a preference stated six months ago. We've found that memory works best when it supports temporal queries, versioning, and relevance decay signals.
3. **Confidence and provenance tracking**: A production system should ideally distinguish between explicitly stated facts, inferred patterns, and potentially outdated information. Providing provenance metadata helps agents calibrate their confidence and avoid making assertions on stale data.
4. **Typed and hierarchical**: Different kinds of memory (e.g., *episodic* for past conversations, *semantic* for facts about the world/user, and *procedural* for how to do things) serve fundamentally different retrieval purposes and typically benefit from being stored and queried with appropriate type semantics.
5. **Contradiction aware**: When new information conflicts with existing memory, the system should aim to flag the conflict rather than silently overwriting it. Left unchecked, unresolved contradictions can accumulate into "constraint drift," which may erode the coherence of the agent's world model over time.
6. **Zero overhead ingestion**: For real-time workflows, memory should ideally be available for retrieval immediately at write time, minimizing indexing delays, mandatory LLM extraction steps, and graph construction bottlenecks.
### How Memanto Solves These Challenges
Memanto is designed from the ground up to address these six principles:
* **Dynamic Retrieval**: Rather than relying on massive context windows, Memanto provides an active search layer, allowing agents to pull exactly what they need, when they need it.
* **Rich Metadata & Typing**: Every memory is stored with a specific **type** (e.g., `fact`, `preference`, `decision`) and a **confidence score**, providing the provenance and structure agents need to reason effectively.
* **Temporal Context**: Memories belong to specific sessions and timelines, allowing agents to distinguish between outdated assumptions and recent commitments.
* **Instant Availability**: Because it is built on Moorcheh.ai (a no-indexing semantic database), Memanto eliminates the indexing delays of traditional vector databases. Memories are searchable the exact millisecond they are written.
## Key Advantages
### Zero-Cost Ingestion Latency
Unlike traditional vector databases that index after writes, Memanto uses **no-indexing semantic search**. Memories are available for retrieval **immediately** no waiting.
### State-of-the-Art Accuracy
Evaluated on LongMemEval and LoCoMo benchmarks:
* **89.8%** accuracy on LongMemEval
* **87.1%** accuracy on LoCoMo
### Semantic Search
Store memories with semantic meaning and retrieve them intelligently by relevance, not just keywords. For example, a query for "How should we contact the user?" will successfully match a memory stating "User prefers email communication" even without exact keyword overlap.
### Built on Moorcheh
Memanto uses **Moorcheh.ai**, the world's only no-indexing semantic database. Compared to traditional vector databases:
| Feature | Traditional VDB | Moorcheh |
| --------------- | ------------------------- | ------------- |
| Write-to-Search | Minutes (indexing) | **Instant** |
| Accuracy | Approximate (ANN) | **Exact** |
| Idle Costs | \$\$\$\$ (always running) | **\$0** |
| Computation | Heavy (indexing) | **Efficient** |
## Core Concepts
Before diving in, here are the core building blocks of Memanto:
* **Agents**: A persistent identity with its own isolated memory namespace (e.g., `customer-support-bot`).
* **Sessions**: A 6-hour active window for an agent. Memories created in one session persist forever and are available in all future sessions.
* **Memories**: A semantic unit of information (e.g., "User prefers email") stored with a specific type and confidence score.
## What You Can Build
| Use Case | Example | Benefit |
| ---------------------- | ------------------------------------------------------ | ---------------------------------- |
| **Customer Support** | Agent remembers past issues, preferences, tickets | Faster resolution, better context |
| **AI Assistants** | Assistant recalls your style, preferences, commitments | More personalized interactions |
| **Agent Workflows** | Multi-step processes maintain state across sessions | Reliable long-running automation |
| **Research Tools** | Track hypotheses, findings, decisions over time | Better scientific documentation |
| **Project Management** | Decisions and context persist across team discussions | Clearer history, faster onboarding |
## Memory Types
Memanto categorizes memories into 13 semantic types (like `fact`, `preference`, `decision`, `goal`, and `instruction`) to make memories highly organized and filterable.
→ See the [Memory Types Reference](/reference/memory-types) for the complete list.
## Architecture Overview
![Memanto architecture]()
## On-Prem
![Memanto architecture]()
## Deployment Options
* **Cloud (default)**: Talk to Moorcheh Cloud with a single API key — zero install, instant retrieval.
* **On-Prem**: Run the full stack (Memanto + Moorcheh server + optional Ollama) on your own hardware. No API key, no data leaves your network. See [On-Prem Overview](/on-prem/overview).
* **Docker**: Fastest setup, reproducible environments
* **Python**: Development and customization
* **Kubernetes / Cloud Platforms**: AWS ECS, Google Cloud Run, Azure Container Instances, or self-managed K8s.
* **Local**: Single machine testing and prototyping
## Next Steps
Choose your path based on your use case:
* ** Using Memanto CLI?** → See [Installation & Quickstart](./installation)
* ** Integrating with an agent?** → See [Agent Integration](./quickstart-api)
* ** Building a Node.js app?** → See [TypeScript SDK Reference](/sdk/typescript)
* ** Need complete reference?** → See [API Reference](/api-reference/authentication)
***
## Need Help?
* **Docs**: Full documentation on Moorcheh [https://docs.moorcheh.ai](https://docs.moorcheh.ai)
* **Discord**: Join the community at [https://memanto.ai/discord](https://memanto.ai/discord)
* **Reddit**: Join the community at [https://www.reddit.com/r/Memanto/](https://www.reddit.com/r/Memanto/)
* **Email**: [support@moorcheh.ai](mailto:support@moorcheh.ai)
# Quickstart: REST API
Source: https://docs.memanto.ai/getting-started/quickstart-api
Integrate Memanto into your application using the REST API.
# Quickstart: REST API
Learn how to build an AI agent with persistent memory using Memanto's REST API.
## What You'll Build
A simple customer support agent that:
* Remembers customer preferences
* Recalls relevant context
* Uses memories to provide personalized responses
## Prerequisites
* Memanto server running (`memanto serve`) with `MOORCHEH_API_KEY` configured in its environment
* Python 3.10+
* `httpx` library: `pip install httpx`
Memanto authenticates with Moorcheh **on the server** using the configured `MOORCHEH_API_KEY`. API clients **do not** send an `Authorization` header — they only send `X-Session-Token` for memory operations.
## Architecture
```
Your Agent Code
↓
REST API (X-Session-Token only)
↓
Memanto Server (MOORCHEH_API_KEY env)
↓
Moorcheh.ai (Semantic Database)
```
## Step 1: Start Memanto Server
In a terminal:
```bash theme={null}
export MOORCHEH_API_KEY=your_moorcheh_key
memanto serve
```
Expected output:
```
INFO: Application startup complete
```
## Step 1.5: Create the Agent Once
Create the agent ID used by the example before running the script:
```bash theme={null}
memanto agent create my-support-bot
```
## Step 2: Create the Agent
Create `customer_agent.py`:
```python theme={null}
import httpx
from typing import Optional
class CustomerSupportAgent:
def __init__(self, agent_id: str = "customer-support"):
self.memanto_url = "http://localhost:8000"
self.agent_id = agent_id
self.session_token: Optional[str] = None
self.client = httpx.Client()
def _headers(self) -> dict:
if not self.session_token:
raise ValueError("Session not activated. Call activate_session() first.")
return {
"X-Session-Token": self.session_token,
"Content-Type": "application/json",
}
def activate_session(self) -> str:
"""Start a new agent session."""
response = self.client.post(
f"{self.memanto_url}/api/v2/agents/{self.agent_id}/activate"
)
response.raise_for_status()
data = response.json()
self.session_token = data["session_token"]
print(f"✓ Session activated for '{self.agent_id}'")
print(f" Session expires: {data['expires_at']}")
return self.session_token
def remember(self, content: str, memory_type: str = "fact") -> str:
"""Store a memory about the customer."""
response = self.client.post(
f"{self.memanto_url}/api/v2/agents/{self.agent_id}/remember",
headers=self._headers(),
json={
"content": content,
"type": memory_type,
"title": f"{memory_type.title()}: {content[:50]}",
"confidence": 1.0,
},
)
response.raise_for_status()
data = response.json()
print(f"✓ Memory stored: {data['memory_id']}")
return data["memory_id"]
def recall(self, query: str, limit: int = 5) -> list[dict]:
"""Retrieve relevant memories about the customer."""
response = self.client.post(
f"{self.memanto_url}/api/v2/agents/{self.agent_id}/recall",
headers=self._headers(),
json={"query": query, "limit": limit},
)
response.raise_for_status()
return response.json().get("memories", [])
def answer(self, question: str) -> str:
"""Generate an answer grounded in agent memories."""
response = self.client.post(
f"{self.memanto_url}/api/v2/agents/{self.agent_id}/answer",
headers=self._headers(),
json={"question": question},
)
response.raise_for_status()
return response.json().get("answer", "")
def close(self):
"""Clean up resources."""
self.client.close()
```
## Step 3: Use Your Agent
Create `main.py`:
```python theme={null}
from customer_agent import CustomerSupportAgent
def main():
agent = CustomerSupportAgent(agent_id="my-support-bot")
try:
agent.activate_session()
# Remember customer preferences
print("\n📝 Storing customer memories...")
agent.remember("Customer name is Alice Johnson", "fact")
agent.remember("Alice works in the finance industry", "fact")
agent.remember("Alice prefers email communication", "preference")
agent.remember("Alice's timezone is PST (UTC-8)", "fact")
# Recall memories
print("\n🔍 Recalling memories...")
memories = agent.recall("What do I know about Alice?")
print(f"Found {len(memories)} memories:")
for mem in memories:
print(f" - {mem['content']} ({mem['type']})")
# Get AI-powered answer
print("\n🤖 Generating AI answer...")
answer = agent.answer("How should I communicate with Alice and what time zone is she in?")
print(f"Answer: {answer}")
# Simulate another conversation
print("\n\n--- Later Conversation ---\n")
memories = agent.recall("Tell me about this customer")
print(f"✓ Recalled {len(memories)} memories from first conversation")
if memories:
context = memories[0]["content"]
print(f"Using context: {context}")
finally:
agent.close()
if __name__ == "__main__":
main()
```
## Step 4: Run Your Agent
```bash theme={null}
python main.py
```
Expected output:
```
✓ Session activated for 'my-support-bot'
Session expires: 2026-05-09T20:30:00Z
📝 Storing customer memories...
✓ Memory stored: mem_abc123
✓ Memory stored: mem_def456
✓ Memory stored: mem_ghi789
✓ Memory stored: mem_jkl012
🔍 Recalling memories...
Found 4 memories:
- Alice works in the finance industry (fact)
- Customer name is Alice Johnson (fact)
- Alice prefers email communication (preference)
- Alice's timezone is PST (UTC-8) (fact)
🤖 Generating AI answer...
Answer: Alice works in finance and is in the PST timezone.
She prefers email communication, so I should reach out
to her via email during business hours in PST.
--- Later Conversation ---
✓ Recalled 4 memories from first conversation
Using context: Alice works in the finance industry
```
## Step 5: Use Memory Types Effectively
Different memory types help organize information:
```python theme={null}
# Facts - objective information
agent.remember("Customer ID is CUST-12345", "fact")
# Preferences - user likes/dislikes
agent.remember("Prefers concise responses", "preference")
# Decisions - choices made
agent.remember("Chose Plan B (Enterprise)", "decision")
# Commitments - promises made
agent.remember("Will provide report by Friday", "commitment")
# Events - what happened
agent.remember("Attended quarterly business review", "event")
# Goals - objectives
agent.remember("Target: Reduce support tickets by 20%", "goal")
# Errors - mistakes to avoid
agent.remember("Previous order had billing issue", "error")
```
## Step 6: Extend Your Agent
### Batch Store Memories
Store multiple memories at once:
```python theme={null}
def batch_remember(self, memories: list[dict]) -> dict:
"""Store multiple memories efficiently (max 100 per call)."""
response = self.client.post(
f"{self.memanto_url}/api/v2/agents/{self.agent_id}/batch-remember",
headers=self._headers(),
json={"memories": memories},
)
response.raise_for_status()
return response.json()
# Usage
agent.batch_remember([
{"content": "Alice Johnson", "type": "fact"},
{"content": "Finance industry", "type": "fact"},
{"content": "Email preferred", "type": "preference"},
])
```
### Temporal Queries
Recall memories from specific time periods:
```python theme={null}
def recall_as_of(
self,
timestamp: str,
type: list[str] | None = None,
limit: int | None = None,
) -> list[dict]:
"""Get memories valid at a specific time."""
body: dict = {"as_of": timestamp}
if type:
body["type"] = type
if limit:
body["limit"] = limit
response = self.client.post(
f"{self.memanto_url}/api/v2/agents/{self.agent_id}/recall/as-of",
headers=self._headers(),
json=body,
)
response.raise_for_status()
return response.json()["memories"]
# Recall state as of yesterday
memories = agent.recall_as_of(
timestamp="2026-05-08T12:00:00Z",
type=["preference"],
)
```
### Recall the Latest Memories
`/recall/recent` returns memories sorted newest-first (no query needed):
```python theme={null}
def recall_recent(self, limit: int = 10) -> list[dict]:
response = self.client.post(
f"{self.memanto_url}/api/v2/agents/{self.agent_id}/recall/recent",
headers=self._headers(),
json={"limit": limit},
)
response.raise_for_status()
return response.json()["memories"]
```
### Session Renewal
Sessions are auto-renewed on memory requests when they're near expiry. To start a fresh session explicitly, call `/activate` again — the new token replaces the old one. There is no separate `/extend` endpoint.
```python theme={null}
agent.activate_session() # returns a new session_token
```
## Complete Example
For a production-ready example, see the [API Reference](/api-reference/authentication) with all endpoints documented.
## Next Steps
* **Full REST API Reference**: [API Documentation](/api-reference/authentication)
* **Memory Types**: [Memory Types Reference](/reference/memory-types)
* **Advanced Patterns**: [Agent Patterns Guide](/guides/agent-management)
* **CLI Alternative**: [CLI Commands](/cli/overview)
* **TypeScript SDK**: [TypeScript SDK Reference](/sdk/typescript)
* **Integrations**: [Connect to IDE Plugins](/integrations/overview)
***
Congratulations! You've built your first memory-enabled agent. Now explore advanced features!
# Quickstart: CLI
Source: https://docs.memanto.ai/getting-started/quickstart-cli
Get up and running with Memanto using the command-line interface.
# Quickstart: CLI (5 Minutes)
Get Memanto working with real memory operations in under 5 minutes.
## Prerequisites
* Memanto installed (`pip install memanto`)
* Moorcheh API key configured (`memanto` setup)
* Terminal access
## 1. Check Status
Verify everything is set up:
```bash theme={null}
memanto status
```
## 2. Create and Activate Your First Agent
Creating an agent now automatically activates a session for you, so you're ready to go immediately.
```bash theme={null}
memanto agent create quick-demo
```
**Output:**
```
✓ Agent 'quick-demo' created successfully
✓ Session activated for agent 'quick-demo'
Session ID: session_abc123xyz
Session Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Expires In: 6h 0m
```
Verify activation:
```bash theme={null}
memanto status
```
## 3. Store Your First Memory
Store a simple fact:
```bash theme={null}
memanto remember "Paris is the capital of France" --type fact
```
Store a preference:
```bash theme={null}
memanto remember "I prefer responses in JSON format" --type preference
```
Store a commitment:
```bash theme={null}
memanto remember "Will complete the project by Friday" --type commitment
```
## 4. Recall Memories
Retrieve memories using semantic search:
```bash theme={null}
memanto recall "What is the capital of France?"
```
Recall by semantic similarity (not exact match):
```bash theme={null}
memanto recall "What format should responses be in?"
```
## 5. Get AI-Powered Answers
Generate answers grounded in your memories:
```bash theme={null}
memanto answer "Where is the capital of France and what format should I use?"
```
## 6. View Daily Summary (optional)
See all your memories and any conflicts:
```bash theme={null}
memanto daily-summary
```
## 7. Detect Contradictions (optional)
Check for conflicting memories:
```bash theme={null}
memanto conflicts
```
If you add a contradictory memory:
```bash theme={null}
memanto remember "Paris is in Germany" --type fact
```
Then check conflicts:
```bash theme={null}
memanto conflicts
```
## Next Steps
### For CLI Users
* **Full CLI Guide**: [CLI Overview](/cli/overview)
* **Memory Commands**: [Memory Operations](/cli/data/remember)
* **Agent Management**: [Agent Commands](/cli/agents/create)
### For Developers (Programmatic Access)
Want to use Memanto via REST API or Python?
→ See [First Agent Setup](./quickstart-api)
### Explore Features
* **Temporal Queries**: [Recall memories from specific times](/guides/memory-operations)
* **Batch Operations**: [Store 100 memories at once](/cli/data/remember)
* **Daily Workflows**: [Automated summaries and conflict detection](/guides/daily-workflows)
* **Integrations**: [Connect to Claude Code, Cursor, Cline, etc.](/integrations/overview)
***
**Done!** You've learned:
* Create agents
* Store memories
* Recall semantically
* Get AI answers
* Detect conflicts
* Manage sessions
Now explore advanced features in the guides!
# Agent Management
Source: https://docs.memanto.ai/guides/agent-management
Create, list, and delete agents in Memanto.
# Agent Management
Agents are the core identity in Memanto. Each agent maintains its own memory namespace and sessions.
## What is an Agent?
An **agent** represents a persistent identity that can maintain memories across sessions:
* **Unique identifier** - Never changes (e.g., `customer-support-bot`)
* **Memory namespace** - Isolated from other agents
* **Multiple sessions** - Can have sessions at different times
* **Long-term context** - Memories persist across sessions
## Agent Lifecycle
```
Create Agent (Auto-Activates) → Store/Recall Memories → Deactivate Session → Reactivate Later
↓
Delete Agent (optional)
```
## Managing Agents
Agent creation, listing, and session management are handled via the CLI or the REST API.
* **CLI Reference**: See [Agent Commands](/cli/agents/create) and [Session Commands](/cli/sessions/info).
* **API Reference**: See [Agents API](/api-reference/agents/create-agent) and [Sessions API](/api-reference/sessions/activate-agent).
* **Session Guide**: See [Session Management Guide](/guides/session-management) for details on session lifecycles.
## Agent Namespaces
Each agent automatically gets its own namespace in Moorcheh. Namespaces isolate semantic search so memories stay scoped to the correct agent.
```
Agent: customer-support
Namespace: memanto_agent_customer-support
```
All memories for that agent are stored in this namespace, and recall operations run against that namespace only.
### Search Isolation
Searches are isolated by default:
```
Agent: customer-support (namespace: memanto_agent_customer-support)
Query: "user preferences"
Search: ONLY in memanto_agent_customer-support
Agent: project-manager (namespace: memanto_agent_project-manager)
Query: "project status"
Search: ONLY in memanto_agent_project-manager
```
Agents never see each other's memories unless you intentionally implement a cross-agent access pattern.
### When You Need Shared Memory
If multiple agents need common context, use a dedicated shared agent:
```
Agent: shared-context
Namespace: memanto_agent_shared-context
Stores: company policies, product features, shared customer context
Sales Agent: recalls from its own namespace + shared-context
Support Agent: recalls from its own namespace + shared-context
```
This preserves isolation while allowing controlled sharing of common facts.
### Namespace Naming
Namespaces follow this pattern:
```
memanto_agent_{agent_id}
```
Examples:
* `customer-support` -> `memanto_agent_customer-support`
* `project-manager` -> `memanto_agent_project-manager`
* `research-bot` -> `memanto_agent_research-bot`
### Namespace Best Practices
DO:
* Create separate agents for different domains
* Keep related memories in the same agent
* Use a shared-context agent for cross-team knowledge
DON'T:
* Put all memories in one agent
* Expect cross-agent search automatically
* Reuse one agent for unrelated purposes
## Deleting Agents
When an agent is no longer needed, you can permanently delete it. The delete command walks you through two decisions: confirming the deletion, and choosing whether to keep a copy of the agent's memories in the Moorcheh cloud.
### CLI Method
```bash theme={null}
memanto agent delete customer-support
```
Skip confirmation with `--force`:
```bash theme={null}
memanto agent delete customer-support --force
```
### What Gets Deleted
| Item | Default behavior | If you decline cloud preservation |
| -------------------------------------------- | ---------------- | --------------------------------- |
| Local agent metadata (`~/.memanto/agents/`) | Always deleted | Always deleted |
| Moorcheh cloud namespace (`memanto_agent_*`) | **Preserved** | Deleted |
### REST API Method
By default the API endpoint removes local metadata only and leaves the Moorcheh namespace intact. Pass `delete-backup-too=true` to also delete the cloud namespace and its memories:
```python theme={null}
import httpx
# Local metadata only (cloud namespace retained)
response = httpx.delete(
"http://localhost:8000/api/v2/agents/old-agent"
)
# Also delete the Moorcheh namespace
response = httpx.delete(
"http://localhost:8000/api/v2/agents/old-agent",
params={"delete-backup-too": "true"},
)
if response.status_code == 200:
print(response.json()["message"])
```
API clients do not send an `Authorization` header — Memanto authenticates with Moorcheh server-side using the configured `MOORCHEH_API_KEY`.
***
## Agent Metadata
### View Agent Metadata
```bash theme={null}
memanto agent bootstrap customer-support
```
This shows:
* Agent ID
* Created timestamp
* Memory count by type
* Last session info
* Summary of important memories
## Agent Isolation & Scaling
Scale your architecture by creating distinct agents based on your needs:
* **Per User/Role:** `alice-support-rep`, `bob-support-rep`
* **Per Domain/Task:** `customer-preferences`, `billing-issues`
* **Per Environment:** `prod-support-bot`, `staging-support-bot`
Use clear, descriptive naming conventions to keep your agents organized as your project scales.
## Performance Considerations
### Agent Limits
* No hard limit on number of agents (free tier up to 5 agents)
* Each agent can have unlimited memories
* Sessions limited to 1 active per agent at a time
* Memories queryable in under 100ms on average
### Optimization Tips
1. **Reuse agent sessions** - Don't create new sessions frequently if active session is available
2. **Batch operations** - Store multiple memories at once
3. **Deactivate sessions** - Deactivate sessions when no longer needed to free resources
## Next Steps
* **Store Memories**: [Memory Operations Guide](./memory-operations)
* **Session Management**: [Session Management Guide](./session-management)
* **CLI Reference**: [Agent Commands](/cli/agents/create)
***
Agents are the foundation of Memanto. Master agent management to build powerful memory-enabled applications!
# Daily Workflows
Source: https://docs.memanto.ai/guides/daily-workflows
Common day-to-day workflows with Memanto.
# Daily Workflows & Automation
Automate daily memory management tasks with Memanto.
## What Are Daily Workflows?
Daily workflows are automated tasks that run on a schedule:
* **Daily Summaries** - Compile all day's memories into a summary
* **Conflict Detection** - Find contradictory memories
* **Memory Validation** - Verify important memories
* **Export & Backup** - Regular memory exports
## Daily Summaries
### What They Include
A daily summary shows:
* Total memories created today
* Breakdown by memory type
* Key facts discovered
* Important decisions made
* Potential issues detected
### Generate Summary - CLI
```bash theme={null}
memanto daily-summary
```
See the [Memory Commands CLI Reference](/cli/data/remember) for output details.
## Conflict Detection
### Find Contradictions - CLI
```bash theme={null}
memanto conflicts
```
See the [Memory Commands CLI Reference](/cli/data/remember) for details on resolving conflicts interactively.
## Scheduled Tasks
### Enable Daily Summary Schedule
Enable automated daily summaries:
```bash theme={null}
memanto schedule enable
```
### Check Schedule Status
```bash theme={null}
memanto schedule status
```
### Disable Schedule
```bash theme={null}
memanto schedule disable
```
See the [Schedule Commands CLI Reference](/cli/schedule/status) for full configuration details.
## Related Operations
Daily workflows often call memory operations, but command-level details are maintained in the memory guides and CLI reference.
* Batch ingest: [Memory Operations](./memory-operations)
* Export commands and formats: [Memory Commands CLI Reference](/cli/data/remember)
### Automated Backups
Set up a cron job for daily exports:
```bash theme={null}
#!/bin/bash
# backup_memories.sh
AGENT_ID="customer-support"
BACKUP_DIR="./backups"
DATE=$(date +%Y-%m-%d)
mkdir -p "$BACKUP_DIR"
memanto memory export --output "$BACKUP_DIR/${AGENT_ID}_${DATE}.md"
# Keep only last 30 days
find "$BACKUP_DIR" -type f -name "${AGENT_ID}_*.md" -mtime +30 -delete
```
Add to crontab:
```bash theme={null}
crontab -e
# Add line:
0 0 * * * /path/to/backup_memories.sh
```
## Workflow Automation Examples
### Daily Review Workflow
```python theme={null}
def daily_workflow(agent_id: str):
"""Run complete daily workflow."""
# 1. Generate summary (CLI command)
print("📊 Generating daily summary...")
# subprocess.run(["memanto", "daily-summary", "--agent", agent_id], check=True)
# 2. Check for conflicts (CLI command)
print("🔍 Checking for conflicts...")
# subprocess.run(["memanto", "conflicts", "--agent", agent_id, "--list"], check=True)
# 3. Export backup
print("💾 Exporting backup...")
# memanto memory export command
# 4. Report
print("✓ Daily workflow complete")
```
### Weekly Analysis
```python theme={null}
def weekly_workflow(agent_id: str):
"""Run weekly memory analysis."""
# Recall all new memories from past week
week_ago = (datetime.now() - timedelta(days=7)).isoformat()
response = httpx.post(
f"http://localhost:8000/api/v2/agents/{agent_id}/recall/changed-since",
json={"since": week_ago},
headers={"X-Session-Token": session_token, "Content-Type": "application/json"},
)
new_memories = response.json()["memories"]
# Analyze patterns
type_counts = {}
for mem in new_memories:
mem_type = mem['type']
type_counts[mem_type] = type_counts.get(mem_type, 0) + 1
print(f"Weekly Summary ({week_ago}):")
for mem_type, count in sorted(type_counts.items(), key=lambda x: x[1], reverse=True):
print(f" {mem_type}: {count}")
```
## Best Practices
### DO
* Run daily summaries to track memory growth
* Check conflicts weekly
* Schedule recurring tasks for consistency
### DON'T
* Ignore detected conflicts
* Let old memories accumulate unchecked
* Leave failed workflows unreviewed
## Next Steps
* **Memory Operations**: [Memory Operations Guide](./memory-operations)
* **Schedule Commands**: [Schedule Commands](/cli/schedule/status)
* **Memory Commands**: [Memory Commands](/cli/data/remember)
***
Automate your memory workflows for consistent, reliable agent operations!
# Memory Operations
Source: https://docs.memanto.ai/guides/memory-operations
Store, retrieve, validate, and manage memories.
# Memory Operations
Store, retrieve, and maintain high-quality memories in Memanto.
## Memory Fundamentals
### What is a Memory?
A memory in Memanto includes:
* **Content**: The core information.
* **Type**: Semantic category (fact, preference, decision, etc.).
* **Title** (optional): Short label for readability.
* **Confidence** (optional): Reliability score from 0 to 1.
* **Metadata** (optional): Extra structured context.
### Memory Lifecycle
```
Store -> Index (instant) -> Recall -> Conflict detection -> Resolve
```
## Core Operations
Use these commands for most workflows:
* Store a memory: `memanto remember "..." --type fact`
* Batch store: `memanto remember --batch memories.json`
* Recall semantically: `memanto recall "..."`
* Answer from context: `memanto answer "..."`
* Delete a memory: `memanto forget MEMORY_ID`
* Detect contradictions: `memanto conflicts`
* Export memory history: `memanto memory export`
## Uploading Files into Memory
When information already exists in documents, upload files instead of manually adding many individual memories.
### Supported Formats
`.pdf`, `.docx`, `.xlsx`, `.json`, `.txt`, `.csv`, `.md` (up to 5 GB per file).
### CLI
Activate an agent session, then upload:
```bash theme={null}
memanto agent activate customer-support
memanto upload ./customer-profile.pdf
```
Recall uploaded knowledge with normal search:
```bash theme={null}
memanto recall "What is the customer's annual revenue?"
```
### REST API
```python theme={null}
import httpx
with open("customer-profile.pdf", "rb") as f:
response = httpx.post(
"http://localhost:8000/api/v2/agents/customer-support/upload-file",
files={"file": ("customer-profile.pdf", f, "application/pdf")},
headers={"X-Session-Token": session_token},
)
result = response.json()
print(f"Status: {result['status']}, File: {result['file_name']}")
```
### Upload vs Remember
| Use `upload` when... | Use `remember` when... |
| -------------------------------- | ---------------------------------------- |
| You have existing documents | You are storing short atomic facts |
| Content spans many pages | You want explicit memory typing per item |
| You ingest structured data files | You want precise confidence per memory |
## Extracting from Conversations
If you have raw chat logs, Memanto can automatically parse the conversation and use the underlying LLM to extract durable, structured memories (like facts and preferences) while discarding the noise.
### Using the Web UI
The Memanto Web Dashboard features an **Extract** tab in the Playground:
1. Paste a JSON array of conversation turns (`[{"role": "user", "content": "..."}, ...]`).
2. Click **Preview Extraction** to review the memory cards Memanto generated. You can modify types, content, and confidence.
3. Click **Save to Database** to persist the selected facts.
4. (Optional) Use **Extract & Save** to skip the preview and directly persist the memories.
### Using the CLI
You can extract and store memories from a local JSON file containing your chat history:
```bash theme={null}
# Preview what would be extracted
memanto remember --from-conversation chat.json --dry-run
# Extract and persist directly
memanto remember --from-conversation chat.json
```
### Using the REST API
Send your conversation payload to the extract endpoint:
```bash theme={null}
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/remember/extract" \
-H "X-Session-Token: " \
-H "Content-Type: application/json" \
-d '{
"messages": [
{"role": "user", "content": "I prefer 4 spaces for indentation."},
{"role": "assistant", "content": "Got it."}
],
"dry_run": true
}'
```
## Recall Patterns
### Semantic Recall
```bash theme={null}
memanto recall "What do I know about user preferences?"
```
### Filter by Type
```bash theme={null}
memanto recall "How should I contact this user?" --type preference
```
### Limit Result Volume
```bash theme={null}
memanto recall "customer details" --limit 10
```
### Temporal Recall
Use the temporal recall variants (`--as-of`, `--changed-since`, and `--recent`) to query memory across time.
See [Temporal Memory Details](./temporal-memory) for complete patterns and examples.
## Answering and Conflict Management
### Grounded Answers
```bash theme={null}
memanto answer "Based on memory, how should we communicate with this customer?"
```
### Conflict Detection
```bash theme={null}
memanto conflicts
```
When contradictions are found, resolve them by keeping the new memory, the old one, both, removing both, or replacing them with a manual entry. See [List Conflicts](/api-reference/data/list-conflicts) and [Resolve Conflict](/api-reference/data/resolve-conflicts) for the API contract.
## Deleting a Memory
Remove a single memory from the active agent by its ID. Find the ID in the
output of `memanto recall`, then:
```bash theme={null}
memanto forget b7c3cf31-e537-49f1-abc4-c50ac6adeac5
```
This prompts for confirmation. Add `--force` to skip it. See the
[forget command](/cli/data/forget) and [Delete Memory API](/api-reference/data/delete-memory)
for details.
For contradictions, prefer resolving conflicts (keep new/old/both, remove both, or replace) over deleting history. Use `forget` for one-off removals such as a memory stored by mistake.
## Migrating from Other Providers
Already have memories in Mem0, Letta, or Supermemory? Import them into a
Memanto agent with `memanto migrate`:
```bash theme={null}
# Preview the mapping and savings report without writing
memanto migrate mem0 --dry-run
# Import into the active agent
memanto migrate mem0
```
See the [migrate command](/cli/migrate/migrate) for providers, options, and output details.
## Export and Sync
### Export to Markdown
```bash theme={null}
memanto memory export
```
### Export to Custom Path
```bash theme={null}
memanto memory export --output /path/to/memory.md
```
### Sync to MEMORY.md
```bash theme={null}
memanto memory sync
```
## Performance Tips
1. Use specific memory types instead of defaulting everything to `fact`.
2. Batch ingest when importing many items.
3. Keep recall limits tight for faster, cleaner responses.
4. Use confidence scoring when information quality varies.
## Best Practices
### DO
* Keep memories concise and atomic.
* Record source context in metadata when useful.
* Resolve conflicts explicitly when contradictions arise rather than deleting history.
### DON'T
* Store the same fact repeatedly.
* Mix multiple unrelated facts in one memory.
* Over-fetch with very high recall limits by default.
## Next Steps
* **CLI**: [Remember](/cli/data/remember), [Recall](/cli/search/recall)
* **API**: [Remember](/api-reference/data/remember), [Recall](/api-reference/search/recall)
* **Temporal Guide**: [Temporal Memory Details](./temporal-memory)
***
Memory operations are the core of Memanto. Keep this flow lean, typed, and conflict-aware for best results.
# Moorcheh Integration
Source: https://docs.memanto.ai/guides/moorcheh-integration
Configure and integrate Moorcheh as the backend for Memanto.
# Moorcheh Setup & Integration
Moorcheh.ai is a no-indexing semantic database for AI memory and retrieval workloads. Memanto uses Moorcheh as its semantic memory backend. This guide focuses on Moorcheh platform concepts, account setup, API key management, and operational best practices.
This page explains Moorcheh itself. For Memanto installation and CLI/API setup flow, use [Installation & Setup](/getting-started/installation).
## The Moorcheh Difference
### Traditional Vector Databases
Traditional systems (Pinecone, Weaviate, Milvus) use HNSW (Hierarchical Navigable Small World) for approximate nearest neighbor search:
```
Write Memory → Index (5-10 minutes wait) → Available for search
↑ (CPU-intensive)
```
Problems:
* **Indexing delays** - Wait minutes before memories are searchable
* **Approximate search** - Results are probabilistic, not exact
* **High costs** - Always-running infrastructure
* **Complex setup** - Complex configuration and tuning
### Moorcheh's Approach
Moorcheh uses Information Theoretic Vector Compression (ITVC) with full vector scans:
```
Write Memory → Instant availability (no indexing) → Search immediately
↑ (efficient)
```
Advantages:
* **Zero indexing delay** - Memories searchable immediately
* **Exact search** - Deterministic results, same query always returns same results
* **Serverless** - Scales to zero, pay only for operations
* **Efficient** - 80% less compute than traditional systems
## How Moorcheh Works
### Storage
```
Memory: "User prefers email"
↓
Memanto: Converts to vector representation
↓
Moorcheh: Compresses vector using ITVC
↓
Result: Instantly searchable (no indexing wait)
```
### Retrieval
```
Query: "How should we contact the user?"
↓
Memanto: Converts to vector
↓
Moorcheh: Searches with full vector scans
↓
Result: Exact match: "User prefers email"
```
## Integration Details
Moorcheh can be used directly from your application, or through a higher-level memory layer such as Memanto.
### Connection
Memanto connects to Moorcheh via REST API:
```
Your App → Moorcheh API
└─ Uses your API key
or
Your Agent → Memanto API → Moorcheh API
└─ Uses your API key
```
### Authentication
Moorcheh's own API uses the `Authorization: Bearer` header. **Memanto consumes this on the server side** — it reads `MOORCHEH_API_KEY` from its environment and authenticates against Moorcheh internally. Clients calling the Memanto API never send the Moorcheh key.
```
# Direct Moorcheh API call (server-to-server, or your own integration)
Authorization: Bearer your_moorcheh_key
```
### Data Flow
```
1. Store Memory
Agent → Memanto → Moorcheh (vector storage)
2. Recall Memory
Agent → Memanto → Moorcheh (vector search)
↑ (vector conversion)
3. Semantic Matching
Memanto uses Moorcheh's semantic search
(not traditional keyword matching)
```
## Getting Your API Key
### Step 1: Create Moorcheh Account
1. Visit [https://moorcheh.ai](https://moorcheh.ai)
2. Click **"Sign Up"** or **"Get Started"**
3. Enter your email and create a password
4. Verify your email (check your inbox)
5. Log in to the dashboard
### Step 2: Generate API Key
1. Log in to [Moorcheh Console](https://console.moorcheh.ai)
2. Navigate to **API Keys** section (left sidebar)
3. Click **"Create New API Key"**
4. Choose a name (e.g., "Memanto Development")
5. Click **"Generate"**
6. **Copy the key immediately**
⚠️ **Important**: The key is only shown once. Copy it to a safe place.
### Step 3: Keep It Secret
**Never:**
* Commit API keys to Git
* Share in emails or chat
* Hardcode in public repositories
* Add to client-side code
**Instead:**
* Use environment variables
* Use `.env` files (excluded from git)
* Use secrets managers (AWS Secrets Manager, HashiCorp Vault, etc.)
## Using Your API Key Securely
### Option 1: Environment Variable
```bash theme={null}
export MOORCHEH_API_KEY=your_api_key_here
```
### Option 2: .env File
Create `.env` in your project:
```bash theme={null}
MOORCHEH_API_KEY=your_api_key_here
```
Then load it:
```bash theme={null}
source .env
```
For Python projects:
```python theme={null}
import os
from dotenv import load_dotenv
load_dotenv()
api_key = os.getenv("MOORCHEH_API_KEY")
```
## Verify Connectivity
Check Moorcheh API health:
```bash theme={null}
curl https://api.moorcheh.ai/v1/health
```
### Test from Code
```python theme={null}
import httpx
import os
api_key = os.getenv("MOORCHEH_API_KEY")
response = httpx.get(
"https://api.moorcheh.ai/v1/health",
headers={"Authorization": f"Bearer {api_key}"}
)
print(response.json()) # Should return {"status": "healthy"}
```
## Cost Advantage
### Traditional System
```
Scenario: 100K memories, weekly queries
Fixed Infrastructure: $500/month
└─ Always-running indexing service
Query Operations: $200/month
└─ 10K queries × $0.02 per query
TOTAL: $700/month + complexity
```
### Moorcheh + Memanto
```
Scenario: 100K memories, weekly queries
Fixed Infrastructure: $0
└─ Serverless (scales to zero)
Query Operations: $150/month
└─ 100K operations × $0.0015 per operation
TOTAL: $150/month + simplicity
```
**Savings: 78% cost reduction**
## Scalability
Moorcheh scales naturally:
```
1,000 memories: Same cost and speed
100,000 memories: Same cost and speed
1,000,000 memories: Same cost and speed
```
No indexing means no scaling complexity.
## Understanding Free Tier
Moorcheh's free tier includes:
* **500 monthly credits** (\~100,000 operations)
* **Create up to 5 agents**
* **Unlimited sessions** (no session limits)
* **No credit card required**
* **Zero Indexing Delay** & **Exact Search**
### What Counts as Operations?
* **Write operations**: storing semantic records
* **Read operations**: semantic and exact retrieval queries
* **Special operations**: workload-dependent metadata and management operations
### Estimation
| Scenario | Memories | Operations/Day | Days Limit |
| ----------------------------- | -------- | -------------- | ---------- |
| Small agent (10 mem/day) | 10 | 10 | 5,000 |
| Medium agent (50 mem/day) | 50 | 50 | 1,000 |
| Large agent (100 queries/day) | - | 100 | 500 |
| Development (200 ops/day) | - | 200 | 250 |
The free tier is **plenty for heavy development and testing**.
## Upgrading to Paid Plan
When you need more than 500 credits/month:
1. Go to [https://console.moorcheh.ai](https://console.moorcheh.ai)
2. Select a plan:
* **Pro**: 10,000 monthly credits
* **Enterprise**: Custom limits
3. Add payment method
4. Your free API key automatically upgrades
No code changes needed - same API key works with your new plan.
## Multi-Environment Key Management
### Development
```bash theme={null}
# .env.development
MOORCHEH_API_KEY=dev_key_here
```
### Testing
```bash theme={null}
# .env.test
MOORCHEH_API_KEY=test_key_here
```
### Production
Use a secrets manager:
**AWS Secrets Manager:**
```python theme={null}
import boto3
client = boto3.client('secretsmanager')
secret = client.get_secret_value(SecretId='memanto/moorcheh-key')
api_key = secret['SecretString']
```
**HashiCorp Vault:**
```python theme={null}
import hvac
client = hvac.Client(url='https://vault.example.com')
secret = client.secrets.kv.read_secret_version(path='memanto/moorcheh-key')
api_key = secret['data']['data']['api_key']
```
**Azure Key Vault:**
```python theme={null}
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
credential = DefaultAzureCredential()
client = SecretClient(vault_url="https://myvault.vault.azure.net/", credential=credential)
secret = client.get_secret("moorcheh-api-key")
api_key = secret.value
```
## Troubleshooting
### "Invalid API Key" Error
```bash theme={null}
# Check your key is correct
echo $MOORCHEH_API_KEY
# Verify it starts with
# Get a new key if needed from console.moorcheh.ai
```
### "Connection Refused" Error
```bash theme={null}
# Check Moorcheh status
curl https://api.moorcheh.ai/v1/health
# If Moorcheh is down, check status page
# https://status.moorcheh.ai
```
### "Rate Limited" Error
You've exceeded quota. Free tier includes 500 credits/month.
**Solutions:**
1. Wait for next month's reset
2. Upgrade to paid plan
3. Optimize your agent to use fewer operations
### "Unauthorized" Error
API key is not being passed correctly.
**Check:**
```bash theme={null}
# Verify key is in environment
echo $MOORCHEH_API_KEY
# Check header format
# Should be: Authorization: Bearer your_key
```
## Using Sovereign Moorcheh
For enterprises requiring data residency:
1. Contact [sales@moorcheh.ai](mailto:sales@moorcheh.ai)
2. Deploy Moorcheh to your VPC:
* AWS (Terraform templates provided)
* GCP (Cloud Deployment Manager templates provided)
3. Get a private endpoint URL
4. Configure your clients to use it:
```bash theme={null}
export MOORCHEH_BASE_URL=https://moorcheh.your-company.internal
export MOORCHEH_API_KEY=your_key
```
## Architecture Benefits
### For Memanto Users
1. **Fast onboarding** - Memanto provides a ready-made memory layer while Moorcheh handles semantic retrieval.
2. **Immediate recall after writes** - New memories become searchable without indexing delays.
3. **Deterministic retrieval behavior** - Stable search behavior helps with predictable agent outputs.
### For Application Teams
1. **Instant Memory Availability** - No waiting for indexing
2. **Predictable Performance** - Same query = same result every time
3. **Affordable Scaling** - Costs don't increase with scale
4. **Simple Deployment** - No infrastructure to manage
### For Developers
1. **Easy Integration** - Just an API key, no setup
2. **Reliable** - No indexing issues or rebalancing
3. **Cost-Effective** - Perfect for startups and projects
4. **Deterministic** - Easier to debug than probabilistic systems
## Best Practices
### DO
* Store API keys in environment variables
* Rotate keys regularly
* Use secrets manager for production
### DON'T
* Commit keys to Git
* Share keys in Slack/Email
* Hardcode keys in client code
## Next Steps
* **Configure Memanto with your key**: [Installation Guide](../getting-started/installation)
* **Moorcheh Console**: [https://console.moorcheh.ai](https://console.moorcheh.ai)
* **Moorcheh Website**: [https://moorcheh.ai](https://moorcheh.ai)
***
All set! Your Moorcheh account and API key are ready to use.
# Session Management
Source: https://docs.memanto.ai/guides/session-management
Activate, inspect, and deactivate agent sessions.
# Session Management
Sessions control when agents are active and gate memory operations behind a short-lived token.
## Understanding Sessions
### Session Basics
A **session** is a time-bounded window (configured server-side, default \~6 hours) where:
* The agent can store and retrieve memories
* The session token authenticates memory operations
* Memories persist after the session ends
* Multiple sessions can exist over time
Sessions serve two core purposes:
1. **Authorization** — the session token proves your client is allowed to perform memory operations against a specific agent.
2. **State boundaries** — sessions create a clear active/inactive boundary for long-running workflows and produce a per-session summary on deactivation.
The Moorcheh API key is configured **on the Memanto server** (`MOORCHEH_API_KEY`). Clients never send it. The only client-side credential is the `X-Session-Token` header, used on memory endpoints.
### Session Properties
Each session includes:
* **session\_id** — unique identifier
* **session\_token** — JWT used in `X-Session-Token`
* **agent\_id** — which agent the session is bound to
* **namespace** — `memanto_agent_{agent_id}`
* **started\_at** / **expires\_at** — lifetime
* **pattern** — `support`, `project`, or `tool`
* **status** — `active`, `expired`, or `terminated`
### Session Lifecycle
```
Activate → Use (until expiry, auto-renewed near expiry) → Deactivate
```
### Session States
```text theme={null}
+-----------------------------------------+
| ACTIVE |
| - Can store memories |
| - Can recall memories |
| - Session token valid |
+-----------------+-----------------------+
|
(token expires or deactivate)
v
+-----------------------------------------+
| INACTIVE |
| - Memories still exist |
| - Cannot access without new session |
| - Can reactivate anytime |
+-----------------------------------------+
```
## Managing Sessions
Sessions can be activated, inspected, and deactivated using the CLI or REST API.
* **CLI Reference**: see [activate](/cli/sessions/activate), [info](/cli/sessions/info), [deactivate](/cli/sessions/deactivate).
* **API Reference**: see [Activate Agent](/api-reference/sessions/activate-agent), [Get Current Session](/api-reference/sessions/get-current-session), [Deactivate Agent](/api-reference/sessions/deactivate-agent).
## Session Token Management
### Token Handling
A session token is a JWT returned when activating an agent. It carries the agent ID and expiry, and must be sent with all memory operations:
```python theme={null}
import httpx
headers = {
"X-Session-Token": session_token,
"Content-Type": "application/json",
}
response = httpx.post(
f"http://localhost:8000/api/v2/agents/{agent_id}/remember",
headers=headers,
json={"content": "...", "type": "fact"},
)
```
### Automatic Token Refresh
Memanto auto-renews sessions that are near expiry on the next memory request — no separate "extend" call is needed. The CLI inherits this behavior:
```bash theme={null}
memanto status # if the session is near expiry, Memanto renews it
```
For API clients, simply keep using the current `session_token`; if Memanto renews it, the next response carries the refreshed expiration. If the token has fully expired (`401`), call `/activate` again to obtain a new one.
## Multi-Session Patterns
### Sequential Sessions
Same agent, different times:
```
Session 1 (Day 1) → Store facts about customer
↓ (session ends)
Session 2 (Day 1 later) → Recall facts, add new info
↓ (session ends)
Session 3 (Day 2) → Continue with full context
```
All memories persist across sessions.
### Session vs Memory
Sessions are temporary. Memories are persistent.
```
Session A ends
↓
Memories remain
↓
Session B can still recall them
```
### Parallel Sessions
Different agents, same time:
```python theme={null}
import httpx
agents = ["customer-support", "billing-bot", "technical-support"]
sessions = {}
for agent_id in agents:
response = httpx.post(
f"http://localhost:8000/api/v2/agents/{agent_id}/activate"
)
sessions[agent_id] = response.json()["session_token"]
# Now can use all agents simultaneously
for agent_id, token in sessions.items():
# Perform operations with each agent using token in X-Session-Token
...
```
## Session Persistence
### Across Runs
Session information is tracked under `~/.memanto/sessions/` on the server, and the CLI cached state allows the same active session to be picked up across runs.
### Explicit Session Management
For long-running processes, use this pattern:
1. Try the existing token.
2. On `401 Unauthorized`, activate a new session.
3. Cache and continue.
```python theme={null}
import httpx
def ensure_session(agent_id: str, token: str | None) -> str:
if token and is_token_valid(token):
return token
resp = httpx.post(
f"http://localhost:8000/api/v2/agents/{agent_id}/activate"
)
return resp.json()["session_token"]
```
## Session Timeouts & Limits
### Default Duration
* **Standard session**: configured server-side via `SESSION_DEFAULT_DURATION_HOURS` (typically 6 hours).
* **Auto-renewal**: Memanto extends sessions near expiry automatically when memory requests are made.
* **Manual renewal**: re-activate the agent to obtain a fresh token.
### Handling Expiry
On `401 Unauthorized`, treat the token as expired:
```python theme={null}
import httpx
resp = httpx.post(url, headers=headers, json=body)
if resp.status_code == 401:
new_token = httpx.post(
f"http://localhost:8000/api/v2/agents/{agent_id}/activate"
).json()["session_token"]
headers["X-Session-Token"] = new_token
resp = httpx.post(url, headers=headers, json=body)
```
## Best Practices
### DO
* Let Memanto auto-renew sessions; only re-activate after a hard `401`
* Store session tokens in process memory, not on disk
* Deactivate sessions when a workflow finishes to capture a session summary
### DON'T
* Create a new session for every request
* Send the Moorcheh API key from clients (Memanto reads it server-side)
* Reuse a session token across different agents
## Next Steps
* **Memory Operations**: [Memory Operations Guide](./memory-operations)
* **CLI Reference**: [Session commands](/cli/sessions/activate)
* **API Reference**: [Session endpoints](/api-reference/sessions/activate-agent)
***
Session management ensures reliable, long-running agent operations. Master it for production reliability!
# Temporal Memory
Source: https://docs.memanto.ai/guides/temporal-memory
Query memories as of a specific point in time, since a given date, or by recency.
# Temporal Memory
Query memories from specific points in time using temporal queries. All temporal endpoints are `POST` and accept a JSON body. Authentication uses `X-Session-Token` only — clients do not send a Moorcheh API key.
## Temporal Queries
Memanto supports three time-based query variants:
### 1. As Of (Point in Time)
Return memories that were valid at a specific moment, excluding memories created after that moment or expired before it:
```
Query: "What did we know on May 1?"
Result: Memories valid as of May 1 — created before that date,
not expired before it.
```
**Use case:** Historical audit trail.
```python theme={null}
import httpx
response = httpx.post(
f"{base}/agents/{agent}/recall/as-of",
headers={"X-Session-Token": session_token, "Content-Type": "application/json"},
json={
"as_of": "2026-05-01T14:00:00Z",
"type": ["fact", "decision"],
},
)
```
There is **no `query` parameter** for `/recall/as-of`; results are listed chronologically. Use `type` to narrow the listing server-side.
### 2. Changed Since (Time Range)
Return memories created or updated after a given timestamp:
```
Query: "What changed in the last 7 days?"
Result: All memories created or updated since that date.
```
**Use case:** Recent updates and changes.
```python theme={null}
import httpx
response = httpx.post(
f"{base}/agents/{agent}/recall/changed-since",
headers={"X-Session-Token": session_token, "Content-Type": "application/json"},
json={
"since": "2026-05-01",
"limit": 50,
},
)
```
There is **no `query` parameter** for `/recall/changed-since`; results are sorted by `updated_at` descending. Each item carries a `change_type` field (`"created"` or `"updated"`). Use `type` to narrow by memory type.
### 3. Recent (Newest-First)
Return the most recently stored memories, sorted by `created_at` descending. Useful when you want the latest context without a semantic query:
```
Result: The N latest memories for the agent (optionally filtered by type).
```
**Use case:** "What did the agent learn most recently?"
```python theme={null}
import httpx
response = httpx.post(
f"{base}/agents/{agent}/recall/recent",
headers={"X-Session-Token": session_token, "Content-Type": "application/json"},
json={"limit": 10, "type": ["fact", "decision"]},
)
```
There is **no `query` parameter** for `/recall/recent`; results are purely chronological.
## Time Format
Temporal endpoints accept ISO 8601 (with UTC) or date-only:
```
2026-05-09T16:30:00Z ← full ISO 8601
2026-05-09 ← date-only
/recall/as-of: end-of-day UTC
/recall/changed-since: start-of-day UTC
```
## Use Cases
### 1. Audit Trail
Verify what was known at a specific time:
```python theme={null}
import httpx
response = httpx.post(
f"{base}/agents/support/recall/as-of",
headers=headers,
json={
"as_of": "2026-05-01T00:00:00Z",
"type": ["fact"],
},
)
```
### 2. Change Tracking
See what changed during a project window:
```python theme={null}
import httpx
response = httpx.post(
f"{base}/agents/project/recall/changed-since",
headers=headers,
json={
"since": "2026-05-01",
"limit": 50,
},
)
```
### 3. Latest Activity
Pull the most recent memories without a query:
```python theme={null}
import httpx
response = httpx.post(
f"{base}/agents/project/recall/recent",
headers=headers,
json={"limit": 10},
)
# Returns the 10 newest memories, sorted newest-first
```
### 4. Time Series Analysis
Track how information changed over time:
```python theme={null}
import httpx
dates = ["2026-04-01", "2026-04-15", "2026-05-01"]
for date in dates:
response = httpx.post(
f"{base}/agents/project/recall/as-of",
headers=headers,
json={"as_of": date},
)
memories = response.json().get("memories", [])
if memories:
print(f"{date}: {memories[0]['content']}")
```
### 5. Regression Detection
Find when something changed:
```python theme={null}
import httpx
test_dates = ["2026-04-20", "2026-04-25", "2026-05-01"]
for date in test_dates:
response = httpx.post(
f"{base}/agents/support/recall/as-of",
headers=headers,
json={"as_of": date},
)
memories = response.json().get("memories", [])
if memories:
print(f"{date}: {memories[0]['content']}")
```
## Memory Versioning
Superseding a memory is a **delete-and-recreate**, not a status flip: resolving a conflict removes the memory you didn't keep and writes the surviving one. Every stored memory has `status: "active"`. Temporal queries reconstruct history from `created_at` / `updated_at`, so `recall/as-of` still reflects the state that existed at the queried timestamp.
```
Memory A
└─ Created: 2026-04-20
Content: "Project deadline: April 30"
Memory B (written during conflict resolution; A is deleted)
└─ Created: 2026-04-25
Content: "Project deadline: May 15 (extended)"
"As of" Queries:
└─ Before April 25: returns Memory A as it was
└─ After April 25: returns Memory B
```
## Best Practices
### DO
* Use ISO 8601 timestamps for precision
* Resolve conflicts explicitly via [Resolve Conflict](/api-reference/data/resolve-conflicts)
* Use `/recall/recent` to surface fresh context quickly
### DON'T
* Delete old memories by hand — go through conflict resolution so the replacement is recorded
* Ignore temporal information when results look ambiguous
* Mix old and new data without checking `created_at`
## Next Steps
* [Memory Operations](/guides/memory-operations)
* [Recall As Of](/api-reference/search/recall-as-of)
* [Recall Changed Since](/api-reference/search/recall-changed-since)
* [Recall Recent](/api-reference/search/recall-recent)
# Antigravity
Source: https://docs.memanto.ai/integrations/antigravity
Give Google Antigravity persistent, cross-session memory with Memanto.
# Antigravity + Memanto
![Antigravity]()
Connect [Google Antigravity](https://antigravity.google) to Memanto so it can store and recall persistent memory across sessions.
## Connect via CLI (recommended)
```bash theme={null}
memanto connect antigravity
```
This installs an Antigravity-specific instruction file and the `memanto-memory` skill into your project. Add `--global` to install system-wide:
```bash theme={null}
memanto connect antigravity --global
```
## Connect via MCP
Antigravity supports MCP, so you can alternatively register Memanto as an MCP server. See the [MCP integration guide](/integrations/mcp) for the `memanto-mcp` server reference and config.
## Next Steps
* [CLI: connect command](/cli/connect/connect)
* [MCP Integration](/integrations/mcp)
* [Memory Types Reference](/reference/memory-types)
# Augment
Source: https://docs.memanto.ai/integrations/augment
Give Augment Code persistent, cross-session memory with Memanto.
# Augment + Memanto
Connect [Augment Code](https://augmentcode.com) to Memanto so it can store and recall persistent memory across sessions.
## Connect via CLI (recommended)
```bash theme={null}
memanto connect augment
```
This installs an Augment-specific instruction file and the `memanto-memory` skill into your project. Add `--global` to install system-wide:
```bash theme={null}
memanto connect augment --global
```
## Connect via MCP
Augment supports MCP, so you can alternatively register Memanto as an MCP server. See the [MCP integration guide](/integrations/mcp) for the `memanto-mcp` server reference and config.
## Next Steps
* [CLI: connect command](/cli/connect/connect)
* [MCP Integration](/integrations/mcp)
* [Memory Types Reference](/reference/memory-types)
# Claude Code
Source: https://docs.memanto.ai/integrations/claude-code
Give Anthropic Claude Code persistent, cross-session memory with Memanto.
# Claude Code + Memanto
![Claude Code]()
Connect [Claude Code](https://claude.com/claude-code) to Memanto so it can store facts, decisions, and preferences and recall them across sessions.
## Connect via CLI (recommended)
```bash theme={null}
memanto connect claude-code
```
This installs a `CLAUDE.md` instruction file and the `memanto-memory` skill into your project. Add `--global` to install to `~/.claude/` for every project:
```bash theme={null}
memanto connect claude-code --global
```
Output:
```
✓ Memanto connected to Claude Code
Scope: Local
Path: /project/.claude/
Status: Ready to use
```
## Connect via MCP
Claude Code is an MCP client, so you can alternatively register Memanto as an MCP server rather than a skill file. See the [MCP integration guide](/integrations/mcp) for the `memanto-mcp` server reference and config.
## Next Steps
* [CLI: connect command](/cli/connect/connect)
* [MCP Integration](/integrations/mcp)
* [Memory Types Reference](/reference/memory-types)
# Cline
Source: https://docs.memanto.ai/integrations/cline
Give the Cline VS Code extension persistent, cross-session memory with Memanto — via the CLI connector or as an MCP server.
# Cline + Memanto
![Cline]()
Connect the [Cline](https://cline.bot) VS Code extension to Memanto so it can store and recall persistent memory across sessions.
## Connect via CLI (recommended)
```bash theme={null}
memanto connect cline
```
This installs a Cline-specific instruction file and the `memanto-memory` skill into your project. Add `--global` to install system-wide:
```bash theme={null}
memanto connect cline --global
```
## Connect via MCP
Cline is an MCP client, so you can alternatively register Memanto as an MCP server. Edit `cline_mcp_settings.json`:
* **Linux**: `~/.config/Code/User/globalStorage/cline.cline/settings/cline_mcp_settings.json`
* **macOS**: `~/Library/Application Support/Code/User/globalStorage/cline.cline/settings/cline_mcp_settings.json`
* **Windows**: `%APPDATA%\Code\User\globalStorage\cline.cline\settings\cline_mcp_settings.json`
```json theme={null}
{
"mcpServers": {
"memanto": {
"command": "memanto-mcp",
"env": {
"MOORCHEH_API_KEY": "mch_xxxxxxxxxxxxxxxxxx",
"MEMANTO_DEFAULT_AGENT_ID": "cline-workspace"
}
}
}
}
```
See the [MCP integration guide](/integrations/mcp) for the full server reference.
## Next Steps
* [CLI: connect command](/cli/connect/connect)
* [MCP Integration](/integrations/mcp)
* [Memory Types Reference](/reference/memory-types)
# Codex
Source: https://docs.memanto.ai/integrations/codex
Give the OpenAI Codex CLI persistent, cross-session memory with Memanto.
# Codex + Memanto
![Codex]()
Connect the [OpenAI Codex CLI](https://github.com/openai/codex) to Memanto so it can store and recall persistent memory across sessions.
## Connect via CLI (recommended)
```bash theme={null}
memanto connect codex
```
This installs a Codex-specific instruction file and the `memanto-memory` skill into your project. Add `--global` to install system-wide:
```bash theme={null}
memanto connect codex --global
```
## Connect via MCP
Codex supports MCP, so you can alternatively register Memanto as an MCP server. See the [MCP integration guide](/integrations/mcp) for the `memanto-mcp` server reference and config.
## Next Steps
* [CLI: connect command](/cli/connect/connect)
* [MCP Integration](/integrations/mcp)
* [Memory Types Reference](/reference/memory-types)
# Continue
Source: https://docs.memanto.ai/integrations/continue
Give Continue.dev persistent, cross-session memory with Memanto — via the CLI connector or as an MCP server.
# Continue + Memanto
Connect [Continue.dev](https://continue.dev) to Memanto so it can store and recall persistent memory across sessions.
## Connect via CLI (recommended)
```bash theme={null}
memanto connect continue
```
This installs a Continue-specific instruction file and the `memanto-memory` skill into your project. Add `--global` to install system-wide:
```bash theme={null}
memanto connect continue --global
```
## Connect via MCP
Continue is an MCP client, so you can alternatively register Memanto as an MCP server. Edit `~/.continue/config.json`:
```json theme={null}
{
"experimental": {
"modelContextProtocolServers": [
{
"transport": {
"type": "stdio",
"command": "memanto-mcp",
"env": {
"MOORCHEH_API_KEY": "mch_xxxxxxxxxxxxxxxxxx",
"MEMANTO_DEFAULT_AGENT_ID": "continue-workspace"
}
}
}
]
}
}
```
See the [MCP integration guide](/integrations/mcp) for the full server reference.
## Next Steps
* [CLI: connect command](/cli/connect/connect)
* [MCP Integration](/integrations/mcp)
* [Memory Types Reference](/reference/memory-types)
# CrewAI
Source: https://docs.memanto.ai/integrations/crewai
Integrate Memanto persistent memory into CrewAI agent workflows.
# CrewAI + Memanto
![CrewAI]()
Give your CrewAI agents persistent, cross-session memory powered by Memanto using the official `crewai-memanto` package.
By default, CrewAI agents lose context when a crew run ends. With Memanto, agents can store facts, decisions, and preferences � and recall them in future runs.
> **Important**: We recommend explicitly setting `memory=False` on your CrewAI `Crew` objects. This prevents CrewAI from auto-injecting its own temporary LanceDB memory tools, which can confuse agents when mixed with Memanto's persistent memory tools.
## How It Works
```text theme={null}
CrewAI Agent ? Memanto Tools (remember / recall / answer) ? Memanto Server ? Moorcheh.ai
```
Each agent in your crew gets access to three tools: one to store memories, one to search them, and one to get a synthesized answer directly from memory. Memanto handles the semantic layer � no vector DB setup required.
## Prerequisites
* Python 3.10+
* [Moorcheh API key](https://console.moorcheh.ai/api-keys) (free tier: 100K ops/month)
* [OpenRouter API key](https://openrouter.ai/keys) (for CrewAI's LLM � free tier available)
## Install
```bash theme={null}
pip install crewai-memanto
```
## Quick Start
The `crewai-memanto` package provides pre-built tools that wrap Memanto's SDK. You don't need to make HTTP requests manually.
```python theme={null}
import os
from crewai import Agent, Task, Crew
from crewai_memanto import MemantoSetup, create_memanto_tools
# 1. Set up Memanto (one-time per session)
api_key = os.getenv("MOORCHEH_API_KEY")
setup = MemantoSetup(api_key=api_key)
client = setup.setup(agent_id="my-crew-agent")
# 2. Create memory tools bound to your agent
tools = create_memanto_tools(client, agent_id="my-crew-agent")
# 3. Give agents Memanto tools
researcher = Agent(
role="Research Analyst",
goal="Gather and store key facts about the topic",
backstory="You are thorough and always save important findings for future reference.",
tools=[tools["remember"], tools["recall"]], # Persistent memory!
verbose=True
)
writer = Agent(
role="Content Writer",
goal="Write a report using previously stored research",
backstory="You rely on stored research to write accurate, grounded content.",
tools=[tools["recall"], tools["answer"]], # Reads persistent memory!
verbose=True
)
research_task = Task(
description="Research the latest trends in AI agents and store 5 key findings.",
expected_output="Confirmation that 5 findings have been stored in memory.",
agent=researcher
)
write_task = Task(
description="Recall the stored AI agent findings and write a concise summary report.",
expected_output="A 3-paragraph summary report grounded in recalled memory.",
agent=writer
)
# 4. Run the crew with memory=False to prevent dual memory systems
crew = Crew(
agents=[researcher, writer],
tasks=[research_task, write_task],
memory=False, # Memanto handles memory via tools
verbose=True
)
result = crew.kickoff()
print(result)
```
## Available Tools
The `create_memanto_tools` function returns a dictionary containing these pre-built CrewAI tools:
### `remember` (MemantoRememberTool)
Allows agents to store a piece of information in long-term memory.
* **Smart Categorization**: The tool schema has definitions for all 13 Memanto memory types (e.g., `fact`, `preference`, `observation`) baked directly into the prompt. The LLM intrinsically understands how to categorize what it discovers without you needing to explicitly define the types in your CrewAI `Task` description.
* **Confidence Scoring**: The agent is forced to actively evaluate its certainty on every memory it stores, assigning a mandatory confidence score between 0.0 (unverified) and 1.0 (objective fact).
* **Capacity**: Agents can store up to 10,000 characters per memory block.
### `recall` (MemantoRecallTool)
Allows agents to search long-term memory for relevant information using semantic search. Best used when the agent needs raw memory items to reason over.
### `answer` (MemantoAnswerTool)
Uses Memanto's built-in RAG to synthesize a response directly from stored memories � no extra LLM call needed from your agent.
> **Tip**: Use `answer` when the agent needs a ready-to-use response, such as for a final task output or a direct reply to a user, and use `recall` when they just need the raw data.
## Persistent Memory Across Runs
Because memories live in Memanto (not in-process), they persist between separate crew runs. Additionally, the integration handles all backend infrastructure automatically � you never need to manually provision databases or namespaces; the integration auto-creates the required secure Moorcheh namespaces the moment you initialize `MemantoSetup`.
```python theme={null}
# Run 1: researcher stores findings
crew.kickoff()
# Run 2 (next day): writer recalls those same findings
crew.kickoff()
```
No extra configuration needed � the `agent_id` ties memories together across runs.
## Next Steps
* [Check out the Full Examples Directory](https://github.com/moorcheh-ai/memanto/tree/main/examples/crewai-memory)
* [Remember API](/api-reference/data/remember)
* [Recall API](/api-reference/search/recall)
* [Memory Types Reference](/reference/memory-types)
# Cursor
Source: https://docs.memanto.ai/integrations/cursor
Give Cursor persistent, cross-session memory with Memanto — via the CLI connector or as an MCP server.
# Cursor + Memanto
![Cursor]()
Connect [Cursor](https://cursor.com) to Memanto so it can store facts, decisions, and preferences and recall them across sessions.
## Connect via CLI (recommended)
```bash theme={null}
memanto connect cursor
```
This installs a Cursor-specific rules file (`.cursor/rules/memanto.mdc`) and the `memanto-memory` skill into your project. Add `--global` to install to `~/.cursor/` for every project:
```bash theme={null}
memanto connect cursor --global
```
## Connect via MCP
Cursor is an MCP client, so you can alternatively register Memanto as an MCP server. Edit `~/.cursor/mcp.json` (per-user) or `.cursor/mcp.json` (per-project):
```json theme={null}
{
"mcpServers": {
"memanto": {
"command": "memanto-mcp",
"env": {
"MOORCHEH_API_KEY": "mch_xxxxxxxxxxxxxxxxxx",
"MEMANTO_DEFAULT_AGENT_ID": "cursor-workspace"
}
}
}
}
```
Reload Cursor and confirm `memanto` shows up with **7 tools**. See the [MCP integration guide](/integrations/mcp) for the full server reference.
## Next Steps
* [CLI: connect command](/cli/connect/connect)
* [MCP Integration](/integrations/mcp)
* [Memory Types Reference](/reference/memory-types)
# Gemini CLI
Source: https://docs.memanto.ai/integrations/gemini-cli
Give the Google Gemini CLI persistent, cross-session memory with Memanto.
# Gemini CLI + Memanto
![Gemini CLI]()
Connect the [Google Gemini CLI](https://github.com/google-gemini/gemini-cli) to Memanto so it can store and recall persistent memory across sessions.
## Connect via CLI (recommended)
```bash theme={null}
memanto connect gemini-cli
```
This installs a Gemini-specific instruction file and the `memanto-memory` skill into your project. Add `--global` to install system-wide:
```bash theme={null}
memanto connect gemini-cli --global
```
## Connect via MCP
Gemini CLI supports MCP, so you can alternatively register Memanto as an MCP server. See the [MCP integration guide](/integrations/mcp) for the `memanto-mcp` server reference and config.
## Next Steps
* [CLI: connect command](/cli/connect/connect)
* [MCP Integration](/integrations/mcp)
* [Memory Types Reference](/reference/memory-types)
# GitHub Copilot
Source: https://docs.memanto.ai/integrations/github-copilot
Give GitHub Copilot persistent, cross-session memory with Memanto.
# GitHub Copilot + Memanto
![GitHub Copilot]()
Connect [GitHub Copilot](https://github.com/features/copilot) to Memanto so it can store and recall persistent memory across sessions.
## Connect via CLI (recommended)
```bash theme={null}
memanto connect github-copilot
```
This installs a Copilot-specific instruction file and the `memanto-memory` skill into your project. Add `--global` to install system-wide:
```bash theme={null}
memanto connect github-copilot --global
```
## Connect via MCP
GitHub Copilot supports MCP, so you can alternatively register Memanto as an MCP server. See the [MCP integration guide](/integrations/mcp) for the `memanto-mcp` server reference and config.
## Next Steps
* [CLI: connect command](/cli/connect/connect)
* [MCP Integration](/integrations/mcp)
* [Memory Types Reference](/reference/memory-types)
# Goose
Source: https://docs.memanto.ai/integrations/goose
Give the Goose AI agent persistent, cross-session memory with Memanto — via the CLI connector or as an MCP extension.
# Goose + Memanto
![Goose]()
Connect the [Goose](https://block.github.io/goose/) AI agent to Memanto so it can store and recall persistent memory across sessions.
## Connect via CLI (recommended)
```bash theme={null}
memanto connect goose
```
This installs a Goose-specific instruction file and the `memanto-memory` skill into your project. Add `--global` to install system-wide:
```bash theme={null}
memanto connect goose --global
```
## Connect via MCP
Goose speaks MCP, so you can alternatively register Memanto as an extension. Edit `~/.config/goose/config.yaml`:
```yaml theme={null}
extensions:
memanto:
type: stdio
command: memanto-mcp
envs:
MOORCHEH_API_KEY: mch_xxxxxxxxxxxxxxxxxx
MEMANTO_DEFAULT_AGENT_ID: goose-workspace
```
See the [MCP integration guide](/integrations/mcp) for the full server reference.
## Next Steps
* [CLI: connect command](/cli/connect/connect)
* [MCP Integration](/integrations/mcp)
* [Memory Types Reference](/reference/memory-types)
# Hermes Agent
Source: https://docs.memanto.ai/integrations/hermes-agents
Give the Hermes agent typed long-term memory with semantic recall, automatic turn capture, and RAG answers — one pip install, one config line.
# Hermes + Memanto
![Hermes]()
The [`hermes-memanto`](https://pypi.org/project/hermes-memanto/) package is a **memory-agent provider** for the [Hermes agent](https://github.com/NousResearch/hermes-agent). It gives Hermes typed long-term memory backed by [Memanto](https://memanto.ai) and the [Moorcheh](https://moorcheh.ai) semantic platform — semantic recall across sessions, automatic turn capture, RAG-style answers, and per-profile memory isolation.
> Unlike a passive "memory layer", every namespace in Memanto is a first-class **agent** (`memanto agent create/activate`). This provider maps **one Hermes identity to one Memanto agent**, so each profile gets its own persistent memory.
Relevant memories are retrieved and injected into context before each turn — no tool call required.
Meaningful conversation turns are stored as `event` memories in the background; trivial acknowledgements are skipped.
`memanto_remember`, `memanto_recall`, and `memanto_answer` let Hermes manage memory deliberately when it needs to.
`agent_id: hermes-{identity}` scopes memory per Hermes profile — `{identity}` expands to the profile name at startup.
## How It Works
```
┌──────────────┐ register(ctx) ┌──────────────────┐ HTTPS + API key ┌─────────────┐
│ Hermes │ ────────────────► │ memanto plugin │ ──────────────────► │ Moorcheh │
│ agent │ ◄──────────────── │ (this provider) │ ◄────────────────── │ Service │
└──────────────┘ recall / capture └──────────────────┘ no-indexing search └─────────────┘
```
Hermes discovers memory providers as **directories** under `$HERMES_HOME/plugins//`, each holding an `__init__.py` that exposes `register(ctx)` plus a `plugin.yaml`. This package ships exactly that, plus an installer that drops it into place. On first use the provider activates a Memanto session (auto-creating the agent if needed) and reuses it for the run.
## Prerequisites
* Python **3.10+**
* A running [Hermes agent](https://github.com/NousResearch/hermes-agent) install
* A [Moorcheh API key](https://console.moorcheh.ai/api-keys) (free tier: 100K ops/month)
## Install
This pulls in the `memanto` SDK as a dependency.
```bash theme={null}
pip install hermes-memanto
```
The bundled console script copies a self-contained plugin into `~/.hermes/plugins/memanto/`.
```bash theme={null}
hermes-memanto-install
```
Flags: `--hermes-home /path/to/.hermes` (defaults to `$HERMES_HOME` or `~/.hermes`) and `--force` to overwrite an existing install.
```bash theme={null}
export MOORCHEH_API_KEY=your_key_xxxxxxxxxxxxxxxxxx # https://console.moorcheh.ai/api-keys
hermes config set memory.provider memanto
```
`hermes memory setup` also lists **memanto** once the plugin is installed, walks you through configuration, and writes `MOORCHEH_API_KEY` into `~/.hermes/.env` for you.
The first memory call **auto-creates** the agent and namespace; every subsequent call reuses the same persistent memory.
### From a source checkout
```bash theme={null}
git clone https://github.com/moorcheh-ai/memanto.git
cd memanto/integrations/hermes-agents
pip install -e .
hermes-memanto-install # or: hermes-memanto-install --hermes-home /path/to/.hermes
```
The installer copies `hermes_memanto/provider.py` verbatim as the plugin's `__init__.py`, so the installed plugin is self-contained and only needs the `memanto` SDK at runtime (declared in its `plugin.yaml`).
Memory providers are auto-detected as **exclusive** and selected via `memory.provider` — **not** `hermes plugins enable`. Just run `hermes config set memory.provider memanto`.
## Tools Exposed to Hermes
The provider registers three tools with Hermes:
| Tool | When Hermes should call it |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `memanto_remember` | Persist a durable fact, preference, decision, goal, or instruction — with optional `type`, `tags`, and `confidence`. |
| `memanto_recall` | Semantic search across the agent's memory. Use this **first**, before asking the user to repeat stable info. Supports a `type` filter and `limit` (1–100). |
| `memanto_answer` | A grounded RAG answer synthesized **only** over stored memories — no extra LLM key required. Prefer over `recall` when you need a synthesized answer rather than a ranked list. |
`fact`, `preference`, `goal`, `decision`, `artifact`, `learning`, `event`, `instruction`, `relationship`, `context`, `observation`, `commitment`, `error`.
See the [Memory Types Reference](/reference/memory-types) for guidance on picking the right type. If Hermes omits the `type`, the provider infers one from the content.
`explicit_statement`, `inferred`, `corrected`, `validated`, `observed`, `imported`.
Tool writes are tagged `explicit_statement`; automatically captured turns are tagged `observed`.
## Automatic Memory (no tool calls required)
Beyond the explicit tools, the provider keeps memory in sync on its own:
* **Auto-recall** — before each turn, relevant memories are retrieved and injected into context inside a `` block. Tunable via `max_recall_results` and `min_confidence`.
* **Turn capture** — meaningful conversation turns are stored as `event` memories in the background. Trivial acknowledgements (`ok`, `thanks`, …) and very short messages are skipped.
* **Memory mirroring** — Hermes' built-in `memory` writes are echoed into Memanto, so manual saves and automatic recall share one store.
* **Profile isolation** — `agent_id: hermes-{identity}` scopes memory per Hermes profile; `{identity}` expands to the profile name at startup.
## Configuration
After install, settings live in `$HERMES_HOME/memanto.json`:
| Key | Default | Description |
| ------------------------ | ------------------- | ------------------------------------------------------------------------------------- |
| `agent_id` | `hermes-{identity}` | Memanto agent id (memory namespace). `{identity}` expands to the Hermes profile name. |
| `pattern` | `tool` | Agent pattern used when auto-creating: `support`, `project`, or `tool`. |
| `auto_recall` | `true` | Inject relevant memories before each turn. |
| `auto_capture` | `true` | Store cleaned conversation turns as `event` memories. |
| `auto_create` | `true` | Create the agent on first use if it does not exist. |
| `mirror_memory_writes` | `true` | Echo Hermes' built-in `memory` writes into Memanto. |
| `max_recall_results` | `10` | Max memories formatted into prefetch context (1–100). |
| `min_confidence` | `null` | Drop recalled memories below this confidence (0.0–1.0). |
| `session_duration_hours` | `null` | Override Memanto session lifetime (1–720). |
| Environment variable | Required | Description |
| -------------------- | :------: | ------------------------------------------------------------ |
| `MOORCHEH_API_KEY` | **yes** | Moorcheh API key (powers Memanto). |
| `MEMANTO_AGENT_ID` | no | Override the agent id (takes priority over the config file). |
## Session & Lifecycle
* Sessions activate **lazily** on first use and are **warmed up in a background thread** at startup, so the first turn's recall doesn't pay agent-create + activate latency.
* A failed activation triggers a short **cooldown-and-retry** (≈60 s) rather than a permanent kill switch — a transient backend blip doesn't disable the provider for the rest of the run, but a down backend isn't re-hit on every turn either.
* Writes are automatically **disabled in non-interactive contexts** (`cron`, `flush`, `subagent`) so background runs don't pollute memory; recall still works.
* Background captures and mirrored writes **bind the active client at schedule time**, so a delayed write always lands in the session that scheduled it.
## Security & Safety
The API key lives **only** in the environment / `~/.hermes/.env` (`MOORCHEH_API_KEY`). It is never persisted to `memanto.json`, even if passed through the setup wizard.
* Recalled memory is **sanitized before injection**: the `` wrapper delimiters are stripped from stored content, so a memory that happens to contain those tags can't break out of the context block and steer later turns.
* The `memanto` SDK is imported **lazily**, so the module loads even when the package isn't installed — the provider simply reports unavailable and stays inert until a key and the SDK are present.
## Shared Memory Across Integrations
`hermes-memanto` talks to the same Moorcheh-backed Memanto agents as the sibling integrations, so memory written by one is recallable from the others when they share an `agent_id`:
| Integration | Package | What it does |
| ------------------------------------------------- | ------------------ | ----------------------------------------------------------------------- |
| [`integrations/mcp`](/integrations/mcp) | `memanto-mcp` | MCP server for any MCP-compatible client (Claude, Cursor, Windsurf, …). |
| [`integrations/crewai`](/integrations/crewai) | `crewai-memanto` | CrewAI tools for multi-agent memory sharing. |
| `integrations/hermes-agents` | `hermes-memanto` | **This** — a memory provider for the Hermes agent. |
| [`integrations/langfuse`](/integrations/langfuse) | `langfuse-memanto` | Turns Langfuse errors and anomalies into memories. |
## Development
```bash theme={null}
pip install -e ".[dev]"
pytest # provider unit tests (no network; SdkClient is faked)
ruff check .
```
## Try It
Start Hermes and tell it *"remember that I prefer concise answers"*. In a brand-new session tomorrow, ask *"what do I prefer?"* — Hermes recalls it before you finish typing.
## Next Steps
Learn which memory type to pick for each piece of information.
Create, activate, and switch Memanto agents.
The REST endpoint the `memanto_remember` tool wraps.
The REST endpoint the `memanto_recall` tool wraps.
***
**Links**
* [`hermes-memanto` on PyPI](https://pypi.org/project/hermes-memanto/)
* [Memanto on GitHub](https://github.com/moorcheh-ai/memanto)
* [Hermes agent](https://github.com/NousResearch/hermes-agent)
# LangChain
Source: https://docs.memanto.ai/integrations/langchain
Add persistent memory to LangChain agents using Memanto.
# LangChain + Memanto
![LangChain]()
Add persistent, cross-session memory to your LangChain agents and chains using Memanto.
LangChain built-in memory classes reset between runs. Memanto plugs in as a custom memory backend that stores and retrieves context semantically so your chains remember what matters, even days later.
## How It Works
```
LangChain Chain / Agent -> MemantoMemory -> Memanto Server -> Moorcheh.ai
```
You drop `MemantoMemory` in wherever LangChain expects a `BaseMemory`. It handles session activation, storing new messages, and injecting recalled context into your prompts.
The Moorcheh API key (`MOORCHEH_API_KEY`) is configured on the **Memanto server**, not in your LangChain code. The only credential the client sends is `X-Session-Token`.
## Prerequisites
* Python 3.8+
* [Moorcheh API key](https://console.moorcheh.ai/api-keys) configured on the Memanto server
* Memanto server running locally
## Install
```bash theme={null}
pip install memanto langchain langchain-openai httpx
```
## Step 1: Start Memanto Server
```bash theme={null}
export MOORCHEH_API_KEY=your_moorcheh_key
memanto serve
```
## Step 2: Create the Memory Class
Create `memanto_memory.py`:
```python theme={null}
import httpx
from langchain.memory import BaseMemory
class MemantoMemory(BaseMemory):
"""LangChain-compatible memory backend powered by Memanto."""
agent_id: str = "langchain-agent"
memanto_url: str = "http://localhost:8000"
memory_key: str = "memory"
session_token: str = ""
def __init__(self, **kwargs):
super().__init__(**kwargs)
self._client = httpx.Client()
self._activate()
def _activate(self):
response = self._client.post(
f"{self.memanto_url}/api/v2/agents/{self.agent_id}/activate"
)
response.raise_for_status()
self.session_token = response.json()["session_token"]
@property
def _headers(self) -> dict:
return {
"X-Session-Token": self.session_token,
"Content-Type": "application/json",
}
@property
def memory_variables(self) -> list[str]:
return [self.memory_key]
def load_memory_variables(self, inputs: dict) -> dict:
"""Called before each LLM call - recalls relevant memories."""
query = inputs.get("input", inputs.get("human_input", ""))
if not query:
return {self.memory_key: ""}
response = self._client.post(
f"{self.memanto_url}/api/v2/agents/{self.agent_id}/recall",
headers=self._headers,
json={"query": query, "limit": 5},
)
response.raise_for_status()
memories = response.json().get("memories", [])
if not memories:
return {self.memory_key: ""}
context = "\n".join(f"- {m['content']}" for m in memories)
return {self.memory_key: f"Relevant memory:\n{context}"}
def save_context(self, inputs: dict, outputs: dict) -> None:
"""Called after each LLM call - stores the conversation turn."""
human = inputs.get("input", inputs.get("human_input", ""))
ai = outputs.get("output", outputs.get("response", ""))
if human:
self._client.post(
f"{self.memanto_url}/api/v2/agents/{self.agent_id}/remember",
headers=self._headers,
json={"content": f"User said: {human}", "type": "fact"},
)
if ai:
self._client.post(
f"{self.memanto_url}/api/v2/agents/{self.agent_id}/remember",
headers=self._headers,
json={"content": f"Assistant replied: {ai}", "type": "fact"},
)
def clear(self) -> None:
pass # Memories persist in Memanto - clear via CLI if needed
```
## Step 3: Use in a Chain
Create `agent.py`:
```python theme={null}
from langchain_openai import ChatOpenAI
from langchain.chains import ConversationChain
from langchain.prompts import PromptTemplate
from memanto_memory import MemantoMemory
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
memory = MemantoMemory(agent_id="my-assistant")
prompt = PromptTemplate(
input_variables=["memory", "input"],
template=(
"You are a helpful assistant with long-term memory.\n\n"
"{memory}\n\n"
"Human: {input}\n"
"Assistant:"
),
)
chain = ConversationChain(llm=llm, memory=memory, prompt=prompt, verbose=True)
# First run - Alice introduces herself
response = chain.invoke({"input": "My name is Alice and I prefer dark mode."})
print(response["output"])
# Second run - Memanto recalls that Alice prefers dark mode
response = chain.invoke({"input": "What UI settings should I use?"})
print(response["output"])
```
## Step 4: Run
```bash theme={null}
export OPENAI_API_KEY=sk_your_openai_key
# MOORCHEH_API_KEY is read by the Memanto server, not by this script.
python agent.py
```
## Using with LCEL (LangChain Expression Language)
Inject recalled memory directly into an LCEL pipeline:
```python theme={null}
import httpx
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnableLambda
AGENT_ID = "lcel-agent"
BASE_URL = "http://localhost:8000/api/v2"
token = httpx.post(
f"{BASE_URL}/agents/{AGENT_ID}/activate"
).json()["session_token"]
HEADERS = {"X-Session-Token": token, "Content-Type": "application/json"}
def recall_context(inputs: dict) -> dict:
resp = httpx.post(
f"{BASE_URL}/agents/{AGENT_ID}/recall",
headers=HEADERS,
json={"query": inputs["question"], "limit": 5},
)
memories = resp.json().get("memories", [])
context = "\n".join(f"- {m['content']}" for m in memories) or "No prior context."
return {**inputs, "context": context}
prompt = ChatPromptTemplate.from_messages([
("system", "You are a helpful assistant.\n\nMemory:\n{context}"),
("human", "{question}"),
])
chain = RunnableLambda(recall_context) | prompt | ChatOpenAI(model="gpt-4o-mini")
result = chain.invoke({"question": "What are my UI preferences?"})
print(result.content)
```
## Using Memanto's Built-in Answer (Optional)
For cases where you want a direct, grounded response from memory without routing through your chain, Memanto exposes an `answer` endpoint that uses its native RAG model. No external LLM call is made on your side.
This is useful as a quick lookup tool — for example, answering a simple factual question about a user before deciding whether to invoke the full chain.
```python theme={null}
import httpx
AGENT_ID = "my-assistant"
BASE_URL = "http://localhost:8000/api/v2"
token = httpx.post(
f"{BASE_URL}/agents/{AGENT_ID}/activate"
).json()["session_token"]
HEADERS = {"X-Session-Token": token, "Content-Type": "application/json"}
def memanto_answer(question: str) -> str:
"""Get a synthesized answer from stored memories using Memanto's native RAG."""
response = httpx.post(
f"{BASE_URL}/agents/{AGENT_ID}/answer",
headers=HEADERS,
json={"question": question},
)
response.raise_for_status()
return response.json().get("answer", "")
answer = memanto_answer("What UI preferences does Alice have?")
print(answer)
# -> "Alice prefers dark mode and concise responses."
```
You can also use this inside an LCEL chain as a conditional step — call `memanto_answer` first, and only invoke the full LLM if the memory answer is empty:
```python theme={null}
from langchain_core.runnables import RunnableLambda
def answer_or_recall(inputs: dict) -> dict:
quick = memanto_answer(inputs["question"])
if quick:
return {**inputs, "context": f"Memory answer: {quick}"}
resp = httpx.post(
f"{BASE_URL}/agents/{AGENT_ID}/recall",
headers=HEADERS,
json={"query": inputs["question"], "limit": 5},
)
memories = resp.json().get("memories", [])
context = "\n".join(f"- {m['content']}" for m in memories) or "No prior context."
return {**inputs, "context": context}
```
> **When to use `answer` vs `recall`**
>
> * Use `recall` (via `load_memory_variables`) when your LLM should reason over the raw memories itself.
> * Use `answer` when you want a ready-made response from memory, or to short-circuit the chain for simple factual lookups.
## Persistent Memory Across Sessions
Memories stored via `save_context` survive process restarts and are available in future sessions for the same `agent_id`:
```bash theme={null}
# View stored memories
memanto recall "all context" --agent my-assistant
# Export to file
memanto memory export --agent my-assistant
```
## Next Steps
* [Remember API](/api-reference/data/remember)
* [Recall API](/api-reference/search/recall)
* [Memory Types Reference](/reference/memory-types)
* [Session Management](/guides/session-management)
# Langfuse
Source: https://docs.memanto.ai/integrations/langfuse
Turn Langfuse observability signal — errors, failed evals, latency and cost anomalies — into durable Memanto memories, live from your app or on a one-shot sync.
# Langfuse + Memanto
![Langfuse]()
Langfuse records **what went wrong**. Memanto remembers **the lesson**.
This integration connects them: failing spans, failed evaluations, and latency or cost anomalies become durable memories your agents can recall — instead of the same mistake being re-learned on every run.
A thousand identical failures become **one** memory whose confidence reflects how often it happened — not a thousand near-duplicates.
A live SDK handler for instant capture from your app, and a CLI sync that reads the Langfuse API. They share a ledger, so running both is safe.
Re-running never duplicates. A recurring failure **updates** its memory in place; an unchanged one is skipped.
Score names, value ranges, and what counts as slow or expensive are all project-specific — so you decide, and nothing is assumed on your behalf.
## The core idea
Memanto performs no deduplication on write, so piping raw traces in would drown recall — one bad deploy could write thousands of near-identical memories.
Instead, observations are grouped by **error signature**: the operation name plus a message with its volatile parts (ids, numbers, emails, IPs, paths, quoted strings) normalized away.
```
Langfuse observations (thousands)
│ filter level=ERROR, your score rules, your latency/cost budgets
│ group signature = operation + normalized message
│ reconcile new → write · changed → update in place · same → skip
▼
Memanto (dozens)
```
A real example — **812 observations collapsing to 2 memories**:
```
Namespace not found in generate-response error confidence 0.60
Slow: generate-response (anthropic.claude-sonnet-4-6) observation
```
Everything is **rule-based** — no LLM calls, no token cost. Grouping is a regex-normalized hash; confidence is `min(0.95, 0.60 + 0.15 × log₁₀(occurrences))`, so 1 occurrence scores 0.60 and 100 scores 0.90.
## Which path do you want?
| | Live SDK handler | CLI sync |
| ------------ | ----------------------------------------- | ------------------------------------- |
| **Setup** | `pip install langfuse-memanto` + one line | Already in `memanto` |
| **Latency** | Seconds | When you run it |
| **Requires** | `langfuse>=3` in your app | Nothing — reads the Langfuse API |
| **Captures** | Errors, latency | Everything, including scores and cost |
Most teams run **both**: the handler for instant error capture, and a periodic sync for the signals that only exist server-side.
***
## Path 1 — CLI sync
No app changes. Works with **any** Langfuse version, including v2.
You cannot choose a latency budget or a score rule without seeing your own data.
```bash theme={null}
memanto migrate langfuse --discover
```
```
Name Type Count Observed Suggested rule
rating NUMERIC 60 1.0 … 5.0 --score-fail 'rating<3.4'
user-thumbs BOOLEAN 3 0.0 … 1.0 --score-fail 'user-thumbs=false'
Operation Count p50 ms p95 ms p99 ms cost p95
generate-response 300 2000 2000 40000 $0.002409
```
It reads your **actual** range and refuses to guess direction — Langfuse documents no convention for whether a higher score is better.
```bash theme={null}
memanto migrate langfuse \
--capture errors,slow \
--latency-percentile 95 \
--save
```
Stored per Langfuse project in `~/.memanto/migrate/langfuse/config.json`.
```bash theme={null}
memanto migrate langfuse --dry-run
memanto migrate langfuse
```
Run it again — you should see `New: 0 · Unchanged: N`. That is the ledger doing its job.
**Langfuse Cloud is regional and keys are not valid across regions.** If your project is on US, pass `--host https://us.cloud.langfuse.com` once (it is remembered) or set `LANGFUSE_HOST`. A region mismatch surfaces as `401 Invalid credentials`.
Credentials are a **pair**, supplied as one string:
```bash theme={null}
export LANGFUSE_API_KEY="pk-lf-xxxx:sk-lf-yyyy"
# or the vendor-native pair, which is also accepted
export LANGFUSE_PUBLIC_KEY="pk-lf-xxxx"
export LANGFUSE_SECRET_KEY="sk-lf-yyyy"
```
See [`memanto migrate`](/cli/migrate/migrate) for the full option list.
### From the UI
`memanto ui` → **Migrate** → **Langfuse** gives the same thing with checkboxes: **Discover**, capture toggles, threshold fields, **Save settings**, **Preview**, **Sync now**. It reads and writes the same `config.json` and the same ledger as the CLI.
***
## Path 2 — Live SDK handler
Langfuse's Python SDK (v3+) is built on **OpenTelemetry** and attaches its span processor to the global `TracerProvider`. This package attaches a **second** one — so it sees every span your app already produces, with no extra instrumentation and no calls to the Langfuse API.
```
your app ──▶ Langfuse SDK ──▶ OTel TracerProvider ──┬──▶ LangfuseSpanProcessor ──▶ Langfuse
└──▶ MemantoLangfuseHandler ──▶ Memanto
```
### Install
```bash theme={null}
pip install langfuse-memanto
```
That is the only install — `memanto` comes with it, and **there is no server to run**. Memories go straight to the Memanto cloud API from your process.
### Quick start from nothing
You need one thing: a [Moorcheh API key](https://console.moorcheh.ai/api-keys).
```bash theme={null}
export MOORCHEH_API_KEY="your-key"
```
Then two lines:
```python theme={null}
from langfuse import Langfuse
from langfuse_memanto import attach
Langfuse() # your existing setup
attach(agent_id="my-agent") # start capturing
```
That is the whole setup. No CLI, no config file, no decorators to add. **The agent is created and activated automatically on the first write.**
```python theme={null}
@observe()
def summarize(doc):
raise RuntimeError("context window exceeded")
```
becomes:
```
context window exceeded in summarize [error]
Langfuse recorded 6 failing 'summarize' observations: context window exceeded.
Seen 6x between 2026-08-07T17:38:14Z and 2026-08-07T17:38:19Z.
tags: langfuse, capture=errors, sig=4c092b52d146, op=summarize
```
Call `attach()` **after** `Langfuse()`. Before that, OpenTelemetry has only a `ProxyTracerProvider`, which cannot take a span processor — `attach()` raises with that explanation.
### Configuring in code
Anything you would set with the CLI can be passed to `attach()` instead:
```python theme={null}
attach(
agent_id="my-agent",
capture=["errors", "slow"],
latency_ms=5000, # slower than 5s is an anomaly
group_by="metadata.error_code", # if your messages group poorly
)
```
Precedence is **code → stored profile → default (`errors`)**. So a solo developer never touches the CLI, while a team can manage rules centrally with `--save` and each service just calls `attach(agent_id=...)`. Bad settings raise at `attach()` rather than silently capturing nothing.
### More control
```python theme={null}
from langfuse_memanto import MemantoLangfuseHandler
handler = MemantoLangfuseHandler(agent_id="my-agent", host="https://us.cloud.langfuse.com")
handler.attach()
handler.flush() # write immediately
handler.stats() # {'captured': 12, 'written': 2, 'dropped': 0, 'pending': 0}
handler.shutdown() # flush and stop (also runs at exit)
```
***
## Capture modes
Only `errors` works with **no configuration** — `level` is the one field every Langfuse project populates the same way. Everything else stays inert, and **says so**, until you supply a rule or a budget.
| Mode | Catches | Needs | Live? |
| ----------- | ------------------------ | ---------------------------------------- | :-----------------------------------------------: |
| `errors` | `level=ERROR` spans | nothing | ✅ |
| `slow` | Latency outliers | `--latency-ms` or `--latency-percentile` | ✅ with an absolute budget |
| `costly` | Expensive calls | `--cost-usd` or `--cost-percentile` | ⚠️ sync only, unless your app sets `cost_details` |
| `low-score` | Traces your evals failed | `--score-fail` rule | ❌ sync only |
| `success` | Traces your evals passed | `--score-pass` rule | ❌ sync only |
Langfuse scores are attached **after** a trace finishes — nothing in the span carries them. The live handler logs a warning at startup if you enable them, rather than silently capturing nothing. Run `memanto migrate langfuse` periodically to pick them up.
Unless your app explicitly sets `cost_details` on the observation, Langfuse computes cost **server-side after ingestion** — where a span processor cannot see it. Latency is different: it is on the span itself, so `slow` works live.
A percentile needs a population to calibrate against. The sync has the whole pulled window; a single span does not. Give `slow` an absolute `latency_ms` for live capture.
### Score rules
Langfuse scores can be **Numeric, Categorical, Boolean, or Text**, with user-defined names and ranges — and the docs state **no convention** for whether higher is better. So you state the direction:
```bash theme={null}
--score-fail 'correctness<0.7' # numeric, low is bad
--score-fail 'toxicity>0.3' # numeric, high is bad
--score-fail 'thumbs_up=false' # boolean
--score-fail 'tone in rude,evasive' # categorical
--score-pass 'correctness>=0.9' # what "good" looks like
```
Operators: `<` `<=` `>` `>=` `=` `!=` `in`. Run `--discover` to see your score names, types, and observed ranges first.
## Memory shape
| Field | Value |
| ------------ | ------------------------------------------------------------------------------------- |
| `type` | `error` · `learning` (score modes) · `observation` (latency/cost) |
| `source` | `langfuse` |
| `provenance` | `imported` — preserves the original Langfuse timestamps |
| `source_ref` | Deep link back to a representative trace |
| `confidence` | Rises with occurrence count, capped at 0.95 |
| `tags` | `langfuse`, `capture=`, `sig=`, `op=`, `model=…`, `env=…` |
Everything without a schema slot — occurrence count, models, peak latency, total cost, sample trace ids, first/last seen — goes into a bounded `[Supporting data]` footer, so nothing is lost.
## The sync ledger
`~/.memanto/migrate/langfuse/state.json` maps each signature to the memory it wrote, scoped by **Langfuse project and destination agent**.
That scoping matters: a signature written to agent A tells you nothing about agent B, and two projects can produce identical signatures for unrelated faults. Without it, a sync would skip a write the destination never received.
Because the live handler and the CLI share this ledger, running both is safe — whichever gets there first writes, and the other sees it as already stored.
## Configuration reference
Capture rules live in `~/.memanto/migrate/langfuse/config.json`, written by `--save` or the UI. Only runtime settings come from the environment:
| Variable | Required | Default | Description |
| ------------------------------------ | :------: | ---------------------------- | -------------------------------------------------------- |
| `MOORCHEH_API_KEY` | **yes** | — | Memanto API key. Never logged. |
| `MEMANTO_LANGFUSE_AGENT_ID` | yes\* | — | Agent that receives the memories. \*Or pass `agent_id=`. |
| `LANGFUSE_PUBLIC_KEY` | no | — | Also selects which stored capture profile is used. |
| `LANGFUSE_HOST` | no | `https://cloud.langfuse.com` | Use `https://us.cloud.langfuse.com` for US. |
| `MEMANTO_LANGFUSE_PROJECT` | no | derived | Override the capture profile. |
| `MEMANTO_LANGFUSE_FLUSH_INTERVAL` | no | `30` | Seconds between background flushes. |
| `MEMANTO_LANGFUSE_MAX_BUFFER` | no | `100` | Flush early at this many pending spans. |
| `MEMANTO_LANGFUSE_AUTO_CREATE_AGENT` | no | `true` | Create + activate the agent on first write. |
| `MEMANTO_LANGFUSE_SESSION_HOURS` | no | `24` | Lifetime of the session the handler opens. |
## Reliability
* **Nothing runs on your hot path.** `on_end` maps the span and buffers it; grouping and network I/O happen on a daemon thread.
* **Your app is never harmed.** Every entry point swallows its own exceptions — a memory that fails to write will not break your application.
* **Failed writes are retried, not dropped.** A batch that fails is retained and retried; retrying is safe because reconciliation is idempotent. After 4 consecutive failures it is abandoned so a dead backend cannot fill memory.
* **Bounded buffer.** During a storm the buffer stops growing and drops are counted in `stats()["dropped"]`.
## Troubleshooting
Langfuse Cloud is regional and keys are not valid across regions. If your project is on US, use `--host https://us.cloud.langfuse.com` or set `LANGFUSE_HOST`.
Check `handler.stats()`. `captured: 0` means no span matched your settings — confirm with `--discover`. `captured > 0, written: 0` means the flush failed:
```python theme={null}
import logging; logging.getLogger("langfuse_memanto").setLevel(logging.DEBUG)
```
That is correct — those signatures are already synced. Read **Signatures** and **Unchanged** instead. You only see `New` on a project that has not been synced to that agent before.
Your messages embed values the normalizer did not catch. Pin grouping to a stable field you control:
```bash theme={null}
memanto migrate langfuse --group-by metadata.error_code
```
Those are normalization placeholders standing in for the volatile part of the message — they are the group's identity. That is what lets a thousand variations collapse into one memory.
## Requirements
* Python **3.10+**
* A [Moorcheh API key](https://console.moorcheh.ai/api-keys) (free tier: 100K ops/month)
* For the live handler: `langfuse>=3` in your application. The CLI sync works with **any** Langfuse version, including v2.
Verified end-to-end against **langfuse 3.15.0 and 4.14.3**. If your app is on langfuse v2 (the classic `trace()`/`generation()` API), it predates the OpenTelemetry rewrite — use the CLI sync, or upgrade to v4 to use the live handler.
## Shared memory across integrations
`langfuse-memanto` talks to the same Moorcheh-backed Memanto agents as the sibling integrations, so memory written by one is recallable from the others when they share an `agent_id`:
| Integration | Package | What it does |
| ----------------------------------------------------------- | ------------------ | ----------------------------------------------------- |
| [`integrations/mcp`](/integrations/mcp) | `memanto-mcp` | MCP server for any MCP-compatible client. |
| [`integrations/crewai`](/integrations/crewai) | `crewai-memanto` | CrewAI tools for multi-agent memory sharing. |
| [`integrations/hermes-agents`](/integrations/hermes-agents) | `hermes-memanto` | Memory provider for the Hermes agent. |
| `integrations/langfuse` | `langfuse-memanto` | **This** — Langfuse observability signal as memories. |
## Next steps
Full option reference for the CLI sync, including every capture flag.
What `error`, `learning`, and `observation` mean, and how recall uses them.
Create, activate, and switch the agents these memories land in.
Read the captured memories back from your own code.
***
**Links**
* [`langfuse-memanto` on PyPI](https://pypi.org/project/langfuse-memanto/)
* [Memanto on GitHub](https://github.com/moorcheh-ai/memanto)
* [Langfuse](https://langfuse.com)
# LangGraph
Source: https://docs.memanto.ai/integrations/langgraph
Add persistent, cross-session memory to LangGraph agents using Memanto.
# LangGraph + Memanto
![LangGraph]()
Give your LangGraph applications persistent, cross-session memory powered by Memanto.
LangGraph natively manages short-term execution state using Checkpointers, but requires a `BaseStore` to persist semantic memory across different threads or sessions. Memanto integrates seamlessly as a native `BaseStore` or via `@tool` functions to give your agents long-term recall.
## How It Works
```text theme={null}
LangGraph Agent → MemantoStore(BaseStore) → Memanto Server → Moorcheh.ai
```
You can integrate Memanto into LangGraph using three primary patterns:
1. **BaseStore:** A drop-in `BaseStore` implementation that provides cross-thread semantic memory while respecting LangGraph's namespace architecture.
2. **Nodes:** Pre-built graph nodes for automatic memory injection before LLM calls and storage after responses.
3. **Tools:** Pre-built agent tools (`remember`, `recall`, `answer`) injected directly into your LangGraph `ToolNode`.
## Prerequisites
* Python 3.10+
* [Moorcheh API key](https://console.moorcheh.ai/api-keys)
* Memanto package installed
## Install
```bash theme={null}
pip install memanto langgraph-memanto langgraph langchain-openai
```
## Pattern 1: BaseStore Integration
LangGraph uses a split memory architecture: Checkpointers for short-term thread state, and Stores for long-term semantic memory.
`MemantoStore` maps LangGraph's key-value namespace API directly to Memanto's isolated agent buckets (e.g., `langgraph_user123_preferences`), providing instant, zero-latency semantic recall.
### Setup the Store
```python theme={null}
import os
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import InMemorySaver
from memanto_store import MemantoStore # (Copy from memanto examples)
api_key = os.environ.get("MOORCHEH_API_KEY")
# Initialize the MemantoStore
store = MemantoStore(api_key=api_key)
builder = StateGraph(MyState)
# ... add nodes and edges ...
# Compile the graph with the Memanto BaseStore
graph = builder.compile(
checkpointer=InMemorySaver(),
store=store
)
```
### Access Memory in Nodes
In any node, simply require the `store: BaseStore` parameter. LangGraph will automatically inject `MemantoStore`.
```python theme={null}
from langgraph.store.base import BaseStore
async def extract_and_store(state: MyState, config, *, store: BaseStore):
"""Save a user preference to long-term memory."""
user_id = config["configurable"]["user_id"]
await store.aput(
namespace=(user_id, "preferences"),
key="allergy_info",
value={
"kind": "preference",
"content": "User is allergic to peanuts"
}
)
return {}
async def recall_context(state: MyState, config, *, store: BaseStore):
"""Recall memories before responding."""
user_id = config["configurable"]["user_id"]
# MemantoStore performs a semantic search across the user's isolated memory bucket
memories = await store.asearch(
namespace_prefix=(user_id, "preferences"),
query="food allergies",
limit=5
)
# ... inject memories into your LLM prompt ...
return state
```
## Pattern 2: Node-Based Integration
If you prefer a structured, deterministic approach without relying on the LLM to autonomously call tools, you can add pre-built `recall` and `remember` nodes directly to your graph's edges. This guarantees memory is injected before every generation and saved after every response.
```python theme={null}
import os
from langgraph.graph import StateGraph, MessagesState, START, END
from langgraph_memanto import create_recall_node, create_remember_node
from memanto.cli.client.sdk_client import SdkClient
# 1. Initialize the Memanto SDK Client
client = SdkClient(api_key=os.environ.get("MOORCHEH_API_KEY"))
# 2. Create the Nodes
# Nodes can dynamically resolve the agent_id from the graph config at runtime
recall = create_recall_node(client=client, agent_id_from_config="user_id")
remember = create_remember_node(client=client, agent_id_from_config="user_id")
# 3. Wire them into your graph
builder = StateGraph(MessagesState)
builder.add_node("recall", recall)
builder.add_node("agent", agent_node) # your standard LLM node
builder.add_node("remember", remember)
# Execution flow: Recall -> LLM -> Remember
builder.add_edge(START, "recall")
builder.add_edge("recall", "agent")
builder.add_edge("agent", "remember")
builder.add_edge("remember", END)
graph = builder.compile()
```
## Pattern 3: Tool-Based Integration
If you prefer to let the LLM autonomously decide when to search or save memories (rather than hardcoding `store` operations in nodes), you can inject Memanto as tools.
```python theme={null}
import os
from memanto.cli.client.sdk_client import SdkClient
from langgraph_memanto import create_memanto_tools
from langgraph.prebuilt import ToolNode
# 1. Initialize the Memanto client
client = SdkClient(api_key=os.environ.get("MOORCHEH_API_KEY"))
# 2. Create the tools
# The tools will automatically ensure the agent is created and activated
tools = create_memanto_tools(client, agent_id="my-langgraph-agent")
# 3. Create a ToolNode
tool_node = ToolNode(tools)
# 4. Bind tools to your LLM and build the graph
llm_with_tools = llm.bind_tools(tools)
# ...
```
## Persistent Memory Across Runs
Because memories live in Memanto (not in-process), they persist between separate runs, processes, or entire servers. The checkpointer handles short-term context, while Memanto handles lifelong user profiles.
## Next Steps
* [Check out the LangGraph Examples Directory](https://github.com/moorcheh-ai/memanto/tree/main/examples/langgraph-memanto)
* [BaseStore API Reference](https://langchain-ai.github.io/langgraph/concepts/memory/)
* [Memory Types Reference](/reference/memory-types)
# LlamaIndex
Source: https://docs.memanto.ai/integrations/llamaindex
Use Memanto as a memory store for LlamaIndex applications.
# LlamaIndex + Memanto
![LlamaIndex]()
Give your LlamaIndex agents and query engines persistent memory across sessions using Memanto.
LlamaIndex excels at querying documents and data, but context resets between runs. Memanto adds a semantic memory layer so your agents can store insights, user preferences, and decisions - and recall them later.
## How It Works
```
LlamaIndex Agent -> Memanto FunctionTools (remember / recall / answer) -> Memanto Server -> Moorcheh.ai
```
Memanto is wired in as three `FunctionTool` instances (remember, recall, answer) that your LlamaIndex agent can call during reasoning. The agent decides when to store something, when to search raw memories, and when to get a synthesized answer directly from memory.
## Prerequisites
* Python 3.8+
* [Moorcheh API key](https://console.moorcheh.ai/api-keys)
* Memanto server running locally
## Install
```bash theme={null}
pip install memanto llama-index llama-index-llms-openai httpx
```
## Step 1: Start Memanto Server
```bash theme={null}
memanto serve
```
## Step 2: Create the Memory Tools
Create `memanto_tools.py`:
```python theme={null}
import httpx
from llama_index.core.tools import FunctionTool
MEMANTO_URL = "http://localhost:8000"
AGENT_ID = "llamaindex-agent"
# Activate session once at startup
_token = httpx.post(
f"{MEMANTO_URL}/api/v2/agents/{AGENT_ID}/activate"
).json()["session_token"]
_HEADERS = {
"X-Session-Token": _token,
"Content-Type": "application/json",
}
def remember(content: str, memory_type: str = "fact") -> str:
"""
Store important information in long-term memory.
Args:
content: The information to store.
memory_type: Category of memory. Options: fact, preference,
decision, goal, commitment, event, error.
"""
response = httpx.post(
f"{MEMANTO_URL}/api/v2/agents/{AGENT_ID}/remember",
json={"content": content, "type": memory_type},
headers=_HEADERS,
)
response.raise_for_status()
return f"Stored memory: {response.json()['memory_id']}"
def recall(query: str) -> str:
"""
Search long-term memory for relevant information.
Args:
query: A natural language question or topic to search for.
"""
response = httpx.post(
f"{MEMANTO_URL}/api/v2/agents/{AGENT_ID}/recall",
json={"query": query, "limit": 5},
headers=_HEADERS,
)
response.raise_for_status()
memories = response.json().get("memories", [])
if not memories:
return "No relevant memories found."
return "\n".join(f"- [{m['type']}] {m['content']}" for m in memories)
def answer(question: str) -> str:
"""
Get a synthesized answer from long-term memory using Memanto's built-in RAG.
Args:
question: A natural language question to answer from stored memories.
Use this when you want a ready-to-use response instead of raw memory items.
Memanto answers using its native model - no extra LLM call needed.
"""
response = httpx.post(
f"{MEMANTO_URL}/api/v2/agents/{AGENT_ID}/answer",
json={"question": question},
headers=_HEADERS,
)
response.raise_for_status()
return response.json().get("answer", "No answer found.")
remember_tool = FunctionTool.from_defaults(fn=remember)
recall_tool = FunctionTool.from_defaults(fn=recall)
answer_tool = FunctionTool.from_defaults(fn=answer)
```
Set `MOORCHEH_API_KEY` on the **Memanto server** � clients only send `X-Session-Token`.
## Step 3: Build the Agent
Create `agent.py`:
```python theme={null}
import os
from llama_index.core.agent import ReActAgent
from llama_index.llms.openai import OpenAI
from memanto_tools import remember_tool, recall_tool, answer_tool
llm = OpenAI(model="gpt-4o-mini", temperature=0)
agent = ReActAgent.from_tools(
tools=[remember_tool, recall_tool, answer_tool],
llm=llm,
verbose=True,
system_prompt=(
"You are a helpful assistant with long-term memory. "
"When you learn something important about the user, store it with the remember tool. "
"Use recall to search raw memories, or answer to get a synthesized response from memory."
)
)
# Agent stores user preferences to memory
response = agent.chat("I prefer dark mode and concise answers. Please remember this.")
print(response.response)
# Agent recalls preferences before answering
response = agent.chat("How should I configure my editor?")
print(response.response)
```
## Step 4: Run
```bash theme={null}
export OPENAI_API_KEY=sk_your_openai_key
# MOORCHEH_API_KEY is read by the Memanto server, not by this script.
python agent.py
```
## Getting Synthesized Answers from Memory
The `answer_tool` calls Memanto's built-in RAG - it synthesizes a direct response from stored memories using Memanto's native model. No extra LLM token usage on your side.
```python theme={null}
# Agent picks the right tool automatically based on the question
response = agent.chat("What are my editor preferences?")
# -> Agent calls answer_tool, returns: "You prefer dark mode and concise answers."
response = agent.chat("List everything you know about my setup.")
# -> Agent calls recall_tool, returns raw memory items for full reasoning
```
> **When to use `answer_tool` vs `recall_tool`**
>
> * Use `recall_tool` when the agent needs to reason over multiple raw memory items.
> * Use `answer_tool` when the agent (or user) needs a clean, direct response from memory.
## Using with a Query Engine
Combine Memanto memory with LlamaIndex document retrieval:
```python theme={null}
import os, httpx
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.core.tools import QueryEngineTool, FunctionTool
from llama_index.core.agent import ReActAgent
from llama_index.llms.openai import OpenAI
from memanto_tools import remember_tool, recall_tool, answer_tool
# Load your documents
documents = SimpleDirectoryReader("./docs").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
# Wrap the query engine as a tool
doc_tool = QueryEngineTool.from_defaults(
query_engine=query_engine,
name="document_search",
description="Search the project documentation for specific information."
)
# Agent now has both: document search + persistent memory
agent = ReActAgent.from_tools(
tools=[doc_tool, remember_tool, recall_tool, answer_tool],
llm=OpenAI(model="gpt-4o-mini"),
verbose=True
)
# Agent searches docs and stores key findings in memory
response = agent.chat("What is the deployment process? Remember the key steps.")
print(response.response)
# Later: agent recalls the steps without re-reading docs
response = agent.chat("Walk me through the deployment steps again.")
print(response.response)
```
## Persistent Memory Across Sessions
Because memories live in Memanto and not in-process, they persist across agent restarts:
```bash theme={null}
# Check what the agent has remembered
memanto recall "user preferences" --agent llamaindex-agent
# Export all memories
memanto memory export --agent llamaindex-agent
```
## Next Steps
* [Remember API](/api-reference/data/remember)
* [Recall API](/api-reference/search/recall)
* [Memory Types Reference](/reference/memory-types)
* [Session Management](/guides/session-management)
# Mastra
Source: https://docs.memanto.ai/integrations/mastra
Give Mastra agents persistent, cross-session memory with Memanto tools.
# Mastra + Memanto
![Mastra]()
Add persistent memory to any [Mastra](https://mastra.ai/) agent with three ready-made tools, shipped as part of the `@moorcheh-ai/memanto` TypeScript SDK.
## Prerequisites
* Node.js 20+
* [`uv`](https://docs.astral.sh/uv/) (ships `uvx`) — the `Memanto` client spawns a local Memanto server via `uvx` on first use unless you pass `baseUrl`
* **Memanto / Moorcheh credentials** — [Moorcheh API key](https://console.moorcheh.ai/api-keys) (cloud) or an [on-prem](/on-prem/overview) backend (no Moorcheh API key). Set `MOORCHEH_API_KEY` or pass `apiKey` to `new Memanto({ ... })`
* **Agent model credentials** — the quick start uses `openai/gpt-4o` for tool orchestration. Configure your OpenAI API key for Mastra (typically `OPENAI_API_KEY`).
* `@mastra/core` and `zod` installed in your app (optional peer dependencies of `@moorcheh-ai/memanto`)
## Install
```bash theme={null}
npm install @moorcheh-ai/memanto @mastra/core zod
```
`@mastra/core` and `zod` are optional peer dependencies of `@moorcheh-ai/memanto` — install them yourself in the host app. Importing `@moorcheh-ai/memanto/mastra` without them installed will fail at module load with a standard Node resolution error.
## Quick Start
```ts theme={null}
import { Agent } from "@mastra/core/agent";
import { Memanto } from "@moorcheh-ai/memanto";
import { createMemantoMastraTools } from "@moorcheh-ai/memanto/mastra";
const memanto = new Memanto({
agentId: "my-agent",
apiKey: process.env.MOORCHEH_API_KEY, // omit when using on-prem; see On-Prem below
});
const agent = new Agent({
id: "assistant",
name: "Assistant",
instructions:
"You have long-term memory. Persist durable facts with rememberMemory " +
"and look them up with recallMemory / answerMemory before answering.",
model: "openai/gpt-4o", // requires OPENAI_API_KEY — swap for your provider if needed
tools: createMemantoMastraTools(memanto),
});
```
`createMemantoMastraTools` returns an object with three [Mastra tools](https://mastra.ai/docs/agents/using-tools-and-mcp) — pass it straight into an agent's `tools` map.
Each tool's description is written for the model to decide *when* to call it (e.g. `recallMemory`: "Call this before answering whenever the user refers to information from earlier or from a previous session").
## Available Tools
| Tool | Backed by | Description |
| ---------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `recallMemory` | [Recall](/api-reference/search/recall) | Semantic search over stored memories. `query` (required), `limit` (1-50), `type` (optional array of memory types to filter by). |
| `rememberMemory` | [Remember](/api-reference/data/remember) | Persist a durable fact/preference/decision/instruction. `content` (required), `type` (optional — server auto-classifies if omitted), `title`, `tags`. |
| `answerMemory` | [Generate AI Answer](/api-reference/ai/generate-ai-answer) | RAG-synthesized answer over stored memories. `question` (required), `limit` (1-100). |
`answerMemory` calls Memanto's **Generate AI Answer** API (`memanto.answer()` → Moorcheh `answer.generate`). Memanto retrieves relevant memories and synthesizes a grounded response using **Memanto's configured LLM** — not the model you pass to your Mastra `Agent`. Your agent model only decides *when* to call the tool and how to use the result. `recallMemory` and `rememberMemory` do not invoke an LLM.
## Options
```ts theme={null}
createMemantoMastraTools(memanto, {
include: ["recallMemory", "answerMemory"], // expose a subset — omit for all three
defaultLimit: 10, // default limit for recall/answer when the model doesn't specify one
});
```
## Memory Types
`type` fields are constrained to Memanto's 13 supported types via a shared `MEMORY_TYPES` export:
```ts theme={null}
import { MEMORY_TYPES } from "@moorcheh-ai/memanto/mastra";
// ["fact", "preference", "goal", "decision", "artifact", "learning", "event",
// "instruction", "relationship", "context", "observation", "commitment", "error"]
```
See the [Memory Types Reference](/reference/memory-types) for what each type means.
## On-Prem
The integration talks to Memanto through the `Memanto` client, so it works identically against an on-prem backend — no code changes, just configure the backend once with the CLI. See [On-Prem Overview](/on-prem/overview) and the [TypeScript SDK Reference](/sdk/typescript#on-prem-no-api-key).
## Next Steps
* [TypeScript SDK Reference](/sdk/typescript) for the full `Memanto` client API
* [Vercel AI SDK Integration](/integrations/vercel-ai-sdk) for the equivalent AI SDK tools
* [OpenAI Integration](/integrations/openai) for the equivalent OpenAI `runTools()` tools
* [Memory Types Reference](/reference/memory-types)
# MCP
Source: https://docs.memanto.ai/integrations/mcp
Expose Memanto's persistent semantic memory to any MCP-compatible client (Claude Desktop, Cursor, Windsurf, Cline, Continue, Goose, …) with a single config line.
# Model Context Protocol (MCP)
![MCP]()
The [`memanto-mcp`](https://pypi.org/project/memanto-mcp/) package exposes Memanto's memory primitives — `remember`, `recall`, `answer`, and friends — as [Model Context Protocol](https://modelcontextprotocol.io) tools, so any MCP-compatible client can plug into long-term memory in a **single config line**.
> One Moorcheh API key → typed semantic memory shared across every agent that uses the namespace, with sub-90 ms retrieval, conflict detection, and zero ingestion latency.
Works with every MCP host: Claude Desktop, Cursor, Windsurf, Cline, Continue, Goose, Codex, and custom agents using the MCP SDK.
No client code, no vector DB. Add one JSON block to your client's config and the agent gets 7 memory tools.
13 memory types (fact, preference, decision, goal, instruction, …) with confidence + provenance — built for LLM tool-selection.
Different clients pointed at the same `agent_id` share one memory. Remember in Claude Desktop, recall in Cursor.
## How It Works
```
┌──────────────┐ MCP (stdio) ┌──────────────────┐ HTTPS + API key ┌─────────────┐
│ Claude / IDE │ ────────────────► │ memanto-mcp │ ───────────────────► │ Moorcheh │
│ (client) │ ◄──────────────── │ (this server) │ ◄─────────────────── │ Service │
└──────────────┘ tool calls └──────────────────┘ no-indexing search └─────────────┘
```
The server runs locally next to your MCP host. On the first tool call it activates a Memanto session (auto-creating the agent if needed) and reuses it across the conversation. Sessions auto-renew before expiry, so long-running MCP connections never hit a session-expired error mid-turn.
## Prerequisites
* Python **3.10+**
* A [Moorcheh API key](https://console.moorcheh.ai/api-keys) (free tier: 100K ops/month)
* Any MCP-compatible client
## Install
```bash theme={null}
pip install memanto-mcp
```
This installs the `memanto-mcp` console script that every client below launches over stdio.
## Quickstart
Pick your client. The JSON shape is identical across most hosts — only the config file path changes.
* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
Or use **Settings → Developer → Edit Config**.
```json theme={null}
{
"mcpServers": {
"memanto": {
"command": "memanto-mcp",
"env": {
"MOORCHEH_API_KEY": "mch_xxxxxxxxxxxxxxxxxx",
"MEMANTO_DEFAULT_AGENT_ID": "my-assistant"
}
}
}
}
```
Ask Claude to *"remember that I prefer concise answers"*. Tomorrow, in a brand-new chat, ask *"what do I prefer?"* — the answer comes from Memanto.
* **Per-user**: `~/.cursor/mcp.json`
* **Per-project**: `.cursor/mcp.json` (committable)
```json theme={null}
{
"mcpServers": {
"memanto": {
"command": "memanto-mcp",
"env": {
"MOORCHEH_API_KEY": "mch_xxxxxxxxxxxxxxxxxx",
"MEMANTO_DEFAULT_AGENT_ID": "cursor-workspace"
}
}
}
}
```
Open the MCP panel and confirm `memanto` shows up with **7 tools**.
Edit `~/.codeium/windsurf/mcp_config.json`:
```json theme={null}
{
"mcpServers": {
"memanto": {
"command": "memanto-mcp",
"env": {
"MOORCHEH_API_KEY": "mch_xxxxxxxxxxxxxxxxxx",
"MEMANTO_DEFAULT_AGENT_ID": "windsurf-workspace"
}
}
}
}
```
Reload Windsurf via **Cascade → MCP Servers → Refresh**.
Edit `cline_mcp_settings.json` (path depends on OS):
* **Linux**: `~/.config/Code/User/globalStorage/cline.cline/settings/cline_mcp_settings.json`
* **macOS**: `~/Library/Application Support/Code/User/globalStorage/cline.cline/settings/cline_mcp_settings.json`
* **Windows**: `%APPDATA%\Code\User\globalStorage\cline.cline\settings\cline_mcp_settings.json`
```json theme={null}
{
"mcpServers": {
"memanto": {
"command": "memanto-mcp",
"env": {
"MOORCHEH_API_KEY": "mch_xxxxxxxxxxxxxxxxxx",
"MEMANTO_DEFAULT_AGENT_ID": "cline-workspace"
}
}
}
}
```
Edit `~/.continue/config.json`:
```json theme={null}
{
"experimental": {
"modelContextProtocolServers": [
{
"transport": {
"type": "stdio",
"command": "memanto-mcp",
"env": {
"MOORCHEH_API_KEY": "mch_xxxxxxxxxxxxxxxxxx",
"MEMANTO_DEFAULT_AGENT_ID": "continue-workspace"
}
}
}
]
}
}
```
Edit `~/.config/goose/config.yaml`:
```yaml theme={null}
extensions:
memanto:
type: stdio
command: memanto-mcp
envs:
MOORCHEH_API_KEY: mch_xxxxxxxxxxxxxxxxxx
MEMANTO_DEFAULT_AGENT_ID: goose-workspace
```
The first call auto-creates the `MEMANTO_DEFAULT_AGENT_ID` namespace and activates a session. Every subsequent call (in any client pointed at the same agent) reuses the same persistent memory.
## Available Tools
The server registers **7 memory tools** by default. Set `MEMANTO_EXPOSE_ADMIN=true` to also expose **4 agent-management tools**.
### Memory tools (always on)
| Tool | When the agent should call it |
| ---------------------- | ------------------------------------------------------------------------------------- |
| `remember` | Persist a single fact, preference, decision, goal, or instruction. |
| `batch_remember` | Persist up to 100 memories in one call (e.g. extracted from a document). |
| `recall` | Semantic search — **always** check here before asking the user to repeat stable info. |
| `recall_recent` | *"What did we just decide?"* — newest-first, no query needed. |
| `recall_as_of` | Point-in-time recall — *"what did we know on 2025-11-01?"* |
| `recall_changed_since` | Differential recall — *"what's new since I last checked?"* |
| `answer` | RAG: a grounded LLM answer synthesized over the agent's memories. |
### Agent admin tools (opt-in)
Enabled when `MEMANTO_EXPOSE_ADMIN=true`:
| Tool | Purpose |
| -------------- | ------------------------------------- |
| `create_agent` | Create a new memory namespace. |
| `list_agents` | List every agent the API key can see. |
| `get_agent` | Look up an agent's metadata. |
| `delete_agent` | Remove an agent's local metadata. |
`fact`, `preference`, `goal`, `decision`, `artifact`, `learning`, `event`, `instruction`, `relationship`, `context`, `observation`, `commitment`, `error`.
See the [Memory Types Reference](/reference/memory-types) for guidance on picking the right type.
`explicit_statement`, `inferred`, `corrected`, `validated`, `observed`, `imported`.
Use `explicit_statement` when the user said it directly, `inferred` when you deduced it, and `corrected` when overriding an earlier wrong memory.
Each memory hit from `recall` / `recall_recent` / `recall_as_of` / `recall_changed_since` carries its trust and provenance metadata:
* `id`, `title`, `content`, `type`, `confidence`, `score`, `created_at`, `tags`
* `status` — lifecycle state; always `active` for stored memories.
* `source` — who wrote the memory: `user`, `agent`, the connected MCP client's identity (e.g. `cursor`, `codex`), or the uploaded file name.
* `source_ref` — pointer to the original record within that source (e.g. tool-call or migration id). `null` when not set.
* `provenance` — how the memory was obtained (`explicit_statement`, `inferred`, …).
## Configuration
All configuration is via environment variables (load order: process env → `.env` file in the working directory). Most clients let you set these inside the `env` block of the MCP server entry.
| Variable | Required | Default | Description |
| -------------------------------- | :---------: | ----------- | ----------------------------------------------------------------------------------- |
| `MOORCHEH_API_KEY` | **yes** | — | Moorcheh API key. |
| `MEMANTO_DEFAULT_AGENT_ID` | recommended | — | Default agent. When set, tool calls may omit `agent_id`. |
| `MEMANTO_AGENT_PATTERN` | no | `tool` | Pattern (`support` / `project` / `tool`) used when auto-creating the default agent. |
| `MEMANTO_AGENT_AUTO_CREATE` | no | `true` | Create the default agent on first use if missing. |
| `MEMANTO_SESSION_DURATION_HOURS` | no | `6` | Session lifetime in hours (1 – 720). |
| `MEMANTO_EXPOSE_ADMIN` | no | `false` | Register the 4 agent-management tools. |
| `MEMANTO_MCP_TRANSPORT` | no | `stdio` | `stdio`, `sse`, or `streamable-http`. |
| `MEMANTO_MCP_HOST` | no | `127.0.0.1` | Bind host for sse / http transports. |
| `MEMANTO_MCP_PORT` | no | `8765` | Bind port for sse / http transports. |
| `MEMANTO_MCP_LOG_LEVEL` | no | `INFO` | Log level. Logs are always sent to stderr. |
CLI flags override env vars:
```bash theme={null}
memanto-mcp --transport sse --port 9000 --log-level DEBUG
```
## Running over HTTP / SSE
For remote clients or multi-process setups, run the server over a network transport:
```bash theme={null}
memanto-mcp --transport streamable-http --host 0.0.0.0 --port 8765
```
Point your client at `http://your-host:8765/mcp`.
```bash theme={null}
memanto-mcp --transport sse --host 0.0.0.0 --port 8765
```
Older transport, still widely supported.
The server authenticates **upstream** to Moorcheh with your API key, but does **not** authenticate inbound MCP clients. For production, pair it with a reverse proxy that enforces auth (e.g. mTLS, OAuth, or a shared bearer token).
## Programmatic Embedding
Wiring the server into a larger Python process or custom MCP host:
```python theme={null}
from memanto_mcp import MCPServerSettings, build_server
settings = MCPServerSettings() # reads env / .env
mcp = build_server(settings)
# Add your own tools alongside Memanto's, then run.
mcp.run(transport="stdio")
```
Useful when you want to combine Memanto with a domain-specific MCP toolset in one process.
## Sharing Memory Across Clients
Point multiple clients at the **same** `MEMANTO_DEFAULT_AGENT_ID` and they share one persistent memory namespace:
```json theme={null}
// Claude Desktop
"env": { "MEMANTO_DEFAULT_AGENT_ID": "my-personal" }
// Cursor
"env": { "MEMANTO_DEFAULT_AGENT_ID": "my-personal" }
```
A preference stored in Claude Desktop is now recallable from Cursor on the next tool call — Moorcheh's no-indexing search means the memory is queryable the millisecond it's written.
## Troubleshooting
| Symptom | Fix |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `configuration error: MOORCHEH_API_KEY is required` | Set the env var in your MCP client config's `env` block. |
| `Agent '…' does not exist and MEMANTO_AGENT_AUTO_CREATE is disabled` | Re-enable auto-create, or call `create_agent` (admin tools) / `memanto agent create ` once. |
| Tools never appear in the client | Confirm the client supports MCP and the config path matches. Check the client's MCP log: `memanto_mcp` lines on startup come from this server. |
| Garbled output in stdio mode | Something on your side is writing to **stdout** — that channel is reserved for JSON-RPC. Move logs to stderr. The server itself only writes to stderr. |
| Slow first call | Cold-start cost: SDK import + first session activation. Subsequent calls reuse the live session. |
| Session-expired errors mid-conversation | The server auto-renews before expiry. If you still see this, bump `MEMANTO_SESSION_DURATION_HOURS`. |
## Next Steps
Learn which memory type to pick for each piece of information.
Create, activate, and switch Memanto agents.
The REST endpoint the `remember` MCP tool wraps.
The REST endpoint the `recall` MCP tool wraps.
***
**Links**
* [`memanto-mcp` on PyPI](https://pypi.org/project/memanto-mcp/)
* [Memanto on GitHub](https://github.com/moorcheh-ai/memanto)
* [Model Context Protocol spec](https://modelcontextprotocol.io)
* [Anthropic MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
# n8n
Source: https://docs.memanto.ai/integrations/n8n
Connect Memanto to n8n automation workflows.
# n8n + Memanto
![n8n]()
Add persistent memory to your n8n workflows using Memanto's REST API.
n8n workflows are stateless by default — each execution starts fresh. With Memanto, you can store context from one workflow run and recall it in future runs, giving your automations a memory that grows over time.
## How It Works
```
n8n Workflow -> HTTP Request nodes -> Memanto Server -> Moorcheh.ai
```
Memanto exposes a simple REST API. In n8n, you call it using the built-in **HTTP Request** node — no custom code or plugins required.
Memanto authenticates with Moorcheh **on the server** using `MOORCHEH_API_KEY`. n8n nodes do **not** send an `Authorization` header. The only header you pass from n8n is `X-Session-Token` for memory operations.
## Prerequisites
* n8n (self-hosted or cloud)
* Memanto server accessible from your n8n instance, with `MOORCHEH_API_KEY` configured in its environment
## Step 1: Start Memanto Server
On your server or locally:
```bash theme={null}
export MOORCHEH_API_KEY=your_moorcheh_key
pip install memanto
memanto serve
```
> If n8n is running in the cloud or Docker, expose Memanto via a public URL or use a tunnel like ngrok.
***
## Core Workflow Patterns
### Pattern 1: Activate Session + Remember
Use this at the start of a workflow to open a session and store context.
**Node 1 — Activate Session (HTTP Request)**
| Field | Value |
| -------------- | ------------------------------------------------------------------ |
| Method | POST |
| URL | `http://your-memanto-server:8000/api/v2/agents/n8n-agent/activate` |
| Authentication | None |
This returns a `session_token`. Reference it in later nodes via:
```
{{ $node["Activate Session"].json.session_token }}
```
**Node 2 — Remember (HTTP Request)**
| Field | Value |
| --------- | ----------------------------------------------------------------------- |
| Method | POST |
| URL | `http://your-memanto-server:8000/api/v2/agents/n8n-agent/remember` |
| Headers | `X-Session-Token`: `{{ $node["Activate Session"].json.session_token }}` |
| JSON Body | `{ "content": "{{ $json.message }}", "type": "fact" }` |
***
### Pattern 2: Recall Context
Retrieve relevant memories before making an LLM call or sending a response.
**Node — Recall (HTTP Request)**
| Field | Value |
| --------- | ----------------------------------------------------------------------- |
| Method | POST |
| URL | `http://your-memanto-server:8000/api/v2/agents/n8n-agent/recall` |
| Headers | `X-Session-Token`: `{{ $node["Activate Session"].json.session_token }}` |
| JSON Body | `{ "query": "{{ $json.userMessage }}", "limit": 5 }` |
The response contains a `memories` array. Access the first result with:
```
{{ $json.memories[0].content }}
```
Or join all results into a single string using a **Code** node:
```javascript theme={null}
const memories = $input.first().json.memories || [];
return [{ json: { context: memories.map(m => `- ${m.content}`).join("\n") } }];
```
***
### Pattern 3: AI-Powered Answer from Memory
Let Memanto answer a question directly using its built-in RAG:
**Node — Answer (HTTP Request)**
| Field | Value |
| --------- | ----------------------------------------------------------------------- |
| Method | POST |
| URL | `http://your-memanto-server:8000/api/v2/agents/n8n-agent/answer` |
| Headers | `X-Session-Token`: `{{ $node["Activate Session"].json.session_token }}` |
| JSON Body | `{ "question": "{{ $json.question }}" }` |
Returns `answer` — a grounded response based on stored memories, no external LLM call needed.
***
## Example: Customer Support Workflow
This workflow receives a customer message via webhook, recalls past context, and sends a personalized reply.
```
[Webhook] → [Activate Session] → [Recall Context] → [Format Prompt] → [OpenAI] → [Remember Exchange] → [Respond]
```
**Webhook Node** — receives:
```json theme={null}
{ "customer_id": "cust_123", "message": "I need help with my order" }
```
**Activate Session** — `POST /api/v2/agents/{{ $json.customer_id }}/activate`
Using the customer ID as the agent ID gives each customer their own isolated memory.
**Recall Context** — `POST /api/v2/agents/{{ $json.customer_id }}/recall` with body `{ "query": "{{ $json.message }}", "limit": 5 }`
**Code Node — Format Prompt**
```javascript theme={null}
const memories = $input.first().json.memories || [];
const context = memories.length
? memories.map(m => `- ${m.content}`).join("\n")
: "No prior context.";
return [{
json: {
prompt: `Customer history:\n${context}\n\nCustomer: ${$("Webhook").item.json.message}\nAgent:`
}
}];
```
**OpenAI Node** — use the formatted prompt to generate a reply.
**Remember Exchange** — `POST /api/v2/agents/.../remember` with body `{ "content": "", "type": "fact" }`
***
## Memory Types in n8n
Set the `type` field in the Remember body to categorize what you store:
| Type | When to use |
| ------------ | -------------------------------------------------- |
| `fact` | Objective information about the user or entity |
| `preference` | User likes, dislikes, or settings |
| `decision` | Choices made during the workflow |
| `commitment` | Promises or follow-up actions |
| `event` | Things that happened (order placed, ticket opened) |
| `error` | Issues or failures to avoid repeating |
***
## Sessions in Long-Running Workflows
Memanto auto-renews sessions that are near expiry on memory requests, so most workflows can simply reuse the token from the activation step. There is no separate `/session/extend` endpoint.
For scheduled or long-lived workflows, the simplest pattern is to **activate a fresh session at the start of each run** rather than persisting the token between executions:
```
[Trigger] → [Activate Session] → ...remaining nodes use the new token...
```
If a request returns `401 Unauthorized`, re-run the Activate Session node and continue with the new token.
***
## Next Steps
* [Remember API](/api-reference/data/remember)
* [Recall API](/api-reference/search/recall)
* [Session Management](/guides/session-management)
* [Memory Types Reference](/reference/memory-types)
# Open Knowledge Format (OKF)
Source: https://docs.memanto.ai/integrations/okf
Move memories in and out of Memanto as portable OKF bundles — a vendor-neutral, human- and agent-readable markdown format.
# Open Knowledge Format (OKF)
![Google Cloud]()
[Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf)
is an open, vendor-neutral specification from **Google Cloud** (v0.1) that
formalizes the "LLM-wiki" pattern: knowledge stored as a directory of markdown
files with YAML frontmatter, one concept per file, linked with plain markdown
links.
Memanto uses OKF as its **portable, at-rest interchange format**. Moorcheh stays
the retrieval engine — OKF is only how memories are represented on disk so they
can be exported, browsed, versioned in git, and imported elsewhere without lock-in.
Write an agent's memories to an OKF bundle — one folder per memory type, plus daily summaries, session logs, and metrics.
Load any OKF bundle into an agent with `memanto migrate okf`. Unmapped fields are preserved, nothing is lost.
Drop a browsable OKF bundle into a project directory for an agent (or human) to read.
Memanto-only fields ride along in an `x_memanto` frontmatter block, so Memanto → OKF → Memanto round-trips keep confidence, provenance, and source.
## What an OKF document looks like
Only `type` is required; every other field is optional.
```markdown theme={null}
---
type: fact
title: Postgres is the primary database
description: The project uses PostgreSQL 16.
tags: [infra, db]
timestamp: 2026-05-28T14:30:00Z
resource: https://example.com/db
x_memanto:
confidence: 0.9
provenance: explicit_statement
source: user
type: fact
---
The project uses PostgreSQL 16 as its primary database. Runs on port 5432.
```
## Export
```bash theme={null}
memanto memory export --okf
```
Writes an OKF bundle to `~/.memanto/exports/_okf/`. The bundle nests
memories under `memories/` alongside export-only context sections (only the
sections that have data are written):
```
_okf/
├── index.md # navigation for the whole bundle
├── memories/ # the 13 memory types (from Moorcheh)
│ ├── index.md
│ ├── fact/
│ │ ├── index.md
│ │ └── postgres-is-the-primary-database.md
│ └── decision/ …
├── daily-summaries/ # generated daily-summary files (if any)
├── sessions/ # per-session logs: what was added/removed, and from where
└── metrics/ # aggregate stats & ASCII visualizations
└── overview.md
```
**Layout — `--split`:** controls how each memory type folder is written.
| Value | Behavior |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `auto` (default) | One file per memory, but a type with more than 50 memories collapses to a single stacked file to avoid thousands of files. |
| `file` | Always one file per memory. |
| `type` | Always a single stacked file per type. |
See [`memanto memory export`](/cli/data/export) for all options.
## Import
```bash theme={null}
memanto migrate okf ./okf-bundle
```
`migrate okf` accepts a bundle directory (or a single `.md` file), maps each
node onto Memanto's schema, and bulk-writes the memories into the target agent.
It runs as a subcommand of [`memanto migrate`](/cli/migrate/migrate) but, unlike
the provider migrations, needs no API key and produces no savings report — OKF
is a local file format, not a competing provider.
* Fields that don't map onto a Memanto column are preserved in a bounded
`[Supporting data]` footer appended to the memory content, so **nothing is lost**.
* OKF's `type` is free-form domain vocabulary (`BigQuery Table`, `Runbook`, …).
When it isn't one of Memanto's 13 types, it is **auto-classified** and the
original type is kept in the footer.
* Import is **scoped to `memories/`** when a bundle has that folder, so
daily-summaries, sessions, and metrics are never re-ingested as memories.
Preview without writing:
```bash theme={null}
memanto migrate okf ./okf-bundle --dry-run
```
## Sync
```bash theme={null}
memanto memory sync --okf --project-dir ./my-project
```
Runs a fresh export and copies the OKF bundle into `./my-project/okf/`, giving
an agent (or a teammate) a browsable, git-friendly memory wiki. See
[`memanto memory sync`](/cli/data/sync).
## Field mapping
| OKF field | Export (Memanto → OKF) | Import (OKF → Memanto) |
| ------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `type` | Memanto type verbatim | Auto-classify; used directly only when it equals a Memanto type or an `x_memanto.type` round-trip value is present |
| `title` | `title` | `title` |
| `description` | first line of content | prepended to content |
| body | `content` | `content` |
| `resource` | `source_ref` | `source_ref` |
| `tags` | `tags` | `tags` |
| `timestamp` | `created_at` | `created_at` |
| `x_memanto` | confidence, provenance, source, id, status | read back when present |
## Notes & limitations
* **Round-trip:** Memanto → OKF → Memanto preserves the extra fields via
`x_memanto`. Importing a *foreign* bundle auto-classifies `type` (the OKF and
Memanto vocabularies differ), so it is not byte-identical — this is inherent
to the format, not a bug.
* **Links:** exported bundles are flat — Memanto does not store inter-memory
edges, so no cross-links are generated. Links found in imported bodies are
preserved verbatim and listed in the footer.
* **Context sections** (`daily-summaries/`, `sessions/`, `metrics/`) are read
from local files under `~/.memanto/`; a machine that has never generated a
daily summary exports memories only.
# OpenAI SDK
Source: https://docs.memanto.ai/integrations/openai
Give OpenAI Node SDK agents persistent, cross-session memory with Memanto tools.
# OpenAI SDK + Memanto
![OpenAI]()
Add persistent memory to any [OpenAI Node SDK](https://github.com/openai/openai-node) agent with three ready-made tools, shipped as part of the `@moorcheh-ai/memanto` TypeScript SDK.
## Prerequisites
* Node.js 20+
* [`uv`](https://docs.astral.sh/uv/) (ships `uvx`) — the `Memanto` client spawns a local Memanto server via `uvx` on first use unless you pass `baseUrl`
* **Memanto / Moorcheh credentials** — [Moorcheh API key](https://console.moorcheh.ai/api-keys) (cloud) or an [on-prem](/on-prem/overview) backend (no Moorcheh API key). Set `MOORCHEH_API_KEY` or pass `apiKey` to `new Memanto({ ... })`
* **OpenAI API key** — the quick start uses `gpt-4o` via `runTools()`, which reads `OPENAI_API_KEY` from the environment (or pass `apiKey` to `new OpenAI({ ... })`).
* `openai` and `zod` installed in your app (optional peer dependencies of `@moorcheh-ai/memanto`)
## Install
```bash theme={null}
npm install @moorcheh-ai/memanto openai zod
```
`openai` and `zod` are optional peer dependencies of `@moorcheh-ai/memanto` — install them yourself in the host app. Importing `@moorcheh-ai/memanto/openai` without them installed will fail at module load with a standard Node resolution error.
## Quick Start
```ts theme={null}
import OpenAI from "openai";
import { Memanto } from "@moorcheh-ai/memanto";
import { createMemantoOpenAITools } from "@moorcheh-ai/memanto/openai";
const client = new OpenAI(); // reads OPENAI_API_KEY — powers runTools(), not Memanto tools
const memanto = new Memanto({
agentId: "my-agent",
apiKey: process.env.MOORCHEH_API_KEY, // omit when using on-prem; see On-Prem below
});
const runner = client.chat.completions.runTools({
model: "gpt-4o",
tools: createMemantoOpenAITools(memanto),
messages: [
{ role: "user", content: "What milk does Alex like? Also note he switched to soy today." },
],
});
console.log(await runner.finalContent());
```
`createMemantoOpenAITools` returns an array of tools built with `zodFunction`, ready to hand to the OpenAI Node SDK's [`runTools()`](https://github.com/openai/openai-node#automated-function-calls) helper — each tool auto-parses its JSON arguments against a Zod schema before invoking Memanto.
Each tool's description is written for the model to decide *when* to call it (e.g. `recallMemory`: "Call this before answering whenever the user refers to information from earlier or from a previous session").
## Available Tools
| Tool | Backed by | Description |
| ---------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `recallMemory` | [Recall](/api-reference/search/recall) | Semantic search over stored memories. `query` (required), `limit` (nullable — pass `null` for the default), `type` (nullable array of memory types to filter by, or `null` for no filter). |
| `rememberMemory` | [Remember](/api-reference/data/remember) | Persist a durable fact/preference/decision/instruction. `content` (required), `type` (optional — server auto-classifies if omitted), `title`, `tags`. |
| `answerMemory` | [Generate AI Answer](/api-reference/ai/generate-ai-answer) | RAG-synthesized answer over stored memories. `question` (required), `limit` (nullable — pass `null` for the default). |
`answerMemory` calls Memanto's **Generate AI Answer** API (`memanto.answer()` → Moorcheh `answer.generate`). Memanto retrieves relevant memories and synthesizes a grounded response using **Memanto's configured LLM** — not the model you pass to `runTools()`. Your agent model only decides *when* to call the tool and how to use the result. `recallMemory` and `rememberMemory` do not invoke an LLM.
Unlike the Vercel AI SDK and Mastra variants, this integration's schemas use nullable fields (`.nullable()`) instead of optional ones, matching the OpenAI function-calling convention where the model must explicitly pass `null` rather than omit a field.
## Options
```ts theme={null}
createMemantoOpenAITools(memanto, {
include: ["recallMemory", "answerMemory"], // expose a subset — omit for all three
defaultLimit: 10, // default limit for recall/answer when the model doesn't specify one
});
```
## Memory Types
`type` fields are constrained to Memanto's 13 supported types via a shared `MEMORY_TYPES` export:
```ts theme={null}
import { MEMORY_TYPES } from "@moorcheh-ai/memanto/openai";
// ["fact", "preference", "goal", "decision", "artifact", "learning", "event",
// "instruction", "relationship", "context", "observation", "commitment", "error"]
```
See the [Memory Types Reference](/reference/memory-types) for what each type means.
## On-Prem
The integration talks to Memanto through the `Memanto` client, so it works identically against an on-prem backend — no code changes, just configure the backend once with the CLI. See [On-Prem Overview](/on-prem/overview) and the [TypeScript SDK Reference](/sdk/typescript#on-prem-no-api-key).
## Next Steps
* [TypeScript SDK Reference](/sdk/typescript) for the full `Memanto` client API
* [Vercel AI SDK Integration](/integrations/vercel-ai-sdk) for the equivalent AI SDK tools
* [Mastra Integration](/integrations/mastra) for the equivalent Mastra tools
* [Memory Types Reference](/reference/memory-types)
# OpenCode
Source: https://docs.memanto.ai/integrations/opencode
Give the OpenCode CLI persistent, cross-session memory with Memanto.
# OpenCode + Memanto
![OpenCode]()
Connect the [OpenCode CLI](https://opencode.ai) to Memanto so it can store and recall persistent memory across sessions.
## Connect via CLI (recommended)
```bash theme={null}
memanto connect opencode
```
This installs an OpenCode-specific instruction file and the `memanto-memory` skill into your project. Add `--global` to install system-wide:
```bash theme={null}
memanto connect opencode --global
```
## Connect via MCP
OpenCode supports MCP, so you can alternatively register Memanto as an MCP server. See the [MCP integration guide](/integrations/mcp) for the `memanto-mcp` server reference and config.
## Next Steps
* [CLI: connect command](/cli/connect/connect)
* [MCP Integration](/integrations/mcp)
* [Memory Types Reference](/reference/memory-types)
# Overview
Source: https://docs.memanto.ai/integrations/overview
Overview of Memanto integrations with popular AI frameworks, MCP clients, and IDEs.
# Integrations Overview
Memanto plugs into AI assistants, frameworks, IDEs, and your observability stack through several complementary paths:
Add Memanto to any **Model Context Protocol** client (Claude Desktop, Cursor, Windsurf, Cline, Continue, Goose, …) with a single JSON config block.
Drop-in memory for agent frameworks — [CrewAI](/integrations/crewai), [Hermes](/integrations/hermes-agents), [LangChain](/integrations/langchain), [LangGraph](/integrations/langgraph), [LlamaIndex](/integrations/llamaindex), and [n8n](/integrations/n8n) in Python; [Vercel AI SDK](/integrations/vercel-ai-sdk), [Mastra](/integrations/mastra), [VoltAgent](/integrations/voltagent), and [OpenAI](/integrations/openai) via the TypeScript SDK.
`memanto connect ` installs a tool-specific skill file (e.g. `CLAUDE.md`, `.cursor/rules/memanto.mdc`) into your project.
Move memories in and out of Memanto as portable **[Open Knowledge Format](/integrations/okf)** bundles — vendor-neutral markdown you can browse, version in git, and import anywhere.
Turn **[Langfuse](/integrations/langfuse)** errors, failed evals, and latency/cost anomalies into memories — live from your app or on a one-shot sync — so agents stop re-learning the same failure.
Most users start with **MCP** — it's the lowest-friction way to give a desktop AI assistant persistent memory. Use **frameworks** when building custom agents in Python, **IDE skills** when you want a checked-in rules file your team can share, and **observability** when you want production failures to become durable lessons.
## Supported Tools
Memanto integrates with 13+ AI coding assistants. Each has its own setup page — click through for the CLI connector and MCP config:
| Tool | Type | Status |
| ------------------------------------------------------------------------ | ------------- | ----------- |
| ![]()
[**Claude Code**](/integrations/claude-code) | IDE Extension | ✓ Supported |
| ![]()
[**Cursor**](/integrations/cursor) | IDE | ✓ Supported |
| ![]()
[**Cline**](/integrations/cline) | IDE Extension | ✓ Supported |
| ![]()
[**Windsurf**](/integrations/windsurf) | IDE | ✓ Supported |
| [**Continue**](/integrations/continue) | IDE Extension | ✓ Supported |
| ![]()
[**Codex**](/integrations/codex) | IDE | ✓ Supported |
| ![]()
[**Gemini CLI**](/integrations/gemini-cli) | CLI | ✓ Supported |
| ![]()
[**GitHub Copilot**](/integrations/github-copilot) | IDE Extension | ✓ Supported |
| ![]()
[**OpenCode**](/integrations/opencode) | IDE | ✓ Supported |
| ![]()
[**Goose**](/integrations/goose) | IDE | ✓ Supported |
| ![]()
[**Roo**](/integrations/roo) | IDE | ✓ Supported |
| ![]()
[**Antigravity**](/integrations/antigravity) | IDE | ✓ Supported |
| [**Augment**](/integrations/augment) | IDE | ✓ Supported |
## What Integrations Enable
Once connected, tools can:
### 1. Store Development Context
```
"User prefers TypeScript and strict type checking"
"Project uses React 18 with hooks"
"API endpoints follow REST conventions"
```
### 2. Recall Past Decisions
```
Query: "Why did we choose PostgreSQL?"
Result: "Chose PostgreSQL to support JSON queries efficiently"
```
### 3. Access Memory APIs
Full programmatic access to:
* Store memories
* Recall memories
* Generate answers
* Manage sessions
### 4. Continuous Learning
Tools learn from previous sessions and carry context forward.
## Quick Start
### Step 1: Install & Configure Memanto
```bash theme={null}
pip install memanto
memanto # Configure with API key
```
### Step 2: Create Agent
```bash theme={null}
memanto agent create dev-assistant
memanto agent activate dev-assistant
```
### Step 3: Connect Your Tool
```bash theme={null}
# For Claude Code
memanto connect claude-code
# For Cursor
memanto connect cursor
# For Windsurf
memanto connect windsurf
```
### Step 4: Start Using
Your tool now has access to memories!
## Integration Patterns
### Single Tool Integration
Connect one tool:
```bash theme={null}
memanto connect claude-code
```
Benefits:
* Simple setup
* Clear memory isolation
* Perfect for single-person projects
### Team Integration
Connect multiple tools:
```bash theme={null}
memanto connect claude-code
memanto connect cursor
memanto connect windsurf
```
Benefits:
* Team shared context
* Cross-tool consistency
* Better collaboration
### Multi-Environment
Different agents for different projects:
```bash theme={null}
# In your Development project
cd my-dev-project
memanto agent activate dev-assistant
memanto connect claude-code
# In your Production project
cd my-prod-project
memanto agent activate prod-assistant
memanto connect claude-code
```
## Use Cases
### Learning New Codebase
Tool remembers:
* Architecture decisions
* Naming conventions
* Common patterns
* "Why" behind decisions
### Multi-Session Development
Tool carries context across days:
* Open issues
* In-progress features
* Code review feedback
* Design decisions
### Team Onboarding
New team members benefit from:
* Accumulated project knowledge
* Decision history
* Best practices
* Common pitfalls to avoid
### Cross-Project Knowledge
Tool learns and applies:
* Patterns from Project A to Project B
* Solutions to common problems
* Team conventions
* Lessons learned
## Configuration
### Local Scope
```bash theme={null}
memanto connect claude-code
# Installs in: project/.claude/memanto
# Only this project can access
```
### Global Scope
```bash theme={null}
memanto connect claude-code --global
# System-wide installation
# All projects can access
```
## Management
### List Connections
```bash theme={null}
memanto connect list
```
Shows all connected tools and their scope.
### Remove Connection
```bash theme={null}
memanto connect remove claude-code
```
Disconnects a tool (memories remain).
### Connect Multiple
```bash theme={null}
memanto connect multi
```
Interactive selection of multiple tools.
## Tips & Tricks
### Share Context Across Tools
```bash theme={null}
# Same agent for all tools
memanto connect claude-code
memanto connect cursor
memanto connect windsurf
# All three access same memories
```
### Switch Contexts
```bash theme={null}
# Need to work on a different context? Switch the active agent:
memanto agent activate different-agent
# Now all your connected tools will use the new agent's memory
```
### Backup Memories
```bash theme={null}
# Export before disconnecting
memanto memory export
# All memories saved locally
```
For a portable, git-friendly backup, export an [OKF](/integrations/okf) bundle
instead — a directory of markdown files you can browse or import into another
agent:
```bash theme={null}
memanto memory export --okf
```
## Next Steps
* [Installation Guide](/getting-started/installation)
* [CLI: Connect Commands](/cli/connect/connect)
***
Integrations let Memanto work within your favorite development tools!
# Roo Code
Source: https://docs.memanto.ai/integrations/roo
Give Roo Code persistent, cross-session memory with Memanto.
# Roo Code + Memanto
![Roo Code]()
Connect [Roo Code](https://roocode.com) to Memanto so it can store and recall persistent memory across sessions.
## Connect via CLI (recommended)
```bash theme={null}
memanto connect roo
```
This installs a Roo-specific instruction file and the `memanto-memory` skill into your project. Add `--global` to install system-wide:
```bash theme={null}
memanto connect roo --global
```
## Connect via MCP
Roo Code supports MCP, so you can alternatively register Memanto as an MCP server. See the [MCP integration guide](/integrations/mcp) for the `memanto-mcp` server reference and config.
## Next Steps
* [CLI: connect command](/cli/connect/connect)
* [MCP Integration](/integrations/mcp)
* [Memory Types Reference](/reference/memory-types)
# Vercel AI SDK
Source: https://docs.memanto.ai/integrations/vercel-ai-sdk
Give Vercel AI SDK agents persistent, cross-session memory with Memanto tools.
# Vercel AI SDK + Memanto
![Vercel AI SDK]()
Add persistent memory to any [Vercel AI SDK](https://sdk.vercel.ai/) agent with three ready-made tools, shipped as part of the `@moorcheh-ai/memanto` TypeScript SDK.
## Prerequisites
* Node.js 20+
* [`uv`](https://docs.astral.sh/uv/) (ships `uvx`) — the `Memanto` client spawns a local Memanto server via `uvx` on first use unless you pass `baseUrl`
* **Memanto / Moorcheh credentials** — [Moorcheh API key](https://console.moorcheh.ai/api-keys) (cloud) or an [on-prem](/on-prem/overview) backend (no Moorcheh API key). Set `MOORCHEH_API_KEY` or pass `apiKey` to `new Memanto({ ... })`
* **Agent model credentials** — the quick start uses OpenAI `gpt-4o` for tool orchestration. Set `OPENAI_API_KEY` (or swap `openai("gpt-4o")` for any [AI SDK provider](https://sdk.vercel.ai/providers) you already use).
* `ai`, `zod`, and `@ai-sdk/openai` installed in your app (`ai` and `zod` are optional peer dependencies of `@moorcheh-ai/memanto`)
## Install
```bash theme={null}
npm install @moorcheh-ai/memanto ai zod @ai-sdk/openai
```
`ai` and `zod` are optional peer dependencies of `@moorcheh-ai/memanto` — install them yourself in the host app. Importing `@moorcheh-ai/memanto/ai-sdk` without them installed will fail at module load with a standard Node resolution error.
## Quick Start
```ts theme={null}
import { generateText, stepCountIs } from "ai";
import { openai } from "@ai-sdk/openai";
import { Memanto } from "@moorcheh-ai/memanto";
import { createMemantoTools } from "@moorcheh-ai/memanto/ai-sdk";
const memanto = new Memanto({
agentId: "my-agent",
apiKey: process.env.MOORCHEH_API_KEY, // omit when using on-prem; see On-Prem below
});
const { text } = await generateText({
model: openai("gpt-4o"), // requires OPENAI_API_KEY — swap for your provider if needed
tools: createMemantoTools(memanto),
stopWhen: stepCountIs(5),
prompt: "What milk does Alex like? Also note he switched to soy today.",
});
console.log(text);
```
`createMemantoTools` returns an object with three [AI SDK tools](https://sdk.vercel.ai/docs/ai-sdk-core/tools-and-tool-calling) — pass it straight into `tools` on `generateText` / `streamText`.
## Available Tools
| Tool | Backed by | Description |
| ---------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `recallMemory` | [Recall](/api-reference/search/recall) | Semantic search over stored memories. `query` (required), `limit` (1-50), `type` (optional array of memory types to filter by). |
| `rememberMemory` | [Remember](/api-reference/data/remember) | Persist a durable fact/preference/decision/instruction. `content` (required), `type` (optional — server auto-classifies if omitted), `title`, `tags`. |
| `answerMemory` | [Generate AI Answer](/api-reference/ai/generate-ai-answer) | RAG-synthesized answer over stored memories. `question` (required), `limit` (1-100). |
`answerMemory` calls Memanto's **Generate AI Answer** API (`memanto.answer()` → Moorcheh `answer.generate`). Memanto retrieves relevant memories and synthesizes a grounded response using **Memanto's configured LLM** — not the model you pass to `generateText` / `streamText`. Your agent model only decides *when* to call the tool and how to use the result. `recallMemory` and `rememberMemory` do not invoke an LLM.
Each tool's description is written for the model to decide *when* to call it (e.g. `recallMemory`: "Call this before answering whenever the user refers to information from earlier or from a previous session").
## Options
```ts theme={null}
createMemantoTools(memanto, {
include: ["recallMemory", "answerMemory"], // expose a subset — omit for all three
defaultLimit: 10, // default limit for recall/answer when the model doesn't specify one
});
```
## Memory Types
`type` fields are constrained to Memanto's 13 supported types via a shared `MEMORY_TYPES` export:
```ts theme={null}
import { MEMORY_TYPES } from "@moorcheh-ai/memanto/ai-sdk";
// ["fact", "preference", "goal", "decision", "artifact", "learning", "event",
// "instruction", "relationship", "context", "observation", "commitment", "error"]
```
See the [Memory Types Reference](/reference/memory-types) for what each type means.
## On-Prem
The integration talks to Memanto through the `Memanto` client, so it works identically against an on-prem backend — no code changes, just configure the backend once with the CLI. See [On-Prem Overview](/on-prem/overview) and the [TypeScript SDK Reference](/sdk/typescript#on-prem-no-api-key).
## Next Steps
* [TypeScript SDK Reference](/sdk/typescript) for the full `Memanto` client API
* [Mastra Integration](/integrations/mastra) for the equivalent Mastra tools
* [OpenAI Integration](/integrations/openai) for the equivalent OpenAI `runTools()` tools
* [Memory Types Reference](/reference/memory-types)
# VoltAgent
Source: https://docs.memanto.ai/integrations/voltagent
Give VoltAgent agents persistent, cross-session memory with Memanto tools.
# VoltAgent + Memanto
![VoltAgent]()
Add persistent memory to any [VoltAgent](https://voltagent.dev/) agent with three ready-made tools, shipped as part of the `@moorcheh-ai/memanto` TypeScript SDK.
## Prerequisites
* Node.js 20+
* [`uv`](https://docs.astral.sh/uv/) (ships `uvx`) -the `Memanto` client spawns a local Memanto server via `uvx` on first use unless you pass `baseUrl`
* **Memanto / Moorcheh credentials** -[Moorcheh API key](https://console.moorcheh.ai/api-keys) (cloud) or an [on-prem](/on-prem/overview) backend (no Moorcheh API key). Set `MOORCHEH_API_KEY` or pass `apiKey` to `new Memanto({ ... })`
* **Agent model credentials** -the quick start uses OpenAI `gpt-4o` for tool orchestration. Set `OPENAI_API_KEY` (or swap `openai("gpt-4o")` for any provider VoltAgent supports). Memanto memory tools do **not** use this key -they talk to Memanto/Moorcheh only
* `@voltagent/core` and `zod` installed in your app (optional peer dependencies of `@moorcheh-ai/memanto`)
## Install
```bash theme={null}
npm install @moorcheh-ai/memanto @voltagent/core zod @ai-sdk/openai
```
`@voltagent/core` and `zod` are optional peer dependencies of `@moorcheh-ai/memanto` -install them yourself in the host app. Importing `@moorcheh-ai/memanto/voltagent` without them installed will fail at module load with a standard Node resolution error.
## Quick Start
```ts theme={null}
import { Agent } from "@voltagent/core";
import { openai } from "@ai-sdk/openai";
import { Memanto } from "@moorcheh-ai/memanto";
import { createMemantoVoltAgentTools } from "@moorcheh-ai/memanto/voltagent";
const memanto = new Memanto({
agentId: "my-agent",
apiKey: process.env.MOORCHEH_API_KEY, // omit when using on-prem; see On-Prem below
});
const agent = new Agent({
name: "Assistant",
instructions:
"You have long-term memory. Persist durable facts with rememberMemory " +
"and look them up with recallMemory / answerMemory before answering.",
model: openai("gpt-4o"), // requires OPENAI_API_KEY -swap for your provider if needed
tools: createMemantoVoltAgentTools(memanto),
});
const response = await agent.generateText(
"What milk does Alex like? Also note he switched to soy today.",
);
console.log(response.text);
```
`createMemantoVoltAgentTools` returns an array of three [VoltAgent tools](https://voltagent.dev/docs/agents/tools/) -pass it straight into an agent's `tools` array.
Each tool's description is written for the model to decide *when* to call it (e.g. `recallMemory`: "Call this before answering whenever the user refers to information from earlier or from a previous session").
## Available Tools
| Tool | Backed by | Description |
| ---------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `recallMemory` | [Recall](/api-reference/search/recall) | Semantic search over stored memories. `query` (required), `limit` (1-50), `type` (optional array of memory types to filter by). |
| `rememberMemory` | [Remember](/api-reference/data/remember) | Persist a durable fact/preference/decision/instruction. `content` (required), `type` (optional -server auto-classifies if omitted), `title`, `tags`. |
| `answerMemory` | [Generate AI Answer](/api-reference/ai/generate-ai-answer) | RAG-synthesized answer over stored memories. `question` (required), `limit` (1-100). |
`answerMemory` calls Memanto's **Generate AI Answer** API (`memanto.answer()` → Moorcheh `answer.generate`). Memanto retrieves relevant memories and synthesizes a grounded response using **Memanto's configured LLM** -not the model you pass to your VoltAgent `Agent`. Your agent model only decides *when* to call the tool and how to use the result. `recallMemory` and `rememberMemory` do not invoke an LLM.
## Options
```ts theme={null}
createMemantoVoltAgentTools(memanto, {
include: ["recallMemory", "answerMemory"], // expose a subset -omit for all three
defaultLimit: 10, // default limit for recall/answer when the model doesn't specify one
});
```
## Memory Types
`type` fields are constrained to Memanto's 13 supported types via a shared `MEMORY_TYPES` export:
```ts theme={null}
import { MEMORY_TYPES } from "@moorcheh-ai/memanto/voltagent";
// ["fact", "preference", "goal", "decision", "artifact", "learning", "event",
// "instruction", "relationship", "context", "observation", "commitment", "error"]
```
See the [Memory Types Reference](/reference/memory-types) for what each type means.
## On-Prem
The integration talks to Memanto through the `Memanto` client, so it works identically against an on-prem backend -no code changes, just configure the backend once with the CLI. See [On-Prem Overview](/on-prem/overview) and the [TypeScript SDK Reference](/sdk/typescript#on-prem-no-api-key).
## Next Steps
* [TypeScript SDK Reference](/sdk/typescript) for the full `Memanto` client API
* [Vercel AI SDK Integration](/integrations/vercel-ai-sdk) for the equivalent AI SDK tools
* [Mastra Integration](/integrations/mastra) for the equivalent Mastra tools
* [OpenAI Integration](/integrations/openai) for the equivalent OpenAI `runTools()` tools
* [Memory Types Reference](/reference/memory-types)
# Windsurf
Source: https://docs.memanto.ai/integrations/windsurf
Give Windsurf persistent, cross-session memory with Memanto — via the CLI connector or as an MCP server.
# Windsurf + Memanto
![Windsurf]()
Connect [Windsurf](https://windsurf.com) to Memanto so Cascade can store and recall persistent memory across sessions.
## Connect via CLI (recommended)
```bash theme={null}
memanto connect windsurf
```
This installs a Windsurf-specific instruction file and the `memanto-memory` skill into your project. Add `--global` to install to `~/.codeium/` for every project:
```bash theme={null}
memanto connect windsurf --global
```
## Connect via MCP
Windsurf is an MCP client, so you can alternatively register Memanto as an MCP server. Edit `~/.codeium/windsurf/mcp_config.json`:
```json theme={null}
{
"mcpServers": {
"memanto": {
"command": "memanto-mcp",
"env": {
"MOORCHEH_API_KEY": "mch_xxxxxxxxxxxxxxxxxx",
"MEMANTO_DEFAULT_AGENT_ID": "windsurf-workspace"
}
}
}
}
```
Reload Windsurf via **Cascade → MCP Servers → Refresh**. See the [MCP integration guide](/integrations/mcp) for the full server reference.
## Next Steps
* [CLI: connect command](/cli/connect/connect)
* [MCP Integration](/integrations/mcp)
* [Memory Types Reference](/reference/memory-types)
# Commands Reference
Source: https://docs.memanto.ai/memantoclaw/commands
Complete CLI reference for MemantoClaw.
# Commands
The `memantoclaw` CLI handles host-side operations outside the OpenClaw plugin context.
## Standalone Host Commands
| Command | Description | Notes |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `memantoclaw onboard` | Run the interactive setup wizard. Creates gateway, registers providers, builds the image, and launches the sandbox. | `memantoclaw onboard [--non-interactive] [--resume] [--from ]` |
| `memantoclaw list` | List all registered sandboxes with their model, provider, and policy presets. | |
| `memantoclaw connect` | Connect to a sandbox by name. Drops you into the sandbox shell where you can run `openclaw tui`. | |
| `memantoclaw status` | Show sandbox status, health, and inference configuration. | Probes local inference backends to report `healthy` or `unreachable`. |
| `memantoclaw logs` | View sandbox logs. | Use `--follow` to stream output in real time. |
| `memantoclaw destroy` | Stop the NIM container and delete the sandbox permanently. | Back up workspace files first. |
| `memantoclaw policy-add` | Add a policy preset to a sandbox (e.g., `github`, `npm`). | Use `--dry-run` to preview the endpoints it would open. |
| `memantoclaw policy-list` | List available policy presets and show which ones are applied. | |
| `openshell term` | Open the OpenShell TUI to monitor sandbox activity and approve network requests. | |
| `memantoclaw start` / `stop` | Start or stop optional host auxiliary services (like the cloudflared tunnel). | |
| `memantoclaw debug` | Collect diagnostics (system info, Docker state, logs) for bug reports into a tarball. | |
| `memantoclaw credentials list` | List stored credential names. | Values are not printed. |
| `memantoclaw credentials reset ` | Remove a stored credential by name. | Forces a re-prompt on the next onboard. |
| `memantoclaw uninstall` | Run `uninstall.sh` to remove sandboxes, gateway resources, and local state. | `memantoclaw uninstall [--yes] [--keep-openshell] [--delete-models]` |
*For complete, unabridged technical details on this topic, refer to the official [NVIDIA NemoClaw Documentation](https://docs.nvidia.com/nemoclaw/latest/reference/commands.html). Portions of this guide are summarized and adapted from NVIDIA Corporation (Copyright © 2026), licensed under the Apache License, Version 2.0.*
# Inference Routing
Source: https://docs.memanto.ai/memantoclaw/inference
Manage inference providers, local models, and hot-swapping.
# Inference Options
MemantoClaw supports multiple inference providers. During onboarding, the `memantoclaw onboard` wizard presents a list of providers to choose from. Your selection determines where the agent's inference traffic is routed.
## How Inference Routing Works
The agent inside the sandbox talks to `inference.local`. It never connects to a provider directly. OpenShell intercepts inference traffic on the host and forwards it to the provider you selected. Provider credentials stay entirely on the host.
### Provider Options
| Provider | Description |
| ----------------------------- | ------------------------------------------------------------------------------------------- |
| **Moorcheh Routed Inference** | The native MemantoClaw experience. Routes inference directly using your `MOORCHEH_API_KEY`. |
| **NVIDIA Endpoints** | Routes to models hosted on build.nvidia.com. (e.g., Nemotron 3 Super) |
| **OpenAI** | Routes to the OpenAI API. |
| **Anthropic** | Routes to the Anthropic Messages API. |
| **Google Gemini** | Routes to Google's OpenAI-compatible endpoint. |
## Switching Inference Models at Runtime
You can change the active inference model while the sandbox is running. No restart is required. Switching happens through the OpenShell inference route.
```bash theme={null}
# Example for NVIDIA Endpoints
openshell inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b
# Example for OpenAI
openshell inference set --provider openai-api --model gpt-5.4
# Example for Anthropic
openshell inference set --provider anthropic-prod --model claude-sonnet-4-6
```
### Cross-Provider Switching
Switching to a different provider family requires updating both the gateway route and the sandbox config.
```bash theme={null}
openshell inference set --provider anthropic-prod --model claude-sonnet-4-6 --no-verify
export MEMANTOCLAW_MODEL_OVERRIDE="anthropic/claude-sonnet-4-6"
export MEMANTOCLAW_INFERENCE_API_OVERRIDE="anthropic-messages"
memantoclaw onboard --resume --recreate-sandbox
```
## Using a Local Inference Server
MemantoClaw can route inference to a model server running on your machine.
### Ollama
Ollama is the default local option. The wizard detects it automatically. On Linux with Docker, the sandbox reaches Ollama through `http://host.openshell.internal:11434`. Make sure Ollama listens on `0.0.0.0:11434`.
### OpenAI/Anthropic Compatible Servers
Works with vLLM, TensorRT-LLM, llama.cpp, LocalAI, etc. Select "Other OpenAI-compatible endpoint" and enter your base URL (e.g., `http://localhost:8000/v1`). The wizard will probe `/v1/responses` and fall back to `/v1/chat/completions` if streaming events are incompatible.
### Experimental Local vLLM & NVIDIA NIM
Set `MEMANTOCLAW_EXPERIMENTAL=1` to enable vLLM auto-detection on `localhost:8000` or NIM container management on hosts with NIM-capable NVIDIA GPUs.
```bash theme={null}
MEMANTOCLAW_EXPERIMENTAL=1 memantoclaw onboard
```
### Timeout Configuration
Local inference requests use a default timeout of 180 seconds. Increase it if needed:
```bash theme={null}
export MEMANTOCLAW_LOCAL_INFERENCE_TIMEOUT=300
memantoclaw onboard
```
*For complete, unabridged technical details on this topic, refer to the official [NVIDIA NemoClaw Documentation](https://docs.nvidia.com/nemoclaw/latest/inference/inference-options.html). Portions of this guide are summarized and adapted from NVIDIA Corporation (Copyright © 2026), licensed under the Apache License, Version 2.0.*
# Network Policies
Source: https://docs.memanto.ai/memantoclaw/network-policies
Egress controls, operator approvals, and policy customization.
# Network Policies
MemantoClaw runs with a deny-by-default network policy. The sandbox can only reach endpoints that are explicitly allowed. Any request to an unlisted destination is intercepted by OpenShell.
## Baseline Policy
The baseline policy is defined in `memantoclaw-blueprint/policies/openclaw-sandbox.yaml`.
* **Filesystem**: `/sandbox`, `/tmp`, `/dev/null` are Read-write. `/usr`, `/lib`, `/proc`, `/app`, `/etc` are Read-only.
* **Network**: Endpoints like `openclaw.ai:443`, `docs.openclaw.ai:443`, `registry.npmjs.org:443` are allowed.
* **Inference**: The baseline policy allows only the `local` inference route.
*Note: GitHub access is included by default, alongside Memanto and Moorcheh API access.*
## Operator Approval Flow
When the agent attempts to reach an unlisted endpoint, OpenShell intercepts the request interactively.
1. Open the TUI: `openshell term`
2. Trigger a blocked request (the agent tries to reach an unknown host).
3. The TUI displays the Host, Port, Binary, and HTTP method of the request.
4. **Approve** to add the endpoint for the current session, or **Deny** to keep it blocked.
Approved endpoints persist for the current session but are not saved to the baseline policy file.
## Customize the Sandbox Network Policy
### Static Changes
Edit `memantoclaw-blueprint/policies/openclaw-sandbox.yaml`. Each entry defines `endpoints`, `binaries`, and `rules` (methods). Then re-run:
```bash theme={null}
memantoclaw onboard
```
### Dynamic Changes
Create a YAML policy file and apply it to a running sandbox instantly:
```bash theme={null}
openshell policy set
```
### Policy Presets
MemantoClaw ships preset policy files for common integrations (e.g., `github`, `npm`, `pypi`, `discord`, `slack`). To apply a preset to a running sandbox:
```bash theme={null}
openshell policy set memantoclaw-blueprint/policies/presets/pypi.yaml
```
*For complete, unabridged technical details on this topic, refer to the official [NVIDIA NemoClaw Documentation](https://docs.nvidia.com/nemoclaw/latest/reference/network-policies.html). Portions of this guide are summarized and adapted from NVIDIA Corporation (Copyright © 2026), licensed under the Apache License, Version 2.0.*
# Operations & Troubleshooting
Source: https://docs.memanto.ai/memantoclaw/operations
Monitor sandbox activity, debug issues, and manage skills.
# Operations and Troubleshooting
Use the MemantoClaw status, logs, and TUI tools together to inspect sandbox health and trace agent behavior.
## Monitor Sandbox Activity
### Check Health
```bash theme={null}
memantoclaw status
```
This probes the gateway health, process health, and tests local Ollama/vLLM routes directly.
### View Logs
```bash theme={null}
memantoclaw logs --follow
```
### Open TUI
```bash theme={null}
openshell term
```
Use this to view active network connections and approve/deny blocked egress requests.
## Troubleshooting Common Issues
* **Installer fails on Node.js**: MemantoClaw requires Node.js 22.16+. Install it using `nvm use 22`.
* **Docker permission denied**: Ensure your user is in the `docker` group (`sudo usermod -aG docker $USER`).
* **OOM errors during sandbox creation**: Image push requires memory. Add at least 8 GB of swap file on smaller machines.
* **Port already in use**: The gateway uses port `18789`. Terminate conflicting processes (`sudo lsof -i :18789`).
* **Sandbox lost after gateway restart**: Upgrade OpenShell to >= 0.0.24 via `memantoclaw onboard`.
* **Inference unreachable**: Check if Ollama/vLLM is running. Increase timeout (`MEMANTOCLAW_LOCAL_INFERENCE_TIMEOUT=300`) for slow hardware.
Generate a debug tarball for support if needed:
```bash theme={null}
memantoclaw debug
```
## Agent Skills for AI Coding Assistants
MemantoClaw ships agent skills generated directly from documentation. These allow coding assistants (like Cursor, Claude Code) to read project-specific guidance.
Fetch the skills via sparse checkout:
```bash theme={null}
git clone --filter=blob:none --no-checkout https://github.com/moorcheh-ai/memantoclaw.git
cd memantoclaw
git sparse-checkout set --no-cone '/.agents/skills/**'
git checkout
```
Open the directory in your assistant to give it deep context on managing your sandbox.
*For complete, unabridged technical details on this topic, refer to the official [NVIDIA NemoClaw Documentation](https://docs.nvidia.com/nemoclaw/latest/monitoring/monitor-sandbox-activity.html). Portions of this guide are summarized and adapted from NVIDIA Corporation (Copyright © 2026), licensed under the Apache License, Version 2.0.*
# Overview & Ecosystem
Source: https://docs.memanto.ai/memantoclaw/overview
How MemantoClaw integrates with OpenClaw and OpenShell.
![MemantoClaw]()
# MemantoClaw
**MemantoClaw** is an open-source reference stack that simplifies running [OpenClaw](https://openclaw.ai/) always-on assistants safely with built-in long-term memory.
It combines three core technologies:
* **Autonomy ([OpenClaw](https://openclaw.ai))**: A powerful open-source agent framework.
* **Security ([NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell))**: A hardened sandbox that restricts network egress and file access.
* **Memory (Memanto)**: A long-term memory architecture powered by Moorcheh that carries context across sessions.
## 🏗️ Architecture
![High-level architecture overview]()
MemantoClaw keeps sensitive host integrations outside the sandbox while preserving a seamless agent experience inside it:
* The **host** manages credentials and provider routing to long-term memory services.
* The **sandbox** runs OpenClaw under OpenShell policy enforcement.
* The agent receives only the context it needs for each task, not raw host credentials or memory databases.
This gives you autonomous workflows with strong controls over network, filesystem, and process behavior.
## The Ecosystem and How the Stack Fits Together
Three pieces usually appear together in a MemantoClaw deployment, each with a distinct scope:
| Project | Scope |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **OpenClaw** | The assistant: runtime, tools, memory, and behavior inside the container. It does not define the sandbox or the host gateway. |
| **OpenShell** | The execution environment: sandbox lifecycle, network, filesystem, and process policy, inference routing, and the operator-facing `openshell` CLI for those primitives. |
| **MemantoClaw** | The reference stack that implements the definition above on the host: CLI and plugin, versioned blueprint, state migration helpers, and Moorcheh memory bridge. |
MemantoClaw sits above OpenShell in the operator workflow. It drives OpenShell APIs and CLI to create and configure the sandbox that runs OpenClaw. Models and endpoints sit behind OpenShell's inference routing. MemantoClaw onboarding wires provider choice into that routing, and inherently injects the Memanto memory bridge.
## MemantoClaw Path versus OpenShell Path
Both paths assume OpenShell can sandbox a workload. The difference is who owns the integration work.
* **MemantoClaw path**: You adopt the reference stack. MemantoClaw's blueprint encodes a hardened image, default policies, Moorcheh integration, and orchestration so `memantoclaw onboard` can provision a validated environment with minimal manual configuration.
* **OpenShell path**: You use OpenShell as the platform and supply your own container, install steps, policy YAML, provider setup, and any host bridges.
### What MemantoClaw Adds Beyond the OpenShell Community Sandbox
| Capability | `openshell sandbox create --from openclaw` | `memantoclaw onboard` |
| ----------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **Sandbox isolation** | Yes. OpenShell applies seccomp filters, Landlock, privilege dropping. | Yes. MemantoClaw applies these and layers a more restrictive policy. |
| **Credential handling** | You create providers manually. | Creates providers automatically and filters sensitive host env vars. |
| **Image hardening** | Standard system tools included. | Strips build toolchains (`gcc`, `make`) and network probes (`netcat`). |
| **Filesystem policy** | Bundled policy for OpenClaw. | More restrictive read-only/read-write layout. Gateway config is immutable. |
| **Inference setup** | Manual configuration. | Wizard validates credentials, configures routing automatically. |
| **Memory integration** | Manual vector DB provisioning required. | **Zero-config Memanto integration via Moorcheh**. |
## The Memanto Advantage
### Unified API Key for Memory and Inference
MemantoClaw simplifies credential management by bundling both long-term memory access and native LLM inference into a **single API key**.
Instead of juggling separate keys for your vector database (or Moorcheh memory service) and your LLM inference provider, your Moorcheh API key authenticates both. When you run `memantoclaw onboard`, you provide this one key, and MemantoClaw automatically configures the OpenShell inference gateway to proxy your LLM requests while simultaneously enabling the zero-config memory bridge.
### Secure and Real-time Memory
By leveraging Moorcheh's infrastructure, the Memanto memory layer offers zero-wait ingestion (no indexing delays) and a secure host-bridge architecture where memory stays safely on Moorcheh, and the sandbox only receives specific retrieved context.
## Deep Dive: How It Works
![Runtime routing and proxy flow]()
At a high level, MemantoClaw handles each request inside the OpenShell container by letting OpenClaw process the query, work with short-term context, and route memory and model calls through dedicated host-aware proxies. One path connects to Memanto for durable long-term memory, while the other handles inference through Moorcheh-native endpoints.
That routing pattern is what keeps credentials and external integrations on the host side, while the agent runtime remains isolated in the sandbox.
*For complete, unabridged technical details on this topic, refer to the official [NVIDIA NemoClaw Documentation](https://docs.nvidia.com/nemoclaw/latest/about/overview.html). Portions of this guide are summarized and adapted from NVIDIA Corporation (Copyright © 2026), licensed under the Apache License, Version 2.0.*
# Installation & Quickstart
Source: https://docs.memanto.ai/memantoclaw/quickstart
Launch your first sandboxed agent and configure your environment.
# Quickstart & Windows Setup
MemantoClaw provides a CLI to launch and manage a sandboxed OpenClaw instance easily.
## Prerequisites
* A valid `MOORCHEH_API_KEY`.
* Docker installed and running on your system.
## Windows Prerequisites
Running MemantoClaw on Windows requires WSL 2 (Windows Subsystem for Linux).
1. **Enable WSL 2**: Open an elevated PowerShell and run `wsl --install --no-distribution`. Reboot if prompted.
2. **Install Ubuntu**: Open an elevated PowerShell and run `wsl --install -d Ubuntu`. Let it finish first-run setup.
3. **Install Docker Desktop**: Install Docker Desktop with the WSL 2 backend. Confirm WSL integration is enabled for your Ubuntu distribution.
4. **Local Ollama (Optional)**: If using Ollama, install it inside WSL: `curl -fsSL https://ollama.com/install.sh | sh`.
## Installation
Install the CLI using the installer script (run this in your WSL/Linux terminal):
```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/moorcheh-ai/memantoclaw/refs/heads/main/install.sh | bash
```
## Launching the Sandbox
Start the interactive onboarding wizard to configure your sandbox. The wizard will prompt you to select your inference provider and securely enter your `MOORCHEH_API_KEY`.
```bash theme={null}
memantoclaw onboard
```
> **Note**: For MemantoClaw-managed environments, always use `memantoclaw onboard` when you need to create or recreate the OpenShell gateway or sandbox. Avoid using raw `openshell` commands for these lifecycle events.
## Deploy to a Remote GPU Instance
You can deploy MemantoClaw to a remote GPU instance (e.g., Brev, AWS).
The preferred path is to provision the VM, run the standard installer on that host, and then run `memantoclaw onboard`.
*For complete, unabridged technical details on this topic, refer to the official [NVIDIA NemoClaw Documentation](https://docs.nvidia.com/nemoclaw/latest/get-started/quickstart.html). Portions of this guide are summarized and adapted from NVIDIA Corporation (Copyright © 2026), licensed under the Apache License, Version 2.0.*
# Security Best Practices
Source: https://docs.memanto.ai/memantoclaw/security
Host security, credential storage, and sandbox hardening.
# Security Best Practices
MemantoClaw enforces security at four layers: Network, Filesystem, Process, and Inference.
## Layer Protections
* **Network Layer**: Deny-by-default egress. Configured via OpenShell policy. Binary-Scoped rules ensure only authorized binaries (like `gh` or `git`) can access specific endpoints.
* **Filesystem Layer**: Uses Landlock LSM + container mounts. `/sandbox` is read-only, while specific paths like `/sandbox/.openclaw-data` and `/tmp` are writable. Gateway config (`/sandbox/.openclaw`) is immutable and hash-pinned.
* **Process Layer**: Drops dangerous Linux capabilities using `capsh`. Sets `ulimit -u 512` to mitigate fork-bomb attacks. Enforces `no-new-privileges` to block privilege escalation via setuid binaries. Removes build toolchains (`gcc`, `make`) and `netcat` from the image.
* **Inference Layer**: Routes model API calls to controlled backends via `inference.local`.
## Credential Storage
Credentials (like `MOORCHEH_API_KEY`, `OPENAI_API_KEY`) are stored in plaintext JSON at:
`~/.memantoclaw/credentials.json`
They are created with mode `0600` on the host. **They are never injected into the sandbox.** The host bridge authenticates requests before forwarding them. If you suspect exposure, rotate keys and remove the stored file:
```bash theme={null}
rm -f ~/.memantoclaw/credentials.json
```
## OpenClaw Controls
MemantoClaw delegates application-layer security to OpenClaw. OpenClaw provides:
* **Prompt Injection Detection**: Neutralizes attempts like `` tag spoofing.
* **Tool Access Control**: High-risk tools (`exec`, `spawn`, `fs_write`) are gated by a multi-layer policy pipeline.
* **Environment Variable Security**: Blocks dangerous env vars (`NODE_OPTIONS`, `LD_PRELOAD`).
* **Secret Scanner**: Intercepts writes targeting memory paths that look like API keys before they reach the disk.
*For complete, unabridged technical details on this topic, refer to the official [NVIDIA NemoClaw Documentation](https://docs.nvidia.com/nemoclaw/latest/security/best-practices.html). Portions of this guide are summarized and adapted from NVIDIA Corporation (Copyright © 2026), licensed under the Apache License, Version 2.0.*
# Workspace & Backup
Source: https://docs.memanto.ai/memantoclaw/workspace
Agent identity, state management, Memanto integration, and backups.
# Workspace Files
Workspace files define your agent's personality, memory, and user context. They persist across sandbox restarts but are permanently deleted when you run `memantoclaw destroy`.
These files live at `/sandbox/.openclaw/workspace/` inside the sandbox.
## File Reference
| File | Description |
| ------------- | -------------------------------------------------------------------- |
| `SOUL.md` | Core personality, tone, and behavioral rules. |
| `USER.md` | Preferences, context, and facts the agent learns about you. |
| `IDENTITY.md` | Agent name, creature type, emoji, and self-presentation. |
| `AGENTS.md` | Multi-agent coordination, memory conventions, and safety guidelines. |
## The Memanto Advantage
In standard open-source setups, OpenClaw relies on a local SQLite database for recent chat history (using BM25 keyword matching) and manual markdown files like `MEMORY.md` for facts. This approach is lossy, degrades over time, and if the sandbox is destroyed, the agent suffers total amnesia of its conversational context.
With **MemantoClaw**, long-term semantic memory is securely routed to Moorcheh's information-theoretic search engine via the host bridge. Even if you destroy the sandbox, the retrieved context and learned knowledge safely persist remotely, ready to be injected into your next agent immediately.
## Back Up and Restore Workspace Files
Use the OpenShell CLI to manually copy local Markdown files out of the sandbox before destroying it:
```bash theme={null}
SANDBOX=my-assistant
BACKUP_DIR=~/.memantoclaw/backups/$(date +%Y%m%d-%H%M%S)
mkdir -p "$BACKUP_DIR"
openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/SOUL.md "$BACKUP_DIR/"
openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/USER.md "$BACKUP_DIR/"
```
To restore:
```bash theme={null}
openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/SOUL.md" /sandbox/.openclaw/workspace/
```
### Using the Backup Script
MemantoClaw includes a convenience script:
```bash theme={null}
./scripts/backup-workspace.sh backup my-assistant
./scripts/backup-workspace.sh restore my-assistant
```
*For complete, unabridged technical details on this topic, refer to the official [NVIDIA NemoClaw Documentation](https://docs.nvidia.com/nemoclaw/latest/workspace/workspace-files.html). Portions of this guide are summarized and adapted from NVIDIA Corporation (Copyright © 2026), licensed under the Apache License, Version 2.0.*
# Backend Switching
Source: https://docs.memanto.ai/on-prem/backend-switching
Move between Moorcheh Cloud and Moorcheh On-Prem without losing either side's agents or sessions.
# Backend Switching
Memanto keeps cloud and on-prem state strictly separated so you can flip between them at will. The data on each side stays intact — switching backends never deletes or moves your agents or memories.
## The Two Backends
| Backend | Selected with | Data lives in | Auth |
| --------------------- | -------------------------------- | --------------------- | ---------------------------------------------------------------- |
| **Cloud** *(default)* | `memanto config backend cloud` | `~/.memanto/` | `MOORCHEH_API_KEY` in `~/.memanto/.env` |
| **On-Prem** | `memanto config backend on-prem` | `~/.memanto/on-prem/` | None — talks to local Moorcheh server at `http://localhost:8080` |
`memanto status` always shows the **active** backend and its server health.
## Inspect the Current Backend
```bash theme={null}
memanto config backend
```
Sample output (cloud):
```
Active backend: cloud
```
Sample output (on-prem):
```
Active backend: on-prem
Server: http://localhost:8080
Embedding: ollama
```
## Switch to On-Prem
```bash theme={null}
memanto config backend on-prem
```
What happens:
1. If on-prem has **never been configured** on this machine, the on-prem onboarding wizard runs (Docker check, provider prompts, `moorcheh up`, model pulls). See [On-Prem Quickstart](./quickstart).
2. If on-prem has been configured before, the wizard skips the prompts and **reuses** your previous `embedding_provider`, `embedding_model`, and (where possible) provider API keys from `~/.moorcheh/config.json`.
3. The active session is cleared (sessions are backend-specific — you don't want to send a cloud session token to the on-prem server).
4. `backend: on-prem` is persisted in `~/.memanto/config.yaml`.
5. The in-process client singleton is reset so the next call immediately uses the new backend.
Confirmation:
```
Switched backend to on-prem.
Active session was cleared.
```
## Switch Back to Cloud
```bash theme={null}
memanto config backend cloud
```
If your cloud API key is already saved in `~/.memanto/.env`, the switch is instant. Otherwise the cloud setup prompts you for `MOORCHEH_API_KEY` and verifies it against the Moorcheh API.
## What's Preserved Across Switches
| State | Preserved? | Where |
| -------------------------------------- | ---------- | ------------------------------------------------------------------------ |
| **Cloud agents and memories** | Yes | Moorcheh Cloud (server-side) + `~/.memanto/agents`. |
| **On-prem agents and memories** | Yes | Local Moorcheh container + `~/.memanto/on-prem/agents`. |
| **Cloud API key** | Yes | `~/.memanto/.env`. |
| **On-prem provider config** | Yes | `~/.memanto/on-prem/state.json` + `~/.moorcheh/config.json`. |
| **Active session** | **No** | Cleared on every switch (intentional — tokens don't cross backends). |
| **Integrations (`memanto connect …`)** | Yes | `~/.memanto/connections.json` — these are IDE wiring, not backend state. |
Switching backends never mutates or deletes data on either side. You can flip back and forth as often as you like.
## Troubleshooting Switches
### "On-Prem Server: ● offline" after switching to on-prem
The wizard sets up the stack but doesn't keep it running across machine reboots. Bring Moorcheh back up:
```bash theme={null}
moorcheh up
```
If `moorcheh` isn't on `PATH`, re-open your terminal (so pip's scripts dir is loaded) or run `python -m moorcheh up`.
### "Invalid Moorcheh API key" after switching to cloud
Your `~/.memanto/.env` is missing or stale. Re-enter the key:
```bash theme={null}
memanto config backend cloud # triggers the cloud setup flow again
```
Or set it directly:
```bash theme={null}
echo "MOORCHEH_API_KEY=mk_…" > ~/.memanto/.env
```
### Agents missing after switching
Cloud and on-prem maintain **separate** agent registries. An agent created on cloud is not visible from on-prem (and vice versa). Re-create the agent under the target backend, or import a memory export.
## Related
* [On-Prem Quickstart](./quickstart)
* [Configuration](./configuration)
* [Self-Hosting Memanto Server](./server-deployment)
# Configuration
Source: https://docs.memanto.ai/on-prem/configuration
Environment variables, state files, embedding/LLM provider options, and per-backend isolation for Memanto on-prem.
# On-Prem Configuration
The on-prem wizard wires sensible defaults, but every value is editable. This page is the reference for **where** each setting lives, **what** controls it, and **how** to change it after install.
## Configuration Surfaces
On-prem reads from three places. They are evaluated in this order — later sources override earlier ones:
1. **Environment variables** (or a project `.env`) — highest precedence.
2. **`~/.memanto/on-prem/state.json`** — set by the on-prem onboarding wizard.
3. **Built-in defaults** in Memanto's `Settings` model.
The shared `~/.memanto/config.yaml` is owned by the cloud backend; the on-prem wizard does **not** write into it. The only `config.yaml` key on-prem touches is `backend: on-prem` (so subsequent CLI runs know which backend to dispatch to).
## Environment Variables
These are the on-prem-relevant variables in `Settings`. Defaults shown.
| Variable | Default | Purpose |
| ------------------------------------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MEMANTO_BACKEND` | `cloud` | Set to `on-prem` to route all Moorcheh calls to the local server. The wizard sets this for you; you can also set it inline (`MEMANTO_BACKEND=on-prem memanto status`). |
| `MOORCHEH_ONPREM_URL` | `http://localhost:8080` | Base URL of the Moorcheh on-prem server. Override if you've remapped the port or are running Memanto in a different container. |
| `MOORCHEH_ONPREM_EMBEDDING_PROVIDER` | *(empty)* | Surfaced in `memanto status` so you can see at a glance what provider is in use. Auto-populated from `state.json`. |
| `MOORCHEH_ONPREM_TIMEOUT` | `300` | HTTP read timeout in seconds for the on-prem Moorcheh client. Default is high because first-call LLM cold-starts on Ollama can take 1–2 minutes (model load). |
| `MOORCHEH_API_KEY` | *(empty)* | **Not required on-prem.** The on-prem stack does not consult this. |
| `HOST` | `0.0.0.0` | Bind host for Memanto's own REST server (`memanto serve`). |
| `PORT` | `8000` | Bind port for Memanto's own REST server. |
| `ANSWER_MODEL` | `anthropic.claude-sonnet-4-6` | **Cloud default.** On-prem, the active LLM is sourced from `state.json` (`llm_model`); this env var is ignored unless `state.json` is empty. |
| `ANSWER_TEMPERATURE` | `0.7` | LLM temperature for `answer.generate`. Honored on both backends. |
| `ANSWER_LIMIT` | `15` | Number of context memories passed to the LLM for `answer`. |
| `ANSWER_THRESHOLD` | `0.01` | Confidence threshold for memory relevance during `answer`. |
| `RECALL_LIMIT` | `10` | Default Top-N results returned by `recall`. |
| `SUMMARY_MODEL` | `anthropic.claude-sonnet-4-6` | Same backend-awareness rule as `ANSWER_MODEL`. |
| `ALLOWED_ORIGINS` | `*` | CORS origins for Memanto's REST API. Restrict in production. |
| `LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR`. |
### Setting Env Vars
For a single command:
```bash theme={null}
MEMANTO_BACKEND=on-prem memanto status
```
In a project `.env` (loaded automatically):
```bash theme={null}
MEMANTO_BACKEND=on-prem
MOORCHEH_ONPREM_URL=http://moorcheh.internal:8080
MOORCHEH_ONPREM_TIMEOUT=600
LOG_LEVEL=DEBUG
```
Globally for your shell (Linux/macOS):
```bash theme={null}
export MEMANTO_BACKEND=on-prem
```
On Windows PowerShell:
```powershell theme={null}
$env:MEMANTO_BACKEND = "on-prem"
```
## On-Prem State File
`~/.memanto/on-prem/state.json` is the source of truth for on-prem configuration. It is written by the wizard and read by both the CLI and the embedded server.
Example contents:
```json theme={null}
{
"installed_at": "2026-06-09T14:32:11Z",
"embedding_provider": "ollama",
"embedding_model": "nomic-embed-text",
"llm_provider": "ollama",
"llm_model": "qwen2.5",
"url": "http://localhost:8080"
}
```
| Key | Used for |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url` | Exported as `MOORCHEH_ONPREM_URL` at process startup. |
| `embedding_provider`, `embedding_model` | Re-used when re-onboarding on-prem (lets you switch cloud↔on-prem without re-picking a provider). |
| `llm_provider`, `llm_model` | Sent as `ai_model` to the on-prem server on every `answer.generate` call. If empty/missing, the on-prem server falls back to whatever LLM is configured in `~/.moorcheh/config.json`. |
| `installed_at` | Metadata, useful for support diagnostics. |
You can edit this file by hand. After saving, restart `memanto serve` (or run any CLI command) to reload.
## Moorcheh Server Config
`~/.moorcheh/config.json` is owned by the `moorcheh-client` package. The Memanto wizard writes the full **embedding + LLM** block there before calling `moorcheh up`, so the on-prem server has both ready on first boot. Schema:
```json theme={null}
{
"embedding": {
"provider": "ollama",
"model": "nomic-embed-text",
"api_key": null,
"base_url": "http://ollama:11434"
},
"llm": {
"provider": "ollama",
"model": "qwen2.5",
"api_key": null,
"base_url": "http://ollama:11434"
}
}
```
To switch the on-prem server to a different provider after install:
1. Stop the stack: `moorcheh down`.
2. Edit `~/.moorcheh/config.json` (or use `moorcheh configure` interactively).
3. Restart: `moorcheh up`.
4. Update `~/.memanto/on-prem/state.json` to match (`embedding_provider`, `llm_model`, etc.) — Memanto reads its model id from there.
## Provider Reference
### Ollama (Local, Recommended for Air-Gap)
* **Embedding model:** `nomic-embed-text` (default; \~270 MB).
* **LLM model:** `qwen2.5` (default; \~4.7 GB) — change with any `ollama pull`-able model.
* **API key:** none.
* **Where it runs:** sibling Docker container started by `moorcheh up`.
### OpenAI
* **Embedding model:** `text-embedding-3-small` (default; cheaper) or `text-embedding-3-large`.
* **LLM model:** `gpt-4o-mini` (default), `gpt-4o`, etc.
* **API key:** required; stored in `~/.moorcheh/config.json` under `embedding.api_key` / `llm.api_key`.
### Cohere
* **Embedding model:** `embed-english-v3.0` (default) or `embed-multilingual-v3.0`.
* **LLM model:** `command-r-plus-08-2024` (default).
* **API key:** required.
## Answer & Recall Tuning
These knobs work identically on cloud and on-prem.
| Setting | Env var | Default | What it does |
| ------------------- | -------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------- |
| Answer model | `ANSWER_MODEL` *(cloud)* / `state.json: llm_model` *(on-prem)* | — | Which LLM `answer` calls. |
| Answer temperature | `ANSWER_TEMPERATURE` | `0.7` | Higher = more creative, lower = more deterministic. |
| Answer context size | `ANSWER_LIMIT` | `15` | How many memories to pass as context. Lower for faster answers, higher for better grounding. |
| Answer threshold | `ANSWER_THRESHOLD` | `0.01` | Memories below this similarity are dropped. |
| Recall top-N | `RECALL_LIMIT` | `10` | Default page size for `recall`. Override per-call with `--limit`. |
## Timeouts
Ollama cold-starts can be slow on first call after `moorcheh up`. Memanto sets the on-prem client's read timeout to **300 seconds** by default so an initial `answer.generate` doesn't fail with a `ReadTimeout`. Override:
```bash theme={null}
export MOORCHEH_ONPREM_TIMEOUT=600
```
After the first call the model stays resident in Ollama's RAM and subsequent calls return in under seconds.
## Disk Locations Recap
| Path | Owner | Editable? |
| ------------------------------- | ----------------- | ----------------------------------------------------- |
| `~/.memanto/on-prem/state.json` | Memanto CLI | Yes — hand-edit then restart CLI/server. |
| `~/.memanto/.env` | Memanto CLI | Yes — but on-prem does not need a `MOORCHEH_API_KEY`. |
| `~/.moorcheh/config.json` | `moorcheh-client` | Yes via `moorcheh configure` or by hand. |
| `~/.moorcheh/uploads/` | `moorcheh-client` | Append-only; staging for `memanto upload` files. |
## Next Steps
* [Backend Switching](./backend-switching) — toggle between cloud and on-prem without losing state.
* [Self-Hosting Memanto Server](./server-deployment) — run `memanto serve` under Docker/Compose/systemd.
* [Kubernetes Deployment](./kubernetes) — manifests for a clustered on-prem deployment.
* [Security & Operations](./security) — production hardening checklist.
# Kubernetes Deployment
Source: https://docs.memanto.ai/on-prem/kubernetes
Manifests for running Memanto on Kubernetes against the cloud or on-prem Moorcheh backend.
# Kubernetes Deployment
Memanto is a single-binary FastAPI app — there are no leader-election, sticky-session, or shared-volume concerns. The deployment manifests below are intentionally minimal; adapt the resources, security context, and ingress to fit your cluster.
The manifests use the cloud backend by default. The "On-Prem Backend" section at the bottom shows how to add the Moorcheh server (and optionally Ollama) as sibling pods.
## Deployment
```yaml theme={null}
apiVersion: apps/v1
kind: Deployment
metadata:
name: memanto
labels:
app: memanto
spec:
replicas: 3
selector:
matchLabels:
app: memanto
template:
metadata:
labels:
app: memanto
spec:
containers:
- name: memanto
image: memanto:latest
ports:
- containerPort: 8000
env:
- name: MOORCHEH_API_KEY
valueFrom:
secretKeyRef:
name: memanto-secrets
key: moorcheh-api-key
- name: LOG_LEVEL
value: "INFO"
- name: ALLOWED_ORIGINS
value: "https://app.yourdomain.com"
livenessProbe:
httpGet:
path: /ready # lightweight, no Moorcheh dependency
port: 8000
initialDelaySeconds: 10
periodSeconds: 10
readinessProbe:
httpGet:
path: /health # gates traffic on Moorcheh connectivity
port: 8000
initialDelaySeconds: 5
periodSeconds: 5
resources:
requests:
memory: "512Mi"
cpu: "250m"
limits:
memory: "1Gi"
cpu: "500m"
securityContext:
runAsNonRoot: true
runAsUser: 1001
readOnlyRootFilesystem: true
allowPrivilegeEscalation: false
capabilities:
drop: ["ALL"]
```
**Probe note**: `/ready` is the right liveness probe because it always returns 200 once the process is up — using `/health` would restart pods every time Moorcheh has a hiccup. `/health` is the right *readiness* probe because it gates traffic on actual Moorcheh connectivity.
## Service
```yaml theme={null}
apiVersion: v1
kind: Service
metadata:
name: memanto
spec:
selector:
app: memanto
ports:
- protocol: TCP
port: 80
targetPort: 8000
type: ClusterIP
```
## Secret
```yaml theme={null}
apiVersion: v1
kind: Secret
metadata:
name: memanto-secrets
type: Opaque
data:
moorcheh-api-key:
```
Create it from a literal:
```bash theme={null}
kubectl create secret generic memanto-secrets \
--from-literal=moorcheh-api-key="mk_your_api_key"
```
Or via external-secrets, Vault, or your cloud's secret manager. Don't bake API keys into images.
## Ingress (TLS Termination)
```yaml theme={null}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: memanto
annotations:
cert-manager.io/cluster-issuer: letsencrypt-prod
nginx.ingress.kubernetes.io/proxy-body-size: "25m" # for file uploads
spec:
ingressClassName: nginx
tls:
- hosts:
- memanto.yourdomain.com
secretName: memanto-tls
rules:
- host: memanto.yourdomain.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: memanto
port:
number: 80
```
## Horizontal Pod Autoscaler
Memanto is I/O-bound, so scale on CPU:
```yaml theme={null}
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
name: memanto
spec:
scaleTargetRef:
apiVersion: apps/v1
kind: Deployment
name: memanto
minReplicas: 2
maxReplicas: 10
metrics:
- type: Resource
resource:
name: cpu
target:
type: Utilization
averageUtilization: 70
```
## On-Prem Backend on Kubernetes
To run Moorcheh inside the same cluster as Memanto, add a Moorcheh deployment and point `MOORCHEH_ONPREM_URL` at the in-cluster Service.
```yaml theme={null}
apiVersion: apps/v1
kind: Deployment
metadata:
name: moorcheh
spec:
replicas: 1 # Moorcheh on-prem is a single-instance service today
selector:
matchLabels:
app: moorcheh
template:
metadata:
labels:
app: moorcheh
spec:
containers:
- name: moorcheh
image: moorcheh/moorcheh:latest
ports:
- containerPort: 8080
volumeMounts:
- name: data
mountPath: /data
- name: config
mountPath: /root/.moorcheh
readinessProbe:
httpGet:
path: /health
port: 8080
initialDelaySeconds: 10
periodSeconds: 5
resources:
requests:
memory: "1Gi"
cpu: "500m"
limits:
memory: "4Gi"
cpu: "2"
volumes:
- name: data
persistentVolumeClaim:
claimName: moorcheh-data
- name: config
configMap:
name: moorcheh-config
---
apiVersion: v1
kind: Service
metadata:
name: moorcheh
spec:
selector:
app: moorcheh
ports:
- protocol: TCP
port: 8080
targetPort: 8080
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: moorcheh-data
spec:
accessModes: ["ReadWriteOnce"]
resources:
requests:
storage: 20Gi
```
And the `ConfigMap` for the embedding / LLM block (replace with your provider of choice):
```yaml theme={null}
apiVersion: v1
kind: ConfigMap
metadata:
name: moorcheh-config
data:
config.json: |
{
"embedding": {
"provider": "openai",
"model": "text-embedding-3-small",
"api_key": ""
},
"llm": {
"provider": "openai",
"model": "gpt-4o-mini",
"api_key": ""
}
}
```
For real deployments, mount provider API keys via `Secret` + an init container or external-secrets operator instead of embedding them in the ConfigMap.
Then update the Memanto Deployment env block to point at the in-cluster Moorcheh:
```yaml theme={null}
env:
- name: MEMANTO_BACKEND
value: "on-prem"
- name: MOORCHEH_ONPREM_URL
value: "http://moorcheh:8080"
- name: MOORCHEH_ONPREM_TIMEOUT
value: "300"
```
Remove the `MOORCHEH_API_KEY` env var when on-prem — it isn't consulted in on-prem mode.
### Ollama on Kubernetes (Optional)
If you want fully local inference, add an Ollama Deployment with persistent storage for model weights:
```yaml theme={null}
apiVersion: apps/v1
kind: Deployment
metadata:
name: ollama
spec:
replicas: 1
selector:
matchLabels:
app: ollama
template:
metadata:
labels:
app: ollama
spec:
containers:
- name: ollama
image: ollama/ollama:latest
ports:
- containerPort: 11434
volumeMounts:
- name: models
mountPath: /root/.ollama
resources:
requests:
memory: "8Gi"
cpu: "2"
limits:
memory: "16Gi"
cpu: "4"
# nvidia.com/gpu: 1 # if you have GPU nodes + nvidia-device-plugin
volumes:
- name: models
persistentVolumeClaim:
claimName: ollama-models
---
apiVersion: v1
kind: Service
metadata:
name: ollama
spec:
selector:
app: ollama
ports:
- port: 11434
targetPort: 11434
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: ollama-models
spec:
accessModes: ["ReadWriteOnce"]
resources:
requests:
storage: 50Gi
```
Update the Moorcheh ConfigMap to use `"base_url": "http://ollama:11434"` for both embedding and LLM blocks.
After deploy, pull your models once:
```bash theme={null}
kubectl exec -it deployment/ollama -- ollama pull nomic-embed-text
kubectl exec -it deployment/ollama -- ollama pull qwen2.5
```
## NetworkPolicy (Recommended)
Restrict who can reach Memanto and Moorcheh:
```yaml theme={null}
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: memanto-allow-ingress
spec:
podSelector:
matchLabels:
app: memanto
policyTypes: ["Ingress"]
ingress:
- from:
- namespaceSelector:
matchLabels:
name: ingress-nginx
ports:
- protocol: TCP
port: 8000
---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: moorcheh-only-from-memanto
spec:
podSelector:
matchLabels:
app: moorcheh
policyTypes: ["Ingress"]
ingress:
- from:
- podSelector:
matchLabels:
app: memanto
ports:
- protocol: TCP
port: 8080
```
## Applying
```bash theme={null}
kubectl apply -f deployment.yaml
kubectl apply -f service.yaml
kubectl apply -f secret.yaml
kubectl apply -f ingress.yaml
kubectl apply -f hpa.yaml
# Optional on-prem additions:
kubectl apply -f moorcheh.yaml
kubectl apply -f ollama.yaml
kubectl apply -f networkpolicy.yaml
kubectl get pods -l app=memanto -w
kubectl logs -l app=memanto -f
```
## Cloud Platform Quick-Reference
The Memanto image is generic — it runs anywhere that can host a container.
| Platform | Notes |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| **AWS ECS / Fargate** | Pull image from ECR. Inject `MOORCHEH_API_KEY` via AWS Secrets Manager. ALB → port 8000. |
| **Google Cloud Run** | Inject API key via Secret Manager. Set `--port 8000`. Concurrency 80–100 per instance is a reasonable starting point. |
| **Azure Container Instances / Apps** | Inject API key via Azure Key Vault references. |
| **DigitalOcean App Platform** | Set the env var `MOORCHEH_API_KEY` in the App definition. |
| **Fly.io** | `flyctl secrets set MOORCHEH_API_KEY=…`. Set `[http_service] internal_port = 8000`. |
For on-prem on managed platforms, the Moorcheh container needs persistent storage and an internal endpoint your Memanto service can reach — most platforms make this straightforward via "sidecar" or "internal service" features.
## Next Steps
* [Security & Operations](./security)
* [Troubleshooting](./troubleshooting)
# On-Prem Overview
Source: https://docs.memanto.ai/on-prem/overview
Run Memanto entirely on your own infrastructure with a local Moorcheh server — no API key, no data leaving your environment.
![on-prem]()
# Memanto On-Prem
Memanto supports two backends:
* **Cloud** *(default)* — Memanto talks to Moorcheh Cloud over the network with a `MOORCHEH_API_KEY`.
* **On-Prem** — Memanto talks to a local Moorcheh server running in Docker on your own machine or private network. No Moorcheh API key required.
Both backends expose the same CLI, REST API, and SDK behavior. Switching between them is a single command (`memanto config backend on-prem`). Service code never branches on backend — everything in this documentation works identically once you are configured.
## When to Choose On-Prem
| Reason | What on-prem gives you |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Data residency** | Memories and embeddings stay on your hardware. Moorcheh runs in a local Docker container. |
| **Air-gapped environments** | With the `ollama` provider, no outbound calls to OpenAI, Cohere, or Moorcheh are required after initial model pulls. |
| **Cost control** | Zero per-request cost for embeddings, LLM answers, and search when using Ollama. |
| **Compliance** | Useful for HIPAA, SOC 2, and similar regimes that restrict third-party data processors. |
| **Offline development** | Run Memanto locally without internet connectivity. |
Pick **Cloud** instead if you want zero-install, sub-90ms hosted retrieval, and don't need to keep data on-prem. See [Moorcheh Setup & Integration](/guides/moorcheh-integration) for the cloud path.
## Architecture
![on-prem-architecture-diagram]()
Three components run side-by-side:
1. **Memanto CLI/Server** — the same `memanto` binary you'd use against the cloud. With `MEMANTO_BACKEND=on-prem`, it routes Moorcheh calls to the local server at `http://localhost:8080` instead of the cloud API.
2. **Moorcheh on-prem server** — a containerized build of Moorcheh started by the `moorcheh up` command (shipped with the `moorcheh-client` Python package). Exposes the same `namespaces / documents / similarity_search / answer / files / vectors` resource shape as the cloud SDK.
3. **Embedding + LLM providers** — Ollama (default, runs in a sibling container, zero API keys), or your own OpenAI / Cohere account.
Memanto's service layer never branches on backend, so every feature in the [Guides](/guides/memory-operations), [CLI](/cli/overview), and [API Reference](/api-reference/authentication) sections works the same way on-prem.
## What's Included
Everything available in cloud mode is available on-prem:
* **All 13 typed memory types** — `instruction`, `fact`, `decision`, `goal`, `commitment`, `preference`, `relationship`, `context`, `event`, `learning`, `observation`, `artifact`, `error`. See [Memory Types](/reference/memory-types).
* **`remember` / `recall` / `answer`** — the same three primitives. `answer` uses your locally configured LLM provider instead of the cloud's hosted model.
* **Temporal queries** — `--as-of`, `--changed-since`, `--recent`. See [Temporal Memory](/guides/temporal-memory).
* **Batch ingestion** — up to 100 memories per request.
* **File upload** — `.pdf`, `.docx`, `.xlsx`, `.json`, `.txt`, `.csv`, `.md`. Files are copied into `~/.moorcheh/uploads` and made searchable by the on-prem indexer.
* **Sessions** — same 6-hour JWT session model.
* **Agent management** — create, list, activate, deactivate, bootstrap.
* **Daily summaries, conflict detection, scheduled runs** — `memanto daily-summary`, `memanto conflicts`, `memanto schedule enable`.
* **Web UI** — `memanto ui` works against on-prem the same as cloud.
* **Integrations** — Claude Code, Cursor, Codex, Windsurf, Gemini CLI, Cline, Continue, OpenCode, Goose, Roo, GitHub Copilot, Augment (via `memanto connect`).
* **REST API** — every endpoint under `/api/v2/agents/...` works identically.
The only thing that differs between backends is the underlying retrieval engine — on-prem stores data in Moorcheh's local container; cloud stores it in Moorcheh's hosted service.
## Isolation Guarantees
When you switch to on-prem, Memanto isolates your configuration so cloud and on-prem state never cross-contaminate:
* **Per-backend data directory**: cloud uses `~/.memanto/`, on-prem uses `~/.memanto/on-prem/`. Agents, sessions, and registry entries are separate.
* **Per-backend connection state**: the on-prem server URL, embedding provider, and LLM model live in `~/.memanto/on-prem/state.json`. The cloud's `~/.memanto/config.yaml` is never touched by on-prem onboarding.
* **Per-backend session tokens**: switching backends clears the active session so you don't accidentally send a cloud token to the on-prem server (or vice versa).
This means you can keep both backends configured at once and switch between them with `memanto config backend cloud` / `memanto config backend on-prem`. Your agents on each side remain intact.
## Next Steps
* ** Check requirements** → [Requirements](./requirements)
* ** Install in 5–10 minutes** → [On-Prem Quickstart](./quickstart)
* ** Tune embedding + LLM providers** → [Configuration](./configuration)
* ** Move between cloud and on-prem** → [Backend Switching](./backend-switching)
* ** Run Memanto's REST server in production** → [Self-Hosting Memanto Server](./server-deployment)
* ** Ship to Kubernetes** → [Kubernetes Deployment](./kubernetes)
# On-Prem Quickstart
Source: https://docs.memanto.ai/on-prem/quickstart
Bring up Memanto on-prem in 5–10 minutes with the interactive CLI wizard.
# On-Prem Quickstart
This guide walks through the full on-prem install end-to-end. It uses the built-in `memanto` first-run wizard, which provisions the Moorcheh on-prem server, configures embedding + LLM providers, and writes all state for you.
**Time to complete:** 5–10 minutes on first run (most of which is the initial Ollama model pull).
**Result:** A fully working on-prem Memanto stack with `remember`, `recall`, and `answer` operating against a local Moorcheh container.
Before you start, confirm you have Docker running and Python 3.10+ on `PATH`. See [Requirements](./requirements) for details.
## 1. Install the CLI
```bash theme={null}
pip install memanto
```
Or with `uv`:
```bash theme={null}
pip install uv
uv tool install memanto
```
Verify:
```bash theme={null}
memanto --version
```
## 2. Run the Wizard
Launch the interactive setup:
```bash theme={null}
memanto
```
The first time you run the CLI with no subcommand, it prints the welcome banner and asks you to choose a backend:
```
Choose your backend
1 Moorcheh Cloud (instant, needs API key, all features)
2 Moorcheh On-Prem (~5-10 min install, Docker required, no API key)
Enter 1 or 2 [1]:
```
**Type `2` and press Enter.** The wizard then:
1. Verifies Docker is installed and the daemon is running.
2. Installs `moorcheh-client>=0.1.3` if it isn't already.
3. Prompts you for an embedding provider.
4. Prompts you for an LLM provider (for `answer.generate`).
5. Writes both into `~/.moorcheh/config.json`.
6. Runs `moorcheh up --embedding-provider … --embedding-model …` to start the on-prem stack.
7. Waits for `http://localhost:8080/health` to return 200.
8. If you chose Ollama, pulls the embedding and LLM models inside the Ollama container via `docker exec ollama pull …`.
9. Saves the final state to `~/.memanto/on-prem/state.json`.
## 3. Pick an Embedding Provider
The wizard asks:
```
Embedding provider
1 Ollama (local, zero API keys) - we'll pull the embedding model for you
2 Bring your own (OpenAI or Cohere) - cloud-hosted embeddings, requires an API key
Enter 1 or 2 [1]:
```
| Choice | Default model | API key | Where embeddings run |
| ---------- | ------------------------ | ------- | ----------------------------------------- |
| **Ollama** | `nomic-embed-text` | None | Local container started by `moorcheh up`. |
| **OpenAI** | `text-embedding-3-small` | Yes | OpenAI API. |
| **Cohere** | `embed-english-v3.0` | Yes | Cohere API. |
If you pick OpenAI or Cohere, the wizard prompts (with hidden input) for your provider API key and validates it is non-empty.
## 4. Pick an LLM Provider
Next, the wizard asks for the LLM used by `memanto answer`:
```
Answer LLM provider
1 Ollama (local, zero API keys) - model: qwen2.5
2 OpenAI - model: gpt-4o-mini, requires an API key
3 Cohere - model: command-r-plus-08-2024, requires an API key
Enter 1, 2, or 3 [1]:
```
The default mirrors your embedding choice — if you picked OpenAI for embeddings, OpenAI is suggested for the LLM, and the wizard reuses your API key so you don't have to enter it twice.
You can mix providers freely (e.g., **Ollama embeddings + OpenAI LLM**) — Memanto stores both choices independently.
To change the model later, edit `answer.model` in `~/.memanto/on-prem/config.yaml`.
## 5. Wait for the Server
After provider selection, the wizard prints:
```
Starting Moorcheh server (`moorcheh up`)...
✓ Docker is running
✓ moorcheh-client installed
✓ LLM config saved to ~/.moorcheh/config.json
Waiting for http://localhost:8080/...
✓ Moorcheh server online
```
If you picked Ollama, you'll also see:
```
Pulling nomic-embed-text inside Ollama container abc123def456...
✓ Embedding model ready in container
Pulling qwen2.5 inside Ollama container abc123def456...
✓ Embedding model ready in container
```
The initial Ollama pull downloads \~5 GB and can take several minutes on a slow connection. Subsequent runs reuse the cached models.
When the wizard finishes you'll see:
```
Setup complete!
Backend: On-Prem
Config: /Users//.memanto
Server: http://localhost:8080
Embedding: ollama
```
## 6. Verify the Install
Run the status dashboard:
```bash theme={null}
memanto status
```
You should see something like:
```
Configuration
Config Dir /Users//.memanto
Backend on-prem
On-Prem URL http://localhost:8080
Embedding ollama
On-Prem Server ● online
```
If the **On-Prem Server** line says `● offline`, see [Troubleshooting](./troubleshooting).
## 7. Try It End-to-End
The on-prem CLI is identical to the cloud CLI — no `--on-prem` flags anywhere. Create an agent, store a memory, then ask Memanto a question:
```bash theme={null}
# Create an agent (auto-activates a 6-hour session)
memanto agent create on-prem-demo
# Store a memory — instantly searchable, no indexing wait
memanto remember "The user prefers dark mode for the dashboard" --type preference
# Recall it semantically
memanto recall "What theme does the user want?"
# Generate a grounded answer (uses your chosen LLM provider)
memanto answer "Based on memory, what theme should I set?"
```
Expected behavior:
* `remember` returns a `memory_id` immediately — no indexing delay.
* `recall` returns the stored memory by semantic similarity, even with no keyword overlap.
* `answer` calls your chosen LLM (Ollama / OpenAI / Cohere) with the recalled memories as context and prints the grounded answer.
Open the web UI to browse everything in a browser:
```bash theme={null}
memanto ui
```
This starts the embedded Memanto server (on port `8000` by default) and opens the dashboard in your default browser.
## 8. Start the REST API (Optional)
If you want to drive Memanto from your own application code or external tools, start the local REST server:
```bash theme={null}
memanto serve
```
The server listens on `http://localhost:8000`. It auto-detects your on-prem backend choice and routes all Moorcheh calls to `http://localhost:8080`. Interactive API docs are at `http://localhost:8000/docs`.
All endpoints documented in the [API Reference](/api-reference/authentication) work identically on-prem — including `/api/v2/agents/{id}/remember`, `/recall`, `/answer`, `/upload-file`, and `/batch-remember`.
## What Just Got Installed
| Component | Where | Started by |
| ------------------------------------ | ------------------------------- | ------------------------------------ |
| Memanto CLI + server | `pip` site-packages | `memanto`, `memanto serve` |
| Moorcheh on-prem container | Docker | `moorcheh up` (called by the wizard) |
| Ollama container *(if chosen)* | Docker, sibling to Moorcheh | `moorcheh up` |
| Embedding + LLM models *(if Ollama)* | Inside Ollama container | `docker exec ollama pull …` |
| On-prem state | `~/.memanto/on-prem/state.json` | Wizard |
| Moorcheh provider config | `~/.moorcheh/config.json` | Wizard (via `moorcheh-client`) |
Nothing else is installed system-wide. To remove the on-prem stack later, run `moorcheh down` (or `docker compose down` against the moorcheh project), uninstall `moorcheh-client`, and delete `~/.memanto/on-prem/`.
## Next Steps
* [Configuration](./configuration) — tune providers, model overrides, timeouts, ports.
* [Backend Switching](./backend-switching) — swap between on-prem and cloud without losing either side's state.
* [Self-Hosting Memanto Server](./server-deployment) — run the Memanto REST API as a long-lived service.
* [Troubleshooting](./troubleshooting) — common errors and what to check.
# Requirements
Source: https://docs.memanto.ai/on-prem/requirements
Hardware, OS, and software prerequisites for running Memanto on-prem.
# On-Prem Requirements
The on-prem stack runs Memanto plus the Moorcheh server (and optionally Ollama) in Docker on a single host. Everything is automated by the `memanto` CLI — you only need to make sure the prerequisites are in place before you start.
## Operating Systems
The on-prem stack is supported on:
* **Windows 10/11** with Docker Desktop (WSL2 backend)
* **macOS 12+** (Apple Silicon and Intel) with Docker Desktop
* **Linux** (Ubuntu 20.04+, Debian 11+, RHEL 8+, Amazon Linux 2) with Docker Engine 20.10+
## Hardware
| Component | Minimum | Recommended | Notes |
| --------- | ------------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **CPU** | 4 cores | 8+ cores | More cores noticeably speed up Ollama inference. |
| **RAM** | 8 GB | 16 GB+ | Ollama with `qwen2.5` needs \~6 GB resident; embeddings add \~1 GB. With OpenAI/Cohere as providers, 4–6 GB total is enough. |
| **Disk** | 10 GB free | 30 GB+ free | Ollama model images are 1–7 GB each. Moorcheh storage grows with your memory volume. |
| **GPU** | Not required | NVIDIA GPU with 8 GB+ VRAM | Optional — speeds up Ollama. CPU-only inference works on any modern machine. |
For air-gapped deployments using OpenAI or Cohere as the embedding/LLM provider, the hardware footprint is much smaller (no Ollama container needed).
## Software
### Required
* **Docker Engine 20.10+** or **Docker Desktop 4.0+** with the daemon running.
* The Memanto onboarding wizard fails fast with a clear error if `docker info` does not succeed.
* Verify with:
```bash theme={null}
docker --version
docker info
```
* **Python 3.10+** for the Memanto CLI itself.
* Verify with:
```bash theme={null}
python --version
```
* **`memanto`** Python package.
```bash theme={null}
pip install memanto
```
* **`moorcheh-client>=0.1.3`** — the Python package that ships the `moorcheh up` command and exposes the on-prem SDK shape Memanto talks to. The onboarding wizard installs this automatically the first time you choose **On-Prem** at the prompt; you can also install it explicitly:
```bash theme={null}
pip install "moorcheh-client>=0.1.3"
```
### Optional
* **`uvicorn[standard]`** if you plan to run `memanto serve` directly. Installed automatically as a dependency of `memanto` in most cases.
* **NVIDIA Container Toolkit** if you want Ollama to use a GPU inside Docker.
## Network & Ports
| Port | Bound to | Used by |
| --------- | ------------------------- | ------------------------------------------------------------------------------------------------- |
| **8000** | `localhost` (default) | Memanto's REST API (`memanto serve`, `memanto ui`). |
| **8080** | `localhost` (default) | Moorcheh on-prem server, started by `moorcheh up`. |
| **11434** | inside the Docker network | Ollama, when used as the embedding/LLM provider. Started as a sibling container by `moorcheh up`. |
You do **not** need any inbound internet access for the runtime path. Internet is required only:
* Once, to `pip install memanto` and `moorcheh-client`.
* Once per Ollama model, to pull the image from the Ollama registry.
* For every `answer.generate` call if your LLM provider is OpenAI or Cohere.
## Provider Choices
You will be prompted to choose providers during onboarding. The choices and what they imply:
| Provider | Embedding | LLM (Answer) | API key | Cost | Best for |
| ---------- | ------------------------ | ------------------------ | -------- | --------- | ----------------------------------------------------------------- |
| **Ollama** | `nomic-embed-text` | `qwen2.5` | None | \$0 | True air-gap; local development; demos; cost-sensitive workloads. |
| **OpenAI** | `text-embedding-3-small` | `gpt-4o-mini` | Required | Per-token | High-quality embeddings; existing OpenAI relationships. |
| **Cohere** | `embed-english-v3.0` | `command-r-plus-08-2024` | Required | Per-token | High-quality long-context answers; multilingual embeddings. |
You can mix providers — e.g., **Ollama embeddings** with an **OpenAI LLM** for answers. The onboarding wizard prompts for each independently.
## Disk Layout
Once onboarding finishes, the on-prem stack uses these locations on the host:
| Path | Owner | Purpose |
| ------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `~/.memanto/` | Memanto CLI | Top-level config dir. The cloud backend stores everything here. |
| `~/.memanto/on-prem/` | Memanto CLI (on-prem only) | Isolated data dir: agents, sessions, registry, and `state.json` for the on-prem backend. |
| `~/.memanto/on-prem/state.json` | Memanto CLI | Source of truth for `url`, `embedding_provider`, `embedding_model`, `llm_provider`, `llm_model`. |
| `~/.moorcheh/config.json` | `moorcheh-client` | Embedding and LLM provider config consumed by the on-prem server. |
| `~/.moorcheh/uploads/` | `moorcheh-client` | Staging area for files uploaded via `memanto upload` — paths inside this dir are mapped into the container. |
Cloud and on-prem state are deliberately kept in separate directories so you can switch backends without one polluting the other.
## Verifying Prerequisites
Before running the on-prem setup, the wizard performs these checks for you:
1. `docker` is on `PATH`.
2. `docker info` returns successfully (daemon is up).
3. `moorcheh-client>=0.1.3` is importable (installs it if not).
4. Provider API keys (if you chose OpenAI or Cohere) are non-empty.
If any check fails, the wizard prints a one-line error with a hint and exits with a non-zero status — no partial state is left behind.
## Next Step
→ [On-Prem Quickstart](./quickstart) — install the stack end-to-end in 5–10 minutes.
# Self-Hosting Memanto Server
Source: https://docs.memanto.ai/on-prem/server-deployment
Run the Memanto FastAPI REST server as a long-lived service with Docker, Compose, or systemd — on-prem or cloud.
# Self-Hosting Memanto Server
`memanto serve` runs the same FastAPI server that powers the [REST API](/api-reference/authentication). For development, running it from the CLI is enough — but for shared environments you'll want it under a process manager that survives logouts and restarts.
This page covers Docker, Docker Compose, systemd, and a manual long-running process. All four options work for **both** backends — set `MEMANTO_BACKEND=on-prem` to talk to your local Moorcheh server, or leave it `cloud` (default) for Moorcheh Cloud.
## Image: What Memanto Ships
The Memanto repository includes a production-ready `Dockerfile`:
* Base: `python:3.12-slim`
* Runs as a non-root user (`memanto`, UID `1001`)
* Exposes port `8000`
* Builds dependencies via [`uv`](https://github.com/astral-sh/uv) for fast, deterministic installs
* Built-in `HEALTHCHECK` polling `/ready` (a lightweight endpoint that does not call Moorcheh)
* Entry point: `uvicorn memanto.app.main:app --host 0.0.0.0 --port 8000`
## Option 1: Docker
### Cloud backend
```bash theme={null}
docker build -t memanto:latest .
docker run -d \
--name memanto \
-p 8000:8000 \
-e MOORCHEH_API_KEY=mk_your_key \
-e LOG_LEVEL=INFO \
--restart unless-stopped \
memanto:latest
curl http://localhost:8000/health
```
Expected response:
```json theme={null}
{
"status": "healthy",
"service": "MEMANTO",
"version": "0.1.x",
"moorcheh_connected": true
}
```
### On-prem backend
Memanto's container needs to reach the Moorcheh on-prem container running on the same host. On Linux/macOS, use `host.docker.internal`; on Linux without Docker Desktop, use `--network host` instead.
```bash theme={null}
docker run -d \
--name memanto \
-p 8000:8000 \
-e MEMANTO_BACKEND=on-prem \
-e MOORCHEH_ONPREM_URL=http://host.docker.internal:8080 \
-e LOG_LEVEL=INFO \
--restart unless-stopped \
memanto:latest
```
Or, if Moorcheh and Memanto are on the same user-defined Docker network (recommended):
```bash theme={null}
docker network create memanto-net
# (start moorcheh container attached to memanto-net as 'moorcheh')
docker run -d \
--name memanto \
--network memanto-net \
-p 8000:8000 \
-e MEMANTO_BACKEND=on-prem \
-e MOORCHEH_ONPREM_URL=http://moorcheh:8080 \
memanto:latest
```
## Option 2: Docker Compose
The Memanto repo ships a `docker-compose.yml` for the cloud backend. Drop in an `.env` file and you're done.
### Cloud backend
```bash theme={null}
cp .env.example .env
# Edit .env:
# MOORCHEH_API_KEY=mk_your_key
# ALLOWED_ORIGINS=https://yourdomain.com
# LOG_LEVEL=INFO
docker compose up -d
docker compose logs -f
```
### On-prem backend
Extend the compose file to add the Moorcheh server and (optionally) Ollama:
```yaml theme={null}
services:
memanto:
build: .
image: memanto:latest
container_name: memanto
depends_on:
moorcheh:
condition: service_healthy
environment:
MEMANTO_BACKEND: "on-prem"
MOORCHEH_ONPREM_URL: "http://moorcheh:8080"
LOG_LEVEL: "INFO"
ports:
- "8000:8000"
restart: unless-stopped
moorcheh:
image: moorcheh/moorcheh:latest # or build from your moorcheh-client
container_name: moorcheh
ports:
- "8080:8080"
volumes:
- moorcheh-data:/data
- ~/.moorcheh:/root/.moorcheh # for embedding/LLM config
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
interval: 30s
timeout: 5s
retries: 5
ollama: # only if your provider is ollama
image: ollama/ollama:latest
container_name: ollama
volumes:
- ollama-data:/root/.ollama
restart: unless-stopped
volumes:
moorcheh-data:
ollama-data:
```
Bring it up:
```bash theme={null}
docker compose up -d
docker compose ps
docker compose logs -f memanto
```
## Option 3: systemd (Linux)
For a single-host install without Docker, run Memanto under systemd. Save as `/etc/systemd/system/memanto.service`:
```ini theme={null}
[Unit]
Description=Memanto REST API
After=network.target docker.service
Wants=docker.service
[Service]
Type=simple
User=memanto
Group=memanto
WorkingDirectory=/opt/memanto
Environment=MEMANTO_BACKEND=on-prem
Environment=MOORCHEH_ONPREM_URL=http://127.0.0.1:8080
Environment=LOG_LEVEL=INFO
EnvironmentFile=/etc/memanto/memanto.env
ExecStart=/opt/memanto/.venv/bin/memanto serve --host 0.0.0.0 --port 8000
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
```
Then:
```bash theme={null}
sudo useradd --system --home-dir /opt/memanto --shell /usr/sbin/nologin memanto
sudo mkdir -p /opt/memanto && sudo chown memanto:memanto /opt/memanto
sudo -u memanto python -m venv /opt/memanto/.venv
sudo -u memanto /opt/memanto/.venv/bin/pip install memanto
sudo mkdir -p /etc/memanto
sudo install -m 600 /dev/stdin /etc/memanto/memanto.env <<'EOF'
# Empty file is fine on-prem (no MOORCHEH_API_KEY needed).
# For cloud, set:
# MOORCHEH_API_KEY=mk_...
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now memanto
sudo systemctl status memanto
journalctl -u memanto -f
```
The on-prem Moorcheh container (`moorcheh up`) should be managed by a separate systemd unit or by Docker's own `--restart unless-stopped` so it comes back automatically.
## Option 4: Manual / Background
For one-off testing on a remote host:
```bash theme={null}
nohup memanto serve --host 0.0.0.0 --port 8000 > memanto.log 2>&1 &
```
Stop it with `pkill -f "memanto serve"`. Not recommended for production — use systemd or Docker.
## Endpoints to Probe
All deployment modes expose the same operational endpoints:
| Endpoint | Purpose | Notes |
| ------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `GET /health` | Full health, including Moorcheh connectivity. | Returns 200 only when Moorcheh is reachable; use for readiness gating before sending traffic. |
| `GET /ready` | Lightweight check; always 200 once the process is up. | Use for liveness probes — does not depend on Moorcheh. |
| `GET /live` | Same as `/ready`. | Kept for Kubernetes idiom. |
| `GET /docs` | Swagger UI for the REST API. | |
| `GET /redoc` | ReDoc rendering of the OpenAPI spec. | |
| `GET /ui` | Web dashboard. | Available when running `memanto ui` or with `MEMANTO_UI_MODE=true`. |
## Performance & Concurrency
For more than a handful of concurrent agents, run Memanto with multiple `uvicorn` workers behind a reverse proxy:
```bash theme={null}
uvicorn memanto.app.main:app \
--host 0.0.0.0 --port 8000 \
--workers 4 \
--proxy-headers
```
Recommended starting point for a single host:
* **2 workers** per CPU core (Memanto is I/O-bound).
* **Reverse proxy** (Nginx, Caddy, or Traefik) terminating TLS and forwarding to `127.0.0.1:8000`.
* **Rate limits** at the proxy if exposing publicly.
## CORS
By default, `ALLOWED_ORIGINS=*`. Restrict in production:
```bash theme={null}
export ALLOWED_ORIGINS="https://app.yourdomain.com,https://admin.yourdomain.com"
```
## Logs
Structured JSON logging is enabled by default. Memory operations are logged with content redaction so payloads never end up in your log aggregator.
```bash theme={null}
# Docker
docker logs -f memanto
# systemd
journalctl -u memanto -f
# Local
memanto serve # logs to stdout
```
Set `LOG_LEVEL=DEBUG` for detailed request/response traces during troubleshooting.
## Next Steps
* [Kubernetes Deployment](./kubernetes) — manifests for a clustered install.
* [Security & Operations](./security) — TLS, secrets management, hardening.
* [Troubleshooting](./troubleshooting) — common deployment failure modes.
# Memory Types
Source: https://docs.memanto.ai/reference/memory-types
Complete reference for all 13 semantic memory types in Memanto.
# Memory Types Reference
Complete reference for all 13 semantic memory types in Memanto.
## Why Memory Types?
Memory types serve two purposes:
1. **Organization** - Group related memories instead of throwing everything into a generic "notes" bucket.
2. **Filtering** - Query specific types (e.g., retrieving only "commitments" or "preferences").
## Quick Reference
| Type | Use Case | Example |
| ---------------- | --------------------- | ------------------------- |
| **fact** | Objective information | "User is in Finance dept" |
| **preference** | Likes/dislikes | "Prefers email contact" |
| **decision** | Choices made | "Chose PostgreSQL" |
| **commitment** | Promises/obligations | "Will deliver Friday" |
| **goal** | Objectives | "Reach 10K users" |
| **event** | Things that happened | "Meeting at 2pm" |
| **instruction** | Rules/procedures | "Validate input always" |
| **relationship** | Connections | "Alice manages Bob" |
| **context** | Situational info | "In Q1 planning" |
| **learning** | Lessons learned | "Users need help" |
| **observation** | Patterns noticed | "Traffic peaks Fridays" |
| **error** | Mistakes to avoid | "Skip validation=bug" |
| **artifact** | Documents/files | "Q3 budget.xlsx" |
## Detailed Definitions
### fact
**Objective, verifiable information about the world or domain.**
* Static information
* Not opinions or preferences
* Verifiable claims
* Core knowledge
Examples:
* "Paris is the capital of France"
* "Database uses PostgreSQL"
* "Team has 5 engineers"
CLI:
```bash theme={null}
memanto remember "Paris is the capital of France" --type fact
```
### preference
**User or system likes, dislikes, or preferences.**
* Opinions about preferences
* User/system choices
* Style choices
* Communication preferences
Examples:
* "Prefers dark mode"
* "Email over phone"
* "Concise responses"
CLI:
```bash theme={null}
memanto remember "Prefers email contact" --type preference
```
### decision
**Important choices made that affect future behavior.**
* Technology choices
* Process decisions
* Strategic choices
* Why decisions
Examples:
* "Chose TypeScript for codebase"
* "Decided to use AWS"
* "Selected Agile methodology"
CLI:
```bash theme={null}
memanto remember "Chose PostgreSQL for database" --type decision
```
### commitment
**Promises or obligations made.**
* Deliverables
* Promises to keep
* Obligations
* Accountability
Examples:
* "Will deliver report by Friday"
* "Committed to 10% growth"
* "Promised 24/7 support"
CLI:
```bash theme={null}
memanto remember "Will deliver API docs by Friday" --type commitment
```
### goal
**Objectives to achieve.**
* Future targets
* KPIs
* Milestones
* Aspirations
Examples:
* "Reach 1M users"
* "Improve performance by 50%"
* "Launch MVP by Q2"
CLI:
```bash theme={null}
memanto remember "Launch MVP by March 31" --type goal
```
### event
**Something that happened or will happen.**
* Historical events
* Meetings
* Incidents
* Milestones
Examples:
* "Had meeting with CEO"
* "System outage on March 20"
* "Project launched successfully"
CLI:
```bash theme={null}
memanto remember "Team meeting at 2pm" --type event
```
### instruction
**Rules, guidelines, or procedures to follow.**
* Policies
* Best practices
* Procedures
* Constraints
Examples:
* "Always validate input"
* "Follow REST conventions"
* "Require code review"
CLI:
```bash theme={null}
memanto remember "Always validate user input" --type instruction
```
### relationship
**Connections or relationships between entities.**
* People relationships
* System dependencies
* Business relationships
* Hierarchies
Examples:
* "Alice manages Bob"
* "Project X depends on API Y"
* "Customer referred by John"
CLI:
```bash theme={null}
memanto remember "Alice manages Bob" --type relationship
```
### context
**Contextual information about the current situation.**
* Seasonal context
* Business phases
* System states
* Environmental factors
Examples:
* "In Q1 planning phase"
* "Budget season is active"
* "System in maintenance"
CLI:
```bash theme={null}
memanto remember "We're in Q1 planning" --type context
```
### learning
**Lessons learned from experience.**
* Insights
* Lessons
* Patterns recognized
* Knowledge gained
Examples:
* "Users need better onboarding"
* "Mobile-first is essential"
* "Documentation must be clear"
CLI:
```bash theme={null}
memanto remember "Users need simpler onboarding" --type learning
```
### observation
**Something noticed or perceived.**
* Patterns observed
* Trends noticed
* Data observations
* Field observations
Examples:
* "Traffic peaks on Fridays"
* "Users skip step 2"
* "Support tickets spike after releases"
CLI:
```bash theme={null}
memanto remember "Traffic peaks on Fridays" --type observation
```
### error
**Mistakes to avoid in the future.**
* Warnings
* Lessons from failures
* Anti-patterns
* Known issues
Examples:
* "Avoid deprecated API"
* "Skip validation=bug"
* "Don't hardcode secrets"
CLI:
```bash theme={null}
memanto remember "Never skip input validation" --type error
```
### artifact
**Important documents, files, or references.**
* Documents
* Code files
* Resources
* References
Examples:
* "Q3 budget spreadsheet"
* "API documentation file"
* "Customer contract"
CLI:
```bash theme={null}
memanto remember "Q3 budget spreadsheet" --type artifact
```
## Selection Guide
```
Does it describe something that happened?
→ event
Is it a choice or decision?
→ decision
Is it a promise or obligation?
→ commitment
Is it a rule or guideline?
→ instruction
Is it someone's preference?
→ preference
Is it an objective fact?
→ fact
Is it a future goal?
→ goal
Is it a lesson learned?
→ learning
Is it a pattern observed?
→ observation
Is it a warning or mistake?
→ error
Is it a connection between things?
→ relationship
Is it situational info?
→ context
Otherwise, ask: "Is it a document/file?"
→ artifact
```
## Best Practices
### DO
* Use specific types for better organization
* Choose the most specific type available
* Be consistent in your selections
* Filter queries by type when appropriate
### DON'T
* Overuse generic "fact" type
* Store everything as one type
* Mix unrelated information in one memory
* Ignore type distinctions
* Use wrong type for convenience
* Skip commitment type for promises
* Forget about error type for lessons
***
## Filtering by Type
### CLI
```bash theme={null}
# Get only commitments
memanto recall "what must we do" --type commitment
# Get only preferences
memanto recall "what does user like" --type preference
# Get only decisions
memanto recall "why did we choose this" --type decision
```
### API
```python theme={null}
response = httpx.get(
f"{base}/agents/{agent}/recall",
params={
"query": "What must we do?",
"memory_type": "commitment"
},
headers=headers
)
```
# TypeScript SDK Reference
Source: https://docs.memanto.ai/sdk/typescript
Full reference for the @moorcheh-ai/memanto TypeScript SDK.
# TypeScript SDK Reference
The `@moorcheh-ai/memanto` SDK for Node.js / TypeScript boots a local Memanto server on demand via `uvx` and exposes an ergonomic client.
## Prerequisites
* **Node.js 20+**
* **`uvx` on PATH** — install [uv](https://docs.astral.sh/uv/getting-started/installation/) (which ships `uvx`)
## Installation
```bash theme={null}
npm install @moorcheh-ai/memanto
```
## Quick Start
```ts theme={null}
import { Memanto } from "@moorcheh-ai/memanto";
const memanto = new Memanto({
agentId: "my-agent",
apiKey: process.env.MOORCHEH_API_KEY,
});
await memanto.remember({ content: "Alex prefers oat milk." });
const { memories } = await memanto.recall({ query: "what does Alex drink?" });
console.log(memories);
const { answer } = await memanto.answer({ question: "Does Alex drink dairy?" });
console.log(answer);
await memanto.close();
```
On the first call, the SDK:
1. Picks a free port and spawns `uvx memanto serve --port `.
2. Polls `/health` until the server is ready.
3. Creates the agent (if `autoCreate` is enabled — default `true`) and activates a session.
4. Sends the request with the session token attached.
When `close()` is called (or the Node process exits), the server is sent `SIGTERM`.
## `Memanto` Client
### Constructor
```ts theme={null}
new Memanto(options: MemantoOptions)
```
| Option | Type | Default | Description |
| ----------------- | --------- | ----------- | ------------------------------------------------------------- |
| `agentId` | `string` | — | **Required.** Agent identifier. |
| `apiKey` | `string` | — | Moorcheh API key, passed to the server as `MOORCHEH_API_KEY`. |
| `autoCreate` | `boolean` | `true` | Create the agent if it does not exist. |
| `baseUrl` | `string` | — | Use an already-running server URL instead of spawning one. |
| `port` | `number` | auto | Bind the spawned server to this port. |
| `host` | `string` | `127.0.0.1` | Bind host. |
| `uvxPath` | `string` | `uvx` | Override the path to `uvx`. |
| `packageSpec` | `string` | `memanto` | Package spec for `uvx`. Use `memanto==0.2.3` to pin. |
| `healthTimeoutMs` | `number` | `60000` | Health-check timeout. |
| `verbose` | `boolean` | `false` | Stream server logs to the parent process. |
### Memory Write Methods
```ts theme={null}
await memanto.remember({ content, type?, title?, confidence?, tags?, source?, provenance? })
await memanto.batchRemember(items[]) // up to 100 items
await memanto.extractMemories({ messages, dryRun?, maxMemories?, aiModel? })
await memanto.uploadFile({ path, filename? }) // .pdf, .docx, .xlsx, .json, .txt, .csv, .md
await memanto.deleteMemory(memoryId)
```
### Memory Read Methods
```ts theme={null}
await memanto.recall({ query, limit?, minSimilarity?, type? })
await memanto.recallAsOf({ asOf, limit?, type? }) // point-in-time
await memanto.recallChangedSince({ since, limit?, type? }) // what changed after
await memanto.recallRecent({ limit?, type? }) // newest-first
await memanto.answer({ question, limit?, threshold?, temperature?, aiModel?, kioskMode? })
```
### Analysis Methods
```ts theme={null}
await memanto.dailySummary({ date?, outputPath? })
await memanto.generateConflicts({ date? })
await memanto.listConflicts({ date? })
await memanto.resolveConflict({ conflictIndex, action, date?, manualContent?, manualType? })
```
`action` is one of: `keep_old | keep_new | keep_both | remove_both | manual`.
### Agent & Session Lifecycle
```ts theme={null}
await memanto.listAgents()
await memanto.getAgent()
await memanto.createAgent({ pattern?, description? })
await memanto.deleteAgent()
await memanto.deactivate() // end session, next call rebootstraps
await memanto.status() // current session info
await memanto.close() // stop the spawned server
```
### Diagnostics
```ts theme={null}
import { doctor } from "@moorcheh-ai/memanto";
const result = await doctor();
if (!result.uvxAvailable) {
console.error(result.hint);
}
```
## Framework Integrations
The SDK ships pre-built memory tools for three agent frameworks, each behind its own subpath import so unused framework code never enters your bundle:
| Framework | Import | Docs |
| --------------- | ----------------------------- | -------------------------------------------------------- |
| Vercel AI SDK | `@moorcheh-ai/memanto/ai-sdk` | [Vercel AI SDK Integration](/integrations/vercel-ai-sdk) |
| Mastra | `@moorcheh-ai/memanto/mastra` | [Mastra Integration](/integrations/mastra) |
| OpenAI Node SDK | `@moorcheh-ai/memanto/openai` | [OpenAI Integration](/integrations/openai) |
Each exposes `recallMemory`, `rememberMemory`, and `answerMemory` tools backed by this same `Memanto` client. The corresponding framework package (`ai`, `@mastra/core`, or `openai`) plus `zod` are optional peer dependencies — install only the ones you use.
## Versioning
The npm package version tracks the matching PyPI release. Pin the server version with:
```ts theme={null}
new Memanto({
packageSpec: "memanto==0.2.3",
// ...
});
```
## License
MIT