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.

Related MCP server: Memsolus MCP Server

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

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