Durable memory

By default MarkDB captures every exchange as events and the worker rolls them into summaries. That happens automatically. The durable-memory tools let an agent go further and deliberately shape what persists and what gets pulled back into context.

All of these are write operations: they need a key with write scope, and over MCP they're only present when the server isn't read-only. Each has a REST equivalent.

Objects and pages

The building blocks are objects and pages. An object is a durable, named container; pages are the versioned entries written to it, and the latest page is the object's head. Summaries, promoted notes, and overlays all live as pages on objects. You rarely create these by hand -- the tools below do it for you.

Promote an event

memory_promote (POST /v1/promotions) takes a specific captured event and promotes it into a durable object + page, so an important message survives beyond raw event retention and becomes first-class, retrievable memory.

{
  "event_id": "abc-123",
  "create_object": { "namespace": "notes", "…": "…" },
  "page": { "importance": 0.9, "…": "…" }
}

Pin an object

memory_pin (POST /v1/objects/{id}/pin) marks an object pinned (or unpins it):

{ "object_id": "…", "pinned": true }

Pinned objects are always eligible for context hydration, so critical facts (project conventions, a task's north star) stay in view across sessions instead of aging out.

Overlays

memory_overlay_upsert (POST /v1/overlays) attaches an overlay -- a small summary or importance hint -- at a scope, without mutating the core rollups the enrichment worker produces. Use it to correct or annotate memory ("this decision was reversed") without rewriting history.

Checkpoints

memory_checkpoint (POST /v1/checkpoints) snapshots the state of an object or session; checkpoint_restore (POST /v1/checkpoints/{id}/restore) brings that snapshot back. Use checkpoints to mark a known-good point you can return to.

{
  "target_type": "object",     // object | session
  "target_id": "…",
  "summary_page_id": "…"        // optional
}

Hydrate a working context

memory_hydrate_context (POST /v1/context/hydrate) assembles a ready-to-use context bundle from several sources at once, bounded by a token budget:

This is the one-call way to rebuild "what should I have in mind right now" from pins, recency, explicit picks, and cross-agent broadcasts.