# Tasks: Cerebro

## Phase 1: Infrastructure

- [x] 1.1 Add Cerebro workspace crate skeleton at `clients/cerebro/` (add `Cargo.toml`,
  `src/main.rs`, `src/lib.rs`) and register it in root workspace members.
- [x] 1.2 Define Cerebro service config schema and defaults in `clients/cerebro/src/config.rs`
  (host/port, auth token, storage mode, worker toggles).
- [x] 1.3 Remove SurrealDB feature/dependency from `clients/agent-runtime/Cargo.toml` and delete
  `clients/agent-runtime/src/memory/surreal.rs`.
- [x] 1.4 Remove SurrealDB backend wiring from `clients/agent-runtime/src/memory/mod.rs` and
  `clients/agent-runtime/src/memory/backend.rs`.
- [x] 1.5 Update runtime config schema in `clients/agent-runtime/src/config/schema.rs` to drop
  SurrealDB fields and add MCP memory endpoint settings (URL, auth token, timeout,
  `allow_insecure`).

## Phase 2: Implementation (TDD)

- [x] 2.1 RED: Add failing config validation tests for legacy Surreal config and insecure MCP
  endpoints in `clients/agent-runtime/tests/mcp_config_validation.rs`.
- [x] 2.2 GREEN: Implement runtime config validation in
  `clients/agent-runtime/src/config/schema.rs` (and helpers in
  `clients/agent-runtime/src/config/mod.rs` if needed) to pass the new tests.
- [x] 2.3 REFACTOR: Normalize config error messages and reuse shared validation helpers in
  `clients/agent-runtime/src/config/mod.rs`.
- [x] 2.4 RED: Add failing tests for legacy tool aliasing and missing Cerebro endpoint errors in
  `clients/agent-runtime/tests/memory_cerebro_aliases.rs`.
- [x] 2.5 GREEN: Route `memory_store`, `memory_recall`, `memory_forget` through MCP adapters in
  `clients/agent-runtime/src/tools/memory_store.rs`,
  `clients/agent-runtime/src/tools/memory_recall.rs`, and
  `clients/agent-runtime/src/tools/memory_forget.rs`, using
  `clients/agent-runtime/src/tools/mcp/adapter.rs` for MCP calls.
- [x] 2.6 REFACTOR: Centralize alias mapping and response normalization in
  `clients/agent-runtime/src/tools/mcp/normalize.rs` (or a new helper module).
- [x] 2.7 RED: Add failing backend selection tests (MCP vs local, no SurrealDB) in
  `clients/agent-runtime/tests/memory_backend_selection.rs`.
- [x] 2.8 GREEN: Update backend selection in `clients/agent-runtime/src/agent/memory_loader.rs` and
  `clients/agent-runtime/src/memory/mod.rs` to prefer MCP when configured and keep local short-term
  otherwise.
- [x] 2.9 REFACTOR: Remove dead memory backend branches and update related trait docs in
  `clients/agent-runtime/src/memory/traits.rs`.
- [x] 2.10 RED: Add failing MCP tool contract tests for Cerebro (input validation, soft-delete
  behavior, drill-in recall) in `clients/cerebro/tests/mcp_tools_contract.rs`.
- [x] 2.11 GREEN: Implement Cerebro MCP handlers and storage abstractions in
  `clients/cerebro/src/` (e.g., `server.rs`, `tools.rs`, `storage/`) to satisfy tool contract tests.
- [x] 2.12 REFACTOR: Extract shared validation and error mapping into
  `clients/cerebro/src/validation.rs` and `clients/cerebro/src/errors.rs`.
- [x] 2.13 RED: Add failing tests to ensure memory_store blocks sensitive data before MCP calls.
- [x] 2.14 GREEN: Implement local sensitive-data guard in
  `clients/agent-runtime/src/tools/memory_store.rs`.
- [x] 2.15 REFACTOR: Keep guard logic lightweight and deterministic with clear error messaging.

## Phase 3: Testing

- [x] 3.1 Add MCP round-trip integration test between runtime and Cerebro in
  `clients/agent-runtime/tests/memory_cerebro_integration.rs`.
- [x] 3.2 Add security tests for endpoint policy and auth token requirements in
  `clients/agent-runtime/tests/mcp_config_validation.rs` and
  `clients/cerebro/tests/mcp_auth_policy.rs`.
- [x] 3.3 Run `cargo fmt --all -- --check` to verify code formatting compliance (or document why
  this
  check was skipped in test log notes).
- [x] 3.4 Run `cargo clippy --all-targets -- -D warnings` to verify linting compliance (or document
  why this check was skipped in test log notes).
- [x] 3.5 Run `cargo test` (or `make test`) and capture results for formatting (3.3), linting (3.4),
  and all test suites in the test log notes, explaining which checks were intentionally omitted if
  any.

## Phase 4: Documentation

- [x] 4.1 Create a migration guide at
  `clients/web/apps/docs/src/content/docs/guides/cerebro/migration.md` with secure defaults and
  Cerebro MCP configuration guidance (link `openspec/changes/cerebro/cerebro.md` for narrative
  context).
- [x] 4.2 Update `clients/agent-runtime/README.md` with Cerebro MCP configuration, secure defaults,
  legacy tool alias behavior, and links to the migration guide and MCP schemas.
- [x] 4.3 Update `clients/agent-runtime/examples/custom_memory.rs` to reflect MCP-backed long-term
  memory usage and link the migration guide.
- [x] 4.4 Update root `README.md` to note the new `clients/cerebro` module, removal of the
  SurrealDB memory backend, and links to the migration guide and MCP schemas.
- [x] 4.5 Add machine-readable JSON schema files for the 13 Cerebro tools in
  `clients/web/apps/docs/src/content/docs/guides/cerebro/mcp-schema/`, and link them from the
  READMEs (reference `openspec/changes/cerebro/cerebro.md` for narrative details).
- [x] 4.6 Tighten MCP JSON schema constraints (minLength, maximums, timestamps, enums).
- [x] 4.7 Update the migration guide with parity notice + expanded checklist.
- [x] 4.8 Update Cerebro spec + root README for loopback opt-in and Surreal removal.

## Phase 5: Verification Gaps

- [x] 5.1 Add secure endpoint happy-path validation tests for https/wss.
- [x] 5.2 Add tests ensuring local-only memory operations do not emit MCP calls.
- [x] 5.3 Add runtime tests confirming SurrealDB backend removal (local + MCP only).
- [x] 5.4 Update verification report with coverage guidance and new test evidence.
- [x] 5.5 Add ws insecure endpoint validation test.
- [x] 5.6 Reformat verification report code blocks with language tags.
