MarsNMe

**English** | [繁體中文（台灣）](docs/README.zh-TW.md) | [繁體中文（香港）](docs/README.zh-HK.md) | [简体中文](docs/README.zh-CN.md)

---

**[marsnme.com](https://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.

```bash
curl -fsSL https://marsnme.com/install.sh | bash
```

[![MarsNMe on Glama](https://glama.ai/mcp/servers/Marsmanleo/MarsNMe/badges/score.svg?v=2026-06-10)](https://glama.ai/mcp/servers/Marsmanleo/MarsNMe/score) [![npm version](https://img.shields.io/npm/v/@marsnme/mcp-gateway?color=%23E5484D&label=npm)](https://www.npmjs.com/package/@marsnme/mcp-gateway) [![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-%2300A67E?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTNTMTcuNTIgMiAxMiAyem0tMSAxN1Y5bDQgNHY0aC00eiIvPjwvc3ZnPg==)](https://registry.modelcontextprotocol.io/v0.1/servers?search=marsnme) [![LobeHub](https://lobehub.com/badge/mcp/marsmanleo-marsnme)](https://lobehub.com/mcp/marsmanleo-marsnme) [![npm downloads](https://img.shields.io/npm/dm/@marsnme/mcp-gateway?color=%23E5484D&label=downloads)](https://www.npmjs.com/package/@marsnme/mcp-gateway) [![License](https://img.shields.io/badge/license-Apache--2.0-%23D22128)](LICENSE) [![GitHub stars](https://img.shields.io/github/stars/Marsmanleo/MarsNMe?style=social)](https://github.com/Marsmanleo/MarsNMe)

<p align="center">
  <img src="docs/assets/demo.gif" alt="MarsNMe dark mode demo" width="640" />
</p>
<p align="center">
  <img src="docs/assets/demo-light.gif" alt="MarsNMe light mode demo" width="640" />
</p>


<p align="center">
  <img src="docs/assets/social-concept.png" alt="MarsNMe — Your AI finally remembers you" width="720" />
</p>
<p align="center">
  <img src="docs/assets/social-compare.png" alt="Without vs With MarsNMe" width="480" />
  &nbsp;&nbsp;
  <img src="docs/assets/social-arch.png" alt="How MarsNMe works" width="480" />
</p>

## 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 (16)

| 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 — ~80-char preview per match |
| `get_summary` | Medium excerpt (~300 chars) of a chunk by ID |
| `get_full` | Complete text of a long-term chunk by ID |
| `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, summarize, auto-promote expiring memories |
| `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 |
| `batch_promote` | Promote expiring short-term memories to long-term |

## What's new in 0.3.0

- **3-layer recall**: `recall` returns ~80-char previews, then `get_summary` (~300 chars), then `get_full` (complete). Avoids token-dumping full chunks on every recall; drill down only when a preview looks relevant.
- **Body-to-body note handoff**: `session_close(to=<body>, note=...)` leaves a note that `session_boot(body=<target>)` delivers and marks read — one agent can hand context to another.
- **Auto `batch_promote` on `session_close`**: closing a session automatically promotes soon-expiring short-term memories (48h window, up to 5) to long-term storage — no Hermes or manual promote needed.
- **`grok` + `draft` sources**: added to the source whitelist so the Grok body and Draft lifecycle hooks can write memories natively.
- **CoCo-only tool surface**: PRD tools (`save_prd`, `get_prd`, `list_prds`, `score_prd`, `spawn_to_linear`) removed from the Supabase gateway — idea/PRD/task execution now lives in [Draft](https://github.com/Marsmanleo/draft-ai). MarsNMe = CoCo soul memory only.

# 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)

## Runtime packages

| Folder | Runtime | Who uses it |
|---|---|---|
| `marsnme-supabase/` | Supabase + Jina gateway (`@marsnme/mcp-gateway`) | **Mars Group dogfood** — Proxmox CT101 (CoCo / Toto soul memory) |
| `marsnme-cf/` | Cloudflare Workers + D1 + Vectorize | Self-host template; **not** the Proxmox deploy path |
| `marsnme-supabase/cloudflare-routing-worker/` | `mcp.marsnme.com` routing proxy | Public setup wizard → upstream gateway |

**Product split (Mars Group):** Idea / PRD / task execution → [Draft](https://github.com/Marsmanleo/draft-ai) + `draft-mcp`. **MarsNMe Supabase = CoCo soul memory only** (recall, session boot/close, ingest, lifecycle). As of `@marsnme/mcp-gateway` v0.3.0, PRD MCP tools (`save_prd`, `get_prd`, `list_prds`, `score_prd`, `spawn_to_linear`) are removed from the Supabase gateway — use Draft for idea/PRD/task workflows.

**Proxmox deploy:** private [MarsNMe-lab](https://github.com/Marsmanleo/MarsNMe-lab) — `deploy/deploy-proxmox-ct101.sh` or GitHub `cd-selfhosted` workflow. Not a single-script deploy like draft-mcp.

## Repository Packages

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

## Quick Setup (no install needed)

Go to **[mcp.marsnme.com/setup](https://mcp.marsnme.com/setup)** — create your personal MCP URL in 4 steps:

1. Pick a username
2. Enter your Supabase credentials (URL + anon key)
3. Choose preferences
4. Get your MCP URL: `https://mcp.marsnme.com/your-name`

Then add it to any MCP client (Claude, Cursor, Perplexity, Warp).

**Self-hosted?** Deploy [`marsnme-cf/`](marsnme-cf/) to your own Cloudflare account — no Supabase needed, uses D1 + Workers AI + Vectorize.

---

## Before You Start (External Dependencies)
1. 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.
2. Create a Jina API key (free tier available):
   - Get key: https://jina.ai/api-key/
   - Copy key to `JINA_API_KEY`

## Quick Start (15-20 minutes)
For the fastest path, use the one-line installer: `curl -fsSL https://marsnme.com/install.sh | bash`

The manual path below follows the same tools-first flow as `docs/onboarding-a-mcp-zero-to-recall.md` and `docs/onboarding-b-platform-skill-install.md`.
1. Clone repository:
```bash
git clone https://github.com/Marsmanleo/MarsNMe.git
cd MarsNMe
```
2. Verify Node.js version (20+ required):
```bash
node --version
```
3. Copy environment template:
```bash
cp .env.example .env
```
4. Fill required values in `.env`:
   - `SUPABASE_BASE_URL`
   - `SUPABASE_SERVICE_ROLE_KEY`
   - `JINA_API_KEY`
5. Run required Supabase migrations before first start:
   - Option A (recommended, Supabase CLI):
```bash
npx supabase db push --db-url "<your-supabase-db-connection-string>"
```
   - Note: `--db-url` must be the Postgres database connection string from `Project Settings → Database → Connection string`.
   - It is not the same as `SUPABASE_BASE_URL` (`https://<project-ref>.supabase.co`, REST API URL).