Store ONE durable fact about the user or project for future recall.

When to use this tool

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.

When NOT to use this tool

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.

What to save (not just tech stack!)

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

How to write a good fact

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)

How to resolve the project_name (Session Locking & Ambiguity)

• 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).

Distill a raw conversation or dense text into clean facts and store them.

When to use this tool

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.

What happens internally

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.

How to resolve the project_name

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.

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.

Cross-project discovery

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.

How to resolve the project_name

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.

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.

How to resolve the project_name

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.

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.

How to resolve the project_name

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.

List all known projects that have stored memories.

When to use this tool

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

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).

How to resolve the project_name

Same as remember: auto-match if unambiguous. If ambiguous, call list_projects() and explicitly ask the user to choose. Once chosen, session-lock it.

Edit an existing memory by id (re-embeds if the content changes).

Permanently delete a memory by id.

Merge near-duplicate memories within a project to keep memory clean.