📅
🕵️‍♂️ อ่าน ~3 นาที

คดีที่ 36: ผ่าพิมพ์เขียว hindsight — ถอดรหัสสถาปัตยกรรม AI ยุคใหม่ (28.5k Stars)

🕵️‍♂️ ปมคดีและที่มา: ทำไมวงการถึงต้องจับตามอง?

ทำไมโปรเจกต์ vectorize-io/hindsight ถึงได้รับความนิยมและมียอดกด Star ทะลุ 28.5k บน GitHub?

เบื้องหลังความสำเร็จนี้ไม่ใช่แค่การเป็นเครื่องมือสำเร็จรูป แต่คือการแก้ปัญหาทางวิศวกรรมที่เจ็บปวด: สถาปัตยกรรมโอเพ่นซอร์สเทคโนโลยี AI ยุคใหม่

📊 ตารางเปรียบเทียบเชิงลึก: วิธีดั้งเดิม vs สถาปัตยกรรมสมัยใหม่

มิติการเปรียบเทียบ สถาปัตยกรรมเดิม (Traditional Approaches) สถาปัตยกรรม {clean_name}
ความยืดหยุ่น ผูกติดกับ Cloud Provider รายใหญ่ Modular Engine รองรับทั้ง Local และ API มาตรฐาน
ประสิทธิภาพ Token บริโภค Context สูง ขาดการแคชที่ดี ออกแบบ Layer แยก Context และ Execution ออกจากกัน
ความง่ายในการ Integrate ต้องเขียน Custom Glue Code มหาศาล เชื่อมต่อผ่าน Standardized Protocols (MCP/REST)

🔍 แกะรอยสถาปัตยกรรมระบบ (Deep Architecture Breakdown)

พิมพ์เขียวสถาปัตยกรรมเบื้องหลังระบบนี้ ถูกออกแบบมาเพื่อแก้ปัญหาคอขวดด้านประสิทธิภาพและความปลอดภัย:

flowchart TD
    subgraph 👤 User & Agent Layer
        User["👨‍💻 Developer / AI Agent"] -->|"Task / Intent"| Router["⚡ Protocol Router (MCP / CLI)"]
    end

    subgraph 🧠 Core Intelligence Engine
        Router --> Engine["⚙️ hindsight Engine"]
        Engine --> Decision["🎯 Intelligent Decision Core"]
        Engine --> Memory["💾 Persistent Session & Cache"]
    end

    subgraph 🛠️ Execution & Tooling
        Decision --> Tools["🔧 Specialized Execution Modules"]
        Tools --> Output["📊 Filtered & Optimized Results"]
    end

    Output -->|"Clean Context"| User

3 เสาหลักของการออกแบบระบบ (System Design Pillars):

  1. Decoupled Execution & Protocol-First: สื่อสารผ่านโปรโตคอลมาตรฐาน ทำให้ถอดเปลี่ยนสมองกล (LLM) ได้อิสระโดยไม่ต้องเขียน Logic การเชื่อมต่อ Tool ใหม่
  2. Context & Token Economy: ป้องกันไม่ให้ Output ดิบขนาดมหึมาทะลักเข้าสู่หน้าต่างบริบท ช่วยลดอาการ Hallucination และประหยัดค่าใช้จ่าย
  3. Resilience & State Continuity: มีกลไก Handle Exception และบันทึก State ความคืบหน้า เพื่อให้การทำงานแบบ Multi-step สามารถรันต่อได้จนจบภารกิจ

💻 ผ่ารหัสลับของจริง (Source Code Autopsy)

จากการผ่าโครงสร้าง Repo ของจริง เราพบชิ้นส่วนโค้ดสำคัญที่เป็นหัวใจของการขับเคลื่อนระบบ:

📄 ผ่าไฟล์จริง: package.json

{
  "name": "hindsight",
  "private": true,
  "workspaces": [
    "hindsight-clients/typescript",
    "hindsight-control-plane",
    "hindsight-docs",
    "hindsight-interfig",
    "hindsight-all-npm",
    "hindsight-tools/hindsight-agent-sdk"
  ],
  "scripts": {
    "prepare": "./scripts/setup-hooks.sh"
  },
  "overrides": {
    "qs": ">=6.16.0 <7.0.0",
    "fast-xml-parser": ">=5.5.6",
    "serialize-javascript": "^7.0.5",
    "minimatch": "^3.1.4",
    "undici": ">=7.29.0 <8.0.0",
    "flatted": ">=3.4.2",
    "picomatch": ">=2.3.2 <3.0.0 || >=4.0.4",
    "yaml": ">=1.10.3",
    "svgo": ">=4.1.0",
    "dompurify": ">=3.4.13",
    "@redocly/openapi-core": {
      "minimatch": "^5.1.8"
    },
    "@typescript-eslint/typescript-estree": {
      "minimatch": "^9.0.7"
    },
    "ajv-formats": {
      "ajv": "^8.18.0"
    },
    "handlebars": ">=4.7.9",
    "path-to-regexp": ">=0.1.13",
    "brace-expansion": ">=1.1.18 <2.0.0 || >=2.1.4 <3.0.0",
    "lodash-es": ">=4.18.1",
    "mermaid": ">=11.16.1",
    "websocket-driver": ">=0.7.5",
    "http-proxy-middleware": ">=2.0.10 <3",
    "next": ">=16.3.3 <17",
    "fast-uri": ">=3.1.6 <4",
    "sharp": ">=0.35.4",
    "shell-quote": ">=1.9.0",
    "@istanbuljs/load-nyc-config": {
      "js-yaml": "^3.15.2"
    },
    "gray-matter": {
      "js-yaml": "^3.15.2"
    },
    "sockjs": {
      "uuid": "^11.1.1"
    },
    "postcss": ">=8.5.23",
    "js-yaml": ">=3.15.2 <4.0.0 || >=4.3.2 <5.0.0",
    "nanoid": ">=3.3.18 <4.0.0",
    "webpack-dev-server": ">=5.2.6 <6.0.0",
    "esbuild": ">=0.28.1 <0.29.0",
    "body-parser": ">=1.20.6 <2.0.0",
    "browserslist": ">=4.28.7 <5.0.0",
    "postcss-selector-parser": ">=7.1.3 <8.0.0",
    "postcss-calc": {
      "postcss-selector-parser": "^6.1.3"
    },
    "postcss-discard-unused": {
      "postcss-selector-parser": "^6.1.3"
    },
    "postcss-merge-rules": {
      "postcss-selector-parser": "^6.1.3"
    },
    "postcss-minify-selectors": {
      "postcss-selector-parser": "^6.1.3"
    },
    "postcss-unique-selectors": {
      "postcss-selector-parser": "^6.1.3"
    },
    "stylehacks": {
      "postcss-selector-parser": "^6.1.3"
    },

การทำงานทางวิศวกรรม:

  • โค้ดส่วนนี้ทำหน้าที่เป็นแกนกลางในการควบคุม Flow ของข้อมูล
  • แยกหน้าที่การทำงานชัดเจน (Separation of Concerns) ทำให้สเกลเครื่องมือใหม่ๆ เข้าสู่ระบบได้ทันทีโดยไม่ต้องแก้ Core Engine

📄 ผ่าไฟล์จริง: pyproject.toml

[tool.uv.workspace]
members = ["hindsight-all", "hindsight-api", "hindsight-api-slim", "hindsight-all-slim", "hindsight-dev", "hindsight-mcp-server", "hindsight-clients/python", "hindsight-embed"]

[tool.uv]
# Allow uv to search all configured indexes for packages, not just the first one
# This prevents dependency resolution failures when using pytorch index + PyPI
index-strategy = "unsafe-best-match"
dev-dependencies = []

การทำงานทางวิศวกรรม:

  • โค้ดส่วนนี้ทำหน้าที่เป็นแกนกลางในการควบคุม Flow ของข้อมูล
  • แยกหน้าที่การทำงานชัดเจน (Separation of Concerns) ทำให้สเกลเครื่องมือใหม่ๆ เข้าสู่ระบบได้ทันทีโดยไม่ต้องแก้ Core Engine

📄 ผ่าไฟล์จริง: CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Hindsight is an agent memory system that provides long-term memory for AI agents using biomimetic data structures. Memories are organized as:
- **World facts**: General knowledge ("The sky is blue")
- **Experience facts**: Personal experiences ("I visited Paris in 2023")
- **Mental models**: Consolidated knowledge synthesized from facts ("User prefers functional programming patterns")

## Development Commands

### Local Development (API + UI)
```bash
# Start both API server and control plane UI
./scripts/dev/start.sh

API Server (Python/FastAPI)

# Start API server only (loads .env automatically)
./scripts/dev/start-api.sh

# Run all tests (parallelized with pytest-xdist)
cd hindsight-api-slim && uv run pytest tests/

# Run specific test file
cd hindsight-api-slim && uv run pytest tests/test_http_api_integration.py -v

# Run single test function
cd hindsight-api-slim && uv run pytest tests/test_retain.py::test_retain_with_chunks -v

# Lint and format
cd hindsight-api-slim && uv run ruff check .
cd hindsight-api-slim && uv run ruff format .

# Type checking (uses ty - extremely fast type checker from Astral)
cd hindsight-api-slim && uv run ty check hindsight_api/

Control Plane (Next.js)

./scripts/dev/start-control-plane.sh
# Or manually:
cd hindsight-control-plane && npm run dev

# Run frontend unit tests
cd hindsight-control-plane && npm test

# Run frontend linter
cd hindsight-control-plane && npm run lint

CLI Tool (Rust)

# Build CLI binary (hindsight-cli/target/release/hindsight)
cd hindsight-cli && cargo build --release

# Run CLI tests
cd hindsight-cli && cargo test

System Tests (Blackbox End-to-End)

# Prerequisite: server needs pg0 installed in api-slim
(cd hindsight-api-slim && uv sync --frozen --extra embedded-db)

# Run blackbox integration tests against local embedded Postgres & stub provider
# (The stub handles LLM, embeddings, and reranking without downloading models)
cd hindsight-system-tests && uv run pytest tests/ -v

Documentation Site (Docusaurus)

./scripts/dev/start-docs.sh

Generating Clients/OpenAPI

**การทำงานทางวิศวกรรม:**
- โค้ดส่วนนี้ทำหน้าที่เป็นแกนกลางในการควบคุม Flow ของข้อมูล
- แยกหน้าที่การทำงานชัดเจน (Separation of Concerns) ทำให้สเกลเครื่องมือใหม่ๆ เข้าสู่ระบบได้ทันทีโดยไม่ต้องแก้ Core Engine

### 📄 ผ่าไฟล์จริง: `AGENTS.md`
``` typescript
# AGENTS.md

See [CLAUDE.md](./CLAUDE.md) for project documentation and coding conventions.

การทำงานทางวิศวกรรม:

  • โค้ดส่วนนี้ทำหน้าที่เป็นแกนกลางในการควบคุม Flow ของข้อมูล
  • แยกหน้าที่การทำงานชัดเจน (Separation of Concerns) ทำให้สเกลเครื่องมือใหม่ๆ เข้าสู่ระบบได้ทันทีโดยไม่ต้องแก้ Core Engine

💰 3 พิมพ์เขียวสร้างรายได้จริงจากสถาปัตยกรรมนี้

  1. Enterprise Security & Architecture Consulting (รับงานที่ปรึกษาองค์กร)

    • องค์กรขนาดใหญ่ต้องการนำ AI Agent มาใช้ แต่ติดปัญหา Data Leak และการควบคุม Tool Calling
    • นำสถาปัตยกรรม FastMCP / Sandboxed Context ไปติดตั้งแบบ On-premise ค่าบริการเริ่มต้น 150,000 - 300,000 บาท/โปรเจกต์

  2. Specialized AI Automation Micro-SaaS (สร้างบริการเฉพาะทาง)

    • พัฒนาบริการ Agent สำหรับตรวจสอบช่องโหว่เว็บ (Bug Bounty as a Service) หรือเครื่องมือคุม Context สำหรับทีม Dev
    • ตั้งราคาแบบ Subscription รายเดือน ($29 - $99/เดือน/ผู้ใช้)

  3. Developer Tools & Workflow Optimization Retainer

    • ให้บริการตรวจสอบและ Optimize สถาปัตยกรรม Token Consumption ให้แก่บริษัท Startup หรือ Tech Agency
    • ช่วยลดค่า API OpenAI / Anthropic จากหลักแสนเหลือหลักหมื่นบาทต่อเดือน โดยคิดส่วนแบ่งจากยอดเงินที่ช่วยประหยัดได้ (Cost-Saving Share 20-30%)

💬 ร่วมสืบคดีและแลกเปลี่ยนความรู้ด้าน AI Engineering กับเราได้ที่เพจ Facebook: นักสืบอัลกอริทึม

🕵️‍♂️

ชอบคดีนี้ไหม? ส่งต่อให้เพื่อนในวงการ Dev!

แชร์บทความวิเคราะห์สถาปัตยกรรม AI & โค้ดจริงที่นำไปใช้สร้างเงินได้ทันที

แชร์บน Facebookแชร์บน XLinkedIn
💬

ร่วมอภิปรายคดีลับ (Case Discussion)

มีข้อสงสัย บัค หรือไอเดียต่อยอดสถาปัตยกรรมนี้? แลกเปลี่ยนกับเพื่อนสาย Dev ได้ด้านล่าง: