# MemPalace: bộ nhớ AI chạy trên máy bạn, tìm lại mọi cuộc trò chuyện — hướng dẫn cài đặt và dùng

> MemPalace là công cụ dòng lệnh Python giúp AI có bộ nhớ dài hạn: nó lưu nguyên văn hội thoại và tài liệu trên máy bạn rồi tìm lại theo ý nghĩa. Nó cũng có máy chủ MCP để nối với Claude Code và các công cụ tương tự. Cài bằng một lệnh uv hoặc pipx, mức khó từ dễ đến vừa.

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

MemPalace là một công cụ bộ nhớ cho AI, chạy ngay trên máy bạn. Nó lưu nguyên văn các cuộc trò chuyện và file dự án, rồi cho bạn (hoặc trợ lý AI của bạn) tìm lại bằng tìm kiếm theo ý nghĩa. Nó không tóm tắt hay diễn đạt lại nội dung, nên thứ bạn lấy ra luôn là chữ gốc.

Vấn đề repo giải quyết rất quen thuộc: bạn làm việc với Claude Code hay một trợ lý AI khác cả tuần, rồi phiên mới mở ra thì AI quên sạch. Bạn nhớ mang máng hôm trước đã bàn "vì sao đổi sang GraphQL" nhưng không biết tìm ở đâu. MemPalace gom các phiên đó lại một chỗ để hỏi lại được. Người nên dùng là lập trình viên, người hay làm việc dài hơi với AI và ai muốn dữ liệu nằm trên máy mình.

Điểm đáng giá nhất: README nói chế độ tìm kiếm cơ bản đạt 96,6% R@5 trên bộ đo LongMemEval mà không cần gọi API hay LLM nào. Repo hiện có khoảng 60.500 sao và 7.600 fork, giấy phép MIT.

```repo
- repo | MemPalace/mempalace
- kind | CLI
- desc | MemPalace lưu nguyên văn các cuộc trò chuyện và file dự án trên máy bạn, rồi tìm lại bằng tìm kiếm ngữ nghĩa, không cần gọi API.
- stars | 61k
- lang | Python
- license | MIT
```

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

**Lưu nguyên văn, tìm theo ý nghĩa.** Bạn không cần nhớ đúng từ khoá. Gõ "why did we switch to GraphQL" là nó tìm đoạn hội thoại liên quan. Vì lưu nguyên văn nên bạn không lo AI tóm tắt sai ý.

**Tổ chức như một toà lâu đài.** Người và dự án thành *wing* (cánh), chủ đề thành *room* (phòng), nội dung gốc nằm trong *drawer* (ngăn kéo). Nhờ vậy bạn thu hẹp được phạm vi tìm, ví dụ chỉ tìm trong dự án A, thay vì lục cả kho.

**Nạp ngữ cảnh cho phiên mới.** Lệnh `mempalace wake-up` tải lại ngữ cảnh để phiên làm việc mới không bắt đầu từ con số không.

**Chạy cục bộ.** README ghi rõ: không có gì rời khỏi máy bạn trừ khi bạn tự bật. Chế độ tìm kiếm cơ bản không cần API key.

**Máy chủ MCP với 47 công cụ.** Qua MCP, trợ lý AI có thể đọc ghi bộ nhớ, thao tác đồ thị tri thức, quản lý ngăn kéo, ghi nhật ký cho từng agent và điều phối giữa các agent.

**Đồ thị tri thức theo thời gian.** Lưu quan hệ giữa các thực thể (người, dự án…) kèm khoảng thời gian có hiệu lực, dựa trên SQLite cục bộ. Bạn có thể thêm, truy vấn, vô hiệu hoá và xem dòng thời gian.

**Hook tự động lưu.** Có hook cho Claude Code, Codex CLI và Cursor IDE, tự lưu định kỳ và trước khi ngữ cảnh bị nén.

**Đổi được nơi lưu trữ.** Mặc định là ChromaDB. Ngoài ra có `sqlite_exact`, `rust_exact`, `milvus`, `qdrant`, `pgvector`. Người mới cứ dùng mặc định, không cần cấu hình gì.

**Bộ kỹ năng (skill) cho trợ lý AI.** Repo có ba skill: `mempalace` để cài đặt và vận hành có hướng dẫn, `mempalace-recall` để tìm trong bộ nhớ trước khi trả lời, `mempalace-task` để giao việc qua logstream.

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

- **Python 3.10 trở lên.** Đây là yêu cầu trong README và file `pyproject.toml`.
- **Một backend vector.** Mặc định là ChromaDB và đã đi kèm sẵn, bạn không phải cài riêng.
- **Khoảng 300 MB ổ đĩa** cho mô hình embedding (mô hình biến chữ thành vector để tìm theo nghĩa). Có hai lựa chọn: `embeddinggemma` (đa ngôn ngữ, hơn 100 ngôn ngữ, README khuyên dùng) hoặc `minilm` (chỉ tiếng Anh, nhẹ hơn, khoảng 30 MB). Vì bạn người Việt, bản đa ngôn ngữ là hướng đáng cân nhắc. Chọn lúc `mempalace init` bằng tuỳ chọn `--embedding-model`.
- **Công cụ cài đặt:** README khuyên dùng `uv`, hoặc `pipx`. Dùng `pip` thường thì phải ở trong môi trường ảo.
- **Không cần API key** cho đường chạy cơ bản. Không cần GPU: README nói trên Apple Silicon dùng CPU là bình thường.
- **Docker** (tuỳ chọn) nếu bạn không muốn cài Python.
- Android/Termux: bản cài thẳng chưa được hỗ trợ.

```note
Chỉ tải từ ba nguồn chính thức: kho GitHub, gói PyPI tên mempalace, và trang mempalaceofficial.com. README cảnh báo các tên miền khác (đuôi .tech, .net hoặc biến thể .com) là giả mạo và có thể phát tán mã độc.
```

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

Có hai đường: nhờ trợ lý AI cài giúp (qua skill), hoặc tự cài bằng CLI. Phần dưới hướng dẫn đường tự cài, vì lệnh rõ ràng và dễ kiểm soát.

```steps
- Cài uv | Công cụ quản lý môi trường Python mà README khuyên dùng
- Cài mempalace | Dùng uv tool install để có lệnh mempalace trên PATH
- Khởi tạo | Chạy mempalace init với thư mục dự án của bạn
- Nạp dữ liệu | Dùng mempalace mine để đưa file hoặc hội thoại vào
- Tìm thử | Dùng mempalace search để hỏi lại
```

### Cài uv (nếu chưa có)

README khuyên dùng `uv` nhưng không ghi lệnh cài uv. Bạn xem hướng dẫn cài trên trang tài liệu của uv (docs.astral.sh/uv). Nếu thích `pipx`, README nói dùng cũng được và cách làm tương tự.

### Cài MemPalace

Mở terminal (PowerShell hoặc Terminal trên máy bạn). Lệnh nào cũng gõ ở đây, không cần vào thư mục đặc biệt.

```bash
uv tool install mempalace
```

Lệnh này cài MemPalace vào một môi trường riêng và đưa lệnh `mempalace` ra ngoài, nên không đụng tới các thư viện Python khác trên máy. Đây là lý do README khuyên cách này: tránh lỗi PEP 668 trên Debian/Ubuntu/Homebrew và tránh xung đột thư viện.

Nếu dùng pipx:

```bash
pipx install mempalace
```

Nếu muốn dùng `pip` thường, hãy làm trong môi trường ảo đã kích hoạt:

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

Lệnh `source .venv/bin/activate` là của macOS/Linux. README không ghi dòng tương đương cho Windows, nên người dùng Windows nên ưu tiên `uv` hoặc `pipx`.

### Khởi tạo cho một dự án

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

Đổi `~/projects/myapp` thành thư mục dự án của bạn. Lệnh `init` cũng là nơi bạn chọn mô hình embedding bằng `--embedding-model` (`embeddinggemma` hoặc `minilm`). Lần đầu cần embedding, mô hình sẽ được tải về nên sẽ chậm và cần mạng.

### Nạp dữ liệu và tìm thử

```bash
# Mine content into the palace
mempalace mine ~/projects/myapp                    # project files
mempalace mine ~/.claude/projects/ --mode convos   # Claude Code sessions (scope with --wing per project)

# Search
mempalace search "why did we switch to GraphQL"
```

Dòng đầu đưa file dự án vào. Dòng thứ hai đưa các phiên Claude Code đã lưu vào, `--mode convos` báo cho công cụ đây là hội thoại. README gợi ý dùng `--wing` để chia theo từng dự án. Chữ sau dấu `#` chỉ là chú thích, bạn không cần gõ.

### Cách khác: nhờ trợ lý AI cài giúp

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

Lệnh này (cần có Node/npx) thêm ba skill vào trợ lý. Sau đó bạn nhờ trợ lý "cài MemPalace". Skill sẽ dò hệ thống, cài gói Python, cấu hình MCP và hỏi bạn muốn palace riêng trên máy, hub dùng chung hay kết nối tới hub có sẵn. Lưu ý: chỉ cài skill thì CLI và máy chủ MCP chưa có, việc đó do bước hướng dẫn của skill làm.

### Cách khác: dùng Docker

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

Chạy máy chủ MCP qua stdio (nhớ cờ `-i`):

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

Chạy một lệnh CLI, ví dụ mine thư mục dự án (container chỉ thấy thư mục bạn mount, `:ro` nghĩa là chỉ đọc):

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

Mọi thứ lưu trong `/data`, nên phải mount volume ở đó để không mất dữ liệu. Lần đầu chạy sẽ tải mô hình embedding (khoảng 80 MB cho `minilm`, khoảng 300 MB cho `embeddinggemma`), nên có thể trông như bị treo. Đừng vội tắt.

Để nối vào Claude Code hay client MCP khác như một server stdio, README đưa cấu hình sau:

```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"
      ]
    }
  }
}
```

Hãy dùng đường dẫn tuyệt đối thật. `~` và `$HOME` không phải client nào cũng hiểu. Từ đó trở đi, đường dẫn là đường dẫn trong container: bạn mine `/transcripts`, không phải `~/.claude/projects`.

Về cách nối MCP khi cài bằng `uv` hay `pipx` (không dùng Docker): phần README mình có chưa ghi lệnh cụ thể. Bạn xem trang hướng dẫn bắt đầu và trang tham chiếu công cụ MCP trên mempalaceofficial.com, hoặc dùng skill cài đặt ở trên.

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

Cách đơn giản nhất là chạy chuỗi lệnh trong phần Quickstart của README và xem có kết quả không:

1. Chạy `mempalace mine` với một thư mục nhỏ có vài file văn bản.
2. Chạy `mempalace search` với một câu hỏi mà bạn biết đáp án nằm trong các file đó.
3. Nếu kết quả trả về đúng đoạn liên quan, cài đặt đã ổn.

Bạn cũng có thể chạy:

```bash
mempalace audit
```

Lệnh này chấm điểm mức độ ngăn nắp của palace. README ghi nó chỉ đọc, nên an toàn kể cả khi máy chủ MCP đang chạy. Nếu bạn dùng Docker, lần đầu chậm vì tải mô hình là chuyện bình thường.

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

### Lập trình viên muốn nhớ lý do của một quyết định

Bạn làm dự án vài tháng với Claude Code. Giờ đồng nghiệp hỏi "sao hồi đó mình chọn GraphQL?" mà không ai nhớ. Bạn đã nạp các phiên cũ bằng lệnh mine ở chế độ hội thoại, nên chỉ cần:

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

Kết quả là các đoạn hội thoại gốc nơi hai bên bàn về chuyện đó, đúng từng chữ. Bạn đọc lại lý do thay vì đoán.

> Khác biệt lớn nhất là AI không còn "đoán lại" quá khứ, nó đưa bạn đúng câu đã nói.
>
> — Ông T

### Mở phiên làm việc mới mà không phải kể lại từ đầu

Sáng thứ Hai bạn mở một phiên mới cho dự án cũ. Thay vì dán lại cả đống ghi chú, bạn chạy:

```bash
mempalace wake-up
```

Nó nạp ngữ cảnh đã lưu để phiên mới có điểm xuất phát. Nếu nối MCP và cài skill `mempalace-recall`, trợ lý có thể tự tìm trong bộ nhớ trước khi trả lời.

### Giữ lại các phiên Claude Code trước khi hết hạn

README cảnh báo: phiên Claude Code hết hạn sau 30 ngày nếu chưa gắn hook tự lưu. Nếu bạn có nhiều phiên quý, làm theo gợi ý của README: gắn hook, sao lưu các file JSONL hội thoại hiện có, rồi nạp lại:

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

Sau đó, để có khả năng tìm từng tin nhắn một, chạy định kỳ lệnh sau (README mô tả: mỗi tin nhắn của người dùng và trợ lý thành một ngăn kéo nguyên văn, chạy lại không bị lặp, bị ngắt thì chạy tiếp được):

```bash
mempalace sweep <thư-mục-hội-thoại>
```

Thay `<thư-mục-hội-thoại>` bằng thư mục chứa hội thoại của bạn.

### Nhóm nhỏ muốn dùng chung một bộ nhớ

README có nhắc chế độ "hub dùng chung" khi cài qua skill, và có file `deploy/docker-compose.server.yml` để dựng máy chủ cho nhóm. Phần README mình có chưa mô tả chi tiết cách vận hành. Nếu bạn thuộc nhóm có người biết Docker, hãy bắt đầu từ file đó và tài liệu trên trang chính thức. Người dùng cá nhân thì không cần bước này.

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

**Lỗi `PermissionError: [Errno 13]` khi dùng Docker trên Linux.** Image chạy bằng uid 1000, nên thư mục bạn mount phải đọc được bởi uid đó. Thư mục quyền `0755` thì ổn, `0700` thì lỗi. README dặn đừng né bằng `--user`, vì như vậy tiến trình sẽ không ghi được vào `/data`. Hãy sửa quyền thư mục nguồn.

**Lệnh Docker như bị treo ở lần chạy đầu.** Thường là nó đang tải mô hình embedding vào `/data` (vài chục đến khoảng 300 MB). Chờ và kiểm tra mạng. Nếu bạn quên mount volume, lần nào cũng phải tải lại.

**Máy chủ MCP qua Docker không kết nối được.** Hai lỗi hay gặp: thiếu cờ `-i` (giao tiếp JSON-RPC cần stdin) hoặc dùng `~` trong đường dẫn mount. Hãy dùng đường dẫn tuyệt đối thật.

**Lỗi PEP 668 khi cài bằng pip toàn cục.** Đây chính là lý do README khuyên `uv tool install` hoặc `pipx install`. Đừng ép cài với cờ phá bảo vệ, hãy chuyển sang hai cách đó hoặc dùng môi trường ảo.

**Đổi mô hình embedding rồi tìm ra kết quả lạ.** README nói đổi mô hình trên palace đã có thì phải embed lại, vì không gian vector khác nhau. Với embedding qua máy chủ kiểu `openai-compat`, README nêu cần chạy `mempalace repair rebuild-index`. Nên chọn mô hình ngay từ đầu để đỡ phải làm lại.

**Build GPU trên máy ARM (kể cả Apple Silicon) báo lỗi phân giải phụ thuộc.** Image GPU chỉ có cho x86_64. Người dùng ARM hãy dùng bản CPU.

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

**Điểm mạnh.** Dữ liệu ở trên máy bạn, chế độ cơ bản không cần API key. Lưu nguyên văn nên đáng tin hơn bản tóm tắt. Kết quả đo được công bố và README nói có thể tự chạy lại để kiểm chứng bằng lệnh trong thư mục `benchmarks`. README cũng khá thẳng thắn: họ không đưa bảng so sánh với các dự án khác vì mỗi bên đo một kiểu, và không quảng cáo con số "100%" vì phần cuối đạt được nhờ xem lại các câu sai.

**Giới hạn.** Đây là công cụ dòng lệnh, nên người hoàn toàn chưa quen terminal sẽ thấy hơi nặng ở bước đầu. Cần chọn mô hình embedding sớm, và mô hình đa ngôn ngữ nặng hơn bản tiếng Anh. Termux trên Android chưa hỗ trợ cài trực tiếp. Phần cấu hình MCP không dùng Docker nằm ở tài liệu riêng, bạn phải đọc thêm.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần ghi chú vài dòng, một file ghi chú hay công cụ ghi chú thường là đủ. Nếu bạn cần bộ nhớ dạng tóm tắt, tự trích xuất sự kiện, MemPalace không làm vậy vì nó cố ý không tóm tắt. Nếu bạn là người dùng văn phòng không dùng trợ lý AI dạng dòng lệnh, lợi ích sẽ ít hơn so với lập trình viên làm việc dài ngày với Claude Code, Codex hay Cursor.

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

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

Có. Repo dùng giấy phép MIT và mô tả của tác giả nói rõ là miễn phí. Chế độ tìm kiếm cơ bản không cần API key hay dịch vụ trả phí nào. Nếu bạn tự chọn dùng máy chủ embedding hoặc LLM bên ngoài thì chi phí phụ thuộc vào dịch vụ bạn chọn.

### Có cần GPU không?

Không bắt buộc. README nói trên Apple Silicon dùng CPU là bình thường cho các mô hình embedding mặc định. Có bản Docker GPU riêng (Dockerfile.gpu, chạy với --gpus all) nhưng nó chỉ dành cho x86_64 và không được xuất bản sẵn, bạn phải tự build.

### Chạy được trên Windows không?

README không có mục riêng cho Windows. Gói cài bằng Python 3.10+ qua uv hoặc pipx, còn Docker Desktop cũng được nhắc đến. Chưa có thông tin chi tiết về việc kiểm thử trên Windows trong phần README mình có, nên nếu vướng bạn hãy xem tài liệu trên trang chính thức.

### Dữ liệu của tôi có an toàn không?

README nói MemPalace là local-first và không có gì rời khỏi máy bạn trừ khi bạn tự bật. Nếu dùng máy chủ embedding trong máy hoặc mạng nội bộ thì nội dung cũng không ra ngoài mạng của bạn. Bạn vẫn nên tự giữ an toàn cho thư mục dữ liệu và chỉ tải từ các nguồn chính thức.

### Nó khác gì việc nhờ AI tóm tắt lại hội thoại?

MemPalace không tóm tắt, trích xuất hay diễn đạt lại. Nó lưu nguyên văn rồi tìm theo ý nghĩa, nên bạn nhận lại đúng chữ gốc. README không nói gì thêm về so sánh trực tiếp với từng công cụ bộ nhớ khác và cố ý không đưa bảng đối chiếu.

### Dùng tiếng Việt được không?

README nói mô hình embeddinggemma là đa ngôn ngữ (hơn 100 ngôn ngữ) và được khuyên dùng, còn minilm chỉ dành cho tiếng Anh. Chưa có số liệu riêng cho tiếng Việt trong tư liệu, nên bạn nên thử trên dữ liệu thật của mình.

### Dùng với Claude Code như thế nào?

Có hai hướng: cài các skill bằng npx skills add rồi nhờ trợ lý cài giúp, hoặc tự cài CLI và nối máy chủ MCP. Repo còn có hook tự lưu cho Claude Code, Codex CLI và Cursor IDE. README cảnh báo phiên Claude Code hết hạn sau 30 ngày nếu chưa gắn hook.
