Memory Core MCP Server API Design

This guide documents the design of the Memory Core Model Context Protocol (MCP) server for Neo.mjs. This server provides a structured, agent-agnostic interface for AI agents to maintain persistent memory across sessions by exposing a collection of tools.

Overview

The Memory Core MCP server replaces the retired shell-based memory scripts with a formal set of tools (add_memory, query_raw_memories, query_summaries, and related graph/A2A operations). This provides:

• Structured Communication: JSON-based tool calls and responses instead of parsing stdout.
• Better Error Handling: Clear error messages within the tool response.
• Platform Independence: No shell-specific dependencies.
• Type Safety: Tool inputs and outputs are defined by a schema.

Architecture

The server is built using the @modelcontextprotocol/sdk and communicates with the client environment (e.g., Gemini CLI) over standard input/output (stdio). It no longer operates as an HTTP web server. The API is defined as a collection of tools in an openapi.yaml specification, which provides the single source of truth for the server's capabilities.

Data Model

The Memory Core manages two primary ChromaDB collections:

1. Memories Collection (neo-agent-memory)

Stores raw agent interaction data:

{
  "id": "mem_2025-10-08T12:00:00.000Z",
  "sessionId": "session_1696800000000",
  "timestamp": "2025-10-08T12:00:00.000Z",
  "prompt": "User's verbatim question",
  "thought": "Agent's internal reasoning",
  "response": "Agent's final answer",
  "type": "agent-interaction"
}

2. Summaries Collection (neo-agent-sessions)

Stores high-level session summaries with structured metadata:

{
  "id": "summary_session_1696800000000",
  "sessionId": "session_1696800000000",
  "timestamp": "2025-10-08T12:00:00.000Z",
  "title": "Implement MCP Server Configuration",
  "summary": "Detailed session summary...",
  "category": "feature",
  "memoryCount": 15,
  "quality": 85,
  "productivity": 90,
  "impact": 75,
  "complexity": 60,
  "technologies": ["neo.mjs", "nodejs", "chromadb"]
}

Available Tools

The server exposes the following tools, which are derived from its OpenAPI specification:

Database lifecycle is managed outside the MCP tool surface. Agents should use healthcheck to inspect ChromaDB connectivity and the configured topology rather than invoking database lifecycle commands.

Tool Specifications

This section details the parameters and behavior of each tool exposed by the Memory Core server.

Health Tools

healthcheck

Confirms server health and database connectivity. This tool takes no parameters.

Memory Tools

add_memory

Adds a new agent interaction to the memory store.

Parameters:

• prompt (string, required): The user's verbatim prompt.
• thought (string, required): The agent's internal reasoning.
• response (string, required): The agent's final response.
• sessionId (string, optional): The session ID. If not provided, one is generated.

Migration from retired CLI:

• Old way: retired shell memory script with prompt flags.
• New way: call_tool('add_memory', {prompt: "...", thought: "...", ...})

get_session_memories

Retrieves all memories for a specific session.

Parameters:

• sessionId (string, required): The session to retrieve memories for.
• limit (integer, optional): Maximum memories to return (default: 100).
• offset (integer, optional): Pagination offset (default: 0).

query_raw_memories

Performs semantic search across all memories.

Parameters:

• query (string, required): The natural language search query.
• nResults (integer, optional): Number of results to return (default: 10).
• sessionId (string, optional): An optional session ID to scope the search.

Migration from retired CLI:

• Old way: retired shell memory-query script with query flags.
• New way: call_tool('query_raw_memories', {query: "search query"})

Summary Tools

get_all_summaries

Lists all session summaries with optional filtering.

Parameters:

• limit (integer, optional): Maximum summaries to return (default: 50).
• offset (integer, optional): Pagination offset (default: 0).
• category (string, optional): Filter by category (bugfix, feature, etc.).

query_summaries

Searches session summaries semantically.

Parameters:

• query (string, required): The natural language search query.
• nResults (integer, optional): Number of results to return (default: 10).
• category (string, optional): Filter by category.

Session Tools

summarize_sessions

Triggers the session summarization process.

Parameters:

• sessionId (string, optional): If provided, only this session will be summarized. If omitted, all unsummarized sessions are processed in batch.

Migration from retired CLI:

• Old way: retired shell summarization script.
• New way: call_tool('summarize_sessions', {})

Database Tools

export_database

Exports the entire memory database to a JSONL file.

Parameters:

• include (array, optional): Collections to export (memories, summaries, or both).

Migration from retired CLI:

• Old way: retired shell export script.
• New way: call_tool('export_database', {})

import_database

Imports a previously exported JSONL file.

Parameters:

• file (string, required): The path to the JSONL backup file.
• mode (string, optional): merge (default) or replace.

Migration from retired CLI:

• Old way: retired shell import script with a file flag.
• New way: call_tool('import_database', {file: "path/to/file.jsonl"})

Error Handling

The server no longer uses HTTP status codes. Instead, errors are communicated within the CallToolResponse object. If a tool call fails, the response will have isError: true and the content will contain a descriptive error message.

Example Error Response:

{
  "content": [
    {
      "type": "text",
      "text": "Tool Error: Database connection failed. Message: Could not connect to ChromaDB."
    }
  ],
  "isError": true
}

Implementation Considerations

Authentication & Authorization

The initial implementation runs locally with no authentication. Future versions should consider:

• API key authentication for remote access
• Rate limiting to prevent abuse
• Role-based access control for multi-user scenarios

Performance Optimizations

• Pagination: Implemented for all list-based tools to handle large datasets.
• Caching: Consider caching frequently accessed summaries.
• Batch Operations: The summarize_sessions tool supports batch mode.
• Streaming: Future enhancement for large exports.

Database Consistency

• Atomic Operations: Use transactions where supported by the database.
• Validation: Validate all inputs before database operations.
• Idempotency: Ensure operations are idempotent where appropriate.

Monitoring & Logging

• Health Checks: The healthcheck tool should be monitored periodically.
• Request Logging: Memory Core records redacted MCP tool-call telemetry with tool, success, duration_ms, failure stage, bounded error metadata, and payload sizes only.
• Error Tracking: Dispatch, policy, and health-gate failures are recorded without raw Memory Core arguments or result JSON.
• Metrics: Use get_memory_core_tool_metrics for on-demand per-tool call counts, failures, and latency summaries without bloating healthcheck.

OpenAPI Specification

The complete API specification is available in OpenAPI 3.0 format at:

ai/mcp/server/memory-core/openapi.yaml

This specification can be:

• Used to generate client libraries in multiple languages.
• Imported into API development tools (Postman, Insomnia).
• Used for automated API testing.

Related Resources

• Model Context Protocol Specification
• Agent-Agnostic MCP Configuration
• Knowledge Base MCP Server API Design (coming soon)
• Strategic AI Workflows