# Personal Memory Tools Reference

Memco Personal Memory exposes seven tools through its MCP interface.

## start_session

Loads your identity and preferences at the start of a conversation. Returns memories tagged `type:user` as one-line hooks (title and description), along with a summary of all tags in use.

Call this at the beginning of every conversation to give the agent immediate context about the user's preferences and working style.

The hooks returned are summaries, not full content. Call `get_memory` with the `external_id` shown in the listing to retrieve the full note.

**Parameters:** None.

**Returns:** A listing of preference hooks and tags in use.

```
start_session()
→
# Your preferences (type:user)
- Preferred spelling convention for written content. (spelling-preference) — updated 2026-09-02
- Preferred code style and formatting. (code-style) — updated 2026-08-28

# Tags in use
- type:user (2)
```

---

## search

Searches your personal memories by semantic query. Returns full memory content for matching results.

Call when you need to find a specific preference or piece of context but do not know its `external_id`. Use `list_memories` instead when you want to browse all memories or filter by keyword or tag.

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | A natural language query describing what you are looking for |

**Returns:** Matching memories with their full content, `external_id`, and last-updated date.

**Usage:**

```
search(query: "spelling convention preference")
→
## Spelling preference (spelling-preference) — updated 2026-09-02
User prefers British English spelling in all documents.
```

---

## list_memories

Lists your personal memories, newest first. Pass `keyword` to filter by substring match on title or content, `tags` to filter by tag, or `page` and `page_size` to paginate.

Call when you want to see everything saved, or to find the `external_id` of a memory you intend to read, update, or delete. Use `search` instead when you know what you are looking for semantically.

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `keyword` | string | no | Only list memories whose title or content contains this text (case-insensitive substring match) |
| `tags` | array | no | Filter by tags. See [Tag format](#tag-format) below |
| `page` | integer | no | Page to return (1-based, default 1) |
| `page_size` | integer | no | Memories per page (default 25, max 100) |

**Returns:** A list of memories as `external_id: title`.

**Usage:**

```
list_memories(keyword: "spelling")
→ spelling-preference: Spelling preference
```

---

## get_memory

Fetches one personal memory in full by its `external_id`. Returns the title, content, and last-updated date.

Call when `start_session` or `list_memories` showed you an `external_id` whose full content you now need. Those listings carry only a one-line hook; this tool returns the complete note.

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `external_id` | string | yes | The `external_id` of the memory to retrieve |

**Returns:** The full memory content.

**Usage:**

```
get_memory(external_id: "spelling-preference")
→
# spelling-preference — updated 2026-09-02
Spelling preference

User prefers British English spelling in all documents.
```

---

## write_memory

Saves a new note to your personal memory. Use for durable, private preferences: how you like responses formatted, your editor and workflow settings, personal facts, or working context.

One preference per memory. Keep memories focused and atomic so they are easy to find, update, and delete independently.

Supply a stable `external_id` to name the memory. Re-writing the same `external_id` replaces the note entirely, so use `update_memory` when only part of it should change.

Add a one-line `description` — it is the hook shown in your `start_session` listing and what semantic search matches on.

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `title` | string | yes | A short title, shown in listings |
| `content` | string | yes | The knowledge to save. Keep these short, under 5000 characters |
| `description` | string | no | A one-line description — the hook shown in your startup listing and used to find the memory |
| `external_id` | string | no | A stable name for this memory. Re-writing the same `external_id` replaces it. Generated when omitted |
| `tags` | array | no | Tags to organise the memory. See [Tag format](#tag-format) below |

**Returns:** Confirmation with the assigned `external_id`.

**Usage:**

```
write_memory(
  title: "Spelling preference",
  content: "User prefers British English spelling in all documents.",
  description: "Preferred spelling convention for written content.",
  external_id: "spelling-preference",
  tags: ["<tag type=\"type\" value=\"user\" />"]
)
→ Saved to your personal memory as "spelling-preference".
  update_memory edits part of it in place.
```

---

## update_memory

Edits an existing personal memory in place. You can replace a substring of the content (`old_string` → `new_string`), prepend or append text, and change the title or description. Untouched fields and tags are preserved.

Call when a preference has changed or needs a detail added and the rest of the note should survive. Use `write_memory` with the same `external_id` when the whole note should be replaced.

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `external_id` | string | yes | The `external_id` of the memory to edit |
| `old_string` | string | no | Exact text in the content to replace. Must appear exactly once unless `replace_all` is set |
| `new_string` | string | no | Replacement for `old_string`. Omit to delete the matched text |
| `replace_all` | boolean | no | Replace every occurrence of `old_string` instead of erroring when it appears more than once |
| `prepend` | string | no | Text to insert at the very start of the content |
| `append` | string | no | Text to insert at the very end of the content |
| `title` | string | no | Replace the title |
| `description` | string | no | Replace the one-line description |

**Returns:** Confirmation that the memory was updated.

**Usage:**

```
update_memory(
  external_id: "spelling-preference",
  append: " Exception: use American English for documents intended for US audiences."
)
→ Updated your personal memory "spelling-preference".
  get_memory returns it in full if you want to read back the result.
```

---

## delete_memory

Permanently deletes one personal memory by its `external_id`. There is no undo.

Call when a saved preference is wrong or no longer true and no edit would fix it. Prefer `update_memory` when the note should change rather than disappear.

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `external_id` | string | yes | The `external_id` of the memory to delete |

**Returns:** Confirmation that the memory was deleted.

**Usage:**

```
delete_memory(external_id: "spelling-preference")
→ Deleted personal memory "spelling-preference".
  Deletion is permanent — there is no undo.
```

---

## Tag format

Tags use XML format with a `type` and a `value`:

```
<tag type="type" value="user" />
<tag type="scope" value="work" />
```

The most important tag is `type:user`, which marks a memory as a user preference. Memories with this tag appear in the `start_session` listing, giving agents immediate access to your core preferences at the start of every conversation.

Use `scope` tags to partition memories by context (e.g. `work`, `personal`, `project-name`). This is optional but can help keep memories organised as the collection grows.