Soot DocsSoot được thiết kế thế nàoMarkdown ↗

05 / Dữ liệu

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.

Văn bản mẫu · không phải lệnh
              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):

  • <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): 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.

OpViệc
levels, list, searchNhư 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.

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); 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ố.

TargetAi thấyAi ghi
conversationHội thoại hiện tạiRun hiện tại
userMột người đã xác thực, dùng chung mọi hội thoại và SootRun đã 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ùngChính Soot
teamThành viên team (kèm team.brief từ template)Thành viên team
workspaceNội bộ cả tenant; không vào live chat hay web công khaiNgười vận hành, hoặc grant memory ghi
workspace_publicCả 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óaCách
Một mụcmemory_edit erase (khi người dùng yêu cầu) hoặc Nest, tab Trí nhớ
Một ngườiDELETE /v1/principals/{tenant}/{sub}
Theo thời gianretention.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.

Văn bản mẫu · không phải lệnh
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.

Văn bản mẫu · không phải lệnh
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: 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:
Mẫu JSON · không phải lệnh
"knowledge": {
  "pool": "projects", "refresh": "6h",
  "sources": [{"id": "2novel", "url": "https://2novel.app/llms.txt"}]
}

  1. 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.
  2. 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 conversationGá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 chatBà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àmMemory sootBank riêng, qua consolidation
Điều cả team cần nhớMemory teamThành viên cùng đọc
Fact nội bộ cả công ty / fact được nói với kháchMemory workspace / workspace_publicCô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áchPack crm của Soot Forge, chọn ở một runtime nhà; runtime khác đọc pipeline và ghi crm_inbox qua hợp đồng độiKhớ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õiBảng data ở level phù hợpCó 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ệcTệp ở level phù hợpTheo 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ácArtifactContent-addressed
Cẩm nang, chính sách dùng chung nhiều Soot, nhiều máyData poolMột nguồn, grant theo pool, có revision
Giá, gói, tính năng, giới hạn của sản phẩmTrang của sản phẩm, qua KnowledgeKhô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ườiSkillHành vi ở skill, dữ kiện thì tra cứu
Việc cần làm, có người nhậnTaskCó nhật ký và nút Start
Bảng riêng của một PackLưu trữ của PackChỉ Pack đó thấy
Secret, token, mật khẩuVault credential (runtime.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ênSở 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-poolDịch vụ tài liệu dùng chung, grant theo pool, PostgreSQL
Pack artifactsKho artifact content-addressed
Host (deployment.json)access, data_store, data_pool, knowledge_pools, retention, quyền công bố memory (conversation.memory_workspace_write)
NestHiể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.

Nội dung được xem lại: 12.11.2026