Tools Reference

MemLayer exposes five MCP tools. Claude calls these automatically based on conversation context.

---

memlayer_retain

Store information the user wants remembered. Use when the user says “remember”, shares preferences, or provides facts about themselves.

Parameter	Type	Required	Description
content	string	Yes	The fact to remember. Write in third person: “User prefers X” not “I prefer X”
source	string	No	Origin identifier: conversation, user_stated, or inferred

Example call:

{
  "content": "User prefers Neovim as their primary editor",
  "source": "user_stated"
}

When Claude uses it: User says “Remember that I use Neovim for everything.” Claude extracts the fact, rephrases it in third person, and calls retain.

Maps to: POST /api/v1/retain

---

memlayer_recall

Search stored memories. Claude calls this before answering questions about user preferences, history, or previously shared information.

Parameter	Type	Required	Description
query	string	Yes	Natural language search. Be specific: “editor preference” not just “editor”
limit	integer	No	Max results (default: 5). Use 10+ for broad searches

Example call:

{
  "query": "editor preference",
  "limit": 5
}

When Claude uses it: User asks “What editor do I use?” Claude searches for semantically similar memories and uses the results to answer.

Maps to: POST /api/v1/recall

---

memlayer_reflect

Consolidate related memories into higher-level summaries. Use sparingly — only when the user asks to organize memories or after many retain calls.

Parameter	Type	Required	Description
query	string	No	Only consolidate memories about this topic

Example call:

{
  "query": "development tools"
}

When Claude uses it: User says “Organize my memories about development tools.” Claude scopes the reflection to that topic.

Maps to: POST /api/v1/reflect

---

memlayer_forget

Remove a memory from active queries. Use when explicitly asked to forget something.

Parameter	Type	Required	Description
memory-id	string	Yes	The memory UUID to forget (get this from recall results)

Example call:

{
  "memory-id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

When Claude uses it: User says “Forget my editor preferences.” Claude first calls recall to find matching memories, reads the memory-id from the results, then calls forget with that ID.

Maps to: POST /api/v1/forget

---

memlayer_batch_retain

Store multiple memories in a single call. Use when the user shares several facts at once or when importing bulk information.

Parameter	Type	Required	Description
namespace	string	Yes	Namespace to store memories in
items	array	Yes	Array of {content, source} objects

Example call:

{
  "namespace": "default",
  "items": [
    {"content": "User works at Acme Corp", "source": "user_stated"},
    {"content": "User's role is senior engineer", "source": "user_stated"}
  ]
}

When Claude uses it: User shares multiple facts in a single message. Claude batches them into one call for efficiency.

Maps to: POST /api/v1/retain/batch

---

Tool discovery

When Claude connects to MemLayer via MCP, it receives the tool definitions automatically through the tools/list JSON-RPC method. The descriptions guide Claude on when and how to use each tool.

Beyond tool definitions, memlayer also serves a SKILL.md file — behavioral instructions that teach the agent best practices for using memory (when to recall silently, how to write good memories, budget awareness, etc.). See Connect Your Agent for details.

You can inspect the raw tool definitions in the source at src/clj/memlayer/mcp/tools.clj.