Bạn biết GPT dự đoán từ tiếp theo trong câu. Nhưng nếu thay “từ” bằng “con số”, bạn sẽ có TimesFM — foundation model cho dự báo chuỗi thời gian từ Google Research. Bài viết này phân tích thuật toán, benchmark với 6 model truyền thống, và xây MVP dự báo du lịch Đà Nẵng.

Mục lục

1. TimesFM là gì?
2. Thuật toán — 8 bước chi tiết
3. Data training — 100 tỷ timepoints
4. MVP: Dự báo du lịch Đà Nẵng
5. Benchmark: TimesFM vs 6 model truyền thống
6. Kết luận

1. TimesFM là gì?

TimesFM (Time Series Foundation Model) là mô hình pretrained do Google Research phát triển, công bố tại ICML 2024. Ý tưởng cốt lõi: áp dụng kiến trúc GPT (decoder-only transformer) cho bài toán dự báo chuỗi thời gian.

Specs:

• 200M parameters (nhỏ hơn GPT-3 gần 1000 lần)
• 16K context length — nhìn được tới 16,000 điểm dữ liệu quá khứ
• Zero-shot — không cần train lại, chạy thẳng trên data mới
• Quantile forecast — confidence intervals 10%-90%

Paper: A decoder-only foundation model for time-series forecasting

Repo: github.com/google-research/timesfm

2. Thuật toán — 8 bước chi tiết

Tổng quan: “GPT cho Time Series”

Cách train TimesFM gần như giống hệt cách train GPT/LLM, chỉ thay token text → patch số liệu:

GPT:     "Tôi" → "đi" → "học" → [dự đoán: "bài"]
TimesFM: [32 giá] → [32 giá] → [32 giá] → [dự đoán: 128 giá tiếp]

Bước 1: Patching — Tokenize chuỗi số

Thay vì tokenize text thành words, TimesFM chia chuỗi thời gian thành patches (tương tự ViT chia ảnh):

Input: [y₁, y₂, ... y₅₁₂]  (512 ngày)
                ↓
Patch 1: [y₁ ... y₃₂]      ← 32 điểm = 1 "token"
Patch 2: [y₃₃ ... y₆₄]
...
Patch 16: [y₄₈₁ ... y₅₁₂]

Tại sao?

• Giảm sequence length 32× → transformer nhanh hơn nhiều
• Mỗi patch chứa đủ thông tin local (trend ngắn, mức noise)
• Output patch = 128 điểm (4× input) — “nhìn ít, đoán nhiều”

Bước 2: Input Encoding

Mỗi patch [32 số] + mask [32 bit] → concat thành vector 64 chiều → qua Residual Block (Linear→SiLU→Linear + skip connection) → vector 1280 chiều → cộng Rotary Position Embedding (RoPE).

Mask đánh dấu vị trí padding — model biết chỗ nào là data thật, chỗ nào không.

Bước 3: Transformer Decoder (Core)

20 layers, mỗi layer gồm:

1. RMSNorm (thay LayerNorm — nhẹ hơn)
2. Multi-Head Causal Attention: 16 heads × 80d, Fused QKV, Per-dim scaling
3. Residual connection
4. FFN với SiLU activation + Residual

Causal Attention = điểm mấu chốt — mỗi token chỉ nhìn được các token trước nó (tương lai bị che). Giống hệt GPT.

Bước 4: Output Heads

Mỗi output embedding → 2 heads:

Bước 5: Loss Function — MSE

Loss = mean(MSE₁, MSE₂, ..., MSEₙ)

Tính song song cho tất cả positions trong 1 forward pass. Decoder-only architecture cho phép parallelize hoàn toàn khi training.

Bước 6: Random Front Masking

Vấn đề: nếu train với patches đều đặn, model chỉ giỏi khi context = bội số 32.

Giải pháp: mỗi sample, random mask r ∈ [0, 31] điểm đầu của patch 1:

r=4:  Patch 1 = [MASK×4, y₅...y₃₂] → thấy 28 điểm
r=20: Patch 1 = [MASK×20, y₂₁...y₃₂] → thấy 12 điểm

Lặp qua tất cả r → model học được mọi context length.

Bước 7: RevIN (Reversible Instance Normalization)

# Forward: normalize
normalized = (patch - μ) / σ  # running stats per patch

# Transformer xử lý
output = Transformer(normalized)

# Reverse: denormalize
forecast = output × σ + μ

Đảm bảo f(aX + b) = a·f(X) + b — model xử lý được mọi scale (giá 1,684 hay giá 27 đều OK).

Bước 8: Autoregressive Decoding (Inference)

Prefill 16 patches → KV-Cache → Output 128 ngày
Nếu cần thêm: lấy output → chia patches mới → decode tiếp (dùng cache)

Giống LLM inference: KV-Cache tránh tính lại attention cho tokens cũ.

So sánh với GPT

3. Data training — 100 tỷ timepoints

TimesFM được pretrain trên ~100 tỷ timepoints từ 3 nguồn chính:

Google Trends (~0.5B timepoints)

• ~22K search queries phổ biến nhất
• Hourly, daily, weekly, monthly (2007-2022)
• Pattern: seasonal spikes, trends, mean-reversion

Wikipedia Pageviews (~300B timepoints) — Nguồn lớn nhất

• Lượt xem tất cả trang Wikimedia
• Jan 2012 – Nov 2023
• Pattern: daily/weekly seasonality + event-driven spikes

Synthetic Data (3 triệu chuỗi × 2048 points)

• ARMA processes
• Seasonal (tổ hợp sin/cos)
• Trends (linear, exponential + change points)
• Step functions

Ý nghĩa cho ứng dụng

TimesFM không được train trên financial data hay dữ liệu du lịch cụ thể. Nhưng vì Google Trends data là nguồn training chính, nên khi chúng ta dùng Google Trends làm input → đúng domain → accuracy cao.

4. MVP: Dự báo du lịch Đà Nẵng

Bài toán

Đà Nẵng đón 12.8 triệu lượt khách trong 8 tháng đầu 2025. Chủ khách sạn, nhà hàng, tour operator cần biết: tuần/tháng tới khách đông hay vắng?

Giải pháp

Kết hợp 4 nguồn dữ liệu miễn phí + TimesFM 2.5:

Google Trends (daily/weekly) ─┐
Open-Meteo Weather ───────────┤──> TimesFM 2.5 ──> Forecast
Event Calendar ───────────────┤                        │
Cục Thống kê ĐN (monthly) ───┘                   Dashboard

Google Trends — Leading Indicator

Tôi track 11 search queries liên quan đến du lịch Đà Nẵng:

Tiếng Việt (nội địa):

• “khách sạn đà nẵng”, “du lịch đà nẵng”, “vé máy bay đà nẵng”
• “bà nà hills”, “biển mỹ khê”

Tiếng Anh (quốc tế):

• “da nang hotel”, “da nang travel”, “flight to danang”
• “danang”, “danang hotel”, “vietnam beach”

Kết quả forecast (12 tuần tới)

“Khách sạn đà nẵng” — Search interest tăng 80.5% trong 12 tuần tới. Seasonal pattern rõ ràng: peak mùa hè.

Lượng khách hàng tháng — Từ peak 1,970K (T8/2025) dự báo giảm về ~1,296K (mùa mưa). Đúng seasonal pattern.

Nhận định từ model

Insight: Khách nội địa đang dẫn dắt tăng trưởng. Khách quốc tế giảm nhẹ — có thể do bất ổn địa chính trị toàn cầu (căng thẳng Iran). Khuyến nghị: focus marketing nội địa, tăng giá phòng mùa hè, tuyển thêm seasonal staff.

Dashboard tổng hợp: 11 queries + lượng khách + thời tiết Đà Nẵng

5. Benchmark: TimesFM vs 6 model truyền thống

Để đánh giá công bằng, tôi chạy walk-forward backtest (3 splits, horizon 6 tháng) trên data lượng khách hàng tháng:

Kết quả

Phân tích

Holt-Winters thắng — hợp lý vì:

• Data có seasonal pattern cực kỳ rõ (mùa hè vs mùa mưa)
• Chỉ 32 datapoints (monthly) — ít → model truyền thống chuyên seasonality chiếm ưu thế
• Holt-Winters được thiết kế đúng cho bài toán trend + seasonality

TimesFM 2.5 xếp thứ 4 nhưng đáng chú ý:

• Directional Accuracy = 80% — ngang top, đoán đúng hướng tăng/giảm
• Zero-shot hoàn toàn — không cần config, tuning, hay chọn hyperparameters
• Đánh bại Auto-ARIMA (cần grid search) và Prophet (Meta)
• Gap 43% MAE vs best — chấp nhận được cho model không train trên domain

Prophet tệ nhất — 32 datapoints quá ít cho Prophet hoạt động tốt.

Khi nào dùng gì?

6. Kết luận

TimesFM 2.5 — Đánh giá

Điểm mạnh:

• 🟢 Zero-shot: chạy ngay, không cần train hay tuning
• 🟢 Đa năng: 1 model cho mọi loại time series
• 🟢 Quantile forecast: confidence intervals miễn phí
• 🟢 Fast: ~2s cho 11 queries trên MacBook Air M1

Điểm yếu:

• 🔴 Thua model truyền thống trên data ít điểm + seasonal rõ
• 🔴 Không train trên financial data → stock forecast yếu
• 🔴 Cần PyTorch + HuggingFace (nặng hơn statsmodels)

MVP Du lịch Đà Nẵng — Lessons Learned

1. Google Trends = leading indicator tuyệt vời — khách search trước khi đến
2. TimesFM + Google Trends = match hoàn hảo — đúng domain training
3. Luôn benchmark — đừng assume model mới = tốt hơn
4. Kết hợp — dùng TimesFM cho daily trends (mạnh), Holt-Winters cho monthly visitors (mạnh hơn)

Source Code

• MVP: github.com/phanngoc/danang-tourism-forecast
• TimesFM: github.com/google-research/timesfm
• Paper: arxiv.org/abs/2310.10688

Viết bởi Ngoc Phan — Đà Nẵng, 04/2026

TL;DR: DeerFlow 2.0 là rewrite hoàn toàn của ByteDance, đạt #1 GitHub Trending ngày 28/2/2026 với 46k ⭐. Kiến trúc xoay quanh middleware pipeline composable, memory có schema rõ ràng, và subagent executor với ThreadPool + timeout. Bài này mổ xẻ từng phần từ source code thực tế, sau đó so sánh với OpenClaw để hiểu khi nào nên dùng cái nào.

Mục lục

1. Tổng quan
2. Middleware Pipeline
3. Memory System
4. Subagent Executor
5. ThreadState — Custom LangGraph State
6. DeerFlow vs OpenClaw
7. Lessons Learned
8. Nguồn & Stack

Tổng quan

DeerFlow v1 là một Deep Research framework đơn giản. V2 là rewrite hoàn toàn — không share một dòng code nào — thành một Super Agent Harness có thể:

• Orchestrate multiple sub-agents chạy song song
• Maintain long-term memory với schema structured
• Execute code trong isolated sandbox
• Nhận lệnh qua Telegram, Slack, Feishu
• Load extensible skills (tương tự plugin)

Stack: Python 3.12 + LangChain + LangGraph + FastAPI. Frontend: Next.js.

Phần 1: Middleware Pipeline

Thay vì hardcode mọi logic vào agent, DeerFlow dùng middleware chain có thứ tự rõ ràng:

# Từ lead_agent/agent.py — thứ tự này không phải ngẫu nhiên
middlewares = [
    ThreadDataMiddleware(),        # 1. inject workspace paths
    UploadsMiddleware(),           # 2. handle file uploads (cần thread_id từ #1)
    DanglingToolCallMiddleware(),  # 3. patch orphan ToolMessages
    SummarizationMiddleware(),     # 4. compress context SỚM để giảm tokens
    TodoMiddleware(),              # 5. plan mode (track tasks)
    TokenUsageMiddleware(),        # 6. track costs
    TitleMiddleware(),             # 7. auto-generate thread title
    MemoryMiddleware(),            # 8. async memory update (sau TitleMiddleware)
    ViewImageMiddleware(),         # 9. vision (nếu model support)
    DeferredToolFilterMiddleware(),# 10. tool search
    SubagentLimitMiddleware(),     # 11. cap parallel subagents
    LoopDetectionMiddleware(),     # 12. phá loop
    ClarificationMiddleware(),     # 13. CUỐI CÙNG: hỏi user
]

Mỗi middleware implement hook after_model() hoặc after_agent(). Cực kỳ dễ thêm/bỏ feature mà không đụng vào core agent logic.

LoopDetectionMiddleware — P0 Safety

Đây là middleware ấn tượng nhất. Agent AI hay bị stuck gọi cùng một tool liên tục — middleware này phá vòng lặp:

def _hash_tool_calls(tool_calls: list[dict]) -> str:
    """MD5 của (tool_name + args), order-independent."""
    normalized = [{"name": tc["name"], "args": tc["args"]} for tc in tool_calls]
    normalized.sort(key=lambda tc: (tc["name"], json.dumps(tc["args"], sort_keys=True)))
    blob = json.dumps(normalized, sort_keys=True)
    return hashlib.md5(blob.encode()).hexdigest()[:12]

Logic 3 mức:

1. Bình thường — pass qua
2. >= warn_threshold (mặc định 3) → inject cảnh báo vào HumanMessage
3. >= hard_limit (mặc định 5) → strip toàn bộ tool_calls, force text answer

Tại sao dùng HumanMessage thay vì SystemMessage? Anthropic không cho phép SystemMessage ở giữa conversation. Dùng HumanMessage work với mọi provider.

Sliding window 20 calls, LRU evict 100 threads — production-ready.

Phần 2: Memory System

Memory không phải flat string mà có schema JSON structured:

{
  "version": "1.0",
  "user": {
    "workContext":     { "summary": "...", "updatedAt": "..." },
    "personalContext": { "summary": "...", "updatedAt": "..." },
    "topOfMind":       { "summary": "...", "updatedAt": "..." }
  },
  "history": {
    "recentMonths":       { "summary": "...", "updatedAt": "..." },
    "earlierContext":     { "summary": "...", "updatedAt": "..." },
    "longTermBackground": { "summary": "...", "updatedAt": "..." }
  },
  "facts": []
}

Flow memory update

Agent hoàn thành turn
    ↓
MemoryMiddleware.after_agent()
    ↓
_filter_messages_for_memory()
  ✅ giữ: HumanMessage, AIMessage (không có tool_calls)
  ❌ bỏ: ToolMessage, AIMessage với tool_calls, <uploaded_files> blocks
    ↓
MemoryUpdateQueue.add(thread_id, filtered_messages)
    ↓ debounce timer
    ↓ batch nhiều threads update gần nhau
    ↓
MemoryUpdater.update_memory()  ← LLM summarize async
    ↓
Write JSON file (global hoặc per-agent)

Điểm tinh tế: <uploaded_files> blocks bị strip trước khi vào memory vì file paths là session-scoped. Nhưng user’s actual question vẫn được giữ lại.

Debounce Queue

class MemoryUpdateQueue:
    def add(self, thread_id, messages, agent_name=None):
        # Nếu thread đã có pending update → replace bằng cái mới nhất
        self._queue = [c for c in self._queue if c.thread_id != thread_id]
        self._queue.append(context)
        self._reset_timer()  # reset debounce

Elegant — nhiều conversations trong cùng debounce window được batch, và luôn dùng state mới nhất của mỗi thread.

Phần 3: Subagent Executor

Architecture

Lead Agent
  └─ gọi tool "task" → spawn subagent
        ↓
SubagentLimitMiddleware  ← hard cap 2-4 concurrent
        ↓
SubagentExecutor
  ├─ filter tools (allowlist/denylist per config)
  ├─ resolve model ("inherit" từ parent hoặc model riêng)
  └─ create minimal agent (thinking=False để tiết kiệm token)
        ↓
2 execution modes:
  ├─ execute()       → synchronous
  └─ execute_async() → background
       _scheduler_pool (3 workers): lifecycle + timeout
       _execution_pool (3 workers): actual execution

Async execution với real-time streaming

async def _aexecute(self, task: str, result_holder):
    agent = self._create_agent()
    # stream thay vì invoke → capture từng AIMessage real-time
    async for chunk in agent.astream(state, stream_mode="values"):
        last_msg = chunk.get("messages", [])[-1]
        if isinstance(last_msg, AIMessage):
            if not any(m.get("id") == last_msg.id for m in result.ai_messages):
                result.ai_messages.append(last_msg.model_dump())

Timeout handling

execution_future = _execution_pool.submit(self.execute, task, result_holder)
try:
    exec_result = execution_future.result(timeout=self.config.timeout_seconds)
except FuturesTimeoutError:
    result.status = SubagentStatus.TIMED_OUT
    execution_future.cancel()  # best-effort

Tránh đệ quy vô hạn

SubagentConfig(
    name="bash",
    tools=["bash", "ls", "read_file", "write_file", "str_replace"],
    disallowed_tools=["task", "ask_clarification"],  # subagent không spawn subagent
    model="inherit",
    max_turns=30,
)

Một dòng disallowed_tools=["task"] ngăn infinite recursion. Trace ID được parent truyền xuống subagent, giúp follow log chain mà không cần distributed tracing phức tạp.

Phần 4: ThreadState

Custom LangGraph State với reducers thông minh:

class ThreadState(AgentState):
    sandbox: NotRequired[SandboxState | None]
    thread_data: NotRequired[ThreadDataState | None]
    title: NotRequired[str | None]

    # Custom reducer: deduplicate artifacts
    artifacts: Annotated[list[str], merge_artifacts]

    # Custom reducer: empty dict = CLEAR (không phải merge!)
    viewed_images: Annotated[dict[str, ViewedImageData], merge_viewed_images]

    todos: NotRequired[list | None]
    uploaded_files: NotRequired[list[dict] | None]

viewed_images dùng convention {} để signal “clear all” — ViewImageMiddleware inject ảnh vào state, xử lý xong thì clear bằng return {"viewed_images": {}}.

Phần 5: DeerFlow vs OpenClaw

Sau khi mổ xẻ DeerFlow, mình thấy nó có nhiều điểm tương đồng với OpenClaw — cả hai đều là agent harness với skills/channels. Nhưng triết lý thiết kế khác nhau rõ ràng.

Bảng so sánh

Triết lý khác nhau

DeerFlow là “task-centric” — bạn đưa task, nó plan → execute → deliver. Tối ưu cho research, coding, report generation. Think: “Do this complex thing for me.”

OpenClaw là “ambient-centric” — agent chạy nền, chủ động monitor, proactive interrupt khi cần. Tối ưu cho personal productivity. Think: “Be my always-on assistant.”

Use case thực tế

Bạn cần...                          → Dùng
──────────────────────────────────────────────────────
Research report dài (1-2 giờ)       → DeerFlow
Deploy code với CI/CD               → DeerFlow
Multi-user workspace cho team       → DeerFlow
Nhắn Telegram lúc 7am hỏi tin       → OpenClaw
Nhắc meeting sau 30 phút            → OpenClaw
Monitor PR và ping khi merge        → OpenClaw
Chạy cron job kiểm tra server       → OpenClaw

Điều DeerFlow làm tốt hơn

LoopDetectionMiddleware là thứ OpenClaw không có nhưng nên có. Khi agent gọi tool lặp đi lặp lại, DeerFlow tự detect và force-stop sau 5 lần — critical cho production.

Memory schema granular hơn — phân biệt workContext vs personalContext vs topOfMind giúp LLM recall đúng loại thông tin.

Điều OpenClaw làm tốt hơn

Heartbeat system — OpenClaw tự động check email, calendar, mentions và proactive notify. DeerFlow hoàn toàn reactive.

Channel diversity — Signal, WhatsApp, Discord ngoài Telegram.

clawhub.com — Skills marketplace cho phép install features không cần code.

Verdict

Nếu build SaaS có AI feature → DeerFlow SDK.
Nếu cần personal assistant 24/7 → OpenClaw.
Nếu có budget → Cả hai: OpenClaw làm “daily driver”, DeerFlow làm “heavy worker”.

Lessons Learned

1. Middleware pattern > monolithic agent
Dễ add/remove behavior, dễ test từng middleware riêng lẻ, dễ debug. Pattern này giống Express.js middleware — ai đã làm Node.js sẽ thấy quen ngay.

2. Memory cần schema, không phải free-form
workContext, personalContext, topOfMind tách biệt → LLM summarize đúng chỗ → recall chính xác hơn. Free-form markdown linh hoạt hơn nhưng recall kém hơn.

3. Loop detection là must-have cho production
Hash tool calls + sliding window là approach đơn giản mà hiệu quả. Không có cái này, agent có thể bị stuck vô hạn gây chi phí không kiểm soát.

4. Debounce queue cho memory update
Không cần update memory sau mỗi message. Batch + debounce giảm API calls đáng kể, đồng thời luôn giữ state mới nhất.

5. Subagent không được spawn subagent
disallowed_tools=["task"] — một dòng config ngăn infinite recursion. Đơn giản nhưng dễ bỏ sót khi tự build.

Nguồn & Stack

Source code: git clone https://github.com/bytedance/deer-flow (phân tích commit tháng 3/2026)

Stack DeerFlow:

• Python 3.12 · LangChain · LangGraph · FastAPI · Next.js
• Tested với: Claude Sonnet 4.6 via CLIProxyAPI OAuth (Max subscription, không cần API key trực tiếp)

Bài viết phân tích cách claude-mem giải quyết bài toán cốt lõi của AI agent: làm thế nào để “nhớ” chính xác những gì quan trọng qua nhiều session, trong khi vẫn giữ context nhỏ gọn và tìm kiếm hiệu quả. Đây là bài học thực tế từ việc reverse-engineer và benchmark toàn bộ pipeline.

Mục lục

1. Vấn đề cần giải quyết
2. Kiến trúc tổng quan — 7 phases
3. Phase 1: Hook vào tool activity
4. Phase 2-3: Observer XML generation
5. Phase 4: Atomic SQLite storage + FTS5
6. Phase 5-6: ChromaDB semantic sync
7. Phase 7: Hybrid search + context injection
8. Schema SQLite — 7 migrations
9. Benchmark thực tế
10. Key design decisions

1. Vấn đề cần giải quyết

Claude Code làm việc trong sessions ngắn. Mỗi session restart, toàn bộ context biến mất. Các giải pháp naive:

• Replay toàn bộ transcript: 50 tool calls × 300 tokens = 15,000 tokens. Tốn kém, nhiễu.
• Tóm tắt thủ công: Phụ thuộc vào user, không đáng tin.
• Lưu raw logs: Fast nhưng không searchable, không hierarchical.

claude-mem giải quyết bằng cách ép một observer agent chọn lọc và extract những gì thực sự quan trọng thành schema cố định — và inject context đó vào session tiếp theo với 39x ít tokens hơn.

2. Kiến trúc tổng quan

Tool Call (raw, noisy)
  ↓ PostToolUse hook
HTTP POST /api/sessions/observations
  ↓ SessionQueueProcessor
buildObservationPrompt()  →  XML prompt
  ↓ @anthropic-ai/claude-agent-sdk
Observer Claude (no tools, read-only)
  ↓ selectivity filter
<observation> XML  |  "no observation needed"
  ↓ parseObservations()
ParsedObservation struct
  ↓ storeObservation() — atomic, dedup
SQLite (observations table)  →  FTS5 auto-trigger
  ↓ async fire-and-forget
ChromaDB (vector embeddings)
  ↓
GET /api/context/inject
  ↓ HybridSearch (FTS5 + Chroma)
Top-N context  →  Next session

7 phases, mỗi phase giải quyết 1 vấn đề cụ thể.

3. Phase 1: Hook vào tool activity

// PostToolUse hook trong Claude Code
HTTP POST /api/sessions/observations
{
  contentSessionId: "user-abc123",   // user's session
  tool_name: "Write",
  tool_input: { path: "server/db.js" },
  tool_response: "File written (728 insertions)",
  cwd: "/projects/kanban-mvp"
}

Key insight: Dùng 2 loại session ID riêng biệt:

• contentSessionId → gắn với user’s work (stable)
• memorySessionId → gắn với observer agent (thay đổi khi restart)

Observer crash và restart không mất data vì tất cả observations đều gắn với contentSessionId.

4. Phase 2-3: Observer XML generation

Observer Claude nhận prompt được format từ tool call:

<observed_from_primary_session>
  <what_happened>Write</what_happened>
  <parameters>{"path": "server/db.js"}</parameters>
  <outcome>"File written (728 insertions, 10 files changed)"</outcome>
  <working_directory>/projects/kanban-mvp</working_directory>
</observed_from_primary_session>

Observer được config không có tools (observer-only) và respond bằng XML có schema cố định:

<observation>
  <type>feature</type>
  <title>Issue Version History Database Schema</title>
  <subtitle>Added SQLite table and snapshot function</subtitle>
  <facts>
    <fact>issue_history table với composite PRIMARY KEY (repo_key, number, version)</fact>
    <fact>snapshotIssue() function capture state trước mỗi edit</fact>
    <fact>Version numbers auto-increment per issue</fact>
    <fact>728 insertions across 10 files</fact>
  </facts>
  <narrative>Implemented foundational infrastructure for version history tracking.</narrative>
  <concepts>
    <concept>architecture</concept>
    <concept>how-it-works</concept>
  </concepts>
  <files_modified>
    <file>server/db.js</file>
  </files_modified>
</observation>

Selectivity quan trọng: Observer tự quyết định skip noise:

• git log --oneline -3 → “routine git status, no observation needed”
• Write server/db.js (728 insertions) → captured với 4 facts cụ thể
• Write tests/e2e/06-history.spec.cjs → captured với 21 tests, full coverage info

5. Phase 4: Atomic SQLite storage + FTS5

// observations/store.ts
function storeObservation(db, memorySessionId, project, observation) {
  // 1. Content-hash deduplication (30s window)
  const hash = sha256(memorySessionId + title + narrative).slice(0, 16)
  const existing = db.query(
    'SELECT id FROM observations WHERE content_hash = ? AND created_at_epoch > ?'
  ).get(hash, Date.now() - 30_000)
  if (existing) return { id: existing.id }  // skip duplicate

  // 2. Atomic INSERT
  db.prepare(`
    INSERT INTO observations
    (memory_session_id, project, type, title, subtitle,
     facts, narrative, concepts, files_modified,
     discovery_tokens, content_hash, created_at_epoch)
    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
  `).run(
    memorySessionId, project, type, title, subtitle,
    JSON.stringify(facts), narrative, JSON.stringify(concepts),
    JSON.stringify(files_modified),
    discoveryTokens, hash, Date.now()
  )
}

Ngay sau INSERT, FTS5 trigger tự động fire:

-- Auto-generated trigger từ migration006
CREATE TRIGGER observations_ai AFTER INSERT ON observations BEGIN
  INSERT INTO observations_fts(rowid, title, subtitle, narrative, text, facts, concepts)
  VALUES (new.id, new.title, new.subtitle, new.narrative, new.text, new.facts, new.concepts);
END;

Kết quả: SQLite query <1ms ở 10,000 observations, WAL mode, zero config.

6. Phase 5-6: ChromaDB semantic sync

// Async, fire-and-forget — không block storage
ChromaSync.syncObservation(obsId)

// Build document text (concatenate fields for embedding)
const doc = `${title} ${subtitle} ${facts.join(' ')} ${narrative} ${concepts.join(' ')}`

// Gọi chroma-mcp subprocess (Python 3.11)
await chromaMcp.callTool("chroma_add_documents", {
  collection_name: "kanban-mvp_observations",
  documents: [doc],
  ids: [`obs_${obsId}`],
  metadatas: [{ type, project, created_at_epoch }]
})
// → onnxruntime embeds: [0.023, -0.145, ...] (384 dims, all-MiniLM-L6-v2)
// → stored in ~/.claude-mem/chroma/

Python version gotcha: ChromaDB chỉ tương thích Python 3.11. Python 3.13/3.14 fail do onnxruntime dependency conflict. Fix:

// ~/.claude-mem/settings.json
{ "CLAUDE_MEM_PYTHON_VERSION": "3.11" }

7. Phase 7: Hybrid search + context injection

// HybridSearchStrategy
async search(query, project, limit) {
  // 1. SQLite FTS5 — keyword match, <1ms
  const ftsIds = db.query(`
    SELECT rowid FROM observations_fts
    WHERE observations_fts MATCH ?
    ORDER BY rank  -- BM25
  `).all(query).map(r => r.rowid)

  // 2. ChromaDB — semantic similarity, ~100-500ms
  const chromaResults = await chroma.query({
    collection: `${project}_observations`,
    query_texts: [query],
    n_results: limit * 2
  })

  // 3. Intersect + order by Chroma (semantic) rank
  const rankedIds = chromaResults.ids
    .filter(id => ftsIds.includes(parseInt(id.replace('obs_', ''))))

  // 4. Hydrate full rows từ SQLite
  return rankedIds.map(id => db.query('SELECT * FROM observations WHERE id = ?').get(id))
}

Context injection output (format compact, token-efficient):

# $CMEM kanban-mvp 2026-03-21 10:19am GMT+7

Stats: 2 obs (491t read) | 705t work | 30% savings

1 10:06a 🟣 Issue Version History Database Schema
2 10:19a 🟣 E2E test suite for issue version history

Access 1k tokens of past work via get_observations([IDs]) or mem-search skill.

8. Schema SQLite — 7 migrations

migrations/
├── 001 — Core tables: sessions, memories, overviews, diagnostics, transcript_events
├── 002 — Add hierarchical fields to memories (title, subtitle, facts, concepts)
├── 003 — streaming_sessions (v2 arch — deprecated)
├── 004 — SDK agent arch: sdk_sessions, observation_queue, observations, session_summaries
├── 005 — DROP orphaned tables (streaming_sessions, observation_queue)
├── 006 — FTS5 virtual tables + auto-sync triggers
└── 007 — discovery_tokens column (ROI tracking)

Core schema hiện tại (post-migration 007):

sdk_sessions (1) ──── (N) observations
sdk_sessions (1) ──── (1) session_summaries
observations   ──── auto-trigger ──── observations_fts (FTS5)
observations   ──── async ──── ChromaDB (vectors)

observations:
  type, title, subtitle, facts JSON, narrative, concepts JSON
  files_read JSON, files_modified JSON
  discovery_tokens, content_hash  ← dedup + ROI

9. Benchmark thực tế

Đo trên macOS 14.6 M1, Bun 1.3.11, 46 test cases:

Compression reality check:

Short sessions don’t compress — by design. At scale (50+ calls với file reads), savings rất lớn.

10. Key design decisions

1. Facts array thay vì narrative blob

❌ "Implemented authentication using express-session with SQLite backend 
    where tokens are stored server-side and never exposed via httpOnly cookies"

✅ facts: [
    "express-session + connect-sqlite3",
    "token không bao giờ gửi xuống browser",
    "httpOnly cookie trong production",
    "7-day session expiry (604800s)"
  ]

Mỗi fact độc lập, verifiable, và match được riêng biệt → recall cao hơn nhiều.

2. Dual session IDs — tách concerns

Observer crash không mất data vì observations luôn gắn với contentSessionId (user’s work), không phải memorySessionId (observer state).

3. Chroma là optional, FTS5 là mandatory

Nếu Chroma down, SQLite FTS5 vẫn serve keyword search. discovery_tokens không phụ thuộc vào Chroma.

4. discovery_tokens — feedback loop

487 tokens → 4 facts = efficient
2000 tokens → 2 facts = prompt cần tune

Đây là signal để cải thiện observer prompt theo thời gian.

5. Observer không có tools

Strict: observer chỉ có thể read và write observations. Không thể Bash, Write, Edit. Loại bỏ hoàn toàn infinite loop risks.

Kết luận

claude-mem không phải là “lưu chat history vào DB”. Đây là một structured knowledge extraction pipeline với:

• Observer agent thông minh, chọn lọc
• Schema atomic facts (không phải narrative blob)
• Hybrid search (FTS5 keyword + ChromaDB semantic)
• Deduplication, ROI tracking, crash-safe dual IDs

39x token savings không phải là con số marketing — đó là kết quả đo được khi pipeline đủ mature để phân biệt signal khỏi noise.

Code: thedotmack/claude-mem

Tags: SQLite, AI Memory, ChromaDB, Claude Code, RAG, Bun

Disclaimer: Bài viết này hoàn toàn mang tính nghiên cứu kỹ thuật. Hãy tôn trọng Terms of Service của các nền tảng bạn tương tác.

Ở bài trước, tôi đã mổ xẻ toàn bộ hệ thống anti-bot của Shopee — 6 lớp phòng thủ từ TLS fingerprint đến behavioral analysis — và kết luận rằng không có giải pháp free nào bypass được ở scale.

Nhưng bài đó bỏ sót một insight quan trọng: điều gì xảy ra nếu chúng ta không cần bypass bất kỳ lớp nào?

Thay vì giả mạo browser, giả mạo hành vi người dùng, rotate proxy đắt tiền — tại sao không dùng luôn browser thật của bạn? Mọi cookie, mọi fingerprint, mọi behavioral signal đều 100% authentic. Chúng ta chỉ cần một cách để “nghe lén” các API call mà browser đang thực hiện.

Đó là ý tưởng đằng sau shopee-proxy — một hệ thống zero-bypass crawling dùng Chrome Extension làm network sniffer, local Python server làm data sink, và SQLite làm storage.

Vấn Đề Gốc Rễ Với Mọi Crawler Truyền Thống

Trước khi vào architecture, hãy hiểu tại sao approach thông thường thất bại.

Khi bạn dùng requests, Playwright, hay Selenium để crawl Shopee, bạn đang cố gắng impersonate một browser. Shopee detect impersonation thông qua:

[Your bot]
    ├── TLS fingerprint ≠ real Chrome → BLOCK
    ├── Canvas hash = known headless hash → BLOCK  
    ├── Mouse patterns = too uniform → CAPTCHA
    ├── IP = datacenter/proxy → rate limit
    └── Session tokens = stale/stolen → REVOKE

Mỗi lớp detection là một signal độc lập. Bypass 5/6 vẫn bị block.

Insight: Thay vì impersonate browser, hãy là browser. Chỉ cần thêm một lớp ở giữa để capture data mà browser đang fetch.

[Real Chrome, thật 100%]
    ├── TLS fingerprint = real Chrome ✅
    ├── Canvas hash = real GPU ✅
    ├── Mouse patterns = bạn đang dùng chuột thật ✅
    ├── IP = IP nhà bạn ✅
    └── Session tokens = thật, fresh ✅
    │
    └── [Chrome Extension] ← chúng ta chỉ thêm cái này
            │ intercept API responses
            ▼
    [Local Python Server]
            │ parse + store
            ▼
    [SQLite Database]

Kiến Trúc Tổng Thể

Hệ thống gồm 2 phần chạy song song:

┌─────────────────────────────────────────────────────────────┐
│                    Chrome Browser                            │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                 Web Page (MAIN world)                │    │
│  │                                                      │    │
│  │  window.fetch()    ←── intercepted by injector.js   │    │
│  │  XMLHttpRequest()  ←── intercepted by injector.js   │    │
│  │                                                      │    │
│  │  Khi có API response → window.postMessage(payload)  │    │
│  └──────────────────────────┬──────────────────────────┘    │
│                             │ postMessage                    │
│  ┌──────────────────────────▼──────────────────────────┐    │
│  │            Content Script (ISOLATED world)           │    │
│  │                      bridge.js                       │    │
│  │                                                      │    │
│  │  Nhận postMessage → chrome.runtime.sendMessage()    │    │
│  └──────────────────────────┬──────────────────────────┘    │
│                             │ chrome.runtime message         │
│  ┌──────────────────────────▼──────────────────────────┐    │
│  │                  background.js                       │    │
│  │              (Service Worker, MV3)                   │    │
│  │                                                      │    │
│  │  Nhận message → đính kèm cookies → POST /capture    │    │
│  └──────────────────────────┬──────────────────────────┘    │
└───────────────────────────────────────────────────────────   │
                              │ HTTP POST localhost:9234
┌─────────────────────────────▼───────────────────────────┐
│                     proxy.py                             │
│                 (Python HTTP Server)                     │
│                                                          │
│  Nhận payload → parse recommend_v2 / search_items       │
│  → INSERT OR IGNORE INTO products                        │
│                    │                                     │
│                    ▼                                     │
│              products.db (SQLite)                        │
└──────────────────────────────────────────────────────────┘

4 components, mỗi cái một trách nhiệm rõ ràng. Hãy đi sâu vào từng phần.

Component 1: injector.js — Monkey-Patch Fetch/XHR

Đây là “trái tim” của extension. File này được inject vào MAIN world của trang web — nghĩa là nó chạy trong cùng execution context với JavaScript của Shopee, có thể override các global APIs.

// injector.js — chạy trong MAIN world của trang
(function () {
  if (window.__shopeeCapture) return;  // chống inject lại
  window.__shopeeCapture = true;

  // Intercept fetch
  const _fetch = window.fetch;  // lưu bản gốc
  window.fetch = async function (...args) {
    const [input, init] = args;
    const url = typeof input === "string" ? input : input?.url || "";

    // Chỉ capture các API call
    if (!isApi(url)) return _fetch.apply(this, args);

    // Gọi fetch thật
    const resp = await _fetch.apply(this, args);
    
    // Clone response để đọc body (response body chỉ đọc được 1 lần)
    const clone = resp.clone();
    clone.text().then((body) => {
      emit({
        method, url,
        timestamp: new Date().toISOString(),
        requestBody: reqBody,
        responseStatus: resp.status,
        responseBody: body,  // full response body
      });
    });

    return resp;  // trả về response gốc cho Shopee
  };
})();

Tại sao clone response? Response.body là ReadableStream — chỉ có thể đọc một lần. Nếu chúng ta đọc nó trước, Shopee code sẽ nhận về stream rỗng. resp.clone() tạo bản sao để chúng ta đọc riêng mà không ảnh hưởng đến luồng chính.

Tương tự với XHR:

// Patch XMLHttpRequest
XMLHttpRequest.prototype.open = function (method, url, ...rest) {
  this._cap = { method: method.toUpperCase(), url, headers: {} };
  return _open.call(this, method, url, ...rest);
};

XMLHttpRequest.prototype.send = function (body) {
  if (this._cap && isApi(this._cap.url)) {
    this.addEventListener("load", function () {
      emit({
        url: this._cap.url,
        responseBody: this.responseText,  // XHR thì dễ hơn
        // ...
      });
    });
  }
  return _send.call(this, body);
};

Component 2: Chrome Extension World Isolation

Chrome Extension MV3 có một security model quan trọng cần hiểu: world isolation.

┌─────────────────────────────────────────┐
│             Chrome Tab                   │
│                                          │
│  ┌─────────────────────────────────┐    │
│  │    MAIN world                   │    │
│  │    - Shopee's JavaScript        │    │
│  │    - window.fetch (original)    │    │
│  │    - injector.js ← inject vào đây│   │
│  └──────────────┬──────────────────┘    │
│                 │ window.postMessage     │
│  ┌──────────────▼──────────────────┐    │
│  │    ISOLATED world               │    │
│  │    - Content scripts (bridge.js)│    │
│  │    - Có chrome.* API            │    │
│  │    - Không có window.fetch thật │    │
│  └──────────────┬──────────────────┘    │
│                 │ chrome.runtime.sendMessage
└─────────────────│───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│  Service Worker (background.js)          │
│  - Chạy ngoài tab                        │
│  - Có chrome.cookies API                 │
│  - Có fetch() để call localhost          │
└──────────────────────────────────────────┘

Tại sao cần bridge.js?

Content scripts chạy trong ISOLATED world — họ không thể đọc/ghi window của trang web. Nhưng cả MAIN world lẫn ISOLATED world đều nhận window.postMessage từ cùng origin.

Đây là cách data flow:

1. injector.js (MAIN) gọi window.postMessage({ type: "__SHOPEE_CAPTURE__", payload })
2. bridge.js (ISOLATED) lắng nghe window.addEventListener("message", ...)
3. bridge.js forward qua chrome.runtime.sendMessage()
4. background.js (Service Worker) nhận và POST lên localhost

// bridge.js — đơn giản nhưng critical
window.addEventListener("message", (event) => {
  if (event.source !== window) return;  // chỉ nhận từ cùng tab
  if (event.data?.type !== "__SHOPEE_CAPTURE__") return;  // filter đúng type
  
  try {
    chrome.runtime.sendMessage({ action: "capture", data: event.data.payload });
  } catch (e) {
    // Extension context có thể bị invalidate khi reload extension
    // Ignore để tránh crash
  }
});

Component 3: background.js — Cookie Enrichment + HTTP Forward

Background script có quyền truy cập chrome.cookies API — thứ mà content script không có. Trước khi POST lên local server, nó đính kèm toàn bộ cookies của .shopee.vn:

// background.js
chrome.runtime.onMessage.addListener((message) => {
  if (message.action !== "capture") return;

  // Lấy toàn bộ cookies shopee.vn
  chrome.cookies.getAll({ domain: ".shopee.vn" }, (cookies) => {
    const cookieStr = cookies.map((c) => `${c.name}=${c.value}`).join("; ");
    
    const enriched = { 
      ...message.data,    // original payload (url, method, body, headers)
      cookies: cookieStr  // thêm cookies vào
    };

    // POST lên local proxy server
    fetch("http://localhost:9234/capture", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(enriched),
    });
  });
});

Một điểm thú vị về SPA navigation: Shopee là Single Page Application dùng React. Khi bạn navigate giữa các trang, URL thay đổi nhưng không có full page reload. injector.js có thể bị mất sau navigation.

background.js handle điều này bằng cách lắng nghe chrome.webNavigation.onHistoryStateUpdated — event này fire mỗi khi SPA thay đổi URL qua History API:

// Re-inject khi SPA navigate
chrome.webNavigation?.onHistoryStateUpdated?.addListener(
  (details) => {
    if (details.frameId !== 0) return;
    chrome.scripting.executeScript({
      target: { tabId: details.tabId },
      files: ["injector.js"],
      world: "MAIN",
    });
  },
  { url: [{ hostContains: "shopee.vn" }] }
);

Component 4: proxy.py — Parse, Deduplicate, Store

Python HTTP server nhận POST requests từ extension và parse data ra 2 API format khác nhau.

Shopee có 2 API trả về sản phẩm:

1. recommend/recommend_v2 — dùng cho category pages, có structure phức tạp hơn:

def parse_recommend_product(unit: dict) -> dict | None:
    item = unit.get("item", {})
    asset = item.get("item_card_displayed_asset", {})  # display data
    item_data = item.get("item_data", {})  # raw data

    # Lấy item_id từ tracking_card_id
    # Format: "TYPE::SHOPID::ITEMID"
    tid = unit.get("tracking_card_id", "")
    item_id = tid.split("::")[-1] if "::" in tid else ""

    # Price được store dưới dạng integer * 100000
    price_raw = asset.get("display_price", {}).get("price", 0)
    price = price_raw / 100000  # convert về VND thật

    return {
        "item_id": item_id,
        "name": asset.get("name", ""),
        "price": price,
        # ...
    }

2. search/search_items — dùng cho search results, structure đơn giản hơn:

def parse_search_product(item: dict) -> dict | None:
    item_basic = item.get("item_basic") or item
    item_id = str(item_basic.get("itemid", ""))

    price = item_basic.get("price", 0) / 100000
    
    # Sold count formatting
    historical_sold = item_basic.get("historical_sold", 0)
    if historical_sold >= 1000:
        sold_text = f"Đã bán {historical_sold // 1000}k+"
    else:
        sold_text = f"Đã bán {historical_sold}" if historical_sold else ""

    # Seller type
    if item_basic.get("is_official_shop"):
        seller_type = "MALL"
    elif item_basic.get("shopee_verified"):
        seller_type = "PREFERRED"

    return { "item_id": item_id, "price": price, "sold": sold_text, ... }

SQLite với INSERT OR IGNORE — deduplication tự động:

def init_db(db_path: str) -> sqlite3.Connection:
    conn = sqlite3.connect(db_path)
    conn.execute("""
        CREATE TABLE IF NOT EXISTS products (
            item_id TEXT PRIMARY KEY,  -- PRIMARY KEY đảm bảo unique
            shop_id TEXT,
            name TEXT,
            price REAL,
            original_price REAL,
            discount TEXT,
            sold TEXT,
            seller_type TEXT,
            image TEXT,
            images TEXT,       -- JSON array
            url TEXT,
            category_id TEXT,
            captured_at TEXT
        )
    """)
    return conn

def insert_products(products: list[dict], cat_id: str) -> int:
    for p in products:
        conn.execute(
            """INSERT OR IGNORE INTO products (...)  -- bỏ qua nếu item_id đã tồn tại
               VALUES (?, ?, ?, ...)""",
            (...),
        )
    conn.commit()

INSERT OR IGNORE kết hợp với PRIMARY KEY trên item_id tự động handle deduplication — cùng một sản phẩm xuất hiện ở nhiều pages/categories chỉ được lưu một lần.

manifest.json — Minimum Permissions

Extension request đúng permissions cần thiết, không hơn:

{
  "manifest_version": 3,
  "name": "Shopee Network Capture",
  "version": "2.2",
  "permissions": [
    "scripting",      // để inject injector.js vào MAIN world
    "tabs",           // để detect tab navigation
    "webNavigation",  // để detect SPA history changes
    "cookies"         // để đọc shopee.vn cookies
  ],
  "host_permissions": ["*://*.shopee.vn/*"],  // chỉ trên shopee.vn
  "background": {
    "service_worker": "background.js"  // MV3: service worker thay cho background page
  },
  "content_scripts": [{
    "matches": ["*://*.shopee.vn/*"],
    "js": ["bridge.js"],
    "run_at": "document_start"  // inject sớm nhất có thể
  }]
}

Workflow Thực Tế

1. Khởi động server

pip install rich
python3 proxy.py --db products.db --port 9234

Output:

╭─────────────────────────────────────────╮
│          Shopee Product Proxy           │
│ Server:   http://localhost:9234         │
│ Database: /path/products.db (0 products)│
│ Captures: recommend_v2 + search_items  │
╰─────────────────────────────────────────╯

Listening... Browse Shopee category pages.

2. Load Extension

chrome://extensions → Developer mode → Load unpacked → chọn thư mục extension/

3. Browse Shopee bình thường

Mở bất kỳ category page nào, scroll:

  # 1  GET 200 /api/v4/recommend/recommend_v2
       ＋48 new (0 dupes, 48 parsed, 48 in DB)
  # 2  GET 200 /api/v4/recommend/recommend_v2
       ＋0 new (48 dupes, 48 parsed, 48 in DB)
  # 3  POST 200 /api/v4/recommend/recommend_v2
       ＋52 new (3 dupes, 55 parsed, 100 in DB)
  # 4  GET 200 /api/v4/search/search_items
       ＋24 new (0 dupes, 24 parsed, 124 in DB)

4. Query data

sqlite3 products.db "
  SELECT name, printf('%.0f', price) as price, discount, sold
  FROM products
  WHERE seller_type = 'MALL'
  ORDER BY price DESC
  LIMIT 10;
"

Hoặc trong Python:

import sqlite3, json

conn = sqlite3.connect("products.db")

# Top sản phẩm discount cao nhất
results = conn.execute("""
    SELECT name, price, original_price, discount
    FROM products
    WHERE original_price IS NOT NULL
    ORDER BY (original_price - price) DESC
    LIMIT 20
""").fetchall()

for name, price, orig, disc in results:
    print(f"{name[:40]} | {price:,.0f}đ | {disc}")

Xử Lý Edge Cases

Anti-bot Response (error code 90309999)

Shopee đôi khi trả về response với error code này khi phát hiện bất thường. proxy.py check và skip:

if "90309999" in resp_body:
    console.print("[red]BLOCKED (anti-bot)[/]")
    return 0, 0

Trong thực tế với approach này (browser thật), bạn rất hiếm gặp error này vì mọi request đều đến từ session hợp lệ của bạn.

SPA Navigation — Re-inject

Shopee SPA thay đổi URL mà không reload page. background.js inject lại injector.js mỗi khi detect history state change:

chrome.webNavigation?.onHistoryStateUpdated?.addListener(
  (details) => {
    chrome.scripting.executeScript({
      target: { tabId: details.tabId },
      files: ["injector.js"],
      world: "MAIN",
    });
  },
  { url: [{ hostContains: "shopee.vn" }] }
);

Guard if (window.__shopeeCapture) return; trong injector.js đảm bảo nếu đã inject rồi thì không patch lại (tránh double-patch fetch/XHR).

Extension Context Invalidated

Khi bạn reload extension trong chrome://extensions, Service Worker bị restart nhưng content scripts trong các tab đang mở thì không. chrome.runtime.sendMessage() trong bridge.js lúc này sẽ throw error.

try {
  chrome.runtime.sendMessage({ action: "capture", data: event.data.payload });
} catch (e) {
  // Extension context invalidated — bỏ qua, không crash page
}

Crawl.py — Standalone Extractor Từ JSON Log

Ngoài real-time capture, có thể export network log từ Chrome DevTools và parse offline:

# crawl.py
def extract_from_log(log_file: str) -> list[dict]:
    with open(log_file) as f:
        data = json.load(f)

    all_products = []
    seen_ids = set()

    for r in data:
        url = r.get("url", "")
        if "recommend/recommend_v2" not in url:
            continue

        resp_body = r.get("response_body", "")
        if not resp_body or "90309999" in resp_body:
            continue

        resp = json.loads(resp_body)
        units = resp.get("data", {}).get("units", [])
        
        for u in units:
            product = parse_product(u)
            if product and product["item_id"] not in seen_ids:
                seen_ids.add(product["item_id"])
                all_products.append(product)

    return all_products

Dùng khi bạn đã có sẵn network_log.json (export từ DevTools → Network → Save all as HAR):

python3 crawl.py --log network_log.json --output products.json

So Sánh Với Các Approach Khác

*Scale limitation: Approach này yêu cầu bạn browse thủ công hoặc có browser đang chạy thật. Không tự động hoàn toàn như headless crawler. Phù hợp với data collection có giám sát, không phải autonomous scraping 24/7.

Giới Hạn Và Khi Nào Nên Dùng

Phù hợp khi:

• Cần data chất lượng cao, không lo bị block
• Dataset size vừa phải (vài ngàn đến vài chục ngàn sản phẩm)
• Có thể để browser chạy trong vài giờ
• Muốn lấy data từ nhiều categories khác nhau

Không phù hợp khi:

• Cần crawl 1 triệu+ sản phẩm một cách autonomous
• Cần schedule tự động không cần người dùng
• Production pipeline không có human supervision

Extension vào approach tốt hơn:

• Thêm auto-pagination: inject JavaScript để tự click “next page” sau mỗi N giây
• Kết hợp với category list để system hướng dẫn bạn browse đúng trang
• Add price tracking: so sánh price giữa các lần capture để detect price changes

Kết Luận

Đôi khi giải pháp tốt nhất không phải là đánh trực tiếp vào vấn đề — mà là đi vòng quanh nó.

Thay vì chiến đấu với 6 lớp anti-bot của Shopee bằng proxy đắt tiền, fingerprint spoofing, và behavior simulation phức tạp, hệ thống này tận dụng một sự thật đơn giản: browser thật của bạn đã vượt qua tất cả các lớp đó rồi. Chúng ta chỉ cần một cái “tai nghe” gắn vào.

Kiến trúc này dạy chúng ta một bài học quan trọng về system design: luôn hỏi “có gì sẵn có mà ta có thể tận dụng không?” trước khi bắt đầu build từ đầu.

Data pipeline đơn giản nhất thường là data pipeline tốt nhất.

Source code: github.com/phanngoc/shopee-proxy

Xem thêm: Giải Mã Hệ Thống Anti-Bot Của Shopee — phân tích 6 lớp phòng thủ và 10 lần thất bại.

Tôi crawl 16,825 bài báo từ Tuổi Trẻ Online trong vòng 24 phút bằng Go + Chrome DevTools Protocol, sau đó dùng TF-IDF clustering để vẽ bản đồ các chủ đề chính trị theo tuần. Kết quả khá thú vị — đặc biệt là cú shock của chiến sự Iran bắt đầu ngày 28/2/2026.

Tại sao làm việc này?

Tôi muốn có một cách để nhanh chóng nắm bắt xu hướng chính trị qua các tuần mà không cần đọc từng bài. Câu hỏi đặt ra: Tuần này Tuổi Trẻ đang viết nhiều nhất về gì? Topic nào vừa bùng nổ?

Thay vì đọc thủ công, tôi xây pipeline:

1. Crawl toàn bộ bài báo → SQLite
2. TF-IDF vectorize → K-Means cluster thành 20 topic
3. Vẽ heatmap, timeline, entity tracking

Architecture: Bypass IP Block bằng chromedp

Vấn đề đầu tiên: Tuổi Trẻ block comment API với server IP (cookie __stat="BLOCK"). Giải pháp: dùng Chrome DevTools Protocol để chạy fetch() bên trong browser thật — browser dùng cookies thật của mình, bypass hoàn toàn.

// chromedp: chạy JS fetch() trong browser session thật
js := fmt.Sprintf(`
  (async () => {
    const resp = await fetch(
      "https://id.tuoitre.vn/api/getlist-comment.api?appKey=%s&objectId=%s&...",
      { credentials: "include" }  // dùng cookies của browser
    );
    return JSON.stringify(await resp.json());
  })()
`, appKey, objectID)

var result interface{}
chromedp.Run(ctx, chromedp.Evaluate(js, &result, chromedp.EvalAsValue))

Trick quan trọng: chromedp.Evaluate với interface{} thay vì string để handle cả khi API trả về JSON object trực tiếp thay vì string-wrapped.

Tốc độ: HTTP parallel + Browser chỉ cho comments

Kiến trúc cuối cùng:

Kết quả: 37,100 articles/giờ (so với ~140/giờ khi dùng Chrome navigate cho tất cả).

Pagination API

Tuổi Trẻ dùng format ít tài liệu hóa:

• Page 1: https://tuoitre.vn/{section}.htm
• Page 2+: https://tuoitre.vn/timeline/{cateId}/trang-{page}.htm

Tìm được bằng cách intercept network requests qua CDP khi scroll trang.

Dataset: 16,825 bài, 11 chuyên mục

the-gioi:    1,995 bài  | giai-tri:   1,975 bài
thoi-su:     1,937 bài  | van-hoa:    1,936 bài
phap-luat:   1,899 bài  | nhip-song-tre: 1,890 bài
suc-khoe:    1,774 bài  | giao-duc:   1,768 bài
kinh-doanh:  1,571 bài  | chinh-tri:     78 bài

Phạm vi: 2025-01-01 đến 2026-03-18

TF-IDF + K-Means: 20 Topic Clusters

Dùng scikit-learn với bigrams:

vectorizer = TfidfVectorizer(
    max_features=5000,
    ngram_range=(1, 2),      # unigrams + bigrams
    min_df=3, max_df=0.7,    # lọc quá hiếm và quá phổ biến
    stop_words=STOPWORDS_VI,
    sublinear_tf=True,        # log normalization
)
X = vectorizer.fit_transform(df['title'] + ' ' + df['sapo'])

km = MiniBatchKMeans(n_clusters=20, random_state=42, n_init=5)
km.fit(X)

20 clusters auto-detected:

Kết quả: Timeline theo tuần

Entity mentions — Chiến sự bùng nổ tuần 2026-02-23

Theo dõi 6 thực thể chính theo tuần:

Cú nhảy từ 19 → 144 mentions/tuần của Iran sau ngày 28/2 rất rõ.

Topic shift: Trước vs Sau chiến sự

So sánh cơ cấu bài viết 7,002 bài trước 28/2 vs 2,689 bài sau:

TĂNG MẠNH:
  +5.9%  🇻🇳 VN Chính trị (Quốc hội khóa XVI)
  +3.8%  ⚔️ Chiến sự Trung Đông
  +1.9%  📈 Tài chính/Chứng khoán
  +1.2%  🚗 Giao thông

GIẢM MẠNH:
  -0.8%  👮 Công an/Pháp luật  
  -2.6%  🌡️ Đời sống/Xã hội
  -9.5%  🎋 Tết Bính Ngọ (đương nhiên!)

Weekly digest — Mỗi tuần có gì?

Một vài tuần đáng chú ý:

📅 Tuần 2026-02-09 (trước chiến sự):

• 🎋 Tết Bính Ngọ (196 bài) — tuần cao điểm Tết
• 🌡️ Đời sống (146 bài)

📅 Tuần 2026-02-23 (chiến sự bắt đầu):

• 🌡️ Đời sống (177 bài)
• ⚔️ Chiến sự: “Dân Iran được kêu gọi ‘rời thủ đô’, dân Israel ‘bình thản’”
• 👮 Pháp luật: “Cựu Bộ trưởng Nguyễn Thị Kim Tiến được đưa 20,4 tỉ…”

📅 Tuần 2026-03-02 (chiến sự leo thang):

• 🌡️ Đời sống (171 bài)
• 🇻🇳 VN Chính trị (126 bài) — “Chủ tịch Quốc hội: Kỳ họp thứ nhất Quốc hội khóa XVI…”
• ⚔️ Chiến sự (122 bài): “Sáng nay Israel không kích mạnh vào Tehran…”

Interactive Charts

Tất cả charts interactive (Plotly) ở đây:

• 🗺️ Heatmap: Topic × Tuần 2025-2026
• 🌍 Entity Timeline: Iran/Israel/Mỹ/Nga theo tuần
• 📊 Topic Shift: Trước/Sau chiến sự 28/2
• 📅 Weekly Digest HTML

Code

GitHub: tuoitre-crawler (trong repo này)

Stack:

• Crawler: Go + chromedp (CDP) + net/http
• Analysis: Python + scikit-learn + plotly
• Storage: SQLite

Limitations

1. Comments = 0 — server IP bị block, chỉ lấy được article metadata
2. TF-IDF không hiểu ngữ nghĩa — một số cluster bị mix. Nên thử PhoBERT hoặc multilingual sentence-transformers cho kết quả tốt hơn
3. Chỉ title + sapo — content đầy đủ có nhưng chưa dùng để cluster (quá nhiều noise)

Phần 2: Gensim LDA — Probabilistic Topic Modeling

Sau khi có kết quả từ TF-IDF K-Means, mình apply thêm Latent Dirichlet Allocation (LDA) từ Gensim để có model probabilistic — mỗi document không bị gán cứng vào 1 cluster mà có phân phối xác suất trên tất cả topics.

Tại sao LDA tốt hơn K-Means cho text?

Chọn số topics bằng Coherence Score

from gensim.models import LdaMulticore
from gensim.models.coherencemodel import CoherenceModel

for k in [10, 15, 20, 25]:
    lda = LdaMulticore(corpus=bow_corpus, id2word=dictionary, 
                       num_topics=k, workers=4, passes=15)
    cm = CoherenceModel(model=lda, texts=docs, coherence='c_v')
    print(f"k={k}: coherence={cm.get_coherence():.4f}")

k=10: coherence=0.4817  ← best
k=15: coherence=0.4726
k=20: coherence=0.4758
k=25: coherence=0.4674

k=10 tối ưu — thêm topics không cải thiện coherence.

10 LDA Topics tìm được

LDA Insights — Chiến sự Iran rõ hơn

Với LDA, topic ⚔️ Chiến sự được phân biệt rõ với 🏛️ Chính trị VN — điều mà K-Means gộp chung do cùng xuất hiện từ “Mỹ”, “tổng thống”. LDA nhận ra:

• Topic 0 → quốc hội, cử, biểu = bầu cử trong nước
• Topic 1 → iran, quân, bay, tàu, chiến = chiến sự quân sự

Topic confidence (avg probability) của ⚔️ Chiến sự tăng vọt từ tuần 2026-02-23, trong khi confidence của 🚗 Giao thông/Tết giảm — người đọc chuyển sang đọc tin chiến sự, tòa soạn follow accordingly.

Interactive LDA Charts

• 🧠 LDA Heatmap: Topic × Tuần
• 🔑 Top Keywords mỗi Topic
• 📈 LDA Timeline 2026
• 🌡️ Topic Confidence theo tuần
• 📊 LDA Topic Shift: Trước/Sau chiến sự

Updated 2026-03-18 với Gensim LDA (k=10, coherence=0.4817)

Phần 3: BERTopic — Neural Topic Modeling với Multilingual BERT

Sau TF-IDF K-Means và Gensim LDA, mình apply BERTopic — phương pháp dùng sentence embeddings thay vì bag-of-words, kết hợp UMAP + HDBSCAN để cluster.

Architecture BERTopic

texts → SentenceTransformer → embeddings (384-dim)
                                    ↓
                               UMAP (5-dim)
                                    ↓
                            HDBSCAN clustering
                                    ↓
                   c-TF-IDF per cluster → topic keywords
                                    ↓
                    MaximalMarginalRelevance (diversity=0.3)

Model dùng: paraphrase-multilingual-MiniLM-L12-v2 — hỗ trợ 50+ ngôn ngữ kể cả tiếng Việt.

So sánh 3 methods

Outlier 34.9%: BERTopic dùng HDBSCAN nên những bài không thuộc cluster nào bị đánh dấu -1. Đây là trade-off của clustering density-based — chỉ giữ lại những pattern rõ ràng.

37 Topics cụ thể từ BERTopic (2026)

Top 20 topics tìm được (với keywords tự động):

Điểm nổi bật của BERTopic so với LDA

1. Topic 1 “iran_trump_ukraine” — LDA gộp chung thành “mỹ

   tổng

   thống”, BERTopic tách riêng nhờ semantic embeddings phân biệt ngữ cảnh chiến sự vs. bầu cử trong nước

2. Topic 11 AI/LLM — LDA không tìm được topic này (too niche), BERTopic tìm được 107 bài về AI
3. Topic 19 Anime — 49 bài cực kỳ specific về Jujutsu Kaisen — không phương pháp nào khác detect được
4. Topic 6 xăng dầu — Tách riêng khỏi kinh tế chung, peak tuần 03-09 khi chiến sự ảnh hưởng giá dầu

Interactive BERTopic Charts

• 🧠 BERTopic Heatmap: Topic × Tuần
• 🗺️ BERTopic UMAP 2D Scatter
• 📊 Method Comparison: 3 methods side-by-side
• ⚔️ Iran/Chiến sự topic theo 3 methods

Kết luận: Nên dùng method nào?

• TF-IDF K-Means: Nhanh, đơn giản, tốt cho prototyping. Dùng khi cần tổng quan nhanh.
• Gensim LDA: Probabilistic, có coherence score để tune. Tốt khi muốn soft assignment và interpretable.
• BERTopic: Tốt nhất cho tiếng Việt vì dùng multilingual embeddings — hiểu ngữ nghĩa thay vì chỉ đếm từ. Trade-off: chậm hơn và có nhiều outliers.

Với 9,691 bài Tuổi Trẻ 2026, BERTopic tìm ra 37 topics granular so với 10-20 topics thô của các method truyền thống.

Pipeline: Go + chromedp → SQLite → Python (scikit-learn + gensim + bertopic) → Plotly

Disclaimer: Bài viết này được viết với mục đích nghiên cứu kỹ thuật. Tất cả các thử nghiệm được thực hiện trên dữ liệu public. Hãy tôn trọng ToS của các nền tảng.

Tôi vừa mất 3 giờ chiến đấu với hệ thống anti-bot của Shopee để crawl danh sách sản phẩm điện thoại. Kết quả: chỉ crawl được ~250 sản phẩm trước khi bị chặn hoàn toàn. Nhưng trong quá trình đó, tôi học được rất nhiều thứ thú vị về cách Shopee bảo vệ platform của họ.

Đây là bài phân tích chi tiết — dành cho những developer muốn hiểu anti-bot hoạt động như thế nào ở cấp độ thực tế.

Bức Tranh Tổng Thể: Shopee Dùng Gì?

Qua quan sát trực tiếp network requests, response patterns và hàng chục lần bị chặn, đây là kiến trúc bảo vệ đầy đủ mà Shopee triển khai:

Một request từ bot phải vượt qua 6 lớp kiểm tra độc lập, mỗi lớp bắt một loại attacker khác nhau:

[Bot Request]
      │
      ▼
[L1] TLS Fingerprint ──── JA3/JA4 hash mismatch → BLOCK
      │ pass
      ▼
[L2] IP Reputation ──────  Datacenter/TOR/proxy AS → BLOCK
      │ pass
      ▼
[L3] Browser Fingerprint ─ Canvas hash, WebGL → BLOCK
      │ pass
      ▼
[L4] Behavioral Analysis ─ Mouse entropy, scroll timing → CAPTCHA
      │ pass
      ▼
[L5] Session Token ──────  SPC_EC server-side revoke → BLOCK
      │ pass
      ▼
[L6] Correlation ID ─────  Honeypot tracking_id → PERMANENT BAN
      │ pass
      ▼
[Response] ✓

Không có layer nào là “magic bullet” — chính sự kết hợp 6 signals đồng thời mới tạo nên độ khó thực sự. Bypass một layer không đủ nếu các layer còn lại vẫn fire.

Vì sao khó bypass đến vậy?

Mỗi layer được thiết kế để fail independently — tức là nếu layer 2 (IP) pass nhưng layer 4 (behavior) fail, request vẫn bị block. Không có “shortcut” nào bypass toàn bộ stack chỉ bằng một trick đơn lẻ.

Layer 1: TLS Fingerprinting (JA3/JA4)

Đây là thứ đầu tiên tôi gặp phải và không nhận ra ngay.

Khi một browser connect tới HTTPS server, quá trình TLS handshake tạo ra một fingerprint độc nhất dựa trên:

• Cipher suites được đề xuất (và thứ tự)
• TLS extensions
• Elliptic curves và point formats

Tools như curl, requests (Python), hay Playwright Chromium có JA3 hash khác với real Chrome. Shopee detect điều này ở connection layer — trước khi nhìn vào HTTP headers.

# requests library JA3: 771,4866-4867-4865-...,0-23-65281-...
# real Chrome JA3:      771,4866-4867-4865-...,0-23-65281-... (khác order)

Cách Playwright Firefox thoát được: Firefox có TLS profile khác hoàn toàn với Chromium và giống với real Firefox traffic. Đó là lý do p.firefox.launch() hoạt động còn p.chromium.launch() bị block ngay.

Layer 2: IP Reputation & Rate Limiting

Đây là layer chặn tôi nhiều nhất — và đây là những gì tôi quan sát được:

Signal 1: AS Number Data center IPs (AWS, GCP, DigitalOcean) bị rate-limit cực gắt. Shopee trace AS number của IP và assign “trust score” thấp hơn cho cloud IPs.

Signal 2: Request velocity Phân tích response thực tế cho thấy pattern:

• Request 1-2: OK ✅
• Request 3: verify/captcha ❌

Đây không phải threshold đơn giản — Shopee tracking velocity per IP per time window với sliding window, không phải fixed counter.

Signal 3: Shared IP history Nếu IP đó từng được dùng để spam/scrape trước đây, nó sẽ bị “pre-flagged”. Public proxy lists thường toàn IPs đã bị blacklist.

# Thực tế từ crawl session của tôi:
Page 1: OK (60 products)
Page 2: verify/captcha
↳ Restart browser + re-inject cookies: OK
Page 3: verify/captcha (permanent)
↳ Browser restart: vẫn block

Pattern này cho thấy IP bị “cool down” sau N requests — không phải session-based.

Layer 3: Behavioral Fingerprinting

Layer này tinh vi nhất và khó bypass nhất. Shopee collect các signals sau trong JavaScript:

Mouse Movement Entropy

Real users có mouse movement với Gaussian noise — cursor không bao giờ di chuyển thẳng tuyến tính. Automation tools tạo ra movement patterns quá “đều”:

// Bot: perfect straight line
mousemove(100,100) → mousemove(200,200) → mousemove(300,300)

// Human: có micro-jitter, acceleration/deceleration
mousemove(100,100) → mousemove(143,152) → mousemove(198,201) → ...

Tôi đã implement human_mouse_wiggle() để simulate điều này, nhưng chưa đủ — cần thêm Bezier curves và velocity modeling.

Scroll Pattern

Shopee detect scroll bằng cách measure:

• Time between scroll events
• Delta per event (humans scroll in non-uniform chunks)
• Pause patterns (humans dừng lại để đọc)

# Human-like scroll implementation của tôi:
async def human_scroll(page):
    for scroll_pct in [20, 40, 60, 80, 100]:
        await page.evaluate(f"window.scrollTo()")
        await asyncio.sleep(random.uniform(0.15, 0.45))
        if random.random() < 0.15:  # đọc content
            await asyncio.sleep(random.uniform(0.5, 1.5))

Điều thú vị: behavior: 'smooth' trong JS thực ra giúp bypass detection vì nó tạo ra nhiều intermediate scroll events như human.

Event Timing Distribution

Browser automation thường trigger events với timing quá đều. Real users có timing jitter theo phân phối log-normal:

Bot timing:    [100ms, 100ms, 100ms, 100ms]  ← quá đều
Human timing:  [87ms, 134ms, 92ms, 201ms]    ← log-normal distribution

Layer 4: Session Token Architecture

Đây là discovery thú vị nhất. Shopee dùng 2 loại tokens:

SPC_F — Device fingerprint token, tồn tại lâu dài SPC_EC — Session encryption token, expire nhanh

Khi tôi inspect cookies sau khi bị captcha:

SPC_EC: [encrypted blob, ~256 chars]  ← bị invalidate server-side
SPC_F:  [shorter token]               ← vẫn valid nhưng bị flag

Vấn đề: ngay cả khi re-inject cookies từ real Chrome profile, server đã revoke SPC_EC sau khi detect automation. Re-inject cookies cũ không giúp được gì vì server-side state đã thay đổi.

Đây là kiến trúc stateful session validation — token validity được check ở server, không chỉ ở client.

Layer 5: Canvas & WebGL Fingerprinting

Shopee run JavaScript để lấy canvas fingerprint:

// Shopee's fingerprinting code (deobfuscated pattern)
var canvas = document.createElement('canvas');
var ctx = canvas.getContext('2d');
ctx.fillText('Shopee fingerprint', 10, 10);
var hash = canvas.toDataURL(); // unique per GPU/driver/OS

Playwright Chromium headless có một known canvas fingerprint mà Shopee đã blacklist. Firefox có fingerprint khác — đó là lý do Firefox hoạt động ban đầu.

Tuy nhiên, sau vài requests, behavioral signals (mouse, scroll, timing) override cả canvas fingerprint.

Layer 6: The Honeypot — verify/traffic/error

URL này rất thú vị:

https://shopee.vn/verify/traffic/error?
  home_url=https://shopee.vn
  &is_logged_in=false
  &tracking_id=676960ddb3-5467-4771-a88e-230f1195c66d

tracking_id là một correlation ID — Shopee dùng nó để link request này với toàn bộ session history của IP/fingerprint combination. Một khi bị assign tracking_id này, mọi request tiếp theo từ IP đó đều bị route qua verification flow, bất kể browser hay cookies.

Cái Gì Thực Sự Hoạt Động

Từ quá trình thử nghiệm, đây là ranking của các techniques:

Pattern thực tế: Shopee cho phép ~1-3 pages per IP per time window trước khi captcha. Với residential proxy rotation (mỗi request/IP khác nhau), bạn bypass được layer IP hoàn toàn.

Architecture Của Một Crawler Thực Sự Bypass Được

Nếu phải thiết kế lại từ đầu, đây là architecture tôi sẽ dùng:

┌─────────────────────────────────────────────────┐
│                  Crawler Core                    │
│                                                  │
│  Playwright Firefox (TLS fingerprint ✅)         │
│       + Real Chrome Cookies (session ✅)         │
│       + Human Behavior Engine (behavioral ✅)   │
│                    │                             │
│                    ▼                             │
│         Residential Proxy Rotator               │
│    (new IP per page, ISP-grade trust ✅)        │
│                    │                             │
│                    ▼                             │
│              Shopee.vn ✅                        │
└─────────────────────────────────────────────────┘

Human Behavior Engine cần implement:

1. Bezier curve mouse movement — không phải random wiggle
2. Log-normal timing distribution cho keyboard/click events
3. Realistic scroll with reading pauses — dừng lại ở product cards
4. Random viewport interactions — hover qua filters, không chỉ scroll thẳng

Lesson Learned: Shopee Không Chỉ Detect Bot, Họ Detect Patterns

Điều tôi nhận ra sau cùng: Shopee không nhìn vào từng request riêng lẻ. Họ build behavioral profile theo thời gian:

• Session mở lúc nào?
• Có xem trang chủ trước không?
• Click vào category hay vào thẳng URL?
• Dừng lại bao lâu ở mỗi trang?
• Có interact với search/filter không?

Real users không mở thẳng ?page=5&sortBy=pop. Họ vào trang chủ, search, filter, rồi mới pagination. Một crawler “hoàn hảo” phải simulate toàn bộ user journey, không chỉ từng request.

Hành Trình Thất Bại Hoàn Toàn (Ghi Chép Thực Tế)

Đây là phần tôi muốn viết rõ nhất — vì hầu hết blog tech chỉ show success story. Đây là timeline thất bại theo thứ tự:

Attempt 1: Go + go-rod (Chromium)

Result: Redirect ngay → /verify/traffic/error
Time to fail: ~3 giây
Reason: Chromium fingerprint bị blacklist

Attempt 2: Go + go-rod + stealth (Chromium)

Result: Vẫn bị /verify/traffic/error
Time to fail: ~3 giây  
Reason: Stealth mode không đủ che TLS fingerprint của Chromium

Attempt 3: Chrome profile thật (copy cookies)

Result: login page — cookies không decrypt được
Time to fail: ~5 giây
Reason: Chrome encrypt cookies bằng OS keyring, copy raw file ra không dùng được

Attempt 4: Playwright Chromium + stealth

Result: /verify/captcha
Time to fail: ~8 giây
Reason: Chromium headless fingerprint đã bị blacklist

Attempt 5: Playwright Firefox + Chrome cookies (pycookiecheat) ← BREAKTHROUGH

Result: ✅ 60 items page 1!
Pages crawled: 1 → captcha
Reason: Firefox TLS profile khác, pycookiecheat decrypt được cookies

Attempt 6: Human behavior simulation

# Tôi implement:
async def human_scroll(page):          # smooth scroll với random pauses
async def human_mouse_wiggle(page):    # random mouse movement
# + delay 20-40s giữa các trang
# + quay lại homepage giữa các page

Result: Vẫn captcha sau 1-2 trang
Pages crawled: 2 → captcha
Reason: Behavior delay tốt nhưng IP reputation vẫn bị flag

Attempt 7: Browser restart + re-inject cookies

Result: 1 lần recover, lần 2 permanent block
Reason: Server đã revoke SPC_EC token, inject lại vô nghĩa

Attempt 8: ScraperAPI (free plan)

Result: "requires Ultra Premium proxies" — paid plan only
Cost: Free plan không work với Shopee

Attempt 9: Free proxy lists (220 proxies)

Result: 3/220 pass basic test, 0/3 pass Shopee
Reason: Tất cả public proxy IPs đã bị Shopee pre-blacklist

Attempt 10: TOR (5 different exit nodes)

IPs tried:
- 38.135.24.72   → /verify/traffic ❌
- 185.62.56.249  → /verify/captcha ❌  
- 192.42.116.46  → /verify/captcha ❌
- 192.42.116.93  → /verify/captcha ❌
- 192.159.99.27  → /verify/traffic ❌

Result: 5/5 bị block
Reason: Shopee maintain danh sách TOR exit nodes và blacklist toàn bộ

Tổng kết sau ~5 giờ chiến đấu:

Attempts:  10
Success:   1 (Firefox + cookies, ~1 trang)
Products:  251 / ~6,000 (4%)
Proxies:   220+ tested, 0 work
Cost:      $0 (free tier only)

Điều Thực Sự Cần Để Bypass

Sau tất cả những thử nghiệm trên, đây là điều kiện cần (không phải đủ) để crawl Shopee ở scale:

1. Residential proxy — không phải datacenter, không phải TOR, không phải public proxy. Phải là IP từ ISP thật của người dùng (Viettel, VNPT, FPT…). Chi phí: ~$15-50/tháng cho rotating residential.

2. Real browser fingerprint — Firefox hoặc Chrome built bằng Playwright với đầy đủ GPU/canvas rendering (không phải headless hoặc virtual display). Chạy trên máy thật hoặc cloud VM có GPU.

3. Session warming — không jump thẳng vào category page. Phải simulate user journey: trang chủ → search → filter → browse → pagination.

4. Cookie refresh — SPC_EC token expire nhanh. Cần mechanism tự động login lại và lấy token mới thay vì reuse token cũ.

Nói thẳng: không có giải pháp free nào bypass Shopee ở thời điểm 2026. Shopee đã đầu tư đủ để làm cho ROI của scraper nhỏ lẻ trở nên âm.

Kết Luận

Shopee đã đầu tư nghiêm túc vào anti-bot — đây là hệ thống multi-layer với từng layer bắt một loại attacker khác nhau:

• Script kiddies → bị chặn bởi TLS fingerprint
• Basic Selenium/Playwright → bị chặn bởi canvas fingerprint + IP reputation
• Sophisticated bots → bị chặn bởi behavioral analysis
• TOR / free proxies → bị chặn bởi IP reputation blacklist (pre-emptive)
• Residential proxies → bypass được IP layer, nhưng còn behavioral + session analysis

Hệ thống này không “unhackable” — nhưng chi phí để bypass nó đã vượt qua ngưỡng mà hầu hết side projects có thể chịu được. Đó là mục tiêu thực sự: không cần block 100%, chỉ cần làm cho cost > benefit.

Từ góc nhìn defensive, đây là một case study xuất sắc về economic security — bảo mật không phải bằng tường lửa tuyệt đối mà bằng cách tăng chi phí tấn công lên đủ cao. Từ góc nhìn offensive… thất bại cũng là một loại học 🙂

Source code của crawler (Python + Playwright + proxy rotation): github.com/phanngoc/shopee-crawler

Dataset 251 sản phẩm crawl được: kaggle.com/ngocphansun

TL;DR: Tôi crawl 5,207 listings bất động sản Đà Nẵng từ batdongsan.com.vn, chạy EDA toàn diện và rút ra một số insights thú vị: Sơn Trà đắt nhất tính theo m², Ngũ Hành Sơn sôi động nhất về khối lượng giao dịch, và phần lớn thị trường tập trung ở phân khúc 5–15 tỷ. Dataset và notebook đầy đủ trên Kaggle.

Bối Cảnh & Phương Pháp

Đà Nẵng luôn là một trong những thị trường BĐS được theo dõi sát nhất Việt Nam — vừa là thành phố du lịch quốc tế, vừa là hub công nghệ đang phát triển mạnh. Nhưng đọc tin tức thị trường thì được mấy phần thực chất?

Tôi quyết định lấy thẳng từ nguồn: crawl toàn bộ listings đất nền Đà Nẵng trên batdongsan.com.vn bằng Go + go-rod (browser automation với stealth mode), thu về 5,207 listings tính đến ngày 17/03/2026.

Stack sử dụng:

• Crawler: Go 1.21 + go-rod + stealth
• Storage: SQLite
• Analysis: Python + Pandas + Seaborn + Matplotlib
• Publish: Kaggle Datasets + Notebook

📊 Dataset & Notebook: kaggle.com/ngocphansun/da-nang-real-estate-listings

1. Bức Tranh Tổng Quan

Con số đáng chú ý đầu tiên: khoảng cách lớn giữa trung vị (9 tỷ) và trung bình (19.4 tỷ) — dấu hiệu rõ của phân phối lệch phải. Một số lô đất siêu cao (100–582 tỷ) kéo giá trung bình lên đáng kể, trong khi đại đa số giao dịch vẫn nằm ở mức 5–20 tỷ.

2. Quận Nào Sôi Động Nhất?

Ngũ Hành Sơn chiếm gần 30% tổng listings — con số này phản ánh làn sóng phát triển ở khu vực ven biển phía Nam thành phố, đặc biệt quanh Bán đảo Sơn Trà và Non Nước. Khu vực này đang hút rất nhiều nhà đầu tư dài hạn với quỹ đất còn tương đối rộng so với trung tâm.

3. Phân Bổ Giá: Thị Trường Tập Trung Ở Đâu?

Phân khúc giá       Số lượng    Tỷ lệ
─────────────────────────────────────
< 3 tỷ                  283      5.8%
3 – 5 tỷ                697     14.3%
5 – 8 tỷ              1,174     24.1%  ← đông nhất
8 – 10 tỷ               433      8.9%
10 – 15 tỷ              731     15.0%
15 – 20 tỷ              420      8.6%
20 – 30 tỷ              410      8.4%
30 – 50 tỷ              393      8.1%
50 – 100 tỷ             208      4.3%
> 100 tỷ                119      2.4%

Phân khúc 5–8 tỷ là “sweet spot” của thị trường với 24% tổng số listings. Kết hợp với phân khúc 3–5 tỷ, có thể thấy gần 40% listings nằm trong range 3–8 tỷ — đây là phân khúc tầm trung đang được giới đầu tư lướt sóng và ở thực nhắm đến nhiều nhất.

Đáng chú ý, gần 15% listings có giá từ 30 tỷ trở lên — cho thấy phân khúc cao cấp vẫn rất sôi động ở Đà Nẵng, chủ yếu tập trung ở Sơn Trà và Hải Châu.

4. Giá Theo m²: Sơn Trà Đắt Gấp 7 Lần Hòa Vang

Đây là góc nhìn công bằng hơn để so sánh giá trị thực giữa các quận:

Sơn Trà đắt nhất với trung vị 142 tr/m² — đây là hệ quả của vị trí ven biển, mật độ resort/khách sạn cao, và quỹ đất hạn chế do địa hình bán đảo. Hòa Vang rẻ nhất (17.9 tr/m²), nhưng đây là huyện ngoại thành với đất nông nghiệp và đất ở nông thôn, không thể so sánh trực tiếp.

Điều thú vị: Ngũ Hành Sơn có giá trung bình (112 tr/m²) cao hơn nhiều so với trung vị (81 tr/m²) — nghĩa là có một số lô siêu cao giá đang kéo trung bình lên. Phân phối ở đây rất rộng, phản ánh sự đa dạng từ đất nền khu dân cư đến đất mặt tiền biển.

5. Diện Tích: 100m² Là “Standard”

Phân tích diện tích cho thấy thị trường Đà Nẵng khá chuẩn hóa:

• 100 m² là size phổ biến nhất (785 listings, ~15%)
• 90 m² đứng thứ hai (245 listings)
• Hơn 60% listings nằm trong range 80–200 m²

Điều này phản ánh quy hoạch đô thị khá đồng nhất — hầu hết các dự án đất nền ở Đà Nẵng được chia lô theo tiêu chuẩn 5×20m (100m²) hoặc 5×18m (90m²).

6. Độ Tươi Của Data & VIP Tier

94.2% listings được đăng trong 1 tuần trước — đây là điểm mạnh của dữ liệu, phản ánh “nhiệt độ” thực của thị trường tại thời điểm crawl chứ không phải tồn đọng cũ.

Về VIP tier (mức độ quảng cáo trả phí):

• Normal (miễn phí): 5,080 listings (97.6%)
• Silver: 96 (1.8%)
• Gold: 21 (0.4%)
• Diamond: 10 (0.2%)

Chỉ ~2.4% listings trả phí để boost — điều này có nghĩa là thị trường BĐS Đà Nẵng vẫn chủ yếu do môi giới/cá nhân đăng tự do, chưa có nhiều chủ đầu tư lớn đổ ngân sách marketing vào nền tảng này.

7. Tương Quan Giá & Diện Tích

Scatter plot và correlation matrix cho thấy:

• Tương quan giá × diện tích: ~0.35 — tương quan dương nhưng không mạnh
• Tương quan giá × giá/m²: ~0.72 — cao hơn nhiều

Kết luận: Vị trí (quận, đường, view) giải thích giá tốt hơn diện tích. Một lô 100m² ở Sơn Trà có thể đắt hơn 5–7 lần so với lô cùng size ở Hòa Vang. Diện tích lớn hơn không nhất thiết tương quan với giá cao hơn theo cách tuyến tính.

8. Key Takeaways Cho Nhà Đầu Tư

🔴 Phân khúc Hot: 5–15 tỷ

Gần 40% tổng listings, liquidity tốt nhất thị trường. Phù hợp cho cả ở thực lẫn đầu tư lướt sóng.

🟡 Cẩn Trọng: Sơn Trà & Hải Châu

Giá/m² cao nhất (>100 tr/m²), nhưng room tăng tiếp có thể hạn chế. Phù hợp cho dài hạn, nắm giữ.

🟢 Tiềm Năng: Ngũ Hành Sơn & Liên Chiểu

• Ngũ Hành Sơn: Thị phần lớn nhất, infrastructure đang phát triển, giá/m² còn chấp nhận được
• Liên Chiểu: Giá thấp nhất trong nội thành (~59 tr/m²), hưởng lợi từ quy hoạch cảng Liên Chiểu

🔵 Cơ Hội Niche: Hòa Vang

Giá đất siêu rẻ (trung vị 17.9 tr/m²), thích hợp cho đầu tư đất nông nghiệp chuyển đổi dài hạn hoặc resort/nghỉ dưỡng.

Hạn Chế & Caveats

Một số điều cần lưu ý khi đọc phân tích này:

1. Giá listing ≠ giá thành công: Đây là giá chào, không phải giá giao dịch thực tế
2. Bias từ nền tảng: batdongsan.com.vn có thể không đại diện cho toàn bộ thị trường (bỏ sót giao dịch qua Facebook, Zalo, môi giới trực tiếp)
3. Snapshot 1 tuần: Dữ liệu phản ánh thời điểm tháng 3/2026, không track được trend theo thời gian
4. Geocoding thô: Phân loại quận dựa trên text, có thể có sai sót nhỏ

Kết Luận

Với 5,207 listings trong tay, bức tranh thị trường BĐS Đà Nẵng đầu 2026 khá rõ nét: thị trường đang sôi động (94% listings mới trong tuần), tập trung ở phân khúc 5–15 tỷ, và Sơn Trà + Hải Châu dẫn đầu về giá trị/m² trong khi Ngũ Hành Sơn dẫn đầu về khối lượng.

Dataset đầy đủ và notebook EDA interactive trên Kaggle — mọi người có thể tự khám phá thêm:

Source code crawler (Go): github.com/phanngoc/bds-pipeline

Bạn có bao giờ cảm thấy mệt mỏi khi phải chuyển đổi giữa ChatGPT, Claude, các ứng dụng messaging, email, và vô số công cụ khác? Hay lo ngại về việc dữ liệu cá nhân bị gửi đến các server cloud mà bạn không kiểm soát được?

Đó chính là lý do ra đời của Personal AI Assistant — một hệ thống AI chạy trên thiết bị của bạn, kết nối với tất cả các kênh giao tiếp bạn sử dụng hàng ngày.

Trong bài viết này, tôi sẽ phân tích sâu ba dự án open-source đang làm mưa làm gió trong cộng đồng: OpenClaw, nanobot, và PicoClaw. Ba dự án này đại diện cho ba triết lý thiết kế hoàn toàn khác nhau — từ “feature-rich” đến “ultra-minimal”.

🦞 OpenClaw: Con Tôm Hùm Full-Stack

“EXFOLIATE! EXFOLIATE!” — Slogan của OpenClaw

Tổng Quan

OpenClaw là dự án “heavyweight” nhất trong ba — một full-featured personal AI assistant với hơn 430,000 dòng code TypeScript. Đây không chỉ là chatbot, mà là một platform hoàn chỉnh.

Kiến Trúc

WhatsApp / Telegram / Slack / Discord / Signal / iMessage / ...
                     │
                     ▼
          ┌─────────────────────┐
          │      Gateway        │
          │   (Control Plane)   │
          │  ws://127.0.0.1     │
          └─────────┬───────────┘
                    │
          ┌─────────┼─────────┐
          │         │         │
          ▼         ▼         ▼
       Pi Agent   CLI    macOS/iOS App
       (RPC)            (Canvas, Voice)

Core Components:

1. Gateway WebSocket Server: Control plane duy nhất quản lý tất cả sessions, channels, tools và events
2. Multi-Channel Support: WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage (BlueBubbles), Microsoft Teams, Matrix, Zalo, WebChat…
3. Companion Apps: Native apps cho macOS, iOS, Android
4. Voice Wake + Talk Mode: Always-on speech với ElevenLabs TTS
5. Live Canvas: Agent-driven visual workspace
6. Browser Control: Tích hợp Playwright/CDP để điều khiển browser

Điểm Mạnh

• ✅ Feature Completeness: Hầu như mọi thứ bạn cần đều có sẵn
• ✅ Enterprise-Ready: Security policies, DM pairing, allowlists
• ✅ Rich Ecosystem: Skills platform, browser automation, cron jobs
• ✅ Multi-Agent Routing: Có thể route requests đến các agents khác nhau

Trade-offs

• ⚠️ Footprint Lớn: >1GB RAM, startup time dài
• ⚠️ Complexity: 430K+ lines code → học curve cao
• ⚠️ Hardware Requirements: Cần Mac Mini hoặc máy Linux tương đối mạnh

🐈 nanobot: Chú Mèo Nhỏ Nhưng Có Võ

“Ultra-lightweight: 99% smaller than Clawdbot”

Tổng Quan

nanobot ra đời từ câu hỏi: “Liệu chúng ta có thể giữ lại 80% functionality với 1% code?”

Được phát triển bởi HKUDS (HKU Data Science), nanobot chỉ có ~4,000 dòng code Python — đúng là 99% nhỏ hơn OpenClaw!

Kiến Trúc

┌─────────────────────────────────────────┐
│               nanobot                    │
├─────────────────────────────────────────┤
│  Providers   │  Channels   │   Tools    │
│  ──────────  │  ─────────  │  ───────   │
│  OpenRouter  │  Telegram   │  Web Search│
│  Anthropic   │  Discord    │  Code Exec │
│  OpenAI      │  WhatsApp   │  Memory    │
│  DeepSeek    │  Feishu     │  Schedule  │
│  Groq        │  Slack      │            │
│  vLLM        │  Email      │            │
│  Gemini      │  QQ         │            │
│  Zhipu       │  DingTalk   │            │
└─────────────────────────────────────────┘

Design Philosophy

nanobot áp dụng Provider Registry Pattern — thêm một LLM provider mới chỉ cần 2 bước:

# Step 1: Add to registry
ProviderSpec(
    name="myprovider",
    keywords=("myprovider", "mymodel"),
    env_key="MYPROVIDER_API_KEY",
    litellm_prefix="myprovider",
)

# Step 2: Add to config schema
class ProvidersConfig(BaseModel):
    myprovider: ProviderConfig = ProviderConfig()

Không còn if-elif chains rối rắm!

Điểm Mạnh

• ✅ Research-Ready: Code sạch, dễ đọc, dễ modify
• ✅ Fast Iteration: Startup nhanh, modify nhanh, test nhanh
• ✅ Local LLM Support: vLLM integration cho self-hosted models
• ✅ China-Friendly: Support Zhipu, Moonshot, Qwen, Feishu, DingTalk, QQ

Trade-offs

• ⚠️ Python Dependencies: Vẫn cần pip/uv, có thể conflict
• ⚠️ Memory: >100MB RAM
• ⚠️ Fewer Features: Không có Voice Wake, Canvas, Browser Control

🦐 PicoClaw: Con Tôm Tích Chạy Trên $10 Hardware

“皮皮虾，我们走！” (Let’s go, mantis shrimp!)

Tổng Quan

PicoClaw đẩy giới hạn đến mức cực đoan: chạy AI assistant trên hardware chỉ $10 với <10MB RAM!

Được viết bằng Go và phát triển qua quá trình AI-bootstrapping — 95% code được generate bởi chính AI agent!

So Sánh Đáng Kinh Ngạc

Kiến Trúc

PicoClaw tận dụng đặc tính của Go:

• Single Binary: Compile một lần, chạy everywhere (RISC-V, ARM, x86)
• No Runtime Dependencies: Không cần Python, Node.js, hay bất cứ gì khác
• Minimal Memory: Go’s efficient garbage collector

// Một binary duy nhất, cross-compile cho mọi platform
make build-all  // → picoclaw-linux-amd64
                //    picoclaw-linux-arm64
                //    picoclaw-linux-riscv64

Use Cases Độc Đáo

PicoClaw mở ra những khả năng mà trước đây không thể:

1. $9.9 LicheeRV-Nano: Biến board RISC-V $10 thành Home Assistant
2. $30-100 NanoKVM: Automated Server Maintenance
3. $50-100 MaixCAM: Smart Monitoring với AI Vision

Điểm Mạnh

• ✅ True Portability: Một binary chạy mọi nơi
• ✅ Instant Startup: 1 giây boot, không chờ đợi
• ✅ Edge Deployment: Chạy trên IoT devices
• ✅ AI-Generated: 95% code do AI viết, dễ maintain

Trade-offs

• ⚠️ Limited Channels: Chỉ Telegram và Discord (currently)
• ⚠️ Basic Features: Không có Voice, Canvas, Browser Control
• ⚠️ Go Ecosystem: Ít libraries hơn Python/Node

📊 Deep Comparison: Chọn Cái Nào?

Bảng So Sánh Toàn Diện

Khi Nào Chọn Gì?

Chọn OpenClaw khi:

• Bạn cần full ecosystem với voice, canvas, browser control
• Bạn muốn native apps cho macOS/iOS/Android
• Bạn cần enterprise-grade security (DM policies, pairing)
• Bạn có hardware mạnh (Mac Mini, Linux server)
• Bạn cần support nhiều channels (đặc biệt iMessage, Signal)

Chọn nanobot khi:

• Bạn đang research/experiment và cần code dễ đọc
• Bạn muốn modify/extend core functionality
• Bạn cần local LLM support (vLLM)
• Bạn ở China và cần Feishu, QQ, DingTalk
• Bạn muốn fast iteration cycle

Chọn PicoClaw khi:

• Bạn cần chạy trên IoT/edge devices ($10-50)
• Bạn cần instant startup (<1s)
• Bạn muốn single binary deployment
• Memory là constraint (<10MB available)
• Bạn thích Go và muốn contribute

🧬 The Evolution Tree

             OpenClaw (2024)
             ───────────────
             Full-featured, 430K LOC
             TypeScript, >1GB RAM
                    │
                    │ "Can we do 80% with 1%?"
                    ▼
             nanobot (2026)
             ───────────────
             Ultra-light, 4K LOC
             Python, >100MB RAM
                    │
                    │ "Can we run on $10 hardware?"
                    ▼
             PicoClaw (2026)
             ───────────────
             Edge-ready, 2K LOC
             Go, <10MB RAM

Đây là một ví dụ tuyệt vời về evolutionary design: mỗi thế hệ học từ thế hệ trước, tập trung vào một góc cạnh khác nhau của vấn đề.

🔮 Tương Lai

Convergence hay Divergence?

Tôi dự đoán ba dự án này sẽ diverge thay vì converge:

1. OpenClaw sẽ tiếp tục thêm features, trở thành “macOS of AI assistants”
2. nanobot sẽ focus vào research community và local LLM integration
3. PicoClaw sẽ mở rộng vào embedded systems và IoT

What’s Next?

• Federated Learning: Học từ nhiều devices mà không share raw data
• On-Device LLMs: Khi Llama 4 1B đủ mạnh để chạy on-edge
• Hardware Acceleration: RISC-V AI extensions cho PicoClaw
• Protocol Standardization: Có thể sẽ có chuẩn chung cho personal AI assistants

💡 Kết Luận

Cả ba dự án đều có chỗ đứng riêng trong ecosystem personal AI:

Không có “best” choice — chỉ có right choice cho use case của bạn.

Nếu bạn đang bắt đầu và có Mac, hãy thử OpenClaw. Nếu bạn muốn hack và learn, hãy đọc nanobot code. Nếu bạn có một con Raspberry Pi Zero hoặc ESP32 nằm không, hãy thử PicoClaw.

📚 References

• OpenClaw GitHub
• OpenClaw Docs
• nanobot GitHub
• PicoClaw GitHub
• LicheeRV-Nano - $9.9 RISC-V Board

Bạn đang dùng AI assistant nào? Hãy chia sẻ experience của bạn trong comments! 🚀

Bài viết phân tích chuyên sâu kiến trúc Memory Search của OpenClaw – hệ thống kết hợp Vector Search (semantic) và Full-Text Search (BM25) để tạo ra một bộ nhớ dài hạn thông minh cho AI agent. Dành cho developer muốn hiểu cách xây dựng Retrieval-Augmented Generation (RAG) system trong thực tế production.

Mục lục

1. Vấn đề cần giải quyết
2. Kiến trúc tổng quan
3. Giai đoạn 0: Ingestion Pipeline
4. Giai đoạn 1: Dual Search – Vector + FTS
5. Giai đoạn 2: Score Fusion – Weighted Sum
6. Giai đoạn 3: Post-Processing
7. SQLite Schema – Ba bảng, hai virtual table
8. Embedding Provider System
9. Sync Lifecycle & Atomic Reindex
10. Session Memory & Pre-Compaction Flush
11. Fallback Architecture
12. Sơ đồ kiến trúc hoàn chỉnh
13. Lessons Learned & Trade-offs

1. Vấn đề cần giải quyết

AI agent xử lý conversation trong context window có giới hạn. Khi conversation kéo dài, các thông tin quan trọng bị mất do compaction. Memory system giải quyết bài toán này: duy trì kiến thức dài hạn bằng cách lưu thông tin ra file Markdown, rồi tìm kiếm lại khi cần.

Nhưng “tìm kiếm” không đơn giản. Có hai kiểu tìm kiếm bổ sung cho nhau:

• Semantic search (vector): “Tìm nội dung liên quan đến thanh toán” – hiểu nghĩa, không cần match chính xác từ.
• Keyword search (FTS): “payment_processor” – match chính xác tên biến, tên hàm, thuật ngữ kỹ thuật.

Mỗi kiểu có điểm mạnh riêng. Hybrid search kết hợp cả hai.

2. Kiến trúc tổng quan

Toàn bộ hệ thống Memory nằm trong src/memory/ với khoảng 40 file TypeScript. Entry point là MemoryIndexManager – một singleton per-agent, cached theo key agentId:workspaceDir:settingsHash.

                    ┌──────────────────────────────┐
                    │     MemoryIndexManager        │
                    │  (singleton per agent config) │
                    └──────────┬───────────────────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                │
    ┌─────────▼──────┐  ┌─────▼──────┐  ┌──────▼───────┐
    │  Ingestion      │  │   Search    │  │  Lifecycle   │
    │  Pipeline       │  │   Engine    │  │  Management  │
    │                 │  │             │  │              │
    │ - File watcher  │  │ - Vector    │  │ - Sync       │
    │ - Chunking      │  │ - FTS/BM25  │  │ - Reindex    │
    │ - Embedding     │  │ - Fusion    │  │ - Flush      │
    │ - Caching       │  │ - Filtering │  │ - Cleanup    │
    └─────────────────┘  └────────────┘  └──────────────┘
              │                │                │
              └────────────────┼────────────────┘
                               │
                    ┌──────────▼───────────────┐
                    │     SQLite Database       │
                    │                           │
                    │ tables: meta, files,      │
                    │         chunks,           │
                    │         embedding_cache   │
                    │ virtual: chunks_fts (FTS5)│
                    │          chunks_vec (vec0)│
                    └───────────────────────────┘

3. Giai đoạn 0: Ingestion Pipeline

Trước khi search được, dữ liệu phải được ingest vào database. Đây là pipeline đầy đủ:

3.1 Thu thập file nguồn

listMemoryFiles(workspaceDir)
    │
    ├── MEMORY.md          (workspace root)
    ├── memory.md          (alternative)
    ├── memory/**/*.md     (recursive walk)
    └── extraPaths (config) (absolute or relative)

    Filter: chỉ .md, bỏ qua symlinks
    Dedup: theo realpath

Hệ thống cũng index session transcripts – file .jsonl chứa lịch sử conversation, nằm tại ~/.openclaw/agents/<agentId>/sessions/.

3.2 Chunking: Chia văn bản thành đoạn

File internal.ts – hàm chunkMarkdown():

// Default config
chunking: {
  tokens: 400,    // target chunk size
  overlap: 80     // overlap giữa 2 chunk liên tiếp
}

Thuật toán:

1. Quy đổi token → char: maxChars = tokens * 4 = 1600 chars, overlapChars = overlap * 4 = 320 chars
2. Duyệt từng dòng, tích lũy vào buffer hiện tại
3. Khi buffer vượt maxChars → flush thành 1 chunk
4. Sau flush, giữ lại các dòng cuối (tổng ≤ overlapChars) làm overlap cho chunk tiếp theo
5. Dòng quá dài → cắt thành segments maxChars ký tự

Mỗi chunk lưu: startLine, endLine, text, hash (SHA-256 của text).

Tại sao overlap? Để tránh mất ngữ cảnh ở biên chunk. Nếu một ý nằm trải qua ranh giới giữa 2 chunk, overlap đảm bảo nó xuất hiện đầy đủ ở ít nhất 1 chunk.

3.3 Embedding: Chuyển text → vector

Mỗi chunk text được gửi qua embedding provider để tạo vector số thực:

"Lỗi xử lý thanh toán khi amount = 0"
        │
        ▼
  Embedding API (OpenAI / Gemini / Voyage / Local)
        │
        ▼
  [0.012, -0.034, 0.089, ..., 0.001]  ← N chiều (thay đổi theo model)
        │
        ▼
  sanitizeAndNormalizeEmbedding()
    - NaN/Infinity → 0
    - L2 normalize to unit length

Embedding cache: Trước khi gọi API, hệ thống kiểm tra bảng embedding_cache theo key (provider, model, provider_key, hash). Nếu text không đổi (cùng SHA-256 hash) và cùng provider config → dùng lại embedding cũ, tiết kiệm API call.

3.4 Lưu trữ

Mỗi chunk được lưu vào 3 nơi đồng thời:

1. chunks table     ← text + JSON embedding + metadata
2. chunks_vec       ← Float32Array blob (cho sqlite-vec vector search)
3. chunks_fts       ← text (cho FTS5 keyword search)

4. Giai đoạn 1: Dual Search – Vector + FTS

Khi user query đến, hai search engine chạy song song:

4.1 Vector Search (Semantic)

File manager-search.ts – hàm searchVector():

User Query: "Lỗi logic code xử lý thanh toán"
    │
    ▼
embedQuery(text)  ← cùng embedding provider đã dùng lúc index
    │
    ▼
queryVec: [0.023, -0.045, ...]
    │
    ▼
┌─ Path A: sqlite-vec available ──────────────────────────┐
│  SQL:                                                     │
│  SELECT c.*, vec_distance_cosine(v.embedding, ?) AS dist │
│  FROM chunks_vec v JOIN chunks c ON c.id = v.id          │
│  WHERE c.model = ?                                        │
│  ORDER BY dist ASC  LIMIT ?                               │
│                                                           │
│  score = 1 - dist  (cosine distance → similarity)        │
└──────────────────────────────────────────────────────────┘
    │
    │ (fallback nếu sqlite-vec không load được)
    ▼
┌─ Path B: JS fallback ───────────────────────────────────┐
│  Load ALL chunks from DB                                  │
│  Parse JSON embeddings                                    │
│  Compute cosineSimilarity() in JavaScript                │
│  Sort + take top-N                                        │
│  (chậm nhưng luôn hoạt động)                             │
└──────────────────────────────────────────────────────────┘

Cosine Similarity đo sự tương đồng về ngữ nghĩa giữa hai vector:

// internal.ts
function cosineSimilarity(a: number[], b: number[]): number {
  // dot(a,b) / (||a|| * ||b||)
  // Range: -1 (opposite) to 1 (identical)
  // Do vectors đã L2-normalized nên dot product = cosine similarity
}

4.2 Keyword Search (FTS/BM25)

File hybrid.ts – hàm buildFtsQuery() + file manager-search.ts – hàm searchKeyword():

Bước 1: Tokenization (đơn giản)

// hybrid.ts
function buildFtsQuery(raw: string): string | null {
  const tokens = raw.match(/[A-Za-z0-9_]+/g);  // regex, không phải NLP tokenizer
  const quoted = tokens.map(t => `"${t}"`);
  return quoted.join(" AND ");
}

// Input:  "Lỗi logic code xử lý thanh toán"
// Output: "logic" AND "code" AND "thanh" AND "to" AND "n"
// (Lưu ý: regex chỉ lấy [A-Za-z0-9_], Unicode chars bị loại)

Bước 2: FTS5 BM25 query

SELECT id, path, source, start_line, end_line, text,
       bm25(chunks_fts) AS rank
  FROM chunks_fts
 WHERE chunks_fts MATCH '"logic" AND "code"'
   AND model = ?
 ORDER BY rank ASC    -- BM25: lower = better match
 LIMIT ?

Bước 3: Rank → Score normalization

// hybrid.ts
function bm25RankToScore(rank: number): number {
  const normalized = Number.isFinite(rank) ? Math.max(0, rank) : 999;
  return 1 / (1 + normalized);
  // rank=0 → score=1.0 (best)
  // rank=1 → score=0.5
  // rank=9 → score=0.1
  // Asymptotically approaches 0
}

4.3 Candidate Pool

Cả hai search đều fetch nhiều hơn số kết quả cần thiết:

candidateMultiplier = 4  (default)
maxResults = 6           (default)

→ Mỗi search engine fetch: min(200, max(1, 6 * 4)) = 24 candidates

Mục đích: tạo pool đủ lớn để fusion algorithm có “nguyên liệu” chất lượng.

5. Giai đoạn 2: Score Fusion – Weighted Sum

File hybrid.ts – hàm mergeHybridResults():

Quan trọng: Đây là Weighted Sum, KHÔNG PHẢI Reciprocal Rank Fusion (RRF).

Vector Results:  [{id: "c1", vectorScore: 0.92}, {id: "c2", vectorScore: 0.85}, ...]
Keyword Results: [{id: "c2", textScore: 0.78}, {id: "c5", textScore: 0.65}, ...]
                          │
                          ▼
              ┌───────────────────────┐
              │   Merge by chunk ID   │
              └───────────┬───────────┘
                          │
        ┌─────────────────┼─────────────────┐
        │                 │                 │
  id="c1"           id="c2"           id="c5"
  vec=0.92          vec=0.85          vec=0.00  ← chỉ có keyword
  text=0.00         text=0.78         text=0.65
  (chỉ có vector)   (có cả hai)
        │                 │                 │
        ▼                 ▼                 ▼
  score = 0.7*0.92   0.7*0.85          0.7*0.00
        + 0.3*0.00   + 0.3*0.78        + 0.3*0.65
        = 0.644      = 0.829           = 0.195

Thuật toán chi tiết:

function mergeHybridResults({ vector, keyword, vectorWeight, textWeight }) {
  const byId = new Map();

  // 1. Insert tất cả vector results, textScore = 0
  for (const r of vector) {
    byId.set(r.id, { ...r, vectorScore: r.vectorScore, textScore: 0 });
  }

  // 2. Merge keyword results
  for (const r of keyword) {
    const existing = byId.get(r.id);
    if (existing) {
      existing.textScore = r.textScore;  // ← chunk có cả 2 signals
    } else {
      byId.set(r.id, { ...r, vectorScore: 0, textScore: r.textScore });
    }
  }

  // 3. Compute final score
  return Array.from(byId.values())
    .map(entry => ({
      ...entry,
      score: vectorWeight * entry.vectorScore + textWeight * entry.textScore
    }))
    .toSorted((a, b) => b.score - a.score);  // descending
}

Tại sao Weighted Sum mà không phải RRF?

Project docs thừa nhận: “This is not IR-theory perfect. RRF or score normalization would be potential future improvements.” Weighted Sum đơn giản, nhanh, dễ debug, và đủ tốt cho use case memory recall. Trade-off có ý thức.

Phân tích ưu/nhược

Trong context này, cả vectorScore (cosine similarity, range 0-1) và textScore (BM25 normalized, range 0-1) đã được normalize về cùng range, nên Weighted Sum hoạt động ổn.

6. Giai đoạn 3: Post-Processing

Sau fusion, kết quả đi qua 2 bộ lọc:

Merged results (sorted by score descending)
    │
    ▼
Filter: score >= minScore (default: 0.35)
    │
    ▼
Limit: top maxResults (default: 6)
    │
    ▼
Truncate snippet: max 700 chars (SNIPPET_MAX_CHARS)
    │
    ▼
Return MemorySearchResult[] {
  path, startLine, endLine,
  score (0-1), snippet, source,
  citation? ("path#L5-L20")
}

7. SQLite Schema – Ba bảng, hai virtual table

File memory-schema.ts:

┌──────────────────────────────────────────────────────────┐
│                     SQLite Database                       │
│              (~/.openclaw/memory/{agentId}.sqlite)        │
│                                                           │
│  ┌──────────────────────────────────────────────────┐    │
│  │ meta (key-value store)                           │    │
│  │   key: "memory_index_meta_v1"                    │    │
│  │   value: {model, provider, vectorDims, ...}      │    │
│  └──────────────────────────────────────────────────┘    │
│                                                           │
│  ┌──────────────────────────────────────────────────┐    │
│  │ files (tracks indexed source files)              │    │
│  │   path TEXT PK, source, hash, mtime, size        │    │
│  └──────────────────────────────────────────────────┘    │
│                                                           │
│  ┌──────────────────────────────────────────────────┐    │
│  │ chunks (text + embedding data)                   │    │
│  │   id TEXT PK, path, source, start_line,          │    │
│  │   end_line, hash, model, text,                   │    │
│  │   embedding TEXT (JSON number[]),                 │    │
│  │   updated_at                                      │    │
│  │   INDEX: idx_chunks_path, idx_chunks_source      │    │
│  └──────────────────────────────────────────────────┘    │
│                                                           │
│  ┌──────────────────────────────────────────────────┐    │
│  │ embedding_cache (avoid re-embedding)             │    │
│  │   PK: (provider, model, provider_key, hash)      │    │
│  │   embedding TEXT, dims INT, updated_at            │    │
│  └──────────────────────────────────────────────────┘    │
│                                                           │
│  ┌──────────────────────────────────────────────────┐    │
│  │ chunks_fts (FTS5 virtual table)                  │    │
│  │   text (indexed), id/path/source/model/          │    │
│  │   start_line/end_line (UNINDEXED)                │    │
│  │   ⚠️ Created conditionally, graceful degradation │    │
│  └──────────────────────────────────────────────────┘    │
│                                                           │
│  ┌──────────────────────────────────────────────────┐    │
│  │ chunks_vec (vec0 via sqlite-vec extension)       │    │
│  │   id TEXT PK, embedding FLOAT[N]                 │    │
│  │   N = dims from embedding provider               │    │
│  │   ⚠️ Created lazily when dims known              │    │
│  │   ⚠️ Dropped & recreated if dims change          │    │
│  └──────────────────────────────────────────────────┘    │
│                                                           │
└──────────────────────────────────────────────────────────┘

Key insight: Embedding lưu ở hai nơi: chunks.embedding là JSON string (cho JS fallback), chunks_vec.embedding là Float32Array blob (cho sqlite-vec accelerated search). Redundancy có chủ đích.

8. Embedding Provider System

File embeddings.ts – Hệ thống multi-provider với auto-selection:

Provider Selection (provider = "auto")
    │
    ├── 1. Local (node-llama-cpp + GGUF model)
    │     ├── Kiểm tra: modelPath configured + file exists on disk?
    │     ├── Default model: embeddinggemma-300M-Q8_0.gguf (~0.6GB)
    │     └── Ưu điểm: không cần API key, chạy offline
    │
    ├── 2. OpenAI
    │     ├── Model: text-embedding-3-small
    │     ├── Endpoint: /v1/embeddings
    │     └── Cần: OPENAI_API_KEY
    │
    ├── 3. Gemini
    │     ├── Model: gemini-embedding-001
    │     ├── Phân biệt: taskType "RETRIEVAL_QUERY" vs "RETRIEVAL_DOCUMENT"
    │     └── Cần: GEMINI_API_KEY
    │
    └── 4. Voyage
          ├── Model: voyage-4-large
          ├── Phân biệt: input_type "query" vs "document"
          └── Cần: VOYAGE_API_KEY

Nếu tất cả fail → throw aggregated error

Fallback mechanism: Nếu primary provider fail, config fallback (e.g., "openai") sẽ tự động kick in. Ngoài ra có runtime fallback – nếu embedding errors xảy ra giữa sync, hệ thống tự thử provider khác.

Batch embedding APIs: Cho indexing lớn, hệ thống hỗ trợ async batch processing qua OpenAI/Gemini/Voyage Batch API (max 50,000 requests/batch). Có failure tracking: sau 2 batch failures → disable batch, fall back to inline embedding.

9. Sync Lifecycle & Atomic Reindex

9.1 Sync triggers

File watcher (chokidar, debounce 1.5s)
          │
Session transcript event (debounce 5s)
          │
Search request (if dirty + sync.onSearch = true)
          │
Session start (if sync.onSessionStart = true)
          │
Interval timer (configurable)
          │
          ▼
     runSync() ← coalesced (chỉ 1 sync chạy tại 1 thời điểm)

9.2 Incremental vs Full Reindex

runSync()
    │
    ├── Check meta: model/provider/chunking params changed?
    │     │
    │     ├── YES → runSafeReindex() (atomic full reindex)
    │     │
    │     └── NO → Incremental sync
    │           ├── Compare file hashes: chỉ re-index files đã thay đổi
    │           ├── Delete chunks của files đã xóa
    │           └── Embed new/changed chunks (with cache lookup)
    │
    ▼
  Done

9.3 Atomic Reindex – Crash-safe

runSafeReindex()
    │
    ├── 1. Tạo temp SQLite DB (temp file)
    ├── 2. Index toàn bộ vào temp DB
    ├── 3. Seed embedding cache từ old DB (tránh re-embed)
    ├── 4. Đổi tên: current → backup, temp → current
    ├── 5. Mở DB mới, verify
    ├── 6. Xóa backup
    │
    └── Nếu fail ở bước 4-5:
          └── Rollback: backup → current

Đây là pattern chuẩn trong database: write-ahead with swap. Tránh tình trạng DB corrupt nếu process crash giữa chừng.

10. Session Memory & Pre-Compaction Flush

10.1 Session Transcript Indexing

Session .jsonl file
    │
    ▼
Parse each line → filter type="message"
    │
    ▼
Extract user/assistant text content
    │
    ▼
Normalize whitespace + redact sensitive data
    │
    ▼
Format: "User: ..." / "Assistant: ..."
    │
    ▼
chunkMarkdown() → embed → store (source="sessions")

Delta-based sync: Không reindex toàn bộ session file mỗi lần. Theo dõi lastSize, pendingBytes, pendingMessages. Chỉ sync khi vượt ngưỡng:

• deltaBytes >= 100KB HOẶC
• deltaMessages >= 50 messages

10.2 Pre-Compaction Memory Flush

Khi conversation gần hết context window:

totalTokens >= contextWindow - reserveTokensFloor(20K) - softThresholdTokens(4K)
    │
    ▼
Inject prompt: "Hãy lưu thông tin quan trọng vào memory file"
    │
    ▼
Agent writes to MEMORY.md / memory/YYYY-MM-DD.md
    │
    ▼
File watcher triggers sync → index new content
    │
    ▼
Context compaction proceeds (old messages trimmed)
    │
    ▼
Agent có thể recall thông tin đã flush qua memory_search tool

Đây là cơ chế durable memory – biến context ephemeral thành persistent storage.

11. Fallback Architecture

OpenClaw có fallback ở 3 tầng:

Tầng 1: Backend Fallback
┌───────────────────────────────┐
│  QMD Backend (external tool)  │
│  BM25 + Vector + Reranking    │
└──────────┬────────────────────┘
           │ fail
           ▼
┌───────────────────────────────┐
│  Builtin MemoryIndexManager   │
│  (luôn available)             │
└───────────────────────────────┘

Tầng 2: Embedding Provider Fallback
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  OpenAI  │ →  │  Gemini  │ →  │  Voyage  │ →  │  Local   │
└──────────┘    └──────────┘    └──────────┘    └──────────┘

Tầng 3: Vector Search Fallback
┌──────────────────────┐
│ sqlite-vec extension │
│ vec_distance_cosine()│
└──────────┬───────────┘
           │ extension not loaded
           ▼
┌──────────────────────┐
│ JS cosineSimilarity()│
│ (load ALL chunks,    │
│  compute in-memory)  │
└──────────────────────┘

Thiết kế này đảm bảo memory search luôn hoạt động dù environment thiếu dependencies.

12. Sơ đồ kiến trúc hoàn chỉnh

╔═══════════════════════════════════════════════════════════════════════════════╗
║                        HYBRID MEMORY SEARCH PIPELINE                           ║
╚═══════════════════════════════════════════════════════════════════════════════╝

┌─────────────────────────────────────────────────────────────────────────────────┐
│ GIAI ĐOẠN 0: INGESTION PIPELINE                                                 │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│   Memory Files (.md)              Session Transcripts (.jsonl)                  │
│   MEMORY.md, memory/*.md          ~/.openclaw/agents/*/sessions/                │
│         │                                    │                                  │
│         ▼                                    ▼                                  │
│   ┌─────────────┐                    ┌──────────────────┐                       │
│   │ File Watcher│                    │ Session Event    │                       │
│   │ debounce 1.5s│                   │ debounce 5s      │                       │
│   └──────┬──────┘                    └────────┬─────────┘                       │
│          │                                    │                                  │
│          │                           ┌────────▼─────────┐                       │
│          │                           │ Delta Check      │                       │
│          │                           │ ≥100KB or ≥50msg?│                       │
│          │                           └────────┬─────────┘                       │
│          │                                    │ Yes                             │
│          └────────────────┬───────────────────┘                                 │
│                           ▼                                                     │
│                  ┌─────────────────┐                                            │
│                  │ chunkMarkdown() │                                            │
│                  │ tokens=400      │                                            │
│                  │ overlap=80      │                                            │
│                  └────────┬────────┘                                            │
│                           ▼                                                     │
│                  ┌─────────────────┐      ┌─────────────────┐                   │
│                  │ Embedding Cache │──Hit─▶│ chunks table    │                   │
│                  │ Lookup          │      │ (text + JSON)   │                   │
│                  └────────┬────────┘      └────────┬────────┘                   │
│                           │ Miss                   │                            │
│                           ▼                        ▼                            │
│                  ┌─────────────────┐      ┌─────────────────┐                   │
│                  │ Embed Provider  │      │ chunks_vec      │                   │
│                  │ local→openai→   │      │ (Float32Array)  │                   │
│                  │ gemini→voyage   │      └─────────────────┘                   │
│                  └────────┬────────┘              │                             │
│                           │                       ▼                             │
│                           ▼              ┌─────────────────┐                    │
│                  ┌─────────────────┐     │ chunks_fts      │                    │
│                  │ L2 Normalize    │     │ (FTS5 indexed)  │                    │
│                  └────────┬────────┘     └─────────────────┘                    │
│                           │                                                     │
│                           ▼                                                     │
│                  ┌─────────────────┐                                            │
│                  │ embedding_cache │                                            │
│                  └─────────────────┘                                            │
└─────────────────────────────────────────────────────────────────────────────────┘

                                    │
                    ════════════════╪════════════════
                                    │
                                    ▼

        ╔═══════════════════════════════════════════════════╗
        ║              USER QUERY                            ║
        ║  "Lỗi logic code xử lý thanh toán"                ║
        ╚═══════════════════════════════════════════════════╝
                           │
           ┌───────────────┴───────────────┐
           ▼                               ▼

┌─────────────────────────────────────────────────────────────────────────────────┐
│ GIAI ĐOẠN 1: DUAL SEARCH (Song song)                                            │
├──────────────────────────────────┬──────────────────────────────────────────────┤
│                                  │                                              │
│  VECTOR SEARCH (Semantic)        │  KEYWORD SEARCH (FTS/BM25)                   │
│  ─────────────────────────       │  ──────────────────────────                  │
│                                  │                                              │
│  embedQuery(text)                │  buildFtsQuery()                             │
│         │                        │  Regex: /[A-Za-z0-9_]+/g                     │
│         ▼                        │         │                                    │
│  Query Vector                    │         ▼                                    │
│  [0.023, -0.045, ...]            │  "logic" AND "code" AND ...                  │
│         │                        │         │                                    │
│    ┌────┴────┐                   │         ▼                                    │
│    ▼         ▼                   │  bm25(chunks_fts)                            │
│ sqlite-vec  JS Fallback          │  MATCH + ORDER BY rank                       │
│ (native)    (all chunks)         │         │                                    │
│    │         │                   │         ▼                                    │
│    └────┬────┘                   │  bm25RankToScore()                           │
│         ▼                        │  score = 1/(1+rank)                          │
│  vectorScore                     │         │                                    │
│  = 1 - distance                  │         ▼                                    │
│  (range 0-1)                     │  textScore (range 0-1)                       │
│                                  │                                              │
└──────────────────────────────────┴──────────────────────────────────────────────┘
           │                               │
           └───────────────┬───────────────┘
                           ▼

┌─────────────────────────────────────────────────────────────────────────────────┐
│ GIAI ĐOẠN 2: SCORE FUSION (Weighted Sum)                                        │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│   Candidate Pool (24 per engine)                                                │
│            │                                                                    │
│            ▼                                                                    │
│   Merge by chunk ID ◄─── Weights: vectorWeight=0.7, textWeight=0.3              │
│            │                                                                    │
│            ▼                                                                    │
│   score = 0.7 × vectorScore + 0.3 × textScore                                   │
│            │                                                                    │
│            ▼                                                                    │
│   Sort descending by score                                                      │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘
                           │
                           ▼

┌─────────────────────────────────────────────────────────────────────────────────┐
│ GIAI ĐOẠN 3: POST-PROCESSING                                                    │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│   Filter: score >= 0.35  ──▶  Limit: top 6  ──▶  Truncate: 700 chars            │
│                                      │                                          │
│                                      ▼                                          │
│                          Add citation: path#L{start}-L{end}                     │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘
                           │
                           ▼

        ╔═══════════════════════════════════════════════════╗
        ║              MemorySearchResult[]                  ║
        ║  {path, startLine, endLine, score, snippet,       ║
        ║   source, citation}                                ║
        ╚═══════════════════════════════════════════════════╝

13. Lessons Learned & Trade-offs

Trade-off 1: Weighted Sum vs RRF

Weighted Sum cần scores được calibrate về cùng range. Trong hệ thống này, cosine similarity tự nhiên ở range 0-1, và BM25 rank được transform qua 1/(1+rank) cũng về 0-1. Đủ tốt cho use case recall, không cần phức tạp hóa.

Trade-off 2: Dual storage cho embedding

Embedding lưu cả JSON string (trong chunks) lẫn Float32Array (trong chunks_vec). Tốn storage gấp đôi, nhưng đảm bảo JS fallback luôn có data khi sqlite-vec không available.

Trade-off 3: Regex tokenizer thay vì NLP tokenizer

/[A-Za-z0-9_]+/g không xử lý được Unicode (tiếng Việt, tiếng Trung…), không stemming, không stop-word removal. Nhưng: zero dependency, fast, predictable. Với code-heavy memory (tên biến, tên hàm), regex tokenizer thực ra khá hiệu quả.

Trade-off 4: Token-based chunk size estimation

maxChars = tokens * 4 là heuristic thô. Thực tế character/token ratio thay đổi theo ngôn ngữ. Nhưng tránh phải load tokenizer model chỉ để ước chunk size.

Trade-off 5: Single SQLite file per agent

Đơn giản, không cần external database. Nhưng giới hạn concurrency (SQLite single-writer lock). Với use case single-agent-per-session, đây không phải vấn đề.

Key Takeaways

1. Hybrid search không khó: Chỉ cần 2 search engine + 1 hàm merge ~70 dòng code.
2. Fallback everywhere: Production system cần degrade gracefully, không crash.
3. Cache embeddings aggressively: API calls tốn tiền và chậm. SHA-256 hash + provider fingerprint = cache key hoàn hảo.
4. Atomic operations cho persistence: Temp file → swap pattern bảo vệ data integrity.
5. Simple > Perfect: Weighted Sum đủ tốt. Regex tokenizer đủ tốt. Ship it, iterate later.

Code references: src/memory/hybrid.ts, src/memory/manager-search.ts, src/memory/manager.ts, src/memory/memory-schema.ts, src/memory/embeddings.ts, src/memory/internal.ts

Hướng dẫn xây lại cốt lõi vững – không màu mè, không đạo lý, không chữa lành sáo rỗng. Chỉ là cách một con người học cách đứng vững bên trong, sau khi đã sống quá lâu bằng phòng vệ.

I. Hiểu đúng trước khi làm (rất quan trọng)

1. “Xây lại cốt lõi” không phải

• Tự tin hơn
• Nghĩ tích cực
• Buông bỏ hết
• Trở nên hiền lành

👉 Những thứ đó là hệ quả, không phải gốc

2. “Xây lại cốt lõi” thực chất là

Tái lập cảm giác an toàn nội tại, để bạn không cần phản ứng để tự vệ nữa.

Cốt lõi vững = Tôi có thể ở đây, như tôi đang là, và tôi không bị đe dọa.

II. Bản đồ cốt lõi (để bạn không làm mù mờ)

Cốt lõi vững gồm 4 tầng, làm theo thứ tự, không nhảy cóc:

1. Nhận diện phản xạ sinh tồn
2. Ở lại với cảm giác (không sửa)
3. Xây giá trị không điều kiện
4. Tập hành động từ giá trị, không từ sợ

Nếu bạn bỏ qua tầng nào → cốt lõi sẽ giả vững

III. TẦNG 1 – Nhận diện phản xạ sinh tồn (không phán xét)

Việc cần làm (hằng ngày, rất thực tế)

Khi có chuyện xảy ra, đừng hỏi “tôi nên làm gì”, hãy hỏi:

❓ “Tôi đang bảo vệ điều gì?”

4 phản xạ sinh tồn phổ biến (hãy nhận diện mình)

1. Kiểm soát

   • Muốn nắm hết
   • Khó tin ai
   • Sợ mất quyền chủ động → Gốc: “Nếu tôi không kiểm soát, tôi sẽ bị tổn thương”

2. Làm hài lòng

   • Nhường
   • Chịu
   • Sợ người khác buồn → Gốc: “Nếu họ không hài lòng, tôi sẽ bị bỏ”

3. Rút lui

   • Ít nói
   • Ít cần
   • Không đòi hỏi → Gốc: “Ở gần là nguy hiểm”

4. Tấn công / hơn thua

   • Nhanh phản bác
   • Không chịu thua → Gốc: “Nếu tôi yếu, tôi sẽ bị đè”

👉 Chỉ cần nhận ra, chưa cần sửa.

Nhận ra = bắt đầu có cốt lõi Chưa nhận ra = cốt lõi đang bị lái

IV. TẦNG 2 – Ở lại với cảm giác (bước khó nhất)

Đây là chỗ 99% người bỏ cuộc.

Nguyên tắc sắt

Đừng sửa cảm giác trước khi nó được cảm.

Thực hành 3 phút (đủ dùng)

Khi bị kích hoạt:

1. Dừng hành động
2. Nhắm mắt (hoặc nhìn cố định)

3. Hỏi thầm:

   • “Cảm giác này nằm ở đâu trong cơ thể?”
   • Nặng / nóng / co / trống?

❌ Không phân tích ❌ Không hợp lý hóa ❌ Không tự trấn an

👉 Chỉ ở lại

Điều sẽ xảy ra (đừng sợ)

• Khó chịu tăng lên
• Muốn trốn
• Muốn làm gì đó cho xong

👉 Đây là hệ thần kinh đang học rằng: ‘Tôi có thể ở lại mà không chết’

Đó là xây cốt lõi, không phải thiền cho vui.

V. TẦNG 3 – Xây giá trị không điều kiện (cốt lõi thật bắt đầu ở đây)

Sự thật quan trọng

Cốt lõi yếu vì giá trị bản thân có điều kiện

Ví dụ:

• Tôi có giá trị khi giỏi
• Tôi xứng đáng khi hữu ích
• Tôi ổn khi không sai

Bài tập gốc (rất thẳng)

Viết ra và hoàn thành câu này:

“Ngay cả khi tôi không ______, tôi vẫn xứng đáng được tồn tại.”

Điền vào:

• Giỏi
• Mạnh
• Được yêu
• Có ích
• Đúng

👉 Nếu bạn không viết nổi, đó chính là chỗ cốt lõi đang rách.

Lặp lại bằng hành vi (quan trọng hơn suy nghĩ)

• Cho phép mình mệt
• Cho phép mình không tối ưu
• Cho phép mình không chứng minh

👉 Không sửa – không cải thiện – không justify

VI. TẦNG 4 – Hành động từ giá trị (không từ sợ)

Câu hỏi chuyển trục (rất mạnh)

Thay vì:

“Làm vậy có an toàn không?”

Hãy hỏi:

“Nếu tôi không sợ, tôi sẽ chọn gì?”

Ví dụ rất đời

• Nói thật dù có thể mất lòng
• Dừng một mối quan hệ dù còn tiếc
• Không giải thích thêm khi đã đủ
• Nghỉ khi mệt, không xin phép

👉 Lúc này bạn chưa hết sợ 👉 Nhưng sợ không còn lái tay lái

VII. Dấu hiệu bạn đang xây đúng (không dễ chịu đâu)

• Bạn chậm hơn trước khi phản ứng
• Bạn thấy rõ mình đang phòng vệ
• Bạn ít ghét bản thân hơn khi yếu
• Bạn không cần thắng để thấy mình đúng
• Bạn dám mất để giữ giá trị

👉 Nếu thấy khó nhưng thật → bạn đi đúng

VIII. Sai lầm phổ biến (đừng mắc)

❌ Muốn chữa nhanh ❌ Muốn “xong” ❌ Muốn thành phiên bản tốt hơn để được yêu

👉 Cốt lõi vững không làm bạn đáng yêu hơn 👉 Nó làm bạn không cần phải đáng yêu

IX. Một câu kết (rất quan trọng)

Cốt lõi vững không khiến bạn không còn đau. Nó khiến bạn không còn phải đánh mất mình để né đau.