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.

Variable	Default (ollama)	Default (openai)	Description
MNEMO_EMBEDDING_PROVIDER	ollama	—	ollama or openai
MNEMO_EMBEDDING_MODEL	nomic-embed-text	text-embedding-3-small	Model name
MNEMO_EMBEDDING_BASE_URL	http://localhost:11434	https://api.openai.com	API base URL
MNEMO_EMBEDDING_API_KEY	—	(required)	API key for cloud providers
MNEMO_DIMENSIONS	768	1536	Embedding vector dimensions
MNEMO_DB_PATH	~/.mnemo/memory.db	~/.mnemo/memory.db	SQLite database path

Supported Clients

Works with any app that supports the Model Context Protocol:

Client	Platform	Notes
Claude Desktop	Mac, Windows	Local + remote MCP servers
Claude Code	Terminal	Full MCP support
Claude.ai	Web	Remote MCP servers
ChatGPT	Web	Developer Mode (Pro/Plus/Business/Enterprise)
Cursor	Mac, Windows, Linux	AI code editor
Windsurf	Mac, Windows, Linux	AI code editor
VS Code	Mac, Windows, Linux	Via Continue, Cline, or Copilot-MCP extensions
Codex (OpenAI)	Terminal	CLI coding agent
Amazon Q	Terminal, IDEs	AWS coding assistant
Zed	Mac, Linux	Code editor with MCP support
BoltAI	Mac, iOS	Multi-provider AI chat
Chatbox	Mac, Windows, Linux, Web	Open-source AI chat (37K+ stars)

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

Tool	Description
remember	Store a memory with tag, categories, and namespace
remember_batch	Store multiple memories in a single call (batch embedding)
recall	Semantic search by query (default 10 results, no hard cap)
forget	Delete a memory by ID
update	Patch an existing memory's content or metadata (re-embeds if content changes)
bump	Reinforce a memory's weight (+0.1 default)
decay	Run a decay cycle (tag-based weight reduction)
inspect	View a specific memory or aggregate stats

Decay System

Memories have a tag that controls how fast they fade:

Tag	Rate	Use case
core	0.0	Never decays — identity, values
crucial	0.01/cycle	Slow decay — relationships, key facts
default	0.05/cycle	Normal decay — conversations, observations

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

• [x] Pluggable embedding backends (Ollama local, OpenAI-compatible API)
• [x] 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