MemoryBộ nhớ
A chat session forgets everything when it closes. The harness keeps the few things that should outlive the session in plain files on disk — each kind in its own home, each one a single source of truth (one canonical file you edit through a tool, never two copies to drift apart). Nothing here is a database or a server; it is all git-tracked text you can read.Một phiên chat quên sạch khi đóng. Harness giữ vài thứ cần sống lâu hơn phiên trong các file thường trên đĩa — mỗi loại một nơi, mỗi cái là một nguồn sự thật duy nhất (một file chuẩn bạn sửa qua công cụ, không bao giờ hai bản lệch nhau). Ở đây không có database hay server; tất cả là text được git theo dõi và bạn đọc được.
Four durable homesBốn nơi lưu bền
Each home is written by a small register tool, not by hand — so every record carries an actor and a timestamp, and the human-readable view is regenerated from the data.Mỗi nơi do một công cụ register nhỏ ghi, không phải tay — nên mỗi bản ghi có actor và mốc thời gian, và bản đọc-được-cho-người được sinh lại từ dữ liệu.
DecisionsQuyết định
Every architectural decision (a "DEC") lands in docs/decisions.yaml — the source of truth — via decision_register.py. decisions.md is rendered from it. This is why a maintainer never has to rediscover why a thing was built a certain way.Mọi quyết định kiến trúc (một "DEC") vào docs/decisions.yaml — nguồn sự thật — qua decision_register.py. decisions.md được render từ nó. Nhờ vậy người bảo trì không phải khám phá lại vì sao một thứ được làm như thế.
GlossaryThuật ngữ
The canonical terms — and the wording the harness forbids — live in docs/glossary.yaml via glossary_register.py; GLOSSARY.md is the generated view. A nudge flags a new decision that coins an unlisted term.Thuật ngữ chuẩn — và cách nói mà harness cấm — nằm trong docs/glossary.yaml qua glossary_register.py; GLOSSARY.md là bản sinh. Một nudge cảnh báo quyết định mới đặt ra thuật ngữ chưa có trong danh sách.
BacklogViệc tồn
Deferred work (a "BL") goes to docs/backlog.yaml via backlog_register.py; BACKLOG.md is the rendered view. Review findings that are real but out of scope are parked here instead of lost.Việc hoãn (một "BL") vào docs/backlog.yaml qua backlog_register.py; BACKLOG.md là bản render. Phát hiện review có thật nhưng ngoài phạm vi được gửi vào đây thay vì mất.
LessonsBài học
harness/LESSONS.md records hard-won "we tried X, it broke, do Y" notes for the harness's own developers. It is reset to a clean template when a release is packed, so a shipped install starts fresh.harness/LESSONS.md ghi các bài học xương máu "thử X, hỏng, làm Y" cho chính người phát triển harness. Nó được reset về template sạch khi đóng gói release, nên bản cài đi vẫn mới.
How a fact gets in: hs:rememberMột sự thật vào kho thế nào: hs:remember
At the end of a work chunk, hs:remember looks at what actually happened and routes each keeper to the right home: a decision made → the DEC ledger; a non-obvious fact or constraint learned → an auto-memory note; correcting feedback worth keeping → memory; deferred work → the backlog. You approve each entry before it is written — nothing is saved silently.Cuối một mảng việc, hs:remember nhìn lại điều thực sự xảy ra và định tuyến mỗi thứ đáng giữ về đúng nơi: một quyết định → sổ DEC; một sự thật/ràng buộc không hiển nhiên → ghi chú bộ-nhớ-tự-động; phản hồi chỉnh sửa đáng giữ → bộ nhớ; việc hoãn → backlog. Bạn duyệt từng mục trước khi ghi — không gì lưu âm thầm.
A separate auto-memory directory (one fact per file, with a one-line index) persists user preferences, feedback, and project context across sessions and is recalled as background context next time. A nudge reminds you when a session made a decision but recorded none.Một thư mục bộ-nhớ-tự-động riêng (mỗi file một sự thật, kèm chỉ mục một dòng) lưu sở thích người dùng, phản hồi và bối cảnh dự án xuyên các phiên và được gợi lại làm bối cảnh nền lần sau. Một nudge nhắc khi một phiên có quyết định nhưng chưa ghi gì.
decisions.md, GLOSSARY.md, BACKLOG.md) are never hand-edited — edit the data, regenerate the view.Config của người là YAML; dữ liệu máy ghi là JSON/JSONL. Công cụ register giữ đường-ghi nên hai bên đọc không bao giờ lệch, và các bản Markdown sinh ra (decisions.md, GLOSSARY.md, BACKLOG.md) không bao giờ sửa tay — sửa dữ liệu, sinh lại bản xem.FAQHỏi đáp
Why YAML for the ledgers instead of Markdown?Vì sao sổ dùng YAML thay vì Markdown?
decisions.md) is generated from the YAML source of truth, so the two can never disagree.Công cụ đọc và ghi lại YAML an toàn; Markdown tự do lệch ngay khi hai người sửa. Markdown bạn đọc (decisions.md) sinh từ nguồn-sự-thật YAML, nên hai bên không bao giờ mâu thuẫn.Does the memory leave my machine?Bộ nhớ có rời máy tôi không?
state/. There is no server and no network call in the gate path.Không. Mỗi nơi là file cục bộ — git theo dõi các sổ, gitignore thư mục bộ-nhớ-tự-động và toàn bộ state/. Không server, không network call ở đường gate.