project-memory

name	project-memory
description	Bộ nhớ tri thức cấp dự án tự cải tiến: capture bài học, consolidate đúc kết, recall khi làm việc, execute tách riêng. Dữ liệu ghi vào memory/ ở gốc repo.

Project Memory

Bộ nhớ tri thức cho dự án đang mở. Gom bài học và context rời rạc vào kho có index routing, đúc kết định kỳ thành tri thức sạch, làm nền cải tiến dự án.

Cái lõi: tách 2 pha. Pha tri thức (capture, consolidate) và pha thực thi (execute) tách riêng. Consolidation không bao giờ tự nhảy sang execute.

Cơ chế portable, dữ liệu theo repo

Skill nằm trong skills/project-memory/, dùng cho mọi dự án. Dữ liệu ghi vào memory/ ở thư mục gốc repo đang mở. Script tự tìm gốc repo qua git rev-parse --show-toplevel.

Định tuyến theo lệnh

/project-memory <op> [query]:

op	Việc
capture	Ghi một bài học hoặc context vào kho
consolidate	Đúc kết kho: gộp trùng, phát hiện pattern, lint, archive
recall [query]	Đọc index, load entry liên quan
execute	Thực thi entry Tool/Map (pha tách riêng, user kích hoạt)

Không có op: hỏi user muốn làm gì.

Taxonomy: 3 loại bản chất

Loại	Prefix	Trả lời	Ghi gì
Tool (subtype improve/new)	T-	Làm việc X thế nào?	Cách làm + contract
Map	M-	Khi nào dùng tool nào, thứ tự ra sao?	Trình tự + tool mỗi bước
Fact	F-	Cần nhớ gì khi làm?	Sự kiện + khi nào liên quan

Schema chi tiết 3 loại, index, log, frontmatter mở rộng: references/schemas.md.

Phân vai LLM vs script

Script giữ index và log luôn đồng bộ với frontmatter, LLM khỏi gõ tay bảng:

Việc	Ai
Tạo entry, cấp ID tăng dần	scripts/new-entry.py <type> [subtype]
Dựng lại index.md từ frontmatter	scripts/reindex.py
Archive entry, đổi status, reindex	scripts/archive.py <id>
Append timeline	scripts/log.py <op> <summary>
Đúc kết, phát hiện pattern, lint, cross-ref	LLM đề xuất, user duyệt thay đổi cấu trúc

Chạy script bằng python (stdlib, không cần cài gói): python skills/project-memory/scripts/new-entry.py fact

capture

Hai ngả, cùng đổ về memory/entries/.

Thủ công: user gọi capture hoặc nói "ghi nhớ cái này". Đoán type và tags từ ngữ cảnh, hỏi gọn nếu chưa chắc (type? tiêu đề?). Chạy new-entry.py <type> [subtype], mở file vừa tạo, điền title, tags, và các section theo schema. Chạy reindex.py.

Gợi ý cuối phiên: khi task xong, quét hội thoại tìm tín hiệu đáng ghi, liệt kê đề xuất "nên capture X vào nhóm Y". User duyệt rồi mới ghi. Không tự ghi lén.

Tín hiệu nhận biết: references/capture-signals.md. Tóm tắt:

• Gotcha mất thời gian thử sai, ghi Fact.
• Một trình tự làm 2 lần trở lên, ghi Map.
• Skill có sẵn yếu hoặc thiếu năng lực, ghi Tool.

consolidate

Chạy thủ công. Quy trình đầy đủ, lint, cross-ref: references/consolidation.md.

Năm chốt:

• Đọc index, lọc entry status: raw, nhóm theo type + tags + related.
• Gộp trùng thành 1 entry gọn status: consolidated. Entry gốc không xóa, chuyển archive qua archive.py (giữ vết).
• Phát hiện pattern: từ 3 entry cùng trỏ 1 gốc, tạo entry tổng hợp mới.
• Lint health-check (orphan, mâu thuẫn, thiếu cross-ref, gap), chỉ đề xuất.
• Mọi thay đổi cấu trúc (merge, archive, sửa cross-ref) user duyệt trước, script chỉ chạy sau khi duyệt.

Consolidation dừng ở tầng tri thức. Output là entry consolidated sạch, danh sách pattern, báo cáo lint. Không tự thực thi.

recall

recall [query]: đọc chỉ index.md trước, match theo type/tags/tiêu đề, rồi chỉ load file entry liên quan (progressive disclosure).

Tự động gợi recall: đầu phiên hoặc khi task khớp tag, chủ động hỏi "memory có N entry liên quan, đọc không?".

File-answer-back: khi recall tổng hợp ra câu trả lời có giá trị (so sánh, phân tích, quy trình vừa đúc), đề nghị lưu thành entry mới (thường Map hoặc Fact). User duyệt. Nhờ vậy khám phá compound vào kho thay vì trôi vào chat.

Lấy 5 sự kiện gần nhất để biết vừa làm gì: grep "^## \[" memory/log.md | tail -5.

execute (pha tách riêng)

User kích hoạt, không tự nối tiếp consolidate. Đọc entry rồi làm trực tiếp bằng năng lực chung, không gọi skill ngoài.

• Entry Tool: đọc Contract đề xuất và Hành động, làm trực tiếp (sửa SKILL.md, hoặc tạo skill theo cấu trúc chuẩn). Checklist tối thiểu: references/self-contained-exec.md.
• Entry Map: chính là playbook, chạy theo trình tự.

Sau khi execute, ghi log: log.py execute "<id> <tóm tắt>".

Mọi thao tác ghi log

Capture, consolidate, execute đều append 1 dòng vào memory/log.md. Script new-entry và archive tự ghi. Thao tác thủ công gọi log.py.