Tools Reference

The Memsolus MCP server exposes 17 tools organized in four categories. Claude selects and calls these tools automatically based on your instructions.

Memory Management

add_memory

Stores a new persistent memory in the workspace.

Parameter	Type	Required	Description
`memory`	string	Yes	The memory content — write as a clear, self-contained statement
`user_id`	string	No	ID of the user this memory belongs to
`agent_id`	string	No	ID of the agent this memory belongs to
`session_id`	string	No	ID of the conversation session
`metadata`	string (JSON)	No	Arbitrary key-value metadata encoded as a JSON string
`priority`	string	No	`LOW`, `MEDIUM` (default), or `HIGH`

Example response

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "status": "PENDING",
  "createdAt": "2026-06-07T10:00:00.000Z"
}

search_memories

Searches memories using semantic, keyword, or hybrid matching. Returns memories ranked by relevance.

Parameter	Type	Required	Description
`query`	string	Yes	Natural language search query
`user_id`	string	No	Filter results to a specific user
`limit`	number	No	Maximum results to return (default `10`)
`mode`	string	No	`hybrid` (default), `semantic`, or `keyword`

Example response

{
  "data": [
    {
      "id": "9b1deb4d-...",
      "content": "The user prefers TypeScript for all new projects.",
      "score": 0.94,
      "priority": "HIGH",
      "categories": ["preferences", "tech-stack"],
      "createdAt": "2026-06-07T09:00:00.000Z"
    }
  ],
  "meta": { "total": 1, "mode": "hybrid" }
}

get_memories

Lists memories chronologically with pagination. Use when browsing all memories rather than searching by relevance.

Parameter	Type	Required	Description
`user_id`	string	No	Filter by user ID
`agent_id`	string	No	Filter by agent ID
`page`	number	No	Page number (default `1`)
`limit`	number	No	Results per page (default `20`)

Example response

{
  "data": [
    {
      "id": "9b1deb4d-...",
      "content": "The user is building a SaaS product.",
      "status": "READY",
      "createdAt": "2026-06-07T09:00:00.000Z"
    }
  ],
  "meta": { "total": 42, "page": 1, "pageSize": 20, "totalPages": 3 }
}

get_memory

Retrieves a specific memory by its ID.

Parameter	Type	Required	Description
`memory_id`	string	Yes	UUID of the memory to retrieve

Example response

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "content": "The user prefers TypeScript for all new projects.",
  "userId": "user_123",
  "status": "READY",
  "layer": "RAW",
  "priority": "HIGH",
  "categories": ["preferences", "tech-stack"],
  "metadata": { "source": "onboarding" },
  "createdAt": "2026-06-07T09:00:00.000Z",
  "updatedAt": "2026-06-07T09:05:00.000Z"
}

update_memory

Updates an existing memory's content or priority.

Parameter	Type	Required	Description
`memory_id`	string	Yes	UUID of the memory to update
`memory`	string	No	New memory content
`priority`	string	No	New priority: `LOW`, `MEDIUM`, or `HIGH`

Example response

{
  "id": "9b1deb4d-...",
  "content": "The user prefers TypeScript and Rust for new projects.",
  "status": "PENDING",
  "updatedAt": "2026-06-07T11:00:00.000Z"
}

delete_memory

Permanently deletes a memory. This action cannot be undone.

Parameter	Type	Required	Description
`memory_id`	string	Yes	UUID of the memory to delete

Example response

{ "deleted": true }

promote_memory

Promotes a TASK-layer memory (temporary, with expiration) to RAW layer (permanent, no expiration).

Parameter	Type	Required	Description
`memory_id`	string	Yes	UUID of the memory to promote

Example response

{ "promoted": true, "layer": "RAW" }

submit_feedback

Submits a quality signal on a memory. Feedback improves retrieval quality over time.

Parameter	Type	Required	Description
`memory_id`	string	Yes	UUID of the memory
`signal`	string	Yes	`POSITIVE`, `NEGATIVE`, or `NEUTRAL`
`comment`	string	No	Optional explanation for the feedback

Example response

{ "recorded": true }

get_memory_history

Returns the event timeline for a memory — creation, updates, promotions, and feedback.

Parameter	Type	Required	Description
`memory_id`	string	Yes	UUID of the memory
`limit`	number	No	Number of events to return (default `20`)

Example response

{
  "data": [
    {
      "id": "evt-uuid",
      "type": "CREATED",
      "createdAt": "2026-06-07T09:00:00.000Z"
    },
    {
      "id": "evt-uuid-2",
      "type": "FEEDBACK_SUBMITTED",
      "payload": { "signal": "POSITIVE" },
      "createdAt": "2026-06-07T10:30:00.000Z"
    }
  ]
}

Knowledge

get_knowledge

Returns the consolidated knowledge profile for a user. Use at the start of a conversation to load full context.

Parameter	Type	Required	Description
`user_id`	string	No	Filter to a specific user
`category`	string	No	Filter to a specific knowledge category
`merged`	boolean	No	When `true` (default), returns a single unified Markdown document

Example response (merged=true)

{
  "content": "## Tech Stack\nThe user builds with Next.js and Supabase...\n\n## Preferences\nPrefers TypeScript for all new projects...",
  "entries": [
    { "id": "kn-uuid", "category": "tech-stack" },
    { "id": "kn-uuid-2", "category": "preferences" }
  ],
  "mergedAt": "2026-06-07T08:00:00.000Z"
}

get_knowledge_entry

Retrieves a specific knowledge entry by its ID.

Parameter	Type	Required	Description
`knowledge_id`	string	Yes	UUID of the knowledge entry

Example response

{
  "id": "kn-uuid",
  "category": "tech-stack",
  "content": "The user builds with Next.js and Supabase. Prefers TypeScript.",
  "userId": "user_123",
  "sourceMemoryIds": ["9b1deb4d-...", "a4c7..."],
  "createdAt": "2026-06-07T08:00:00.000Z"
}

Graph

graph_search

Searches for entities (people, organizations, places, things) in the knowledge graph.

Parameter	Type	Required	Description
`query`	string	Yes	Text query to search entities
`user_id`	string	No	Filter to entities linked to a specific user
`type`	string	No	Filter by type: `PERSON`, `ORGANIZATION`, `PLACE`, or `THING`
`limit`	number	No	Maximum results (default `10`)

Example response

[
  {
    "id": "ent-uuid",
    "name": "João Silva",
    "type": "PERSON",
    "description": "Senior backend engineer specializing in TypeScript"
  }
]

graph_traverse

Traverses relationships from a known entity in the knowledge graph.

Parameter	Type	Required	Description
`entity_id`	string	Yes	UUID of the entity to start from
`direction`	string	No	`outgoing`, `incoming`, or `both` (default `both`)
`hops`	number	No	Traversal depth: `1`, `2`, or `3` (default `2`)

Example response

{
  "startEntity": {
    "id": "ent-uuid",
    "name": "João Silva",
    "type": "PERSON"
  },
  "paths": [
    {
      "entity": { "id": "org-uuid", "name": "Acme Corp", "type": "ORGANIZATION" },
      "relationship": "WORKS_AT",
      "depth": 1
    },
    {
      "entity": { "id": "thing-uuid", "name": "TypeScript", "type": "THING" },
      "relationship": "USES",
      "depth": 1
    }
  ]
}

graph_query

Answers a natural language question using the knowledge graph.

Parameter	Type	Required	Description
`question`	string	Yes	Natural language question

Example response

{
  "answer": "João Silva is working on Project X and the internal API redesign at Acme Corp. He leads the backend team on Project X.",
  "confidence": 0.87,
  "entitiesUsed": [
    { "id": "ent-uuid", "name": "João Silva", "type": "PERSON" },
    { "id": "thing-uuid", "name": "Project X", "type": "THING" }
  ]
}

Utilities

get_dashboard_summary

Returns workspace KPIs for a given time window.

Parameter	Type	Required	Description
`days`	number	No	Time window in days (default `30`)

Example response

{
  "totalMemories": 142,
  "totalSearches": 891,
  "totalTokens": 45200,
  "comparisonPeriod": {
    "memories": 130,
    "searches": 810,
    "tokens": 41000
  },
  "days": 30
}

get_memory_profile

Returns a summarized profile of a user built from their memories.

Parameter	Type	Required	Description
`user_id`	string	Yes	UUID or identifier of the user

Example response

{
  "userId": "user_123",
  "summary": "A senior backend engineer focused on SaaS products. Strong preference for TypeScript and open-source tooling. Currently building a project management platform.",
  "topics": ["typescript", "saas", "backend", "open-source"],
  "entityCount": 14
}

list_entities

Lists all users and agents in the workspace with their memory counts.

No parameters.

Example response

[
  {
    "userId": "user_123",
    "memoryCount": 47,
    "lastActivityAt": "2026-06-07T10:00:00.000Z"
  },
  {
    "agentId": "agent_456",
    "memoryCount": 12,
    "lastActivityAt": "2026-06-06T18:30:00.000Z"
  }
]

Tool selection guide

Need	Tool
Load full user context at conversation start	`get_knowledge` with `merged=true`
Find specific info by topic	`search_memories`
Store new information	`add_memory`
Correct or update existing info	`update_memory`
Remove wrong or outdated info	`delete_memory` (search first if you need the ID)
Browse memories chronologically	`get_memories`
Discover who has memories	`list_entities`
Find people or concepts in the graph	`graph_search`
Explore entity connections	`graph_traverse`
Ask complex relational questions	`graph_query`
Get workspace usage statistics	`get_dashboard_summary`
Get a quick overview of a specific user	`get_memory_profile`

Getting Started — installation and client configuration
Integrations — Claude Desktop, Cursor, HTTP mode, and troubleshooting

Memory Management​

add_memory​

search_memories​

get_memories​

get_memory​

update_memory​

delete_memory​

promote_memory​

submit_feedback​

get_memory_history​

Knowledge​

get_knowledge​

get_knowledge_entry​

Graph​

graph_search​

graph_traverse​

graph_query​

Utilities​

get_dashboard_summary​

get_memory_profile​

list_entities​

Tool selection guide​

Related​

Memory Management

add_memory

search_memories

get_memories

get_memory

update_memory

delete_memory

promote_memory

submit_feedback

get_memory_history

Knowledge

get_knowledge

get_knowledge_entry

Graph

graph_search

graph_traverse

graph_query

Utilities

get_dashboard_summary

get_memory_profile

list_entities

Tool selection guide

Related