Mnemosyne

Mnemosyne MCP provides a local-first server that connects to a FastAPI backend to manage knowledge graphs, run SPARQL operations, and enable real-time document collaboration via Y.js CRDT. It offers browser-based authentication, health checks, and multiple ways to run and connect the MCP server from your development environment.

How to use

You will authenticate once to obtain an access token, connect the MCP server to a local or remote FastAPI backend, and then use your MCP client to manage graphs, run SPARQL queries, and collaborate on documents in real time. The server streams job progress via WebSocket when available and falls back to HTTP polling if WebSocket streaming is disabled or unavailable.

How to install

Prerequisites: a modern Python environment, an MCP client that can communicate with stdio or HTTP endpoints, and access to a Kubernetes context if you plan to port-forward the backend.

uv tool install -e . 

# When developing locally with uv
uv sync
uv run neem-mcp-server

# Run the MCP server directly for testing
uv run neem-mcp-server

# Quick command to authenticate via the browser-based OAuth flow
neem init

Configuration overview

The MCP server connects to a FastAPI backend, which can run in your local Kubernetes context or be exposed remotely. You configure the backend URL and related options via environment variables when starting the MCP server. A lightweight health probe checks backend reachability on startup.

Configuration specifics

Key environment variables you will encounter include the following. Use them to point the MCP server at your backend, control WebSocket usage, and adjust logging.

Troubleshooting

If the MCP server does not load or you encounter authentication or SPARQL issues, follow these practical steps to diagnose and resolve common problems.

Notes on data model and operations

All documents, folders, and artifacts are represented in RDF through dedicated backend pipelines. You will use a set of tools to manage graphs, run SPARQL queries, and edit documents in real time. Each operation is designed to work efficiently in a local-first environment with live collaboration.

Appendix: Example workflows

The following represent typical usage patterns you will perform with MCP clients: connect to the backend, authenticate, list graphs, create a graph, run a SPARQL query, and begin collaborative editing of a document.

Available tools

list_graphs

List all knowledge graphs owned by the authenticated user; option to include soft-deleted graphs.

create_graph

Create a new knowledge graph with an ID, title, and optional description.

delete_graph

Delete a graph; supports soft delete by default and hard delete with a flag.

sparql_query

Execute read-only SPARQL SELECT/CONSTRUCT queries against your graphs.

sparql_update

Execute SPARQL INSERT/DELETE/UPDATE operations to modify graph data.

get_user_location

Get the graph and document the user is currently viewing.

get_workspace

Get the folder/file structure of a graph for exploration.

get_session_state

Get full session state including tabs and preferences.

create_folder

Create a new folder in the workspace.

rename_folder

Rename an existing folder.

move_folder

Move a folder to a different parent.

delete_folder

Delete a folder and optionally cascade delete its contents.

read_document

Read a document's content in TipTap XML format.

write_document

Replace a document's content with TipTap XML.

append_to_document

Append a block or content to the end of a document.

move_document

Move a document to a different folder.

delete_document

Remove a document from the workspace.

get_block

Read a specific block by its ID, including length and formatting.

query_blocks

Search for blocks matching specific criteria.

update_block

Update a block's attributes or replace its content.

edit_block_text

Edit block text at character offsets with CRDT-safe collaboration.

insert_block

Insert a new block relative to an existing block.

delete_block

Delete a block, with optional cascade to children.

batch_update_blocks

Update multiple blocks in a single transaction.

move_artifact

Move an artifact to a different folder.

rename_artifact

Rename an artifact.

list_wire_predicates

List available semantic predicates categorized by type.

create_wire

Create a semantic connection between documents or blocks; synced via CRDT.

get_wires

Get all wires connected to a document with directional filtering.

traverse_wires

Breadth-first search of the wire graph from a starting document.