mnemosyne-oss/mnemosyne installation guide

Install Mnemosyne for Claude Code on macOS Tahoe (Apple silicon)

What you are installing

Mnemosyne is a local-first memory system backed by SQLite. For Claude Code, the repository documents an **MCP (Model Context Protocol) integration**: Claude Code starts the `mnemosyne` program as a local MCP server and receives memory tools from it.

**Classification:** Claude Code extension via an MCP **tool surface** (`installMode: claude_extension`). It is not evidenced as a Claude Code plugin, hook, or skill. The reliable mechanism in the supplied first-party files is a local stdio MCP server configured in `claude.json`.

The documented MCP quick start exposes three tools:

• `mnemosyne_remember` — store a memory
• `mnemosyne_recall` — search memories
• `mnemosyne_forget` — remove a memory

This guide assumes Claude Code is already installed. The supplied repository files do not document how to install Claude Code or name a minimum Claude Code version.

Before you begin

You need:

• A Mac running macOS Tahoe on Apple silicon.
• Python 3.10 or later.
• Claude Code already installed.
• Internet access while Python downloads the package from PyPI.

The repository does not require a cloud account or API key for the basic local setup. It also does not document any required Rosetta, Homebrew, Docker, Node.js, or Xcode installation for this MCP route.

If Python is not installed, obtain Python 3.10 or later from the official Python website. The repository does not supply a macOS package-manager command, so none is included here.

1. Open Terminal

Open **Terminal** from macOS. The following approach uses a Python virtual environment. A virtual environment keeps Mnemosyne separate from other Python applications and avoids changing Apple-managed Python packages.

The virtual environment will be created as a hidden `.venv` folder in Terminal’s current directory. Run:

python3 -m venv .venv
source .venv/bin/activate

After activation, Terminal commonly shows `(.venv)` near the prompt. Keep this Terminal window open for the installation and checks below.

If the first command reports that `python3` is missing, stop and install Python 3.10 or later before retrying. If environment creation fails because the Python installation lacks virtual-environment support, repair or replace that Python installation; the supplied project files do not document a macOS-specific repair command.

2. Install the MCP-enabled package

For Claude Code, install the documented `mcp` extra:

pip install "mnemosyne-memory[mcp]"

Wait for the installation to finish. Do not close Terminal or deactivate `.venv` yet.

The repository also documents a larger all-features package:

pip install "mnemosyne-memory[all]"

You do **not** need to run both commands. The `mcp` installation is the focused choice for this guide. The `[all]` profile adds local embeddings and local-LLM dependencies; the repository estimates about 1.5 GB of RAM for that profile and recommends 8 GB or more. Use it only if you want those optional features.

3. Verify the command-line installation

With `.venv` still active, ask Mnemosyne for database statistics:

mnemosyne stats

A normal statistics response confirms that the `mnemosyne` executable can start and reach its local SQLite storage. By default, the main README’s configuration table places data under:

`~/.hermes/mnemosyne/data`

You can optionally perform a small write-and-search test. These commands deliberately add a test memory to the database:

mnemosyne store "User likes dark mode"
mnemosyne recall "preferences"

The recall result should include or refer to the stored preference. This checks the application independently of Claude Code.

Mnemosyne is local-first by default and reports no telemetry. However, the repository warns that memory text and recall queries can leave the Mac if you later configure remote embeddings, sync, or external LLM services. No such remote service is configured by the MCP JSON below.

4. Add Mnemosyne to Claude Code

The repository says Claude Code uses `claude.json`, but the supplied files do not give a reliable macOS path for that file. Open the Claude Code configuration file appropriate to your existing installation rather than guessing a location.

Add the following source-provided MCP configuration:

{
  "mcpServers": {
    "mnemosyne": {
      "command": "mnemosyne",
      "args": ["mcp"],
      "env": {}
    }
  }
}

If `claude.json` is empty, the block can be the entire file. If it already contains settings or other MCP servers, merge the `mnemosyne` entry into the existing `mcpServers` object. Do not create a second top-level `mcpServers` key, remove existing servers, add comments, or leave trailing commas; JSON does not permit comments or trailing commas.

The `command` value relies on `mnemosyne` being available on the process PATH. Because this guide installed it in `.venv`, activate that environment in the Terminal session from which you start Claude Code. The project README explicitly says that an isolated virtual environment must be activated, or its `bin/mnemosyne` executable must be invoked. The supplied Claude configuration only documents the command name `mnemosyne`, so this guide does not invent an absolute-path configuration.

5. Restart and test Claude Code

After saving `claude.json`, fully stop and restart Claude Code from the Terminal environment in which `.venv` is active. This allows Claude Code to inherit the PATH containing the installed `mnemosyne` command and to load the new MCP server configuration.

In a new Claude Code conversation, ask it to remember a harmless preference, such as your preferred test framework. Then ask what it remembers about that preference. Claude Code should use the Mnemosyne MCP tools rather than relying only on the current chat.

Use non-sensitive test data first. The database is local, but anyone or any process with access to your macOS account and database files may be able to read unencrypted local memory content. The repository specifically says you are responsible for what is stored.

Troubleshooting

Claude Code cannot find `mnemosyne`

The most likely issue with this virtual-environment setup is that Claude Code was started without `.venv` active. Return to the installation directory and run:

source .venv/bin/activate

Then verify again:

mnemosyne stats

If that succeeds, restart Claude Code from the same activated Terminal environment.

The package is installed, but MCP does not appear

Check that:

1. The configuration is valid JSON.
2. `mnemosyne` is nested under `mcpServers`.
3. The command is exactly `mnemosyne` and its single argument is exactly `mcp`.
4. Claude Code was restarted after the file was saved.
5. `mnemosyne stats` works in the environment used to start Claude Code.

You can start the documented stdio server directly for diagnosis:

mnemosyne mcp

An stdio MCP server may appear to wait silently because it expects an MCP client to communicate over standard input and output. Stop that diagnostic process using Terminal’s normal interrupt action before restarting Claude Code.

Upgrade later

The repository documents this upgrade command:

pip install --upgrade mnemosyne-memory

Run it while `.venv` is active. Restart Claude Code afterward so the next MCP process uses the updated package.

macOS Tahoe and Apple-silicon caveat

The supplied files state Python 3.10+ support and document macOS use, but they do not provide a Tahoe-specific test result, an Apple-silicon compatibility matrix, or a minimum Claude Code version. This guide therefore uses only the repository’s platform-neutral Python and MCP route and does not add undocumented architecture flags or compatibility commands.

At this point, Mnemosyne is installed locally, its CLI has been checked, and Claude Code is configured to launch it as an MCP memory server.