feat(agent-runtime): add SurrealDB memory backend and secure wizard flow

clients/agent-runtime/Cargo.toml

@@ -82,6 +82,7 @@ prost = { version = "0.14", default-features = false }
 
 # Memory / persistence
 rusqlite = { version = "0.38", features = ["bundled"] }
+surrealdb = { version = "2.3", optional = true, default-features = false, features = ["protocol-ws", "rustls"] }
 chrono = { version = "0.4", default-features = false, features = ["clock", "std", "serde"] }
 chrono-tz = "0.10"
 cron = "0.15"
@@ -151,6 +152,8 @@ landlock = ["sandbox-landlock"]
 probe = ["dep:probe-rs"]
 # rag-pdf = PDF ingestion for datasheet RAG
 rag-pdf = ["dep:pdf-extract"]
+# memory-surreal = SurrealDB-backed memory backend
+memory-surreal = ["dep:surrealdb"]
 [profile.release]
 opt-level = "z"      # Optimize for size
 lto = "thin"         # Lower memory use during release builds

clients/agent-runtime/README.md

@@ -73,6 +73,9 @@ cd corvus
 cargo build --release
 cargo install --path . --force
 
+# Enable SurrealDB memory backend support
+cargo build --release --features memory-surreal
+
 # Quick setup (no prompts)
 corvus onboard --api-key sk-... --provider openrouter
 
@@ -131,7 +134,7 @@ Every subsystem is a **trait** — swap implementations with a config change, ze
 |-------------------|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------|
 | **AI Models**     | `Provider`       | 22+ providers (OpenRouter, Anthropic, OpenAI, Ollama, Venice, Groq, Mistral, xAI, DeepSeek, Together, Fireworks, Perplexity, Cohere, Bedrock, etc.) | `custom:https://your-api.com` — any OpenAI-compatible API |
 | **Channels**      | `Channel`        | CLI, Telegram, Discord, Slack, iMessage, Matrix, WhatsApp, Webhook                                                                                  | Any messaging API                                         |
-| **Memory**        | `Memory`         | SQLite with hybrid search (FTS5 + vector cosine similarity), Markdown                                                                               | Any persistence backend                                   |
+| **Memory**        | `Memory`         | SQLite (hybrid search), SurrealDB (feature: `memory-surreal`), Markdown                                                                              | Any persistence backend                                   |
 | **Tools**         | `Tool`           | shell, file_read, file_write, memory_store, memory_recall, memory_forget, browser_open (Brave + allowlist), composio (optional)                     | Any capability                                            |
 | **Observability** | `Observer`       | Noop, Log, Multi                                                                                                                                    | Prometheus, OTel                                          |
 | **Runtime**       | `RuntimeAdapter` | Native, Docker (sandboxed)                                                                                                                          | WASM (planned; unsupported kinds fail fast)               |
@@ -168,11 +171,17 @@ The agent automatically recalls, saves, and manages memory via tools.
 
 ```toml
 [memory]
-backend = "sqlite"          # "sqlite", "markdown", "none"
+backend = "sqlite"          # "sqlite", "lucid", "surreal", "markdown", "none"
 auto_save = true
 embedding_provider = "openai"
 vector_weight = 0.7
 keyword_weight = 0.3
+
+[memory.surreal]
+url = "http://127.0.0.1:8000"
+namespace = "corvus"
+database = "memory"
+allow_http_loopback = true
 ```
 
 ## Security
@@ -263,7 +272,8 @@ WhatsApp uses Meta's Cloud API with webhooks (push-based, not polling):
 
 ## Configuration
 
-Config: `~/.corvus/config.toml` (created by `onboard`)
+Config: `~/.corvus/config.toml` (created by `onboard`; wizard now includes SurrealDB prompts when
+available)
 
 ```toml
 api_key = "sk-..."
@@ -272,12 +282,21 @@ default_model = "anthropic/claude-sonnet-4-20250514"
 default_temperature = 0.7
 
 [memory]
-backend = "sqlite"              # "sqlite", "markdown", "none"
+backend = "sqlite"              # "sqlite", "lucid", "surreal", "markdown", "none"
 auto_save = true
 embedding_provider = "openai"   # "openai", "noop"
 vector_weight = 0.7
 keyword_weight = 0.3
 
+[memory.surreal]
+url = "http://127.0.0.1:8000"
+namespace = "corvus"
+database = "memory"
+# username = "corvus"
+# password = "corvus-pass"
+# token = "..."                  # preferred over username/password when set
+allow_http_loopback = true
+
 [gateway]
 require_pairing = true          # require pairing code on first connect
 allow_public_bind = false       # refuse 0.0.0.0 without tunnel
@@ -323,6 +342,19 @@ format = "openclaw"             # "openclaw" (default, markdown files) or "aieos
 # aieos_inline = '{"identity":{"names":{"first":"Nova"}}}'  # inline AIEOS JSON
 ```
 
+SurrealDB environment overrides (env-first):
+
+```bash
+export CORVUS_MEMORY_BACKEND=surreal
+export CORVUS_SURREALDB_URL=http://127.0.0.1:8000
+export CORVUS_SURREALDB_NAMESPACE=corvus
+export CORVUS_SURREALDB_DATABASE=memory
+export CORVUS_SURREALDB_USERNAME=corvus
+export CORVUS_SURREALDB_PASSWORD=your-password-here
+# optional:
+export CORVUS_SURREALDB_TOKEN=...
+```
+
 ## Identity System (AIEOS Support)
 
 Corvus supports **identity-agnostic** AI personas through two formats:
@@ -408,7 +440,7 @@ See [aieos.org](https://aieos.org) for the full schema and live examples.
 | Command                                       | Description                                             |
 |-----------------------------------------------|---------------------------------------------------------|
 | `onboard`                                     | Quick setup (default)                                   |
-| `onboard --interactive`                       | Full interactive 7-step wizard                          |
+| `onboard --interactive`                       | Full interactive 7-step wizard (includes memory backend + Surreal options) |
 | `onboard --channels-only`                     | Reconfigure channels/allowlists only (fast repair flow) |
 | `agent -m "..."`                              | Single message mode                                     |
 | `agent`                                       | Interactive chat mode                                   |

clients/agent-runtime/docker-compose.yml

@@ -27,6 +27,15 @@ services:
 
       # Optional: Model override
       # - CORVUS_MODEL=anthropic/claude-sonnet-4-20250514
+
+      # Optional: Memory backend override
+      # - CORVUS_MEMORY_BACKEND=surreal
+      # - CORVUS_SURREALDB_URL=http://surrealdb:8000
+      # - CORVUS_SURREALDB_NAMESPACE=corvus
+      # - CORVUS_SURREALDB_DATABASE=memory
+      # - CORVUS_SURREALDB_USERNAME=corvus
+      # - CORVUS_SURREALDB_PASSWORD=corvus-pass
+      # - CORVUS_SURREALDB_TOKEN=
 
     volumes:
       # Persist workspace and config
@@ -44,5 +53,13 @@ services:
       retries: 3
       start_period: 10s
 
+  # Optional local SurrealDB for memory backend testing/development
+  surrealdb:
+    image: surrealdb/surrealdb:v2.3
+    command: start --log info --user ${SURREALDB_USER:-corvus} --pass ${SURREALDB_PASS:-corvus-pass} memory
+    profiles: ["surreal"]
+    ports:
+      - "8000:8000"
+
 volumes:
   corvus-data:

clients/agent-runtime/src/config/mod.rs

@@ -9,8 +9,8 @@ pub use schema::{
     LarkConfig, MatrixConfig, MemoryConfig, ModelRouteConfig, ObservabilityConfig,
     PeripheralBoardConfig, PeripheralsConfig, QueryClassificationConfig, ReliabilityConfig,
     ResourceLimitsConfig, RuntimeConfig, SandboxBackend, SandboxConfig, SchedulerConfig,
-    SecretsConfig, SecurityConfig, SlackConfig, StreamMode, TelegramConfig, TunnelConfig,
-    WebSearchConfig, WebhookConfig,
+    SecretsConfig, SecurityConfig, SlackConfig, StreamMode, SurrealMemoryConfig, TelegramConfig,
+    TunnelConfig, WebSearchConfig, WebhookConfig,
 };
 
 #[cfg(test)]