Tools Reference

memcp Tools Reference

All tools are exposed via the Model Context Protocol. Agents call them the same way they call any other MCP tool.

---

store_memory

Store a new memory in memcp.

Parameters

Name	Type	Required	Description
content	string	Yes	The text content to store
tags	string[]	No	Labels for categorization and filtering
agent_id	string	No	Agent identifier. Defaults to the calling agent.
importance	number	No	Initial salience weight (0.0–1.0). Default: 0.5
metadata	object	No	Arbitrary key-value pairs attached to the memory

Example call

{
  "tool": "store_memory",
  "arguments": {
    "content": "User prefers responses in bullet points. Dislikes verbose prose.",
    "tags": ["preference", "formatting"],
    "importance": 0.8
  }
}

Example response

{
  "id": "mem_01jk9x8zy3",
  "content": "User prefers responses in bullet points...",
  "tags": ["preference", "formatting"],
  "salience": 0.8,
  "created_at": "2025-06-01T12:34:56Z"
}

---

search_memories

Hybrid BM25+vector search across stored memories.

Parameters

Name	Type	Required	Description
query	string	Yes	Search query (semantic or keyword)
limit	number	No	Maximum results to return. Default: 10
tags	string[]	No	Filter to memories with ALL of these tags
agent_id	string	No	Restrict to a specific agent’s memories
min_salience	number	No	Only return memories with salience above this threshold

Example call

{
  "tool": "search_memories",
  "arguments": {
    "query": "user formatting preferences",
    "limit": 5,
    "tags": ["preference"]
  }
}

Example response

{
  "memories": [
    {
      "id": "mem_01jk9x8zy3",
      "content": "User prefers responses in bullet points...",
      "tags": ["preference", "formatting"],
      "salience": 0.78,
      "score": 0.92,
      "created_at": "2025-06-01T12:34:56Z"
    }
  ],
  "total": 1
}

---

recall

Automatically surface the most relevant memories for the current context. Combines salience weighting with hybrid search.

Parameters

Name	Type	Required	Description
context	string	Yes	Current message or conversation turn to recall against
limit	number	No	Maximum memories to return. Default: 5
agent_id	string	No	Restrict to a specific agent’s memories

Example call

{
  "tool": "recall",
  "arguments": {
    "context": "The user is asking about their project deadline.",
    "limit": 5
  }
}

Example response

{
  "memories": [
    {
      "id": "mem_01jk9x3ab2",
      "content": "Project Alpha deadline is July 15th. User confirmed this is hard.",
      "tags": ["project", "deadline"],
      "salience": 0.91,
      "created_at": "2025-05-28T09:00:00Z"
    }
  ]
}

---

delete_memory

Remove a memory by ID.

Parameters

Name	Type	Required	Description
id	string	Yes	Memory ID to delete

Example call

{
  "tool": "delete_memory",
  "arguments": {
    "id": "mem_01jk9x8zy3"
  }
}

Example response

{
  "deleted": true,
  "id": "mem_01jk9x8zy3"
}

---

list_memories

List recent memories with optional filtering. Useful for inspection and auditing.

Parameters

Name	Type	Required	Description
limit	number	No	Number of entries to return. Default: 20, max: 100
offset	number	No	Pagination offset. Default: 0
tags	string[]	No	Filter by tags
agent_id	string	No	Filter by agent
order	string	No	created_at_desc (default), created_at_asc, salience_desc

Example call

{
  "tool": "list_memories",
  "arguments": {
    "limit": 10,
    "order": "salience_desc"
  }
}

Example response

{
  "memories": [
    {
      "id": "mem_01jk9x3ab2",
      "content": "Project Alpha deadline is July 15th...",
      "tags": ["project", "deadline"],
      "salience": 0.91,
      "created_at": "2025-05-28T09:00:00Z"
    }
  ],
  "total": 47,
  "limit": 10,
  "offset": 0
}