Skip to content

Commit fe45317

Browse files
cdeustcdeust
committed
docs: record shared backend startup decision and review follow-up
1 parent db22b16 commit fe45317

5 files changed

Lines changed: 64 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,13 @@ adheres to [Semantic Versioning](https://semver.org/).
2020

2121
### Fixed
2222

23+
- **Claude and direct MCP startup honour the same saved backend (#600).** A
24+
saved SQLite selection was honoured by the Claude launcher while direct
25+
console/module startup could select a reachable PostgreSQL server, sending
26+
the two hosts to different stores. Direct startup now resolves the saved
27+
selection before loading memory settings, preserving explicit overrides.
28+
Existing databases are not migrated or merged.
29+
2330
- **Procedural skills are stored on the default backend too (#596).** The
2431
`procedural_skills` table existed only on PostgreSQL, so on SQLite the
2532
session-end writer mined its skills and lost every one to an

‎docs/adr/ADR-1076-resolve-saved-backend-before-direct-mcp-startup-imports.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
<!-- Generated by Cortex wiki_reindex from wiki/adr/cortex/1076-resolve-saved-backend-before-direct-mcp-startup-imports.md; ADR-1076. Read-only mirror: edit the canonical wiki page. -->
2+
3+
---
4+
created: 2026-09-16T19:44:08Z
5+
kind: adr
6+
number: 1076
7+
status: proposed
8+
tags: [architecture, storage, codex, startup]
9+
title: Resolve saved backend before direct MCP startup imports
10+
---
11+
# ADR-1076: Resolve saved backend before direct MCP startup imports
12+
13+
## Status
14+
15+
proposed
16+
17+
## Context
18+
19+
ADR-0505 resolves the saved backend in scripts/launcher.py. Direct console and python -m mcp_server startup skipped that resolution: Claude could honour a saved SQLite selection while Codex selected a reachable PostgreSQL server. PR #600 reproduces four failing bootstrap cases before the fix. Settings-dependent registry imports bind configuration early, so resolution inside main() would happen too late.
20+
21+
## Decision
22+
23+
Call the existing apply_backend_resolution(os.environ) at module startup before settings-dependent imports. Preserve precedence: explicit CORTEX_MEMORY_STORE_BACKEND, then CORTEX_BACKEND alias, then non-empty DATABASE_URL or CORTEX_MEMORY_DATABASE_URL, then saved methodology/backend.json, otherwise existing automatic selection. Retain the existing blank DATABASE_URL normalization. Importing this entry point intentionally mutates the process environment when resolution requires it. Keep the file-wide Ruff suppression scoped to E402 only: the intervening resolver call makes fourteen pre-existing downstream imports trigger E402, as independently measured in the PR review; one file-level explanation records this shared ordering constraint instead of fourteen repeated annotations.
24+
25+
## Consequences
26+
27+
Claude launcher and direct MCP startup apply the same saved backend policy without duplicating the resolver or merging existing stores. Explicit overrides remain authoritative. Tests isolate configuration roots and use subprocesses to avoid ambient environment leakage. Nine bootstrap cases pass after the fix; the reviewer reproduced four failures on the baseline and reported 8670 full-suite passes at db22b167. This establishes startup selection and tested process handoff, not installed-host hook parity, semantic retrieval quality, or PostgreSQL handoff. Project ADR sharing additionally requires a common physical project_root; lean authoring permissions remain unchanged. Evidence: https://github.com/cdeust/Cortex/pull/600#issuecomment-5703423724 and tests_py/test_shared_backend_bootstrap.py.

‎mcp_server/__main__.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
"""
88

99
# ruff: noqa: E402 — backend selection must precede settings-dependent imports.
10+
# File-wide: the resolver call requires the same exemption for 14 existing imports.
1011

1112
from __future__ import annotations
1213

‎wiki/adr/cortex/1076-resolve-saved-backend-before-direct-mcp-startup-imports.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
created: 2026-09-16T19:44:08Z
3+
kind: adr
4+
number: 1076
5+
status: proposed
6+
tags: [architecture, storage, codex, startup]
7+
title: Resolve saved backend before direct MCP startup imports
8+
---
9+
# ADR-1076: Resolve saved backend before direct MCP startup imports
10+
11+
## Status
12+
13+
proposed
14+
15+
## Context
16+
17+
ADR-0505 resolves the saved backend in scripts/launcher.py. Direct console and python -m mcp_server startup skipped that resolution: Claude could honour a saved SQLite selection while Codex selected a reachable PostgreSQL server. PR #600 reproduces four failing bootstrap cases before the fix. Settings-dependent registry imports bind configuration early, so resolution inside main() would happen too late.
18+
19+
## Decision
20+
21+
Call the existing apply_backend_resolution(os.environ) at module startup before settings-dependent imports. Preserve precedence: explicit CORTEX_MEMORY_STORE_BACKEND, then CORTEX_BACKEND alias, then non-empty DATABASE_URL or CORTEX_MEMORY_DATABASE_URL, then saved methodology/backend.json, otherwise existing automatic selection. Retain the existing blank DATABASE_URL normalization. Importing this entry point intentionally mutates the process environment when resolution requires it. Keep the file-wide Ruff suppression scoped to E402 only: the intervening resolver call makes fourteen pre-existing downstream imports trigger E402, as independently measured in the PR review; one file-level explanation records this shared ordering constraint instead of fourteen repeated annotations.
22+
23+
## Consequences
24+
25+
Claude launcher and direct MCP startup apply the same saved backend policy without duplicating the resolver or merging existing stores. Explicit overrides remain authoritative. Tests isolate configuration roots and use subprocesses to avoid ambient environment leakage. Nine bootstrap cases pass after the fix; the reviewer reproduced four failures on the baseline and reported 8670 full-suite passes at db22b167. This establishes startup selection and tested process handoff, not installed-host hook parity, semantic retrieval quality, or PostgreSQL handoff. Project ADR sharing additionally requires a common physical project_root; lean authoring permissions remain unchanged. Evidence: https://github.com/cdeust/Cortex/pull/600#issuecomment-5703423724 and tests_py/test_shared_backend_bootstrap.py.

‎wiki/manifest.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3471,6 +3471,10 @@
34713471
"ADR-1075": {
34723472
"mirror": "ADR-1075-procedural-skills-are-stored-on-both-backends.md",
34733473
"path": "adr/cortex/1075-procedural-skills-are-stored-on-both-backends.md"
3474+
},
3475+
"ADR-1076": {
3476+
"mirror": "ADR-1076-resolve-saved-backend-before-direct-mcp-startup-imports.md",
3477+
"path": "adr/cortex/1076-resolve-saved-backend-before-direct-mcp-startup-imports.md"
34743478
}
34753479
},
34763480
"project": "cortex",

0 commit comments

Comments
 (0)