This directory contains all Architecture Decision Records (ADRs) for the Memory Context Browser project.
- ADR 001: Modular Crates Architecture — Workspace crate organization
- ADR 002: Async-First Architecture — Tokio async patterns
- ADR 003: Unified Provider Architecture & Routing — Provider abstraction, multi-provider routing, failover
- ADR 005: Context Cache Support (Moka and Redis) — Hybrid caching layer
- ADR 006: Code Audit and Architecture Improvements — Quality improvements
- ADR 008: Git-Aware Semantic Indexing — Repository-level context
- ADR 009: Persistent Session Memory — Cross-session observation storage
- ADR 010: Hooks Subsystem with Agent-Backed Processing — Agent hooks
- ADR 011: HTTP Transport Request/Response Pattern
- ADR 012: Two-Layer DI Strategy — Historical; see ADR-050 for current composition root
- ADR 013: Clean Architecture Crate Separation — Seven-crate workspace
- ADR 014: Multi-Domain Architecture Strategy — Future domain expansion
- ADR 015: Workspace Shared Libraries — Shared code in libs/
- ADR 016: Integration Points and Adapter Pattern — PMAT integration
- ADR 017: Phased Feature Integration — Release roadmap
- ADR 018: Hybrid Caching Strategy — Moka + SHA256 caching
- ADR 019: Error Handling Strategy — thiserror + anyhow integration
- ADR 020: Testing Strategy Integration — Test migration plan
- ADR 021: Dependency Management — Workspace dependencies
- ADR 022: CI Integration Strategy — Quality gates and benchmarks
- ADR 023: Inventory to Linkme Migration — Plugin registration simplification
- ADR 024: Simplified Dependency Injection — Historical; superseded by ADR-050
- ADR 027: Architecture Evolution v0.1.3 — Onion/Clean enhancement — Proposed
- ADR 028: Advanced Code Browser v0.2.0
- ADR 030: Multi-Provider Strategy — Merged into ADR-003
- ADR 031: Documentation Excellence — Documentation standards
- ADR 032: Agent & Quality Domain Extension — Superseded by ADR-034
- ADR 033: MCP Handler Consolidation — Handler registration and routing
- ADR 039: Context Persistence Boundary — Proposed
- ADR 040: Unified Tool Execution Gate — Proposed
- ADR 048: Gap-Free Observability Strategy — OpenTelemetry metrics, logs, traces — Accepted
The v0.3.0 release is a full platform rebuild on SeaQL (SeaORM, SeaQuery, SeaSchema, SeaStreamer) and Loco.rs. See ADR 051 for the master plan.
- ADR 049: Axum Return for rmcp Tower Compatibility — Supersedes ADR-026 — Accepted
- ADR 050: Manual Composition Root — dill Removal — Supersedes ADR-029 — Implemented
- ADR 051: SeaQL + Loco.rs Platform Rebuild — Supersedes ADR-004, 007, 025, 026 — Accepted
- ADR 052: Schema Resolution with SeaORM 2.x — Domain-driven DDL generation — Accepted
- ADR 053: Shared Provider Resolution — Extends ADR-050, shared provider lifecycle — Accepted
- ADR 054: mcb-utils Innermost Crate — Utility crate boundary — Accepted
- ADR 055: Constants SSOT Enforcement — Shared constants and validation — Accepted
- ADR 056: Multi-Tenant Isolation and OIDC Boundary — Tenant identity and vector-store boundary — Proposed
- ADR 057: Multi-Agent Coordination and SSOT Consolidation — Generated pointers and rule ownership — Accepted
- ADR 034: Workflow Core FSM — Finite state machine and persistence
- ADR 035: Context Scout — Project state discovery
- ADR 036: Enforcement Policies — Policy enforcement framework
- ADR 037: Workflow Orchestrator — Coordination and MCP integration
- ADR 038: Multi-Tier Execution Model — Integration of ADR-034–037
- ADR 041: Context Architecture — 5-layer (v0.4.0-v0.5.0) context system design (future work)
- ADR 042: Knowledge Graph — Graph structure and relationships
- ADR 043: Hybrid Search Engine — RRF fusion algorithm
- ADR 044: Model Selection — Embedding and search model choices
- ADR 045: Context Versioning — Snapshot and temporal queries
- ADR 046: Integration Patterns — MCP tool integration
- ADR 047: Project Architecture — Central Hub and Multi-Dimensional Coordination
These ADRs have been superseded by newer decisions and moved to archive/:
| Archived ADR | Superseded By | Reason |
|---|---|---|
| 004 — Event Bus (Local and Distributed) | ADR 051 | Replaced by SeaStreamer event architecture |
| 007 — Integrated Web Administration Interface | ADR 051 | Replaced by Loco.rs + SeaORM Pro admin |
| 012 — DI Strategy (Shaku) | ADR-024 | Original Shaku-based DI approach |
| 024 — Simplified DI | ADR 050 | Replaced by manual composition root |
| 025 — Figment Configuration | ADR 051 | Replaced by Loco YAML config system |
| 026 — Routing Refactor (Rocket vs Poem) | ADR 049 | Replaced by Axum return for rmcp Tower |
| 029 — Hexagonal Architecture (dill) | ADR 050 | Replaced by linkme + Handle pattern |
| 032 — Agent Quality Domain | ADR 034 | Replaced by Workflow Core FSM |
This table explains how ADRs map to release themes. It is not a live roadmap or
task board. Use bd ready --json and bead-specific bd show <id> --json
commands for current work state.
| Version | Theme | Key ADRs |
|---|---|---|
| v0.1.x | Core architecture, Clean Architecture layers | 001–006, 011–013 |
| v0.1.2 | Refactoring: linkme, simplified DI, Figment | 023–024, 027–031 |
| v0.2.0 | Git-aware indexing, persistent memory, hooks | 008–010, 014–022 |
| v0.2.1 | Handler consolidation, context boundaries | 033, 039–040 |
| v0.2.2 | Observability (OpenTelemetry) | 048 |
| v0.3.0 | SeaQL + Loco.rs platform rebuild | 049–052 |
| v0.4.0 | Workflow FSM & enforcement policies | 034–038; current backlog tracked in mcb-6pjx |
| v0.5.0 | Integrated context system, knowledge graph | 041–047; create beads before implementation |
ADR status records the decision lifecycle. Any implementation_status value
inside an ADR is a historical snapshot unless that ADR explicitly names a bead;
live implementation state is tracked in bd.
| Status | Meaning |
|---|---|
| Proposed | Under discussion |
| Accepted | Approved and to be implemented |
| Implemented | Completed in codebase |
| Deprecated | No longer relevant |
| Superseded | Replaced by another ADR |
Total ADRs: 57 (ADR-001 through ADR-057)
- Active numbered files: 52 ADRs in this directory
- Archived copies: 3 superseded ADR files in
archive/ - Core Architecture: ADR-001–006 (5 active)
- v0.2.0 Features: ADR-008–010 (3 ADRs)
- Infrastructure: ADR-011–022 (12 ADRs)
- v0.1.2 Refactoring: ADR-023–031 (5 active, 3 archived)
- v0.2.1 Additions: ADR-032–033, 039–040 (4 ADRs)
- v0.2.2 Observability: ADR-048 (1 ADR)
- v0.3.0 Platform Rebuild: ADR-049–053 (5 ADRs)
- v0.3.2+ Governance/SSOT: ADR-054–057 (4 ADRs)
- v0.4.0 Workflow: ADR-034–038 (5 ADRs)
- v0.5.0 Context System: ADR-041–047 (7 ADRs)
Use the sequential numbering format: XXX-descriptive-name.md
See ADR Template and standard format.