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 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 preferenceget_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 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.