alanshurafa · alanshurafa · Apr 18, 2026 · Apr 18, 2026 · Apr 6, 2026 · Apr 6, 2026
diff --git a/.gitignore b/.gitignore
@@ -3,6 +3,15 @@ node_modules/
 .planning/
 supabase/
 
+# Maintainer-local overlays (not part of upstream contribution contract)
+.local/
+.agent/
+.claude.json
+
+# Python caches
+__pycache__/
+*.pyc
+
 # Credentials & runtime state
 .env
 .env.local
@@ -14,3 +23,7 @@ sync-log.json
 
 # Build artifacts
 deno.lock
+docs/walkthroughs/*/public/
+docs/assets/agent-memory/promotional/generated-backgrounds/**/result.json
+docs/assets/agent-memory/screenshots/**/.chrome-*/
+integrations/openclaw-agent-memory/dist/
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,20 @@
+# OB1 Agent Instructions
+
+## Required Step: Update Linear
+
+- For feature work tied to a Linear issue, update Linear at the start of the work, at meaningful checkpoints, and before handing back to the user.
+- Use the parent issue as the living implementation log and keep child issues aligned with the files and behavior being changed.
+- For the OB1 Agent Memory / OpenClaw launch work, the parent issue is `NAT-833`. Record architecture notes, implementation milestones, blockers, and verification results there.
+- Do not wait until the end to document decisions. If a decision changes schema, API contract, trust policy, user-facing workflow, or publishing path, capture it in Linear while it is still fresh.
+
+## Agent Memory Product Guardrails
+
+- Keep `OB1 Agent Memory` runtime-neutral. OpenClaw is the flagship launch runtime, not the product boundary.
+- Treat inferred or generated memory as evidence by default. Instruction-grade memory requires human confirmation or trusted import.
+- Avoid raw transcript, model reasoning trace, secret, and large-code-block storage by default.
+- Avoid profanity in all content. Keep docs, examples, seed data, UI copy, prompts, walkthroughs, and generated assets clean and professional.
+- Prefer diagram-first documentation for this work: diagram, short explanation, copy-paste setup, then deeper reference.
+- Carry Nate B. Jones / OB1 provenance through product surfaces, docs, diagrams, screenshots, and starter seed data. Keep it subtle and useful: micro-branding, source labels, logo marks, and provenance language instead of loud marketing copy.
+- Treat public OB1 assets as helpful-first audience growth for Nate Jones. Every public guide, recipe, tutorial, package page, release note, and walkthrough should point back to Nate's Substack and site in a natural way: https://substack.com/@natesnewsletter and https://natebjones.com.
+- Make the case by being genuinely useful. The CTA should feel earned: "Nate gives away practical systems like this" rather than generic marketing copy.
+- For ClawHub/OpenClaw publishing, do not fall back to Jonathan's personal handle or any non-Nate namespace. If `@natebjones` / Nate OB1 ownership is not available, stop and record the blocker.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -30,6 +30,7 @@ Every contribution lives in its own subfolder under the right category and must
 - **No credentials, API keys, or secrets in any file.** Use environment variables.
 - **No binary blobs** over 1MB. No `.exe`, `.dmg`, `.zip`, `.tar.gz`.
 - **No `DROP TABLE`, `DROP DATABASE`, `TRUNCATE`, or unqualified `DELETE FROM`** in SQL files.
+- **Avoid profanity in all content.** Keep docs, examples, seed data, UI copy, prompts, walkthroughs, and generated assets clean and professional.
 - **MCP servers must be remote (Supabase Edge Functions), not local.** Never use `claude_desktop_config.json`, `StdioServerTransport`, or local Node.js servers. All extensions deploy as Edge Functions and connect via Claude Desktop's custom connectors UI (Settings → Connectors → Add custom connector → paste URL). See `docs/01-getting-started.md` Step 7 for the pattern.
 
 ## PR Standards
@@ -47,3 +48,12 @@ Every contribution lives in its own subfolder under the right category and must
 - `.github/metadata.schema.json` — JSON schema for metadata.json validation
 - `.github/PULL_REQUEST_TEMPLATE.md` — PR description template
 - `LICENSE.md` — FSL-1.1-MIT terms
+
+## Local GSD Execution Layer
+
+This repo also has a maintainer-local GSD layer in `.planning/`.
+
+- If `.planning/` exists, use it for local brownfield planning and phased execution.
+- Start with `.planning/STATE.md`, then read `.planning/PROJECT.md`, `.planning/ROADMAP.md`, and the relevant `.planning/codebase/*.md` documents.
+- Keep `.planning/` local. It is gitignored intentionally and is not part of the public contribution contract or upstream PR scope.
+- Public contributor rules still come from `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, and the committed repo files.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -128,6 +128,7 @@ grant select, insert, update, delete on table public.your_table to service_role;
 - **"Cross-Extension Integration"** prominently documenting connections to other extensions
 - **"Next Steps"** linking to the next extension
 - **Tool audit link** — Any extension or integration that exposes MCP tools must link to the [MCP Tool Audit & Optimization Guide](docs/05-tool-audit.md) in its "Next Steps" or closing section. This helps users manage their tool surface area as they add extensions. The link is checked by the automated review.
+- **MCP tool annotations** — Any extension or integration that exposes MCP tools must mark read-only tools with `annotations: { readOnlyHint: true }` and write tools with `annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false }` unless the tool really can touch arbitrary external resources or destroy data. ChatGPT uses this metadata to distinguish read tools from write actions.
 - **Remote MCP setup** — MCP servers must be deployed as Supabase Edge Functions and connected via custom connectors (URL-based). Do NOT use local Node.js servers or `claude_desktop_config.json`. See the [extension template](extensions/_template/) for the correct pattern.
 
 **Primitives** additionally require:
@@ -298,3 +299,4 @@ Every PR is checked against these rules. All must pass before human review.
 13. **Internal links** — All relative links in READMEs resolve to existing files
 14. **Remote MCP pattern** — Extensions and integrations must use remote MCP via Supabase Edge Functions. No `claude_desktop_config.json`, no local Node.js stdio servers. See the [Getting Started guide](docs/01-getting-started.md) for the correct pattern
 15. **Tool audit link** — Extensions and integrations must link to the [MCP Tool Audit & Optimization Guide](docs/05-tool-audit.md) in their README. This ensures users are aware of tool surface area management as they add capabilities
+16. **MCP tool annotations** — Read-only tools include `readOnlyHint: true`; write tools include `readOnlyHint: false`, `openWorldHint`, and `destructiveHint`
diff --git a/README.md b/README.md
@@ -94,6 +94,9 @@ Standalone capabilities that make your Open Brain smarter.
 | [Work Operating Model Activation](recipes/work-operating-model-activation/) | Conversation-first workflow that turns tacit work patterns into structured Open Brain records and agent-ready operating files | [@jonathanedwards](https://github.com/jonathanedwards) |
 | [World Model Diagnostic Activation](recipes/world-model-diagnostic-activation/) | Ship-now activation path for a 20-minute world-model readiness diagnostic that compounds through core Open Brain capture | [@jonathanedwards](https://github.com/jonathanedwards) |
 | [Research-to-Decision Workflow](recipes/research-to-decision-workflow/) | Composition recipe that chains canonical skills into operator and investor research, synthesis, meeting, and memo workflows | [@NateBJones](https://github.com/NateBJones) |
+| [OpenClaw Agent Memory for OB1](recipes/openclaw-agent-memory/) | Canonical recipe for using OB1 Agent Memory as the governed continuity layer for OpenClaw workflows | OB1 Team |
+| [OpenClaw Code Review Memory](recipes/openclaw-code-review-memory/) | Flagship workflow for compounding repo-specific review lessons, maintainer corrections, and false positives | OB1 Team |
+| [OpenClaw TaskFlow Work Log](recipes/openclaw-taskflow-work-log/) | Durable handoff recipe for long-running OpenClaw TaskFlows across agents, models, and channels | OB1 Team |
 
 ### [`/skills`](skills/) — Agent Skills
 
@@ -111,6 +114,7 @@ Plain-text skill packs you can drop into Claude Code, Codex, or other AI clients
 | [Aiception Skill Pack (formerly Claudeception)](skills/claudeception/) | Extracts reusable lessons from work sessions into new skills | [@jaredirish](https://github.com/jaredirish) |
 | [Work Operating Model Skill Pack](skills/work-operating-model/) | Runs a five-layer elicitation interview and saves the approved operating model into Open Brain | [@jonathanedwards](https://github.com/jonathanedwards) |
 | [World Model Readiness Diagnostic](skills/world-model-diagnostic/) | Runs a 20-minute world-model diagnostic that maps paradigm fit, audits the boundary layer, and labels findings by confidence | [@jonathanedwards](https://github.com/jonathanedwards) |
+| [OpenClaw Agent Memory Skill Pack](skills/openclaw-agent-memory/) | Teaches OpenClaw agents to recall, write back, report usage, and respect OB1 provenance/use-policy rules | OB1 Team |
 
 ### [`/dashboards`](dashboards/) — Frontend Templates
 
@@ -128,9 +132,19 @@ MCP server extensions, alternative deployment targets, and capture sources beyon
 | Integration | What It Does | Contributor |
 | ----------- | ------------ | ----------- |
 | [Kubernetes Deployment](integrations/kubernetes-deployment/) | Fully self-hosted K8s deployment with PostgreSQL + pgvector — no Supabase required | [@velo](https://github.com/velo) |
+| [Agent Memory API](integrations/agent-memory-api/) | Runtime-neutral recall, write-back, review, inspector, and recall-trace API for OB1 Agent Memory | OB1 Team |
+| [OpenClaw Agent Memory](integrations/openclaw-agent-memory/) | OpenClaw plugin and publishing package for using OB1 Agent Memory from OpenClaw workflows | OB1 Team |
 | [Slack Capture](integrations/slack-capture/) | Quick-capture thoughts via Slack messages with auto-embedding and classification | Core |
 | [Discord Capture](integrations/discord-capture/) | Discord bot that captures messages into Open Brain, mirroring the Slack pattern | Core |
 
+### [`/schemas`](schemas/) — Database Extensions
+
+Tables and sidecars that extend the base `thoughts` model without replacing it.
+
+| Schema | What It Does | Contributor |
+| ------ | ------------ | ----------- |
+| [Agent Memory](schemas/agent-memory/) | Provenance, review, use-policy, source-reference, relation, recall-trace, and audit sidecars for agent workflow memory | OB1 Team |
+
 ### [`/primitives`](primitives/) — Reusable Patterns
 
 | Primitive | What It Does | Contributor |

diff --git a/dashboards/open-brain-dashboard-next/.env.example b/dashboards/open-brain-dashboard-next/.env.example
@@ -1,10 +1,28 @@
 # Required: URL of your Open Brain REST API
 NEXT_PUBLIC_API_URL=https://YOUR-PROJECT-REF.supabase.co/functions/v1/open-brain-rest
 
+# Optional: URL of your OB1 Agent Memory API.
+# If omitted, the dashboard derives it from NEXT_PUBLIC_API_URL by replacing open-brain-rest with agent-memory-api.
+# AGENT_MEMORY_API_URL=https://YOUR-PROJECT-REF.supabase.co/functions/v1/agent-memory-api
+
+# Optional: default Agent Memory scope for the dashboard governance views.
+# AGENT_MEMORY_WORKSPACE_ID=ob1-staging
+# AGENT_MEMORY_PROJECT_ID=
+
 # Required: 32+ character secret for iron-session cookie encryption
 # Generate with: openssl rand -hex 32
 SESSION_SECRET=
 
+# Optional: force HTTPS-only auth cookies. Leave unset for localhost previews.
+# Set to true on HTTPS hosts if NEXT_PUBLIC_APP_URL/APP_URL is not configured.
+# AUTH_COOKIE_SECURE=true
+
+# Optional: local walkthrough/screenshot mode only.
+# Bypasses login and uses this demo key against a local demo REST shim.
+# Never enable this in a shared preview or production deployment.
+# OB1_DEMO_AUTH_BYPASS=false
+# OB1_DASHBOARD_DEMO_KEY=local-screenshot-key
+
 # Optional: SHA-256 hash of passphrase to unlock restricted/sensitive content
 # Requires the sensitivity-tiers primitive (sensitivity_tier column on thoughts)
 # Generate with: echo -n "your-passphrase" | shasum -a 256

diff --git a/dashboards/open-brain-dashboard-next/README.md b/dashboards/open-brain-dashboard-next/README.md
@@ -26,11 +26,12 @@ Provides 9 pages for managing your thoughts:
 | **Add to Brain** | Smart ingest with auto-routing — short text goes to single capture, long text to extraction with dry-run preview |
 | **Audit** | Quality review for low-score thoughts with bulk delete |
 | **Duplicates** | Semantic similarity detection with keep/delete/keep-both resolution |
+| **Agent Memory** | Review queue, memory inspector, and recall trace debugging for OB1 Agent Memory |
 | **Login** | API key authentication via encrypted session cookie |
 
 ## Prerequisites
 
-- A working Open Brain setup with the **REST API gateway** (`open-brain-rest`) deployed
+- A working Open Brain setup with the **REST API gateway** (`open-brain-rest`) deployed from [integrations/open-brain-rest](../../integrations/open-brain-rest/)
 - **Node.js 18+** installed
 - A **Vercel account** (free tier works) or any Node.js hosting
 
@@ -39,7 +40,13 @@ Provides 9 pages for managing your thoughts:
 | Credential | Where to get it | Where it goes |
 |------------|----------------|---------------|
 | `NEXT_PUBLIC_API_URL` | Your Supabase project URL + `/functions/v1/open-brain-rest` | `.env` or hosting env vars |
+| `AGENT_MEMORY_API_URL` | Optional. Your Supabase project URL + `/functions/v1/agent-memory-api` | `.env` or hosting env vars |
+| `AGENT_MEMORY_WORKSPACE_ID` | Optional. Default workspace for Agent Memory governance views | `.env` or hosting env vars |
+| `AGENT_MEMORY_PROJECT_ID` | Optional. Default project filter for Agent Memory governance views | `.env` or hosting env vars |
 | `SESSION_SECRET` | Generate: `openssl rand -hex 32` | `.env` or hosting env vars |
+| `AUTH_COOKIE_SECURE` | Optional. Force HTTPS-only auth cookies when set to `true`; leave unset for localhost previews | `.env` or hosting env vars |
+| `OB1_DEMO_AUTH_BYPASS` | Optional. Local walkthrough capture only; bypasses login when set to `true` | local shell only |
+| `OB1_DASHBOARD_DEMO_KEY` | Optional. Local walkthrough capture key used by the demo REST shim | local shell only |
 | `RESTRICTED_PASSPHRASE_HASH` | Optional. Generate: `echo -n "passphrase" \| shasum -a 256` | `.env` or hosting env vars |
 
 ## Steps
@@ -69,7 +76,12 @@ Edit `.env` and set your values:
 
 ```
 NEXT_PUBLIC_API_URL=https://YOUR-PROJECT-REF.supabase.co/functions/v1/open-brain-rest
+# Optional if your Agent Memory function follows the standard slug:
+# AGENT_MEMORY_API_URL=https://YOUR-PROJECT-REF.supabase.co/functions/v1/agent-memory-api
+# AGENT_MEMORY_WORKSPACE_ID=ob1-staging
 SESSION_SECRET=your-32-char-secret-here
+# Optional on HTTPS hosts:
+# AUTH_COOKIE_SECURE=true
 ```
 
 ### Step 4: Run locally
@@ -103,6 +115,7 @@ When working correctly:
 - **Search** returns results with similarity scores (semantic mode) or rank scores (full-text mode)
 - **Add to Brain** auto-routes short text (< 500 chars, single paragraph) to single capture, and long/structured text to extraction with dry-run preview
 - **Detail page** shows full thought content with metadata, inline edit for content/type/importance, and linked reflections
+- **Agent Memory** shows pending agent-written memories, lets you confirm/evidence-only/reject them, inspects provenance/source data, and loads recall traces by request id
 
 ## Workflow Board
 
@@ -162,9 +175,22 @@ The dashboard calls these endpoints on your Open Brain REST API:
 | `/thoughts?type=task` | GET | Workflow board (filtered by type) |
 | `/thought/:id` | PUT | Workflow board (status/priority updates) |
 
+Agent Memory pages also call these endpoints on `agent-memory-api`:
+
+| Endpoint | Method | Used By |
+|----------|--------|---------|
+| `/memories` | GET | Agent Memory list by status/scope |
+| `/memories/review` | GET | Pending review queue |
+| `/memories/:id` | GET | Memory inspector |
+| `/memories/:id/review` | PATCH | Confirm, evidence-only, reject, stale, or restrict memory |
+| `/recall-traces/:request_id` | GET | Recall trace debugger |
+
 > [!NOTE]
 > If your Open Brain instance doesn't have all these endpoints (e.g., no smart-ingest or duplicates), those pages will show errors but the core pages (dashboard, browse, search, detail) will still work.
 
+> [!IMPORTANT]
+> OB1's real `thoughts.id` values are UUID strings. The dashboard treats thought IDs as strings end to end so detail links, workflow updates, audit deletes, and duplicate resolution work against production Supabase rows.
+
 ## Optional: Restricted Content
 
 If you've applied the [sensitivity-tiers](https://github.com/NateBJones-Projects/OB1/pull/110) primitive and want to control access to sensitive thoughts:
@@ -188,6 +214,21 @@ The dashboard uses **iron-session** for encrypted HTTP-only session cookies:
 
 No API key is stored in environment variables or exposed to the browser.
 
+## Local Walkthrough Capture
+
+The walkthrough asset pipeline lives in [docs/walkthroughs/ob1-agent-dashboard](../../docs/walkthroughs/ob1-agent-dashboard). It seeds the Dashboard, Thoughts, Workflow, Duplicates, Audit, Agent Memory, and Recall Trace surfaces with Nate B. Jones / OB1 demo data for screenshots, PDF guides, and video walkthroughs.
+
+The dashboard has a gated local-only bypass for that capture flow:
+
+```bash
+OB1_DEMO_AUTH_BYPASS=true
+OB1_DASHBOARD_DEMO_KEY=local-screenshot-key
+NEXT_PUBLIC_API_URL=http://127.0.0.1:3024
+AGENT_MEMORY_API_URL=http://127.0.0.1:3022
+```
+
+Do not enable `OB1_DEMO_AUTH_BYPASS` in shared previews or production. It exists so repeatable screenshot and video generation can run without putting real API keys in browser automation.
+
 ## Tech Stack
 
 - **Next.js 16** (App Router)