Skip to content
Galdocompany memory

Docs · API reference

Galdo API documentation

Everything you need to build with Galdo — from a five-minute quickstart to the full REST reference and integrations.

Base URL: https://api.mnemohq.com. Authenticate with `Authorization: Bearer <api key>`; the key comes from the dashboard at https://app.mnemohq.com and identifies your workspace, so no workspace header is needed. The machine-readable contract is published at https://getgaldo.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). From Python or any other language, call the REST API directly; the Python samples use httpx because the getmnemo package on PyPI (0.1.x) predates the current request shapes. CLI: `npm install -g getmnemo-cli`. MCP server: `npx -y getmnemo-mcp`.
  • Authentication — a Bearer API key, bound to one workspace. The legacy x-workspace-id header is optional and ignored for API keys. Rotate keys from the dashboard at any time; old keys keep working until you revoke them.
  • OAuth 2.0 and MCP — a live OAuth 2.0 authorization server for MCP clients (issuer https://api.mnemohq.com/v1/mcp/oauth, RFC 8414 metadata at https://api.mnemohq.com/.well-known/oauth-authorization-server). authorization_code and refresh_token grants, PKCE S256 required, dynamic client registration (RFC 7591). API keys remain the primary path for direct REST calls; OAuth is what MCP clients such as Claude and Cowork use to connect to the hosted MCP automatically.
  • Single sign-on and SCIM — dashboard sign-in on Team and Enterprise through Okta, Microsoft Entra ID, and other SAML 2.0 or OpenID Connect providers, limited to verified email domains. Enterprise adds Require SSO and SCIM 2.0 provisioning at https://api.mnemohq.com/v1/scim/v2 (Users, plus viewer, developer and admin groups that set roles; PATCH and filters; no bulk). Set up under Settings → SSO / SAML.

Core concepts

  • Memory and Document — Galdo 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 deployments can bring their own model.

REST API

  • POST /v1/memories — write one or more atomic memories in a batch: an `items[]` array plus a scope. 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. Send `q` plus a scope; Galdo runs the seven retrieval signals in parallel, fuses with intent-aware RRF, and answers with ranked `results`. `limit` is capped at 50; typical use is 5 to 10. Each result's `score` is a fused rank score: it orders results within one response and is not a 0–1 confidence.
  • POST /v1/profile — a prompt-ready summary of what Galdo knows about a scope: static facts, preferences, recent topics.
  • Errors and rate limits — `{ statusCode, message, error?, code? }` bodies; an over-quota write is a 403 whose message starts `Quota exceeded for`. Responses carry RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers for the per-minute request window, whose 429 adds Retry-After. The per-key, per-second limit answers 429 with `{ statusCode, error: { code: "RATE_LIMIT_EXCEEDED", message, details } }` and no Retry-After.

Versioning and deprecation

The Galdo 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://getgaldo.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 — wraps an Anthropic client with one memory tool (search and add) and runs the tool-use loop, with prompt caching and optional extended thinking.
  • getmnemo-vercel-ai — two drop-in tools, memorySearch and memoryAdd, for streamText and generateText. Supports AI SDK 4.x (peer ai ^4.0.0).
  • getmnemo-mastra — a Galdo-backed memory for Mastra agents: rememberMessage() persists each turn, remember() recalls context before generation. Supports Mastra 0.4.x (peer @mastra/core ^0.4.0).
  • getmnemo-mcp — exposes memory_search, memory_add, memory_get, memory_update, memory_delete, and memory_list as MCP tools. Hosted MCP endpoint: https://mcp.mnemohq.com/mcp — a remote MCP server over Streamable HTTP transport, OAuth-protected.
  • getmnemo-langgraph — a LangGraph JS store (BaseStore) plus remember / recall tools.

Self-hosting

  • Self-hosted deployment is available on Enterprise: a single-tenant install on your own Linux servers (Docker Compose), with your own AI provider keys or a local model, scripted backups, restores and upgrades, and an offline mode for air-gapped servers. The MCP server, connectors and email delivery are not in the self-hosted release yet. Contact sales@mnemohq.com to set up a pilot. Every other plan runs on the hosted API at api.mnemohq.com.

Explore Galdo