shared-memory — MCP Server for Cross-Client Long-Term Memory

One shared long-term memory for all your AI clients.

Connect a single MCP server to Cursor, Cherry Studio, Odysseus AI, NextChat — they all read and write to the same database. A fact saved in Cursor is available in Cherry Studio and vice versa.

---

How it works

Cursor ─┐
Cherry Studio ─┤  HTTPS + Bearer token   ┌──── Raspberry Pi ────────────────┐
Odysseus AI ─┼─────────────────────────►  │  FastMCP (Streamable HTTP)       │
NextChat ─┘   (mcp-remote if stdio)       │  → MongoDB Atlas (Vector Search) │
                                           └──────────────────────────────────┘

• Server: Python (FastMCP 3.x), runs on Raspberry Pi 4 inside Docker.
• Transport: Streamable HTTP (single POST endpoint /mcp, SSE for streaming).
• Storage: MongoDB Atlas (M0 free tier) with Atlas Vector Search + Automated Embedding (Voyage AI).
• Security: Per-client Bearer tokens, rate limited at 60 req/min.
• Publication: Tailscale Funnel — HTTPS out of the box, no open ports.

---

Tools (MCP)

The server exposes 5 tools. Below is the description written for the AI agent that will call them.

1. memory_write

memory_write(content: string, type: "fact" | "preference" | "decision" | "snippet",
             scope?: string, tags?: string[], pinned?: boolean) -> { id, created, scope }

Saves a fact to long-term memory. Idempotent: if the exact same fact (normalized: lowercase, collapsed whitespace) already exists in this scope, it does not create a duplicate but updates updated_at.

Parameters:

• content — one self-contained statement, 1-4000 characters.
• type — category: fact, preference, decision, snippet.
• scope — namespace (global / project-name). Defaults to the client's scope from the token.
• tags — labels for filtering.
• pinned — if true, surfaces in every bootstrap call.

When to call: user stated a preference, made a decision, corrected you, or shared configuration.

2. memory_search

memory_search(query: string, scope?: string, tags?: string[],
              limit?: number) -> { count, limit, results: [...] }

Semantic search over memory. Uses Atlas Vector Search (Voyage AI embeddings) when available, falls back to case-insensitive regex.

Parameters:

• query — phrase this as the question you are trying to answer, not keywords.
• scope, tags — filters.
• limit — 1..25 (default 5).

Each result:

{
  "id": "ObjectId",
  "content": "fact text",
  "scope": "global",
  "type": "fact",
  "tags": [],
  "pinned": false,
  "created_at": "2026-08-01T07:48:48+00:00",
  "source_client": "cursor",
  "score": 0.92        // only present with vector search
}

When to call: before answering a question about preferences, projects, or past user decisions.

3. memory_bootstrap

memory_bootstrap(scope?: string, limit?: number) -> { count, results: [...] }

Returns pinned facts (always first) + most recent. Cheap call to load context at the start of a dialogue.

When to call: exactly once at the beginning of a new conversation.

4. memory_forget

memory_forget(id: string) -> { forgotten: boolean }

Soft-delete: marks the record as deleted: true. Does not physically erase it.

When to call: the user said a fact is no longer accurate. After forget, write the corrected version.

5. ping

ping() -> "pong"

Health check.

---

Authentication

Every request to /mcp must include:

Authorization: Bearer <token>

Tokens are configured in .env:

MCP_TOKENS=tok_cursor:cursor:global,tok_cherry:cherry:global,tok_nextchat:nextchat:global,tok_odysseus:odysseus:global

Format: token:client_name:default_scope. Different clients get different tokens (auditing + revoking one doesn't break the others).

Rate limit: 60 requests/minute per token. On exceeding: 429 + Retry-After: 60.

---

Endpoints

Path	Method	Auth	Description
/healthz	GET	none	Server health check
/mcp	POST	Bearer	MCP requests (tools/list, tools/call, etc.)

---

Data model

Collection shared_memory.memories:

{
  "_id": ObjectId,
  "content": "user prefers dark mode in all editors",
  "content_hash": "sha256(normalize(content))",
  "scope": "global",
  "type": "preference",
  "source_client": "cursor",
  "tags": ["editor", "theme"],
  "pinned": false,
  "deleted": false,
  "created_at": ISODate,
  "updated_at": ISODate
}

Unique index: (scope, content_hash) — guarantees no exact duplicates within a scope.

Collection shared_memory.audit_log (TTL 30 days):

{
  "_id": ObjectId,
  "ts": ISODate,
  "client": "cursor",
  "tool": "memory_write",
  "args": "type=preference scope=global",
  "result_count": 1
}

---

Client setup

Cursor (direct connection)

~/.cursor/mcp.json:

{
  "mcpServers": {
    "shared-memory": {
      "url": "https://mcp-pi.<tailnet>.ts.net/mcp",
      "headers": { "Authorization": "Bearer tok_cursor" }
    }
  }
}

Cherry Studio (direct connection)

Settings → MCP Servers → Add:

• Type: Streamable HTTP
• URL: https://mcp-pi.<tailnet>.ts.net/mcp
• Headers: { "Authorization": "Bearer tok_cherry" }

NextChat / Odysseus AI (via mcp-remote bridge)

{
  "mcpServers": {
    "shared-memory": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp-pi.<tailnet>.ts.net/mcp",
               "--header", "Authorization: Bearer tok_client"]
    }
  }
}

---

System prompt (paste into each client's custom instructions)

You have access to the user's shared long-term memory via the `shared-memory` MCP server.

- At the start of a new conversation, call `memory_bootstrap` once.
- Before answering a question that depends on the user's preferences, projects,
  or past decisions — call `memory_search` with the question you are trying to answer.
- When the user states a stable preference, makes a decision, or corrects you —
  call `memory_write` (one self-contained statement).
- When the user corrects a previously stored fact — `memory_forget` by the id
  from search results, then `memory_write` with the corrected version.
- Do NOT save temporary task state, drafts, or anything easily re-derived.

---

Infrastructure

• Server: Raspberry Pi 4 (4GB), Docker + docker-compose.
• Publication: Tailscale Funnel → https://mcp-pi.<tailnet>.ts.net.
• Database: MongoDB Atlas M0 (free), automated Voyage AI embeddings for vector search.
• Auto-start: systemd unit (deploy/mcp-memory.service).
• Backup: nightly mongodump via deploy/backup.sh (30-day retention).

---

Tests

pytest -v    # 48 tests, mongomock (no Docker needed)

For integration with a real Atlas cluster: TEST_MONGODB_URI="mongodb+srv://..." pytest -v.

---

Key source files

File	Purpose
src/mcp_memory/server.py	FastMCP server, 5 tool registrations
src/mcp_memory/tools/memory.py	Pure tool logic (memory_write_impl etc.)
src/mcp_memory/repository.py	MongoDB CRUD + vector search + audit
src/mcp_memory/auth.py	Bearer authentication + rate limiting
src/mcp_memory/ratelimit.py	Token bucket rate limiter
src/mcp_memory/models.py	Pydantic MemoryRecord + content_hash
src/mcp_memory/config.py	Settings from env
src/mcp_memory/context.py	ContextVar for per-request client identity
src/mcp_memory/app.py	ASGI composition: healthz + auth + MCP
Dockerfile	ARM64 Docker image for Pi
deploy/docker-compose.yml	Production compose config
docs/setup-tailscale.md	Tailscale Funnel setup guide