mnemo-mcp

Portable cognitive memory for AI agents. An MCP server with semantic search and decay.

What it does

Gives any MCP-compatible AI agent persistent memory that behaves like human memory:

• Memories decay unless reinforced — noise fades, important things stick

• Deduplication — same content bumps weight instead of duplicating

• Namespaced — multiple agents can share or isolate their memories

• Semantic search — find memories by meaning, not keywords

• Pluggable embeddings — Ollama (local) or any OpenAI-compatible API

• Multi-agent — author tracking so you know who remembered what

Quick start

npx mnemo-mcp

Node version note: mnemo uses native addons (better-sqlite3, sqlite-vec) that are compiled for a specific Node ABI version. If you switch Node versions (e.g. via nvm), the cached npx install may break. Fix: rm -rf ~/.npm/_npx/ && npx -y mnemo-mcp, or use one of the stable install methods below.

Stable install (recommended for MCP clients)

For MCP clients like Claude Code or Claude Desktop, a global install avoids npx cache issues:

npm install -g mnemo-mcp

Then configure your client with "command": "mnemo-mcp" instead of npx.

Alternatively, run from source:

git clone https://github.com/skye-flyhigh/mnemo-mcp.git
cd mnemo-mcp && npm install && npm run build

Then point your client to "command": "node", "args": ["/path/to/mnemo-mcp/dist/cli.js"].

CLI commands

Consult help

npx mnemo-mcp help

Help section:

Usage:
  mnemo-mcp                              Start MCP server (default)
  mnemo-mcp export [--md] [--ns <ns>]    Export memories as JSON or markdown
  mnemo-mcp search <query> [-n <limit>]  Semantic search from terminal
  mnemo-mcp inspect [<id>] [--ns <ns>]   View a memory or aggregate stats
  mnemo-mcp decay                        Run a decay cycle
  mnemo-mcp count [--ns <ns>]            Quick count
  mnemo-mcp help                         Show this help

Options:
  --ns <namespace>    Filter by namespace
  --md                Export as markdown (default: JSON)
  -n <number>         Limit search results (default: 10)

Environment:
  MNEMO_DB_PATH                 Database path (default: ~/.mnemo/memory.db)
  MNEMO_EMBEDDING_PROVIDER      ollama | openai (default: ollama)
  MNEMO_EMBEDDING_MODEL         Model name
  MNEMO_EMBEDDING_BASE_URL      Provider URL
  MNEMO_EMBEDDING_API_KEY       API key (openai only)
  MNEMO_DIMENSIONS              Vector dimensions

Embedding provider

Ollama (default, local) — no API key needed, fully offline:

ollama pull nomic-embed-text

OpenAI-compatible (cloud) — set provider + API key in your MCP client config:

MNEMO_EMBEDDING_PROVIDER=openai
MNEMO_EMBEDDING_API_KEY=sk-...

This covers OpenAI, Azure OpenAI, Together AI, Voyage AI, Jina, and any service that speaks the /v1/embeddings format.

Configuration

All config is passed via env vars through your MCP client config. Defaults work out of the box with Ollama.

Supported Clients

Works with any app that supports the Model Context Protocol:

And 500+ more MCP clients. If your app supports MCP, mnemo works with it.

Client Setup Examples

Claude Code

Add to .claude.json (globally under "/Users/you" or per-project):

{
  "mcpServers": {
    "mnemo": {
      "type": "stdio",
      "command": "npx",
      "args": ["mnemo-mcp"],
      "env": {}
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mnemo": {
      "command": "npx",
      "args": ["mnemo-mcp"]
    }
  }
}

With OpenAI embeddings

Pass provider config through the env block:

{
  "mcpServers": {
    "mnemo": {
      "command": "npx",
      "args": ["mnemo-mcp"],
      "env": {
        "MNEMO_EMBEDDING_PROVIDER": "openai",
        "MNEMO_EMBEDDING_API_KEY": "sk-..."
      }
    }
  }
}

Tools

Decay System

Memories have a tag that controls how fast they fade:

Weight floor is 0.1 — memories never fully disappear.

Deduplication

Mnemo prevents memory drift with three layers of dedup:

1. Timing-based — identical content within 10 seconds is silently dropped

2. Hash-based — exact duplicate content bumps the existing memory's weight instead of duplicating

3. Semantic — if new content is very similar to an existing memory (vector distance < 0.12), the existing memory's weight is bumped instead

Roadmap

• Pluggable embedding backends (Ollama local, OpenAI-compatible API)

• Published to npm (npx mnemo-mcp)

• Register on MCP directories (Smithery, mcp.run)

• CLI companion for manual memory inspection/export

• Memory export/import (JSON)

License

MIT