# MemPalace: bộ nhớ AI cục bộ — hướng dẫn cài đặt và dùng

> MemPalace là hệ thống bộ nhớ AI mã nguồn mở, lưu nguyên văn nội dung hội thoại rồi tìm kiếm theo ngữ nghĩa trên máy người dùng. Nó có CLI, MCP server, knowledge graph và nhiều backend lưu trữ. Cài đơn giản nhất bằng uv hoặc Docker; Python cần từ 3.10 trở lên.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-10-02 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/mempalace-bo-nho-ai-cuc-bo

MemPalace là hệ thống bộ nhớ AI cục bộ, giúp lưu lại lịch sử hội thoại và tìm đúng thông tin liên quan bằng semantic search. Repo phù hợp với người dùng Claude Code, Codex CLI, Cursor, Gemini CLI, lập trình viên xây ứng dụng LLM và đội nhóm muốn giữ dữ liệu trong máy hoặc mạng nội bộ.

Điểm đáng giá nhất là MemPalace lưu nội dung nguyên văn. Nó không tự tóm tắt, trích xuất hay diễn giải trước khi lưu. Nhờ vậy, bạn có thể quay lại đúng câu trả lời, quyết định hoặc đoạn trao đổi cũ thay vì phụ thuộc vào một bản tóm tắt có thể làm mất chi tiết. Đường truy xuất mặc định chạy với ChromaDB và không cần API key cho luồng cơ bản.

Repo hiện có khoảng 60.540 sao và 7.668 fork. Dự án dùng giấy phép MIT, có mã Python, CLI, MCP server, Docker image và các backend có thể thay thế.

```repo
- repo | MemPalace/mempalace
- kind | Thư viện
- desc | MemPalace lưu nguyên văn lịch sử hội thoại và tìm lại bằng semantic search ngay trên máy, không cần gọi API.
- stars | 61k
- lang | Python
- license | MIT
```

## MemPalace làm được gì

- Lưu lịch sử hội thoại nguyên văn: Nội dung được giữ lại như lúc ban đầu, giúp bạn tìm lại quyết định, yêu cầu và ngữ cảnh cũ mà không phải nhớ chính xác từ khóa.

- Tìm kiếm theo ngữ nghĩa: Bạn có thể hỏi `why did we switch to GraphQL` thay vì phải biết chính xác câu cũ chứa từ nào. Cách này hữu ích khi lịch sử dự án đã rất dài.

- Sắp xếp bộ nhớ theo cấu trúc: Người và dự án được tổ chức thành “wings”, chủ đề thành “rooms”, còn nội dung gốc nằm trong “drawers”. Bạn có thể giới hạn phạm vi tìm kiếm thay vì quét một kho phẳng.

- Chạy local-first: Theo README, dữ liệu không rời khỏi máy trừ khi bạn chủ động bật kết nối bên ngoài. Đây là điểm phù hợp với mã nguồn riêng, ghi chú nội bộ và các cuộc trò chuyện có thông tin nhạy cảm.

- Cung cấp CLI: Các lệnh như `mine`, `search`, `wake-up` và `audit` bao phủ quy trình nạp dữ liệu, tìm kiếm, nạp ngữ cảnh cho phiên mới và kiểm tra mức độ tổ chức của palace.

- Kết nối qua MCP: MCP server có 47 công cụ cho việc đọc và ghi palace, quản lý drawer, điều hướng giữa các wing, thao tác knowledge graph, nhật ký agent và bàn giao artifact.

- Hỗ trợ knowledge graph: Repo có đồ thị quan hệ thực thể theo thời gian, với các thao tác thêm, truy vấn, vô hiệu hóa và xem timeline. Dữ liệu được hỗ trợ bởi SQLite cục bộ.

- Hỗ trợ nhiều backend: ChromaDB là lựa chọn mặc định. Ngoài ra còn có `sqlite_exact`, `rust_exact`, `milvus`, `qdrant` và `pgvector`, tùy nhu cầu chạy local hay kết nối server.

- Hỗ trợ agent chuyên biệt: Mỗi agent có thể có một wing và diary riêng. Các agent có thể được phát hiện lúc chạy thông qua `mempalace_list_agents`, nên không cần nhồi toàn bộ danh sách vào system prompt.

- Có auto-save hooks: Hooks dành cho Claude Code, Codex CLI và Cursor IDE có thể lưu định kỳ, lưu trước khi nén context và hỗ trợ khôi phục lịch sử. Với transcript đã có, bạn có thể dùng `mine` hoặc `sweep` để nạp vào palace.

- Có thể chạy bằng Docker: Nếu không muốn tự quản lý Python và dependency, bạn có thể dùng image có sẵn. Dữ liệu, cấu hình và model embedding được giữ trong `/data` để tái sử dụng qua volume.

- Có benchmark tái lập được: README nêu raw semantic search đạt 96,6% R@5 trên LongMemEval mà không cần LLM, API key hay cloud. Đây là số liệu benchmark của repo, không nên hiểu là mọi dữ liệu thực tế đều đạt cùng kết quả.

## Cần chuẩn bị gì

Bạn cần Python 3.10 trở lên nếu cài trực tiếp. Repo dùng ChromaDB làm vector-store mặc định và không yêu cầu cấu hình thêm cho backend này.

Bạn cũng cần khoảng 300 MB dung lượng cho embedding model theo phần Requirements. README nêu hai lựa chọn: `embeddinggemma` dùng model embeddinggemma-300m, hỗ trợ hơn 100 ngôn ngữ và được khuyến nghị; `minilm` dùng all-MiniLM-L6-v2, chỉ dành cho tiếng Anh và có dung lượng model khoảng 30 MB. Lệnh khởi tạo có thể chọn model bằng `mempalace init --embedding-model`.

Lần đầu cần embedding, model sẽ được tải xuống. Với Docker, model nằm trong `/data`; README ước tính khoảng 80 MB cho `minilm` và khoảng 300 MB cho `embeddinggemma`. Lần gọi đầu tiên có thể chậm và cần mạng.

Không cần API key cho luồng benchmark cơ bản và cho cách chạy embedding cục bộ. Nếu muốn tính embedding trên server, bạn có thể cấu hình endpoint tương thích OpenAI bằng `embedding_model: "openai-compat"`, thêm URL, model và tùy chọn API key trong `~/.mempalace/config.json`.

GPU không bắt buộc. README nói CPU được kỳ vọng trên Apple Silicon cho MiniLM và EmbeddingGemma ONNX. GPU có thể dùng với image CUDA tự build, nhưng image GPU chỉ dành cho x86_64 và không có sẵn trên registry.

Nếu dùng Docker, cần Docker. Nếu dùng cách agent-guided setup, cần `npx` và một coding agent hỗ trợ quy trình đó. Nếu dùng backend server như Qdrant, Milvus hoặc Postgres, bạn cần dịch vụ tương ứng và biến cấu hình của backend đó.

```note
MemPalace giữ nội dung nguyên văn. Hãy kiểm tra quyền đọc trước khi mine thư mục có transcript, mã nguồn hoặc dữ liệu khách hàng. Với Docker, chỉ mount đúng những thư mục cần thiết và ưu tiên mount nguồn ở chế độ chỉ đọc.
```

## Cài đặt từng bước

```steps
- Chọn cách cài | Dùng uv, pipx, virtualenv hoặc Docker tùy môi trường
- Cài MemPalace | Cài CLI vào môi trường độc lập
- Khởi tạo palace | Tạo kho bộ nhớ cho dự án
- Nạp dữ liệu | Mine thư mục dự án hoặc transcript
- Tìm và kiểm tra | Search, wake-up và audit để xác nhận hệ thống hoạt động
```

### Chọn cách cài phù hợp

Cách được README khuyến nghị là `uv tool install`. Lệnh này đặt CLI vào môi trường cô lập, giúp tránh lỗi PEP 668 trên Debian, Ubuntu hoặc Python của Homebrew và tránh xung đột với `chromadb`, `numpy`, `grpcio` cùng các dependency khác.

Nếu đã dùng pipx, bạn có thể cài bằng pipx. Nếu muốn import `mempalace` trong một dự án Python cụ thể, hãy dùng virtualenv đã kích hoạt rồi mới chạy pip.

```bash
uv tool install mempalace
```

Hoặc:

```bash
pipx install mempalace
```

Cách dùng pip trong virtualenv:

```bash
python -m venv .venv && source .venv/bin/activate
pip install mempalace
```

Lệnh `python -m venv .venv` tạo môi trường Python riêng. Lệnh `source .venv/bin/activate` kích hoạt môi trường trên shell kiểu Unix. Trên Windows, README không đưa lệnh kích hoạt PowerShell tương ứng, nên bạn cần dùng cách kích hoạt phù hợp với shell đang mở hoặc chọn uv, pipx hay Docker.

### Cài bằng skills nếu bạn dùng coding agent

MemPalace có quy trình agent-guided setup. Trước tiên cài các skill của repo:

```bash
npx skills add MemPalace/mempalace
```

Repo cung cấp ba skill: `mempalace` để hướng dẫn cài đặt và vận hành, `mempalace-recall` để tìm lại bộ nhớ trước khi trả lời, và `mempalace-task` để phân công qua logstream.

Cài skill chưa tự cài CLI hoặc MCP server. Sau bước này, setup skill sẽ hướng dẫn agent nhận diện hệ thống, cài package Python, cấu hình MCP và chọn một trong ba kiểu: palace riêng, hub dùng chung hoặc client kết nối tới hub có sẵn.

### Khởi tạo palace

Sau khi cài CLI, tạo palace cho dự án bằng lệnh sau:

```bash
mempalace init ~/projects/myapp
```

Thay `~/projects/myapp` bằng thư mục dự án bạn muốn quản lý nếu môi trường của bạn dùng đường dẫn khác. Người mới thường chạy lệnh ở nhầm thư mục hoặc trỏ vào một thư mục không có quyền đọc. Hãy kiểm tra đường dẫn trước khi chạy.

Nếu muốn chọn model embedding, README cho biết có thể dùng tùy chọn `--embedding-model`. Hai lựa chọn được nêu là `embeddinggemma` và `minilm`. Việc đổi model trên palace đã có dữ liệu yêu cầu embedding lại.

### Nạp mã nguồn hoặc hội thoại

Để nạp file dự án:

```bash
mempalace mine ~/projects/myapp
```

Để nạp các phiên Claude Code:

```bash
mempalace mine ~/.claude/projects/ --mode convos
```

Bạn có thể giới hạn theo project bằng `--wing`. Lệnh `mine` đọc nội dung nguồn và đưa vào palace. Với Docker, thư mục nguồn phải được mount vào container; container chỉ thấy những gì bạn mount.

Nếu cần lưu từng message user hoặc assistant thay vì các chunk cấp file mà hooks tạo ra, README hướng dẫn dùng:

```bash
mempalace sweep <transcript-dir>
```

Lệnh này lưu một drawer nguyên văn cho mỗi message, có thể chạy lại và tiếp tục an toàn.

### Cài và chạy bằng Docker

Nếu không muốn cài Python toolchain, tải image:

```bash
docker pull ghcr.io/mempalace/mempalace:latest
```

Chạy MCP server qua stdio:

```bash
docker run -i --rm -v mempalace-data:/data ghcr.io/mempalace/mempalace
```

Cờ `-i` quan trọng vì JSON-RPC cần stdin. Volume `mempalace-data` giữ palace, cấu hình và embedding model sau khi container kết thúc.

Nạp một thư mục dự án ở chế độ chỉ đọc:

```bash
docker run --rm -v mempalace-data:/data -v /path/to/project:/work:ro \
  ghcr.io/mempalace/mempalace mine /work
```

Tìm kiếm trong palace:

```bash
docker run --rm -v mempalace-data:/data ghcr.io/mempalace/mempalace search "why GraphQL"
```

Khi cấu hình MCP client, dùng đường dẫn tuyệt đối. Không phải MCP client nào cũng tự mở rộng `~` hoặc `$HOME`.

```json
{
  "mcpServers": {
    "mempalace": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "mempalace-data:/data",
        "-v", "/absolute/path/to/.claude/projects:/transcripts:ro",
        "ghcr.io/mempalace/mempalace"
      ]
    }
  }
}
```

Trong container, hãy dùng `/transcripts`, không dùng đường dẫn host như `~/.claude/projects`. Trên Linux, image chạy với uid 1000. Thư mục bind mount phải cho uid này quyền đọc; thư mục `0755` thường phù hợp, còn `0700` có thể gây `PermissionError: [Errno 13]`. Không dùng `--user` để né lỗi vì `/data` cần được uid 1000 ghi.

### Tự build image nếu cần

Các lệnh build được README cung cấp:

```bash
docker build -t mempalace .
docker build --build-arg EXTRAS="extract,spellcheck" -t mempalace .
docker build -f Dockerfile.gpu -t mempalace:gpu .
```

Hai lệnh đầu dùng cho image CPU. Lệnh cuối dùng CUDA và khi chạy cần `--gpus all`. GPU image chỉ dành cho x86_64; trên máy ARM, gồm Apple Silicon, build có thể thất bại do không có wheel Linux aarch64 cho `onnxruntime-gpu`.

## Kiểm tra đã chạy được chưa

Chạy tìm kiếm sau khi đã nạp dữ liệu:

```bash
mempalace search "why did we switch to GraphQL"
```

Nếu lệnh trả về các đoạn hội thoại hoặc nội dung liên quan đến GraphQL, embedding và backend đang hoạt động. Lần gọi đầu có thể lâu vì model cần được tải xuống.

Nạp context cho phiên mới:

```bash
mempalace wake-up
```

Nếu chạy được và trả về context từ palace, kho bộ nhớ đã có dữ liệu để sử dụng.

Kiểm tra chất lượng tổ chức bằng lệnh chỉ đọc:

```bash
mempalace audit
```

README mô tả `audit` là thao tác chỉ đọc và an toàn khi MCP server đang chạy. Bạn cũng có thể kiểm tra MCP bằng cách kết nối client tới server rồi gọi các công cụ MemPalace; repo mô tả server có 47 MCP tools.

## Dùng vào việc thật

### Chủ shop muốn nhớ cách xử lý đơn và khách hàng

Chủ shop có thể nạp thư mục chứa ghi chú vận hành hoặc dự án quản lý đơn:

```bash
mempalace mine ~/projects/myapp
```

Sau đó tìm bằng câu hỏi tự nhiên:

```bash
mempalace search "how did we handle the delayed delivery complaint"
```

Kết quả là các đoạn nội dung nguyên văn liên quan. Cách này phù hợp khi chủ shop nhớ tình huống nhưng không nhớ chính xác từ khóa đã ghi trong tài liệu.

### Nhân viên văn phòng cần tìm lại quyết định cũ

Nếu các cuộc trao đổi được lưu trong thư mục transcript, hãy nạp chúng:

```bash
mempalace mine ~/.claude/projects/ --mode convos
```

Sau đó dùng `search` với câu hỏi như `why did we choose this workflow` hoặc `what was the agreed approval process`. MemPalace tìm theo ý nghĩa và trả lại ngữ cảnh gốc, giúp bạn chuẩn bị báo cáo hoặc tiếp tục công việc mà không phải đọc lại toàn bộ lịch sử.

### Dev muốn khôi phục ngữ cảnh dự án

Dev có thể nạp mã nguồn, rồi mở phiên mới bằng:

```bash
mempalace wake-up
```

Khi cần truy lại lý do của một thay đổi:

```bash
mempalace search "why did we switch to GraphQL"
```

Nếu làm việc với Claude Code, Codex CLI hoặc Cursor IDE, có thể cấu hình auto-save hooks để lưu định kỳ và trước khi context compression. README cũng khuyến nghị backfill transcript cũ bằng `mempalace mine`.

### Đội nhóm muốn dùng MCP và phân tách agent

Đội phát triển có thể chạy MCP server bằng Docker, giữ dữ liệu trong volume:

```bash
docker run -i --rm -v mempalace-data:/data ghcr.io/mempalace/mempalace
```

Mỗi specialist agent có thể có wing và diary riêng. Knowledge graph hỗ trợ theo dõi quan hệ thực thể theo thời gian. Cách này phù hợp với nhóm có nhiều agent cùng làm việc và cần bàn giao artifact hoặc logstream event qua MCP.

> Bộ nhớ tốt không chỉ là nhớ nhiều, mà là tìm lại đúng ngữ cảnh khi bạn cần.
>
> — Ông T

## Lỗi hay gặp và cách xử lý

### Cài pip vào Python hệ thống bị lỗi PEP 668

Đây là lỗi dễ gặp trên Debian, Ubuntu hoặc Python của Homebrew. README khuyên dùng `uv tool install` để cài trong môi trường cô lập, hoặc dùng pipx. Nếu dùng pip, hãy tạo và kích hoạt virtualenv trước.

### Lần chạy đầu tưởng bị treo

Lần đầu cần embedding, model phải tải xuống nên lệnh có thể chậm và cần mạng. Với Docker, hãy đảm bảo volume `/data` được giữ lại; nếu xóa volume, model có thể phải tải lại.

### Docker báo PermissionError khi mine

Trên Linux, kiểm tra quyền đọc của thư mục bind mount đối với uid 1000 trong image. Thư mục `0700` có thể không đọc được. Đừng thêm `--user` tùy tiện vì có thể khiến container không ghi được vào `/data`.

### MCP client không thấy transcript

Container chỉ nhìn thấy thư mục đã mount. Hãy mount đúng thư mục transcript và dùng đường dẫn container, chẳng hạn `/transcripts`. Trong cấu hình MCP, dùng đường dẫn host tuyệt đối vì `~` và `$HOME` không được mọi client mở rộng.

### Đổi embedding model nhưng kết quả tìm kiếm không đúng

Đổi model tạo ra không gian vector khác. README yêu cầu re-embed bằng `mempalace repair rebuild-index`. Đổi thiết bị tính toán thì không cần làm vậy, nhưng đổi model trên palace hiện có thì cần.

## Có nên dùng không

MemPalace đáng dùng nếu bạn muốn một lớp bộ nhớ AI chạy local, giữ nguyên văn dữ liệu và có thể kết nối với agent qua MCP. CLI dễ bắt đầu, Docker thuận tiện cho môi trường không muốn quản lý Python, còn backend pluggable cho phép mở rộng khi nhu cầu tăng. Việc có knowledge graph, auto-save hooks và nhiều công cụ MCP cũng giúp repo phù hợp với workflow agent dài hạn.

Giới hạn cần cân nhắc là embedding model phải tải lần đầu, dữ liệu nguyên văn cần được quản lý quyền truy cập, và một số lựa chọn nâng cao yêu cầu server hoặc dependency riêng. Native Termux hiện chưa được hỗ trợ trực tiếp vì ChromaDB và ONNX Runtime có wheel Linux chứ không có wheel Android; Android ARM64 cần Debian PRoot container. GPU image không phù hợp với ARM.

Nếu bạn chỉ cần một bộ nhớ nhỏ trong một ứng dụng Python và không cần CLI, MCP hay tổ chức theo wing-room-drawer, một giải pháp vector store đơn giản có thể nhẹ hơn. Nếu cần dịch vụ quản trị hoàn toàn trên cloud, MemPalace cũng không phải lựa chọn mặc định vì định hướng chính của repo là local-first. Còn nếu ưu tiên dữ liệu nằm trong máy, truy xuất nguyên văn và khả năng mở rộng cho nhiều agent, đây là một lựa chọn rất đáng thử.

## Câu hỏi thường gặp

### MemPalace có miễn phí không?

README mô tả MemPalace là hệ thống AI memory mã nguồn mở và miễn phí. Repo dùng giấy phép MIT. Tuy vậy, chi phí hạ tầng, Docker hoặc dịch vụ embedding bên ngoài nếu bạn tự chọn không được README chi tiết.

### Có cần GPU hoặc API key không?

Không cần GPU cho luồng cơ bản; README nêu CPU là lựa chọn kỳ vọng trên Apple Silicon. Không cần API key cho benchmark raw và embedding chạy cục bộ. API key chỉ có thể cần khi bạn cấu hình endpoint embedding tương thích OpenAI có yêu cầu xác thực.

### Có chạy được trên Windows không?

README không ghi rõ quy trình cài native trên Windows. README nói Docker Desktop ánh xạ uid trên macOS và Windows, nên Docker là hướng được mô tả rõ hơn cho môi trường này.

### Dữ liệu có rời khỏi máy không?

Theo README, dữ liệu không rời khỏi máy trừ khi bạn chủ động bật kết nối bên ngoài. Model embedding có thể cần tải lần đầu; nếu dùng embedding server hoặc backend server, dữ liệu sẽ tuân theo cấu hình mạng của bạn.

### Có thể dùng với Claude Code, Codex CLI và Cursor không?

Có. README nêu hướng dẫn cho Claude Code, Codex CLI và Cursor IDE, cùng auto-save hooks để lưu định kỳ và trước khi nén context. Claude Code transcript cũng có thể nạp bằng `mempalace mine ... --mode convos`.

### Backend mặc định là gì? Có đổi được không?

ChromaDB là backend mặc định và không cần cấu hình. Repo còn có `sqlite_exact`, `rust_exact`, `milvus`, `qdrant` và `pgvector`; có thể chọn bằng `--backend`, biến `MEMPALACE_BACKEND` hoặc `config.json`.

### Đổi embedding model có làm mất dữ liệu không?

README nói đổi model trên palace hiện có yêu cầu re-embedding, cụ thể là chạy `mempalace repair rebuild-index`. Việc đổi thiết bị tính toán đơn thuần không yêu cầu bước này.
