psychology GrimTech
description API Reference

GrimTech MCP Server

Model Context Protocol server for persistent AI memory. Store, recall, and manage memories across sessions.

POST https://mcp.grimtech.co.uk/mcp
key
Authentication required. All MCP calls require a valid API key passed via the Authorization: Bearer <key> header. Generate keys at https://mcp.grimtech.co.uk/dashboard/#/apikeys.

edit Write Operations

Create and store new memories. Write operations create or modify data.

memory Write

Store a new memory in the database. Optionally assign to a space by name — the space is auto-created if it doesn't exist.

Parameter Type Required Description
title string required Memory title
content string required Full memory content (markdown supported)
project string optional Space/project name — auto-creates if it doesn't exist
collection_id integer optional Optional collection ID (overrides project)
tags string[] optional Array of tag strings
source string optional Source label (e.g. "session:2026-07-20")
importance integer optional Priority 1-5 (default: 3)
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "memory", "arguments": {"title":"API Design Notes","content":"REST conventions...","project":"MyProject","tags":["api","rest"],"importance":4} } }
merge_memories Write

Merge multiple memories into one. Originals are soft-deleted, merged memory gets all tags from all sources.

Parameter Type Required Description
ids integer[] required At least 2 memory IDs to merge
title string required Title for the merged memory
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "merge_memories", "arguments": {"ids":[1,2,3],"title":"Combined Notes"} } }
memories Write

Create multiple memories in a single call.

Parameter Type Required Description
items array required Array of memory objects (each with title, content, and optional tags/importance/project)
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "memories", "arguments": {"items":[{"title":"Note 1","content":"Content 1","tags":["tag1"]},{"title":"Note 2","content":"Content 2"}]} } }
import_memories Write

Import memories from a previously exported JSON object. Collections are created if they don't exist.

Parameter Type Required Description
data object required The exported JSON object with memories, collections, tags
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "import_memories", "arguments": {"data":{"version":1,"collections":[],"memories":[{"title":"Imported Note","content":"Content here"}]}} } }

visibility Read Operations

Search, retrieve, and list memories. Read operations never modify data.

recall Read

Search memories by query string. Returns ranked results. Optionally filter to a specific space.

Parameter Type Required Description
query string required Search query string
project string optional Filter to a specific space/project
limit integer optional Max results (default: 50)
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "recall", "arguments": {"query":"API authentication","project":"MyProject","limit":10} } }
get_memory Read

Retrieve a specific memory by its ID. Returns the full memory object with all fields.

Parameter Type Required Description
id integer required Memory ID
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_memory", "arguments": {"id":42} } }
listMemories Read

List all memories with optional pagination. Returns truncated previews (first 200 chars of content).

Parameter Type Required Description
limit integer optional Max results (default: 50)
offset integer optional Pagination offset (default: 0)
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "listMemories", "arguments": {"limit":20,"offset":0} } }
listProjects Read

List all spaces (collections) with their memory counts.

No parameters required.

JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "listProjects", "arguments": {} } }
memory-graph Read

Retrieve a graph structure of memories, tags, and projects. Returns nodes (memories, tags, projects) and edges (belongs_to, has_tag).

No parameters required.

JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "memory-graph", "arguments": {} } }
whoAmI Read

Get the current authenticated user's profile information.

No parameters required.

JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "whoAmI", "arguments": {} } }
get_collection Read

Retrieve a space/collection by ID, including all of its memories.

Parameter Type Required Description
id integer required Space/collection ID
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_collection", "arguments": {"id":3} } }
list_tags Read

List all tags used across your memories.

No parameters required.

JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "list_tags", "arguments": {} } }
search_by_tags Read

Search memories by exact tag match. Returns memories that have ALL specified tags (AND logic).

Parameter Type Required Description
tags string[] required Array of tag strings to match
limit integer optional Max results (default: 50)
offset integer optional Pagination offset (default: 0)
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "search_by_tags", "arguments": {"tags":["api","rest"],"limit":20} } }
find_similar Read

Find memories similar to a given memory, ranked by similarity score.

Parameter Type Required Description
id integer required Memory ID to compare against
limit integer optional Max results (default: 10)
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "find_similar", "arguments": {"id":42,"limit":5} } }
dedup_check Read

Check whether a proposed title+content would duplicate an existing memory, based on similarity threshold.

Parameter Type Required Description
title string required Proposed memory title
content string required Proposed memory content
threshold number optional Similarity threshold 0-1 (default: 0.85)
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "dedup_check", "arguments": {"title":"API Design Notes","content":"REST conventions...","threshold":0.85} } }
count_memories Read

Get memory counts broken down by space/collection.

No parameters required.

JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "count_memories", "arguments": {} } }
random_recall Read

Retrieve a random sample of memories, optionally scoped to a space.

Parameter Type Required Description
limit integer optional Max results (default: 5)
collection_id integer optional Restrict to a specific space
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "random_recall", "arguments": {"limit":3} } }
get_memory_versions Read

List all saved versions of a memory (edit history). Versions are created automatically on every update.

Parameter Type Required Description
id integer required Memory ID
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_memory_versions", "arguments": {"id":42} } }
get_memory_version Read

Get a specific version of a memory with full content (not truncated).

Parameter Type Required Description
id integer required Memory ID
version integer required Version number
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_memory_version", "arguments": {"id":42,"version":1} } }
diff_versions Read

Show a line-by-line diff between two versions of a memory.

Parameter Type Required Description
id integer required Memory ID
version_a integer required Older version number
version_b integer required Newer version number
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "diff_versions", "arguments": {"id":42,"version_a":1,"version_b":2} } }
list_deleted_memories Read

List all soft-deleted memories in trash.

No parameters required.

JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "list_deleted_memories", "arguments": {} } }
list_expired Read

List memories that have passed their expiration date but not yet been purged.

No parameters required.

JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "list_expired", "arguments": {} } }
export_memories Read

Export all your memories, collections, and tags as a JSON object.

No parameters required.

JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "export_memories", "arguments": {} } }

sync Update Operations

Modify fields, favourite, or archive existing memories.

update_memory Update

Update fields on an existing memory (title, content, tags, importance, source, project).

Parameter Type Required Description
id integer required Memory ID to update
title string optional New title
content string optional New content
tags string[] optional Replacement tag array
importance integer optional Priority 1-5
source string optional Source label
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "update_memory", "arguments": {"id":42,"title":"Updated title","importance":5} } }
favourite_memory Update

Toggle the favourite flag on a memory.

Parameter Type Required Description
id integer required Memory ID to toggle
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "favourite_memory", "arguments": {"id":42} } }
archive_memory Update

Toggle the archived flag on a memory.

Parameter Type Required Description
id integer required Memory ID to toggle
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "archive_memory", "arguments": {"id":42} } }
pin_memory Update

Toggle pin status on a memory (pins it to the top / unpins it).

Parameter Type Required Description
id integer required Memory ID to toggle
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "pin_memory", "arguments": {"id":42} } }
restore_memory_version Update

Restore a memory to a previous version. Current state is auto-saved before restoring.

Parameter Type Required Description
id integer required Memory ID
version integer required Version number to restore
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "restore_memory_version", "arguments": {"id":42,"version":1} } }
restore_memory Update

Restore a soft-deleted memory from trash.

Parameter Type Required Description
id integer required Memory ID to restore
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "restore_memory", "arguments": {"id":42} } }
add_tags_bulk Update

Add tags to multiple memories at once.

Parameter Type Required Description
ids integer[] required Array of memory IDs
tags string[] required Tags to add
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "add_tags_bulk", "arguments": {"ids":[1,2,3],"tags":["api","rest"]} } }
remove_tags_bulk Update

Remove tags from multiple memories at once.

Parameter Type Required Description
ids integer[] required Array of memory IDs
tags string[] required Tags to remove
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "remove_tags_bulk", "arguments": {"ids":[1,2,3],"tags":["deprecated"]} } }
reembed_memory Update

Regenerate the embedding for a memory (useful after bulk edits or model changes).

Parameter Type Required Description
id integer required Memory ID
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "reembed_memory", "arguments": {"id":42} } }

delete Delete Operations

Remove memories and spaces. Delete operations are permanent and cannot be undone.

delete_memory Delete

Delete a specific memory by ID. Also cleans up orphaned tags.

Parameter Type Required Description
id integer required Memory ID to delete
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "delete_memory", "arguments": {"id":42} } }
delete_memories Delete

Delete multiple memories by their IDs in a single operation.

Parameter Type Required Description
ids integer[] required Array of memory IDs to delete
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "delete_memories", "arguments": {"ids":[1,2,3]} } }
delete_space Delete

Delete a space (collection) by ID. Memories inside are NOT deleted — they become unassigned.

Parameter Type Required Description
id integer required Space/collection ID to delete
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "delete_space", "arguments": {"id":5} } }
delete_spaces Delete

Delete multiple spaces by their IDs.

Parameter Type Required Description
ids integer[] required Array of space/collection IDs to delete
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "delete_spaces", "arguments": {"ids":[3,5,7]} } }
force_delete_memory Delete

Permanently delete a memory. Cannot be undone.

Parameter Type Required Description
id integer required Memory ID to permanently delete
JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "force_delete_memory", "arguments": {"id":42} } }
purge_deleted Delete

Permanently delete all memories in trash (older than 30 days).

No parameters required.

JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "purge_deleted", "arguments": {} } }
purge_expired Delete

Permanently delete all expired memories.

No parameters required.

JSON-RPC Request{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "purge_expired", "arguments": {} } }