Mnemosyne MCP

THIS IS A WORK IN PROGRESS AND THE DOCUMENTATION IS AI-GENERATED AND WILL BE REWRITTEN BY HUMAN BEFORE PEOPLE ARE WIDELY ENCOURAGED TO READ IT AND USE THIS CODE. THANK YOU FOR YOUR ATTENTION TO THIS MATTER XOXO VERA

AI-powered knowledge graph integration for Claude Code, Goose & Codex

The Mnemosyne MCP (neem) provides seamless integration between AI coding agents (Claude Code, Goose CLI, OpenAI Codex CLI) and your Mnemosyne knowledge graphs through the Model Context Protocol (MCP). It handles OAuth authentication, provides a standard MCP stdio server, and enables AI agents to query, create, and manage your knowledge graphs directly.

Features:

• 🔐 Browser-based OAuth authentication

• 🤖 9 MCP tools for graph operations (query, create, upload, etc.)

• 📁 RDF file upload support (Turtle, RDF/XML, N-Triples, JSON-LD)

• 🔍 SPARQL query execution

• 📊 Graph schema analysis

• ✨ Optimized responses for LLM consumption

Installation

While developing locally with uv:

Commands

Quick Start (Claude Code)

Step 1: Install and authenticate

Step 2: Add MCP server to Claude Code

Using the Claude CLI (recommended):

Or manually add to ~/.claude.json:

Step 3: Restart Claude Code

After configuration, restart Claude Code completely. You can verify the MCP server is loaded with:

Usage Examples

Once configured, you can ask Claude Code to:

• List graphs: "Show me all my knowledge graphs"

• Query data: "Run a SPARQL query to find all entities of type Person in my personal-knowledge graph"

• Upload files: "Upload the ontology.ttl file to my research-data graph"

• Create graphs: "Create a new graph called project-notes with description 'Notes from my projects'"

• Get schema info: "What types and properties exist in my personal-knowledge graph?"

Token Management

Tokens expire after a day. Re-run neem init --force whenever you need a fresh token, and restart Claude Code afterwards.

Goose CLI Setup

Goose is an open-source AI agent CLI that also supports MCP servers.

Step 1: Install and authenticate

Step 2: Configure Goose

Interactive configuration (recommended):

Or edit

Step 3: Start Goose

Goose will automatically load the MCP server. You can verify with:

Codex CLI Setup

OpenAI Codex CLI also supports MCP servers.

Note: Codex CLI intentionally silences stderr from MCP servers, so use LOG_LEVEL=ERROR to suppress all logging:

Configuration example:

Important: Set LOG_LEVEL=ERROR for Codex CLI to avoid any stderr interference with the stdio protocol.

Available MCP Tools

The neem-mcp-server provides the following tools for any MCP client (Claude Code, Goose, etc.):

Session Management

• create_session - Initialize a new MCP session with the authenticated user

Graph Operations

• list_graphs - List all accessible knowledge graphs with optional stats and metadata

• get_graph_schema - Analyze graph schema (classes, properties, relationships)

• get_graph_info - Get comprehensive graph information and statistics

• create_graph - Create a new knowledge graph

• delete_graph - Delete an existing graph (requires confirmation)

Data Operations

• sparql_query - Execute SPARQL queries against graphs

  • Parameters: graph_id, query, result_format (json/csv/xml), timeout_seconds

• upload_file_to_graph - Upload RDF files (Turtle, RDF/XML, N-Triples, JSON-LD) to graphs

  • Parameters: graph_id, file_path, rdf_format (optional), validation_level (strict/lenient/none), namespace (optional), replace_existing (bool)

  • Supports format auto-detection

  • Configurable validation levels

  • Progress tracking with job IDs

System Operations

• get_system_health - Check system health and component status

All tools support:

• ✅ Automatic authentication via saved tokens

• ✅ Session caching for performance

• ✅ Detailed error messages with helpful suggestions

• ✅ Structured JSON responses optimized for LLM consumption

Configuration

• Tokens are stored at ~/.mnemosyne/config.json (override with MNEMOSYNE_CONFIG_DIR).

• Claude Code settings are written to ~/.claude/settings.json (override with CLAUDE_CODE_SETTINGS_PATH).

• Override the API endpoint with --api-url or MNEMOSYNE_API_URL.

Architecture

This package contains two main components:

1. CLI Tool (neem)

Located in neem.cli:

• OAuth PKCE authentication flow (neem.utils.oauth)

• Secure token storage (neem.utils.token_storage)

• Claude Code configuration management (neem.utils.claude_config)

2. MCP Server (neem-mcp-server)

Located in neem.mcp.server:

• Stdio transport - Communicates with Claude Code via stdin/stdout

• HTTP API client - Calls the Mnemosyne Graph API for all operations

• Session management - Redis-backed session caching (optional)

• Structured logging - All logs go to stderr (stdio-safe)

Key design principles:

• Stateless MCP server - All state lives in the API, MCP server is just a client

• Token-based auth - Tokens obtained via neem init are used for API authentication

• Clean separation - MCP protocol handling separate from business logic

• Error handling - Helpful error messages with suggestions for LLM consumption

Development

Local Development

Project Structure

Environment Variables

• MNEMOSYNE_API_URL - API endpoint (default: https://api.sophia-labs.com)

• MNEMOSYNE_CONFIG_DIR - Token storage location (default: ~/.mnemosyne)

• CLAUDE_CODE_SETTINGS_PATH - Claude settings file (default: ~/.claude/settings.json)

• REDIS_URL - Redis connection for sessions (default: redis://localhost:6379)

• LOG_LEVEL - Logging verbosity (default: INFO)

  • DEBUG - Verbose logging for troubleshooting

  • INFO - Normal operational logging (default)

  • WARNING - Quiet mode, only warnings and errors

  • ERROR - Silent mode, only errors (recommended for Codex CLI)

  • CRITICAL - Minimal logging, critical errors only

Troubleshooting

MCP Server Not Loading

For Claude Code:

1. Check configuration: cat ~/.claude.json | grep mnemosyne-graph

2. Test server directly: echo '{"jsonrpc": "2.0", "method": "initialize", "id": 1}' | neem-mcp-server

3. Check logs: Look for stderr output when Claude Code starts

4. Verify token: neem status should show "Active" authentication

5. Restart Claude Code: Configuration changes require a complete restart

For Goose CLI:

1. Check configuration: cat ~/.config/goose/config.yaml | grep mnemosyne-graph

2. Verify extension is enabled: enabled: true in the config

3. Check timeout: Increase to 600 seconds if server is slow to start

4. Test in session: Start a new Goose session and ask it to list available tools

5. Check environment: Ensure MNEMOSYNE_API_URL is set correctly

For Codex CLI:

1. Enable debug logging: Codex intentionally silences stderr, making debugging difficult

2. Set LOG_LEVEL: Use LOG_LEVEL=ERROR in the environment to prevent stderr interference

3. Test manually: Run echo '{"jsonrpc":"2.0","method":"initialize","id":1}' | neem-mcp-server to verify it works

4. Check configuration: Ensure codex.json or your config file has the correct command and environment variables

Authentication Issues

1. Token expired: Run neem init --force to get a fresh token

2. Check token: neem config to see token details

3. Verify API access: The token should have access to the API endpoint

Upload Issues

1. File not found: Ensure the file path is absolute or relative to working directory

2. Format detection: Explicitly specify format with rdf_format parameter if auto-detection fails

3. Validation errors: Try validation_level="lenient" for less strict parsing

Schema/Proto Errors (Goose/Gemini)

If you see errors like "Unknown name 'type'" or "Proto field is not repeating, cannot start list":

1. Cause: This was caused by using JSON Schema reserved keywords (format, type, etc.) as parameter names

2. Fixed in: Latest version uses result_format and rdf_format instead of format

3. Solution: Update to latest version with pip install --upgrade neem

Note: Parameter names were changed to avoid conflicts with JSON Schema keywords:

• format → result_format (in sparql_query)

• format → rdf_format (in upload_file_to_graph)

• validation → validation_level (in upload_file_to_graph)

Goose + Gemini users: If you get proto errors even with the latest version, disable Goose's built-in extensions temporarily:

This is a known issue with Goose's built-in extensions and Gemini compatibility (not a Mnemosyne MCP issue).

See the docs/ directory for end-user quick start and detailed guides that can ship with the package or be published separately.