Refactor: move shared orchestration into basic_memory/app/ services; keep adapters thin

[phernandez]

Refactor: move shared orchestration into basic_memory/app/ services; keep adapters thin

Why

API routers and MCP tools often duplicate orchestration: resolve project → call services/repos → format response. Domain-ish orchestration should live in reusable application services.

Scope

• Create basic_memory/app/ layer for shared orchestration returning typed results (not strings):
  • e.g. NotesAppService, ProjectsAppService, ContextAppService
• Keep adapters thin:
  • API routers map to HTTP schemas
  • MCP tools map to markdown/guidance strings

Acceptance criteria

• Reduced duplication between MCP and API.
• Application services are independently testable.
• Adapters remain small and focused.

Dependencies

• Works best after typed internal API clients + config injection.

[claude]

Claude finished @phernandez's task in 2m 12s —— View job

---

Issue Triage Complete

Todo List

• Read CLAUDE.md for project context
• Explore current architecture (MCP tools and API routers)
• Search for related issues
• Classify issue and add appropriate labels
• Provide triage analysis

---

Classification

Type: Enhancement (Architectural Refactoring)
Priority: Medium
Complexity: Complex
Components: API, MCP, Services, Architecture

Label added: enhancement

---

Analysis

This issue proposes a significant architectural improvement to reduce code duplication between MCP tools and API routers by introducing a new application service layer (basic_memory/app/).

Current State

After reviewing the codebase, I can confirm there is significant duplication between MCP tools and API routers:

Example from search functionality:

• MCP tool (src/basic_memory/mcp/tools/search.py): ~380 lines

  • Project resolution logic
  • Search query building
  • API calls via async client
  • Rich error formatting for LLM consumption

• API router (src/basic_memory/api/routers/search_router.py): ~35 lines

  • Direct service calls
  • HTTP response formatting
  • Minimal orchestration

Example from read_note:

• MCP tool (src/basic_memory/mcp/tools/read_note.py): ~270 lines

  • Project resolution
  • Entity ID resolution
  • Multiple fallback strategies (permalink → title → text search)
  • Elaborate guidance formatting

• API router (src/basic_memory/api/routers/memory_router.py): ~90 lines

  • Direct context service calls
  • Simple HTTP response mapping

The duplication is particularly evident in:

1. Project resolution - Every MCP tool resolves the active project
2. Entity resolution - Converting identifiers to entity IDs
3. Search strategies - Fallback logic for finding content
4. Pagination logic - Converting page/page_size to limit/offset

Proposed Architecture

The issue proposes creating basic_memory/app/ services that:

• Contain reusable orchestration logic
• Return typed domain objects (not strings or HTTP responses)
• Are independently testable
• Can be called by both MCP tools and API routers

Example architecture:

basic_memory/app/notes_app_service.py
  ├─ read_note(project_id, identifier, page, page_size) → NoteResult
  ├─ search_notes(project_id, query, filters) → SearchResult
  └─ write_note(project_id, title, content) → NoteResult

MCP tools → format as markdown/guidance → return string
API routers → format as HTTP schemas → return JSON

Dependencies & Related Work

This refactoring has explicit dependencies on:

• Issue Refactor: extract typed internal API clients for MCP tools #494: "Refactor: extract typed internal API clients for MCP tools"
• Issue Refactor: explicit config injection (only roots read ConfigManager) #496: "Refactor: explicit config injection (only roots read ConfigManager)"
• Issue Refactor: introduce ProjectResolver and unify project selection across MCP/API/CLI #493: "Refactor: introduce ProjectResolver and unify project selection"

These issues form a cohesive refactoring plan to improve architecture:

1. Refactor: introduce ProjectResolver and unify project selection across MCP/API/CLI #493: Unify project resolution
2. Refactor: extract typed internal API clients for MCP tools #494: Create typed internal API clients
3. Refactor: move shared orchestration into basic_memory/app/ services; keep adapters thin #495: Extract application services (this issue)
4. Refactor: explicit config injection (only roots read ConfigManager) #496: Clean up config injection

Existing Services Layer

The project already has basic_memory/services/ with:

• entity_service.py
• search_service.py
• context_service.py
• project_service.py
• directory_service.py
• file_service.py

These are domain services that work with repositories and models. The proposed app/ layer would sit above these, orchestrating multiple services and handling cross-cutting concerns like:

• Project resolution
• Entity resolution
• Pagination
• Result formatting (typed objects, not strings)

Benefits

1. Reduced duplication - Orchestration logic written once
2. Better testability - Application services independently testable
3. Clearer separation - Adapters (MCP/API) stay thin, focused on I/O formatting
4. Type safety - Typed results instead of strings/dicts
5. Easier maintenance - Changes to orchestration in one place

Challenges

1. Scope - This touches many files across MCP tools and API routers
2. Sequential dependency - Best done after Refactor: introduce ProjectResolver and unify project selection across MCP/API/CLI #493, Refactor: extract typed internal API clients for MCP tools #494, Refactor: explicit config injection (only roots read ConfigManager) #496
3. Testing burden - Need comprehensive tests for app services
4. Migration strategy - Need to refactor incrementally to avoid breaking changes
5. Naming/boundaries - Need clear distinction between services/ (domain) and app/ (application orchestration)

---

Recommendation

This is a well-considered architectural improvement that addresses real duplication in the codebase. However:

1. Don't implement immediately - This should be done after the dependency issues (Refactor: introduce ProjectResolver and unify project selection across MCP/API/CLI #493, Refactor: extract typed internal API clients for MCP tools #494, Refactor: explicit config injection (only roots read ConfigManager) #496) are resolved
2. Plan carefully - This needs design discussion about:
   • Exact boundaries between services/ and app/
   • Which orchestration belongs in app layer vs MCP/API adapters
   • Migration strategy (big bang vs incremental)
3. Consider creating a design document - Given the scope, a SPEC document might help plan the refactoring
4. Incremental approach - Could start with one feature (e.g., notes) as a pilot before full migration

---

Next Steps

1. ✅ Issue triaged and labeled
2. ⏳ Wait for dependency issues to be resolved (Refactor: introduce ProjectResolver and unify project selection across MCP/API/CLI #493, Refactor: extract typed internal API clients for MCP tools #494, Refactor: explicit config injection (only roots read ConfigManager) #496)
3. 📝 Consider creating a SPEC document for detailed design
4. 💬 Discuss architectural boundaries and naming conventions
5. 🧪 Plan testing strategy for new app services
6. 🔨 Implement incrementally, starting with a pilot (e.g., notes operations)

[phernandez]

Closing as no longer needed

After implementing #494 (typed API clients), the architecture now cleanly separates concerns:

MCP Tool → Typed Client → HTTP API → Router → Service/Repository

The original problem this issue aimed to solve was:

"API routers and MCP tools often duplicate orchestration"

With typed API clients, MCP tools are now thin adapters that delegate to the API. The duplication is eliminated because:

• MCP tools call typed clients (thin)
• Typed clients call the HTTP API
• API routers call services (no duplication)

Adding an app/ services layer would:

1. Create unnecessary indirection
2. Potentially bypass the API, breaking the clean separation
3. Add complexity without clear benefit

The typed API clients achieve the same goal more elegantly. Closing as superseded by #494.