mem-persistence

🧠 Persistent memory MCP server for AI agents — one memory, every agent, your files.

mem-persistence lets Claude Desktop, Claude Code, Cursor, Zed, and any MCP-compatible client share the same persistent memory, backed by plain Markdown files you own and can edit by hand.

Why?

AI agents have amnesia. Each tool keeps its own silo — Claude Code forgets what OpenClaw knows, Cursor can't recall what you told Claude yesterday. Your context is scattered across sessions that evaporate.

mem-persistence fixes this:

• Markdown is the source of truth — not a database, not a binary blob. Files you can read, edit, and version with git.

• Hybrid search — token matching + semantic embeddings for accurate recall.

• Embedding providers — Gemini (free), OpenAI, or none (token-only). Cached to disk.

• Deduplication — prevents writing the same fact twice (token + entity overlap detection).

• Works offline — no cloud dependency. Embeddings are optional.

Related MCP server: HKC Memory Server

MCP Tools

Facts are stored in data/facts.db (built-in node:sqlite), separate from the markdown corpus — exact key-value recall for names, settings, and IDs that semantic search handles badly.

Quick Start

1. Install and build

git clone https://github.com/emiliotorrens/mem-persistence.git
cd mem-persistence
npm install
npm run build

2. Start the server

node dist/index.js --workspace /path/to/your/workspace --port 3456

3. Connect a client

Pick the setup that matches your client — see Client Setup below.

4. Add agent instructions

Copy AGENT_INSTRUCTIONS.md into your agent's instruction file:

Client Setup

There are two MCP transports. Which one you need depends on the client:

HTTP clients (Claude Code, Cursor, Zed)

Point to the running server URL:

{
  "mcpServers": {
    "memory": {
      "url": "http://127.0.0.1:3456/mem-persistence/mcp"
    }
  }
}

For remote access over Tailscale, replace 127.0.0.1 with the server's Tailscale hostname:

{
  "mcpServers": {
    "memory": {
      "url": "http://my-machine.tail1234.ts.net:3456/mem-persistence/mcp"
    }
  }
}

Claude Desktop (stdio, same machine)

Claude Desktop only supports stdio — it spawns mem-persistence as a child process.

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": [
        "/path/to/mem-persistence/dist/index.js",
        "--workspace", "/path/to/your/workspace"
      ],
      "env": {
        "MEM_PERSISTENCE_EMBEDDINGS": "gemini",
        "GOOGLE_API_KEY": "your-key-here"
      }
    }
  }
}

WSL users (Windows): replace "command": "node" with "command": "wsl" and add "node" as the first element of args.

⚠️ Do not pass --port in stdio mode. It causes an EADDRINUSE conflict if an HTTP instance is already running.

Remote Claude Desktop via proxy

If Claude Desktop runs on a different machine (e.g., a laptop) where mem-persistence isn't installed, use the bundled mcp-proxy.js to bridge stdio to the remote HTTP server.

Requirements on the client machine: Node.js + Tailscale. That's it — no cloning, no npm install.

1. Copy mcp-proxy.js to the laptop (one file, zero dependencies).

2. Add to Claude Desktop config:

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/path/to/mcp-proxy.js"],
      "env": {
        "MCP_REMOTE_URL": "http://my-machine.tail1234.ts.net:3456/mem-persistence/mcp"
      }
    }
  }
}

Desktop thinks it's talking to a local stdio server; the proxy forwards everything over HTTP.

Set MCP_DEBUG=1 to log proxy traffic to stderr for troubleshooting.

Running as a Service (PM2)

For production use, run the server as a persistent background service with PM2:

# 1. Install pm2
npm install -g pm2

# 2. Copy and edit the config
cp ecosystem.config.cjs.example ecosystem.config.cjs
# → Set workspace path and optional API keys

# 3. Start and persist
pm2 start ecosystem.config.cjs
pm2 save
pm2 startup    # autostart on reboot (follow the printed instructions)

Health check: curl http://127.0.0.1:3456/health

Network Binding

By default, the server listens on 127.0.0.1 only. Use --bind to control which interfaces it binds to:

# Localhost + Tailscale (recommended for remote access)
node dist/index.js --workspace /path --port 3456 --bind 127.0.0.1,tailscale

# Localhost + explicit VPN IP
node dist/index.js --workspace /path --port 3456 --bind 127.0.0.1,10.0.0.5

# All interfaces (⚠️ only behind a firewall)
node dist/index.js --workspace /path --port 3456 --bind all

In ecosystem.config.cjs:

args: '--workspace /path --port 3456 --bind 127.0.0.1,tailscale',

Or via environment variable: MEM_PERSISTENCE_BIND=127.0.0.1,tailscale

⚠️ Security: mem-persistence has no built-in authentication. Never expose the port to the public internet. Use --bind 127.0.0.1,tailscale to limit access to localhost + your private network.

Workspace

The --workspace flag points to the directory containing your memory files. mem-persistence indexes all .md files recursively.

Any directory with .md files works. Search quality improves with a layered layout:

For automatic setup of this structure (with crons, dedup, and knowledge graph), see layered-memstack.

You can also set the workspace via environment variable: MEM_PERSISTENCE_WORKSPACE=/path/to/workspace

Embeddings

By default, search uses token matching only (Jaccard + containment + entity overlap). No API calls, works offline.

Enabling embeddings adds semantic understanding:

Get a free Gemini API key → aistudio.google.com → Get API key.

Configure via environment variables:

MEM_PERSISTENCE_EMBEDDINGS=gemini    # "gemini" or "openai"
GOOGLE_API_KEY=your-key              # Gemini — free
OPENAI_API_KEY=your-key              # OpenAI — $0.02/M tokens

Details:

• Hybrid scoring: 0.4 × token + 0.6 × vector

• Disk cache: .mem-persistence/embeddings/ — no repeated API calls

• Default model: gemini-embedding-001 (free, 1500 req/min)

• Silent fallback: if API unavailable, falls back to token-only automatically

Deduplication

Before writing, mem-persistence checks if similar content already exists:

Input:  "GitHub configured with gh auth login, user emiliotorrens"
Match:  "gh auth login hecho — cuenta emiliotorrens, protocolo HTTPS"
Result: DUPLICATE (score: 0.90) — not written

Uses token similarity (Jaccard + containment) and entity overlap (IDs, dates, versions, URLs).

Adjust the threshold: MEM_PERSISTENCE_DEDUP_THRESHOLD=0.65 (default — lower = stricter).

OpenClaw Integration

If you use OpenClaw, mem-persistence coexists with OpenClaw's native memory:

• External clients (Claude Desktop, Code, Cursor) → connect via mem-persistence (stdio or HTTP)

• OpenClaw agent → uses its native memory-core plugin with hybrid search + embeddings

Both systems index the same Markdown files. mem-persistence is the MCP bridge for external clients; OpenClaw handles its own recall, wiki compilation, and dreaming.

Roadmap

• Deduplication engine

• Hybrid search (token + vector + MMR + temporal decay)

• MCP server — stdio and HTTP transports, 6 tools, TypeScript + ESM

• Embedding providers: Gemini (free) and OpenAI, with disk cache

• Request/response logging (.mem-persistence/logs/)

• HTTP mode — Tailscale-friendly, pm2-ready

• stdio→HTTP proxy for remote Claude Desktop

• CLI (mem-persistence search "query")

• Local embeddings via transformers.js (offline, no API key)

• npm publish

Related

• layered-memstack — OpenClaw skill that sets up a 3-layer memory system with automated maintenance. Uses mem-persistence as the MCP bridge for external clients.

Credits

• OpenClaw — the agent framework where this was born and battle-tested

• MCP — the protocol that makes cross-agent memory possible

License

MIT

Built with 🐾 by Emilio Torrens and Claw.