Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Memory MCP remember we use Postgres for the production database"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A persistent, shared, selective memory layer for LLM clients (Claude, Cursor, ChatGPT, IDEs), built on the Model Context Protocol.
LLMs forget everything between sessions and across tools, so developers keep re-explaining their stack, project architecture, workflows, and decisions. Pasting old chats does not scale — it overflows the context window, replays past mistakes, leaks secrets, and goes stale the moment a decision changes.
Memory MCP is the brain on top of storage: it extracts durable facts from noisy conversations (like architecture, module responsibilities, workflows, decisions, and stack choices), deduplicates them, resolves conflicts as beliefs change, and surfaces only the handful of relevant facts for the current task — to every connected tool, automatically.
Storing text is the easy 10%. Memory MCP does the hard 90%: extract → dedupe → index → retrieve-the-right-bit → resolve conflicts → expire.
Problem with paste / flat file | What Memory MCP does |
Doesn't scale — which of hundreds of chats has the context? | Semantic retrieval surfaces the relevant slice, not the whole history |
Long pastes overflow the context window ("lost in the middle") | Token-budgeted packing returns the top few facts, not 50 pages |
Raw chat ≠ knowledge (dead ends, corrections) | Fact extraction & distillation into clean, self-contained facts |
One flat file cross-contaminates projects/tools | Project/tool scoping with a readable-ancestor hierarchy |
Contradictions pile up ("React" then "Vue", "AWS" then "GCP") | Conflict detection supersedes stale beliefs by canonical key |
Facts rot; nothing expires | TTL / staleness handling keeps memory current |
Blind pastes leak secrets/PII | PII-aware filtering + append-only audit log |
Related MCP server: Recall
flowchart LR
subgraph Clients["MCP Clients"]
C1[Claude Desktop]
C2[Cursor]
C3[ChatGPT / IDEs]
end
C1 & C2 & C3 -->|MCP Protocol / stdio / SSE| SRV[FastMCP Server<br/>remember · recall · ingest]
SRV --> MM[MemoryManager<br/>orchestrator]
subgraph Write["Write path"]
EX[Fact Extractor] --> PII[PII Filter] --> EMB[Embedder] --> DIS[Distiller<br/>dedup · conflict]
end
subgraph Read["Read path"]
Q[Embed query] --> VS[(Vector Store)] --> RK[Ranker<br/>relevance+recency+importance] --> PK[Token-budget pack]
end
MM --> Write --> VS
MM --> Read
MM --> AUD[(Audit Log)]Every component is designed with a pluggable interface and clean offline defaults, so the entire system runs out-of-the-box with zero configuration and zero API keys — then seamlessly upgrades in place when advanced backends are installed.
Layer | Offline Default | Production Upgrade |
Embeddings |
|
|
Vector store |
| ChromaDB |
Fact extraction | Rule-based patterns + taxonomy | OpenAI / Anthropic LLM |
Clone the repository and install dependencies:
git clone https://github.com/mrunmayeekokitkar/Memory-MCP.git
cd Memory-MCP
# Install core dependencies (lightweight, zero cloud dependencies required)
pip install -r requirements.txt
pip install -e .Walk through the entire 6-stage memory pipeline in your terminal:
python examples/demo.pyThis demonstrates:
Conversation Ingestion & Distillation: Parsing multi-turn dialogue into structured facts.
Conflict Resolution: Changing a belief (e.g., Postgres → MySQL) supersedes old facts automatically.
Hybrid Ranked Recall: Fetching facts scored by relevance, recency, and importance.
PII Masking: Automatic redacting of phone numbers, emails, and credentials.
Scope & Project Isolation: Enforcing boundary checks across different projects.
Immutable Audit Trail: Chronological event logs for enterprise governance.
Ensure full test coverage passes locally:
pytest -qStandard I/O (Default for desktop clients like Claude and Cursor):
python -m memmcp.server
# or via the console script:
memmcpSSE Transport (Network / Remote HTTP transport):
python -m memmcp.server --transport sse --host 127.0.0.1 --port 8000Add the following to your claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"memory-mcp": {
"command": "python",
"args": ["-m", "memmcp.server"],
"env": {
"MEMMCP_DATA_DIR": "./.memmcp_data",
"MEMMCP_EMBEDDING_PROVIDER": "hash",
"MEMMCP_VECTOR_BACKEND": "numpy",
"MEMMCP_EXTRACTION_PROVIDER": "rule",
"MEMMCP_PII_POLICY": "redact"
}
}
}
}Restart Claude Desktop, and Memory MCP will appear under the hammer / tools icon.
Tool | Purpose |
| Store one durable fact (with project scope, importance, conflict key, TTL) |
| Distill a raw dialogue into clean, deduplicated facts |
| Bootstrap memory from a high-level codebase or architecture description |
| Retrieve a structured snapshot of the whole project (grouped by category) |
| Retrieve top relevant facts for a query, constrained to a token budget |
| List active (or superseded/expired) memories in a project scope |
| Edit a memory in place (re-computes embeddings if content changed) |
| Soft-delete a memory by unique ID |
| Cluster and merge near-duplicate facts in a project scope |
Resources exposed:
memmcp://stats: Real-time system statistics and vector index sizes.
memmcp://audit: Tail of the security and mutation audit log.
When configured with an LLM backend (openai or anthropic), Memory MCP categorizes and indexes project facts into 8 structured categories:
Identity: User, team, and contributor preferences.
Stack: Technology choices (frameworks, runtime versions, databases).
Project: High-level purpose, architecture, and deployment targets.
Modules: Module boundaries, component interfaces, and responsibilities.
Workflows: CI/CD processes, deployment pipelines, testing routines.
Decisions: Architectural Decision Records (ADRs) and design rationales.
Domain: Project-specific vocabulary and business terminology.
Status: Current milestones, active bugs, and technical debt.
Hybrid Ranking: Blends vector cosine similarity, half-life recency decay ($e^{-\lambda \Delta t}$), and user-assigned importance into a composite score, dynamically packed to fit token budgets.
Fact Distillation & Conflict Detection: Automatically canonicalizes keys (user:database, stack:framework). When a contradicting assertion arrives, the engine supersedes prior facts while preserving historical audit records.
Privacy & Security: Built-in regex engine with Luhn algorithm validation masks API keys, JWTs, emails, phone numbers, and payment details before data reaches the vector store.
Hierarchical Scoping: Strict project and workspace partitioning prevents context leaks between unrelated projects.
Override any setting via .env or system environment variables:
Variable | Default | Description |
|
| Directory where index and audit logs reside |
|
|
|
|
|
|
|
|
|
|
|
|
|
| Weight for semantic similarity |
|
| Weight for freshness |
|
| Weight for caller-assigned importance |
|
| Days until recency score decreases by 50% |
Memory-MCP/
├── src/memmcp/
│ ├── server.py # FastMCP server & tool endpoints
│ ├── memory_manager.py # Core pipeline orchestrator
│ ├── config.py # Environment-driven configuration
│ ├── models.py # Pydantic models & data contracts
│ ├── scoping.py # Project namespace & isolation logic
│ ├── embeddings/ # Pluggable embeddings (Hash, Local, OpenAI)
│ ├── store/ # Vector stores (Numpy, Chroma)
│ ├── retrieval/ # Ranking & token-budget packing
│ ├── extraction/ # Fact extraction, distillation & conflict judge
│ └── privacy/ # PII detection & append-only audit trail
├── tests/ # Pytest test suite (87 tests)
├── examples/ # End-to-end demo and client configurations
├── pyproject.toml # Build system and package metadata
├── requirements.txt # Core dependencies
└── README.md # Project documentationThis project is licensed under the MIT License.
Merge near-duplicate memories within a project to keep memory clean.
Inputs: project_name. Returns: object
Permanently delete a memory by id.
Inputs: memory_id (required), tool. Returns: object
Get a structured snapshot of everything known about the project.
Call this at the START of a session to load the full project model into
your context — purpose, architecture, modules, workflows, decisions,
domain terms, and status — grouped by category. Much richer than recall
which returns a flat ranked list for a specific query.
Same as remember: auto-match if unambiguous. If ambiguous, call list_projects() and explicitly ask the user to choose. Once chosen, session-lock it.
Args: project_name: Project name to search within. Also includes global memories. Omit for global-only. categories: Optional filter — only include specific categories. Valid values: "identity", "stack", "project", "module", "workflow", "decision", "domain", "status". Pass null/omit for all categories. detail_level: "full" (complete content) or "summary" (first sentence only, for lightweight injection when context is tight). tool: Calling tool name (for audit).
Returns a dict keyed by category, each containing a list of facts with their content, key, and importance. Only non-empty categories appear.
Inputs: tool, categories, detail_level, project_name. Returns: object
Bootstrap project memory from a high-level codebase description.
Pass a description of the project — what it does, its architecture, the main modules and their responsibilities, key decisions, deployment setup, domain terminology. Memory MCP will extract structured facts and store them.
Ideal for onboarding: describe your project once, and every future session (across all connected tools) will already have the context.
Same as remember: auto-match if unambiguous. If ambiguous, call list_projects() and explicitly ask the user to choose. Once chosen, session-lock it.
Args: summary: A description of the codebase/project. Can be multi-paragraph. Include as much detail as useful: what the project is, its modules, architecture, tech stack, deployment, key decisions, domain terms. project_name: Project name. Facts will be stored under this project. If omitted, stored as global. tool: Calling tool name (for audit + provenance).
Returns counts of extracted/created/merged/superseded facts.
Inputs: summary (required), tool, project_name. Returns: object
Distill a raw conversation or dense text into clean facts and store them.
Use this when a large block of text needs to be turned into memory:
The user pastes a meeting transcript, chat log, or design doc.
You just generated a dense response (e.g. a full architecture plan, a multi-module breakdown, a deployment strategy) that contains many facts worth remembering. Pass your own response text into this tool.
The user asks you to "remember this" or "save this" about a big block.
Rule of thumb: if the text contains more than ~3 distinct facts, use
this tool instead of calling remember many times.
Memory MCP's backend uses a dedicated extraction LLM to read the full text (both user and assistant turns), extract only the durable conclusions, standardise them into clean facts with conflict keys, and deduplicate against existing memory. Dead ends, chit-chat, and corrected mistakes are discarded automatically.
Same as remember: auto-match if unambiguous. If ambiguous, call list_projects() and explicitly ask the user to choose. Once chosen, session-lock it.
Args: conversation: The raw text to distill — can be a chat transcript, your own generated response, meeting notes, or any unstructured text. project_name: Project name. If provided, facts are stored under that project. If omitted, stored as global. tool: Calling tool name (for audit + provenance).
Returns counts of extracted/created/merged/superseded facts.
Inputs: conversation (required), tool, project_name. Returns: object
List stored memories, optionally filtered to a project.
Set include_inactive to also show superseded/expired facts (useful for
auditing how beliefs changed over time).
Same as remember: auto-match if unambiguous. If ambiguous, call list_projects() and explicitly ask the user to choose. Once chosen, session-lock it.
Inputs: project_name, include_inactive. Returns: object
List all known projects that have stored memories.
Call this FIRST when you are unsure which project the user is working on:
At the start of a chat session in a non-IDE client (Claude Desktop, ChatGPT, etc.) to discover what projects exist.
Before inventing a new project_name — check if one already exists that matches (to avoid creating duplicates like "my-app" vs "MyApp").
When the user mentions a project by a partial or informal name — look up the exact stored name here.
In IDE-based clients (Cursor, Windsurf, VS Code) you usually already know the workspace folder name, but calling this is still useful to confirm the exact project name used in memory.
Returns a list of projects, each with:
name: the project_name (null for global/unscoped memories)
memory_count: number of active facts stored
last_updated: when the most recent fact was updated
categories: which knowledge categories have facts
Inputs: no named parameters. Returns: object
Retrieve only the most relevant remembered facts for the current task.
Call this at the start of a task instead of asking the user to re-explain context. Returns the top facts ranked by relevance + recency + importance, trimmed to a token budget so you never overflow the context window.
When project_name is omitted (None), recall searches across all
projects — not just global memories. Each result includes a
project_name field so you can see which project a fact belongs to.
This is useful when the user hasn't told you which project they're working
on: search broadly, read the project names in the results, and use the
correct name for follow-up calls.
Same as remember: auto-match if unambiguous. If ambiguous (e.g. chat client with no filesystem), call list_projects() and explicitly ask the user which project they want to search, or leave it blank to search everything. Once chosen, lock it for the session.
Args: query: What you need context about (the user's request/topic). project_name: Project name to search within. When given, searches that project's memories plus global memories. When omitted (None), searches across ALL projects (cross-project discovery). top_k: Maximum number of facts to return. token_budget: Optional cap on total tokens of returned facts. tool: Calling tool name (for audit).
Returns a ready-to-inject context_block string plus the structured
memories with their ranking signals. Each memory includes its
project_name so you can tell which project it belongs to.
Inputs: query (required), tool, top_k, project_name, +1 more. Returns: object
Store ONE durable fact about the user or project for future recall.
Use remember when you identify 1 to 3 clear, distinct facts during a
conversation — a preference, a tech-stack choice, an architectural decision,
an identity detail, a constraint, a workflow step, or a domain term.
Call it in real time as the conversation progresses. You do NOT need to wait for the user to explicitly ask you to save something. If the user confirms a plan you proposed (e.g. "ok, let's go with that"), save the key decisions from your proposal immediately.
If you just generated (or the user pasted) a dense block of text containing
many facts (architecture docs, meeting notes, large plans), use
ingest_conversation instead — it extracts and deduplicates automatically.
Rule of thumb: if you would need more than ~3 remember calls, prefer ingest.
Save ALL categories of durable knowledge:
Identity: user name, role, company, team
Stack: language, framework, database, cache, cloud, editor, CI/CD
Architecture: project purpose, system design, deployment target
Modules: component names, responsibilities, boundaries, dependencies
Workflows: CI/CD pipelines, data flows, deployment steps
Decisions: architectural choices and the reasoning behind them
Domain terms: project-specific jargon and definitions
Status: current milestones, blockers, known tech debt
Write a concise, third-person, present-tense, self-contained sentence. Good: "Project uses PostgreSQL as primary database." Bad: "they said postgres" (not self-contained, ambiguous)
No Ambiguity (IDE/Filesystem): If you can reliably determine the project from the workspace folder name or Git remote, auto-match and use it silently.
Ambiguity (Chat Client / Multiple Projects): On the first ambiguous remember or recall call, DO NOT GUESS. Call list_projects() and explicitly ask the user to choose (e.g., "I found these existing projects... Which one are we working on today?").
Session Lock: Once the user selects a project, or it is auto-matched, lock that project_name for all subsequent calls in the current session.
New Project: When saving to a new project name for the first time, explicitly confirm it with the user (e.g., "I've created a new project memory space called X. All facts from this session will be saved under this project.").
Args: content: The fact, e.g. "Project uses PostgreSQL as primary database." project_name: Project name to associate this fact with. If omitted (None), the fact is stored as a global memory visible to all projects. If provided, the fact is scoped to that project but still visible alongside global memories when querying that project. importance: 0..1 estimate of long-term value. - 0.85–0.95: identity, architecture, core decisions - 0.75–0.85: module descriptions, workflows - 0.70–0.80: stack choices - 0.65–0.80: domain terms, status - 0.50–0.65: preferences, dislikes - 0.40–0.50: ephemeral observations key: Optional conflict slot (e.g. "user:database"). A new fact with the same key supersedes the old one, so beliefs stay current. Common keys: user:name, user:language, user:framework, user:database, user:cloud, user:editor, user:current_project, project:architecture, project:deployment, project:purpose, project:status. For modules/workflows/decisions use dynamic keys like project:module:, project:workflow:, project:decision:. tags: Optional labels for filtering. ttl_days: Optional expiry in days for facts that go stale on their own. tool: Name of the calling tool (recorded for audit).
Returns a summary including the resulting action: created, merged (a duplicate already existed), superseded (an older conflicting fact was retired), or blocked (PII policy refused it).
Inputs: content (required), key, tags, tool, +3 more. Returns: object
Edit an existing memory by id (re-embeds if the content changes).
Inputs: memory_id (required), tags, content, ttl_days, +1 more. Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 10 tools
Most tools map to clearly distinct memory operations: store one fact, ingest bulk text, query, get a project snapshot, list, update, delete, and consolidate. The only notable overlap is between ingest_conversation and ingest_codebase_summary, which both extract facts from text and could be confused despite usage guidance.
All names use snake_case and are action-oriented, making the tool set readable and predictable. Consistency is slightly reduced by mixing bare verbs (remember, recall, forget) with verb_noun forms (list_projects, update_memory).
Ten tools are well-scoped for a memory service, covering storage, retrieval, maintenance, and lifecycle operations without obvious bloat. Each tool appears to earn its place.
The surface covers the full memory lifecycle: create/store, bulk ingest, recall/read, project context, list, update, delete, and consolidation. No obvious CRUD or maintenance operation is missing for the stated purpose.
Shared project context for AI agents and teams: docs, tasks, and messages that stay current.
Shared, permission-aware company context for AI agents, with provenance, approvals and audit.
Shared project memory that keeps teammates and AI agents aligned across sessions.
Persistent context for Claude. Your AI always knows your projects and next actions across sessions.
