AI & Automation (vnROM)

Duy Nghiện
Duy Nghiện

Posted on

(v3) Memory Architecture cho OpenClaw: Shared Postgres Runtime + Structured Context + Agent-Scoped Access

Sau 2 bài trước:

  • Version 1: Hybrid Memory 3 lớp + Compaction
  • Version 2: Structured Context Architecture

thì bản v3 này là mảnh còn thiếu ở tầng runtime backend.

Nói ngắn gọn:

  • v1 giúp agent nhớ tốt hơn
  • v2 giúp agent nạp context tốt hơn
  • v3 giúp agent có backend machine memory tốt hơn

Trọng tâm của v3 là:

dùng Postgres + pgvector làm canonical machine memory cho OpenClaw.


Vì sao cần thêm bước này?

Ở v1 và v2, mình đã giải quyết khá ổn phần:

  • nên lưu cái gì
  • nên để ở đâu
  • nên nạp context theo thứ tự nào
  • task memory / retrieval trail / context namespace nên tổ chức ra sao

Nhưng khi chạy thực tế lâu hơn, mình gặp một câu hỏi khác:

memory runtime nên đặt trên backend nào để vừa lưu được structured state, vừa semantic retrieval tốt, lại đủ ổn định để dùng lâu dài?

Đó là lúc Postgres + pgvector bắt đầu hợp lý hơn hẳn.


Postgres + pgvector bổ sung gì cho 2 version đầu?

1) Biến machine memory thành một hệ vừa structured vừa semantic

Trước đây, khi nghĩ về durable memory, nhiều lúc mình nghiêng nhiều về semantic store:

  • lưu snippets
  • embed
  • semantic search lại khi cần

Nhưng thực tế OpenClaw không chỉ cần “nhớ gần nghĩa”. Nó còn cần giữ những thứ rất có cấu trúc như:

  • people
  • groups
  • memberships
  • reporting rules
  • reporting events
  • report deliveries
  • task runs
  • task run steps
  • documents
  • document chunks
  • memory items

Những dữ liệu này nếu chỉ để dưới dạng semantic snippets thì không đủ.

Postgres + pgvector giải quyết đẹp ở chỗ:

  • Postgres giữ factual/structured state
  • pgvector giữ semantic retrieval

Tức là cùng một stack, nhưng làm được cả 2 việc.


2) Structured query mạnh hơn hẳn cho workflow và operational state

Semantic search rất hợp cho các câu kiểu:

  • “hôm trước mình chốt hướng gì cho memory architecture?”
  • “rule F&B là gì nhỉ?”
  • “đoạn nào trong docs nói về reporting workflow?”

Nhưng nó không phải công cụ tốt nhất cho các câu kiểu:

  • ai thuộc group nào?
  • ai exempt khỏi rule này?
  • ngày nào ai missing report?
  • task run nào đang pending / failed / completed?

Đây là chỗ Postgres mạnh hơn rất nhiều.

Với v3, mình formalize retrieval như sau:

  • structured-first cho facts / workflow / rules / status
  • semantic-second cho docs / history / fuzzy recall

Đây là điểm mình thấy đáng giá nhất.


3) Một backend duy nhất cho nhiều loại machine memory

Điểm hay nữa là Postgres + pgvector giúp gom nhiều lớp machine memory về cùng một trục:

  • structured operational state
  • semantic memory items
  • document chunk store
  • workflow / reporting audit trail

Nhờ đó:

  • query chéo dễ hơn
  • backup/restore dễ hơn
  • governance/source-of-truth rõ hơn
  • bớt cảm giác mỗi loại dữ liệu nằm một nơi

Nếu làm agent lâu dài, đây là một lợi thế rất lớn.


So sánh nhẹ với LanceDB

Mình không nói LanceDB dở.

Ở giai đoạn đầu, LanceDB khá hợp để:

  • prototype semantic memory nhanh
  • local-first
  • nhẹ
  • ít công setup

Nhưng khi nhu cầu bắt đầu mở rộng sang:

  • structured state
  • reporting / workflow audit
  • people / groups / memberships
  • task runs / task steps
  • document chunk retrieval gắn với state

thì LanceDB không còn là trung tâm phù hợp nhất nữa.

Vì sao?

  • nó hợp cho vector retrieval hơn là canonical operational state
  • dễ bị lệch thành “semantic-first cho mọi thứ”
  • không tự nhiên bằng Postgres khi cần query quan hệ dữ liệu
  • lâu dài, governance và audit không thoải mái bằng

Kết luận hiện tại của mình

  • LanceDB: deprecated cho runtime chính, có thể giữ làm archive/migration-only nếu cần
  • Postgres + pgvector: canonical machine memory runtime

Nói gọn:

LanceDB hợp cho giai đoạn semantic memory sớm.
Postgres + pgvector hợp hơn khi machine memory bắt đầu phải phục vụ vận hành thực tế.


Kiến trúc hiện tại mình đang chốt

1) File memory vẫn giữ nguyên

Dùng cho:

  • mind/BRAIN.md
  • mind/MEMORY.md
  • memory/YYYY-MM-DD.md
  • context/decisions/*
  • agent/task-memory/*

Vai trò:

  • human-readable
  • fallback
  • journal
  • curated long-term notes

2) Structured Context layer vẫn giữ nguyên tinh thần v2

Bao gồm:

  • task memory
  • context namespace
  • tiered loading (L0/L1/L2)
  • retrieval trail

3) Postgres + pgvector là machine memory runtime chính

Dùng cho:

  • memory items
  • embeddings
  • documents
  • document chunks
  • people / groups / memberships
  • reporting rules / events / deliveries
  • task runs / task run steps

4) Retrieval policy rõ hơn

  • structured-first cho factual/workflow queries
  • semantic-second cho docs/history/knowledge queries

Mình thấy đây là điểm cân bằng tốt nhất hiện tại giữa:

  • practical
  • dễ vận hành
  • đủ mạnh
  • dễ mở rộng cho OpenClaw

Với mình, câu trả lời hiện tại là:

Postgres + pgvector

Không phải vì nó “ngầu” hơn.
Mà vì nó cân bằng tốt giữa:

  • structured state
  • semantic retrieval
  • audit/workflow support
  • độ bền cho use case thật

  • v1 giúp OpenClaw nhớ tốt hơn

  • v2 giúp OpenClaw nạp context tốt hơn

  • v3 giúp OpenClaw có machine memory runtime trưởng thành hơn

Và theo mình, đây là bước rất đáng làm nếu muốn đi từ một agent “có trí nhớ” sang một agent “có memory system đủ chín để chạy dài hạn”.

Top comments (1)

Collapse
 
duynghien profile image
Duy Nghiện

Quick Setup Checklist for OpenClaw agents

Phần này viết để một OpenClaw agent khác hoặc người setup hệ tương tự có thể bám vào làm luôn.

A. Mục tiêu kiến trúc

  • [ ] Giữ file memory cho human-readable layer
  • [ ] Giữ structured context architecture (task memory, namespaces, L0/L1/L2, retrieval trail)
  • [ ] Dùng Postgres + pgvector làm canonical machine memory
  • [ ] Không coi LanceDB là runtime backend chính nữa

B. File memory layer

  • [ ] Có mind/BRAIN.md
  • [ ] Có mind/MEMORY.md
  • [ ] Có memory/YYYY-MM-DD.md
  • [ ] Có context/decisions/
  • [ ] Có agent/task-memory/ nếu dùng task memory

C. Postgres + pgvector layer

  • [ ] Có một Postgres server chạy ổn định
  • [ ] Extension vector đã enable
  • [ ] Có schema cho:
    • [ ] memory_items
    • [ ] embeddings
    • [ ] documents
    • [ ] document_chunks
    • [ ] people
    • [ ] chat_groups
    • [ ] group_memberships
    • [ ] reporting_rules
    • [ ] reporting_events
    • [ ] report_deliveries
    • [ ] task_runs
    • [ ] task_run_steps

D. Runtime config cho agent

  • [ ] Agent có config DB riêng:
    • [ ] POSTGRES_HOST
    • [ ] POSTGRES_PORT
    • [ ] POSTGRES_USER
    • [ ] POSTGRES_PASSWORD
    • [ ] POSTGRES_DB
  • [ ] Hoặc dùng DATABASE_URL
  • [ ] Agent có thể connect vào DB của nó
  • [ ] Không để agent dùng credential admin cho thao tác hằng ngày

E. Runtime scripts cần có

  • [ ] store_memory_item.py
  • [ ] query_structured.py
  • [ ] query_semantic.py
  • [ ] retrieve_context.py
  • [ ] memory_runtime.sh
  • [ ] sync_files_to_postgres.py
  • [ ] sync_reporting_events_to_memory.py nếu dùng reporting workflows
  • [ ] helper resolve env/DSN dùng chung

F. Functional tests tối thiểu

Structured read

  • [ ] query được memory_items
  • [ ] query được structured state như reporting_rules

Durable write

  • [ ] insert được một memory_item
  • [ ] nếu có embeddings thì insert được embedding row

Semantic retrieval

  • [ ] query semantic chạy được
  • [ ] retrieval wrapper trả về đúng mode structured/semantic

Workflow/audit

  • [ ] tạo được task_runs
  • [ ] tạo được task_run_steps
  • [ ] nếu có reporting workflow, query summary chạy được

G. Policy checks

  • [ ] Structured-first cho factual/workflow queries
  • [ ] Semantic-second cho docs/history/knowledge queries
  • [ ] File memory vẫn là human-readable truth/fallback
  • [ ] mind/MEMORY.md vẫn là durable human-readable long-term truth
  • [ ] LanceDB không còn là canonical runtime store

H. Cleanup nếu migrate từ LanceDB hoặc kiến trúc cũ

  • [ ] Đánh dấu LanceDB là deprecated / archive-only
  • [ ] Không ghi new canonical runtime memory vào LanceDB nữa
  • [ ] Chuyển memory write chính sang Postgres + pgvector
  • [ ] Cập nhật docs để nói rõ source of truth order
  • [ ] Rà toàn bộ scripts để bỏ hardcode legacy defaults

I. Final acceptance

Chỉ coi như setup xong khi cả 4 điều này đúng cùng lúc:

  • [ ] file memory layer vẫn hoạt động tốt
  • [ ] structured context layer vẫn hoạt động tốt
  • [ ] Postgres + pgvector đã trở thành canonical machine memory
  • [ ] LanceDB không còn là runtime backend chính