memshare

Peer-to-peer AI memory sharing — approved on both sides. Works in any AI tool.

Every AI memory tool today treats memory as a feature of a chat product. memshare treats it as a data type: plain JSON files you own.

Once memory is a file, three things follow, in this order. You can inspect it — greppable, diffable, and actually gone when you delete it. You can move it — one store, every MCP client, every machine you own. And only then can you share it — selectively, item by item, with approval on both sides. That last one no other tool does at all; they are all per-account by design.

A designer working in Cursor and backend devs working in Claude Code can hand each other context directly — different people and different vendors, same bundle format.

No central server. No cloud. No signup.

🌐 Site · 📊 Pitch deck · 🔧 MCP tools

30-second quickstart

npm install -g memshare-mcp
memshare init

Then connect it to your AI tool:

# Claude Code
claude mcp add memshare --scope user -- npx -y memshare-mcp serve

// Cursor / Windsurf / GitHub Copilot — add to your MCP config
// (Cursor: .cursor/mcp.json, Windsurf: .windsurf/mcp.json,
//  Copilot: .github/copilot-mcp.json — or the global equivalent)
{
  "mcpServers": {
    "memshare": {
      "command": "npx",
      "args": ["-y", "memshare-mcp", "serve"]
    }
  }
}

npx rather than the memshare you just installed globally, because a client launched from a desktop icon rather than a shell often does not inherit a PATH that finds it. --scope user because the store is yours across every project, not one repo's.

memshare init creates ~/.claude/CLAUDE.md, ./CLAUDE.md and ./AGENTS.md with standing instructions — the files your assistant reads at the start of every session. Nothing in MCP can make a model call a tool, and some clients never pass the server's own instructions to the model at all, so that file is the one channel that always arrives. It never appends twice, memshare init --no-create-instructions skips creating missing files (still appends to existing ones), and memshare init --no-append-instructions leaves them all alone.

Asking an AI assistant to install this for you? Say "install memshare-mcp from github.com/kampana/memshare" — not just "install memshare." The plain name memshare is a different, unpublished package on npm, and a search for it can surface unrelated results. The command above is the one that actually works.

You mostly talk, not type

After setup, capture and recall happen in conversation — there is no command to run:

"we went with Postgres — the JSONB support decided it" → the AI calls memory_set, saved as private

"what do you know about this project?" → the AI calls memory_get

"remember that I like dark mode" → the AI calls memory_set

"forget what you know about the old auth flow" → the AI shows you what matched, then calls memory_forget

Sharing works the same way. Ask to send something and you are shown the exact list — including anything held back for containing personal data — before a file is written. Ask what someone sent you and you get the contents without taking any of it; ask to take it in and you see every item first. The approval moves into the conversation rather than disappearing from it. The CLI does all of this too, for scripting and for people who prefer it.

Promoting happens either way — in conversation, or at a prompt:

"make the project-x notes shareable" → the AI calls memory_set_visibility

memshare mark --tags project-x --shareable

Either route only makes an item eligible. Nothing is shared until you run memshare export and approve the preview — that step stays deliberately out of the model's hands.

Tags name themselves

You never have to say "tag this project-x". The project tag is derived from the git checkout the assistant is working in, so every tool, every session and every teammate on that repo agrees on it — and the model is told to add only subject-matter tags (auth, deploy) on top. Turn it off with memshare config --set autoProjectTag=false.

If near-duplicates creep in anyway, merge them:

memshare tags --rename projectx --to project-x

You can also add memories by hand at any time:

memshare add "Auth service uses JWT with 15min refresh" --tags project-x,auth --visibility shareable
memshare list
memshare list --tags project-x

Is it actually capturing?

The honest risk with this tool is a silent one: nothing in MCP can force a model to call a tool, so capture can quietly not happen and you would not find out for weeks. Two things make that visible.

The assistant is asked to say so in one line each time it saves — "noted: the team chose Postgres for JSONB" — so you see it working, and can correct a bad one on the spot instead of a month later. And:

memshare stats

12 memories, 5 in the last 14 days

  ▂▁▄█▂ ▁▃    14d ago → today

- 9 captured by an assistant, 3 added by hand
- 5 shareable, 7 private

A flat line there means capture is not firing, and you know within days rather than at the end of a month.

If nothing is being captured

memshare can offer memory, but nothing in MCP can make a model use it. The server asks the assistant to save as it learns — in its handshake and in every tool description — but some clients never pass server instructions to the model at all. That is why memshare init also writes the same request into the files your assistant reads every session.

If memshare list is still empty after a few days of real work, the likely reason is that your tool reads a different file, or you ran init --no-create-instructions. Point it at the right file:

memshare instructions --append ~/.claude/CLAUDE.md    # Claude Code
memshare instructions --append ./AGENTS.md            # Cursor, Windsurf, Copilot
memshare instructions --append ./.cursorrules         # Cursor, older versions

Safe to run twice — it checks before appending — and it creates the file if it is not there yet. Then restart your assistant, since these files are read once per session.

Try it in a sandbox first

The whole flow — capture, the consent step, PII getting blocked, export, per-item import — against throwaway stores:

git clone https://github.com/kampana/memshare.git
cd memshare && npm install && npm run build
bash examples/try-it.sh

This does install the project's dependencies locally, in the folder you cloned. What it does not do: install anything globally, create or modify ~/.memshare, or add anything to your Claude config — including the CLAUDE.md and AGENTS.md a real memshare init appends to, which the script opts out of. It builds two fake stores under a temp directory and deletes cleanly. Nothing carries over to a real setup.

Sharing with someone else

# Alice — see exactly what would go out, before anything is written
memshare export --tags "project-x,architecture" --for bob --expires 7d --preview

# Happy with it? Write the bundle.
memshare export --tags "project-x,architecture" --for bob --expires 7d
# → ~/.memshare/bundles/bundle-a3f8c2d1.memshare.json

Send that file however you like — email, Slack, AirDrop, a USB stick. Then, on Bob's machine:

memshare preview bundle-a3f8c2d1.memshare.json   # look, import nothing
memshare import  bundle-a3f8c2d1.memshare.json   # choose item by item

Bob picks each item individually. Accepted items land in his store marked imported, stored private by default — receiving something is not consent to pass it on. Nothing he already had is overwritten.

Architecture

              ~/.memshare/memories/*.json
              the actual product — plain JSON files
                ▲        ▲         ▲         ▲
                │        │         │         │
          MCP server   CLI    ChatGPT adapter  system-prompt inject
                │                (planned)        (planned)
                │
      Claude · Cursor · VS Code · Windsurf · any MCP client

The memory store is the product. The MCP server is one adapter over it, the CLI is another. If MCP disappears tomorrow, your data is still sitting in a folder — human-readable, diffable, and git-friendly. Sync it between your own machines with git or Dropbox; it is just files.

~/.memshare/
├── config.json              # your settings
├── memories/
│   └── mem_<uuid>.json      # one file per memory
├── suggestions.json         # pending, not yet approved
└── bundles/
    └── bundle_<id>.memshare.json

How memories get saved — three modes

These control what gets written down locally. What gets shared is a separate gate, covered below, and is never automatic.

| Mode | What happens | Who decides | |---|---|---| | auto (default) | The AI saves what it learns as you work, choosing shareable or private for each. | The AI, locally | | suggest | The AI calls memory_suggest. Nothing is stored until you run memshare review. | You, in batch | | manual | Nothing is saved unless you say "remember this". | You, every time |

auto is the default because an empty store is useless. The assistant picks a visibility for every memory — shareable for the project, the codebase and how the team works; private for anything about you personally, and whenever the call is arguable. Marking something shareable only makes it eligible: nothing leaves until you run an export and approve the preview. If you would rather approve every item, use suggest — and note that a direct memory_set is then queued as a suggestion rather than saved, so an over-eager model cannot skip the consent step.

memshare review          # approve or reject, one by one
memshare review --yes    # accept everything pending
memshare review --clear  # reject everything pending

Consent, on both sides

1. You tag at creation time. Every item is private (the default) or shareable. Private items are never exported, not even when their tags match.
2. PII is blocked automatically. Before anything leaves your machine, memshare scans for emails, phone numbers, government IDs, payment cards, bank details, credentials, and health or financial language. Flagged items are held back; you decide per item whether to skip them, send a redacted version, or send them as-is.
3. You see the exact bundle first. --preview runs the identical computation the real export does — there is no separate preview code path to drift out of sync.
4. They choose too. The recipient previews every item and accepts or rejects individually. Bundles are content-hashed, so a file edited in transit is refused.

What --expires does, and does not do

memshare export --expires 30d sets a deadline that does two things: the recipient's memshare refuses to import the bundle after it passes, and any item they did import inherits that deadline — so it stops being recalled and is deleted by memshare prune.

It does not delete the bundle file, and it is cooperative, not enforced: the deadline lives in the bundle metadata, which is not covered by the content hash, so a determined recipient can edit it. Expiry protects against stale context, not against a hostile recipient. There is no central server, so there is nothing that could revoke a file someone already has.

How it compares

| | Cross-model portability | Self-hosted | User-to-user sharing | Consent flow | |---|:---:|:---:|:---:|:---:| | Claude / ChatGPT memory | ✗ | ✗ | ✗ | ✗ | | Mem0 | ✓ | ✓ | ✗ | ✗ | | OMP (Open Memory Protocol) | ✓ | ✓ | ✗ | ✗ | | Portable Memory (MacPaw) | ✓ | ✓ | ✗ | ✗ | | memshare | ✓ | ✓ | ✓ | ✓ |

MCP tools

The server exposes ten tools to any MCP client:

| Tool | What it does | |---|---| | memory_set | Save one durable fact, choosing private or shareable for it. Routed to the approval queue in suggest mode. | | memory_get | Recall or browse memories — free text, tags, visibility, the tool that wrote them, or most-recent. | | memory_suggest | Propose memories for the user to approve later. | | memory_set_visibility | Mark memories shareable or private, when the user asks. | | memory_forget | Delete memories by id. Only when the user asks — deletion is irreversible. | | memory_stats | Counts, as JSON: per day, per tool, per tag, and the shareable/private split. | | memory_export | Prepare a bundle to send someone. Previews first, writes only on confirmation. | | memory_preview | Look inside a bundle someone sent, storing nothing. No argument can make it write. | | memory_import | Take in a bundle someone sent. Previews first, imports only on confirmation. | | memory_list_tags | List every tag, so the model reuses tags instead of inventing near-duplicates. |

memory_preview and memory_import's first call render the same plan through the same code — the difference is that preview is not the first half of anything, so "what did Dana send me?" can be answered without the next step being an import. memory_get is the browse tool as well as the recall tool: it takes the same filters memshare list does, so "what have you marked shareable?" and "what did Cursor save?" are answered without a second tool that could drift from the first. memory_forget is the one destructive tool in the set, and it is annotated as such — the assistant is told to call it only on an explicit request, never on its own judgement that a memory looks stale or wrong.

CLI reference

| Command | | |---|---| | memshare init | Create the store, and tell your assistant about it. --name, --mode, --yes, --no-append-instructions | | memshare add <text> | Add a memory. --tags, --visibility, --expires, --tool | | memshare list | Show the store. --tags, --visibility, --query, --from, --limit, --json, --all |

--from matches the MCP client that wrote the memory — the name it gives in the handshake, such as claude-code or cursor-vscode. Memories added by hand are cli.

| memshare recall | Print memories as plain text, to paste into any AI tool | | memshare stats | Is it actually capturing? Counts per day, tool and tag. --days <n> | | memshare tags | List all tags. --rename <from> --to <to> merges near-duplicates | | memshare mark [ids...] | Promote memories to shareable, or pull them back. --tags, --query, --shareable, --private | | memshare review | Approve or reject pending suggestions. --yes, --clear | | memshare export | Write a bundle. --tags, --for, --expires, --note, --out, --preview, --redact-blocked, --include-private, --no-scan | | memshare preview <file> | Inspect a bundle, import nothing | | memshare import <file> | Import a bundle, item by item. --yes, --visibility, --tag-sender, --allow-duplicates | | memshare forget <ids...> | Delete memories | | memshare prune | Delete expired memories | | memshare config | Show or change settings. --set key=value | | memshare instructions | Print standing instructions for your assistant. --append <file> appends them to a file init did not find | | memshare serve | Run the MCP server on stdio |

--dir <path> or MEMSHARE_DIR points any command at a different store — handy for keeping a separate memory profile per client, or for trying the sharing flow with yourself:

MEMSHARE_DIR=/tmp/bob memshare init
MEMSHARE_DIR=/tmp/bob memshare import bundle-a3f8c2d1.memshare.json

Where it can run

Your memories are the same JSON files in all four, so moving between them costs you nothing — no migration, no re-setup, nothing left behind:

• Local (we suggest starting here) — files on your laptop, MCP as a local process. Sharing: export a file and send it.
• Shared folder (planned) — Dropbox, Drive, or a git repo. Sharing: auto-sync through the folder.
• Team server (planned) — Docker on your VPS. Sharing: by username.
• Hosted (planned) — managed infra, same protocol, zero ops.

Roadmap

• Shipped: CLI, MCP server, export/import bundles, PII guard, consent flow
• Next: a ChatGPT route — only if people ask for one. Claude Code, Cursor, Copilot and Windsurf already work; they speak MCP and need no adapter.
• Later: Docker deploy, remote MCP server, revocable sharing
• Someday: discovery and live sync

Use as a library

import { MemoryStore, selectForExport, planImport } from "memshare-mcp";

const store = new MemoryStore();
await store.add({ content: "Team chose Postgres over MySQL", tags: ["db"] });
const { included, blocked } = await selectForExport(store, { tags: ["db"] });

Every adapter — the CLI, the MCP server, and any you write — goes through these exports. See src/index.ts.

Why is the package called memshare-mcp?

Two reasons. memshare itself is unusable on npm — an unrelated project published it in February 2021 and unpublished it that November, and npm permanently reserves unpublished names, returning 409 for everyone including the original owner. And -mcp says what this actually is: an MCP server first, with a CLI for the decisions that should not be delegated to a model.

The installed command is still memshare. An earlier release used memshare-cli, which is now deprecated and points here.

Development

npm install
npm run build
npm test
npm run check:docs   # docs and CLI must agree

Contributions welcome — see CONTRIBUTING.md.

License

MIT © memshare contributors