Memory MCP (local-first)

Yêu cầu

• Node.js >= 20

• Docker + Docker Compose

Related MCP server: Engram

Docker (phiên bản image)

• Postgres: postgres:16-alpine

• Qdrant: qdrant/qdrant:v1.9.3

Checklist khởi động

1. docker compose up -d

2. npm install

3. Copy .env.example → .env (Postgres host mặc định 127.0.0.1:55432)

4. npm run db:migrate

5. npm run qdrant:bootstrap

6. npm run dev hoặc npm run build && npm start

Scripts

ENV

Copy .env.example thành .env.

MCP tools (stdio)

Server giao tiếp JSON-RPC qua stdout. Log (pino) trên stderr — không redirect stderr nếu cần xem log.

recall / fallback metadata lọc memory đã hết hạn (expires_at); có thể bổ sung cảnh báo CONFLICTING_FACTS khi hai fact trong workspace mâu thuẫn (cùng subject+predicate, khác object).

Payload chi tiết theo Zod trong src/contracts/tools/*.ts.

Ví dụ cấu hình Cursor

Thêm MCP server trỏ tới entrypoint đã build (hoặc tsx):

{
  "mcpServers": {
    "memory-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/Memory-mcp/dist/index.js"],
      "env": {
        "PGHOST": "127.0.0.1",
        "PGPORT": "55432",
        "PGUSER": "memory",
        "PGPASSWORD": "memory",
        "PGDATABASE": "memory_mcp",
        "QDRANT_URL": "http://127.0.0.1:6333",
        "QDRANT_COLLECTION": "memories",
        "EMBEDDING_PROVIDER": "hash",
        "EMBEDDING_DIMENSION": "384"
      }
    }
  }
}

Đường dẫn và env chỉnh theo máy bạn.

Chế độ suy giảm (recall / context pack)

Khi embedding hoặc Qdrant lỗi, recall vẫn trả ok: true với retrieval chỉ từ Postgres (metadata / keyword nhẹ), kèm warnings:

Lỗi business (input sai, scope, không tìm thấy, v.v.) trả ok: false + error.code từ INVALID_INPUT, SCOPE_VIOLATION, NOT_FOUND, DEPENDENCY_UNAVAILABLE, …

Tests

npm test

• Unit: không cần Docker.

• Integration (src/testing/integration/memoryMcp.int.test.ts): cần Postgres (và Qdrant cho luồng vector thật trong vài case). Nếu không kết nối được DB trong ~8s, các case đó bỏ qua (log cảnh báo), suite vẫn PASS.

• Tắt hẳn integration: SKIP_INTEGRATION=1 npm test.