From 5858c617df2354bf4293d73c3f5e835281a18288 Mon Sep 17 00:00:00 2001
From: weishen <ishenwei@gmail.com>
Date: Sun, 5 Apr 2026 18:06:00 +0800
Subject: [PATCH] feat: TimescaleDB hypertable migration and README

Add hypertable migration that only runs on PostgreSQL (no-op for SQLite dev/tests).
Update README with architecture, quick start, and client sync instructions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.md                                     | 44 +++++++++++++++++++
 .../migrations/0002_add_hypertables.py        | 33 ++++++++++++++
 2 files changed, 77 insertions(+)
 create mode 100644 src/openclaw/migrations/0002_add_hypertables.py

diff --git a/README.md b/README.md
index cc16be7..839af46 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,46 @@
 # agent-base
 
+OpenClaw Session Archive - 多 Agent 会话解析与归档系统。
+
+## Architecture
+
+Three nodes (Mac Mini, Ubuntu1, Ubuntu2) run a sync script that parses local JSONL session files and pushes structured data to a central Django API. The Django service runs in Docker Compose and stores data in a remote PostgreSQL + TimescaleDB instance on NAS.
+
+## Quick Start
+
+```bash
+# 1. Configure environment
+cp .env.example .env
+# Edit .env with your database credentials and Django settings
+
+# 2. Build and start
+docker compose build
+docker compose run --rm web python manage.py migrate
+docker compose run --rm web python manage.py createsuperuser
+docker compose up -d
+
+# 3. Access
+# Django Admin: http://<host>:8000/admin/
+# API: http://<host>:8000/api/sessions/bulk_upsert/
+```
+
+## Running Tests
+
+```bash
+pip install -r requirements-dev.txt
+pytest -v
+```
+
+## Client Sync Script
+
+Deploy `scripts/sync_sessions.py` on each node:
+
+```bash
+python sync_sessions.py --remote-url http://<django-host>:8000/api/sessions/bulk_upsert/
+```
+
+Set `SOURCE_NODE` environment variable on each node (`macmini`, `ubuntu1`, `ubuntu2`).
+
+## Daily Export
+
+In Django Admin, select sessions and choose "Export selected sessions to Markdown" action.
diff --git a/src/openclaw/migrations/0002_add_hypertables.py b/src/openclaw/migrations/0002_add_hypertables.py
new file mode 100644
index 0000000..694e89a
--- /dev/null
+++ b/src/openclaw/migrations/0002_add_hypertables.py
@@ -0,0 +1,33 @@
+from django.db import migrations, connection
+
+CREATE_HYPERTABLES = """
+SELECT create_hypertable(
+    'sessions',
+    'start_time',
+    if_not_exists => TRUE
+);
+
+SELECT create_hypertable(
+    'messages',
+    'timestamp',
+    if_not_exists => TRUE
+);
+"""
+
+
+def create_hypertables(apps, schema_editor):
+    if connection.vendor != "postgresql":
+        return
+    with schema_editor.connection.cursor() as cursor:
+        cursor.execute(CREATE_HYPERTABLES)
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("openclaw", "0001_initial"),
+    ]
+
+    operations = [
+        migrations.RunPython(create_hypertables, migrations.RunPython.noop),
+    ]