Introduction to Mnemosyne

Mnemosyne is a stateful memory service designed to give AI applications a persistent, long-term memory. It solves the "amnesia" problem in conversational AI by providing a robust backend to store and retrieve user-specific information across multiple sessions.

Whether you're building a personalized health assistant, a smart sales agent, or an intelligent customer support bot, Mnemosyne provides the foundational memory layer you need.

Getting Started

Running Mnemosyne locally involves two main components: the FastAPI backend and the MCP server.

1. Run the FastAPI Backend

The core service must be running first. Ensure you have Python 3.9+ and an accessible MySQL database.

# 1. Set up a virtual environment and install dependencies
pip install -r requirements.txt

# 2. Configure your .env file with database and OpenAI keys

# 3. Start the server
uvicorn app.main:app --reload

2. Run the MCP Server

The MCP server acts as a bridge for AI workflow tools.

# 1. Navigate to the MCP server directory and build
cd memocore-mcp-server
npm install && npm run build

# 2. Configure your workflow tool to run the server using its absolute path
# e.g., /path/to/memocore_v1/memocore-mcp-server/build/index.js

Core Concepts

Hybrid Database Architecture

Mnemosyne uses a powerful hybrid database model:

  • Central MySQL Database: Stores global user information and profiles.
  • Per-User SQLite Databases: Each user's conversational history and memories are stored in a dedicated SQLite file, ensuring complete data isolation and privacy.

Structured Memory

Beyond simple chat history, Mnemosyne allows you to store structured "memories" as key-value pairs. This enables more precise context retrieval and more intelligent AI responses.

MCP Tools API Reference

Interact with Mnemosyne using these four powerful tools.

createUser

Creates a new user in the system.

{
  "tool_name": "createUser",
  "arguments": {
    "username": "new_user_456",
    "profile": { "plan": "premium" }
  }
}

getUser

Retrieves a user's details by their ID.

{
  "tool_name": "getUser",
  "arguments": {
    "userId": 123
  }
}

chat

Sends a message and gets an AI response enriched with memory.

{
  "tool_name": "chat",
  "arguments": {
    "userId": 123,
    "messages": [
      { "role": "user", "content": "What was my goal?" }
    ]
  }
}

updateMemory

Adds or updates a structured memory for a user.

{
  "tool_name": "updateMemory",
  "arguments": {
    "userId": 123,
    "memories": [{
      "key": "primary_goal",
      "embedding_text": "User's primary goal is to learn piano",
      "data": { "skill": "piano", "level": "beginner" }
    }]
  }
}

Advanced Use Case: Multi-Participant Conversations

The optional speaker field is a powerful, general-purpose feature for tracking any conversation involving multiple participants. This could be a meeting with several attendees, a group chat, or a formal debate. By assigning a unique identifier to each speaker, you provide the AI with a clear record of who said what, enabling more sophisticated understanding and interaction.

Below is an example of how to structure a formal debate, but the same principle applies to any multi-speaker scenario.

{
  "tool_name": "chat",
  "arguments": {
    "userId": 789, // Represents the "debate room"
    "messages": [
      { "role": "user", "speaker": "Moderator", "content": "Let's begin. Alice, your opening statement." },
      { "role": "user", "speaker": "Alice", "content": "My position is that AI will create more jobs than it displaces." },
      { "role": "user", "speaker": "Bob", "content": "I disagree. The scale of automation is unprecedented." }
    ]
  }
}