Memory MCP

Memory MCP (local-first)

Yêu cầu

• Node.js >= 20
• Docker + Docker Compose

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

| Script | Mô tả | |--------|--------| | npm run dev | MCP server (tsx watch, stdio) | | npm run build | tsc → dist/ | | npm start | node dist/index.js | | npm test | Vitest: unit + integration (xem bên dưới) | | npm run db:migrate | Chạy migration Postgres theo thứ tự (0001_init, 0002_phase2_indexes, …) | | npm run qdrant:bootstrap | Tạo collection Qdrant nếu chưa có |

ENV

Copy .env.example thành .env.

| Biến | Ý nghĩa | |------|---------| | PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE | Kết nối Postgres (PGPORT=55432 khi dùng compose như mặc định repo) | | QDRANT_URL | REST API Qdrant (mặc định http://localhost:6333) | | QDRANT_COLLECTION | Tên collection điểm vector | | EMBEDDING_PROVIDER | Phase 0–1: hash (embedding offline) | | EMBEDDING_DIMENSION | Chiều vector (mặc định 384) | | LOG_LEVEL | Mức log pino | | MCP_ACTOR | Actor mặc định cho audit (optional) |

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.

| Tool | Vai trò ngắn | |------|----------------| | remember | Lưu memory có scope + metadata; dedupe; index Qdrant best-effort | | recall | Truy vấn (vector + metadata), fallback metadata khi lỗi phụ thuộc | | get_context_pack | Gói context (semantic / procedural / episodic) + trường mở rộng cố định | | forget_memory | Soft transition (archive / delete / expire) + audit | | update_memory | Phase 2: cập nhật có optimistic locking (expected_version); re-index vector; audit memory.update | | remember_facts | Phase 2: ghi fact (subject / predicate / object) gắn với memory_id đã tồn tại |

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:

| Mã | Khi nào | |----|--------| | EMBEDDING_UNAVAILABLE | embedder.embed lỗi | | VECTOR_SEARCH_UNAVAILABLE | search Qdrant lỗi (hoặc cảnh báo khi xóa vector lỗi lúc forget_memory) | | DEGRADED_RETRIEVAL_MODE | Đang dùng fallback metadata |

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.