LoreKit: Trao trí nhớ dài hạn cho AI agent — mã nguồn mở, chạy hoàn toàn trên máy bạn

Bạn đã bao giờ cảm thấy bực bội khi AI agent của mình "mất trí nhớ" sau mỗi phiên làm việc? Hôm qua nó vừa phát hiện ra rằng cần khởi động container Postgres trước khi chạy integration tests, nhưng hôm nay lại gặp lỗi ECONNREFUSED 5432 và mất 9 phút để sửa một file vốn không hề sai. LoreKit ra đời để giải quyết chính xác vấn đề này.

LoreKit là một hệ thống trí nhớ mã nguồn mở cho AI agent, cho phép agent tự động lưu lại "bài học" sau mỗi lần thất bại, dưới dạng các file Markdown đơn giản ngay trên ổ đĩa của bạn. Không cần tài khoản, không cần đăng ký, không cần network — chỉ một câu lệnh và một thư mục bạn toàn quyền sở hữu.

Cài đặt trong hai phút

Việc thiết lập LoreKit vô cùng đơn giản với một câu lệnh duy nhất:

npx @lorekit/cli install

Lệnh này sẽ tự động tạo các skill cần thiết, cấu hình MCP server và thiết lập các hook vào dự án của bạn (ở cấp độ project hoặc toàn cục trong ~/.claude/). Bạn chỉ cần trả lời ba câu hỏi: cài cho project hay toàn cục, token (có thể bỏ trống khi dùng local), và chọn loại hook muốn kích hoạt.

Sau đó, tạo một file .lorekit.json tại thư mục gốc của repo:

{
  "mode": "local"
}

Và trỏ MCP server về máy của bạn thay vì hosted endpoint:

// .mcp.json → mcpServers
"lorekit": { "command": "npx", "args": ["-y", "@lorekit/cli", "mcp"] }

Cơ chế hoạt động: Ghi nhớ từ thất bại

Điểm mấu chốt của LoreKit nằm ở cơ chế "học từ lỗi". Khi agent của bạn gặp thất bại, hook PostToolUseFailure sẽ kích hoạt và nhắc nhở:

LoreKit: lệnh Bash cuối cùng đã thất bại. Nếu lỗi này lặp lại hoặc không rõ nguyên nhân, hãy gọi memory.write để lưu lại giải pháp cho lần chạy tiếp theo.

Quan trọng là, LoreKit không tự động ghi nhớ mọi thứ — nó chỉ nhắc nhở, còn việc ghi là do chính model gọi memory.write. Kết quả là một file Markdown đơn giản:

---
scope: "repo::acme/checkout"
key: "tests-need-local-postgres"
created: "2026-08-15T17:00:18.477Z"
updated: "2026-08-15T17:00:18.477Z"
seen_count: 1
---

Integration tests cần khởi động Postgres local trước: docker compose up -d db.
Nếu không, mọi test sẽ fail với lỗi ECONNREFUSED 5432.

File này hoàn toàn thuộc về bạn — bạn có thể cat, grep, commit hoặc xóa nó bất cứ lúc nào. Trong phiên làm việc tiếp theo, agent sẽ tự động tải bài học này và tránh lặp lại sai lầm.

Sơ đồ Memory Loop

Kiến trúc linh hoạt: Từ local đến shared

Một trong những điểm mạnh nhất của LoreKit là kiến trúc "một mã nguồn, hai nơi lưu trữ". Cùng một code path cho phép đọc từ thư mục cục bộ hoặc từ PostgreSQL trên cloud — việc mở rộng từ local sang remote chỉ là bổ sung, không phải di cư.

Quá trình chuyển từ Local sang Shared

Khi bạn muốn chia sẻ trí nhớ giữa các máy hoặc với đồng đội, chỉ cần:

1. Tạo tài khoản miễn phí tại lorekit.io
2. Tạo API key với quyền đọc-ghi (lk_rw_...)
3. Chạy lại npx @lorekit/cli install --force và dán key vào

Lệnh npx @lorekit/cli list sẽ hiển thị cả hai store (local và remote) cạnh nhau, đảm bảo không có dữ liệu nào bị mất khi chuyển đổi.

Ba trường hợp sử dụng thực tế

1. Những "cạm bẫy" lặp đi lặp lại

Bất kỳ yếu tố môi trường nào gây lỗi lặp lại — một service cần chạy trước, một flag bắt buộc, một package manager không giống với README — đều được ghi lại một lần và đọc lại trong mọi tác vụ sau đó. seen_count tăng dần khi bài học được tái sử dụng, giúp các bài học quan trọng được xếp hạng cao hơn.

2. Bài học trong phạm vi branch

Sử dụng scope branch::owner/repo::branch-name để ghi các phát hiện thử nghiệm — chúng chỉ xuất hiện trên branch đó và biến mất khi branch bị xóa:

memory.write {
  scope: "branch::acme/checkout::feat/new-cache",
  key:   "cache-invalidation-strategy",
  value: "Write-through cho session store; write-behind cho aggregates.",
  tags:  ["wip"]
}

3. Ghi chú có thời hạn

Một số sự thật chỉ đúng trong một tuần. Sử dụng ttl_days để ghi chú tự động "biến mất":

memory.write {
  scope:    "repo::acme/checkout",
  key:      "skip-flaky-checkout-test",
  value:    "checkout.spec bị flaky trên CI — bản fix sẽ ra vào thứ Sáu. Đừng mất thời gian.",
  ttl_days: 5
}

Lưu ý quan trọng: Bài học không phải quy tắc

LoreKit phân biệt rõ ràng giữa "bài học" (advisory observations) và "quy tắc" (rules). Bài học là những ghi chú agent để lại cho chính nó, có thể bỏ qua khi sai. Còn CLAUDE.md là nơi chứa các quy tắc đã được con người xem xét cẩn thận và đưa vào version control.

"Lore là lớp bên dưới: đống tích lũy những câu 'huh, lại gặp nữa rồi' chưa đủ điều kiện thành quy tắc."

Giới hạn trung thực

Cần phải nói rõ: LoreKit không có semantic search, không học máy hay fine-tuning. Việc khớp là lexical — dựa trên tần suất xuất hiện, độ mới và sự trùng lặp từ ngữ. Một câu diễn đạt khác đi có thể không khớp. Nhưng đây lại là một lời hứa nhỏ hơn, và chính vì thế, nó giữ được lời.

Bắt đầu ngay hôm nay

Bạn không cần tài khoản, không cần quyết định lớn hay một đội ngũ để thử nghiệm. Chỉ cần một câu lệnh và một repo nơi agent của bạn vẫn liên tục mắc lỗi — chắc chắn bạn đã có sẵn. 🙂

npx @lorekit/cli install

Đừng để agent của bạn "mất trí nhớ" mỗi ngày. Hãy cho nó một cuốn sổ tay mà chính nó có thể ghi chép — và chính bạn là người sở hữu cuốn sổ đó.