LearnNewsExamplesConnect

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 uses @modelcontextprotocol/sdk through Neo's shared MCP server infrastructure, with transport selected by the deployment. 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 authored diary entries for future sessions. Stored Chroma metadata retains the physical thought key (and canonical Agent Thought: turn text) for revision-digest stability, while MCP read projections expose prompt, decisionContext (on authorized private reads, omitted on public reads), and response:

{
  "id": "mem_2025-10-08T12:00:00.000Z",
  "sessionId": "session_1696800000000",
  "timestamp": "2025-10-08T12:00:00.000Z",
  "prompt": "Summarized task context and constraints",
  "decisionContext": "Concise decisions and deciding facts recorded for the turn",
  "response": "Outcomes, artifact references and continuation",
  "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:

Tool Name Description
Health
healthcheck Confirms the server is running and can connect to the ChromaDB instance.
Diagnostics
get_sandman_handoff Reads the Sandman handoff (Dream Pipeline morning surface) with freshness metadata (stale flag past the window, overridable per call). Defaults to sections: ['goldenPath'] (sections.goldenPath + availableSections / missingSections); pass sections: 'all' for full content or specific section slugs (gaps, consolidation, goldenPath, focus). A missing file returns an explicit null-reason payload. Serves remote/container agents without a repo checkout.
Memories
add_memory Writes a turn diary entry for future sessions using the prompt, decisionContext and response fields.
get_session_memories Retrieves all memories for a specific session in chronological order (prompt, decisionContext, response).
query_raw_memories Performs semantic search across raw memories (decisionContext included on projection='private', omitted on 'public').
query_recent_turns Recalls recent turns in reverse-chronological order (`detail='summary'
Graph
get_neighbors Retrieves bounded, filtered, deterministically ordered adjacent graph nodes and pagination metadata.
Summaries
get_all_summaries Retrieves all session summaries, sorted by timestamp.
query_summaries Performs semantic search across session summaries.
Sessions
summarize_sessions Triggers the session summarization process.
Database
export_database Exports the entire memory database to a JSONL file.
import_database Imports a previously exported JSONL file back into the database.

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

Write a concise turn diary entry for future sessions in the factual register of a commit message or decision record. The reader should be able to recover the task's intent, understand a consequential choice and its deciding fact, and continue when the relevant conditions still hold.

State only decisions, deciding facts, and artifact references — never write a first-person account of how you reasoned. A routine turn needs only a sentence or two. If a provider stop ever rejects an entry, do not retry that entry in another wording; save only the ticket/PR IDs and outcomes and inform the operator.

Parameters:

  • prompt (string, required): Summarized task context, intended outcome and constraints.
  • decisionContext (string, required): Decisions made in the turn, each paired with its deciding fact or source reference, plus what stays open — written in the concise register of a commit message or decision record.
  • response (string, required): Outcomes, artifact references and continuation.
  • sessionId (string, optional): The session ID; when omitted, the existing request-bound Mcp-Session-Id header is used when present, otherwise the process's current session is used.

Worked diary example — a consequential choice:

This historical example is based on the release-policy change at 03e403dff85b1f3a78ed9ba56be7ab10b8672739. Its state is the author's 2026-10-09 source receipt, not a live release claim.

{
  "prompt": "Separate maintainer releases from Dependabot maintenance while retaining validation and human-only merges.",
  "decisionContext": "Classify releases by merged PR author rather than workflow actor so human merges of Dependabot PRs skip npm publish (neomjs/neo-agent-skills#149 @ 03e403d). Open: observe deployed skip after merge; revisit if GitHub's author contract changes.",
  "response": "Policy PR149 at 03e403d had green CI and awaited cross-family review. Its code and evidence are at https://github.com/neomjs/neo-agent-skills/pull/149. After human merge, rebase PR147, require fresh hosted CI and observe its merge skipping publication and tagging; the same policy must still publish maintainer releases."
}

The choice, rejected alternatives and decisive reason are in the entry. The PR carries the full code and test receipts. A future reader can inspect those artifacts before treating the policy as deployed.

Simple-turn example — routine review routing:

This is a historical routing entry from 2026-10-09, before the replacement review was posted.

{
  "prompt": "Reroute the review of https://github.com/neomjs/neo-agent-skills/pull/149 after its reviewer released the seat.",
  "decisionContext": "Previous reviewer reported no review posted (confirmed on GitHub); retained head 03e403dff85b1f3a78ed9ba56be7ab10b8672739 and requested one replacement reviewer.",
  "response": "The sole requested reviewer is @neo-fable-clio. PR149 at that unchanged head remains CI green and awaits the review, then a human merge. Recheck the live PR before acting on this dated entry."
}

The entry carries the PR reference, exact head and next owner a later session needs, with a dated state that must be checked live. It does not invent alternative designs for a mechanical handoff.

Migration from retired CLI:

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

get_session_memories

Retrieves all memories for a specific session in chronological order, returning prompt, decisionContext (concise decisions and deciding facts), response, and miniSummary.

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 raw memories. On detail='full', returns decisionContext on authorized private reads and omits decisionContext when projection='public'. Legacy Agent Thought: headers in raw/reconstructed turn documents are normalized to Decision Context: at the read boundary.

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.
  • detail ('full' | 'summary', optional): 'full' (default) or compact 'summary'.
  • projection ('public' | 'private', optional): 'public' omits decisionContext; 'private' preserves it.

Migration from retired CLI:

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

query_recent_turns

Recalls recent turns in reverse-chronological order for post-compaction recovery or scoped peer inspection. On detail='full', projection='private' (own-agent tenant recovery only) includes decisionContext, while projection='public' (default) omits it.

Parameters:

  • agentIdentity (string, optional): Whose turns to recall ('@me' default).
  • limit (integer, optional): Maximum turns to return (1..100, default: 20).
  • before ({timestamp, id}, optional): Compound pagination cursor (nextCursor from prior page).
  • detail ('summary' | 'full', optional): 'summary' (default) or 'full'.
  • projection ('public' | 'private', optional): 'public' (default) or 'private'.
  • memorySharing ('private' | 'team' | 'legacy', optional): Explicit narrow-only sharing override.

Graph Tools

get_neighbors

Retrieves a bounded, deterministically ordered page of adjacent graph nodes (weight descending, then id ascending, then relationship ascending) alongside pagination metadata ({neighbors, totalCount, truncated, nextOffset, limit, offset}). Self-loop edges on direction='both' are deduplicated, and AGENT_MEMORY descriptions use "Turn diary entry inside session <sessionId>.".

Parameters:

  • id (string, required): Source graph node ID.
  • limit (integer, optional): Page size clamped to 1..200 (default: 50).
  • offset (integer, optional): Non-negative zero-based pagination offset (default: 0).
  • direction ('both' | 'inbound' | 'outbound', optional): Edge traversal direction (default: 'both').
  • types (string[], optional): Adjacent node label filter (e.g. ['ISSUE', 'PULL_REQUEST', 'AGENT_MEMORY']).
  • relationships (string[], optional): Connecting edge relationship filter (e.g. ['ORIGINATES_IN', 'DISCUSSED_IN']).

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