MarsNMe
About
Agent-agnostic persistent memory backend. 13 MCP tools, Supabase + Jina embeddings, multi-profile isolation, semantic recall across sessions.
Details
- Author
- marsmanleo
- Categories
- AI, Other, Knowledge Base
Jump to
Setup
Install MarsNMe in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/marsmanleo/MarsNMe
Follow the installation instructions in the repository README, then restart your MCP client.
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.
curl -fsSL https://marsnme.com/install.sh | bash
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)
- 3-layer recall:recallreturns ~80-char previews, thenget_summary(~300 chars), thenget_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 thatsession_boot(body=<target>)delivers and marks read — one agent can hand context to another.
- Autobatch_promoteonsession_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+draftsources: 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 inDraft. MarsNMe = CoCo soul memory only.
Most AI memory tools help AI remember you.MarsNMe helps you and your AI remember each other.
- You use multiple AI assistants (Claude, Cursor, Perplexity, Warp, custom agents) and wantshared memory across all of them
- You want AI that remembers your projects, preferences, and decisionsacross sessionswithout re-explaining
- You care aboutdata sovereignty— your memories stay in your own Supabase project
- You're building an AI agent and need aproduction-ready memory backendwith semantic recall
- 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)
Product split (Mars Group):Idea / PRD / task execution →Draft+draft-mcp.MarsNMe Supabase = CoCo soul memory only(recall, session boot/close, ingest, lifecycle). As of@marsnme/mcp-gatewayv0.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:privateMarsNMe-lab—deploy/deploy-proxmox-ct101.shor GitHubcd-selfhostedworkflow. Not a single-script deploy like draft-mcp.
Go tomcp.marsnme.com/setup— create your personal MCP URL in 4 steps:
- Pick a username
- Enter your Supabase credentials (URL + anon key)
- Choose preferences
- Get your MCP URL:https://mcp.marsnme.com/your-name
Then add it to any MCP client (Claude, Cursor, Perplexity, Warp).
Self-hosted?Deploymarsnme-cf/to your own Cloudflare account — no Supabase needed, uses D1 + Workers AI + Vectorize.
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_rolekey →SUPABASE_SERVICE_ROLE_KEY
- Get key:https://jina.ai/api-key/
- Copy key toJINA_API_KEY
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 asdocs/onboarding-a-mcp-zero-to-recall.mdanddocs/onboarding-b-platform-skill-install.md.
git clone https://github.com/Marsmanleo/MarsNMe.git cd MarsNMe
- Fill required values in.env:
- SUPABASE_BASE_URL
- SUPABASE_SERVICE_ROLE_KEY
- JINA_API_KEY
npx supabase db push --db-url "<your-supabase-db-connection-string>"
- Note:--db-urlmust be the Postgres database connection string fromProject Settings → Database → Connection string.
- It is not the same asSUPABASE_BASE_URL(https://<project-ref>.supabase.co, REST API URL).
- Use a role that can execute DDL on your target schemas.
- On Supabase-hosted Postgres this is typicallysupabase_admin(notpostgres).
- Option B (Supabase Dashboard SQL Editor):
- Open SQL Editor.
- Ensure thevectorextension is enabled first (Database → Extensions).
- Run migration files in filename order fromsupabase/migrations/:
- 20260504052744_semantic_vector_dual_profile.sql
- 20260513213800_memory_lifecycle_tracking.sql
- 20260513222500_health_check_detect_conflicts_v2.sql
- 20260517183000_provenance_audit_trail.sql
- 20260517194000_memory_scope_agent_body_environment.sql
- 20260517200500_forget_demote_mechanism.sql
- 20260517223500_usage_cost_telemetry_light.sql
- 20260517231000_memories_source_constraint_regex.sql
- 20260517232000_source_registry_table.sql
- Start gateway:
- MCP_PROFILEseparates memory by agent or use case.
- Use any profile name you want (for example:default,my-agent,profile-a).
- Legacy built-in profile IDscocoandtotoare still supported for compatibility.
- IfPORTis omitted, default port is profile-based (coco=18790,toto=18791, other profiles deterministic in20000-29999).
MCP_PROFILE=profile-a PORT=18790 npx @marsnme/mcp-gateway
- Connect your MCP client (next section), then run the first round-trip check.
If you only want a local demo path, use Docker Compose.
curl -fsSL https://marsnme.com/install.sh | bash
cp .env.example .env # fill JINA_API_KEY in .env
- PostgreSQL + pgvector
- SQL migrations fromsupabase/migrations/
- PostgREST + rest-proxy
- MarsNMe gateway (http://127.0.0.1:18790/mcp)
When you need a temporary public endpoint for remote AI tools:
docker compose --profile tunnel logs tunnel | grep -Eo 'https://[^ ]+trycloudflare.com' | head -n1 # append /mcp
- trycloudflare.comURL 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(defaultcoco)
- MCP_TUNNEL_REQUIRE_BEARER(defaultfalsefor demo convenience)
If bearer auth is enabled (MCP_REQUIRE_BEARER=true), include:
- Authorization: Bearer <your-token>
- Openclaude_desktop_config.json(macOS default path:~/Library/Application Support/Claude/claude_desktop_config.json).
- Add/update:
{ "mcpServers": { "marsnme-cf": { "url": "http://127.0.0.1:18790/mcp" } } }
- Open Cursor Settings and search for MCP.
- Add a new server:
- Name:marsnme-cf
- URL:http://127.0.0.1:18790/mcp
- Headers: optional bearer header if enabled
- OpenSettings > Agents > MCP servers.
- Add a server pointing to:
- URL:http://127.0.0.1:18790/mcp
- Open a Space in Perplexity and go to Space Settings.
- Under MCP servers, add:
- URL:http://127.0.0.1:18790/mcp
{ "marsnme-cf": { "url": "http://127.0.0.1:18790/mcp" } }
First Connection Validation (Round Trip)
After client connection, verify this sequence once:
curl -sS http://127.0.0.1:18790/mcp \ -H 'content-type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
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"}}}'
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}}}'
mars-memory-mcpis the core MCP gateway repository behind the public-facing MarsNMe release.
One codebase (marsnme-supabase/server.mjs) serves multiple profile schemas throughMCP_PROFILE. This public repository currently keeps two built-in legacy profile IDs (coco,toto) for backward compatibility.
- MCP methods:initialize,notifications/initialized,tools/list,tools/call,ping
- Profiles: configurable profile IDs (legacy built-ins:coco,toto)
- Memory tools (16):
- insert_memory(short-term memory)
- list_memories
- search_memories(Jina embedding search)
- recall(~80-char preview) thenget_summary(~300-char excerpt) thenget_full(complete text)
- memory_ingest/dream_ingest(long-term chunk ingestion)
- session_boot/session_close(daily rhythm lifecycle; close auto-promotes expiring memories + supports body-to-body note handoff)
- health_check(coverage, expiry, conflict diagnostics)
- reload_source_registry(refresh source whitelist at runtime)
- demote_memory/soft_forget/explain_memory(memory lifecycle management)
- batch_promote(promote expiring short-term memories to long-term)
- Short-term memory table:<profile>.memories
- Long-term memory table:<profile>.marsvault_chunks
- Recommended usage:
- Keep daily interaction context ininsert_memory
- Promote durable insights through ingest tools
- marsnme-supabase/server.mjs— gateway entry point
- marsnme-supabase/scripts/hermes_digest_runner.py— optional digest runner
- marsnme-supabase/scripts/dream_runner.py— public self-host dream runner
- marsnme-supabase/deploy/systemd/— systemd templates
- marsnme-supabase/deploy/phase2/— build/deploy scripts
- marsnme-supabase/deploy/phase3/smoke_gate.sh— smoke gate script
- supabase/migrations/— schema-as-code migrations
- Copy.env.exampleto your local.env(do not commit real secrets).
- Fill required values:
- MCP_PROFILE(your profile identifier; this repo ships with legacycoco/toto)
- SUPABASE_BASE_URL
- SUPABASE_SERVICE_ROLE_KEY
- JINA_API_KEY
- MCP_REQUIRE_BEARER=true
- MCP_CLIENT_ID
- MCP_CLIENT_SECRET
Hermes is optional and disabled by default:
- HERMES_ENABLED=false
- HERMES_DIGEST_MCP_URL
- HERMES_DIGEST_MCP_BEARER_TOKEN
- HERMES_DIGEST_ORIGIN
- HERMES_DIGEST_SOURCE_DIR
Dream Runner is public-friendly and can run without Hermes private environment:
- DREAM_ENABLED=true
- DREAM_MODE=lite|standard|pro
- DREAM_DIGEST_MCP_URL
- DREAM_MCP_BEARER_TOKEN(if required)
- DREAM_ENABLE_ISSUE_SIGNALS,DREAM_ENABLE_REPO_SCAN,DREAM_ENABLE_SOUL_CONTEXT(optional overrides)
DREAM_ENABLED=true DREAM_MODE=lite python3 marsnme-supabase/scripts/dream_runner.py
If you run this repository with bundled defaults and no profile remapping, usecocoandtoto.
Seedocs/dream-runner-self-host.mdfor full configuration.
- 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 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
MCP_PROFILE=profile-a npx @marsnme/mcp-gateway
MCP_PROFILE=profile-b npx @marsnme/mcp-gateway
Usemarsnme-supabase/deploy/systemd/memory-mcp-gateway@.servicewith instances:
- memory-mcp-gateway@profile-a.service
- memory-mcp-gateway@profile-b.service
- /opt/mars-memory-mcp/shared/.env
- /opt/mars-memory-mcp/shared/.env.profile-a
- /opt/mars-memory-mcp/shared/.env.profile-b
bash marsnme-supabase/deploy/phase2/build_release_artifact.sh
- Apply migrations with an explicit DDL-capable role:
npx supabase db push --db-url "<postgres://supabase_admin:<password>@<host>:5432/postgres>"
- Run pre-deploy schema gate (must pass before any service restart):
bash marsnme-supabase/deploy/phase2/pre_deploy_schema_gate.sh \ --db-url "<postgres://supabase_admin:<password>@<host>:5432/postgres>" \ --profiles coco,toto \ --expected-role supabase_admin
- Run your platform-specific rollout/restart adapter.
- This repository ships generic artifact + gate scripts; rollout adapters are environment-specific.
- If schema gate exits non-zero, stop deployment and do not restart services.
bash marsnme-supabase/deploy/phase3/smoke_gate.sh --spawn-local
- Automated npm + MCP Registry release (tag-driven):
- Workflow:.github/workflows/publish-release.yml
- Trigger: push tagv*
- Gate: tag version must matchmarsnme-supabase/package.jsonversion
- Optional local Fish helper:
mrel patch mrel minor mrel major mrel 0.1.2
The helper updatesmarsnme-supabase/package.jsonandserver.json, commits, tags, and pushes.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
