# MCP Tools Reference

Memco exposes eight tools through its MCP interface.

## list_domains

Lists the memory domains available to you and describes each one: what it holds, when to search it, what belongs in it and what does not, and the tag vocabulary and format it uses.

Call before your first search or write of a task, and whenever you are unsure which domain a question or finding belongs to. The slug returned is what `start_session`, `search`, and `create_memory` take as their `domain` argument.

**Parameters:** None.

---

## start_session

Starts a session and returns its ID. A session groups the searches you make while working on one task, so they are recorded as a connected series rather than as unrelated one-off calls.

Pass the session ID to every `search`, `create_memory`, `enrich_memory`, and `share_feedback` call you make for that task. A session stays usable for as long as you keep naming it.

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `domain` | string | yes | The memory domain to operate in. Call `list_domains` for the domains available to you |

**Returns:** A session ID.

```
start_session(domain: "coding")
→ { session_id: "sess_abc123" }
```

---

## search

Searches Memco Shared Memory for existing knowledge before working a problem out from scratch. It holds what your teammates and their agents have already established and recorded.

Call when: you start a task, plan a non-trivial piece of work, meet something unfamiliar, hit a question you cannot answer from what you already know, or are about to reason out something a teammate may already have settled. Search first, then work.

Pass either a `domain` or a `session_id`. Naming a session runs the search in that session's domain and records it alongside the other searches made for the same task. Naming a domain alone starts a session for that one search.

The query uses both keyword and semantic search, and is intended for a single concept per query. If you need varied information, make multiple queries. Results come back most-relevant-first and are bounded; the response says what it left out.

Within one session, a result already returned is not repeated — it comes back as a reference to the `idx` that carried it. Use `get_memory` to turn a reference back into content.

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | A task-based query: a question, statement, or task description. Use markdown formatting for readability |
| `session_id` | string | no | The session to record this search under. Supplies the domain, so `domain` is not needed. Omit to start a new session (requires `domain`) |
| `domain` | string | no | The memory domain to search in. Required unless `session_id` is provided |
| `tags` | array | no | XML tags narrowing subject and context (see [Tag format](#tag-format) below) |

Either `domain` or `session_id` must be provided.

**Usage:**

```
search(
  session_id: "sess_abc123",
  query: "How does the payments service handle retries?",
  tags: ["<tag type=\"language\" name=\"python\" />"]
)
```

---

## get_memory

Fetches the full content of a memory by its `idx`. Call when you hold an `idx` whose content is not in front of you — a search returned the memory as a reference to an earlier result, or another agent passed you the handle.

An insight's `idx` returns the memory holding it. Copy the `idx` exactly as it appeared in the search response — it cannot be constructed by hand.

When a result shows a `ref` instead of content, fetch by the value in its own `idx`, not the value in the `ref`. The `ref` says where the content was originally delivered, not what to ask for.

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `idx` | string | yes | The `idx` from a search result, copied exactly as it appeared |

**Returns:** The full memory content.

**Usage:**

```
get_memory(idx: "memory-abc123-1")
```

---

## create_memory

Saves new knowledge to Memco Shared Memory, where your teammates and their agents will find it. Call when you have learned something non-obvious that would help your team — why something turned out the way it did, how something actually behaves, something that was hard to establish, or a decision and its rationale — or your user has corrected you.

Search first: when a related memory already exists, `enrich_memory` extends it instead of leaving a near-duplicate beside it.

Pass either a `domain` or a `session_id`. Naming the session you have been searching in saves the memory into that session's domain and records it as part of that work. Naming a domain alone saves a standalone memory.

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `content` | string | yes | The knowledge to save. Should be a concise, non-trivial finding that others can learn from. Supports markdown |
| `query` | string | yes | A query describing what someone would search to find this memory — a question or problem statement |
| `title` | string | yes | A short title describing what this memory is about |
| `session_id` | string | no | The session this memory was learned during. Supplies the domain and records the memory as part of that work. Omit to save a standalone memory (requires `domain`) |
| `domain` | string | no | The memory domain to save into. Required unless `session_id` is provided |
| `source` | string | no | `"user"` for human-corrected information, `"agent"` for self-discovered insights without human correction |
| `tags` | array | no | XML tags describing subject and context (see [Tag format](#tag-format) below) |

Either `domain` or `session_id` must be provided.

**Returns:** The created memory, including an operation ID that can be passed to `revert_memory` if needed.

**Usage:**

```
create_memory(
  session_id: "sess_abc123",
  title: "Payments service requires idempotency keys",
  query: "How to avoid duplicate transactions in the payments service?",
  content: "The payments service requires idempotency keys on all POST requests. Without them, retries can create duplicate transactions.",
  source: "agent",
  tags: ["<tag type=\"language\" name=\"python\" />"]
)
```

---

## enrich_memory

Adds information to an existing memory, so your finding lands beside the one it belongs to rather than in a separate memory that competes with it.

Call when a search returned a memory close to what you learned but incomplete, out of date, or missing the approach you took. Use `create_memory` instead when nothing returned covers the subject at all.

Set `memory_idx` to the memory you want to extend (from the search results), or `"new"` to add a standalone addition. Keep an addition concise and say only what is not already there. The addition lands in the domain the search session ran in.

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `content` | string | yes | The knowledge to add. Use markdown formatting. Say only what is not already there |
| `memory_idx` | string | yes | The `memory_idx` from a search result, or `"new"` to add a standalone addition |
| `session_id` | string | yes | The session ID from a previous search |
| `title` | string | yes | A short title describing what you learned |
| `source` | string | no | `"user"` for human-corrected information, `"agent"` for self-discovered insights without human correction |
| `sources` | array | no | Memory indices from Memco that proved helpful in reaching this insight (up to 20) |
| `tags` | array | no | XML tags describing subject and context (see [Tag format](#tag-format) below) |

**Returns:** The updated memory, including an operation ID that can be passed to `revert_memory` if needed.

**Usage:**

```
enrich_memory(
  session_id: "sess_abc123",
  memory_idx: "mem_xyz789",
  title: "Idempotency key format requirement",
  content: "The idempotency key must be a UUID v4. The service rejects other formats with a 422 response."
)
```

---

## share_feedback

Rates the relevance and correctness of search results. Only the searching agent can tell whether a result answered the query, and these ratings shape which results are shown next.

Call once per search, after reading the results, while the session ID is still to hand.

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `session_id` | string | yes | The session ID from the search being rated |
| `feedback` | array | yes | A list of feedback entries in XML format (up to 10 per call) |

Each feedback entry is an XML tag:

```
<feedback idx="TYPE-IDX" relevant="true|false" correct="true|false">optional comment</feedback>
```

The `idx` is copied exactly as it appears in the search response — it cannot be constructed by hand. Set `relevant` to `true` if the result was a good match for the query, and `correct` to `true` if the content was accurate.

Use an insight's `idx` for a specific insight, or a memory's own `idx` to apply feedback to every insight under it.

**Usage:**

```
share_feedback(
  session_id: "sess_abc123",
  feedback: [
    "<feedback idx='insight-1' relevant='true' correct='true'>Exactly what I needed</feedback>",
    "<feedback idx='insight-2' relevant='false' correct='false' />"
  ]
)
```

---

## revert_memory

Undoes a memory you just wrote — wrong content, wrong domain, or something that should not have been shared.

Your entry is always removed. The memory it belongs to is removed with it only when your entry was the last one in it — so reverting a `create_memory` (or an `enrich_memory` sent with `memory_idx` `"new"`) removes that memory too, while reverting an addition to a memory that holds other entries leaves the memory in place.

You can only revert your own writes, and only within 2 days.

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `op_id` | string | yes | The operation ID returned by `create_memory` or `enrich_memory` |

**Usage:**

```
revert_memory(op_id: "create-hpc08-1")
```

---

## Tag format

Tags use XML format with a `type`, `name`, and optional `version`:

```
<tag type="language" name="python" version="3.11" />
<tag type="framework" name="fastapi" />
<tag type="repository" name="payments-service" />
```

The tag types available and their semantics are domain-specific. Call `list_domains` to see which tag types each domain uses and which of them accept a version. Supply as many tags as you can determine for the best results.

Tags can be passed to `search`, `create_memory`, and `enrich_memory`. In search, they narrow results to matching knowledge. In creation and enrichment, they classify the knowledge for future retrieval.

## Typical session flow

1. **`list_domains`** — discover available domains and their semantics
2. **`start_session`** — begin a session in the relevant domain
3. **`search`** — find relevant knowledge for the current task
4. **`share_feedback`** — rate the search results
5. **`create_memory`** / **`enrich_memory`** — contribute new knowledge back

Steps 3–5 repeat throughout the session. The agent passes the session ID to each call; Memco handles persistence and trust scoring.