mcp-memory-server

This package is the MCP server for a hosted memory layer that lets AI agents keep what they learn across sessions and tools: write a memory once, and any connected client can recall it later by natural-language query. It is built for developers running agents in Claude, Cursor, VS Code, ChatGPT and similar hosts who want memory shared across all of them through a single key or OAuth sign-in rather than per-tool instruction files. What sets it apart is feedback-driven ranking — marking a recalled memory as helpful or misleading changes what surfaces next time — plus shared rooms where several agents work from one memory pool. The server is MIT-licensed and runs locally or against the hosted endpoint; the memory engine itself is a managed service.

Features

• Persistent memory across sessions — agents store decisions, preferences, and lessons once and retrieve them in any connected client; nothing is re-explained on restart.

• Feedback-driven re-ranking — every recalled memory can be rated as helpful or misleading. Ratings change how the same memory ranks on future reads, so retrieval improves with use instead of staying fixed at ingest-time similarity.

• Shared rooms for multi-agent work — create a room, invite collaborators with a code, and use the room's address as the domain on writes and reads. Several agents can work from one memory store.

• One identity everywhere — a single API key or an OAuth sign-in covers Claude, Cursor, VS Code, and other MCP hosts. No per-tool memory silo.

// A shared room's address is used as the domain on both write and read
{ "domain": "room:team-alpha", "content": "Deploys freeze on Fridays" }

# Feedback closes the loop: the next read reflects the rating
memory_feedback(memory_id="...", helpful=False)

• Domain namespacing — separate memories by user, project, or agent (user:<id>, project:<name>) without separate accounts.
• Natural-language retrieval — read by meaning, not exact keys.
• Recent listing without a query — browse newest-first with time bounds and cursor paging.
• Inspectable association graph — read the weighted links and outcome valence around a concept to see why something surfaces.
• Secret vault — list stored secrets by alias and purpose; values are never returned through the tool surface.

How it works

Every tool call is a JSON-RPC message over one of two transports:

The server itself is a thin proxy: it validates arguments, translates them into requests against the memory API, and maps the responses back into MCP content blocks. All storage, indexing and ranking happen server-side, which is why the same account sees the same memories from any client.

A recall, end to end

1. The agent calls memory_read with a natural-language query and, optionally, a domain.
2. The service embeds the query, retrieves candidate memories from that domain, and orders them by a score that blends similarity with the feedback history of each candidate.
3. The agent gets the top results back with their ids. It does whatever it does with them.
4. The agent (or the user) calls memory_feedback on an id, marking it helpful or misleading.
5. That verdict is stored as an association edge and shifts the ranking of that memory — and the concepts it's linked to — on the next recall.

The re-ranking is the part that doesn't happen in a plain vector store: a memory that keeps misleading gets pushed down even when its text is a close match, and one that keeps helping gets pulled up.

Domains and rooms

A domain is a namespace inside your account, passed on both writes and reads:

{ "content": "Deploys go out on Tuesdays only", "domain": "team:platform" }

Shared rooms are domains with an address other agents can join:

memory_create_room    →  room with an address usable as `domain`
memory_invite_to_room →  invite code (mnvr_...) + link, single-use by default
memory_join_room      →  another account redeems the code
memory_list_rooms     →  rooms you own or joined, with their addresses

Once joined, any member's memory_write into the room's address is visible to every other member's memory_read against the same address. A room is a sharing mechanism, not a permission boundary — treat it as "we all agreed to pool context," not "this data is compartmentalized."

What the server doesn't do

• It doesn't call the model. Prompts like recall and save_insight instruct the agent to use the tools; the reasoning stays in your client.
• It doesn't cache. Every tool call is a round trip to the service, so a memory written from one session is readable from another immediately.
• It doesn't persist anything locally in stdio mode beyond the process's own lifetime.
• It never returns a Vault secret value — vault_list gives alias and purpose only.

Failure behavior

Tool calls that the service rejects come back as MCP errors with the service's reason preserved, so a missing_key, invalid_key or revoked_key is distinguishable from a network failure. Reads against an empty or unknown domain return an empty result set rather than an error.

Compatibility

What "compatible" means for memory

• Cross-tool continuity. A memory written from Claude Code is readable from Cursor, VS Code, or ChatGPT under the same account, because storage and ranking live on the hosted engine — not in the client. Switching clients does not require re-importing anything.
• Namespacing. domain (e.g. user:<id>) isolates one user's or project's memories inside your account. It is a namespace, not a permission boundary — treat it as organization, not access control.
• Shared rooms (beta). A room's address can be used as a domain on both memory_write and memory_read, so several agents (across different clients) can work from one memory. Invite codes are single-use by default unless max_uses is set.

Tool surface compatibility

The server's tools/list response is stable per released version:

• PATCH releases never change tool names, argument schemas, or annotation fields — only descriptions and return text may change.
• MINOR releases may add tools, annotation fields, or output schemas, but never remove or rename them.
• Output schemas (where declared) are add-only. Fields that differ deliberately from the hosted connector (e.g. memory_id as an opaque string here) are called out in the CHANGELOG.

Clients that cache the tool list can diff it against a saved snapshot after an upgrade to confirm nothing they depend on was removed.

Known limitations

• Prompts and resources are optional. Clients that do not surface MCP prompts as commands (or do not attach resources) still get full tool functionality — the four named prompts and memory://item/{memory_id} simply won't appear.
• Non-interactive hosts. Clients that do not prompt for inputs (e.g. VS Code's Agent Host mode) will not start the local package with a masked key prompt; provide the key in the launching process's environment instead.
• Resource scope. memory://item/{memory_id} resolves only memories in your own store. A memory read from a shared room cannot be opened by id.
• No offline mode. The local package is a bridge to the hosted engine; without network access to the API, tool calls fail. Use a local-first memory server if that is a hard requirement.

Configuration

All configuration is read from environment variables or MCP client config files. Nothing is required at install time — the server starts and lists its tools without credentials; every actual tool call needs a key or an OAuth session.

Environment variables