docs: Add specifications and design documents for Cerebro memory module#215
Merged
Merged
Conversation
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (1)
📜 Recent review details⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
🧰 Additional context used📓 Path-based instructions (2)**/*.{md,mdx}⚙️ CodeRabbit configuration file
Files:
**/*⚙️ CodeRabbit configuration file
Files:
🧠 Learnings (4)📓 Common learnings📚 Learning: 2026-02-17T12:31:17.076ZApplied to files:
📚 Learning: 2026-02-17T12:31:17.076ZApplied to files:
📚 Learning: 2026-02-17T12:31:17.076ZApplied to files:
🔇 Additional comments (1)
📝 WalkthroughSummary by CodeRabbit
WalkthroughAdds comprehensive documentation, design, proposal, specification, and agent docs for "Cerebro" — a new MCP (JSON‑RPC)–backed centralized long‑term memory module and migration plan that routes agent runtime memory tooling through Cerebro and removes the SurrealDB backend flag. Changes
Sequence Diagram(s)sequenceDiagram
participant Agent as Agent Runtime
participant MCP as MCP (JSON‑RPC)
participant Cerebro as Cerebro Service
participant Store as Storage (e.g., Surreal/DB)
Agent->>MCP: tools.save_memory(session_id, memory_payload)
MCP->>Cerebro: Forward SaveMemory request
Cerebro->>Store: Persist memory + edges (async workers may enrich/index)
Store-->>Cerebro: ACK / persisted_id
Cerebro-->>MCP: Save result (persisted_id)
MCP-->>Agent: Return save confirmation
sequenceDiagram
participant Agent as Agent Runtime
participant MCP as MCP (JSON‑RPC)
participant Cerebro as Cerebro Service
participant Store as Storage (index/query)
Agent->>MCP: tools.recall_memory(query, ctx)
MCP->>Cerebro: Forward Recall request
Cerebro->>Store: Query memories + compute relevance
Store-->>Cerebro: Matching memories
Cerebro-->>MCP: Ranked memories / response
MCP-->>Agent: Return recalled memories
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
✅ Contributor ReportUser: @yacosta738
Contributor Report evaluates based on public GitHub activity. Analysis period: 2025-03-13 to 2026-03-13 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 26
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.agents/AGENTS.md:
- Around line 155-166: Update the "Cerebro Memory Module" section to include
explicit version and compatibility details and clear configuration steps: add a
"Version & Compatibility" subheading listing the Cerebro semantic version, the
minimum and tested agent-runtime versions, and any breaking changes; add a
"Configuration & Enabling" subheading that documents how to enable MCP
integration (referencing the MCP JSON-RPC tools), required config
keys/environment variables, example agent config flags, and where to find the
full API in openspec/changes/cerebro/cerebro.md; ensure references to "session",
"memory", "prompt", and the MCP tools are preserved so readers can locate
related behavior and tooling.
In `@openspec/changes/cerebro/cerebro.md`:
- Around line 155-165: Update the "## 12. Configuration" section to remove
direct mention of the SurrealDB backend: replace the backend selection bullet
that currently reads "backend selection (`sqlite`, `surreal`, etc.)" with an
explicit list such as local memory backends (sqlite, in-memory) and MCP-based
backends (Cerebro), and remove any reference to `surreal`; keep other bullets
unchanged so configuration reflects removal of direct SurrealDB access.
- Around line 135-154: Update the "11. Migration Path" Rollout policy entry
"dual-write or alias period" to explicitly define the alias period duration
(e.g., 2–4 weeks), clarify that "dual-write" means writes go to both targets
(SurrealDB and the new Cerebro memory backend such as
mem_save/mem_search/mem_delete), and specify a conflict resolution policy (e.g.,
source-of-truth preference, last-write-wins with monotonic timestamps or
optimistic version checks and abort/retry) plus monitoring/telemetry gates and a
rollback condition; add these details under the existing Rollout policy
paragraph so readers know timeframe, targets, conflict handling, and
observability requirements.
- Around line 14-24: Update the "Tech Stack (Current + Target)" section to
clarify SurrealDB usage by explicitly stating that Cerebro uses SurrealDB as its
internal storage while agent-runtime no longer accesses SurrealDB directly and
instead interacts with it only via the MCP protocol; modify the existing
"Current DB Integration: SurrealDB over remote WebSocket RPC" line into two
concise lines such as "Cerebro: SurrealDB used as internal storage (remote
WebSocket RPC for now)" and "agent-runtime: No direct SurrealDB access —
communicates via MCP only" so the distinction between Cerebro and agent-runtime
is unambiguous.
- Around line 35-50: Add a migration section that explicitly defines the
transition strategy: state that Cerebro will support dual schemas during
migration via a compatibility layer/adapter that reads from `memory_entries`,
`memory_events`, and `memory_relations` and exposes the new `session`, `memory`
(engram), and `prompt` node shapes; describe a concrete conversion mapping from
`memory_entries` -> `memory` (map fields into What/Why/Where/Learned + metadata
`scope`, `topic_key`, `type`), map `memory_relations` into relation edges
(`CREATED_IN`, `RELATES_TO`, `FOLLOWS`), and preserve `memory_events` as the
event log; include a plan for running a migration script (bulk + safe
incremental replay), validation checks, rollback strategy, and a clear timeline
for deprecation with feature-flagged rollout and expected cutover date for
retiring `memory_entries` and `memory_relations`.
- Around line 193-199: Update the "## 16. Deployment" section to remove the
obsolete reference to the `memory-surreal` feature flag and replace it with the
current Cerebro integration feature flags; specifically edit the bullet
"feature-gated builds (`memory-surreal` and related options)" to list the new
Cerebro-related feature flags (e.g., the Cerebro integration flags used in Cargo
or build scripts) and briefly note their purpose (integration vs. standalone),
keeping the rest of the deployment bullets unchanged and ensuring the phrase
`memory-surreal` is deleted or marked removed.
- Around line 166-173: Update the hyphenation in the Error Handling section:
change "Fail safe:" to "Fail-safe:" and change "No hard dependency on LLM:" to
"No hard dependency on LLMs:" (edit the text lines containing those exact
phrases in the Error Handling & Resilience block) to correct grammar while
leaving the rest of the content intact.
- Around line 97-101: The doc section "8. Agent Integration
(`prompt_template.md`)" is missing a specific location for the copy-paste system
prompt; update the text under that heading to point to a concrete file path (for
example docs/prompts/cerebro-memory.md or docs/prompts/prompt_template.md) so
readers know where to find the system prompt and examples; edit the "Agent
Integration (`prompt_template.md`)" paragraph in cerebro.md to include the
chosen file path and a short note that the prompt and examples live in that
file.
- Around line 102-121: The Module Strategy doc contradicts other docs about
Cerebro's location; reconcile and make a single authoritative decision and
update the texts accordingly: choose whether Cerebro will be a sub-crate under
clients/agent-runtime (clients/agent-runtime/crates/cerebro), a new top-level
module (modules/cerebro), or strictly "evolve in place" inside agent-runtime,
then update Decision Record in "Module Strategy (Decision Record)" to state that
chosen location and its extraction path, and edit tasks.md, proposal.md, and
design.md to match that decision (e.g., change tasks.md entry, proposal.md
module list, and design.md description "Cerebro (new module): Rust binary" to
the agreed wording) so all four documents are consistent.
In `@openspec/changes/cerebro/design.md`:
- Around line 56-76: Add a short authentication subsection to the Data Flow
describing where and how auth tokens are attached and validated: specify that
runtime tools (memory_store, mem_save, memory_recall, mem_search,
mem_get_observation, mem_session_start, mem_session_summary) must include bearer
tokens or API keys in the MCP adapter request headers, that the MCP adapter
validates tokens before forwarding to Cerebro, and that Cerebro enforces token
validation and permission checks for write/read/session operations and emits an
auth-failure event on invalid/expired tokens; mention where token renewal or
refresh should be handled (client/runtime) and that sensitive token handling
must be logged in auth-audit events.
- Around line 129-135: Update the "Error Handling" section to explicitly define
the retry policy for MCP calls: state a maximum retry count (e.g., 3-5
attempts), the backoff algorithm (e.g., exponential backoff with jitter), base
and max backoff durations, which error classes are retryable vs terminal (e.g.,
network/timeouts and 5xx vs 4xx client errors), and how client-side timeouts
interact with retries; reference "Save/search" and the MCP call flow by name so
readers know this applies to MCP calls from save/search operations and link or
point to a separate retry policy doc if full details are stored elsewhere.
- Around line 144-154: The "alias period" mention is underspecified—update the
design note for the legacy tool alias by (1) stating a concrete duration (e.g.,
"aliases will be maintained for at least 2 major releases / ~12 months"), (2)
specifying the deprecation notice strategy (emit runtime warnings via logs and
CI/pr tooling, add deprecation headers to agent runtime startup logs and docs,
and send developer-facing upgrade alerts), and (3) defining final removal
criteria (e.g., removal after the stated time or once usage drops below X% or
after two major releases with no active dependents). Edit the paragraph
referencing "alias period" and "legacy tool names" to include these three items
so implementers know the exact timeline, warning channels, and removal
conditions.
- Around line 155-161: Update the "Testing Strategy (Design-Level)" section to
add two concrete test categories: (1) Performance tests that define latency
budgets and benchmarking procedures comparing MCP tool call latency against the
previous SurrealDB backend (include targets, test harness, datasets, and
automated CI benchmarking steps), and (2) Backward compatibility tests that
validate legacy tool name aliasing (add integration tests and migration
scenarios ensuring existing agents using legacy names continue to work without
code changes). Reference the "Testing Strategy (Design-Level)" header and
include expected metrics, pass/fail criteria, and where these tests plug into
the integration/CI pipeline.
- Around line 136-143: Update the "Security Considerations" section to add
concrete token rotation and certificate validation requirements: extend the
existing bullet about "Token-based auth for MCP; no root credentials in client
configs" to specify a rotation policy (e.g., token TTL, rotation frequency,
automated rotation process, and revocation procedure for MCP scoped tokens) and
add a new bullet alongside "Enforce `https/wss` by default; allow `http/ws` only
for explicit loopback" that defines certificate validation rules (disallow
unaudited self-signed certs except for documented loopback/dev cases, require
CA-validated certs in production, and recommend cert pinning where clients use
long-lived MCP endpoints), referencing the MCP token and TLS bullets so readers
can locate the changes.
In `@openspec/changes/cerebro/proposal.md`:
- Around line 68-73: Add measurable performance success criteria to the "Success
Criteria" section to ensure the migration maintains performance—e.g., add items
such as "MCP tool latency under X ms (p95)" and "end-to-end memory read/write
latency under Y ms" and/or "memory operation throughput >= Z ops/sec" tied to
the existing items like "Agent runtime uses MCP to access Cerebro" and
"SurrealDB backend is removed from `clients/agent-runtime`" so reviewers can
verify both correctness and performance post-migration.
- Around line 1-26: Update the proposal text to explicitly define what "initial
alias/bridge strategy" means: state that the initial strategy is limited to
runtime tool aliasing (mapping legacy SurrealDB-backed tool names to the new
Cerebro tool surface) and a lightweight in-process bridge that forwards
read/write calls to Cerebro without performing bulk data migration or
import/export; mention that no automatic data export/import, full ETL, or schema
migration tooling is included in scope and that any persistent historical data
must be migrated manually or via a future migration tool. Reference the new
module name "modules/cerebro", the spec "openspec/changes/cerebro/cerebro.md",
and the phrase "initial alias/bridge strategy" so reviewers can locate and
verify the clarification.
- Around line 27-35: Update the proposal text to explicitly define what
"existing storage model" refers to (e.g., state whether it means the SurrealDB
schema, SQLite schema, or another storage abstraction) and where to find its
schema/details (link or reference the schema file); also define the "transition
period" by specifying its duration (dates or number of releases),
migration/deprecation milestones, and behavior during the period (e.g., which
endpoints/tools remain aliased, how data is synchronized between runtime local
memory and Cerebro, and rollback criteria). Make these changes in the cerebro
module proposal and in openspec/changes/cerebro/cerebro.md, mentioning the MCP
tools API, the SurrealDB backend replacement, and the legacy tool name aliasing
so readers can quickly map terms to the detailed definitions and timeline.
- Around line 57-62: Extend the Rollback Plan to include a data rollback
procedure: document steps to export Cerebro data, transform it to SurrealDB
schema, and re-import into SurrealDB (include commands or scripts and reference
the Cerebro export format and SurrealDB import tool), add a verification step to
run data validation checks and integrity tests after import, mandate creating
full backups of Cerebro before any export and of SurrealDB before import, and
describe toggling the clients/agent-runtime memory-surreal feature flag and
restoring legacy memory tool wiring (MCP Cerebro integration) only after
successful validation; also note expected downtime/coordination and versioning
of migration scripts for repeatability.
- Around line 48-56: The "MCP connectivity failures" risk row conflicts with the
spec's "no SurrealDB fallback is attempted" requirement; either remove the
"graceful fallback to local memory" mitigation or clarify precise conditional
behavior (e.g., only fallback in a legacy/opt-in mode) and explicitly state the
structured error behavior required by the spec. Update the Risks table row for
"MCP connectivity failures" so it references the spec's no-fallback rule and
describes the exact mitigation: either a structured error response (with
logging/alert steps) or a clearly documented, opt-in/local-only fallback path
and its safeguards.
In `@openspec/changes/cerebro/specs/cerebro/spec.md`:
- Around line 111-126: The spec currently allows either "not-found" or "deleted"
when fetching a soft-deleted memory via mem_get_observation; change the
Requirement text and the "Direct fetch of deleted memory" Scenario to mandate a
single, consistent response: return a specific "deleted" status (not
"not-found") for IDs that exist but were soft-deleted. Update the scenario
wording to assert that mem_get_observation returns a "deleted" status error for
soft-deleted entries and adjust any referenced behavior for
mem_delete/mem_search to keep soft-deleted records distinct from truly
non-existent IDs.
- Around line 127-136: Add a performance acceptance criterion to the Cerebro
spec: define measurable MCP→Cerebro latency and throughput targets and where
they apply (e.g., "95th percentile latency for read/write memory operations
<200ms" and "sustained throughput ≥1000 ops/sec per instance"), include any
SLO/SLA and load-test conditions, and state which tools/endpoints these metrics
cover (MCP proxy, Cerebro memory API, and legacy tool aliases) so reviewers can
validate performance against the contract in
openspec/changes/cerebro/cerebro.md.
- Around line 75-93: Add a new scenario (or explicit out-of-scope statement)
addressing existing SurrealDB memories: either (A) a migration scenario that
specifies when and how SurrealDB records are transformed and routed to Cerebro
(including mapping of legacy tool names memory_store/memory_recall/memory_forget
to mem_save/mem_search/mem_delete and any schema transformations, expected
downtime, and failure semantics), or (B) a clear statement that
SurrealDB-to-Cerebro migration is out of scope and existing SurrealDB memories
will remain inaccessible to the aliased tools unless migrated externally;
reference the runtime, Cerebro MCP, SurrealDB, and the legacy/aliased tool names
(memory_store, memory_recall, memory_forget → mem_save, mem_search, mem_delete)
so reviewers can locate and update the spec accordingly.
- Around line 38-56: Add a short "Data classification guidance" subsection under
the "Requirement: Separation of Memory Scopes" explaining what types of data
must remain local-only (e.g., PII, credentials, secrets, ephemeral context)
versus what may be sent to Cerebro (e.g., general user preferences,
non-sensitive long-term facts), and include explicit references to the existing
artifacts: the agent runtime, MCP, and the mem_save tool to show that mem_save
calls should only carry non-sensitive classified long-term memory; keep it
concise (2–4 bullet rules or a short paragraph) and place it after the two
Scenario blocks so readers can directly map classification guidance to the
described behaviors.
- Around line 94-110: Update the "Requirement: Secure Configuration Defaults"
section to explicitly require TLS certificate validation for all https/wss
endpoints and state the validation behavior in the "Secure endpoint default
(happy path)" and "Insecure endpoint without opt-in (edge case)" scenarios;
specifically, add text that the runtime MUST perform standard certificate chain
and hostname verification for https/wss, reject connections with invalid or
untrusted certificates by default, and only allow self-signed certificates when
an explicit, auditable opt-in flag (e.g., loopback/selfSignedTrust=true) is
present and limited to loopback addresses with a documented risk/usage note.
Ensure the spec names the verification checks (chain, expiry, hostname) and how
the opt-in toggles acceptance so implementers of the Requirement: Secure
Configuration Defaults and both scenario blocks have unambiguous rules.
In `@openspec/changes/cerebro/tasks.md`:
- Around line 3-17: The task 1.1 placement of the Cerebro crate is ambiguous
against the proposal; update the plan to explicitly state where Cerebro should
live (either as a standalone module under modules/cerebro or as a sub-crate
under agent-runtime) and make corresponding edits: clarify the intended location
in the Phase 1 checklist (task 1.1), align the README/proposal reference
(proposal.md) to match that choice, and ensure subsequent tasks (1.2–1.5)
reference the chosen location so the implementation steps and file targets are
consistent.
- Around line 63-69: Add a Migration Guide and MCP schema docs: create a
migration guide describing step-by-step instructions to migrate from SurrealDB
to Cerebro and add it to clients/agent-runtime/README.md (include secure
defaults, Cerebro MCP configuration, legacy tool alias behavior), update
clients/agent-runtime/examples/custom_memory.rs to show MCP-backed long-term
memory usage, update the root README.md to mention the new Cerebro module and
removal of the SurrealDB backend, and add a machine-readable MCP tool schema
file (JSON schema) for each of the 13 Cerebro tools—reference cerebro.md for
narrative details but place the 13 JSON schemas in a consumable location linked
from the README files.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: d8d7e4d4-e765-4888-b0af-608815a383c5
📒 Files selected for processing (6)
.agents/AGENTS.mdopenspec/changes/cerebro/cerebro.mdopenspec/changes/cerebro/design.mdopenspec/changes/cerebro/proposal.mdopenspec/changes/cerebro/specs/cerebro/spec.mdopenspec/changes/cerebro/tasks.md
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: pr-checks
- GitHub Check: sonar
- GitHub Check: Cloudflare Pages
🧰 Additional context used
📓 Path-based instructions (3)
**/*.{md,mdx}
⚙️ CodeRabbit configuration file
**/*.{md,mdx}: Verify technical accuracy and that docs stay aligned with code changes.
For user-facing docs, check EN/ES parity or explicitly note pending translation gaps.
Files:
openspec/changes/cerebro/specs/cerebro/spec.mdopenspec/changes/cerebro/design.mdopenspec/changes/cerebro/tasks.mdopenspec/changes/cerebro/cerebro.mdopenspec/changes/cerebro/proposal.md
**/*
⚙️ CodeRabbit configuration file
**/*: Security first, performance second.
Validate input boundaries, auth/authz implications, and secret management.
Look for behavioral regressions, missing tests, and contract breaks across modules.
Files:
openspec/changes/cerebro/specs/cerebro/spec.mdopenspec/changes/cerebro/design.mdopenspec/changes/cerebro/tasks.mdopenspec/changes/cerebro/cerebro.mdopenspec/changes/cerebro/proposal.md
.agents/AGENTS.md
📄 CodeRabbit inference engine (AGENTS.md)
.agents/AGENTS.md: Document agent configurations and capabilities in AGENTS.md
Maintain comprehensive agent metadata including name, description, purpose, and capabilities
Include version information and compatibility details for agents
Files:
.agents/AGENTS.md
🧠 Learnings (4)
📚 Learning: 2026-02-17T12:31:17.076Z
Learnt from: CR
Repo: dallay/corvus PR: 0
File: clients/agent-runtime/AGENTS.md:0-0
Timestamp: 2026-02-17T12:31:17.076Z
Learning: Applies to clients/agent-runtime/**/*.rs : Run `cargo fmt --all -- --check`, `cargo clippy --all-targets -- -D warnings`, and `cargo test` for code validation, or document which checks were skipped and why
Applied to files:
openspec/changes/cerebro/tasks.md.agents/AGENTS.md
📚 Learning: 2026-02-17T07:28:38.934Z
Learnt from: CR
Repo: dallay/corvus PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-02-17T07:28:38.934Z
Learning: Applies to .agents/AGENTS.md : Document agent configurations and capabilities in AGENTS.md
Applied to files:
.agents/AGENTS.md
📚 Learning: 2026-02-17T07:28:38.934Z
Learnt from: CR
Repo: dallay/corvus PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-02-17T07:28:38.934Z
Learning: Applies to .agents/AGENTS.md : Maintain comprehensive agent metadata including name, description, purpose, and capabilities
Applied to files:
.agents/AGENTS.md
📚 Learning: 2026-02-17T07:28:38.934Z
Learnt from: CR
Repo: dallay/corvus PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-02-17T07:28:38.934Z
Learning: Applies to .agents/AGENTS.md : Include version information and compatibility details for agents
Applied to files:
.agents/AGENTS.md
🪛 LanguageTool
openspec/changes/cerebro/cerebro.md
[grammar] ~168-~168: Use a hyphen to join words.
Context: ...3. Error Handling & Resilience * Fail safe: save/search should degrade grace...
(QB_NEW_EN_HYPHEN)
🔇 Additional comments (22)
openspec/changes/cerebro/specs/cerebro/spec.md (3)
1-17: LGTM: Clear purpose and constraints.The specification clearly defines the MCP-based integration and removal of SurrealDB. The scope boundaries are well-defined.
18-37: LGTM: MCP tool surface well-defined.Happy path and validation scenarios are covered. The reference to the detailed tool spec in cerebro.md is appropriate for avoiding duplication.
57-74: LGTM: SurrealDB removal clearly specified.The requirement includes a good edge case for legacy configuration handling. Ensure the "clear error" mentioned in line 73 provides migration guidance (e.g., pointing users to Cerebro MCP configuration).
.agents/AGENTS.md (1)
167-192: LGTM: Skills table formatting improved.The table formatting has been updated for better readability. Content remains unchanged.
openspec/changes/cerebro/proposal.md (2)
36-47: LGTM: Affected areas comprehensively documented.The table provides specific file paths and clear impact descriptions. This will help with implementation tracking.
63-67: LGTM: Dependencies clearly referenced.External specification dependencies are documented. These should be validated during implementation.
openspec/changes/cerebro/design.md (6)
1-28: LGTM: Clear goals and scope definition.The executive summary aligns with the specification and proposal documents. Draft status is appropriate for this documentation PR.
29-55: LGTM: Architecture clearly separates concerns.The module and component breakdown is clear. The preservation of the Memory trait maintains backward compatibility while enabling the new MCP backend.
77-109: LGTM: Comprehensive tool API documented.The 13 tools are well-categorized and the legacy aliases ensure backward compatibility. Consistent with cerebro.md.
110-128: LGTM: Configuration changes well-defined.The removal of SurrealDB configuration and addition of MCP settings is clear. Security defaults (explicit
allow_insecure) align with the secure-by-default principle.
162-167: LGTM: Comprehensive observability plan.The observability strategy covers tracing, metrics, and logging with appropriate security considerations (redaction of sensitive fields). Correlation IDs will enable debugging across MCP boundaries.
168-172: LGTM: Open questions appropriately flagged.The three open questions are architecture-significant and should be resolved before implementation begins. Good practice to document these explicitly.
openspec/changes/cerebro/tasks.md (2)
19-52: LGTM: Excellent TDD task breakdown.The RED-GREEN-REFACTOR cycle is explicitly documented for each feature. Specific test files and implementation files are identified, making this plan actionable.
54-61: 🧹 Nitpick | 🔵 TrivialAdd performance testing task.
Phase 3 includes integration and security testing but no performance/load testing. Add a task to validate MCP tool latency and compare against previous SurrealDB backend performance.
⛔ Skipped due to learnings
Learnt from: CR Repo: dallay/corvus PR: 0 File: clients/agent-runtime/AGENTS.md:0-0 Timestamp: 2026-02-17T12:31:17.076Z Learning: Applies to clients/agent-runtime/**/*.rs : Run `cargo fmt --all -- --check`, `cargo clippy --all-targets -- -D warnings`, and `cargo test` for code validation, or document which checks were skipped and whyLearnt from: CR Repo: dallay/corvus PR: 0 File: clients/agent-runtime/AGENTS.md:0-0 Timestamp: 2026-02-17T12:31:17.076Z Learning: Applies to clients/agent-runtime/src/channels/**/*.rs : Implement `Channel` trait in `src/channels/` with consistent `send`, `listen`, and `health_check` semantics and cover auth/allowlist/health behavior with testsLearnt from: CR Repo: dallay/corvus PR: 0 File: clients/agent-runtime/AGENTS.md:0-0 Timestamp: 2026-02-17T12:31:17.076Z Learning: Include threat/risk notes and rollback strategy for security, runtime, and gateway changes; add or update tests for boundary checks and failure modesLearnt from: CR Repo: dallay/corvus PR: 0 File: clients/agent-runtime/AGENTS.md:0-0 Timestamp: 2026-02-17T12:31:17.076Z Learning: Applies to clients/agent-runtime/src/{security,gateway,tools,config}/**/*.rs : Do not silently weaken security policy or access constraints; keep default behavior secure-by-default with deny-by-default where applicableLearnt from: CR Repo: dallay/corvus PR: 0 File: clients/agent-runtime/AGENTS.md:0-0 Timestamp: 2026-02-17T12:31:17.076Z Learning: Applies to clients/agent-runtime/src/{security,gateway,tools}/**/*.rs : Treat `src/security/`, `src/gateway/`, `src/tools/` as high-risk surfaces and never broaden filesystem/network execution scope without explicit policy checksLearnt from: CR Repo: dallay/corvus PR: 0 File: clients/agent-runtime/AGENTS.md:0-0 Timestamp: 2026-02-17T12:31:17.076Z Learning: Applies to clients/agent-runtime/src/tools/**/*.rs : Implement `Tool` trait in `src/tools/` with strict parameter schema, validate and sanitize all inputs, and return structured `ToolResult` without panics in runtime pathopenspec/changes/cerebro/cerebro.md (8)
1-13: LGTM: Strong core philosophy.The five principles establish a clear design foundation. "Agent decides what to save" is particularly important for security and data minimization. Progressive enhancement ensures the system remains useful without LLM dependencies.
25-34: LGTM: Architecture pattern clearly defined.The sync write + async enrichment pattern is well-suited for maintaining fast response times while enabling background intelligence. Graceful degradation without LLM is a good resilience feature.
51-80: LGTM: Comprehensive MCP tools catalog.The 13 tools are well-organized by category and consistent across all documentation. The progression from 3 current tools to 13 target tools shows thoughtful expansion of capabilities.
81-87: LGTM: Memory hygiene requirements clear.The combination of existing policies and target enhancements (deduplication, topic upserts, soft-delete filtering) provides a comprehensive hygiene strategy.
88-96: LGTM: TUI appropriately scoped as future work.Marking TUI as non-MVP while documenting the future vision is good planning. This keeps the initial scope manageable while providing a roadmap.
122-134: LGTM: Excellent security-first approach.The security model is comprehensive and aligns with the repository's "Security First, Performance Second" principle. The eight requirements cover transport, validation, auth, privilege, defaults, and auditability.
174-182: LGTM: Comprehensive observability strategy.The observability plan covers multiple backends, key metrics, tracing, and security (redaction). The inclusion of queue depth and enrichment duration metrics will help identify bottlenecks.
183-192: LGTM: Testing strategy aligns with TDD principles.The testing strategy follows the repository's TDD approach and includes appropriate test categories including security and performance, which were noted as gaps in other documents.
Comment on lines
+155
to
166
| ## Cerebro Memory Module | ||
|
|
||
| Cerebro is an agent-agnostic, high-performance memory system designed for use with any AI agent or LLM that supports the Model Context Protocol (MCP). It is implemented as a single Rust binary and uses SurrealDB (embedded) for multi-model storage (document, graph, vector search). | ||
|
|
||
| - **Integration:** Agents interact with Cerebro via the MCP JSON-RPC protocol, using a set of 13 memory/session tools (see `openspec/changes/cerebro/cerebro.md` for full API and business logic). | ||
| - **Architecture:** Cerebro uses a sync API for fast agent responses and an async worker for background tasks (e.g., vector embeddings, entity extraction, graph edges) if an LLM is configured. | ||
| - **Data Model:** Structured around `session`, `memory` (engram), and `prompt` nodes, with graph edges for relations and chronology. | ||
| - **Memory Hygiene:** Implements deduplication, topic upserts, and global filters for deleted records. | ||
| - **TUI:** Provides a terminal UI (ratatui + crossterm) for real-time observability, memory browsing, and session timelines. | ||
|
|
||
| **Note:** Cerebro is a separate module. Agents should use the documented MCP tools API for all memory/session operations. See the spec for details on the drill-in retrieval strategy, memory hygiene, and supported operations. | ||
|
|
Contributor
There was a problem hiding this comment.
Add version and configuration information for Cerebro.
The Cerebro documentation is comprehensive but missing:
- Version information: Cerebro version and compatibility with agent-runtime versions
- Configuration guidance: How agents enable/configure Cerebro MCP integration
Based on learnings, agent documentation should include version information and compatibility details.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.agents/AGENTS.md around lines 155 - 166, Update the "Cerebro Memory Module"
section to include explicit version and compatibility details and clear
configuration steps: add a "Version & Compatibility" subheading listing the
Cerebro semantic version, the minimum and tested agent-runtime versions, and any
breaking changes; add a "Configuration & Enabling" subheading that documents how
to enable MCP integration (referencing the MCP JSON-RPC tools), required config
keys/environment variables, example agent config flags, and where to find the
full API in openspec/changes/cerebro/cerebro.md; ensure references to "session",
"memory", "prompt", and the MCP tools are preserved so readers can locate
related behavior and tooling.
Comment on lines
+14
to
+24
| ## 2. Tech Stack (Current + Target) | ||
|
|
||
| * **Language:** Rust. | ||
| * **Protocol:** MCP (JSON-RPC). | ||
| * **Concurrency:** `tokio`. | ||
| * **Current DB Integration:** SurrealDB over remote WebSocket RPC (`ws/wss`), plus existing SQLite | ||
| backend in the runtime. | ||
| * **Target Option:** Embedded SurrealDB can be evaluated later as a deployment mode, but is not the | ||
| current implementation. | ||
| * **UI:** CLI today. TUI (`ratatui` + `crossterm`) is optional future work. | ||
|
|
Contributor
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Clarify SurrealDB usage in Cerebro vs. agent-runtime.
Lines 19-20 state "Current DB Integration: SurrealDB over remote WebSocket RPC" which could be confusing given the repeated emphasis on removing SurrealDB from agent-runtime. Explicitly state that:
- Cerebro will use SurrealDB as its internal storage
- agent-runtime will no longer directly access SurrealDB, only via MCP
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@openspec/changes/cerebro/cerebro.md` around lines 14 - 24, Update the "Tech
Stack (Current + Target)" section to clarify SurrealDB usage by explicitly
stating that Cerebro uses SurrealDB as its internal storage while agent-runtime
no longer accesses SurrealDB directly and instead interacts with it only via the
MCP protocol; modify the existing "Current DB Integration: SurrealDB over remote
WebSocket RPC" line into two concise lines such as "Cerebro: SurrealDB used as
internal storage (remote WebSocket RPC for now)" and "agent-runtime: No direct
SurrealDB access — communicates via MCP only" so the distinction between Cerebro
and agent-runtime is unambiguous.
Comment on lines
+35
to
+50
| ## 4. Data Model (Current and Target) | ||
|
|
||
| ### Current (as implemented) | ||
|
|
||
| * `memory_entries`: canonical memory records. | ||
| * `memory_events`: event log (`store`, `update`, `forget`, etc.). | ||
| * `memory_relations`: lightweight relation edges (entry->category, entry->session, entry->previous). | ||
|
|
||
| ### Target (Cerebro expansion) | ||
|
|
||
| * `session` node: lifecycle, summary, chronology. | ||
| * `memory` node (engram): structured What/Why/Where/Learned payload + metadata (`scope`, | ||
| `topic_key`, `type`). | ||
| * `prompt` node: explicit saved user prompts. | ||
| * Relation edges such as `CREATED_IN`, `RELATES_TO`, `FOLLOWS`. | ||
|
|
Contributor
There was a problem hiding this comment.
Document data model migration strategy.
The document shows both "Current" and "Target" data models but doesn't explain the migration path between them. This is a significant data transformation. Consider:
- Will Cerebro support both schemas during transition?
- How will existing
memory_entriesbe converted tomemorynodes? - What's the timeline for deprecating the current schema?
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@openspec/changes/cerebro/cerebro.md` around lines 35 - 50, Add a migration
section that explicitly defines the transition strategy: state that Cerebro will
support dual schemas during migration via a compatibility layer/adapter that
reads from `memory_entries`, `memory_events`, and `memory_relations` and exposes
the new `session`, `memory` (engram), and `prompt` node shapes; describe a
concrete conversion mapping from `memory_entries` -> `memory` (map fields into
What/Why/Where/Learned + metadata `scope`, `topic_key`, `type`), map
`memory_relations` into relation edges (`CREATED_IN`, `RELATES_TO`, `FOLLOWS`),
and preserve `memory_events` as the event log; include a plan for running a
migration script (bulk + safe incremental replay), validation checks, rollback
strategy, and a clear timeline for deprecation with feature-flagged rollout and
expected cutover date for retiring `memory_entries` and `memory_relations`.
Comment on lines
+97
to
+101
| ## 8. Agent Integration (`prompt_template.md`) | ||
|
|
||
| Provide a copy-paste system prompt that teaches agents how to use drill-in memory patterns and | ||
| structured save formats. | ||
|
|
Contributor
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Specify location of agent system prompt.
Line 99 mentions providing a "copy-paste system prompt" but doesn't specify where it will be documented (e.g., docs/prompts/cerebro-memory.md or similar). Add a reference to the specific file location.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@openspec/changes/cerebro/cerebro.md` around lines 97 - 101, The doc section
"8. Agent Integration (`prompt_template.md`)" is missing a specific location for
the copy-paste system prompt; update the text under that heading to point to a
concrete file path (for example docs/prompts/cerebro-memory.md or
docs/prompts/prompt_template.md) so readers know where to find the system prompt
and examples; edit the "Agent Integration (`prompt_template.md`)" paragraph in
cerebro.md to include the chosen file path and a short note that the prompt and
examples live in that file.
Comment on lines
+94
to
+110
| ### Requirement: Secure Configuration Defaults | ||
|
|
||
| The runtime and Cerebro configuration MUST default to secure transport and require explicit opt-in | ||
| for insecure endpoints. | ||
|
|
||
| #### Scenario: Secure endpoint default (happy path) | ||
|
|
||
| - GIVEN a new configuration for Cerebro MCP | ||
| - WHEN the endpoint uses `https` or `wss` | ||
| - THEN the runtime accepts the configuration without additional flags | ||
|
|
||
| #### Scenario: Insecure endpoint without opt-in (edge case) | ||
|
|
||
| - GIVEN a configuration that uses `http` or `ws` without explicit loopback opt-in | ||
| - WHEN the runtime validates the configuration | ||
| - THEN the configuration is rejected with a security error | ||
|
|
Contributor
There was a problem hiding this comment.
Add certificate validation requirements.
Secure transport defaults are good, but the spec should explicitly require certificate validation for https/wss endpoints and clarify whether self-signed certificates are allowed (and under what conditions).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@openspec/changes/cerebro/specs/cerebro/spec.md` around lines 94 - 110, Update
the "Requirement: Secure Configuration Defaults" section to explicitly require
TLS certificate validation for all https/wss endpoints and state the validation
behavior in the "Secure endpoint default (happy path)" and "Insecure endpoint
without opt-in (edge case)" scenarios; specifically, add text that the runtime
MUST perform standard certificate chain and hostname verification for https/wss,
reject connections with invalid or untrusted certificates by default, and only
allow self-signed certificates when an explicit, auditable opt-in flag (e.g.,
loopback/selfSignedTrust=true) is present and limited to loopback addresses with
a documented risk/usage note. Ensure the spec names the verification checks
(chain, expiry, hostname) and how the opt-in toggles acceptance so implementers
of the Requirement: Secure Configuration Defaults and both scenario blocks have
unambiguous rules.
Comment on lines
+127
to
+136
| ## Acceptance Criteria | ||
|
|
||
| - The Cerebro MCP tool set is available and matches the contract in | ||
| `openspec/changes/cerebro/cerebro.md`. | ||
| - The agent runtime no longer ships a SurrealDB memory backend or `memory-surreal` feature flag. | ||
| - Long-term memory operations route through MCP to Cerebro, while local memory remains private and | ||
| short-term. | ||
| - Legacy memory tool names continue to work as aliases to Cerebro tool names. | ||
| - Insecure transport endpoints are rejected unless explicitly enabled for loopback development. | ||
| - Soft-deleted memories are excluded from default retrieval results. |
Contributor
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Consider adding performance acceptance criteria.
The acceptance criteria cover functionality and security but don't mention performance. Consider adding criteria for MCP tool latency budgets or throughput requirements.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@openspec/changes/cerebro/specs/cerebro/spec.md` around lines 127 - 136, Add a
performance acceptance criterion to the Cerebro spec: define measurable
MCP→Cerebro latency and throughput targets and where they apply (e.g., "95th
percentile latency for read/write memory operations <200ms" and "sustained
throughput ≥1000 ops/sec per instance"), include any SLO/SLA and load-test
conditions, and state which tools/endpoints these metrics cover (MCP proxy,
Cerebro memory API, and legacy tool aliases) so reviewers can validate
performance against the contract in openspec/changes/cerebro/cerebro.md.
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Deploying corvus with
|
| Latest commit: |
5edc0af
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://13684ac7.corvus-42x.pages.dev |
| Branch Preview URL: | https://docs-214-specifications-for.corvus-42x.pages.dev |
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (11)
openspec/changes/cerebro/proposal.md (3)
74-79: 🧹 Nitpick | 🔵 TrivialInclude measurable performance success criteria.
Success criteria are functional only. Add quantitative latency/throughput thresholds for MCP memory operations so migration outcomes are verifiable.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/cerebro/proposal.md` around lines 74 - 79, Add measurable performance success criteria to the "Success Criteria" section: specify quantitative latency and throughput thresholds for MCP memory operations (e.g., 95th percentile read latency < X ms, write latency < Y ms, and sustained throughput of Z ops/sec) and define acceptance tests (sample workload size, percentiles to measure, and pass/fail thresholds). Reference the MCP/Cerebro integration and the removal of SurrealDB (the items already listed) so that tests validate agent runtime calls to MCP via Cerebro tools (include legacy alias behavior) under the defined load and latency targets.
63-68:⚠️ Potential issue | 🟠 MajorAdd data rollback procedure, not only code rollback.
Current rollback covers feature wiring but not how Cerebro-written data is handled if reverting runtime path. Add export/transform/re-import and validation steps (or explicitly mark data rollback out of scope with risk note).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/cerebro/proposal.md` around lines 63 - 68, Update the "Rollback Plan" in the Cerebro proposal to include a concrete data rollback procedure or an explicit risk note: add steps to export Cerebro-written data from the new backend, transform it to the SurrealDB schema expected by the restored runtime, and re-import with a verification/validation step (checksum or sample queries) to ensure integrity; reference the existing feature flag and module names ("memory-surreal" and "clients/agent-runtime") and the Cerebro integration so reviewers know which data sets to target; alternatively, if data rollback is out of scope, add a clear risk statement explaining that data migration is not covered and list manual mitigation steps (backups, retention window, and who to contact).
34-40:⚠️ Potential issue | 🟡 MinorClarify “existing storage model” and define the transition period.
Line 35 and Line 39 remain underspecified. Please name exactly which schema/model is meant and document alias-period duration/milestones.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/cerebro/proposal.md` around lines 34 - 40, Update the proposal text to explicitly name the existing storage schema/model and to specify the transition period and milestones: state the exact schema (e.g., "SurrealDB schema: tables/collections X, Y, Z and field definitions as used by runtime memory model") or whichever model is intended, reference the module and spec files ('cerebro' Rust module and openspec/changes/cerebro/cerebro.md) and describe how short-term vs long-term mapping will occur, and define a concrete alias-period (e.g., duration in weeks/months or milestone-based steps) with clear milestones for deprecating legacy tool names and removing the SurrealDB backend (include triggers such as "all adapters migrated" or a version tag). Ensure the proposal includes these exact names and timeline/milestones so readers can implement the migration unambiguously.openspec/changes/cerebro/cerebro.md (3)
174-174:⚠️ Potential issue | 🟡 MinorUse hyphenated form: “Fail-safe”.
Minor grammar fix for consistency and readability.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/cerebro/cerebro.md` at line 174, Update the list item text that currently reads "Fail safe: save/search should degrade gracefully if enrichment fails." to use the hyphenated form "Fail-safe: save/search should degrade gracefully if enrichment fails." — locate the bullet containing "save/search" or the phrase "Fail safe" and replace it with "Fail-safe" for consistent grammar.
203-203:⚠️ Potential issue | 🟡 MinorRemove obsolete
memory-surrealdeployment reference.Line 203 conflicts with the removal plan across spec/design/tasks. Replace with current Cerebro-related build/deploy switches or remove the bullet if no longer applicable.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/cerebro/cerebro.md` at line 203, The bullet "* feature-gated builds (`memory-surreal` and related options)," is obsolete; update the Cerebro deployment/build mentions by removing the `memory-surreal` reference and either replace it with the current Cerebro-related build/deploy switches (use the canonical switch names used elsewhere in the spec) or delete the bullet entirely if no replacement is needed; locate the exact text matching "feature-gated builds (`memory-surreal` and related options)" in cerebro.md and perform the removal or substitution so the spec no longer references the deprecated `memory-surreal` option.
132-137:⚠️ Potential issue | 🟠 MajorAlign security/config model with MCP-based architecture (remove runtime SurrealDB semantics).
Line 135–137 and Line 165–169 still describe direct SurrealDB auth/backend selection, which conflicts with the runtime-removal contract in the other Cerebro docs. Update this section to MCP endpoint authz + transport policy + scoped tool permissions, and remove direct
surrealruntime backend wording.Also applies to: 165-169
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/cerebro/cerebro.md` around lines 132 - 137, Update the security/config section so it no longer references direct SurrealDB runtime/back-end semantics (remove wording like "surreal" runtime backend and any instructions about using root credentials or selecting SurrealDB directly); instead reframe the "Auth model" and related bullets to describe MCP endpoint authorization (token-based auth to MCP endpoints), transport policy enforcement (https/wss by default, http/ws only for explicit loopback dev), and scoped tool/service permissions (least-privilege scoped DB credentials managed via MCP) — replace the existing lines that mention direct SurrealDB selection with this MCP-centric language and ensure the "Transport security", "Input validation", and "Least privilege" bullets reference MCP-managed authz and scoped permissions rather than a runtime SurrealDB backend.openspec/changes/cerebro/specs/cerebro/spec.md (2)
141-150: 🧹 Nitpick | 🔵 TrivialAdd measurable performance acceptance criteria.
Acceptance criteria currently verify functionality/security but not migration performance. Add explicit SLO-style thresholds (e.g., p95 latency and throughput) for MCP memory operations and legacy aliases.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/cerebro/specs/cerebro/spec.md` around lines 141 - 150, Update the Acceptance Criteria section to add explicit, measurable SLOs for MCP memory operations and legacy alias handling: define p95 latency thresholds (e.g., p95 <= 200ms for single-key memory reads and p95 <= 500ms for batched writes), specify throughput targets (e.g., 1000 req/s sustained with <1% error rate) and a target success rate (e.g., 99.9% availability) for calls routed through MCP to Cerebro, and add equivalent performance bounds for legacy alias endpoints; ensure these SLOs are stated alongside the existing bullets (referencing "MCP memory operations", "legacy aliases", and the Cerebro contract) so acceptance testing can validate latency, throughput, and error-rate metrics.
106-122:⚠️ Potential issue | 🟠 MajorRequire explicit TLS certificate verification rules.
https/wssdefaults are defined, but Line 111–122 still leaves cert validation behavior implicit. Please mandate chain + hostname + expiry verification, default rejection of invalid/untrusted certs, and tightly scoped self-signed allowance (explicit loopback-only audited opt-in).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/cerebro/specs/cerebro/spec.md` around lines 106 - 122, Update the "Requirement: Secure Configuration Defaults" section to explicitly mandate TLS certificate verification semantics: require full chain validation, hostname verification, and expiry checks for all https/wss endpoints; state that invalid or untrusted certificates MUST be rejected by default; and add a narrowly scoped, auditable opt-in for self-signed certificates that is only allowed for loopback addresses and must be explicitly configured. Modify the two scenarios "Secure endpoint default (happy path)" and "Insecure endpoint without opt-in (edge case)" to reference these verification rules and the loopback-only self-signed opt-in mechanism so the validation behavior is no longer implicit.openspec/changes/cerebro/design.md (3)
156-157:⚠️ Potential issue | 🟠 MajorDefine legacy alias deprecation timeline and removal gate.
“Maintain alias period” needs a concrete duration, warning channel(s), and objective removal criteria to avoid indefinite compatibility debt.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/cerebro/design.md` around lines 156 - 157, Update the "Maintain alias period" guidance in the Cerebro design doc to specify a concrete deprecation timeline (e.g., 12 months), the warning channels and cadence (e.g., release notes, repo deprecation notice, and in-app/admin notifications at 6 and 3 months before removal), and objective removal criteria (e.g., telemetry showing <1% usage or end of the 12-month window), and link this to the existing "Cerebro import tooling" note so migration owners know import tooling is the supported path; specifically edit the bullets containing "Maintain alias period for legacy tool names" and "Data migration handled by Cerebro import tooling (out of scope for runtime)" to include the duration, channels, cadence, and removal gate conditions.
129-134:⚠️ Potential issue | 🟠 MajorSpecify concrete MCP retry policy.
Line 133 is too ambiguous for implementation consistency. Define max attempts, backoff algorithm/jitter, retryable vs terminal classes, and timeout interaction for save/search MCP calls.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/cerebro/design.md` around lines 129 - 134, Update the "Error Handling" section to specify a concrete MCP retry policy for save/search operations: define max attempts = 5, initial backoff = 200ms, exponential backoff with multiplier 2.0, max backoff = 5s, and add full jitter (sleep = random(0, backoff)); treat network/timeouts and 5xx MCP responses as retryable, and 4xx client errors (except 429) and structured terminal codes as non-retryable; treat 429 as retryable with adaptive backoff; enforce that per-call timeout (e.g., requestTimeout) is applied to the entire retry sequence (not per-attempt) or clearly specify per-attempt timeout if chosen, and document interaction between max attempts and timeout (abort when overall timeout reached), plus include an example pseudocode outline for save/search showing attempt loop, backoff+jitter, and terminal vs retryable decision points.
159-165: 🧹 Nitpick | 🔵 TrivialAdd explicit performance test targets to the design-level strategy.
Current test plan includes unit/integration/security, but no measurable latency/throughput pass criteria for MCP memory paths.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/cerebro/design.md` around lines 159 - 165, Update the "Testing Strategy (Design-Level)" section to add explicit performance test targets for MCP memory paths: define measurable latency and throughput pass criteria (e.g., p95 latency < X ms, mean latency < Y ms, throughput ≥ Z requests/sec) and list concrete test scenarios (cold/hot cache, concurrent N clients, payload sizes), reference the components under test (MCP, MCP tool adapters, and Cerebro round-trip), and specify measurement methods and tooling (load framework, metrics collection, and CI gating) so the design includes clear, actionable performance acceptance criteria.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@openspec/changes/cerebro/tasks.md`:
- Around line 49-57: Update the Phase 3: Testing checklist to include formatting
and lint gates: add explicit checklist items for running "cargo fmt --all --
--check" and "cargo clippy --all-targets -- -D warnings" (or documenting why
they were skipped), and modify the existing 3.3 test step so it runs/records
results for fmt, clippy, and cargo test (or explains which checks were
intentionally omitted); reference the "Phase 3: Testing" header and the current
checklist entries (3.1, 3.2, 3.3) in the tasks.md so reviewers can find and
verify the new fmt/clippy entries and the updated test logging requirement.
---
Duplicate comments:
In `@openspec/changes/cerebro/cerebro.md`:
- Line 174: Update the list item text that currently reads "Fail safe:
save/search should degrade gracefully if enrichment fails." to use the
hyphenated form "Fail-safe: save/search should degrade gracefully if enrichment
fails." — locate the bullet containing "save/search" or the phrase "Fail safe"
and replace it with "Fail-safe" for consistent grammar.
- Line 203: The bullet "* feature-gated builds (`memory-surreal` and related
options)," is obsolete; update the Cerebro deployment/build mentions by removing
the `memory-surreal` reference and either replace it with the current
Cerebro-related build/deploy switches (use the canonical switch names used
elsewhere in the spec) or delete the bullet entirely if no replacement is
needed; locate the exact text matching "feature-gated builds (`memory-surreal`
and related options)" in cerebro.md and perform the removal or substitution so
the spec no longer references the deprecated `memory-surreal` option.
- Around line 132-137: Update the security/config section so it no longer
references direct SurrealDB runtime/back-end semantics (remove wording like
"surreal" runtime backend and any instructions about using root credentials or
selecting SurrealDB directly); instead reframe the "Auth model" and related
bullets to describe MCP endpoint authorization (token-based auth to MCP
endpoints), transport policy enforcement (https/wss by default, http/ws only for
explicit loopback dev), and scoped tool/service permissions (least-privilege
scoped DB credentials managed via MCP) — replace the existing lines that mention
direct SurrealDB selection with this MCP-centric language and ensure the
"Transport security", "Input validation", and "Least privilege" bullets
reference MCP-managed authz and scoped permissions rather than a runtime
SurrealDB backend.
In `@openspec/changes/cerebro/design.md`:
- Around line 156-157: Update the "Maintain alias period" guidance in the
Cerebro design doc to specify a concrete deprecation timeline (e.g., 12 months),
the warning channels and cadence (e.g., release notes, repo deprecation notice,
and in-app/admin notifications at 6 and 3 months before removal), and objective
removal criteria (e.g., telemetry showing <1% usage or end of the 12-month
window), and link this to the existing "Cerebro import tooling" note so
migration owners know import tooling is the supported path; specifically edit
the bullets containing "Maintain alias period for legacy tool names" and "Data
migration handled by Cerebro import tooling (out of scope for runtime)" to
include the duration, channels, cadence, and removal gate conditions.
- Around line 129-134: Update the "Error Handling" section to specify a concrete
MCP retry policy for save/search operations: define max attempts = 5, initial
backoff = 200ms, exponential backoff with multiplier 2.0, max backoff = 5s, and
add full jitter (sleep = random(0, backoff)); treat network/timeouts and 5xx MCP
responses as retryable, and 4xx client errors (except 429) and structured
terminal codes as non-retryable; treat 429 as retryable with adaptive backoff;
enforce that per-call timeout (e.g., requestTimeout) is applied to the entire
retry sequence (not per-attempt) or clearly specify per-attempt timeout if
chosen, and document interaction between max attempts and timeout (abort when
overall timeout reached), plus include an example pseudocode outline for
save/search showing attempt loop, backoff+jitter, and terminal vs retryable
decision points.
- Around line 159-165: Update the "Testing Strategy (Design-Level)" section to
add explicit performance test targets for MCP memory paths: define measurable
latency and throughput pass criteria (e.g., p95 latency < X ms, mean latency < Y
ms, throughput ≥ Z requests/sec) and list concrete test scenarios (cold/hot
cache, concurrent N clients, payload sizes), reference the components under test
(MCP, MCP tool adapters, and Cerebro round-trip), and specify measurement
methods and tooling (load framework, metrics collection, and CI gating) so the
design includes clear, actionable performance acceptance criteria.
In `@openspec/changes/cerebro/proposal.md`:
- Around line 74-79: Add measurable performance success criteria to the "Success
Criteria" section: specify quantitative latency and throughput thresholds for
MCP memory operations (e.g., 95th percentile read latency < X ms, write latency
< Y ms, and sustained throughput of Z ops/sec) and define acceptance tests
(sample workload size, percentiles to measure, and pass/fail thresholds).
Reference the MCP/Cerebro integration and the removal of SurrealDB (the items
already listed) so that tests validate agent runtime calls to MCP via Cerebro
tools (include legacy alias behavior) under the defined load and latency
targets.
- Around line 63-68: Update the "Rollback Plan" in the Cerebro proposal to
include a concrete data rollback procedure or an explicit risk note: add steps
to export Cerebro-written data from the new backend, transform it to the
SurrealDB schema expected by the restored runtime, and re-import with a
verification/validation step (checksum or sample queries) to ensure integrity;
reference the existing feature flag and module names ("memory-surreal" and
"clients/agent-runtime") and the Cerebro integration so reviewers know which
data sets to target; alternatively, if data rollback is out of scope, add a
clear risk statement explaining that data migration is not covered and list
manual mitigation steps (backups, retention window, and who to contact).
- Around line 34-40: Update the proposal text to explicitly name the existing
storage schema/model and to specify the transition period and milestones: state
the exact schema (e.g., "SurrealDB schema: tables/collections X, Y, Z and field
definitions as used by runtime memory model") or whichever model is intended,
reference the module and spec files ('cerebro' Rust module and
openspec/changes/cerebro/cerebro.md) and describe how short-term vs long-term
mapping will occur, and define a concrete alias-period (e.g., duration in
weeks/months or milestone-based steps) with clear milestones for deprecating
legacy tool names and removing the SurrealDB backend (include triggers such as
"all adapters migrated" or a version tag). Ensure the proposal includes these
exact names and timeline/milestones so readers can implement the migration
unambiguously.
In `@openspec/changes/cerebro/specs/cerebro/spec.md`:
- Around line 141-150: Update the Acceptance Criteria section to add explicit,
measurable SLOs for MCP memory operations and legacy alias handling: define p95
latency thresholds (e.g., p95 <= 200ms for single-key memory reads and p95 <=
500ms for batched writes), specify throughput targets (e.g., 1000 req/s
sustained with <1% error rate) and a target success rate (e.g., 99.9%
availability) for calls routed through MCP to Cerebro, and add equivalent
performance bounds for legacy alias endpoints; ensure these SLOs are stated
alongside the existing bullets (referencing "MCP memory operations", "legacy
aliases", and the Cerebro contract) so acceptance testing can validate latency,
throughput, and error-rate metrics.
- Around line 106-122: Update the "Requirement: Secure Configuration Defaults"
section to explicitly mandate TLS certificate verification semantics: require
full chain validation, hostname verification, and expiry checks for all
https/wss endpoints; state that invalid or untrusted certificates MUST be
rejected by default; and add a narrowly scoped, auditable opt-in for self-signed
certificates that is only allowed for loopback addresses and must be explicitly
configured. Modify the two scenarios "Secure endpoint default (happy path)" and
"Insecure endpoint without opt-in (edge case)" to reference these verification
rules and the loopback-only self-signed opt-in mechanism so the validation
behavior is no longer implicit.
🪄 Autofix (Beta)
✅ Autofix completed
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: d167baee-f0a1-4bd1-8b2f-717bd0ae948c
📒 Files selected for processing (5)
openspec/changes/cerebro/cerebro.mdopenspec/changes/cerebro/design.mdopenspec/changes/cerebro/proposal.mdopenspec/changes/cerebro/specs/cerebro/spec.mdopenspec/changes/cerebro/tasks.md
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
- GitHub Check: pr-checks
- GitHub Check: sonar
- GitHub Check: pr-checks
- GitHub Check: Cloudflare Pages
🧰 Additional context used
📓 Path-based instructions (2)
**/*.{md,mdx}
⚙️ CodeRabbit configuration file
**/*.{md,mdx}: Verify technical accuracy and that docs stay aligned with code changes.
For user-facing docs, check EN/ES parity or explicitly note pending translation gaps.
Files:
openspec/changes/cerebro/tasks.mdopenspec/changes/cerebro/design.mdopenspec/changes/cerebro/proposal.mdopenspec/changes/cerebro/specs/cerebro/spec.mdopenspec/changes/cerebro/cerebro.md
**/*
⚙️ CodeRabbit configuration file
**/*: Security first, performance second.
Validate input boundaries, auth/authz implications, and secret management.
Look for behavioral regressions, missing tests, and contract breaks across modules.
Files:
openspec/changes/cerebro/tasks.mdopenspec/changes/cerebro/design.mdopenspec/changes/cerebro/proposal.mdopenspec/changes/cerebro/specs/cerebro/spec.mdopenspec/changes/cerebro/cerebro.md
🧠 Learnings (7)
📚 Learning: 2026-02-17T12:31:17.076Z
Learnt from: CR
Repo: dallay/corvus PR: 0
File: clients/agent-runtime/AGENTS.md:0-0
Timestamp: 2026-02-17T12:31:17.076Z
Learning: Applies to clients/agent-runtime/src/{security,gateway,tools}/**/*.rs : Treat `src/security/`, `src/gateway/`, `src/tools/` as high-risk surfaces and never broaden filesystem/network execution scope without explicit policy checks
Applied to files:
openspec/changes/cerebro/tasks.mdopenspec/changes/cerebro/cerebro.md
📚 Learning: 2026-02-17T12:31:17.076Z
Learnt from: CR
Repo: dallay/corvus PR: 0
File: clients/agent-runtime/AGENTS.md:0-0
Timestamp: 2026-02-17T12:31:17.076Z
Learning: Applies to clients/agent-runtime/**/*.rs : Run `cargo fmt --all -- --check`, `cargo clippy --all-targets -- -D warnings`, and `cargo test` for code validation, or document which checks were skipped and why
Applied to files:
openspec/changes/cerebro/tasks.mdopenspec/changes/cerebro/cerebro.md
📚 Learning: 2026-02-17T12:31:17.076Z
Learnt from: CR
Repo: dallay/corvus PR: 0
File: clients/agent-runtime/AGENTS.md:0-0
Timestamp: 2026-02-17T12:31:17.076Z
Learning: Include threat/risk notes and rollback strategy for security, runtime, and gateway changes; add or update tests for boundary checks and failure modes
Applied to files:
openspec/changes/cerebro/design.mdopenspec/changes/cerebro/proposal.md
📚 Learning: 2026-02-17T12:31:17.076Z
Learnt from: CR
Repo: dallay/corvus PR: 0
File: clients/agent-runtime/AGENTS.md:0-0
Timestamp: 2026-02-17T12:31:17.076Z
Learning: Applies to clients/agent-runtime/src/main.rs : Preserve CLI contract unless change is intentional and documented; prefer explicit errors over silent fallback for unsupported critical paths
Applied to files:
openspec/changes/cerebro/proposal.mdopenspec/changes/cerebro/cerebro.md
📚 Learning: 2026-02-17T12:31:17.076Z
Learnt from: CR
Repo: dallay/corvus PR: 0
File: clients/agent-runtime/AGENTS.md:0-0
Timestamp: 2026-02-17T12:31:17.076Z
Learning: Keep each iteration reversible with small commits and clear rollback strategy; validate assumptions with code search before implementing
Applied to files:
openspec/changes/cerebro/proposal.md
📚 Learning: 2026-02-17T07:28:38.934Z
Learnt from: CR
Repo: dallay/corvus PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-02-17T07:28:38.934Z
Learning: Applies to .agents/AGENTS.md : Maintain comprehensive agent metadata including name, description, purpose, and capabilities
Applied to files:
openspec/changes/cerebro/specs/cerebro/spec.md
📚 Learning: 2026-02-17T12:31:17.076Z
Learnt from: CR
Repo: dallay/corvus PR: 0
File: clients/agent-runtime/AGENTS.md:0-0
Timestamp: 2026-02-17T12:31:17.076Z
Learning: Applies to clients/agent-runtime/src/{security,gateway,tools,config}/**/*.rs : Do not silently weaken security policy or access constraints; keep default behavior secure-by-default with deny-by-default where applicable
Applied to files:
openspec/changes/cerebro/specs/cerebro/spec.md
🪛 LanguageTool
openspec/changes/cerebro/cerebro.md
[grammar] ~174-~174: Use a hyphen to join words.
Context: ...3. Error Handling & Resilience * Fail safe: save/search should degrade grace...
(QB_NEW_EN_HYPHEN)
Contributor
|
Note Autofix is a beta feature. Expect some limitations and changes as we gather feedback and continue to improve it. Fixes Applied SuccessfullyFixed 1 file(s) based on 1 unresolved review comment. A stacked PR containing fixes has been created.
Time taken: |
# Conflicts: # openspec/changes/cerebro/tasks.md
|
This was referenced Mar 16, 2026
8 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces comprehensive documentation and design specifications for the new Cerebro memory module, which centralizes long-term, agent-agnostic memory behind an MCP (Model Context Protocol) service. The changes clarify the architecture, migration strategy, and integration plan for shifting from the SurrealDB backend to the new Cerebro module, while maintaining compatibility for existing agents. The documentation covers product philosophy, technical design, data flow, API surface, security model, migration plan, and testing strategy.
Key changes include:
Product Overview and Specification
Design and Integration Plan
Implementation Proposal and Scope
Documentation Updates
.agents/AGENTS.mdto document the addition of the Cerebro memory module, describe its integration, architecture, data model, memory hygiene, and TUI observability features, and provide guidance for agent integration. [1] [2]