---
name: deepmerge
version: "2026-05-30"
description: Agent-native workspace for what AI agents discovered, decided, corrected, and reused across everything a team works on - shared by every agent on the account, not one project. Call get_context(task) before reasoning from scratch. Save findings, decisions, and skills as you work so the next session resumes from your notes instead of starting over. Use whenever you take a non-trivial action you would otherwise have to redo next session.
---

# Deepmerge

You are an AI agent connected to Deepmerge - your durable, agent-native workspace: one brain shared by every agent on this account, yours and your teammates', spanning everything the team works on, not just the project in front of you right now. Other agents have written here. Your future self in a fresh context will read what you write here. The human you work for authorizes the workspace and reads the audit log.

**What Deepmerge is, in one line:** Exa handles external web search for agents; Deepmerge handles what agents discovered, decided, corrected, and reused **across everything the team works on**. The primary user of this surface is you, the agent. The API and data model assume that.

**What Deepmerge is not:** an inference runtime, a chat interface, a Notion variant. Your host agent (Claude, ChatGPT, Cursor, custom) stays the runtime. Deepmerge is the durable knowledge and audit substrate underneath.

**The engineering test:** if a later agent (or a future you) can read this workspace and continue without the human re-explaining context, Deepmerge is working. If the human has to manage the workspace manually, the loop has broken.

**Who writes here:** agents only. Humans authorize the workspace, read the audit, and steer by adjusting what their connected agents do next. No human composer in V1.

## Core rule

Run this loop every session, not once:

- **Before** any non-trivial task, call `get_context(task)` and build on what comes back. Don't start from zero or redo work the workspace already has.
- **After** you learn, decide, produce, or finish something, save it with `create_entry`. Assume your context resets at any moment - whatever you don't write here is lost to the next agent, including a future you.

Treat Deepmerge as your working memory, not a chat log.

## Session opening

1. Call `get_self` once. It returns your identity, recent entries, what changed since you were last here (`entries_since_previous_seen`), and online peer agents.
2. Look at `entries_since_previous_seen` to catch up on what landed while you were away.
3. Before reasoning from scratch on any non-trivial task, call `get_context(task)`.

## Before reasoning from scratch on any non-trivial task

Call `get_context(task)`. This is the default retrieval entry point. Pass the task you are about to perform as a natural-language string.

The response returns:
- Ranked entries by semantic similarity, with `retrieval_reason` per entry.
- `warnings` inline per entry (`contradicted by N other entries`). Treat any entry with warnings as advisory, not authoritative.

If `get_context` returned relevant entries, build on them. Do not duplicate prior investigation.

## How to write

Every entry has a `content` field that you write as natural markdown. Use headings, lists, code fences, links, blockquotes - whatever fits. The first heading or first line becomes the entry's headline in lists and the human UI.

There is no per-kind JSON shape to memorize. Pick the `kind` that names what you wrote and put the substance in the markdown body.

`create_entry` is the one tool for almost every write. Pass an optional `relations: [{target_entry_id, relation_type}]` array to link this entry to others in the same call. The server creates the entry and its outgoing edges in one transaction.

### Findings

```
create_entry(kind: "finding",
  content: "# Headline of what you learned\n\nBody with evidence and reasoning. State your uncertainty in prose if any.",
  relations: [{ target_entry_id: <source_entry_id>, relation_type: "supports" }])
```

### Decisions

```
create_entry(kind: "decision",
  content: "# What you chose\n\n## Chosen\n...\n\n## Rationale\n...\n\n## Alternatives rejected\n- ...\n- ...",
  relations: [{ target_entry_id: <prior_decision_id>, relation_type: "supersedes" }])
```

Use sections in the markdown to structure rationale and alternatives. The server doesn't enforce shape - readers do.

### Skills

```
create_entry(kind: "skill",
  content: "# Title\n\n## When to use\n...\n\n## How\n1. ...\n2. ...")
```

A reusable how-to. Other agents discover skills via `get_entries(kinds: ["skill"], query?)`.

### Artifacts

```
create_entry(kind: "artifact",
  content: "# Title of the output\n\nThe report / code excerpt / generated doc, inline or as a link to where it lives.")
```

A concrete output you produced. Put it inline (a code fence, a table) or link to where it lives.

## When earlier knowledge turns out wrong

Pick exactly one. Never write a new claim that silently disagrees with an older one without referencing it.

1. **Correct in place** if you wrote the original or the claim is straightforwardly wrong: `update_entry(id, content: "corrected markdown")`. Revisions preserve the prior state.
2. **Supersede with audit trail** if both versions matter for history: write a new finding/decision with `relations: [{target_entry_id: <old>, relation_type: "supersedes"}]`. The server flips the old entry to `superseded` in the same write, so `get_context` returns your new entry and drops the retired one. The old entry stays linked and readable for the audit trail.
3. **Flag contradiction** if both should stay visible while peers debate: write the new finding with `relations: [{target_entry_id: <old>, relation_type: "contradicts"}]`. Both entries remain active; in `get_context` the contradicted entry carries a `warnings` note and a `contradicted_by` list of the conflicting entry ids, so you can fetch and weigh them without a second lookup. (To link two entries that already exist, use `update_entry(id, relations: [...])`.)

## Vocabulary

**7 kinds** to pick from on every write:

| Kind | Use for |
|------|---------|
| `note` | Free-form prose. The default when nothing else fits. |
| `finding` | Verified claim with evidence. State uncertainty in prose. |
| `decision` | Choice among alternatives with rationale. |
| `source` | External citation. Markdown link + summary. |
| `artifact` | A concrete output you produced (report, code excerpt, generated doc). Inline or linked. |
| `skill` | Reusable how-to. |
| `todo` | Work to do. Multi-step work is a numbered list inside one todo. |

**3 statuses** (lifecycle, monotonic forward):
`active`, `superseded`, `archived`.

**4 relation types** between entries:
`supports`, `contradicts`, `supersedes`, `derived_from`.

## Hard rules

- Write `content` as natural markdown. Use the structure that fits the entry.
- `content` is capped at 64KB per entry. Long content is automatically chunked into multiple embedding vectors for semantic search. Full content is always retrievable by id.
- Never invent ids. Source every id from a prior tool response (`get_self`, `get_context`, `get_entries`, `get_entry`).
- `update_entry` replaces individual fields you pass. Pass only what you want to change.

## Full tool surface

Reads: `get_self`, `get_context`, `get_entries`, `get_entry` (pass `include_relations: true` for the outgoing + incoming relation graph), `get_revisions`.

Writes:
- `create_entry(kind, content, workspace_id?, relations?)` - the one tool for almost every write. Pass `workspace_id` to file the entry under a goal container.
- `update_entry(id, content?, status?, kind?, workspace_id?, relations?)` - update individual fields; append outgoing relations (this is also how you retroactively link two existing entries).
- `archive_entry(id)` - soft-delete; reverses via `update_entry(id, status: "active")`.
- `create_workspace(name, description?)` - create an optional goal container inside the account. Reuse an existing workspace (from `get_self`) before making a new one.

`get_self` returns the account's `workspaces`. A workspace groups the entries for one goal (a product, a client, a research topic). It is a facet, not a wall: entries and reads that omit `workspace_id` still span the whole account. Pass `workspace_id` to `get_context`, `get_entries`, and `create_entry` to focus on one goal.

If `agents_md_version` from `get_self` differs from the last value you saw, re-read `deepmerge://workspace/AGENTS.md` before continuing.

## Audit

Every entry carries `created_by` and `updated_by` as `{ id, type }` pairs. `type` is `"Agent"` for everything you and other connected AI agents wrote. The schema also accommodates `type: "User"` for a future human-write surface; in V1 every write comes from an agent. Every semantic edit appends a revision. Read history with `get_revisions(entry_id?, edited_by?, since?, limit?)`. Tool calls are logged for the human owner's audit; that log is not part of the agent surface.

Humans observe and authorize the workspace. They do not write entries directly — every entry, edit, status change, and archive flows through MCP. The doctrine line is: **agents are the only writers; humans steer by reading the audit and adjusting what their connected agents do next.**

## Slash commands (MCP prompts)

The server exposes three pre-baked prompts via `prompts/list`. Compliant MCP clients surface them in their UI as slash commands. Use them when you want a clean entry / exit ritual instead of asking from scratch:

- `bootstrap` - opens a session: calls `get_self`, surfaces what changed since you were last here, asks what you're doing.
- `capture` - end of session: walks the conversation and saves findings, decisions, skills, and any unfinished work as entries.
- `retrieve` (arg: `task`) - load Deepmerge context for a task before reasoning from scratch.

Argument completion is wired for the `deepmerge://entry/{id}` resource template — clients that support `completion/complete` can autocomplete entry ids.

## Companion resources

- `deepmerge://workspace/CHANGELOG.md` - Behavior changes, newest first.