1 Commits

Author SHA1 Message Date
52398c97d9 docs(PRD): remove hardcoded instance URLs — plugin must be user-configured
No hardcoded brain.woltje.com or any specific host.
baseUrl + apiKey required; missing = OpenBrainConfigError at bootstrap.
2026-03-06 08:12:50 -06:00

View File

@@ -7,7 +7,7 @@
## Problem Statement ## Problem Statement
OpenClaw compacts context when sessions grow long, causing information loss. The new `ContextEngine` plugin interface (merged in PR #22201) allows replacing the default compaction strategy with a persistent, lossless alternative. OpenBrain (brain.woltje.com) is a live pgvector + REST API service that can store and semantically retrieve conversation context indefinitely. OpenClaw compacts context when sessions grow long, causing information loss. The new `ContextEngine` plugin interface (merged in PR #22201) allows replacing the default compaction strategy with a persistent, lossless alternative. OpenBrain is a self-hosted pgvector + REST API service that can store and semantically retrieve conversation context indefinitely.
## Solution ## Solution
@@ -20,8 +20,8 @@ lossless-claw (https://github.com/Martian-Engineering/lossless-claw) is the prim
## OpenBrain API ## OpenBrain API
``` ```
Base: https://brain.woltje.com Base: <user-configured — OPENBRAIN_URL env var or plugin config.baseUrl — NO DEFAULT>
Auth: Bearer <OPENBRAIN_API_KEY> Auth: Bearer <OPENBRAIN_API_KEY env var or plugin config.apiKey — NO DEFAULT>
POST /v1/thoughts { content, source, metadata } POST /v1/thoughts { content, source, metadata }
POST /v1/search { query, limit } POST /v1/search { query, limit }
@@ -85,8 +85,8 @@ export function register(api: OpenClawPluginApi) {
"openclaw-openbrain-context": { "openclaw-openbrain-context": {
"enabled": true, "enabled": true,
"config": { "config": {
"baseUrl": "https://brain.woltje.com", "baseUrl": "https://your-openbrain-instance.example.com",
"apiKey": "${OPENBRAIN_API_KEY}", "apiKey": "your-api-key",
"recentMessages": 20, "recentMessages": 20,
"semanticSearchLimit": 10, "semanticSearchLimit": 10,
"source": "openclaw" "source": "openclaw"
@@ -103,15 +103,27 @@ export function register(api: OpenClawPluginApi) {
- openclaw/plugin-sdk for ContextEngine interface - openclaw/plugin-sdk for ContextEngine interface
- pnpm, vitest, ESLint - pnpm, vitest, ESLint
## ⚠️ Hard Rule: No Hardcoded Instance Values
This plugin will be used by anyone running their own OpenBrain instance. The following are STRICTLY FORBIDDEN in source code, defaults, or fallback logic:
- Any hardcoded URL (no `brain.woltje.com` or any other specific domain)
- Any hardcoded API key
- Any `process.env.OPENBRAIN_URL || 'https://brain.woltje.com'` fallback patterns
Required behavior:
- `baseUrl` and `apiKey` MUST be provided via plugin config or env vars
- If either is missing, throw `OpenBrainConfigError` at `bootstrap()` time with a clear message: "openclaw-openbrain-context: baseUrl and apiKey are required. Set them in your openclaw.json plugin config."
- No silent degradation, no defaults to any specific host
## Acceptance Criteria (v0.0.1) ## Acceptance Criteria (v0.0.1)
1. Plugin registers as a ContextEngine with id `openbrain` 1. Plugin registers as a ContextEngine with id `openbrain`
2. `ingest()` stores messages to OpenBrain with correct metadata 2. `ingest()` stores messages to OpenBrain with correct metadata
3. `assemble()` retrieves recent + semantically relevant context within token budget 3. `assemble()` retrieves recent + semantically relevant context within token budget
4. `compact()` archives turn summary, returns minimal prompt-injection 4. `compact()` archives turn summary, returns minimal prompt-injection
5. `bootstrap()` loads prior session context on restart 5. `bootstrap()` loads prior session context on restart; throws `OpenBrainConfigError` if config missing
6. Tests pass, TypeScript strict, ESLint clean 6. Tests pass, TypeScript strict, ESLint clean
7. openclaw.plugin.json with correct manifest 7. openclaw.plugin.json with correct manifest
8. README: install + config + usage 8. README documents: self-host OpenBrain setup, all config options with types/defaults, env var pattern, example config
## ASSUMPTION: ContextEngine interface shape ## ASSUMPTION: ContextEngine interface shape
Based on lossless-claw source and PR #22201. Plugin SDK import path: `openclaw/plugin-sdk`. Based on lossless-claw source and PR #22201. Plugin SDK import path: `openclaw/plugin-sdk`.