Skip to main content
Glama
cbuntingde

Memory MCP Server

by cbuntingde
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

Copyright 2025 Chris Bunting cbuntingde@gmail.com

Memory MCP Server

MIT License

Memory MCP Server

A production-ready Model Context Protocol (MCP) server implementing a robust three-tiered memory architecture designed for vertical AI agents and applications requiring sophisticated context management.

Glama Badge License: MIT Node.js Version TypeScript

Overview

The Memory MCP Server provides a comprehensive, persistent, and session-based memory management system through three specialized and configurable memory types:

  • Short-term Memory: Volatile, session-specific context with a configurable Time-To-Live (TTL), ideal for maintaining conversational state or temporary operational data. (Default TTL: 30 minutes)

  • Long-term Memory: Persistent storage for user profiles, preferences, demographics, and other stable, long-lived data that defines user characteristics.

  • Episodic Memory: A searchable, time-stamped log of events, interactions, and experiences, enriched with sentiment analysis and tagging for advanced context retrieval and pattern recognition.

This architecture enables AI agents to maintain continuity across sessions, personalize interactions based on historical data, and reason over past events to provide more intelligent and context-aware responses.

Architecture

Project Structure

The project is organized with a clear separation of concerns, promoting maintainability, scalability, and testability.

memory-mcp-server/
├── src/
│   ├── types/              # TypeScript type definitions and interfaces
│   │   └── index.ts
│   ├── store/              # Core memory storage and retrieval logic
│   │   └── MemoryStore.ts
│   ├── handlers/           # MCP protocol handlers (Tools, Resources, Prompts)
│   │   ├── ResourceHandlers.ts
│   │   ├── ToolHandlers.ts
│   │   └── PromptHandlers.ts
│   ├── config/             # Server configuration and settings management
│   │   └── ServerConfig.ts
│   ├── utils/              # Shared utility functions (logging, validation, etc.)
│   │   ├── Logger.ts
│   │   └── Validation.ts
│   └── index.ts            # Main server entry point and MCP server setup
├── memory-data/            # Default directory for persistent data storage
│   ├── long-term.json      # Stores long-term user profiles and preferences
│   └── episodic.json       # Stores episodic event and experience logs
├── test-memory.js          # Functional test suite
├── package.json            # Project dependencies and scripts
├── tsconfig.json           # TypeScript compiler configuration
├── .gitignore              # Git ignore rules
├── LICENSE                 # MIT license file
└── README.md               # This file

Memory Tiers

Memory Type

Persistence

Primary Use Case

TTL

Storage Mechanism

Short-term

In-memory only

Session context, temporary state, conversational flow.

Configurable (default: 30 minutes)

Volatile RAM

Long-term

Disk-based (JSON)

User profiles, preferences, demographics, contact info.

Permanent (until explicitly deleted)

memory-data/long-term.json

Episodic

Disk-based (JSON)

Event history, experiences, interactions, sentiment tracking.

Permanent (until explicitly deleted)

memory-data/episodic.json

Data Flow

  1. Request: An MCP client (e.g., an AI agent) sends a request via a tool, resource, or prompt.

  2. Handler: The appropriate handler (ToolHandlers.ts, ResourceHandlers.ts, or PromptHandlers.ts) receives and parses the request.

  3. Validation: Input parameters are validated using Validation.ts.

  4. Store Interaction: The handler interacts with MemoryStore.ts to perform CRUD operations on the respective memory tier.

  5. Persistence: For long-term and episodic memories, data is atomically written to JSON files on disk.

  6. Response: The result is formatted and returned to the MCP client.

  7. Logging: All operations are logged via Logger.ts for monitoring and debugging.

Installation

Prerequisites

  • Node.js: Version 16.0 or higher.

  • npm: Version 7.0 or higher (or yarn/pnpm).

  • MCP Client: An application or environment that can connect to and utilize MCP servers (e.g., Cline, Claude Desktop).

Setup

  1. Clone the Repository

    git clone https://github.com/cbuntingde/memory-mcp-server.git
cd memory-mcp-server

  2. Install Dependencies

    npm install
# or
yarn install
# or
pnpm install

  3. Build the Project Compile the TypeScript source code into JavaScript.

    npm run build

  4. Configure Your MCP Client You need to inform your MCP client about the Memory Server. This is typically done by adding a configuration entry to your client's settings file (e.g., cline_mcp_settings.json for Cline, or claude_desktop_config.json for Claude Desktop).

    Example MCP Configuration:

    {
  "mcpServers": {
    "memory-server": {
      "command": "node",
      "args": ["./path/to/memory-mcp-server/build/index.js"],
      "env": {
        "MEMORY_DATA_DIR": "./custom-memory-data" // Optional: override default data directory
      },
      "settings": {
        "dataDirectory": "./memory-mcp-server/memory-data", // Optional: can also be set here
        "defaultTTLMinutes": 30, // Optional: override default short-term TTL
        "logLevel": "info" // Optional: set logging level (trace, debug, info, warn, error)
      }
    }
  }
}

    Replace ./path/to/memory-mcp-server/build/index.js with the actual path to the built index.js file.

API Reference

The server exposes its functionality through MCP Tools, Resources, and Prompts.

Tools

Tools are used for actions that modify or retrieve specific data.

Tool Name

Description

Required Parameters

Optional Parameters

set_short_term_memory

Stores a key-value pair in a session's short-term memory.

sessionId (string), key (string), value (any JSON-serializable)

ttlMinutes (number)

get_short_term_memory

Retrieves all data for a given session from short-term memory.

sessionId (string)

-

set_long_term_memory

Creates or updates a user's long-term memory profile.

userId (string), data (object)

-

get_long_term_memory

Retrieves a user's long-term memory profile.

userId (string)

-

add_episodic_memory

Adds a new event or experience to a user's episodic memory.

userId (string), event (string)

context (string), outcome (string), sentiment ('positive', 'negative', 'neutral'), tags (string[]), sessionId (string)

get_episodic_memory

Retrieves all episodic memories for a user, optionally sorted.

userId (string)

sortBy ('timestamp_asc', 'timestamp_desc', 'sentiment'), limit (number)

search_episodic_memory

Searches a user's episodic memory by keyword, tag, or sentiment.

userId (string), query (string)

searchIn ('event', 'context', 'outcome', 'tags'), limit (number)

Resources

Resources provide access to structured data, typically in JSON format.

Resource URI

Description

Returns

memory://long-term/{userId}

Fetches the complete long-term memory profile for a specific user.

JSON object representing the user's profile.

memory://episodic/{userId}

Fetches all episodic memory entries for a specific user.

JSON array of episodic memory objects.

Prompts

Prompts are templates that guide an AI agent to generate responses based on memory data.

Prompt Name

Description

Required Arguments

Optional Arguments

memory_summary

Generates a comprehensive summary of a user's profile and recent history.

userId (string)

includeEpisodicCount (number, default: 10)

personalization_insights

Extracts key personalization opportunities from a user's long-term and episodic data.

userId (string)

-

Usage Examples

Here are practical examples demonstrating how to interact with the Memory MCP Server using its tools.

Managing a User Profile (Long-term Memory)

// Store comprehensive user preferences and demographics
await client.callTool({
  name: "set_long_term_memory",
  arguments: {
    userId: "user-abc-123",
    data: {
      demographics: {
        age: 42,
        location: "San Francisco, CA",
        occupation: "Software Engineer"
      },
      contact: {
        email: "user@example.com",
        phone: "+1-555-123-4567" // Note: Ensure compliance with privacy regulations
      },
      preferences: {
        seating: "window seat",
        temperature: "cool",
        communicationStyle: "concise",
        interests: ["technology", "hiking", "photography"]
      }
    }
  }
});

// Retrieve the user's profile
const userProfile = await client.callTool({
  name: "get_long_term_memory",
  arguments: {
    userId: "user-abc-123"
  }
});
console.log("User Profile:", userProfile);

Recording and Searching Interactions (Episodic Memory)

// Record a positive customer service interaction
await client.callTool({
  name: "add_episodic_memory",
  arguments: {
    userId: "user-abc-123",
    sessionId: "session-xyz-789",
    event: "Customer inquired about premium features.",
    context: "User was on the pricing page and initiated a support chat.",
    outcome: "Explained premium benefits, user seemed interested.",
    sentiment: "positive",
    tags: ["support", "pricing", "premium-features"]
  }
});

// Search for past interactions related to "pricing"
const pricingInteractions = await client.callTool({
  name: "search_episodic_memory",
  arguments: {
    userId: "user-abc-123",
    query: "pricing",
    searchIn: "event",
    limit: 5
  }
});
console.log("Pricing-related interactions:", pricingInteractions);

Maintaining Session Context (Short-term Memory)

// Store the current state of a user's shopping cart
await client.callTool({
  name: "set_short_term_memory",
  arguments: {
    sessionId: "session-xyz-789",
    key: "shopping_cart",
    value: {
      items: [
        { productId: "prod-001", name: "Memory MCP Server License", quantity: 1, price: 99.99 }
      ],
      total: 99.99,
      currency: "USD"
    },
    ttlMinutes: 60 // Extend TTL for this session
  }
});

// Retrieve the cart later in the session
const currentCart = await client.callTool({
  name: "get_short_term_memory",
  arguments: {
    sessionId: "session-xyz-789"
  }
});
console.log("Current Shopping Cart:", currentCart?.shopping_cart);

Generating a User Summary (Prompt)

// Ask the AI agent to generate a summary of the user
const summaryPrompt = await client.getPrompt({
  name: "memory_summary",
  arguments: {
    userId: "user-abc-123",
    includeEpisodicCount: 15
  }
});
// The 'summaryPrompt' would then be fed to the LLM to generate a textual summary.
console.log("Prompt for LLM:", summaryPrompt.messages[0].content.text);

Data Models

Long-term Memory Structure

Data stored in long-term.json follows this structure:

{
  "userId": {
    "demographics": {
      "age": "number | null",
      "location": "string | null",
      "occupation": "string | null"
    },
    "contact": {
      "email": "string | null",
      "phone": "string | null"
    },
    "preferences": {
      "seating": "string | null",
      "temperature": "string | null",
      "communicationStyle": "string | null",
      "interests": "string[] | null"
    },
    "metadata": {
      "createdAt": "timestamp (ISO 8601 string)",
      "lastUpdated": "timestamp (ISO 8601 string)"
    }
  }
}

Episodic Memory Structure

Data stored in episodic.json follows this structure:

{
  "id": "episodic_{timestamp}_{randomId}",
  "userId": "string",
  "sessionId": "string | null",
  "event": "string",
  "context": "string | null",
  "outcome": "string | null",
  "sentiment": "positive | negative | neutral | null",
  "tags": "string[]",
  "timestamp": "number (Unix epoch in ms)",
  "metadata": {
    "createdAt": "timestamp (ISO 8601 string)"
  }
}

Development

Available Scripts

# Install dependencies
npm install

# Build the project from TypeScript to JavaScript in /build
npm run build

# Build in watch mode for development (auto-recompile on changes)
npm run watch

# Run the functional test suite (requires build first)
npm run test

# Run the MCP Inspector for debugging MCP server interactions
npm run inspector

Testing

The project includes a functional test suite located in test-memory.js. These tests verify the core functionality of all memory operations.

To run the tests:

  1. Ensure the project is built: npm run build

  2. Execute the test script: npm run test or node test-memory.js

The tests will create and use a temporary data directory to avoid interfering with production data.

Code Style and Quality

  • TypeScript: All code is written in TypeScript for type safety and better developer experience.

  • ESLint & Prettier: Configured for consistent code style and quality (ensure you have editor plugins or run linting manually).

  • Logging: Comprehensive logging is implemented using Logger.ts. Log levels can be configured via environment variables or MCP settings.

  • Validation: All external inputs are rigorously validated using Validation.ts to prevent errors and ensure data integrity.

Production Considerations

Performance

  • Memory Operations (Short-term): Typically < 5ms. Operates entirely in memory.

  • Disk Operations (Long-term/Episodic): Typically < 50ms on modern SSDs. File I/O is atomic and synchronous to ensure data consistency.

  • Search Operations (Episodic): Performance scales linearly with the number of records. < 100ms for datasets up to 10,000 records. For larger datasets, consider integrating a dedicated search engine (e.g., Lunr.js, ElasticSearch).

  • Memory Usage: Primarily determined by the size of in-memory short-term data and the active working set of long-term/episodic data loaded from disk.

Security

  • Input Validation: All parameters passed to tools and resources are strictly validated for type, format, and content to prevent injection attacks and malformed data.

  • Data Sanitization: While the server itself doesn't render HTML, data is stored in a way that assumes it might be used in contexts where escaping is necessary.

  • File System Security: The server writes to a specific, configurable directory. Ensure this directory has appropriate permissions to prevent unauthorized access or modification.

  • No External Dependencies: The server has no network dependencies, reducing the attack surface.

  • Local Data Storage: All data is stored locally on the file system. You are responsible for securing the host machine and the data directory.

Reliability & Data Integrity

  • Atomic Writes: Disk writes for long-term and episodic memories are performed atomically (write to a temporary file, then rename) to prevent data corruption if the process is interrupted.

  • Graceful Degradation: If the data directory becomes unwritable, the server will log errors but continue to function for short-term memory operations.

  • Automatic Cleanup: Short-term memory entries are automatically purged when their TTL expires, preventing memory leaks.

  • Error Handling: Comprehensive error handling is implemented throughout, with clear error messages returned to the MCP client where appropriate.

Monitoring & Observability

  • Structured Logging: All operations are logged with relevant context (user ID, session ID, operation type, duration) in a structured format (JSON), making it easy to parse and analyze logs.

  • Log Levels: Configurable log levels (trace, debug, info, warn, error) allow for verbose debugging during development and minimal logging in production.

  • Health Checks: The server responds to standard MCP pings, allowing for basic health monitoring.

  • Data Integrity Checks: On startup, the server can optionally verify the basic structure of existing data files (planned for future versions).

Troubleshooting

Common Issues

Server fails to start or MCP client cannot connect.

  • Verify Node.js Version: Ensure you are using Node.js 16.0 or higher (node -v).

  • Check Build Step: Run npm run build to ensure the TypeScript code is compiled to /build/index.js.

  • Check File Path: In your MCP client configuration, double-check the path to build/index.js. It should be an absolute path or a path relative to where the MCP client is run.

  • Examine Logs: Check the console output from the MCP client or the terminal where you might be running the server directly for error messages. Enable debug logging: DEBUG=memory-server:* node build/index.js.

Data is not persisting across server restarts.

  • Data Directory Permissions: Ensure the memory-data/ directory (or your custom dataDirectory) exists and is writable by the process running the server.

  • Disk Space: Verify that there is sufficient disk space available on the volume where the data directory is located.

  • Configuration: Confirm that the dataDirectory setting in your MCP configuration is pointing to the correct and intended location.

"Memory not found" errors.

  • ID Validation: Double-check the userId or sessionId for typos or incorrect formatting.

  • TTL Expiration: For short-term memory, confirm that the session has not expired (i.e., its TTL has not been exceeded).

  • Operation Sequencing: Ensure that data was written to memory before attempting to read it. Check logs for previous write operations.

Debug Mode

For detailed debugging output, you can run the server with the DEBUG environment variable set:

# From the project directory
DEBUG=memory-server:* node build/index.js

This will enable verbose logging for all components of the memory server, providing insights into internal operations, data flow, and potential issues.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Please ensure all code adheres to the project's coding standards and includes appropriate tests for new functionality.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

  • Issues & Bug Reports: Please use the GitHub Issues page to report bugs or request features.

Production Implementation: This server is built with a focus on robustness, security, and operational reliability, making it suitable for integration into production AI systems and applications.

Available Tools

7 tools
add_episodic_memoryC

Add a new episodic memory (past experience or event)

ParametersJSON Schema
NameRequiredDescriptionDefault
contextYesContext surrounding the event
eventYesDescription of the event
outcomeNoOutcome or resolution of the event
sentimentNoSentiment of the experience
sessionIdNoOptional session identifier
tagsNoTags for categorizing the memory
userIdYesUser identifier

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 states the tool adds a memory but doesn't disclose behavioral traits like whether this is a write operation (implied but not explicit), what permissions are needed, how duplicates are handled, or what happens on success/failure. For a mutation tool with zero annotation coverage, this is a significant gap.

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 a single, efficient sentence with zero waste. It's front-loaded with the core purpose and includes clarifying parentheses that add value without verbosity. Every word earns its place.

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 complexity (7 parameters, 3 required), lack of annotations, and no output schema, the description is incomplete. It doesn't explain what the tool returns, error conditions, or behavioral nuances. For a mutation tool with rich parameters, more context is needed to guide effective use.

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 fully documents all 7 parameters. The description adds no parameter-specific information beyond what's in the schema, such as examples or usage notes. With high schema coverage, the baseline is 3, as the description doesn't compensate but also doesn't need to.

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 ('Add') and resource ('episodic memory'), with additional clarifying context ('past experience or event'). It distinguishes from siblings like 'get_episodic_memory' by specifying creation rather than retrieval. However, it doesn't explicitly differentiate from other memory-setting tools like 'set_long_term_memory' beyond the memory type.

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 no guidance on when to use this tool versus alternatives. With siblings like 'set_long_term_memory', 'set_short_term_memory', and 'search_episodic_memory', there's no indication of appropriate contexts, prerequisites, or exclusions for this specific tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_episodic_memoryC

Retrieve episodic memories for a user

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of memories to return
userIdYesUser identifier

TDQS

C2.6/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 the full burden of behavioral disclosure. It only states the action ('retrieve') without detailing aspects like authentication needs, rate limits, error handling, or what the return format looks like (e.g., list of memories with timestamps). This leaves significant gaps in understanding how the tool behaves in practice.

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 a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized for a simple retrieval tool, though it could be more front-loaded with key details if expanded.

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 lack of annotations and output schema, the description is incomplete. It doesn't explain what episodic memories are, how they're structured, or what the return values include, which is crucial for a tool with sibling memory types and no structured output documentation. This leaves the agent under-informed about the tool's context and results.

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%, with clear descriptions for both parameters ('limit' and 'userId') in the input schema. The description adds no additional meaning beyond this, such as explaining the format of 'userId' or typical 'limit' values. Baseline 3 is appropriate as the schema does the heavy lifting.

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 verb ('retrieve') and resource ('episodic memories for a user'), which provides a basic understanding of the tool's function. However, it lacks specificity about what episodic memories are or how they differ from other memory types, and doesn't distinguish this tool from sibling tools like 'get_long_term_memory' or 'get_short_term_memory', making the purpose somewhat vague.

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 no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'search_episodic_memory' for filtered retrieval or differentiate from other memory types, leaving the agent with no context for tool selection beyond the basic purpose.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_long_term_memoryC

Retrieve long-term memory for a user

ParametersJSON Schema
NameRequiredDescriptionDefault
userIdYesUser identifier

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 only states the retrieval action without detailing what 'long-term memory' entails (e.g., format, scope, or persistence), whether it requires authentication, or if there are rate limits. This is inadequate for a tool with no 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is appropriately sized and front-loaded, making it easy to parse quickly.

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 complexity of memory retrieval tools and the lack of annotations or output schema, the description is incomplete. It doesn't explain what 'long-term memory' returns, how it differs from other memory types, or any behavioral traits, leaving significant gaps for an AI agent to understand its use.

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 input schema has 100% description coverage, with the 'userId' parameter clearly documented. The description adds no additional parameter semantics beyond what the schema provides, such as explaining the user context or memory retrieval specifics. Baseline 3 is appropriate since the 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 ('Retrieve') and resource ('long-term memory for a user'), making the purpose understandable. However, it doesn't distinguish this tool from its siblings like 'get_episodic_memory' or 'get_short_term_memory', which also retrieve memory types, so it lacks sibling differentiation.

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 no guidance on when to use this tool versus alternatives. It doesn't mention when to prefer long-term over short-term or episodic memory, nor does it reference sibling tools like 'set_long_term_memory' for updates or 'search_episodic_memory' for queries, leaving usage context unclear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_short_term_memoryC

Retrieve data from short-term memory

ParametersJSON Schema
NameRequiredDescriptionDefault
keyNoMemory key (optional, returns all if not provided)
sessionIdYesSession identifier

TDQS

C2.7/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 the full burden of behavioral disclosure. It states the tool retrieves data, implying a read-only operation, but does not specify if it requires authentication, has rate limits, returns structured or unstructured data, or handles errors. This leaves significant gaps in understanding the tool's behavior beyond basic retrieval.

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 a single, efficient sentence with no wasted words. It is front-loaded with the core action and resource, making it easy to parse quickly. Every word earns its place by directly conveying the tool's 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?

Given the lack of annotations and output schema, the description is incomplete for a retrieval tool. It does not explain what data is returned, in what format, or any behavioral traits like error handling. For a tool with 2 parameters and no structured output, more context is needed to guide effective usage.

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%, with clear documentation for both parameters: 'key' (optional, returns all if not provided) and 'sessionId' (required). The description does not add any meaning beyond what the schema provides, such as explaining the format of keys or session IDs, so it meets the baseline for high schema coverage without extra value.

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 'Retrieve data from short-term memory' clearly states the verb ('retrieve') and resource ('short-term memory'), distinguishing it from siblings like 'add_episodic_memory' or 'set_short_term_memory'. However, it lacks specificity about what kind of data is retrieved or the scope, making it somewhat vague compared to a fully detailed purpose statement.

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 no guidance on when to use this tool versus alternatives like 'get_long_term_memory' or 'get_episodic_memory'. It does not mention any prerequisites, exclusions, or specific contexts for usage, leaving the agent to infer based on tool names alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_episodic_memoryC

Search episodic memories by content

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of results
queryYesSearch query
userIdYesUser identifier

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 the full burden of behavioral disclosure. It states 'search' but doesn't explain what constitutes an episodic memory, how results are ranked, whether it's read-only or has side effects, or any limitations like rate limits. For a search tool with zero annotation coverage, this is a significant gap in transparency.

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 a single, efficient sentence with zero waste—'Search episodic memories by content'—that directly conveys the core action. It's appropriately sized and front-loaded, making it easy to parse quickly.

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 complexity of searching memories, lack of annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects like result format, error handling, or how it differs from siblings. For a tool with 3 parameters and no structured safety hints, more context is needed to be fully helpful.

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%, with clear descriptions for 'limit', 'query', and 'userId'. The description adds no additional meaning beyond the schema, such as query syntax or result format. With high schema coverage, the baseline is 3, as the description doesn't compensate but also doesn't detract.

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 verb ('search') and resource ('episodic memories') with the scope 'by content', making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_episodic_memory' or 'get_long_term_memory', which might also retrieve memories, so it misses full sibling distinction.

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 no guidance on when to use this tool versus alternatives. With siblings like 'get_episodic_memory' and 'get_long_term_memory' that might retrieve memories differently, there's no indication of context, prerequisites, or exclusions, leaving usage ambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_long_term_memoryC

Store user demographics, contact details, or preferences

ParametersJSON Schema
NameRequiredDescriptionDefault
contactNoContact information
demographicsNoUser demographics (age, location, occupation, etc.)
preferencesNoUser preferences and settings
userIdYesUser identifier

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 but offers minimal behavioral insight. It states what gets stored but doesn't disclose whether this creates new records or updates existing ones, what permissions are required, whether data persists permanently, or what happens on success/failure. For a data storage 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 a single, efficient sentence that gets straight to the point with no wasted words. It's appropriately sized for a simple storage operation, though it could be more front-loaded with critical behavioral information given the lack of annotations.

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 data storage tool with no annotations and no output schema, the description is insufficient. It doesn't explain what happens after storage (success response, error conditions), whether this overwrites existing data, or how it differs from sibling storage tools. The context demands more completeness for safe and effective use.

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 4 parameters thoroughly. The description mentions the same three data categories (demographics, contact, preferences) but adds no additional meaning beyond what the schema provides. The baseline of 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.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool stores user data (demographics, contact details, preferences), which is a clear verb+resource combination. However, it doesn't distinguish this from sibling tools like 'set_short_term_memory' or 'add_episodic_memory' - the purpose is clear but lacks sibling differentiation.

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 no guidance on when to use this tool versus alternatives. With siblings like 'set_short_term_memory' and 'get_long_term_memory', there's no indication of when this long-term storage is appropriate versus short-term or when to retrieve versus store data.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_short_term_memoryC

Store data in short-term memory for a session

ParametersJSON Schema
NameRequiredDescriptionDefault
keyYesMemory key
sessionIdYesSession identifier
ttlMinutesNoTime to live in minutes (default: 30)
valueYesMemory value (any JSON-serializable data)

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 action ('Store') but lacks details on permissions, idempotency, error handling, or what happens on conflicts. It mentions TTL via the schema but doesn't explain behavioral implications like automatic expiration.

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 a single, efficient sentence with zero waste. It's front-loaded with the core action and resource, making it easy to parse quickly without unnecessary elaboration.

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 mutation tool with no annotations and no output schema, the description is incomplete. It doesn't cover behavioral aspects like side effects, return values, or error conditions. Given the complexity of memory operations and lack of structured safety hints, more context is needed for safe agent invocation.

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 fully documents all parameters. The description adds no additional semantic context beyond implying session-scoped storage, which is already covered by the 'sessionId' parameter in the schema. Baseline 3 is appropriate as the schema handles parameter documentation.

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 verb ('Store') and resource ('data in short-term memory'), specifying it's for a session. However, it doesn't explicitly differentiate from sibling tools like 'set_long_term_memory' or 'add_episodic_memory', which would require mentioning the specific memory type and session scope.

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 implies usage for session-specific storage but provides no explicit guidance on when to use this tool versus alternatives like 'set_long_term_memory' or 'add_episodic_memory'. There's no mention of prerequisites, exclusions, or comparative contexts with sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.3/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: add vs. get vs. search for episodic memory, get vs. set for long-term and short-term memory. No ambiguity exists between tools, as they target specific memory types and operations.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern with underscores (e.g., add_episodic_memory, get_long_term_memory). The naming is predictable and uniform across all seven tools.

Tool Count5/5

With 7 tools, the server is well-scoped for memory management, covering episodic, long-term, and short-term memory with appropriate operations. Each tool earns its place without feeling excessive or insufficient.

Completeness4/5

The toolset provides good coverage for memory operations, including CRUD-like actions (add/get/set) and search. A minor gap exists in not having update or delete operations for memories, but agents can likely work around this by re-setting or ignoring outdated entries.

Resources

Related MCP Connectors

Appeared in Searches

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/cbuntingde/memory-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server