Operating model
How MarkDB's identity model and the capture/recall loop fit together.
MarkDB has two jobs: capture everything an agent does, and let the agent recall it later. This page explains the identity model those jobs hang off and the two data paths that move work in and out of memory.
Identity model
Everything in MarkDB is scoped to a three-level hierarchy, and an API key binds to a specific point in it.
| Level | What it is |
|---|---|
| Tenant | Your account / workspace. Billing, members, and provider keys live here. |
| App | A project or environment inside a tenant (e.g. prod, my-cli). |
| Agent | A single actor inside an app whose activity you capture. |
An API key (mk_live_...) is minted against one (tenant, app, agent)
triple and carries read and/or write scope. Every request authenticated with
that key is attributed to that agent, so memory stays cleanly partitioned: two
agents in the same app never see each other's raw turns unless you explicitly
share via broadcasts.
tenant
└─ app (slug: "prod")
└─ agent (external_agent_id: "reviewer-bot")
└─ api key mk_live_… scopes: [read, write]You manage all three from the dashboard: Apps to create apps and agents, Connect or Settings -> API keys to mint keys, and Settings -> LLM keys to add the provider credentials MarkDB dispatches with.
The write path: capture
When your agent talks to a model through the proxy, MarkDB forwards the request and records it in the same pass:
agent ──▶ proxy ──▶ model provider (Anthropic / OpenAI / Gemini)
│
├─▶ mirror the exchange ─▶ memory store (Postgres)
│
└─ background ─▶ enrichment worker ─▶ summaries ─▶ search index- Dispatch. The proxy picks the provider from the model name and calls it with your tenant's credentials. Your agent gets a normal model response.
- Mirror. The same exchange is written as events under the active session, de-duplicated by content hash so replayed history isn't stored twice.
- Enrich + index. A worker summarizes turns, sessions, and chats, then embeds the summaries into the hybrid search index -- all in the background, off your request's critical path.
The proxy is the only thing your agent has to change: point it at
https://proxy.markdb.cloud/v1 and capture happens automatically.
The read path: recall
Recall flows through the MCP server, the agent-facing side of memory:
agent ──▶ MCP server (memory tools) ──▶ memory store
memory_search → memory_get_detail → memory_get / memory_list_eventsThe agent calls memory_search to find relevant summaries, drills
down with memory_get_detail, and pulls exact raw events with memory_get or
memory_list_events when it needs precise wording. Search prefers compact
summaries so recall stays cheap, and falls back to raw turns only when detail is
required.
Humans use the same store through the dashboard Work log; agents use the MCP tools. Both read the memory the write path built.
Endpoints
MarkDB exposes four hosts, all authenticated with the same mk_live_... bearer
key:
| Host | Purpose |
|---|---|
proxy.markdb.cloud/v1 | OpenAI-compatible LLM proxy (capture). Chat Completions, Responses, Messages, Embeddings. |
mcp.markdb.cloud/mcp | MCP server (recall). The memory tools. |
api.markdb.cloud | Dashboard + REST API backend. |
app.markdb.cloud | The dashboard web UI. |
One key, both directions
The same key authenticates the proxy and the MCP server. Give your agent the proxy URL to capture its work and the MCP URL to recall it -- that's the whole loop.