Memory MCP
Enables semantic memory capabilities through text embeddings and provides LLM-powered translation of natural language into database operations.
Provides a persistent storage backend using libSQL with support for vector search and semantic memory indexing.
Click on "Install 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 MCPRemember that I prefer using TypeScript for all my backend projects"
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.
Memory MCP
A Model Context Protocol (MCP) server that gives AI assistants persistent, semantic memory. Backed by Turso (libSQL) for storage with vector search, and OpenAI for embeddings and LLM-powered query generation.
All interactions are in plain English. The server uses GPT-5 with function calling to translate natural language into the right database operations automatically.
Features
Remember — Store new memories with automatic duplicate detection, field extraction, and quality validation
Forget — Remove or modify memories by describing what to change
Recall — Search memories semantically or with structured queries, without modifying data
Process — Review and refine stored memories: merge duplicates, fill gaps, ask clarifying questions
Rejection system — The LLM will reject nonsensical, duplicate, contradictory, or low-quality memories with a structured reason and category
Vector search — Semantic similarity search using OpenAI embeddings (text-embedding-3-small, 1536 dimensions) with libSQL DiskANN indexes
Table isolation — Each use case gets its own table with custom freeform columns, all in one database
Claude Code integration — Slash commands for table management (
/setup-table,/list-tables,/drop-table)
Related MCP server: mcp-recall
How It Works
┌─────────────┐ plain English ┌─────────────┐ function calls ┌───────────┐
│ MCP Client │ ──────────────────────► │ GPT-5 │ ──────────────────────► │ Turso DB │
│ (Claude) │ ◄────────────────────── │ + prompts │ ◄────────────────────── │ (libSQL) │
└─────────────┘ structured result └─────────────┘ SQL + vectors └───────────┘The MCP client sends a plain English request (e.g., "remember that user octocat prefers concise replies")
The server loads the table schema and builds a system prompt with operation-specific instructions
GPT-5 decides which internal tools to call (search, insert, update, delete, reject, or ask questions)
An agentic loop executes tool calls against Turso, feeds results back to the LLM, and repeats for up to 5 rounds
The final response is returned to the MCP client with success/rejection/questions status
Architecture
src/
├── index.ts # MCP server entry point — tool definitions
├── llm.ts # OpenAI wrapper — models, tool schemas, prompt loading
├── memory-ops.ts # Agentic loop — tool execution, rejection, questions
├── db.ts # Turso/libSQL client — queries, schema inspection
├── embeddings.ts # OpenAI embeddings — text-embedding-3-small
├── table-setup.ts # Table lifecycle — create, drop, list
└── prompts/
├── base.txt # Shared context (table schema, column descriptions)
├── remember.txt # Store operation instructions + rejection rules
├── forget.txt # Delete/modify operation instructions
├── recall.txt # Read-only search instructions
└── process.txt # Memory refinement and question-asking instructionsSystem prompts are stored as plain text files for easy editing and version control. They use {{TABLE_NAME}} and {{TABLE_SCHEMA}} placeholders that are replaced at runtime.
Requirements
Installation
git clone <repo-url>
cd memory
npm install
npm run buildEnvironment Variables
Create a .env file (see .env.example):
TURSO_DATABASE_URL=libsql://your-db.turso.io
TURSO_AUTH_TOKEN=your-turso-auth-token
OPENAI_API_KEY=sk-your-openai-api-keyCreating Memory Tables
Each use case needs its own table. Use the Claude Code /setup-table command for an interactive setup, or create tables programmatically:
import { createMemoryTable } from "./src/table-setup.js";
await createMemoryTable("github_users", [
{ name: "username", type: "TEXT" },
{ name: "category", type: "TEXT" },
{ name: "importance", type: "TEXT" },
]);Every table automatically gets these core columns:
Column | Type | Description |
| INTEGER PRIMARY KEY | Auto-incrementing ID |
| TEXT NOT NULL | The memory content |
| FLOAT32(1536) | Vector embedding for semantic search |
| TEXT NOT NULL | ISO 8601 timestamp |
Plus whatever freeform columns you define (TEXT, INTEGER, or REAL).
MCP Server Configuration
Add to your Claude Code MCP config (.claude/mcp.json or similar):
{
"mcpServers": {
"memory": {
"command": "node",
"args": ["/path/to/memory-mcp/build/index.js"],
"env": {
"TURSO_DATABASE_URL": "libsql://your-db.turso.io",
"TURSO_AUTH_TOKEN": "your-token",
"OPENAI_API_KEY": "sk-your-key"
}
}
}
}Tool Reference
remember
Store a new memory. The LLM searches for duplicates first, extracts freeform field values from context, and can reject bad input.
Parameter | Type | Description |
| string | The memory table to store into |
| string | Plain English description of what to remember |
Rejection categories: nonsensical, contradictory, duplicate, inappropriate, insufficient_detail, other
forget
Delete or modify existing memories. Searches first, then removes or updates matching entries.
Parameter | Type | Description |
| string | The memory table to modify |
| string | Plain English description of what to forget or change |
recall
Read-only memory retrieval. Can use semantic vector search, SQL queries, or both.
Parameter | Type | Description |
| string | The memory table to search |
| string | Plain English description of what to recall |
process
Review and refine existing memories. Analyzes for duplicates, gaps, and outdated entries. Returns clarifying questions for the user.
Parameter | Type | Description |
| string | The memory table to process |
| string? | Optional focus area or instructions |
process_answers
Follow-up to process. Provide answers to the questions it raised, and the system applies the refinements.
Parameter | Type | Description |
| string | The memory table being processed |
| array | The questions from the previous |
| string | Your answers in plain English |
Processing Workflow
The process → process_answers flow works in two phases:
Phase 1: Analysis (process)
The LLM fetches all memories from the table
It identifies duplicates, vague entries, missing fields, and contradictions
It generates clarifying questions with context about which memories they relate to
Questions are returned to the caller — no mutations happen yet
Phase 2: Refinement (process_answers)
The caller provides answers to the questions
The LLM uses the answers to merge duplicates, update vague memories, fill in fields, and delete outdated entries
A summary of changes is returned
Development and Testing
# Run unit tests (mocked, no API keys needed)
npm test
# Run integration tests (requires OPENAI_API_KEY)
npm run test:integration
# Run all tests
npm run test:all
# Development mode
npm run dev
# Build
npm run buildTest Structure
tests/db.test.ts— Database operations with in-memory libSQLtests/table-setup.test.ts— Table creation, indexing, and lifecycletests/llm.test.ts— System prompt content, tool filtering per operation, strict-mode schema validationtests/memory-ops.test.ts— Agentic loop, rejection handling, process mutation guard, round exhaustiontests/integration/openai.test.ts— Real OpenAI API calls testing tool selection, rejection, multi-turn flows, and strict schema acceptance (skipped withoutOPENAI_API_KEY)
Limitations and Safety Notes
SQL trust boundary — The LLM generates SQL queries and filter clauses. While
sql_queryis restricted toSELECTstatements, the model could theoretically craft queries that read across tables or use unexpected constructs. For sensitive deployments, consider adding schema-level query validation.Process scalability — The
processoperation fetches all memories from a table. For tables with many entries, this may hit token limits or become slow. Consider processing in batches for large tables.Prompt injection — Since the LLM interprets user input as natural language, adversarial inputs could potentially manipulate tool selection. The rejection system and tool filtering per operation mitigate this but don't eliminate it.
Embedding consistency — Memories are embedded with
text-embedding-3-small. Changing the embedding model requires re-embedding all existing memories.
Claude Code Commands
These commands are available when working in this repo with Claude Code:
/setup-table <name>— Interactive table creation with suggested columns based on your use case/list-tables— Show all memory tables, their schemas, and row counts/drop-table <name>— Delete a memory table (asks for confirmation first)
Available Tools
5 toolsforgetC
Delete or modify existing memories. Describe what you want to forget or change in plain English.
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | The memory table to modify | |
| description | Yes | Plain English description of what to forget or change. Be specific about which memories to target. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool performs deletion or modification, indicating a destructive operation, but lacks details on permissions, reversibility, side effects, or rate limits. This is insufficient for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, with two sentences that directly state the purpose and usage instruction. There's no wasted text, though it could be slightly more structured (e.g., separating purpose from parameter guidance). Overall, it's efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (destructive mutation), lack of annotations, and no output schema, the description is incomplete. It doesn't cover behavioral traits like safety, response format, or error handling, leaving significant gaps for an AI agent to understand the tool's full context and implications.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the schema already documents both parameters ('table' and 'description'). The description adds marginal value by emphasizing 'plain English' for the 'description' parameter, but doesn't provide additional syntax, format, or examples beyond what the schema offers. Baseline 3 is appropriate here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Delete or modify existing memories.' It specifies the verb ('Delete or modify') and resource ('existing memories'), making it understandable. However, it doesn't explicitly differentiate from sibling tools like 'recall' or 'remember' beyond the action, which keeps it from a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal guidance: 'Describe what you want to forget or change in plain English.' It implies usage for memory modification but offers no explicit when-to-use rules, alternatives (e.g., vs. 'recall' for retrieval), or exclusions. This lack of context leaves gaps in practical application.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
processB
Review and refine existing memories. Analyzes all stored memories for quality, duplicates, and gaps, then asks clarifying questions. Call again with answers to apply refinements.
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | The memory table to process | |
| context | No | Optional context or focus area for processing (e.g., 'focus on user preferences' or 'clean up old entries'). When following up on questions, provide the answers here. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses behavioral traits such as analyzing memories, asking clarifying questions, and requiring follow-up calls, which adds context beyond basic functionality. However, it lacks details on permissions, rate limits, or error handling, leaving gaps for a tool with mutation implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with two sentences that efficiently convey the tool's purpose and workflow. It's front-loaded with the main action and avoids unnecessary details, though it could be slightly more structured for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (involving analysis and iterative refinement), no annotations, and no output schema, the description is moderately complete. It outlines the process but lacks details on return values, error conditions, or full behavioral context, making it adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description adds minimal value by mentioning 'context' usage for answers, but doesn't provide additional syntax or format details beyond what the schema specifies, aligning with the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Review and refine existing memories' with specific actions like analyzing for quality, duplicates, and gaps. It distinguishes from siblings like 'remember' (create) and 'recall' (retrieve) by focusing on refinement, though it doesn't explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through phrases like 'Call again with answers to apply refinements,' suggesting a two-step workflow. However, it doesn't explicitly state when to use this versus alternatives like 'forget' or 'process_answers,' leaving some ambiguity about the tool's specific context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
process_answersC
Provide answers to questions raised by the process tool. Pass the original questions and your answers; the system will apply memory refinements based on the answers.
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | The memory table being processed | |
| questions | Yes | The questions returned by the previous process call | |
| answers | Yes | Your answers to the questions, in plain English |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the system will 'apply memory refinements based on the answers' which hints at some backend processing, but doesn't clarify what 'memory refinements' means, whether this is a read or write operation, what permissions are needed, or what happens to the data. The behavioral implications are underspecified for a tool that appears to modify memory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise at two sentences, with the first sentence stating the core purpose and the second providing additional context about system behavior. There's no obvious fluff, though the term 'memory refinements' could be more specific. The structure is front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters, no annotations, and no output schema, the description is insufficiently complete. It doesn't explain what 'memory refinements' are, what the tool actually does to the memory system, what the expected outcome is, or how this differs from other memory-related tools. The lack of behavioral transparency and output information creates significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds minimal value beyond the schema - it mentions 'original questions and your answers' which aligns with the 'questions' and 'answers' parameters, but doesn't provide additional semantic context about how answers should be formatted or how they relate to memory refinements.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'Provide answers to questions raised by the process tool' which gives a general purpose, but it's vague about what 'memory refinements' means and doesn't clearly distinguish this from sibling tools like 'process' or 'recall'. It mentions the system will apply memory refinements, but doesn't specify what that entails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions this is for questions 'raised by the process tool' which provides some context, but offers no explicit guidance on when to use this versus alternatives like 'remember' or 'recall'. There's no mention of prerequisites, when-not-to-use scenarios, or clear alternatives among the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
recallA
Recall memories without modifying them. Describe what you want to remember in plain English.
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | The memory table to search | |
| query | Yes | Plain English description of what you want to recall. Can be a topic, a person, a time period, etc. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool is read-only ('without modifying them'), which is helpful, but lacks details on permissions, rate limits, or response format. This is adequate but leaves gaps in behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences that are front-loaded and waste no words. Each sentence adds clear value: the first defines the purpose and constraint, and the second provides usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is moderately complete for a read-only tool. It covers the basic operation and parameter guidance but lacks details on what the recall returns (e.g., format, structure) or any error conditions, which could be important for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds minimal value by reinforcing the 'plain English' aspect for the query parameter, but does not provide additional syntax or format details beyond what the schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('recall memories') and distinguishes it from siblings by emphasizing 'without modifying them.' This explicitly differentiates it from tools like 'forget' or 'remember' that likely involve modification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('Describe what you want to remember in plain English'), but it does not explicitly mention when not to use it or name alternatives. This makes it good but not perfect for guiding usage relative to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
rememberC
Store a new memory. Describe what you want to remember in plain English. The system will figure out how to store it based on the table structure.
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | The memory table to store into | |
| memory | Yes | Plain English description of what to remember. Include all relevant details - who, what, when, context, etc. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions the system 'will figure out how to store it based on the table structure,' hinting at automated processing, but lacks critical behavioral details: whether this is a write operation (implied by 'store'), what permissions are needed, if it's idempotent, error handling, or what happens on success/failure. For a mutation tool with zero annotation coverage, this is inadequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: the first sentence states the purpose, and the second provides usage guidance. Both sentences earn their place by clarifying the tool's function and input expectations, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain what the tool returns, error conditions, or behavioral traits like mutability. For a memory storage tool that likely performs writes, more context is needed to guide the agent effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters ('table' and 'memory') with clear descriptions. The description adds marginal value by emphasizing 'plain English' for the memory parameter and suggesting inclusion of 'who, what, when, context, etc.,' but doesn't provide syntax or format details beyond what the schema offers. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Store a new memory') and resource ('memory'), specifying that it's stored based on table structure. It distinguishes from sibling 'forget' (deletion) and 'recall' (retrieval), but doesn't explicitly differentiate from 'process' or 'process_answers' tools, which might have overlapping memory-related functions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal guidance: 'Describe what you want to remember in plain English.' It doesn't specify when to use this tool versus alternatives like 'forget' or 'recall', nor does it mention prerequisites or constraints. The agent must infer usage from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
Most tools have distinct purposes: remember/recall handle memory storage and retrieval, forget handles deletion/modification, and process/process_answers handle refinement. However, process and process_answers are closely related and could be confused as a single operation, creating minor ambiguity in the workflow.
All tool names follow a consistent verb-based pattern in lowercase (forget, process, process_answers, recall, remember). The naming is uniform and predictable, with process_answers logically extending the process tool without breaking the convention.
With 5 tools, this server is well-scoped for memory management. Each tool serves a clear function in the CRUD lifecycle (create, read, update, delete), and the count is neither too sparse nor bloated, fitting the domain appropriately.
The tool set covers core memory operations: remember (create), recall (read), forget (delete/update), and process/process_answers (refine/update). A minor gap exists in direct update without refinement, but agents can work around this using forget or process, making it largely complete for the domain.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Persistent personal memory for AI assistants — save, search, and recall across every MCP client.
Cloud-hosted MCP server for durable AI memory
An MCP memory server. One memory your agents share — across models, devices and apps.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA local MCP server for AI assistants to store and retrieve personal memories on disk, with optional semantic search using embeddings.
- AlicenseNot gradedqualityCmaintenanceA self-hosted MCP memory server that gives AI assistants persistent, semantic memory by storing facts as vector embeddings locally, supporting semantic search and swappable embedding models.48MIT
- AlicenseNot gradedqualityCmaintenanceA self-hosted MCP server that provides a personal semantic memory layer for AI tools. It enables storing, searching, and managing memories using hybrid vector and keyword search, allowing AI assistants to recall information by meaning.MIT
- AlicenseAqualityAmaintenanceAn MCP server that provides persistent semantic memory for LLMs by building a concept graph with vector search. It enables storing, linking, and retrieving concepts across conversations using Turso vector search and 256-dimensional embeddings.226PolyForm Noncommercial 1.0.0
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/gregpriday/memory-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server