Operating model

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.

An API key (mk_live_...) is minted against one (account, workspace, 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 workspace never see each other's raw turns unless you explicitly share via broadcasts.

account (tenant)
└─ workspace  (slug: "mark-db")
   └─ agent  (external_agent_id: "default")
      └─ api key  mk_live_…   scopes: [read, write]

Create one workspace per repo (or project directory) and configure that workspace's key in the tools you run there. Capture and recall then stay scoped to the repo you're working in, which is exactly how coding agents like Cursor, Claude Code and Codex anchor their work.

You manage all three from the dashboard:

• Workspaces creates workspaces and agents.
• Connect or Settings -> API keys mints keys.
• Settings -> LLM keys adds 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

1. Dispatch. The proxy picks the provider from the model name and calls it with your account's credentials. Your agent gets a normal model response.
2. Mirror. The same exchange is written as events under the active session, de-duplicated by content hash so replayed history isn't stored twice.
3. 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_events

The 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. The two agent-facing hosts authenticate with your mk_live_... key; the two human-facing hosts use your signed-in dashboard session.