# MEMANTO — Full Reference for AI Agents and LLM Tooling

> This is the detailed reference version of llms.txt. See /llms.txt for the condensed summary.

MEMANTO is an open-source, production-ready memory agent that gives AI agents persistent, semantic long-term memory across sessions. It provides instant recall with zero ingestion latency, and is 100% free: run it fully on-prem on your own machine with no API key (Docker + local Ollama models), or use Moorcheh Cloud's free tier. Install with `pip install memanto` (Python/CLI/server) or `npm install @moorcheh-ai/memanto` (TypeScript). MIT licensed.

---

## Quick Identity

- **Name**: MEMANTO
- **Category**: AI memory agent / developer platform
- **License**: MIT
- **Install (Python)**: `pip install memanto`
- **Install (TypeScript)**: `npm install @moorcheh-ai/memanto`
- **Install (MCP server)**: `pip install memanto-mcp`
- **PyPI**: https://pypi.org/project/memanto/
- **npm**: https://www.npmjs.com/package/@moorcheh-ai/memanto
- **GitHub**: https://github.com/moorcheh-ai/memanto
- **Docs**: https://docs.memanto.ai
- **Landing page**: https://memanto.ai
- **Built on**: Moorcheh.ai — an information-theoretic semantic engine. Unlike vector databases that rely on approximate search and require indexing pipelines, Moorcheh returns exact results with zero indexing delay: write a memory and it is searchable immediately.
- **Benchmark accuracy**: 89.8% on LongMemEval, 87.1% on LoCoMo — outperforming Mem0, Zep, and Letta
- **Paper**: *Memanto: Typed Semantic Memory with Information-Theoretic Retrieval for Long-Horizon Agents* — arXiv:2604.22085 (https://arxiv.org/abs/2604.22085)
- **Datasets**: https://huggingface.co/moorcheh

---

## Core Problem MEMANTO Solves

LLMs are stateless — they forget everything between sessions. This means:
- Agents repeat questions users already answered
- Preferences and decisions must be re-explained every conversation
- Long-horizon tasks lose context when sessions end

MEMANTO fixes this by giving agents a persistent, semantically searchable memory store that survives across sessions, restarts, and model changes.

### The six gaps MEMANTO was designed around

| # | Gap in typical memory tools | What MEMANTO does |
|---|---|---|
| 1 | Static injection — memory arrives as a blob, not queryable by relevance | Queryable, not injectable |
| 2 | No temporal decay — a 6-month-old preference weighs the same as yesterday's deadline | Versioning, recency signals, temporal queries |
| 3 | No provenance — can't tell explicit facts from inferred patterns | Confidence + provenance metadata on every memory |
| 4 | Flat memory — episodic, semantic, procedural collapsed into one layer | 13 typed memory categories |
| 5 | No writeback — contradictions silently coexist | Conflict detection, explicit versioning, no silent overwrites |
| 6 | Indexing delay — mandatory LLM extraction / graph construction | Zero-overhead ingestion, searchable at write time |

---

## Installation and Setup

```bash
pip install memanto
memanto                          # first run: choose Cloud (paste API key) or On-Prem (no key)
memanto agent create my-agent    # create an agent namespace
memanto agent activate my-agent  # activate agent for this session
```

Get a free Moorcheh API key (100K ops/month free tier): https://console.moorcheh.ai/api-keys

**On-Prem alternative**: Run `memanto` and select **On-Prem** at the backend prompt. No API key required — the wizard installs a Docker-based Moorcheh server plus optional Ollama for local embeddings/LLM. See the On-Prem section below.

Switch backends at any time with `memanto config backend cloud` / `memanto config backend on-prem`.

---

## Core CLI Commands

### System & Configuration
```bash
memanto status                    # environment, config, server health, active session, registered agents
memanto serve                     # start REST API server (default: 127.0.0.1:8000)
memanto ui                        # start the server and open the web dashboard (same host/port as serve)
memanto config show               # API key status, active agent/session, server settings, schedule time
memanto config backend cloud      # switch to Moorcheh Cloud
memanto config backend on-prem    # switch to the local Docker backend
```

### Agent Management
```bash
memanto agent create <name>       # create agent with isolated namespace
memanto agent list                # list all agents
memanto agent activate <name>     # activate agent for current session
memanto agent deactivate          # deactivate current agent
memanto agent delete <name>       # delete agent and all its memories
memanto agent bootstrap           # generate intelligence snapshot of agent's memory
memanto session info              # show current session details
```

### Memory Write
```bash
memanto remember "<text>"                          # store a memory (type auto-classified)
memanto remember "<text>" --type preference        # store with explicit type
memanto remember "<text>" --title "..." --tags a,b --confidence 0.9 --source user \
                          --provenance explicit_statement
memanto remember --batch memories.json             # batch ingest a JSON array (max 100 items)
memanto remember --from-conversation chat.json     # extract durable memories from a transcript
memanto remember --from-conversation - --dry-run   # read transcript from stdin, preview only
memanto edit <memory_id> --content "..." --type fact --confidence 0.9 --tags a,b --title "..."
memanto forget <memory_id>                         # permanently delete one memory
memanto upload <file_path>                         # .pdf, .docx, .xlsx, .json, .txt, .csv, .md
```

`--from-conversation` options: `--dry-run`, `--max-memories N` (1–100, default 20), `--ai-model TEXT`.

### Memory Read
```bash
memanto recall "<query>"                             # semantic search
memanto recall "<query>" --type fact --limit 20      # filter by type, cap results
memanto recall "<query>" --tags infra,db --min-similarity 0.5
memanto recall --as-of "2026-06-01"                  # point-in-time: what was true then
memanto recall --changed-since "last 2 days"         # differential: what changed since
memanto recall --recent --limit 10                   # chronological: newest first
memanto answer "<question>"                          # RAG-grounded answer from memory
```

Temporal flags are mutually exclusive and take no search query. They accept ISO timestamps (`2026-06-01`, `2026-06-01T00:00:00Z`) or relative phrases (`today`, `yesterday`, `last 2 days`, `last 5 hours`, `this week`, `this month`).

### Analysis & Daily Workflows
```bash
memanto daily-summary                  # generate the daily memory digest
memanto detect-conflicts               # run the conflict-detection pass, write report to ~/.memanto/conflicts/
memanto conflicts                      # interactively resolve detected conflicts
memanto conflicts --list               # list conflicts without resolving
memanto schedule enable                # run daily-summary + conflict detection on a schedule
memanto schedule disable
memanto schedule status
```

Both `detect-conflicts` and `conflicts` accept `--date YYYY-MM-DD` and `--agent <id>`.

### Export / Sync / Import
```bash
memanto memory export                        # write memory.md (all 13 types, sectioned)
memanto memory export -n 50 -o ./memory.md   # limit per type (1–100), custom output path
memanto memory export --okf                  # write an OKF bundle instead
memanto memory export --okf --split type     # OKF layout: auto | file | type
memanto memory sync -p ./my-project          # refresh export and write MEMORY.md into a project
memanto memory sync --okf -p ./my-project    # sync an OKF bundle into <project>/okf

memanto migrate mem0                         # import from Mem0
memanto migrate letta                        # import from Letta
memanto migrate supermemory                  # import from Supermemory
memanto migrate okf <path>                   # import an OKF bundle (directory or single .md)
```

Provider migration options: `--dry-run` (preview without writing), `--report` (savings comparison), `--file PATH` (use a local export), `--agent TEXT` (target agent). `migrate okf` takes `--agent` and `--dry-run` only — it is a local file import, so no API key and no savings report.

### IDE / Tool Integration
```bash
memanto connect claude-code       # Claude Code
memanto connect cursor            # Cursor
memanto connect windsurf          # Windsurf
memanto connect cline             # Cline
memanto connect codex             # Codex CLI
memanto connect gemini-cli        # Gemini CLI
memanto connect github-copilot    # GitHub Copilot
memanto connect antigravity       # Antigravity (Google)
memanto connect continue          # Continue
memanto connect opencode          # OpenCode
memanto connect goose             # Goose
memanto connect roo               # Roo Code
memanto connect augment           # Augment Code
memanto connect list              # list all connected tools and status
memanto connect remove <target>   # disconnect a tool
memanto connect multi             # interactive multi-tool connection
```

`memanto connect <tool>` installs a tool-specific skill/rules file (e.g. `CLAUDE.md`, `.cursor/rules/memanto.mdc`) into the project or your global config.

---

## REST API Reference

Base URL: `http://127.0.0.1:8000` (when running `memanto serve`). Interactive OpenAPI docs at `http://127.0.0.1:8000/docs`.

### Authentication

MEMANTO uses three distinct credentials:

1. **Server-side Moorcheh API key** — `MOORCHEH_API_KEY` is configured on the server and used for every Moorcheh call. It is never accepted from clients.
2. **Session token** — required on every memory operation:
   ```
   X-Session-Token: <session_token>
   ```
   Obtained by activating an agent; sessions last 6 hours and must match the `agent_id` in the path (403 otherwise). Browser clients may instead use the `HttpOnly`, `SameSite=Strict` cookie `memanto_session_token`, set on activate and cleared on deactivate. The cookie's `Secure` flag follows the actual request scheme.
3. **Management credential** — since `v0.2.7`, agent-lifecycle endpoints (`POST /agents`, `GET /agents`, `GET /agents/{id}`, `DELETE /agents/{id}`, activate, deactivate, `GET /status`) require either a loopback client origin or:
   ```
   Authorization: Bearer <key>
   ```
   or
   ```
   X-Api-Key: <key>
   ```
   Attach it when calling from outside `localhost`.

Sample request:
```bash
curl -X POST "http://127.0.0.1:8000/api/v2/agents/my-agent/recall" \
  -H "X-Session-Token: <session_token>" \
  -H "Content-Type: application/json" \
  -d '{"query":"project decisions","limit":5}'
```

### Health

```
GET /health      # service health, active backend, Moorcheh connectivity
GET /ready       # readiness probe
GET /live        # liveness probe
```

### Agent Management

**Create agent**
```
POST /api/v2/agents
Body: { "name": "my-agent" }
Response: { "agent_id": "...", "namespace": "my-agent", "created_at": "..." }
```

**List agents**
```
GET /api/v2/agents
Response: { "agents": [...] }
```

**Get agent metadata**
```
GET /api/v2/agents/{agent_id}
Response: { "agent_id": "...", "namespace": "...", "memory_count": 42 }
```

**Delete agent**
```
DELETE /api/v2/agents/{agent_id}
```
Query parameters: `?delete-backup-too=true` to also delete the Moorcheh namespace backup. Deleting an agent also deletes its persisted session state.

### Session Management

**Activate session**
```
POST /api/v2/agents/{agent_id}/activate
Response: { "session_token": "...", "expires_at": "..." }
```
Sessions last 6 hours. Required for all memory operations below.

**Session info / status**
```
GET /api/v2/status
```

**Deactivate session**
```
POST /api/v2/agents/{agent_id}/deactivate
```

### Memory Operations

*All memory operations require the `X-Session-Token: {session_token}` header (or the session cookie).*

**Store memory**
```
POST /api/v2/agents/{agent_id}/remember
Body: {
  "content": "User prefers TypeScript over JavaScript",   // required, max 10000 chars, non-blank
  "type": "preference",          // optional, auto-classified if omitted
  "title": "...",                // optional, max 100 chars, defaults to truncated content
  "confidence": 0.8,             // optional, 0.0–1.0
  "tags": ["lang"],              // optional
  "source": "agent",             // optional
  "provenance": "explicit_statement"  // explicit_statement | inferred | corrected | validated | observed | imported
}
Response: { "memory_id": "...", "stored_at": "...", "type": "preference" }
```

**Batch ingest**
```
POST /api/v2/agents/{agent_id}/batch-remember
Body: { "memories": [ { "content": "...", "type": "..." }, ... ] }   // 1–100 items
Response: { "successful": N, "failed": N, "total_submitted": N, ... }
```

**Edit memory (partial update)**
```
PATCH /api/v2/agents/{agent_id}/memories/{memory_id}
Body: { "title"?, "content"?, "type"?, "confidence"?, "tags"?, "source"? }   // at least one
```

**Extract memories from a conversation**
```
POST /api/v2/agents/{agent_id}/remember/extract
Body: {
  "messages": [ { "role": "user", "content": "..." }, ... ],  // 1–200 turns
  "dry_run": false,        // true returns candidates without storing
  "max_memories": 20,      // 1–100
  "ai_model": null         // optional override
}
Response: { "candidates": [...], "successful": N, "failed": N, "total_submitted": N }
```

**Upload file**
```
POST /api/v2/agents/{agent_id}/upload-file
# Multipart form data: PDF, DOCX, TXT, CSV, JSON, MD, XLSX
# Streamed to disk in 1 MB chunks; 5 GB cap enforced during the stream (413 if exceeded)
```

**Delete memory**
```
DELETE /api/v2/agents/{agent_id}/memories/{memory_id}
```

**Recall memories**
```
POST /api/v2/agents/{agent_id}/recall
Body: {
  "query": "coding language",   // required, non-blank
  "limit": 10,
  "type": ["preference"],       // optional type filter
  "tags": ["lang"],             // optional tag filter
  "min_similarity": 0.5,        // optional
  "created_after": "...",       // optional ISO timestamp
  "created_before": "..."       // optional ISO timestamp
}
Response: {
  "agent_id": "...", "session_id": "...", "query": "...", "count": 1,
  "memories": [
    { "memory_id": "...", "content": "...", "type": "...", "score": 0.97,
      "confidence": 0.9, "provenance": "explicit_statement", "tags": [...],
      "created_at": "...", "updated_at": "..." }
  ]
}
```

**Temporal queries**
```
POST /api/v2/agents/{agent_id}/recall/as-of           # what was true at a point in time
POST /api/v2/agents/{agent_id}/recall/changed-since   # what changed after a timestamp
POST /api/v2/agents/{agent_id}/recall/recent          # newest-first, no query needed
```
All three accept `limit`, `type`, and `tags` filters, and return `temporal_mode` alongside the memories. Date-only `as-of` values cover the full day.

**RAG-powered answer**
```
POST /api/v2/agents/{agent_id}/answer
Body: {
  "question": "What programming language does the user prefer?",  // required, non-blank
  "limit": 10,           // context memories to use, 1–100
  "temperature": 0.2,    // 0.0–2.0
  "ai_model": null,      // optional model override
  "kiosk_mode": false,   // strict grounded mode
  "threshold": 0.7       // confidence threshold, used only in kiosk mode
}
Response: { "agent_id": "...", "session_id": "...", "question": "...", "answer": "TypeScript", "sources": [...], "namespace": "..." }
```

**Daily summary**
```
POST /api/v2/agents/{agent_id}/daily-summary
```

**Conflict detection & resolution**
```
POST /api/v2/agents/{agent_id}/conflicts/generate   # run the detection pass
GET  /api/v2/agents/{agent_id}/conflicts            # list detected conflicts
POST /api/v2/agents/{agent_id}/conflicts/resolve    # resolve one
# action: keep_old | keep_new | keep_both | remove_both | manual
# manual requires non-empty manual_content
```

---

## Memory Types

MEMANTO supports 13 semantic memory types. The system auto-classifies if no type is specified.

| Type | Description | Example |
|------|-------------|---------|
| `fact` | Objective facts about the world or user | "User's name is Alex" |
| `preference` | User preferences and style choices | "User prefers dark mode" |
| `decision` | Choices made by agent or user | "Decided to use PostgreSQL for this project" |
| `goal` | Active objectives and intentions | "Goal: ship v2 by end of quarter" |
| `commitment` | Promises or commitments made | "Promised to review PR by Friday" |
| `event` | Time-bound occurrences | "Deployed to production on 2026-06-10" |
| `instruction` | Directives and rules to follow | "Always use TypeScript strict mode" |
| `relationship` | Connections between entities | "Alice is the tech lead for project X" |
| `context` | Situational background | "Working on a fintech startup" |
| `learning` | Insights and lessons learned | "Learned that Redis TTL causes cache stampedes" |
| `observation` | Behavioral patterns noticed | "User tends to ask about performance after lunch" |
| `error` | Mistakes and failures to avoid | "Tried approach X, caused memory leak" |
| `artifact` | Code, configs, documents | "Auth middleware lives in /src/middleware/auth.ts" |

Every memory also carries `confidence` (0.0–1.0), `provenance` (`explicit_statement`, `inferred`, `corrected`, `validated`, `observed`, `imported`), `source`, `tags`, `created_at`, and `updated_at`.

---

## Key Architecture Concepts

### Namespaces
Each agent has a fully isolated memory namespace derived from the agent id. Agents cannot read each other's memories.

### Sessions
Sessions are 6-hour windows. Within a session, the agent has an active context. Memories persist permanently beyond the session — sessions just scope the active identity and authorize writes. A session token is bound to one `agent_id`; using it against another agent returns 403.

### Semantic Search
MEMANTO uses Moorcheh's information-theoretic engine. Unlike vector DBs that require indexing pipelines and approximate search, Moorcheh makes memories searchable the instant they are written and returns exact results. Queries match by meaning, not keywords — no reranker, no multi-stage pipeline, no graph schema.

### Zero Ingestion Latency
Stored memories are immediately queryable — there is no background indexing job, no LLM extraction at write time, no eventual consistency delay.

### Deployment flexibility
Run the backend fully local (Docker), as a managed cloud service, or in your own VPC — and switch between them with `memanto config backend`. Cloud mode is serverless: zero cost when idle, scales automatically.

---

## IDE / Agent Integrations (13 tools)

All configured with `memanto connect <slug>`:

| Tool | Slug | Type | Docs |
|------|------|------|------|
| Claude Code | `claude-code` | AI coding assistant | /integrations/claude-code |
| Cursor | `cursor` | AI code editor | /integrations/cursor |
| Windsurf | `windsurf` | AI code editor | /integrations/windsurf |
| Cline | `cline` | VS Code AI agent | /integrations/cline |
| Codex CLI | `codex` | OpenAI CLI agent | /integrations/codex |
| Gemini CLI | `gemini-cli` | Google CLI agent | /integrations/gemini-cli |
| GitHub Copilot | `github-copilot` | AI code assistant | /integrations/github-copilot |
| Antigravity (Google) | `antigravity` | AI coding assistant | /integrations/antigravity |
| Continue | `continue` | Open-source AI assistant | /integrations/continue |
| OpenCode | `opencode` | Terminal AI agent | /integrations/opencode |
| Goose | `goose` | Autonomous dev agent | /integrations/goose |
| Roo Code | `roo` | VS Code AI agent | /integrations/roo |
| Augment Code | `augment` | AI coding assistant | /integrations/augment |

---

## VS Code Extension

A native extension, installed from the Marketplace rather than with `memanto connect`:

```bash
code --install-extension moorcheh.memanto
```

- **Chat sidebar**: Recall lists matching memories with type, confidence, provenance and date; Answer writes a reply grounded in them. Also most recent, as-of-date and changed-since views.
- **Memories tree**: an agent's memories grouped by memory type.
- **Remember selection**: save selected code or text as a typed memory.
- **Copilot Chat participant**: `@memanto`, with `/recall`, `/recent` and `/remember`.
- **Copilot agent-mode tools**: `memanto_recall` (`#memanto`) and `memanto_answer` (`#memantoAsk`) run on their own; `memanto_remember` (`#memantoRemember`) asks the user before saving.
- **Zero configuration**: reads the key from `~/.memanto/.env` and the active agent from `~/.memanto/config.yaml`, and runs a private `memanto serve` per window on a free loopback port, stopped when the window closes.
- **Requires**: VS Code 1.95+ and the Memanto CLI (Python 3.10+). Copilot Chat only for the participant and tools.

Docs: https://docs.memanto.ai/integrations/vscode · Marketplace: https://marketplace.visualstudio.com/items?itemName=moorcheh.memanto

---

## Framework Integrations

**Python**
- **LangChain** — memory backend in agent chains: https://docs.memanto.ai/integrations/langchain
- **LangGraph** — `MemantoStore` plus recall/remember nodes: https://docs.memanto.ai/integrations/langgraph
- **LlamaIndex** — plug into LlamaIndex agent workflows: https://docs.memanto.ai/integrations/llamaindex
- **CrewAI** — persistent memory for multi-agent teams: https://docs.memanto.ai/integrations/crewai
- **Google ADK** — `pip install memanto-google-adk`; drop-in `MemantoMemoryService` for ADK's `preload_memory` / `load_memory`: https://docs.memanto.ai/integrations/google-adk
- **n8n** — use in workflow automation: https://docs.memanto.ai/integrations/n8n
- **Hermes Agents** — `pip install hermes-memanto`: https://docs.memanto.ai/integrations/hermes-agents

**TypeScript** (subpath imports of `@moorcheh-ai/memanto`, each with `recallMemory` / `rememberMemory` / `answerMemory` tools and a shared `MEMORY_TYPES` export)
- **Vercel AI SDK** — `@moorcheh-ai/memanto/ai-sdk`: https://docs.memanto.ai/integrations/vercel-ai-sdk
- **Mastra** — `@moorcheh-ai/memanto/mastra`: https://docs.memanto.ai/integrations/mastra
- **VoltAgent** — `@moorcheh-ai/memanto/voltagent`: https://docs.memanto.ai/integrations/voltagent
- **OpenAI Node SDK** — `@moorcheh-ai/memanto/openai`: https://docs.memanto.ai/integrations/openai

Framework packages (`ai`, `@mastra/core`, `@voltagent/core`, `openai`, plus `zod`) are optional peer dependencies — install only the ones you use.

---

## MCP Integration

The `memanto-mcp` package exposes MEMANTO memory primitives as Model Context Protocol tools for any MCP-compatible client.

**Install:**
```bash
pip install memanto-mcp
```

**Memory tools exposed:** `remember`, `batch_remember`, `recall`, `recall_recent`, `recall_as_of`, `recall_changed_since`, `answer`.

**Admin tools** (opt-in via `MEMANTO_EXPOSE_ADMIN=true`): `create_agent`, `list_agents`, `get_agent`, `delete_agent`.

**Config example (Claude Desktop):**
```json
{
  "mcpServers": {
    "memanto": {
      "command": "memanto-mcp",
      "env": {
        "MOORCHEH_API_KEY": "mch_...",
        "MEMANTO_DEFAULT_AGENT_ID": "my-assistant"
      }
    }
  }
}
```

**Environment variables:** `MOORCHEH_API_KEY`, `MEMANTO_DEFAULT_AGENT_ID`, `MEMANTO_AGENT_PATTERN`, `MEMANTO_AGENT_AUTO_CREATE`, `MEMANTO_SESSION_DURATION_HOURS`, `MEMANTO_EXPOSE_ADMIN`, `MEMANTO_MCP_TRANSPORT`, `MEMANTO_MCP_HOST`, `MEMANTO_MCP_PORT`, `MEMANTO_MCP_LOG_LEVEL`.

The first call auto-creates the configured agent and namespace; every subsequent call reuses the same persistent memory. Works with Claude Desktop, Cursor, Windsurf, Cline, Continue, Goose, Codex, and any MCP host. Multiple clients pointed at the same `agent_id` share one memory namespace.

**PyPI:** https://pypi.org/project/memanto-mcp/

---

## TypeScript SDK (`@moorcheh-ai/memanto`)

A fully-typed client generated from the API's OpenAPI spec. On first call it picks a free port, spawns `uvx memanto serve --port <port>`, polls `/health`, creates the agent if needed, activates a session, and attaches the session token.

**Prerequisites:** Node.js 20+, and `uvx` on PATH (ships with [uv](https://docs.astral.sh/uv/)).

```bash
npm install @moorcheh-ai/memanto
```

```ts
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.", type: "preference" });

const { memories } = await memanto.recall({ query: "what does Alex drink?" });
const { answer } = await memanto.answer({ question: "Does Alex drink dairy?" });

await memanto.close();
```

**Constructor options:** `agentId` (required), `apiKey`, `autoCreate` (default `true`), `baseUrl` (use an already-running server instead of spawning one), `port`, `host` (default `127.0.0.1`), `uvxPath`, `packageSpec` (e.g. `memanto==0.2.10` to pin the server), `healthTimeoutMs` (default 60000), `verbose`.

**Write methods**
```ts
await memanto.remember({ content, type?, title?, confidence?, tags?, source?, provenance? })
await memanto.batchRemember(items[])                        // up to 100
await memanto.extractMemories({ messages, dryRun?, maxMemories?, aiModel? })
await memanto.uploadFile({ path, filename? })               // streamed, not buffered
await memanto.deleteMemory(memoryId)
```

**Read methods**
```ts
await memanto.recall({ query, limit?, minSimilarity?, type? })
await memanto.recallAsOf({ asOf, limit?, type? })
await memanto.recallChangedSince({ since, limit?, type? })
await memanto.recallRecent({ limit?, type? })
await memanto.answer({ question, limit?, threshold?, temperature?, aiModel?, kioskMode? })
```

**Analysis methods**
```ts
await memanto.dailySummary({ date?, outputPath? })
await memanto.generateConflicts({ date? })
await memanto.listConflicts({ date? })
await memanto.resolveConflict({ conflictIndex, action, date?, manualContent?, manualType? })
```

**Lifecycle & diagnostics**
```ts
await memanto.listAgents(); await memanto.getAgent(); await memanto.createAgent({ pattern?, description? })
await memanto.deleteAgent(); await memanto.deactivate(); await memanto.status(); await memanto.close()

import { doctor } from "@moorcheh-ai/memanto";
const result = await doctor();   // checks uvx availability, config, connectivity
```

The npm package version tracks the matching PyPI release. Full reference: https://docs.memanto.ai/sdk/typescript

---

## Python / REST usage

MEMANTO exposes a REST API — any HTTP client works. Example with `requests`:

```python
import requests

BASE = "http://127.0.0.1:8000"
AGENT_ID = "my-agent"

# Start session (loopback callers need no management credential;
# from a remote host add: headers={"Authorization": f"Bearer {MANAGEMENT_KEY}"})
resp = requests.post(f"{BASE}/api/v2/agents/{AGENT_ID}/activate")
SESSION_TOKEN = resp.json().get("session_token")
SESSION_HEADERS = {"X-Session-Token": SESSION_TOKEN}

# Store a memory
requests.post(
  f"{BASE}/api/v2/agents/{AGENT_ID}/remember",
  headers=SESSION_HEADERS,
  json={
    "content": "User is building a fintech app in TypeScript",
    "type": "context",
  },
)

# Recall memories
resp = requests.post(f"{BASE}/api/v2/agents/{AGENT_ID}/recall", headers=SESSION_HEADERS, json={
    "query": "what is the user building",
    "limit": 5
})
memories = resp.json().get("memories", [])

# Newest-first, no query
resp = requests.post(f"{BASE}/api/v2/agents/{AGENT_ID}/recall/recent", headers=SESSION_HEADERS, json={
    "limit": 10
})

# Get a RAG-powered answer
resp = requests.post(f"{BASE}/api/v2/agents/{AGENT_ID}/answer", headers=SESSION_HEADERS, json={
    "question": "What tech stack is the user using?"
})
print(resp.json().get("answer"))
```

---

## OKF (Open Knowledge Format)

[OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) is Google Cloud's open, vendor-neutral v0.1 spec for knowledge stored as a directory of markdown files with YAML frontmatter — one concept per file. MEMANTO uses OKF as its **portable, at-rest interchange format**: Moorcheh remains 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.

```bash
memanto memory export --okf                 # export an OKF bundle (grouped by memory type)
memanto memory export --okf --split type    # layout: auto (default) | file | type
memanto memory sync --okf -p ./my-project   # drop a browsable bundle into <project>/okf
memanto migrate okf ./bundle                # import a bundle back into an agent
memanto migrate okf ./bundle --dry-run      # preview the mapping without writing
```

Example OKF document (only `type` is required):
```markdown
---
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.
```

MEMANTO-only fields ride along in the namespaced `x_memanto` block, so MEMANTO → OKF → MEMANTO round-trips are lossless (confidence, provenance, source, status, id preserved); other OKF consumers simply ignore the unknown keys. Importing also preserves unmapped fields in a `[Supporting data]` footer and auto-classifies OKF's free-form `type`. The Web UI's Migrate tab supports OKF import alongside Mem0/Letta/Supermemory.

Docs: https://docs.memanto.ai/integrations/okf

---

## On-Prem

Run the full MEMANTO stack on your own hardware with no API key required. The on-prem deployment uses a local Moorcheh server in Docker (started by `moorcheh up`) with Ollama for zero-cost local embeddings and LLM inference.

### Requirements
- Docker Engine 20.10+ or Docker Desktop 4.0+
- Python 3.10+
- 4 CPU cores, 8 GB RAM minimum (16 GB+ recommended)
- 10 GB free disk (30 GB+ with Ollama models)

### Quickstart
```bash
pip install memanto
memanto                          # choose On-Prem at the backend prompt
# Wizard: picks providers (Ollama/OpenAI/Cohere), starts Docker, pulls models
memanto agent create my-agent
memanto agent activate my-agent
memanto remember "Hello world" --type fact
memanto recall "Hello"
```

The wizard handles: Docker verification, installing `moorcheh-client`, configuring embedding + LLM providers, starting the Moorcheh container, and pulling Ollama models.

### Configuration
Two backends are supported, switchable via `memanto config backend`:

| Backend | Command | Auth |
|---------|---------|------|
| Cloud (default) | `memanto config backend cloud` | MOORCHEH_API_KEY |
| On-Prem | `memanto config backend on-prem` | None (local Docker) |

Key env vars for on-prem: `MEMANTO_BACKEND=on-prem`, `MOORCHEH_ONPREM_URL=http://localhost:8080`, `MOORCHEH_ONPREM_TIMEOUT=300`. Each backend keeps its own isolated config and agent state, so switching does not lose anything.

### Deployment options
- Docker: `docker pull moorcheh/memanto:latest`
- Docker Compose: ships with `docker-compose.yml`
- systemd: run as a Linux service
- Kubernetes: full Deployment + Service + HPA manifests
- Cloud platforms: AWS ECS, Google Cloud Run, Azure Container Instances, DigitalOcean, Fly.io

### What's included on-prem
All 13 memory types, `remember`/`recall`/`answer`, temporal queries, batch ingestion, conversation extraction, file upload, sessions, agent management, daily summaries, conflict detection, OKF export/import, web UI, integrations (`memanto connect`), and the full REST API — all working identically to cloud mode.

---

## MemantoClaw

MemantoClaw is an open-source reference stack for running [OpenClaw](https://openclaw.ai) always-on assistants safely, with long-term memory built in. It combines three technologies:

- **Autonomy — OpenClaw**: the open-source agent framework running inside the sandbox.
- **Security — [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell)**: a hardened sandbox that restricts network egress, filesystem, and process behavior, and handles inference routing.
- **Memory — MEMANTO on Moorcheh**: long-term memory that carries context across sessions.

**Architecture**: the host manages credentials and provider routing to memory services; the sandbox runs OpenClaw under OpenShell policy enforcement. The agent receives only the context it needs per task — never raw host credentials or memory databases. MemantoClaw drives OpenShell's APIs and CLI to create and configure that sandbox, and injects the Memanto memory bridge automatically.

**Prerequisites**: Docker, a valid `MOORCHEH_API_KEY`, and WSL 2 on Windows.

**Install**
```bash
curl -fsSL https://raw.githubusercontent.com/moorcheh-ai/memantoclaw/refs/heads/main/install.sh | bash
memantoclaw onboard    # interactive wizard: gateway, providers, image build, sandbox launch
```

**Commands**
```bash
memantoclaw onboard [--non-interactive] [--resume] [--from <Dockerfile>]
memantoclaw list                        # registered sandboxes with model, provider, policy presets
memantoclaw <name> connect              # drop into the sandbox shell (then run `openclaw tui`)
memantoclaw <name> status               # sandbox status, health, inference configuration
memantoclaw <name> logs [--follow]
memantoclaw <name> destroy              # stop the container and delete the sandbox
memantoclaw <name> policy-add [--dry-run]   # add a policy preset (e.g. github, npm)
memantoclaw <name> policy-list
memantoclaw start | stop                # host auxiliary services (e.g. cloudflared tunnel)
memantoclaw debug                       # collect diagnostics into a tarball
memantoclaw credentials list | reset <KEY>
memantoclaw uninstall [--yes] [--keep-openshell] [--delete-models]
```

Use `memantoclaw onboard` (not raw `openshell` commands) for creating or recreating the gateway and sandbox. Deployment to remote GPU instances (Brev, AWS) is supported: provision the VM, run the installer on that host, then onboard.

- GitHub: https://github.com/moorcheh-ai/memantoclaw
- Docs: https://docs.memanto.ai/memantoclaw/overview
- Open-source, self-hostable, MIT licensed

---

## Performance Benchmarks

| Benchmark | MEMANTO Score | Notes |
|-----------|--------------|-------|
| LongMemEval | 89.8% | Long-horizon memory evaluation |
| LoCoMo | 87.1% | Long-context memory benchmark |

These scores reflect retrieval accuracy for semantic memory recall over long conversation histories, and outperform Mem0, Zep, and Letta. Retrieval is single-query — no multi-stage pipelines, graph schema, or rerankers. Public datasets: https://huggingface.co/moorcheh

**Paper**: *Memanto: Typed Semantic Memory with Information-Theoretic Retrieval for Long-Horizon Agents*, Abtahi, Rahnema, Patel, Patel, Fekri, Khani (2026). arXiv:2604.22085 — https://arxiv.org/abs/2604.22085

---

## Community & Links

- **Docs**: https://docs.memanto.ai
- **Changelog**: https://docs.memanto.ai/changelog
- **GitHub**: https://github.com/moorcheh-ai/memanto
- **Discord**: https://memanto.ai/discord
- **X / Twitter**: https://x.com/moorcheh_ai
- **YouTube**: https://www.youtube.com/@moorchehai/videos
- **Blog**: https://memanto.ai/blog
- **Research**: https://memanto.ai/research
- **Evaluation**: https://memanto.ai/evaluation
- **Moorcheh Console** (API keys): https://console.moorcheh.ai/api-keys
- **PyPI**: https://pypi.org/project/memanto/ · https://pypi.org/project/memanto-mcp/
- **npm**: https://www.npmjs.com/package/@moorcheh-ai/memanto
- **Email**: support@moorcheh.ai
- **Contributing**: https://github.com/moorcheh-ai/memanto/blob/main/CONTRIBUTING.md
- **Security**: https://github.com/moorcheh-ai/memanto/blob/main/SECURITY.md