# Mnemo API documentation

> Mnemo API documentation: quickstart, REST API reference, SDK guide, integrations, versioning and deprecation policy, and self-hosting. Every sample verified against the shipped code.

Canonical URL: https://mnemohq.com/docs

Everything you need to build with Mnemo Memory — from a five-minute quickstart to a self-hosted, air-gapped install. Every sample on this page was verified against the shipped code.

Base URL: https://api.mnemohq.com. Authenticate with `Authorization: Bearer <api key>` and `x-workspace-id: <workspace>`; both come from the dashboard at https://app.mnemohq.com. The machine-readable contract is published at https://mnemohq.com/openapi.json.

## Getting started

- Quickstart (5 minutes) — store and retrieve your first memory with no infrastructure. Free tier includes 1K ingestion units per month.
- Installation — `npm install getmnemo` (TypeScript, zero runtime dependencies, Node 18+/Bun/Deno/browsers/Workers) or `pip install getmnemo` (Python). CLI: `npm install -g getmnemo-cli`. MCP server: `npx -y getmnemo-mcp`.
- Authentication — Bearer API key plus a workspace header. Rotate keys from the dashboard at any time; old keys keep working until you revoke them.

## Core concepts

- Memory and Document — Mnemo decomposes each Document into atomic Memories with provenance preserved back to the source.
- Container and Scope — containers isolate data and queries; a search inside one container never returns another container's memories.
- Atomic fact extraction — each Document becomes atomic facts carrying the original sentence, an embedding, an entity list, a timestamp, and a confidence score.
- Embedding — text-embedding-3-small (1536-dim) by default, stored in Postgres with pgvector and an HNSW index (ef_construction=200). Enterprise and self-hosted deployments can bring their own model.

## REST API

- POST /v1/memories — write one or more atomic memories in a batch. Per-item idempotencyKey makes retries safe; hard cap of 4,000 characters per item.
- POST /v1/documents — async raw-content ingestion up to 500 KB, running chunking, atomic fact extraction, embedding, and indexing. Returns a job id to poll at /v1/jobs/:id.
- POST /v1/media/youtube — turn a public YouTube video into searchable, timestamped memory.
- POST /v1/search — unified retrieval. Runs the seven retrieval signals in parallel, fuses with intent-aware RRF, and returns ranked hits with citations. `limit` is capped at 50; typical use is 5 to 10.
- POST /v1/profile — a prompt-ready summary of what Mnemo knows about a scope: static facts, preferences, recent topics.
- Errors and rate limits — uniform `{ error: { code, message, details? } }` bodies. Rate-limit responses include Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

## Versioning and deprecation

The Mnemo API is versioned in the URL path. Every endpoint lives under /v1/, and v1 is the only version currently served. A request never changes meaning because of a header, a date, or an account setting — the path is the contract.

Additive changes ship inside v1 without notice: new endpoints, new optional request fields, and new fields in a response object. Clients must ignore unknown response fields and must not depend on key order or on the absence of a field.

Breaking changes never ship inside a version. Removing or renaming a field, changing a type, tightening validation on an existing field, or changing the meaning of a status code all require a new version path (/v2/), served alongside /v1/ while both are supported.

Deprecations are announced in the changelog at https://mnemohq.com/changelog at least six months before an endpoint or version is switched off. During that window every affected response carries the RFC 8594 `Deprecation` header and a `Sunset` header giving the exact retirement date, so a client can detect its own obsolescence without a human reading release notes.

Security fixes are the one exception: a change required to close a vulnerability may ship on a shorter timeline, and the changelog entry says so explicitly.

## Integrations

- getmnemo-anthropic — Mnemo as a memory tool inside the Anthropic SDK, with prompt caching and extended thinking wired up.
- getmnemo-vercel-ai — drop-in tools for streamText, generateText, and useChat.
- getmnemo-mastra — implements Mastra's memory provider interface.
- getmnemo-mcp — exposes search / add / update / delete as MCP tools. Hosted MCP endpoint: https://mcp.mnemohq.com/mcp.
- getmnemo-langgraph — graph nodes for recall and store in LangGraph.

## Self-hosting

- Docker Compose — the reference deployment is one docker-compose.yml with the API, Postgres + pgvector, and Redis. A Helm chart is published for Kubernetes. Self-hosting is an Enterprise plan feature.
- Environment variables — the required minimum to boot an Enterprise instance.
- Migrations — schema changes ship as Prisma migrations and run automatically on container start. They are forward-only by design.
- Air-gapped install — MNEMO_AIR_GAPPED=1 runs Mnemo with no outbound internet: local Ollama for inference, email disabled, billing stubbed, licence verified against a bundled public key.

## Explore Mnemo

- [Mnemo API documentation](https://mnemohq.com/docs)
- [Pricing](https://mnemohq.com/pricing)
- [Benchmarks](https://mnemohq.com/benchmarks)
- [Company Brain for Slack](https://mnemohq.com/brain)
- [Ask Mnemo widget](https://mnemohq.com/widget)
- [Data-source connectors](https://mnemohq.com/connectors)
- [Framework integrations](https://mnemohq.com/integrations)
- [Trust and security](https://mnemohq.com/trust)
- [Contact](https://mnemohq.com/contact)
- [llms.txt](https://mnemohq.com/llms.txt)
- [OpenAPI 3.1 specification](https://mnemohq.com/openapi.json)

---

This is the Markdown representation of https://mnemohq.com/docs, served by content negotiation on `Accept: text/markdown`. Machine-readable index: https://mnemohq.com/llms.txt · https://mnemohq.com/openapi.json · https://mnemohq.com/sitemap.xml