BeGuru AI — Technical Docs: Memory, nén history & tầng context

Tóm lược

• Pipeline khái niệm: RawHistory (messages sau enrich) → CompressedHistory (nếu vượt ngưỡng) → PinnedLayer (ghim sau nén) → ContextPack cho Engineer (Next.js: build_nextjs_context_pack).
• Pins dùng tiền tố ổn định (FE spec, BUILD_STATE, MASTER, USER_INFO, KYB, project context, resource digest) — public internal API; đổi chuỗi phải migrate client/parser (xem fe_spec.py, beguru_chat_context.py trong repo).
• Artifact đĩa (PRODUCT_PLAN.md, BUILD_STATE.md, MASTER.md, beguru_chat_context.json, …) là SSOT giữa các lượt — Engineer đọc qua context pack, không cần full chat.
• DB: SQLite / SQLAlchemy (AgentMemory, AgentSession, WorkflowExecution); tùy chọn persist bản tóm tắt nén khi bật FREETEXT_PERSIST_COMPRESSOR_SUMMARY (hành vi chi tiết trong MEMORY_AND_CONTEXT_LAYERS.md).
• Hướng mở rộng: ADR-0002-memory-oss.md (Mem0 / pgvector / LangGraph) — hiện không triển khai tới khi có chứng cứ sản phẩm.

▸ADR-0002 — chi tiết

File ADR-0002-memory-oss.md trong repo mô tả hướng Mem0 / pgvector / LangGraph; chưa có trong runtime cho tới khi có chứng cứ sản phẩm (xem MEMORY_AND_CONTEXT_LAYERS.md mục cuối).

Mục đích

Giải thích contract nội bộ các tầng memory/context trong runtime beguru-ai, không thay thế toàn bộ MEMORY_AND_CONTEXT_LAYERS.md.

Pipeline tổng quát

1. RawHistory — messages trong request (sau enrich URL/file).
2. CompressedHistory — nếu len(messages) > freetext_compress_threshold: các turn cũ → [CONTEXT_SUMMARY …], giữ keep_recent turn cuối.
3. PinnedLayer — sau compress: message máy ghim cho PM (build_pm_pinned_machine_messages); không bị đưa vào bước tóm tắt (prepend sau).
4. ContextPack — với Engineer Next.js: spec, excerpt PRODUCT_PLAN, MASTER, BUILD_STATE, CROSS_STACK (tuỳ chọn), digest, task.

Bốn lớp “bộ nhớ” (ôn tập)

Lớp	Mô tả ngắn
Short-term	Turn trong request + cửa sổ sau nén; settings: freetext_compress_threshold, freetext_compress_keep_recent_*
Session structured (pins)	Block có tiền tố cố định; đặt sau compress
Artifact đĩa	File dưới design-system/ — nguồn chân lý giữa các lượt build
DB	SQLite; optional lưu summary sau nén (vận hành / bước sau)

Token, giới hạn đọc file

• Ước lượng token khi nén: log compress_history; FREETEXT_TOKEN_ESTIMATE_MODE: chars4 hoặc tiktoken_cl100k.
• Trần đọc BUILD_STATE / CROSS_STACK: freetext_build_state_max_chars, freetext_cross_stack_max_chars (env FREETEXT_BUILD_STATE_MAX_CHARS, FREETEXT_CROSS_STACK_MAX_CHARS).

Prompt resolution (Engineer generate)

• FREETEXT_LOG_PROMPT_RESOLUTION=true: log metadata manifest (segments_applied, độ dài spec/design, …).

Liên kết bài khác

• Artifact đĩa: Design system & đĩa.
• Route chat/generate: Runtime.
• Map hệ thống: Tổng quan.

---