Labsco
Marsmanleo logo

MarsNMe

★ 6

from Marsmanleo

Agent-agnostic persistent memory backend. 13 MCP tools, Supabase + Jina embeddings, multi-profile isolation, semantic recall across sessions.

🔥🔥✓ VerifiedAccount requiredAdvanced setup
#email#automation#database#cloud#devops#git#search#security

English | 繁體中文（台灣） | 繁體中文（香港） | 简体中文

marsnme.com — Claude.md is for context. MarsNMe is for continuity.

Your AI tools should know you — not start from scratch every time. When Perplexity helps you decide, Claude should remember why. When Cursor ships a feature, Warp should know the context. That's not context sharing. That's continuity.

Most AI memory tools help AI remember you. MarsNMe helps you and your AI remember each other — across sessions, across tools, over time.

An agent-agnostic, LLM-agnostic memory backend for MCP-compatible tools.

Copy & paste — that's it
curl -fsSL https://marsnme.com/install.sh | bash

Real user story

I use Cursor to code, Warp to deploy, Perplexity to research, and Claude Code to manage my vault. Before MarsNMe, every tool started blank — I had to re-explain my project, my preferences, my decisions every single session. Now my AI across all four tools knows what we decided yesterday, what we tried last week, and why we chose this architecture over that one. It's not about injecting context. It's about having a relationship that compounds over time.

— Leo, MarsNMe creator (3 months of daily use across 4 AI tools)

Available MCP Tools (13)

Tool Description insert_memory Store short-term memory list_memories List recent memories search_memories Semantic search via Jina embeddings recall Long-term chunk recall from profile schema memory_ingest Ingest long-term insight chunks dream_ingest Dream-mode long-term ingestion session_boot Start a session with context pre-load session_close Close session and summarize health_check Coverage, expiry, conflict diagnostics reload_source_registry Refresh source whitelist at runtime demote_memory Demote a memory to lower priority soft_forget Soft-delete a memory explain_memory Explain a memory's provenance

MarsNMe

Why MarsNMe?

Most AI memory tools help AI remember you. MarsNMe helps you and your AI remember each other.

MarsNMe Typical memory tool Philosophy Mutual continuity — human + AI both grow AI-side context injection only Agent support Any MCP-compatible client Often client-specific Memory tiers Short-term (TTL) + long-term (semantic) Usually one layer Profiles Unlimited isolated profiles via MCP_PROFILE Single-user only Data ownership Your own Supabase — zero vendor lock-in Vendor-hosted Search Jina v3 semantic search (1024-dim pgvector) Keyword or basic similarity Self-hostable ✅ Full control Rarely

When MarsNMe is the right fit

  • You use multiple AI assistants (Claude, Cursor, Perplexity, Warp, custom agents) and want shared memory across all of them

  • You want AI that remembers your projects, preferences, and decisions across sessions without re-explaining

  • You care about data sovereignty — your memories stay in your own Supabase project

  • You're building an AI agent and need a production-ready memory backend with semantic recall

When it might not be the right fit

  • You only need single-session context (just use the system prompt)

  • You want fully managed, zero-config memory with no setup (try a hosted solution)

Repository Packages

Package Description soul-memory/ Core MCP gateway — agent-agnostic memory backend (this package is published to npm as @marsnme/mcp-gateway) soul-memory/cloudflare-routing-worker/ Cloudflare Worker for mcp.marsnme.com — username-based MCP routing proxy with setup wizard marsnme-local/ Self-hosted MCP memory server on Cloudflare Workers + D1 + Vectorize (no Supabase needed)

Before You Start (External Dependencies)

  • Create a Supabase project (free plan is enough):

  • Sign up: https://supabase.com

  • Create project: https://supabase.com/dashboard/new

  • Open API settings (Project Settings → API):

  • Project URL → SUPABASE_BASE_URL

  • service_role key → SUPABASE_SERVICE_ROLE_KEY

  • Keep SUPABASE_SERVICE_ROLE_KEY private. Never commit it.

  • Create a Jina API key (free tier available):

  • Get key: https://jina.ai/api-key/

  • Copy key to JINA_API_KEY

Try In 30 Seconds (Docker, M1)

If you only want a local demo path, use Docker Compose.

One-line install (recommended):

Copy & paste — that's it
curl -fsSL https://marsnme.com/install.sh | bash

Or manually:

  • Set only the required key:
Copy & paste — that's it
cp .env.example .env
# fill JINA_API_KEY in .env
  • Start local stack:
Copy & paste — that's it
docker compose up

This starts:

  • PostgreSQL + pgvector

  • SQL migrations from supabase/migrations/

  • PostgREST + rest-proxy

  • MarsNMe gateway (http://127.0.0.1:18790/mcp)

  • Verify health:

Copy & paste — that's it
curl -sS http://127.0.0.1:18790/health

M2 Cloudflare Tunnel Profile (Demo)

When you need a temporary public endpoint for remote AI tools:

Copy & paste — that's it
docker compose --profile tunnel up

Expected output (from tunnel logs):

Copy & paste — that's it
https://xxxx.trycloudflare.com

Get MCP endpoint:

Copy & paste — that's it
docker compose --profile tunnel logs tunnel | grep -Eo 'https://[^ ]+trycloudflare.com' | head -n1
# append /mcp

Notes:

  • trycloudflare.com URL is temporary (demo only).

  • Local endpoint remains: http://127.0.0.1:18790/mcp.

  • For production/stable URL, use named tunnel (outside M2 scope).

  • Optional env:

  • MCP_TUNNEL_PROFILE (default coco)

  • MCP_TUNNEL_REQUIRE_BEARER (default false for demo convenience)

MCP Client Connection Guide

Local endpoint:

  • http://127.0.0.1:18790/mcp

If bearer auth is enabled (MCP_REQUIRE_BEARER=true), include:

  • Authorization: Bearer <your-token>

Claude Desktop

  • Open claude_desktop_config.json (macOS default path: ~/Library/Application Support/Claude/claude_desktop_config.json).

  • Add/update:

Copy & paste — that's it
{
 "mcpServers": {
 "marsnme-local": {
 "url": "http://127.0.0.1:18790/mcp"
 }
 }
}
  • Restart Claude Desktop.

Cursor

  • Open Cursor Settings and search for MCP.

  • Add a new server:

  • Name: marsnme-local

  • URL: http://127.0.0.1:18790/mcp

  • Headers: optional bearer header if enabled

  • Reconnect MCP in Cursor.

Warp

  • Open Settings > Agents > MCP servers.

  • Add a server pointing to:

  • URL: http://127.0.0.1:18790/mcp

  • Add optional bearer header if required, then reconnect.

Perplexity

  • Open a Space in Perplexity and go to Space Settings.

  • Under MCP servers, add:

  • URL: http://127.0.0.1:18790/mcp

  • Save and start a new conversation in that Space.

Any MCP client (generic HTTP/SSE)

Use a streamable HTTP/SSE MCP entry:

Copy & paste — that's it
{
 "marsnme-local": {
 "url": "http://127.0.0.1:18790/mcp"
 }
}

First Connection Validation (Round Trip)

After client connection, verify this sequence once:

  • tools/list:
Copy & paste — that's it
curl -sS http://127.0.0.1:18790/mcp \
 -H 'content-type: application/json' \
 -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
  • insert_memory:
Copy & paste — that's it
curl -sS http://127.0.0.1:18790/mcp \
 -H 'content-type: application/json' \
 -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"insert_memory","arguments":{"body":"quickstart memory check","source":"warp","session_id":"quickstart-smoke"}}}'
  • recall:
Copy & paste — that's it
curl -sS http://127.0.0.1:18790/mcp \
 -H 'content-type: application/json' \
 -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"recall","arguments":{"query":"quickstart memory check","limit":3}}}'

What this repository is

mars-memory-mcp is the core MCP gateway repository behind the public-facing MarsNMe release. One codebase (soul-memory/server.mjs) serves multiple profile schemas through MCP_PROFILE. This public repository currently keeps two built-in legacy profile IDs (coco, toto) for backward compatibility.

Current capabilities

  • MCP methods: initialize, notifications/initialized, tools/list, tools/call, ping

  • Profiles: configurable profile IDs (legacy built-ins: coco, toto)

  • Memory tools:

  • insert_memory (short-term memory)

  • list_memories

  • search_memories (Jina embedding search)

  • recall (long-term chunk recall from profile schema)

  • memory_ingest / dream_ingest (long-term chunk ingestion)

  • session_boot / session_close (daily rhythm lifecycle)

  • health_check (coverage, expiry, conflict diagnostics)

  • reload_source_registry (refresh source whitelist at runtime)

  • demote_memory / soft_forget / explain_memory (memory lifecycle management)

  • OAuth-protected MCP endpoint (configurable by environment variables)

Memory model

  • Short-term memory table: <profile>.memories

  • Long-term memory table: <profile>.marsvault_chunks

  • Recommended usage:

  • Keep daily interaction context in insert_memory

  • Promote durable insights through ingest tools

Repository layout

  • soul-memory/server.mjs — gateway entry point

  • soul-memory/scripts/hermes_digest_runner.py — optional digest runner

  • soul-memory/scripts/dream_runner.py — public self-host dream runner

  • soul-memory/deploy/systemd/ — systemd templates

  • soul-memory/deploy/phase2/ — build/deploy scripts

  • soul-memory/deploy/phase3/smoke_gate.sh — smoke gate script

  • supabase/migrations/ — schema-as-code migrations

Onboarding

  • Zero-to-first-recall guide: docs/onboarding-a-mcp-zero-to-recall.md

  • Platform install guide (optional skill layer): docs/onboarding-b-platform-skill-install.md

Skill library

  • Skill index and update workflow: skills/README.md

  • Perplexity template: skills/perplexity/memory-daily-boot/SKILL.md

  • Cursor template: skills/cursor/memory-daily-boot/rule.mdc

  • Warp template: skills/warp/memory-daily-boot/prompt.md

Local run (from cloned repo)

Copy & paste — that's it
MCP_PROFILE=profile-a npx @marsnme/mcp-gateway
Copy & paste — that's it
MCP_PROFILE=profile-b npx @marsnme/mcp-gateway

Health endpoints:

  • GET /health

  • POST /mcp

Security and version control

  • Never commit .env, runtime tokens, or oauth-clients.json

  • Keep .env.example committed as the only environment template

  • Prefer bearer/OAuth for public exposure

License and policy

  • License: Apache-2.0 (LICENSE)

  • Notice: NOTICE

  • Trademark policy: TRADEMARK.md

  • Contribution guide: CONTRIBUTING.md

  • Contributor agreement: CLA.md

  • Release notes: CHANGELOG.md