Getting started

This guide takes you from an empty account to a coding agent that captures its work and can recall it later, in about five minutes. You will create a workspace and agent in the dashboard, mint a key, point your agent's harness at MarkDB, and then use the memory tools to retrieve what happened.

Throughout, "harness" means the tool your agent runs in: Cursor, Claude Code, the Codex CLI, or any OpenAI-compatible client. You configure the harness in two places, and both use the same key: the proxy for capture and the MCP server for recall.

1. Create a workspace and an agent

Sign in to the dashboard. MarkDB scopes everything to an account -> workspace -> agent hierarchy (see Operating model):

• Workspace is where an agent works: usually one repo or project directory, e.g. mark-db.
• Agent is a single actor inside that workspace whose work you want to capture.

Go to Workspaces and create one per repo you want memory for. Each new workspace comes with a default agent, so you can go straight to minting a key.

2. Mint an API key

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

mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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. Wire up your harness

Pick your harness below. Each tab sets up capture (route the agent's model calls through the proxy) and recall (add MarkDB's memory tools over MCP). Keep the key out of version control: gitignore the config file, or reference an environment variable instead of pasting the plaintext.

// .cursor/mcp.json
{
  "mcpServers": {
    "markdb": {
      "url": "https://mcp.markdb.cloud/mcp",
      "headers": { "Authorization": "Bearer ${env:MARKDB_API_KEY}" }
    }
  }
}

Smoke-test the proxy

If you just want to confirm capture works before configuring a harness, a raw curl does it:

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

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

5. Retrieve context with the memory tools

Capturing is half the loop; the other half is recall. Once the MCP server is configured for your harness, your agent 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 is usually enough to answer. 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

• Operating model explains how capture and recall fit together.
• Concepts covers how MarkDB structures memory.
• MCP tools is the complete memory tool reference.