Add documents table, session-init hook, and updated memory-extract hook

README.md

@@ -47,6 +47,7 @@ The schema (`schema.sql`) includes tables for:
 - **preferences** - User/system preferences
 - **sops** - Standard Operating Procedures for various tasks and workflows  
 - **agents** - Registry of AI agent instances for delegation
+- **documents** - Registry of workspace files and knowledge documents for cross-session discovery
 
 ### Access Control Architecture
 
@@ -556,6 +557,39 @@ SELECT title, theme, quality_score,
 FROM artwork ORDER BY created_at DESC LIMIT 5;
 ```
 
+### Documents Table (Document Registry)
+
+The `documents` table tracks workspace files and knowledge documents:
+
+| Column | Type | Purpose |
+|--------|------|---------|
+| `id` | int | Primary key |
+| `path` | text | Unique file path (relative to workspace) |
+| `title` | varchar(255) | Human-readable title |
+| `doc_type` | varchar(50) | Category: config, memory, tool, hook, skill, etc. |
+| `description` | text | What this document contains/does |
+| `tags` | text[] | Searchable tags |
+
+**Use Cases:**
+- Discover what files exist without scanning the filesystem
+- Find relevant documents by type or keyword across sessions
+- Track which workspace files are registered vs unregistered
+
+**Example:**
+```sql
+-- Register a document
+INSERT INTO documents (path, title, doc_type, description)
+VALUES ('memory/research-craft-cli.md', 'Craft CLI Research', 'memory', 'Research notes on Craft.do API integration')
+ON CONFLICT (path) DO UPDATE SET title=EXCLUDED.title, updated_at=now();
+
+-- Find all memory documents
+SELECT title, path FROM documents WHERE doc_type = 'memory' ORDER BY title;
+
+-- Search documents
+SELECT title, path, description FROM documents
+WHERE title ILIKE '%research%' OR description ILIKE '%research%';
+```
+
 ### Setup
 
 ```bash
@@ -618,7 +652,18 @@ git add schema.sql && git commit -m "Update schema: [description]"
 git push
 ```
 
-## Clawdbot Hook (Automatic Extraction)
+## Hooks
+
+### Session Init Hook (`hooks/session-init/`)
+
+Automatically injects recent activity context from PostgreSQL into the agent's bootstrap. On `agent:bootstrap`, queries events (48h), decisions (7d), and lessons (7d), then formats them as a `SESSION_CONTEXT.md` bootstrap file. Falls back silently if PostgreSQL is unavailable.
+
+```bash
+cp -r hooks/session-init ~/clawd/hooks/
+openclaw hooks enable session-init
+```
+
+### Memory Extract Hook (`hooks/memory-extract/`)
 
 The `hooks/memory-extract/` directory contains a Clawdbot hook that automatically extracts memories from incoming messages.
 

hooks/memory-extract/HOOK.md

@@ -1,9 +1,33 @@
 ---
 name: memory-extract
-description: "Extracts memories from incoming messages and stores in database"
-metadata: {"clawdbot":{"emoji":"🧠","events":["message:received"]}}
+description: "Extract and store memories from assistant responses after each turn"
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🧠",
+        "events": ["message:sent"],
+        "requires": { "bins": ["node"] },
+      },
+  }
 ---
 
 # Memory Extraction Hook
 
-Automatically extracts entities, facts, opinions, and relationships from incoming messages and stores them in the PostgreSQL memory database.
+Automatically extracts facts, events, decisions, and lessons from conversation turns and stores them in the PostgreSQL memory database via `memory-db` CLI.
+
+## How It Works
+
+When `message:sent` fires:
+
+1. Reads the last few messages from the session transcript
+2. Applies lightweight heuristics to detect extractable content (skips heartbeats, short messages, routine responses)
+3. If heuristics pass, calls the Anthropic API (Claude Haiku) to parse structured memory entries
+4. Shells out to `memory-db` CLI to store extracted facts, events, and lessons
+
+## Safeguards
+
+- **Cooldown:** Minimum 5 minutes between extractions per session
+- **Heuristic gate:** LLM is only called when keywords/patterns suggest extractable content
+- **Graceful failure:** All errors are caught and logged; never blocks message delivery
+- **Skips:** Heartbeats, commands, short messages, isolated/spawn sessions