# Session Buddy Oneiric + mcp-common Migration Plan
**Status:** Phases 1-5 Complete ✅ | Phase 6 In Progress ⚠️ | Not Release Ready
**Owner:** Platform Core
**Phase 0 Completion Date:** 2024-01-15
**Phase 1 Completion Date:** 2024-12-28
**Phase 2 Completion Date:** 2024-12-28
**Phase 3 Completion Date:** 2024-12-28
**Phase 5 Progress:** 4/4 adapters converted to Oneiric-only defaults
**Phase 6 Progress:** Validation pending (post-cutover)
**Scope:** session-buddy runtime + CLI + settings + adapter conversion to Oneiric and mcp-common standards
**Current Priority:** Run post-cutover validation and update docs for Oneiric-only usage
**References:**
- `../fastblocks/ONEIRIC_MIGRATION_PLAN.md`
- `../crackerjack/archive/ONEIRIC_CUTOVER_PLAN.md.archived`
- `../mcp-common/docs/ONEIRIC_CLI_FACTORY_IMPLEMENTATION.md`
- `../archive/integration-docs/MCP_COMMON_INTEGRATION_SUMMARY.md`
- `../../session_buddy/cli.py`
- `../../session_buddy/server.py`
- `../../session_buddy/settings.py`
______________________________________________________________________
## Current Status Summary (2025-12-29)
### ✅ Completed
- **Phase 1: MCP CLI Factory Adoption** - All CLI commands working (start, stop, restart, status, health)
- **Phase 2: Oneiric Runtime Snapshots** - Snapshots fully implemented and tested
- **Phase 3: Settings Migration** - MCPBaseSettings fully implemented with YAML support
- **Phase 4: Oneiric DI Conversion** - Oneiric resolver + service container in place
### ✅ Completed
- **Phase 5: Adapter Conversion** - Oneiric implementations wired for reflection, knowledge graph, storage registry, and serverless storage
### ⚠️ In Progress
- **Phase 6: Validation + Cutover** - Post-cutover parity matrix + FastMCP validation still required before release
### Critical Path
1. **Phase 6 validation** (required before release)
- Re-run parity matrix after Oneiric-only cutover
- Re-run FastMCP validation + tool registration checks
1. **Phase 7: Documentation updates** (required before release)
- Update user documentation with Oneiric-only usage
- Add migration notes for Oneiric conversion
- Update API documentation for new implementations
### Test Status (last verified 2024-12-28)
- ✅ CLI commands work: `python -m session_buddy status` returns "Server not running"
- ✅ Health commands work: `health` and `health --probe` both functional
- ✅ Snapshot functionality verified: `.oneiric_cache/` created with proper files
- ✅ Oneiric reflection adapter tested: Native DuckDB implementation with full API compatibility
- ✅ Oneiric knowledge graph adapter tested: Native DuckDB PGQ implementation working
- ✅ Oneiric storage registry tested: Native file/memory implementations working
- ✅ Adapter integration tested: DI system works with Oneiric adapters
- ✅ Health checks updated: All adapters report healthy status
- ✅ Complete integration tested: All adapters work together through DI system
- ❌ Unit tests failing: `test_cli.py` imports old `app` symbol (expected - CLI migrated)
- ✅ Knowledge graph adapter tests: All 27 tests passing
- ✅ Session storage adapter: Basic functionality verified
- ✅ Integration tests completed: All systems operational
- ✅ Adapter interactions verified: DI system working correctly
- ✅ FastMCP validation completed: Server functionality and tool registration working
- ✅ Parity matrix validation completed: Oneiric implementations match expected behavior
- ⚠️ Oneiric-only validation pending: rerun post-cutover validation suite
______________________________________________________________________
## Progress Tracking
Update checkboxes as tasks are completed. Add dates or notes inline when needed.
### Phase 0: Alignment + Baselines ✅ COMPLETED 2024-01-15
- [x] Confirm cutover posture (Oneiric-only vs. hybrid bridge).
- **Decision**: Oneiric-only end state; allow hybrid bridge during transition
- [x] Confirm CLI migration scope (standard lifecycle commands, no legacy flags).
- **Decision**: Standard lifecycle commands only, remove legacy boolean flags
- [x] Confirm access modes: HTTP streaming is primary; stdio must remain supported.
- **Decision**: HTTP streaming primary (ports 8677/8678), STDIO preserved for compatibility
- [x] Capture baseline ACB usage: `rg -n "\\bacb\\b" session_buddy`.
- **Result**: 64 ACB references across core modules (see ../archive/oneiric-migration/baseline_acb_usage.txt)
- [x] Capture baseline CLI flags and entrypoints (`session_buddy/cli.py`, `session_buddy/__main__.py`).
- **Result**: Typer-based CLI with boolean flags, documented in ../archive/oneiric-migration/baseline_cli_analysis.txt
- [x] Capture current health/status behavior (ports 8677/8678, psutil scanning).
- **Result**: Process-based detection with port scanning, documented in ../archive/oneiric-migration/baseline_health_analysis.txt
- [x] Confirm Oneiric + mcp-common versions from `pyproject.toml` and `uv.lock`.
- **Result**: mcp-common>=0.3.6, oneiric>=0.3.3, acb>=0.32.0 (see ../archive/oneiric-migration/baseline_versions.txt)
- [x] Define rollback plan (revert tag + rollback steps) with owner and trigger criteria.
- **Result**: Comprehensive rollback plan defined in ../archive/oneiric-migration/phase0_decisions.txt
- [x] Block Phase 1 start until recovery plan is approved.
- **Status**: Recovery plan approved, proceeding to Phase 1
### Phase 1: MCP CLI Factory Adoption ✅ COMPLETED 2024-12-28
Replace custom Typer boolean flags with mcp-common CLI factory and standard lifecycle commands.
- [x] Replace CLI in `session_buddy/cli.py` with `MCPServerCLIFactory`.
- **Status**: New CLI implemented in `session_buddy/cli.py` with MCPServerCLIFactory
- **Commands**: start, stop, restart, status, health all working
- **Verification**: CLI help shows standard MCP commands, status command works
- [x] Add Session Buddy MCP settings extending `MCPServerSettings` (server name, cache root, TTL).
- **Status**: SessionBuddySettings class created with custom settings (http_port, websocket_port, timeouts)
- [x] Implement start handler that launches `session_buddy.server.main()` in HTTP streaming mode.
- **Status**: start_server_handler() implemented and integrated
- **Verification**: Start handler calls server.main() with HTTP mode
- [x] Implement stop handler that targets the factory PID and respects timeout/force.
- **Status**: Using default MCPServerCLIFactory stop handler (inherits proper PID management)
- [x] Update `session_buddy/__main__.py` entrypoint to invoke factory app.
- **Status**: ✅ Updated to use new CLI main function
- **Usage**: `python -m session_buddy start/stop/restart/status/health`
- [x] Remove legacy `--start-mcp-server/--stop-mcp-server/--status` flags.
- **Status**: ✅ Replaced with standard MCP commands
- **Old flags removed**: --start-mcp-server, --stop-mcp-server, --status
- [x] Preserve stdio entrypoint behavior for direct MCP client invocation.
- **Status**: ✅ STDIO mode preserved through server.main() call
- **Verification**: Start handler calls server.main() directly
### Phase 2: Oneiric Runtime Snapshots + Health ✅ COMPLETED 2024-12-28
Adopt `.oneiric_cache/` snapshots and standard health behavior.
- [x] Write `.oneiric_cache/runtime_health.json` on startup and periodic updates.
- **Status**: ✅ Fully implemented and tested
- **Verification**: Snapshots created with correct JSON structure and permissions
- **Files**: `.oneiric_cache/runtime_health.json` exists with proper content
- [x] Write `.oneiric_cache/runtime_telemetry.json` with basic counters/uptime.
- **Status**: ✅ Fully implemented and tested
- **Verification**: Telemetry snapshots include PID, uptime, and counters
- **Files**: `.oneiric_cache/runtime_telemetry.json` exists with proper content
- [x] Ensure `health --probe` runs live checks and updates snapshots.
- **Status**: ✅ Health probe working and updating telemetry counters
- **Verification**: `health --probe` command works and updates health_probes counter
- **Implementation**: update_telemetry_counter() called in \_run_health_probe()
- [x] Ensure `status` uses PID + snapshot freshness (no psutil port scan).
- **Status**: ✅ CLI factory status uses PID-based detection (no psutil)
- **Verification**: Status command works without errors or port scanning
- [x] Align TTL and cache paths with `MCPServerSettings`.
- **Status**: ✅ SessionBuddySettings extends MCPServerSettings with proper paths
- **Verification**: health_snapshot_path() and telemetry_snapshot_path() use MCP paths
- [x] Ensure snapshots are created for HTTP streaming runtime without breaking stdio mode.
- **Status**: ✅ Snapshot loop runs in FastMCP lifespan for both transports
- **Verification**: Snapshot functionality tested independently of server mode
- **Implementation**: run_snapshot_loop() in session_lifecycle() context manager
**Implementation Details:**
- RuntimeSnapshotManager handles both health and telemetry snapshots
- Snapshot loop runs every health_ttl_seconds/2 (minimum 5 seconds)
- Files created with secure permissions (600 for files, 700 for directory)
- Atomic writes using .tmp files to prevent corruption
- Health probe updates telemetry counters via update_telemetry_counter()
### Phase 3: Settings Migration (MCPBaseSettings) ✅ COMPLETED 2024-12-28
Migrate ACB `Settings` usage to mcp-common base settings.
- [x] Convert `SessionMgmtSettings` in `session_buddy/settings.py` to `MCPBaseSettings`.
- **Status**: ✅ Settings now use MCPBaseSettings load + validators
- **Verification**: Settings file uses MCPBaseSettings as base class
- [x] Add common MCP fields (server_name, server_description, log_level).
- **Status**: ✅ MCP fields added with defaults + YAML support
- **Verification**: settings/session-buddy.yaml contains MCP base fields
- [x] Map existing `debug` flag to `enable_debug_mode`.
- **Status**: ✅ Legacy debug mapping via model validator
- **Verification**: map_legacy_debug_flag validator handles debug → enable_debug_mode
- [x] Adopt helper methods for data directories and API key retrieval.
- **Status**: ✅ Database paths and LLM API key checks now use MCPBaseSettings helpers
- **Verification**: get_database_path(), get_llm_api_key() use MCPBaseSettings methods
- [x] Update existing settings files: `settings/session-buddy.yaml`, `settings/local.yaml.template`.
- **Status**: ✅ Added MCP base settings + enable_debug_mode
- **Verification**: Both files contain MCP base settings structure
- [x] Update settings loading call sites to use mcp-common patterns.
- **Status**: ✅ get_settings now loads via MCPBaseSettings
- **Verification**: SessionMgmtSettings.load("session-buddy") pattern used
### Phase 4: Oneiric Runtime and DI Conversion ✅ COMPLETE
Replace ACB dependency injection and lifecycle patterns with Oneiric equivalents.
- [x] Replace `acb.depends` usage with Oneiric resolver/lifecycle entrypoints.
- **Status**: ✅ Replaced depends with Oneiric-backed service container
- **Verification**: session_buddy/di/container.py uses Oneiric Resolver
- [x] Refactor `session_buddy/di/` to Oneiric service registration.
- **Status**: ✅ New service container + Config registration
- **Verification**: ServiceContainer uses Oneiric Candidate/Resolver
- [x] Define service boundaries for core modules (server_core, tools, memory, utils).
- **Status**: ✅ Service registry defines core/tools/memory/utils boundaries
- **Verification**: Service boundaries documented in lifecycle/service_registry.py
- [x] Ensure all services expose init/health/cleanup hooks.
- **Status**: ✅ Default registry provides init/health/cleanup hooks per service
- **Verification**: Service registry has hook methods
- [x] Remove hybrid bridge once Oneiric-only cutover is ready.
- **Status**: ✅ Oneiric-only adapter wiring in place
### Phase 5: Adapter Conversion and Lifecycle ✅ COMPLETE (4/4 Oneiric implementations wired)
Convert ACB adapters and storage integrations to Oneiric lifecycle contracts.
- [x] Inventory adapters: reflection, knowledge_graph, storage registry, serverless storage.
- **Status**: ✅ Inventory captured in adapter registry/lifecycle wiring
- **Verification**: Adapters listed in adapters/__init__.py
- [x] For each adapter:
- [x] **Reflection Adapter**: Define Oneiric settings model.
- **Status**: ✅ ReflectionAdapterSettings already uses dataclass pattern
- **Verification**: Settings in session_buddy/adapters/settings.py
- [x] **Reflection Adapter**: Implement init/health/cleanup.
- **Status**: ✅ Oneiric implementation created with full lifecycle
- **Verification**: ReflectionDatabaseAdapterOneiric with async methods
- [x] **Reflection Adapter**: Switch default wiring to Oneiric-only and remove ACB imports.
- **Status**: ✅ Oneiric-only adapter shim in place
- [x] **Knowledge Graph Adapter**: Define Oneiric settings model.
- **Status**: ✅ KnowledgeGraphAdapterSettings already exists
- **Verification**: Settings in session_buddy/adapters/settings.py
- [x] **Knowledge Graph Adapter**: Implement init/health/cleanup.
- **Status**: ✅ Oneiric implementation created with full lifecycle
- **Verification**: KnowledgeGraphDatabaseAdapterOneiric with async methods
- [x] **Knowledge Graph Adapter**: Switch default wiring to Oneiric-only and remove ACB Config usage.
- **Status**: ✅ Oneiric-only adapter shim in place
- [x] **Storage Registry**: Define Oneiric settings model.
- **Status**: ✅ StorageAdapterSettings already exists
- **Verification**: Settings in session_buddy/adapters/settings.py
- [x] **Storage Registry**: Implement init/health/cleanup.
- **Status**: ✅ Oneiric implementation with full lifecycle
- **Verification**: StorageBaseOneiric with async/sync methods
- [x] **Storage Registry**: Switch default wiring to Oneiric-only and remove ACB storage adapters.
- **Status**: ✅ Oneiric-only storage registry shim in place
- [x] **Serverless Storage**: Define Oneiric settings model.
- **Status**: ✅ Serverless storage uses Oneiric-backed SessionStorageAdapter
- [x] **Serverless Storage**: Implement init/health/cleanup.
- **Status**: ✅ Serverless storage lifecycle handled by Oneiric adapters
- [x] **Serverless Storage**: Replace ACB adapter registration.
- **Status**: ✅ Oneiric storage wiring only
- [x] Keep hybrid sync/async pattern where DuckDB requires it.
- **Status**: ✅ Knowledge graph adapter keeps async API with sync DuckDB operations
- **Verification**: Async methods with sync DuckDB calls
- [x] Remove compatibility layers after cutover if no external integrations require them.
- **Status**: ✅ Oneiric-only storage in use
**Progress Summary:**
- ✅ **Reflection Adapter**: Oneiric-only default wiring
- ✅ **Knowledge Graph Adapter**: Oneiric-only default wiring
- ✅ **Storage Registry**: Oneiric-only registry
- ✅ **Serverless Storage**: Oneiric-only storage adapter
**Current State:**
- Reflection adapter: Oneiric-only adapter shim
- Knowledge graph adapter: Oneiric-only adapter shim
- Storage registry: Oneiric-only registry
- Serverless storage: Oneiric-only storage adapter
### Phase 6: Validation Gates + Cutover ⚠️ IN PROGRESS
Crackerjack-style gates (required before release).
- [x] Remove ACB dependency and remaining imports.
- **Status**: ✅ 0 ACB references remain (audit 2025-12-29)
- **Action needed**: Remove `acb` from lockfile on next `uv sync`
- [x] MCP lifecycle commands work: `start/stop/restart/status/health`.
- **Status**: ✅ All commands working (start, stop, restart, status, health, health --probe)
- **Verification**: CLI commands tested and functional
- [x] `health --probe` returns live data (not cached snapshot).
- **Status**: ✅ Health probe working and updating telemetry counters
- **Verification**: Health probe tested and updates health_probes counter
- [x] `.oneiric_cache/runtime_health.json` exists and is valid JSON.
- **Status**: ✅ Snapshot file created with valid JSON structure
- **Verification**: File exists with proper health snapshot content
- [x] `.oneiric_cache/` contains PID + snapshot files with correct permissions.
- **Status**: ✅ Directory and files created with secure permissions (700/600)
- **Verification**: .oneiric_cache/runtime_health.json and runtime_telemetry.json exist
- [x] Oneiric-only cutover completed (no ACB fallbacks).
- **Status**: ✅ Oneiric-only adapters wired by default
- [ ] Parity matrix executed post-cutover (core runtime, MCP tools, memory adapters, serverless mode).
- **Status**: ⚠️ Pending post-cutover validation
- **Result**: Must confirm Oneiric implementations match expected behavior
- [ ] FastMCP tool registration tests passing post-cutover.
- **Status**: ⚠️ Pending post-cutover validation
- [ ] Update MCP client config examples to new CLI syntax.
- **Status**: ⚠️ Move to Phase 7 docs checklist
**FastMCP verification checklist (rerun post-cutover)**
- [ ] MCP tool registration tests pass (server init + decorator wiring).
- **Status**: ⚠️ Pending post-cutover validation
- [ ] MCP tool execution tests pass (sample tool call).
- **Status**: ⚠️ Pending post-cutover validation
- [ ] Middleware compatibility tests pass (no unhashable request context errors).
- **Status**: ⚠️ Pending post-cutover validation
### Oneiric-Only Cutover Checklist (File-Level)
- [x] `session_buddy/adapters/__init__.py`: remove ACB fallback imports; wire Oneiric-only adapters.
- [x] `session_buddy/adapters/reflection_adapter.py`: replace legacy ACB adapter path (prefer `reflection_adapter_oneiric.py`).
- [x] `session_buddy/adapters/knowledge_graph_adapter.py`: drop ACB Config usage; default to Oneiric implementation.
- [x] `session_buddy/adapters/storage_registry.py`: remove ACB storage adapters; route to `storage_oneiric.py`.
- [x] `session_buddy/adapters/session_storage_adapter.py`: remove ACB storage base dependency; align with Oneiric storage contract.
- [x] `session_buddy/serverless_mode.py`: remove "acb" backend option and references; update messaging to Oneiric storage.
- [x] `session_buddy/backends/acb_cache_backend.py`: remove or replace with Oneiric equivalent.
- [x] `session_buddy/resource_cleanup.py`: remove ACB adapter import and wire cleanup via Oneiric services.
- [x] `session_buddy/utils/error_handlers.py`: remove ACB adapter import and update error paths.
- [x] `session_buddy/core/session_manager.py`: remove ACB import paths (templates adapter); replace with Oneiric template handling.
- [x] `session_buddy/tools/crackerjack_tools.py`: remove ACB adapter import; update to Oneiric tool wiring.
- [x] `session_buddy/llm/providers/ollama_provider.py`: remove ACB adapter import; update dependency guidance.
- [x] `session_buddy/di/__init__.py`: remove ACB Config import; rely on Oneiric config wiring.
- [x] `session_buddy/adapters/knowledge_graph_adapter_acb_investigation.py`: archive or remove (no longer active).
- [x] `session_buddy/cli_old.py`: remove legacy CLI code (no longer active).
- [x] `pyproject.toml`: remove ACB dependency once imports are cleared.
- [x] Re-run `rg -n "\\bacb\\b" session_buddy` and update Phase 6 ACB reference count.
### Phase 7: Docs + Release ⚠️ NEXT
- [ ] Update docs and examples to use `start/stop/restart/status/health`.
- [ ] Update `README.md` and user docs to Oneiric-only usage.
- [ ] Update `docs/user/CONFIGURATION.md` with MCPBaseSettings fields.
- [ ] Add migration notes for Oneiric-only conversion.
- [ ] Release notes include Oneiric-only changes and breaking changes.
______________________________________________________________________
## Appendix A: Parity Matrix Template (Functional Only)
| Area | Scenario | Expected Result | Status | Evidence |
| --- | --- | --- | --- | --- |
| Core runtime | Start server | Starts without errors | [ ] | |
| Core runtime | Stop server | Clean shutdown, no orphaned tasks | [ ] | |
| Core runtime | Config load | Settings resolved via MCPBaseSettings | [ ] | |
| MCP CLI | start | Server starts via CLI factory | [ ] | |
| MCP CLI | status | Reports accurate status | [ ] | |
| MCP CLI | health --probe | Live health returned | [ ] | |
| MCP tools | tool registration | Tools listed and callable | [ ] | |
| MCP tools | tool execution | Sample tool returns expected output | [ ] | |
| Memory | reflection adapter | Reads/writes succeed | [ ] | |
| Memory | knowledge graph | Graph queries succeed | [ ] | |
| Serverless | storage adapter | File/memory backends succeed | [ ] | |
______________________________________________________________________
## Appendix B: CLI Command Mapping
| Current Flag | New Command | Notes |
| --- | --- | --- |
| `--start-mcp-server` | `start` | Standard factory command |
| `--stop-mcp-server` | `stop` | Standard factory command |
| `--status` | `status` | Standard factory command |
| `--health` | `health` | Standard factory command |
| `--health --probe` | `health --probe` | Standard factory command |
______________________________________________________________________
## Appendix C: Rollback Plan (Template)
1. Revert to last known good tag.
1. Restore previous CLI entrypoints and config files.
1. Remove `.oneiric_cache/` and re-enable legacy status checks.
1. Reinstall `acb` if Oneiric-only cutover fails.
1. Re-run MCP tool smoke checks and document impact.
