MarkDB

Getting started

Create an agent, mint a key, route a request through MarkDB, and recall it with the memory tools.

This guide takes you from an empty account to an agent that captures its work and can recall it later -- in about five minutes. You'll create an agent in the dashboard, mint a key, route a request through the proxy, and then use the memory tools to retrieve what happened.

1. Create an app and an agent

Sign in to the dashboard. MarkDB scopes everything to a tenant -> app -> agent hierarchy (see Operating model):

  • App -- a project or environment, e.g. prod or my-cli.
  • Agent -- a single actor inside that app whose work you want to capture.

Go to Apps, create an app, then click New agent. You can give the agent an external id (any string that's meaningful to you) or leave it blank to auto-generate one. Creating an agent drops you on the Connect page with that agent preselected.

2. Mint an API key

On Connect (or under Settings -> API keys), pick the app and agent, give the key a name, and mint it. You'll get a key that looks like:

mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Copy it now

The plaintext is shown exactly once. The key is bound to that specific (tenant, app, agent) triple and carries read + write scope. Revoke it anytime from Settings -> API keys -- revocation is immediate.

3. Add a model-provider key

MarkDB calls the model provider on your behalf, so it needs your provider credentials. Under Settings -> LLM keys, add a key for the provider you want to use (Anthropic, OpenAI, or Gemini). Keys are encrypted at rest, and the proxy resolves the right one per request based on the model name.

4. Point a client at the proxy

The proxy is OpenAI-compatible and also speaks the OpenAI Responses API and the Anthropic Messages API. The base URL is:

https://proxy.markdb.cloud/v1

Authenticate with your mk_live_... key as a bearer token. A raw curl smoke test:

curl https://proxy.markdb.cloud/v1/chat/completions \
  -H "Authorization: Bearer mk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [{"role": "user", "content": "Say hello in three words."}]
  }'

You get a normal chat completion back -- and the exchange is now captured in MarkDB. Open the Work log to watch the session and turns appear, and within seconds the enrichment worker starts producing summaries.

For a real coding agent, point your tool at the same base URL instead of curl:

5. Retrieve context with the memory tools

Capturing is half the loop; the other half is recall. MarkDB exposes its memory through an MCP server so your agent can look up what it did before, mid-task. Add MarkDB as an MCP server in any MCP-aware client -- for Cursor, that's .cursor/mcp.json:

{
  "mcpServers": {
    "markdb": {
      "url": "https://mcp.markdb.cloud/mcp",
      "headers": { "Authorization": "Bearer mk_live_xxx" }
    }
  }
}

Your agent now has memory tools available. The primary one is memory_search, which runs hybrid search over your summaries and returns scored results inline:

// memory_search
{
  "query": "how did we fix the postgres shm exhaustion",
  "mode": "hybrid",   // text | vector | hybrid (default)
  "limit": 5
}

Each result carries summary_text, key_facts, and a page_id. That's usually enough to answer -- but when you need to go deeper, follow the page_id with memory_get_detail to read child summaries and citations, then memory_get or memory_list_events to pull the exact raw events. See MCP tools for the full reference and the drill-down workflow.

Next steps

Introduction

MarkDB is the memory database for AI agents - capture, search, and summarize everything your agents do behind one OpenAI-compatible proxy.

Memory model

How MarkDB turns raw agent traffic into structured, searchable memory.

On this page

1. Create an app and an agent2. Mint an API key3. Add a model-provider key4. Point a client at the proxy5. Retrieve context with the memory toolsNext steps