MCP-Compatible · Open Source · Apache 2.0

# Claude.md is for context.
MarsNMe is for continuity.

Your AI tools should know you — not start from scratch every time. MarsNMe gives your AI persistent memory across sessions and tools, so you and your AI grow together.

Install via Agent → Set up MCP URL →
View on GitHub
13 MCP Tools
∞Profiles
1024 Embedding Dims
∞Memory Horizon
Why MarsNMe

## Context is what you write.
Continuity is what you live.

Claude.md records what you remember to write. MarsNMe records what actually happened — the decisions, the doubts, the near-misses. That's not context injection. That's a relationship.

Architecture

## Two layers of memory,
one coherent mind.

01

### Short-term Memory

Session context and recent interactions stored in `<profile>.memories`. Fast reads, ~30 day TTL.

02

### Long-term Knowledge

Semantic chunks ingested into `marsvault_chunks` with Jina v3 embeddings. Semantic recall via pgvector.

03

### Multi-Profile Architecture

One codebase, any number of agents. Set `MCP_PROFILE=my-agent` to route all reads and writes to isolated schemas.

04

### Schema-as-Code

All migrations live in `supabase/migrations/`. Reproducible deployments, version-controlled memory schema.

05

### Cloud Hosted or Self-Hosted

Use `mcp.marsnme.com/your-name` for zero-config cloud routing, or deploy `marsnme-local` to your own Cloudflare account for full self-hosting with D1 + Vectorize.

MarsNMe — multi profile
# Start your agent profile $ MCP_PROFILE=my-agent npx @marsnme/mcp-gateway ✓ MarsNMe MCP Gateway listening :18790 # Or run a second agent on another port $ MCP_PROFILE=assistant-b PORT=18791 npx @marsnme/mcp-gateway ✓ MarsNMe MCP Gateway listening :18791 # Health check $ curl http://localhost:18790/health { "status": "ok", "profile": "my-agent", "tools": 13, "uptime": 42 } $
Features

## Everything an agent needs
to remember.

Semantic Recall

Jina embeddings v3 with 1024 dimensions. Find memories by meaning, not just keywords. pgvector HNSW index for millisecond retrieval.

jina-embeddings-v3
Multi-Profile Isolation

Each agent gets its own schema. Same codebase, zero cross-contamination. Run unlimited profiles with isolated memory spaces.

MCP_PROFILE
Two-Tier Memory

Short-term session memory with TTL and long-term knowledge chunks that persist forever. Agents know what just happened and what always matters.

memories · marsvault_chunks
MCP Native

Full MCP protocol: initialize, tools/list, tools/call, ping. Drop into any MCP-compatible client — Cursor, Claude Desktop, Warp, or your own agent.

Model Context Protocol
Bearer Auth

Optional Bearer token enforcement via `MCP_REQUIRE_BEARER`. Secure your endpoint for production use.

production-ready
One Command Install

Install via npm. No cloning, no build steps. `npx @marsnme/mcp-gateway` and you're running.

npm · npx
Agent-Assisted Install
Installation

## One prompt.
Your agent installs the rest.

Paste the prompt below into your AI assistant. It will set up Supabase, configure your environment, and start MarsNMe automatically.

#### ① Paste agent prompt

Copy the install prompt and paste into your AI coding assistant. The agent handles Supabase setup, npm install, and environment config.

#### ② Fill your keys

Provide your `SUPABASE_BASE_URL`, `SUPABASE_SERVICE_ROLE_KEY` and `JINA_API_KEY`. Agent writes your `.env` file.

#### ③ Verify health

Agent runs `curl http://127.0.0.1:18790/health` to verify the gateway responds correctly.

#### ④ Configure your client

Add the MCP endpoint `http://127.0.0.1:18790/mcp` to your client config. Start remembering.

Agent Install Prompt

    # M1 local demo
    $ cp .env.example .env
    $ # fill JINA_API_KEY in .env
    $ docker compose up
    # local endpoint: http://127.0.0.1:18790/mcp
    # health: curl http://127.0.0.1:18790/health

    # M2 optional quick tunnel (demo only)
    $ docker compose --profile tunnel up
    # expected log: https://xxxx.trycloudflare.com
    # public MCP URL: https://xxxx.trycloudflare.com/mcp

Fastest trial path: Docker Desktop + JINA_API_KEY only.
trycloudflare.com URL is temporary and intended for demos.

    # Paste this into Cursor Agent (Cmd+L → Agent mode)

    Please install MarsNMe memory backend for my AI agent:
    1. Read the Quick Start at https://github.com/Marsmanleo/MarsNMe#quick-start
    2. Create a Supabase project (free plan) at https://supabase.com/dashboard/new
    3. Get a Jina API key at https://jina.ai/api-key/
    4. Run migrations from supabase/migrations/ in filename order
    5. Start: MCP_PROFILE=my-agent npx @marsnme/mcp-gateway
    6. Verify: curl http://127.0.0.1:18790/health
    7. Add to Cursor MCP settings:
       URL: http://127.0.0.1:18790/mcp
    Report health status when done.

Cursor Agent will handle the entire setup interactively.
It will ask for your keys at step 3 — never paste them directly.

    // claude_desktop_config.json
    {
      "mcpServers": {
        "marsnme": {
          "url": "http://127.0.0.1:18790/mcp"
        }
      }
    }

Add to ~/Library/Application Support/Claude/claude_desktop_config.json
First start the gateway: MCP_PROFILE=my-agent npx @marsnme/mcp-gateway

    # Warp MCP Server Settings

    Name: marsnme
    URL: http://127.0.0.1:18790/mcp

Open Settings → Agents → MCP servers and add the server above.
First start the gateway: MCP_PROFILE=my-agent npx @marsnme/mcp-gateway

    # Prerequisites: Node.js 20+, Supabase project, Jina API key

    $ npx @marsnme/mcp-gateway

    # Or with environment variables
    $ MCP_PROFILE=my-agent \
      SUPABASE_BASE_URL=https://xxx.supabase.co \
      SUPABASE_SERVICE_ROLE_KEY=your-key \
      JINA_API_KEY=your-key \
      npx @marsnme/mcp-gateway

    # Verify
    $ curl http://127.0.0.1:18790/health
    {"status":"ok","profile":"my-agent","tools":13}

Requires: Node.js 20+ · Supabase project · JINA_API_KEY

    # Option A: Cloud hosted (zero config)
    $ open https://mcp.marsnme.com/setup
    # → Create your MCP URL in 4 steps
    # → Get: https://mcp.marsnme.com/your-name

    # Option B: Self-hosted on Cloudflare (full control)
    $ cd marsnme-local
    $ npm install
    $ wrangler d1 create marsnme-local-db
    $ wrangler d1 execute marsnme-local-db --file=db/schema.sql
    $ wrangler vectorize create marsnme-local-vectors --dimensions=768 --metric=cosine
    $ wrangler deploy
    # your MCP endpoint: https://marsnme-local.your-name.workers.dev

Cloud hosted: No infrastructure needed. Supabase + our routing worker handles everything.
Self-hosted: Your own Cloudflare account. No Supabase needed — uses D1 + Workers AI + Vectorize.
Both paths expose the same 13 MCP tools.
API Reference

## 13 tools. Everything
your agent needs.

insert_memory

#### Write short-term memory SHORT

Store session context and recent interactions. Auto-routes to your profile's memories table. ~30 day TTL.

list_memories

#### List recent memories SHORT

Retrieve recent short-term memories in reverse chronological order. Supports limit and source filters.

search_memories

#### Semantic search short-term SHORT

Jina-powered semantic search over session memories. Returns similarity scores. Ideal for contextual lookups.

recall

#### Semantic recall long-term LONG

Deep semantic search over marsvault_chunks. Routes to your profile schema. Supports type, visibility, and similarity filters.

memory_ingest

#### Ingest long-term insight LONG

Chunk and embed insight content into marsvault_chunks. Supports visibility (private/shared/global), tags, and custom chunk sizes.

dream_ingest

#### Ingest digest content LONG

Specialized tool for ingesting structured digest reports as long-term knowledge. Auto-chunks and indexes for semantic retrieval.

session_boot

#### Session startup rhythm OPS

One-call session boot: identity recall, workflow status, health snapshot, and heartbeat sign-in. Run at session start.

session_close

#### Session close summary OPS

Store session close summary with configurable retention. Captures topics, mood, and key outcomes for next session.

health_check

#### Memory diagnostics OPS

Run coverage map, expiry alerts, and conflict detection across your memory tables. Essential for maintenance.

reload_source_registry

#### Reload source registry OPS

Refresh the memory source whitelist from configuration. Add or remove sources without restarting the gateway.

demote_memory

#### Demote long-term chunk LONG

Reduce the priority or visibility of a long-term memory chunk. Soft downgrade without permanent deletion.

soft_forget

#### Soft forget memory OPS

Mark a memory as forgotten without deleting it. The memory stays in storage but is excluded from normal recall.

explain_memory

#### Explain memory content OPS

Get a human-readable explanation of a specific memory entry. Shows metadata, source, tags, and relevance context.

Configuration

### Environment Variables

MCP_PROFILE required
Your profile identifier. Routes all reads/writes to the corresponding schema. Use any name you want.
SUPABASE_BASE_URL required
Supabase REST API project URL (e.g. https://xxx.supabase.co).
SUPABASE_SERVICE_ROLE_KEY required
Supabase service role key with schema access. Never expose in client-side code.
JINA_API_KEY required
Jina AI API key for generating embeddings. Required for search_memories, recall, and ingest tools.
PORT optional
Default: 18790. Override for running multiple profiles on different ports.
MCP_REQUIRE_BEARER optional
Set true for production. Enforces Bearer token auth on all MCP endpoints.
Open Source

## Your AI deserves to
remember you.

Apache 2.0. Self-host, fork, extend. Built by Mars Group — a Macau company building the future of human-AI symbiosis.

Star on GitHub → Open an Issue
Early Access

## Join the waitlist

Be the first to know about new features, integrations, and the future of AI memory.

No spam. Unsubscribe anytime. Powered by Listmonk.