# Dữ liệu: workspace, trí nhớ, tệp, data pool và kiến thức

Bảng, memory, tệp, data pool và knowledge nằm ở đâu, ai thấy, ai xóa, và dữ liệu nào đặt ở kho nào.

Một Soot làm việc với bốn loại thông tin bền: bảng có cấu trúc, điều đã học (memory), tệp, và tài liệu dùng chung của công ty. Tài liệu này giải thích mỗi loại nằm ở đâu, ai thấy, ai xóa được, và vì sao tách như vậy. Nếu mọi thứ đổ vào một chỗ (prompt, hoặc một "bộ nhớ" chung), không ai biết dữ liệu nào của ai, không thu hồi được quyền, và một câu trả lời sai lặp lại ở mọi Soot cho tới khi có người sửa từng nơi.

## Mô hình tổng quát

Hai tầng lưu trữ, cộng một lớp tra cứu đặt lên trên.

```text
              Level (ai chạm tới không cần grant)
         ┌───────────────────────────────────────────────┐
workspace│ bảng · memory · tệp · task    Lead + người vận hành ghi; Soot nội bộ đọc
team:<id>│ bảng · memory · tệp · task    thành viên team và Lead, đầy đủ
soot:<id>│ bảng · memory · tệp · task    chính Soot đó và Lead, đầy đủ
pack:<id>│ bảng riêng của một Pack       chỉ Pack đó, qua token một lần
         └───────────────────────────────────────────────┘
tùy chọn:  data pool (PostgreSQL, Pack data-pool) ── tài liệu công ty dùng chung nhiều máy
              └─ pool "projects" ◀── runtime đồng bộ từ /llms.txt ◀── Knowledge
```

- Workspace có sẵn trong runtime, không cần cài gì. Chỉ run của tenant người vận hành có công cụ workspace; run công khai, live chat, widget và SDK không có.
- Data pool là Pack tùy chọn, dịch vụ riêng, dùng khi nhiều Soot trên nhiều máy phải đọc cùng một bản.
- Level là phạm vi dữ liệu. Một run trong team làm việc ở level của team. Chat của Lead làm việc ở `workspace` và level Soot của nó; Lead không thuộc team nào, nó vào level team thay mặt người dùng.

## Quyền truy cập

Mọi thứ vượt mặc định ở bảng trên là một grant trong `deployment.json`, mục `access`: `{subject, scope, kinds, level}`. `subject` là `soot:<id>` hoặc `team:<id>`, `kinds` gồm `data`, `memory`, `files`, `level` là `read` hoặc `write`. Grant đổi qua action `access.grant` và `access.revoke`, có revision và biên nhận như mọi action. Quyền của Pack với credential hay biến môi trường của host là chuyện khác (`grants.packs`, `soot grant`).

Một grant thường ra đời như sau. Soot bị công cụ từ chối, gọi `report_blocker` xin quyền; Nest hiện nút **Cấp quyền**; hoặc Lead tự cấp qua `nest-lead_manage`. Chính sách của Lead: grant đọc cho Soot nội bộ hoặc team là việc của Lead; grant ghi, hoặc bất kỳ grant nào cho Soot có khách của website nói chuyện, chờ người dùng trong **Cần bạn**.

Phát hiện phạm vi: `GET /v1/workspace` cho biết host có những level nào, mỗi level chứa gì và các `access` hiện hành; công cụ `data` (op `tables`) và `storage` (op `levels`) cho Soot tự xem mình thấy gì.

## Scratch và spill trên đĩa

Hai thứ nằm ngoài DB nhưng do runtime giữ và xóa cùng hội thoại (chi tiết trong [runtime.md](https://trysoot.com/vi/docs/runtime/index.md#mo-hinh-bao-mat)):

- `<data_dir>/workspaces/<soot>/<hội thoại>/` là scratch của bash và tool file. Quota mặc định 2 GiB (`execution.scratch_quota_mb`), `.soot/` chỉ runtime ghi, và scratch của hội thoại không hoạt động quá `execution.scratch_ttl_days` (30 ngày) bị host dọn mỗi giờ.
- `<data_dir>/code/<id>/` là của một code project ([runtime.md](https://trysoot.com/vi/docs/runtime/index.md#du-an-ma-nguon-worktree-git-cho-moi-hoi-thoai)): `repo/` (bản clone bare khi `repo` là URL), `worktrees/<hội thoại>/` là workspace git thay scratch, `homes/<hội thoại>/` là HOME của sandbox (cache npm, pip nằm đây, ngoài repo), `owners/` và `requests/` (yêu cầu push, pr chờ người duyệt). Không có quota và không bị dọn theo TTL; xóa hội thoại chưa xóa worktree.
- `<data_dir>/spill/<scope>/<khóa>` giữ kết quả tool lớn hơn 1 MiB (tới 64 MiB) để `read_spill` đọc lại đủ; xóa hội thoại xóa cả thư mục này.

## Bảng, tệp, task

Bảng có kiểu, nằm trong một kho SQL của host: SQLite nhúng ở `<data_dir>/workspace.db` mặc định, hoặc PostgreSQL cho cả host qua `data_store`. Model không viết SQL: công cụ `data` có các op có tên (`create_table`, `insert`, `query`, `search`, `update`...) và runtime biên dịch thành SQL tham số hóa. `search` là tìm mờ, bỏ dấu tiếng Việt, qua chỉ mục trigram. Kho "project pool" kết nối tới database sản phẩm đã bị bỏ; `soot migrate pools-to-workspace` chép bảng của nó vào workspace.

Bảng giữ dòng của khách thì đánh dấu một cột text `principal: true` (cờ có trong schema của công cụ `data`, sống qua `alter_table`). Xóa một principal xóa cả các dòng đó, dùng cùng eraser với bảng của Pack. Khi chat có principal đã xác minh, `insert` tự điền `"<tenant>:<sub>"` vào cột này; công cụ `data` chỉ có ở tenant người vận hành, nên thực tế đó là chat kênh đã ghép cặp. Không drop được cột principal khi bảng còn dòng, vì dòng mất cột thì không ai tìm ra để xóa. Bảng có cột text đang chứa email hay số điện thoại (runtime đọc vài dòng mẫu, không dựa vào tên cột, nên tên cột ở ngôn ngữ nào cũng như nhau) mà chưa có cột principal thành một mục `table_principal` ở **Cần bạn**: thêm cột khách, hoặc trả lời "không chứa dữ liệu khách" (`POST /v1/workspace/tables/{name}/principal?scope=`).

Tệp là một thư mục cho mỗi level dưới `<data_dir>/storage/`, mở bằng `os.Root` nên không đường dẫn nào thoát ra ngoài. Người dùng thêm tệp bất kỳ từ Nest, kể cả từ ô soạn tin: tài liệu kéo vào chat được lưu ở `Tệp từ chat/` của level đang chat, và tin nhắn mang đường dẫn trong trường có cấu trúc `files` (`POST /v1/conversations/{id}/messages`, `[{"scope","path"}]`, tối đa 8), không trong lời người gõ. Nest bản cũ còn ghi dòng "Tệp đính kèm…" vào tin nhắn; runtime chỉ đọc dòng đó khi tin không có `files`, là alias tương thích sẽ bỏ khi Nest gửi trường mới. Trước khi run bắt đầu, runtime chép các tệp đó vào `attachments/` của scratch (xem đoạn "Storage và scratch" bên dưới); tin nhắn của người khác ngoài workspace của chủ thì không chép gì. Mỗi level có chỉ mục trigram trong bảng `soot_files` trên tên, đường dẫn và tối đa 64 KiB text đã trích; mọi lần ghi, chuyển, xóa đều cập nhật nó, level cũ được lập chỉ mục lần đầu khi có người tìm. Op `search` của `storage` và `GET /v1/workspace/files/search?scope=&q=` tìm mờ, bỏ dấu, theo tên lẫn nội dung. Artifact là chuyện khác: Pack `artifacts` giữ kho content-addressed (tham chiếu `art_<hash>`) cho đầu ra của Pack cần băm, bất biến và gửi đi nơi khác; model không chạm tới đường dẫn thật.

**Storage và scratch.** Model không sửa tệp ở kho chung. Công cụ `storage` (thay `files`; không còn alias) là cầu nối giữa kho và scratch của hội thoại, nơi `read`, `write` và `bash` làm việc. Có đúng một điểm kiểm grant, quota, xung đột và audit: `push`. Người vẫn đọc ghi kho trực tiếp từ Nest.

| Op | Việc |
|---|---|
| `levels`, `list`, `search` | Như trước: level Soot với tới, một thư mục, tìm mờ theo tên và nội dung. Cần grant `files:read`. |
| `pull {scope, path, to?, force?}` | Chép một tệp, hoặc một thư mục (tối đa 500 tệp, 100 MiB), vào scratch, mặc định `storage/<level>/<path>` (`storage/team/sales/…`). Ghi hash gốc vào `.soot/pulled.json` (chỉ host ghi). Theo quota scratch. Không đè bản đã sửa ở scratch: `local_changes`, trừ khi `force`. Pull một tệp văn bản tới 64 KiB trả luôn nội dung như `read` (dòng đánh số, `content_hash`) và báo cho tool file rằng model đã thấy cả tệp, nên `edit`/`write` sửa ngay không cần `read`. |
| `push {from, scope?, path?, base?}` | Host đọc `from` qua `os.Root` (symlink ra ngoài bị từ chối: `path_outside_scratch`), kiểm `files:write` (`scope_forbidden`), luật `ui/` và `tools/` (`folder_reserved`), giới hạn 25 MiB/tệp, 2 GiB và 20000 tệp/level (`object_too_large`, `storage_limit`), rồi ghi atomic, cập nhật chỉ mục tìm kiếm và báo ghi chú của watcher (màn hình đã lưu, đề xuất hay công bố). Bỏ `scope`/`path` thì đẩy về chỗ đã `pull`. |
| `status {path?}` | Mỗi tệp đã pull ở một trong: `unchanged`, `modified_locally`, `changed_in_storage`, `both`, `missing_locally`, `missing_in_storage`, `no_access`. Hash hai phía được nhớ theo kích thước và giờ sửa, nên chỉ tệp đã đổi mới bị băm lại. |

`push` an toàn khi gọi lại: nội dung giống hệt bản đang có thì không ghi gì và không tạo phiên bản (`unchanged: true`). `base` là hash mà tệp trong kho phải còn là: truyền hash (hash của `pull`/`push`/`status`, hoặc `content_hash` mà `read` cho bản sao: 16 ký tự hex đầu của cùng SHA-256), hoặc `"new"` (tệp chưa được tồn tại), hoặc bỏ trống để dùng hash lúc `pull`. Tệp đã đổi thì trả `stale_revision` (ngữ nghĩa 409) kèm `base_hash` và `current_hash`, không ghi gì; Soot `pull` lại vào đường dẫn khác, gộp, rồi `push` với hash mới. Không có `base` và chưa pull thì `push` chỉ tạo tệp mới: tệp đã có trong kho mà Soot chưa pull thì bị từ chối `not_pulled` (kèm `current_hash`), như `write` từ chối tệp chưa đọc; muốn thay hẳn thì truyền `base` bằng hash đó. Nội dung giống hệt vẫn là `unchanged`. Một run chỉ đọc (eval, dry run, bản tóm tắt buổi sáng của Lead) nhận bản xem trước `{dry_run: true, would: {…}}` và không ghi gì; `pull` vẫn chạy vì chỉ chép ra scratch.

Mỗi lần `push` đè lên nội dung khác, bản cũ được giữ (tối đa 5 bản mỗi tệp, bản cũ nhất bị bỏ trước) trong `.versions/<hash đường dẫn>/` ở gốc level: tên ẩn nên không liệt kê, không lập chỉ mục, model không với tới, nhưng tính vào quota level. Bản cũ còn lại sau khi tệp bị xóa hoặc chuyển; DropScope xóa cùng level. Chưa có op khôi phục: người vận hành lấy lại từ thư mục đó.

Lỗi theo dạng `{code, message, recovery}` (cộng các trường riêng như `base_hash`). Chỉ `push` cần `files:write`; `delete`, `move` và `mkdir` không còn trong công cụ, nên Soot không xóa hay sửa hàng loạt được kho chung (người làm việc đó ở Nest, và Soot muốn bỏ tệp thì nhờ người). Soot chỉ được cấp `storage` khi chọn `read` (`soot check` từ chối grant `files` thẳng cho một Soot không có `read`, mã `storage_needs_read`; runtime không đưa `storage` cho Soot đó).

Task nằm cùng kho SQL: người nhận (Soot, team, người), trạng thái và nhật ký chỉ ghi thêm. Giao task không bắt đầu nó. **Start** gửi đúng một run vào hội thoại riêng của task qua cùng cửa admission với schedule, không hàng đợi, không retry; chỉ Soot hoặc người dùng đổi trạng thái. Lần đầu một run của task hoàn thành, runtime lưu câu trả lời cuối vào `Task results/<tên việc>/<YYYY-MM-DD HH.mm>.md` trong Tệp của level task (team, rồi Soot, rồi workspace) và ghi event `result_saved{run,scope,path}` vào nhật ký; Nest hiện link mở tệp đó. Task gắn goal và task lặp được nói trong [workspace.md](https://trysoot.com/vi/docs/workspace/index.md).

## Phiên theo nguồn

Mỗi hội thoại ghi `source` `{kind, ref, label}`; `kind` là `nest`, `schedule`, `widget`, `sdk`, `channel`, `task` hoặc `event`. Người vận hành xem được mọi phiên qua `GET /v1/sessions?source=` (chỉ đọc: phiên của widget hay SDK được xem trong Nest, không trả lời ở đó). Source cũng quyết định thông báo: việc người dùng tự bắt đầu thì báo khi xong; schedule, website, SDK và kênh chat chỉ báo khi cần người dùng.

Cạnh một phiên, `GET /v1/sessions/{id}/memory` trả điều Soot giữ: `{conversation: {entries, total}, principal: null | {entries, total}}`. Đây là dữ liệu khách nên chỉ người đọc được (`PersonOnly`, khóa có phạm vi nhận 403); store memory lỗi thì 503 `memory_unavailable`, Nest ghi "Chưa đọc được", không bao giờ coi là trống. `principal` là `null` khi khách chưa xác minh.

## Memory

Memory là điều Soot đã học và chưng cất lại, tách khỏi lịch sử hội thoại. Công cụ (`learn`, `memory_recall`, `memory_edit`) và worker gom (consolidation) đến từ AgentCore trong `2ai` ([runtime.md](https://trysoot.com/vi/docs/runtime/index.md)); Soot cung cấp store Go/Bolt có phạm vi (`internal/core/agentstate`) và quy tắc danh tính của host. Không cần dịch vụ embedding hay bộ quét định kỳ.

Nguyên tắc sở hữu: host suy ra mọi target từ danh tính đã xác thực; model chọn một alias, không bao giờ tự đặt tenant, user hay scope. Quyền đọc không kéo theo quyền sửa, xóa hay công bố.

| Target | Ai thấy | Ai ghi |
| --- | --- | --- |
| `conversation` | Hội thoại hiện tại | Run hiện tại |
| `user` | Một người đã xác thực, dùng chung mọi hội thoại và Soot | Run đã xác thực, không phải ghi chú nội bộ |
| `soot` | Điều Soot đó học, qua mọi người dùng | Chính Soot |
| `team` | Thành viên team (kèm `team.brief` từ template) | Thành viên team |
| `workspace` | Nội bộ cả tenant; không vào live chat hay web công khai | Người vận hành, hoặc grant `memory` ghi |
| `workspace_public` | Cả khách (live chat, web công khai) | Chỉ khi có quyền công bố tường minh; khách không công bố được |

Ba hệ quả:

- Transport công khai chỉ có memory của hội thoại và không đọc hồ sơ người dùng. Ngữ cảnh nhiều nhóm chỉ có `current` để không xuất evidence trộn lẫn.
- Fact công khai phải được ghi có chủ đích; model không tự đổi memory nội bộ thành công khai.
- Bank dùng chung chỉ tenant người vận hành ghi thẳng. Tenant khác (SDK, member key) có nhiều người sau lưng, nên điều họ lưu là đề xuất: chỉ tác giả thấy cho tới khi người vận hành duyệt ở **Dữ liệu, Trí nhớ, Chờ duyệt**. Chỉ người mới duyệt được (`PersonOnly`), Lead và Soot không tự duyệt.

Mỗi mục có kind: `fact`, `preference`, `procedure`, `learning` sống tới khi bị sửa hay xóa; `context` 24 giờ; `episode`, `outcome` 90 ngày. Một `key` ổn định (`staging.endpoint`) cho phép phát hiện xung đột chắc chắn; mâu thuẫn ngữ nghĩa không có khóa vẫn phụ thuộc model. Nguồn do host gán từ hội thoại và run: nó chứng minh bằng chứng đến từ đâu, không chứng minh sự thật.

Consolidation: run gốc thành công đưa vào hàng đợi evidence đã che credential; một worker gom ra tối đa bốn thay đổi ngắn cho bank ghi được của chính nó, trong một giao dịch kiểm tra snapshot. Run lỗi, run con, web công khai không tạo consolidation, và bank chia sẻ chỉ đọc không bị gom tự động. Không có đường nào tự nâng memory của hội thoại lên bank dùng chung. Hàng đợi bền trên đĩa, khởi động lại không chạy lại việc chính. Run eval không tạo consolidation; memory eval cũ dọn bằng `soot conversations prune-memory --origin eval [--before] [--dry-run]` (`POST /v1/conversations/prune-memory`), gọi lại an toàn.

Với chat khách (live chat hay phiên có ghi chú nội bộ, không phải eval), host định tuyến từng mục khi commit, model không chọn được đường này:

- `preference` và `fact` của khách đã xác minh vào bank `user` của principal đó, nên lần sau khách được nhớ; khách ẩn danh thì vẫn ở bank hội thoại.
- `procedure` thành đề xuất trong làn **bài học khách** của Soot (`VisitorLessons`, giữ cùng bank của người vận hành), tác giả `consolidation`. Email, số điện thoại, URL có token bị che trước khi ghi. Bài học trùng (cùng `key`, cùng fingerprint, hoặc giống từ ≥0.6) gộp lại và đếm số hội thoại đã gặp. Gặp ở ≥2 hội thoại trong 14 ngày thì `needs_attention` và thành mục `memory_lesson` ở **Cần bạn**. Khách không thấy đề xuất đang chờ; sau khi người vận hành duyệt, mọi chat khách của Soot đó đọc được (chỉ đọc).

`GET /v1/workspace/memory-proposals` trả thêm `seen_conversations`, `needs_attention`, `bank_tenant` (duyệt và từ chối gửi `tenant` bằng giá trị này) và lọc được `?recurring=true`.

Mỗi mục đếm `recalled_count` và `last_recalled`: chỉ khi mục đó thực sự được đưa vào context của một run, không tính lượt `memory_recall` tìm kiếm; ghi một lần mỗi run. `GET /v1/workspace/health?scope=` gom một level: số mục, mục dùng trong 30 ngày, mục chưa từng dùng, mục 90 ngày chưa dùng, đề xuất chờ và đề xuất lặp lại, số tệp và dung lượng, số bảng và bảng thiếu cột khách. Phần nào không đọc được thì là `null` và có tên trong `unavailable`, không bao giờ là 0. Nest hiện nó ở tab **Sức khỏe**.

### Ai xóa được

| Muốn xóa | Cách |
| --- | --- |
| Một mục | `memory_edit erase` (khi người dùng yêu cầu) hoặc Nest, tab Trí nhớ |
| Một người | `DELETE /v1/principals/{tenant}/{sub}` |
| Theo thời gian | `retention.days` của tenant |

Erase một mục xóa dòng, chỉ mục, các revision và bằng chứng chờ trong scope (để consolidation đang chạy không khôi phục lại), rồi đánh dấu chặn tự học lại. Nó không xóa bản ghi hội thoại, bản sao lưu hay cách diễn đạt khác; một `learn` tường minh sau đó vẫn giữ lại được.

Principal là người dùng cuối có `(tenant, sub)` ổn định, từ một người gửi kênh được khẳng định hoặc ghép cặp (principal-token). Bank `user` của họ là một bank cho mỗi `(tenant, sub)` dùng chung mọi hội thoại, binding và Soot của tenant; khách ẩn danh chỉ có bank của hội thoại. Xóa một principal chạy mọi eraser đã đăng ký (`principal.RegisterEraser`): hội thoại (tin nhắn, run, memory của hội thoại, thư mục làm việc của công cụ), mẫu câu hỏi trong knowledge gap, bank `user`, trace, bảng Pack có cột `principal`, biên nhận trang. Run đang chạy bị dừng trước; hiệu ứng chưa rõ kết quả phải được xử lý trong Nest rồi mới xóa tiếp. Danh sách cần xóa được lưu trước nên gọi lại sau lỗi giữa chừng vẫn đủ. Retention chạy cùng đường đó mỗi ngày cho principal im lặng quá `retention.days`; khách ẩn danh không có principal nên không bị quét.

## Data pool

Khi nhiều Soot trên nhiều máy cần cùng một kho tài liệu (cẩm nang, chính sách hỗ trợ, tài liệu thương hiệu), dữ liệu đó nằm trong data pool: Pack `data-pool` của Soot Forge (`../soot-forge/packs/data-pool`), chạy trên PostgreSQL 16+ với `pg_trgm`, hoàn toàn tùy chọn.

```text
Soot (laptop)   Soot (VM)   Nest "Dữ liệu"
     └─ binding ─┴────────────┘  (Nest dùng credential DATA_POOL_UI riêng)
                ▼
       dịch vụ data-pool ──▶ PostgreSQL
       sở hữu pool, grant, tài liệu, biên nhận, activity
```

Hai điều hay bị nhầm. Cài Pack không cấp quyền, không tạo PostgreSQL, không nhập dữ liệu: người vận hành tự chạy PostgreSQL và dịch vụ, rồi gắn binding. Chọn Pack chỉ lộ công cụ; quyền vào từng pool vẫn là grant của dịch vụ, kiểm tra trước mỗi thao tác.

Dữ liệu có thẩm quyền nằm ở dịch vụ, nên Nest, CLI và agent thấy cùng trạng thái. Tài liệu có ID ổn định, nguồn, tag, hash, revision; pool có thể lồng nhau và quyền độc lập với cây. Tìm kiếm mờ, bỏ dấu, dựa trên chỉ mục GIN.

Chế độ đọc và ghi theo cách chọn Pack: `data-pool:read` cho công cụ đọc (marketing, hỗ trợ), `data-pool` cho đọc, ghi và quản lý (người quản lý dữ liệu), và `data-pool-console` cho giao diện vận hành của Nest. Có hai cách gắn binding. Gắn chung: deployment khai một khối `data_pool`, mọi Soot trừ `except` nhận công cụ và dịch vụ suy ra thao tác từ vai trò của Soot. Gắn riêng: credential `DATA_POOL` cho từng Soot, và khai riêng thì thắng. Mọi process đọc được file binding đều hành động được như mọi Soot trong allowlist của máy đó, nên không bao giờ đưa Soot công khai hay không tin cậy vào; Soot dùng `public_web` phải nằm trong `except`. Chi tiết cấu hình: `soot schema deployment` và README của Pack.

Dịch vụ mới biết danh tính nào được nhận, nên runtime gọi thử `data-pool_pools {limit:1}` bằng danh tính của từng Soot gắn chung: lúc khởi động, khi apply, rồi 15 phút một lần. Soot bị từ chối (`soot.unadmitted`) không nhận công cụ `data-pool_*` và có mục `pool_unadmitted` ở **Cần bạn**; dịch vụ không gọi tới được thì giữ nguyên hiện trạng.

Khu **Dữ liệu** của Nest (`desktop/src/modules/data/`) có cây level và các tab Bảng, Trí nhớ, Tệp, Quyền, Sức khỏe cho mỗi level; trang của data pool là trang riêng của Pack mở trong khung. Người dùng tạo và xóa pool, duyệt và tìm tài liệu, thêm văn bản hoặc nhập URL công khai, sửa với kiểm tra revision (xung đột giữ bản nháp), xem quyền hiệu lực và activity có giới hạn. Một lần ghi trả biên nhận cuối cùng, gửi lại cùng request ID thì được phát lại, không ghi hai lần. Nguồn từng được đọc chưa chứng minh câu trả lời sau đó đã dùng nó.

## Knowledge

Một Soot trả lời về sản phẩm cần dữ kiện của sản phẩm: tính năng, gói, giá, giới hạn. Chép chúng vào skill hay mission thì đúng một tuần; giá đổi ở sản phẩm, bản chép không đổi, mọi Soot giữ bản chép trả lời sai. Nguyên tắc: dữ kiện sản phẩm chảy từ sản phẩm, không phải từ prompt.

```text
trang sản phẩm           source                     workspace            Soot
/llms.txt + trang  ──▶  knowledge.sources  ─sync─▶  pool "projects"  ─▶  knowledge_search
(team sản phẩm giữ)     (site nào, pool nào,        (chunk kèm nguồn     knowledge_read
                         bao lâu một lần)            + thời gian)         (trích nguồn)
```

Skill giữ hành vi (cách chốt lead, khi nào chuyển cho người); dữ kiện thì tra cứu. Bản sao nằm trong kho workspace của chính runtime (bảng `soot_knowledge`, chỉ mục trigram), nên knowledge không cần data pool: mỗi runtime tự mirror từ trang công khai. "Pool" ở đây chỉ là tên một tập kiến thức.

### Thiết lập

Phần này dành cho coding agent làm giúp người dùng; Nest ở **Cài đặt, Kiến thức công khai** có nút **Sao chép lời nhắn cho trợ lý** trỏ tới đây.

1. Sản phẩm công bố `/llms.txt` theo định dạng [llms.txt](https://llmstxt.org/): tiêu đề, tóm tắt một dòng, liên kết tới các trang Markdown, mỗi chủ đề một trang. Giá lấy từ catalog của chính sản phẩm khi build hoặc khi phục vụ; trang gõ cứng giá là đã đưa bản chép trở lại.
2. Source khai `knowledge` trong `source.json`:

```json
"knowledge": {
  "pool": "projects", "refresh": "6h",
  "sources": [{"id": "2novel", "url": "https://2novel.app/llms.txt"}]
}
```

3. Host liệt kê pool được phép chứa kiến thức trong `deployment.json`: `"knowledge_pools": ["projects"]` (Nest có công tắc; action tên `knowledge.pool`). Source khai pool chưa được liệt kê thì không sao chép gì và báo trong trạng thái, không làm hỏng deploy: deploy một repo không tự chép đè tập kiến thức của source khác.
4. Soot hỗ trợ thêm `"knowledge:pools=projects"` (hoặc `"knowledge"` cho mọi pool) vào `packs` trong `soot.json`.

Lên bản này, lần sweep đầu tải lại mọi source vào workspace. Bản sao cũ trong data pool không còn được đọc; người vận hành tự xóa nó. Ghi chú phản hồi của khách (`feedback.pool`) vẫn ghi vào Pack `data-pool` và không được trùng pool kiến thức.

### Runtime giữ bản sao

Vài phút một lần runtime đồng bộ các source đến hạn: tải URL (chỉ `https`, địa chỉ công khai), đi theo chỉ mục một cấp, cắt trang tại tiêu đề `##` thành chunk tự đứng được, ghi mỗi chunk thành tài liệu có `source` là URL trang. Tải lỗi thì giữ bản sao cũ: dữ kiện cũ có ngày còn hơn không có. Trạng thái xem qua `GET /v1/settings/knowledge`. Nest chỉ đưa vào **Cần bạn** thứ retry không sửa được (lỗi liên tiếp, chưa từng đồng bộ, pool chưa được liệt kê, kho từ chối ghi).

### Soot tra cứu

Soot khai `knowledge` nhận ba công cụ ghim vào các pool đó: `knowledge_search` (tối đa 8 kết quả mỗi cách viết, kèm nguồn và ngày; `queries` thêm tối đa 4 cách viết khác trong cùng một lần gọi, gộp bỏ trùng, và `read_top` trả luôn toàn văn kết quả đầu), `knowledge_read` (chunk đầy đủ) và `knowledge_gap` (ghi rằng thiếu dữ kiện). Công cụ mang luật cho mọi Soot nên mission không lặp lại: dữ kiện sản phẩm đến từ `knowledge_search`, câu trả lời trích trang, các câu trả lời trước hay trí nhớ của model không phải nguồn, dữ kiện pool không có thì nói là chưa biết.

Tìm kiếm mờ và bỏ dấu, nên khách gõ sai chính tả vẫn ra trang đúng.

Soot công khai dùng được knowledge. Hai công cụ tra cứu chỉ đọc pool host đã liệt kê, vốn chỉ chứa thứ sản phẩm đã công bố, nên khách dụ Soot tìm kiếm cũng chỉ đọc trang công khai. Hồ sơ an toàn công khai vẫn từ chối data pool gắn kèm và mọi công cụ khác. Vì vậy không đưa dữ liệu riêng tư vào pool kiến thức.

### Knowledge gaps

Khách hỏi một điều các trang không nói, Soot đáp thành thật là chưa xác nhận được. Nếu dừng ở đó, khách sau gặp cùng lỗ hổng và không ai biết nó tồn tại. Nên runtime tự ghi nhận, không để từng mission làm.

Khi `knowledge_search` không xác nhận được dữ kiện, Soot gọi `knowledge_gap` với dữ kiện thiếu (tên sản phẩm trước) và câu hỏi của khách. Câu hỏi khó chạm giới hạn lượt, khi đó câu trả lời cuối không có công cụ, nên Soot kết bằng một dòng `KNOWLEDGE_GAP: <dữ kiện>` mà runtime gỡ khỏi câu trả lời và ghi như thể công cụ đã được gọi. Các gap có từ khóa gần giống thì gộp lại (nghiêng về gộp, vì tách nhầm mới làm mất khuôn mẫu). Câu hỏi lưu được cắt ngắn và che email, số điện thoại; hội thoại chỉ giữ dạng hash để phân biệt hai khách với một khách hỏi hai lần; mỗi chat và mỗi giờ có trần để khách không làm ngập danh sách.

Một khách hỏi là chuyện lẻ, chỉ được liệt kê. Khi gap còn mở và được hỏi trong ít nhất 2 hội thoại khác nhau trong 14 ngày, nó thành `needs_attention` và hiện ở **Cần bạn**. Ngưỡng này chỉ đếm người hỏi thật: run theo lịch không tính, còn câu hỏi từ bàn phản hồi được tính cho hội thoại gốc. Sau khi bổ sung trang, người dùng bấm **Đã bổ sung**, runtime đồng bộ ngay các source của pool đó. Gap bị hỏi lại thì tự mở lại và quay về Cần bạn: cách sửa không hiệu quả, hoặc trang chưa được đồng bộ. Tìm kiếm theo từ, nên **Soot tìm thấy gì?** trong Nest chạy đúng `knowledge_search` để kiểm tra trang mới có được tìm thấy bằng chính từ của khách không.

## Lưu trữ của Pack

Pack khai bảng riêng trong `pack.json` mục `storage`; runtime cấp bảng, giới hạn mọi truy cập vào Pack đó bằng token một lần gắn với `(pack, soot, workspace)`, và chỉ cho di chuyển cộng thêm. Khi Soot cuối bỏ chọn Pack, dữ liệu ẩn 30 ngày rồi bị xóa. Người vận hành đọc bảng của Pack chỉ đọc trong Nest (Dữ liệu, Bảng, "Gói: <tên>"). Cột `principal: true` đưa dòng vào xóa theo principal. Hợp đồng: contracts/pack-storage.md.

Khác data pool: bảng của Pack chỉ Pack đó đọc, sống và chết cùng Pack. Data pool là dịch vụ dùng chung của công ty, nhiều Soot trên nhiều máy đọc theo grant.

## Nên đặt dữ liệu ở đâu?

| Dữ liệu | Đặt ở | Vì sao |
| --- | --- | --- |
| Điều nên nhớ về một người (sở thích, ngữ cảnh) | Memory `user` hoặc `conversation` | Gán theo danh tính; xóa được theo principal |
| Cách tiếp khách Soot học được từ nhiều cuộc chat | Bài học khách (đề xuất, người vận hành duyệt) | Che liên hệ, gộp trùng, duyệt rồi mới dùng |
| Bài học, quy trình của một Soot qua nhiều lần làm | Memory `soot` | Bank riêng, qua consolidation |
| Điều cả team cần nhớ | Memory `team` | Thành viên cùng đọc |
| Fact nội bộ cả công ty / fact được nói với khách | Memory `workspace` / `workspace_public` | Công bố là hành động có chủ đích |
| Khách, cách liên hệ có đồng ý, cơ hội theo sản phẩm, việc theo khách | Pack `crm` của Soot Forge, chọn ở một runtime nhà; runtime khác đọc `pipeline` và ghi `crm_inbox` qua hợp đồng đội | Khớp danh tính chính xác, đồng ý do tool kiểm, mọi bảng có cột `principal` nên xóa theo người được |
| Dòng có cấu trúc khác: đơn, việc theo dõi | Bảng `data` ở level phù hợp | Có kiểu, truy vấn, tìm mờ; dòng của khách thì có cột `principal` |
| Tài liệu, bản nháp văn bản người và Soot cùng đọc; kết quả việc | Tệp ở level phù hợp | Theo level, tìm theo tên và nội dung, không cần dịch vụ |
| Đầu ra Pack cần băm và gửi đi nơi khác | Artifact | Content-addressed |
| Cẩm nang, chính sách dùng chung nhiều Soot, nhiều máy | Data pool | Một nguồn, grant theo pool, có revision |
| Giá, gói, tính năng, giới hạn của sản phẩm | Trang của sản phẩm, qua Knowledge | Không chép; đổi một nơi; không cần data pool |
| Cách chốt lead, khi nào chuyển người | Skill | Hành vi ở skill, dữ kiện thì tra cứu |
| Việc cần làm, có người nhận | Task | Có nhật ký và nút Start |
| Bảng riêng của một Pack | Lưu trữ của Pack | Chỉ Pack đó thấy |
| Secret, token, mật khẩu | Vault credential ([runtime.md](https://trysoot.com/vi/docs/runtime/index.md)) | Không nằm ở đâu trong tài liệu này |

Quy tắc ngón tay cái: thông tin sẽ lỗi thời khi sản phẩm đổi thì đừng ghi vào memory hay skill. Thông tin mô tả một người cụ thể là memory `user` và phải xóa được. Cần nhiều Soot trên nhiều máy đọc cùng một bản thì dùng data pool.

## Ranh giới

| Bên | Sở hữu |
| --- | --- |
| Core (runtime Soot) | Workspace, level và grant, store memory có phạm vi, mirror Knowledge, ghi gap, xóa theo principal và retention |
| AgentCore (`2ai`) | Công cụ memory và worker consolidation |
| Pack `data-pool` | Dịch vụ tài liệu dùng chung, grant theo pool, PostgreSQL |
| Pack `artifacts` | Kho artifact content-addressed |
| Host (`deployment.json`) | `access`, `data_store`, `data_pool`, `knowledge_pools`, `retention`, quyền công bố memory (`conversation.memory_workspace_write`) |
| Nest | Hiển thị và điều khiển; không giữ quyền riêng |

Cố ý không làm: model viết SQL; tự nâng memory hội thoại lên bank chung; Soot công khai đọc data pool nói chung; deploy một repo tự cấp quyền vào dữ liệu của host; coi cài Pack là cấp quyền.

Chưa có: pipeline đồng bộ dữ liệu sản phẩm hay kho dữ liệu vào pool, hàng đợi duyệt và quy trình tóm tắt issue trên pool.
