Skip to main content
Glama

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      └───────────┘
  1. The MCP client sends a plain English request (e.g., "remember that user octocat prefers concise replies")

  2. The server loads the table schema and builds a system prompt with operation-specific instructions

  3. GPT-5 decides which internal tools to call (search, insert, update, delete, reject, or ask questions)

  4. An agentic loop executes tool calls against Turso, feeds results back to the LLM, and repeats for up to 5 rounds

  5. 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 instructions

System 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

  • Node.js 18+

  • A Turso database (or any libSQL-compatible endpoint)

  • An OpenAI API key

Installation

git clone <repo-url>
cd memory
npm install
npm run build

Environment 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-key

Creating 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

id

INTEGER PRIMARY KEY

Auto-incrementing ID

memory

TEXT NOT NULL

The memory content

embedding

FLOAT32(1536)

Vector embedding for semantic search

created_at

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

table

string

The memory table to store into

memory

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

table

string

The memory table to modify

description

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

table

string

The memory table to search

query

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

table

string

The memory table to process

context

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

table

string

The memory table being processed

questions

array

The questions from the previous process call

answers

string

Your answers in plain English

Processing Workflow

The processprocess_answers flow works in two phases:

Phase 1: Analysis (process)

  1. The LLM fetches all memories from the table

  2. It identifies duplicates, vague entries, missing fields, and contradictions

  3. It generates clarifying questions with context about which memories they relate to

  4. Questions are returned to the caller — no mutations happen yet

Phase 2: Refinement (process_answers)

  1. The caller provides answers to the questions

  2. The LLM uses the answers to merge duplicates, update vague memories, fill in fields, and delete outdated entries

  3. 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 build

Test Structure

  • tests/db.test.ts — Database operations with in-memory libSQL

  • tests/table-setup.test.ts — Table creation, indexing, and lifecycle

  • tests/llm.test.ts — System prompt content, tool filtering per operation, strict-mode schema validation

  • tests/memory-ops.test.ts — Agentic loop, rejection handling, process mutation guard, round exhaustion

  • tests/integration/openai.test.ts — Real OpenAI API calls testing tool selection, rejection, multi-turn flows, and strict schema acceptance (skipped without OPENAI_API_KEY)

Limitations and Safety Notes

  • SQL trust boundary — The LLM generates SQL queries and filter clauses. While sql_query is restricted to SELECT statements, 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 process operation 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 tools
forgetC

Delete or modify existing memories. Describe what you want to forget or change in plain English.

ParametersJSON Schema
NameRequiredDescriptionDefault
tableYesThe memory table to modify
descriptionYesPlain English description of what to forget or change. Be specific about which memories to target.

TDQS

C2.9/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
tableYesThe memory table to process
contextNoOptional 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

B3.4/5.0
Behavior3/5

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.

Conciseness4/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
tableYesThe memory table being processed
questionsYesThe questions returned by the previous process call
answersYesYour answers to the questions, in plain English

TDQS

C2.6/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose3/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
tableYesThe memory table to search
queryYesPlain English description of what you want to recall. Can be a topic, a person, a time period, etc.

TDQS

A3.9/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
tableYesThe memory table to store into
memoryYesPlain English description of what to remember. Include all relevant details - who, what, when, context, etc.

TDQS

C2.9/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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

B3.4/5.0
Disambiguation4/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness4/5

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

ActivityInactive
ResponsivenessSyncing

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

Related MCP Servers

  • A
    license
    Not graded
    quality
    C
    maintenance
    A 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.
    48
    MIT
  • A
    license
    Not graded
    quality
    C
    maintenance
    A 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
  • A
    license
    A
    quality
    A
    maintenance
    An 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.
    22
    6
    PolyForm Noncommercial 1.0.0

Latest Blog Posts

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