MCP Memory API Endpoints

Overview

Model Context Protocol (MCP) endpoints for semantic memory storage, search, and management. Requires API key authentication.

Endpoint Summary

Endpoint Method Auth Description
/v1/memory/write POST API Key Write memory entry
/v1/memory/search POST API Key Semantic memory search
/v1/memory/delete POST API Key Delete memory entry
/v1/memory/clear POST API Key Clear memories
/v1/memory/banks/list GET API Key List memory banks
/v1/memory/banks/ping GET API Key Ping banks service
/v1/memory/banks/debug GET None Debug endpoints

Authentication

All MCP endpoints require API key authentication:

X-API-Key: your-api-key

Or in the Authorization header:

Authorization: ApiKey your-api-key

Namespace RBAC

Write operations enforce namespace-level permissions. API keys are configured with allowed namespace patterns:

{
  "my-api-key": ["org:team:*", "public:*"],
  "admin-key": ["*"]
}

Memory Write

POST /v1/memory/write

Description: Writes a memory entry to the semantic store.

Authentication: API Key required

Request Body:

{
  "namespace": "org:team:project",
  "actorId": "user-123",
  "text": "The deployment configuration uses port 8080 for the API server",
  "tags": ["deployment", "config", "api"],
  "ttlMs": 86400000
}
Field Type Required Description
namespace string Yes Memory namespace (subject to RBAC)
actorId string No Actor/user identifier
text string Yes Memory content
tags string[] No Searchable tags
ttlMs long No Time-to-live in milliseconds

Response:

{
  "id": "mem_abc123",
  "namespace": "org:team:project",
  "createdAt": "2025-11-29T12:00:00Z",
  "expiresAt": "2025-11-30T12:00:00Z"
}

Error Responses:

Status Error Description
400 Bad Request Missing namespace or text
401 Unauthorized Missing/invalid API key
403 Forbidden API key not permitted for namespace
502 Bad Gateway MCP backend error
504 Gateway Timeout MCP backend timeout

Memory Search

POST /v1/memory/search

Description: Performs semantic search across memories.

Authentication: API Key required

Request Body:

{
  "query": "deployment configuration port settings",
  "namespace": "org:team:project",
  "actorId": "user-123",
  "topK": 10
}
Field Type Required Description
query string Yes Search query text
namespace string No Filter by namespace
actorId string No Filter by actor
topK int No Max results (1-50, default: 10)

Response:

{
  "results": [
    {
      "id": "mem_abc123",
      "text": "The deployment configuration uses port 8080...",
      "namespace": "org:team:project",
      "tags": ["deployment", "config"],
      "score": 0.92,
      "createdAt": "2025-11-29T12:00:00Z"
    }
  ],
  "totalResults": 5,
  "queryTime": 45
}

Response Fields:

Field Type Description
results array Matching memories
results[].id string Memory ID
results[].text string Memory content
results[].namespace string Memory namespace
results[].tags string[] Memory tags
results[].score double Relevance score (0-1)
results[].createdAt DateTime Creation timestamp
totalResults int Total matching count
queryTime int Query time in ms

Memory Delete

POST /v1/memory/delete

Description: Deletes a specific memory entry.

Authentication: API Key required

Request Body:

{
  "id": "mem_abc123"
}
Field Type Required Description
id string Yes Memory ID to delete

Response:

{
  "deleted": true,
  "id": "mem_abc123"
}

Memory Clear

POST /v1/memory/clear

Description: Clears all memories matching criteria.

Authentication: API Key required

Request Body:

{
  "namespace": "org:team:project",
  "actorId": "user-123"
}
Field Type Required Description
namespace string No Clear by namespace (RBAC enforced)
actorId string No Clear by actor

Response:

{
  "cleared": 15,
  "namespace": "org:team:project"
}

Memory Banks

GET /v1/memory/banks/list

Description: Lists available memory banks.

Authentication: API Key required

Response:

["default", "org:team:project", "public:docs"]

GET /v1/memory/banks/ping

Description: Health check for banks service.

Authentication: API Key required

Response:

{
  "ok": true,
  "ts": "2025-11-29T12:00:00Z",
  "area": "banks"
}

GET /v1/memory/banks/debug

Description: Debug endpoint information (development only).

Authentication: None

Response:

{
  "ok": true,
  "ts": "2025-11-29T12:00:00Z",
  "env": "Development",
  "mcpEnabled": true,
  "mcpBase": "http://localhost:6060",
  "expectedRoutes": [
    "/api/v1/memory/banks/ping",
    "/api/v1/memory/banks/list (GET,POST)",
    "/api/v1/memory/banks/debug-endpoints"
  ]
}

Examples

Write a Memory

curl -X POST "https://api.example.com/v1/memory/write" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "project:docs",
    "text": "API rate limit is 100 requests per minute",
    "tags": ["api", "rate-limit"]
  }'

Search Memories

curl -X POST "https://api.example.com/v1/memory/search" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "rate limit configuration",
    "topK": 5
  }'

Delete a Memory

curl -X POST "https://api.example.com/v1/memory/delete" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"id": "mem_abc123"}'

List Memory Banks

curl -X GET "https://api.example.com/v1/memory/banks/list" \
  -H "X-API-Key: your-api-key"

Integration Patterns

Copilot Extension

The MCP Memory extension automatically injects relevant memories into chat context:

const memories = await searchMemories(userQuery, topK: 5);
const enrichedPrompt = buildEnrichedMessages(query, memories);

GitLab/Jira Integration

MCP also provides proxy endpoints for GitLab and Jira:

Endpoint Method Description
/v1/gitlab/projects/list POST List GitLab projects
/v1/gitlab/issues/search POST Search GitLab issues
/v1/jira/issues/search POST Search Jira issues
/v1/jira/issues/get POST Get Jira issue details
/v1/ssh/exec POST Execute SSH commands

Related Documentation