|
| 1 | +# Shared memory and decisions across Claude and Codex |
| 2 | + |
| 3 | +## What this change establishes |
| 4 | + |
| 5 | +Claude and Codex can connect independent Cortex MCP processes to the same |
| 6 | +storage and decision files. The direct console entry point now applies the |
| 7 | +saved backend selection before importing memory settings, matching the Claude |
| 8 | +launcher (ADR-0505). Previously, a saved SQLite selection could be ignored by |
| 9 | +the direct entry point: its automatic selection could choose a reachable local |
| 10 | +PostgreSQL server instead. |
| 11 | + |
| 12 | +This is a source-checkout change. Installing the currently published package |
| 13 | +does not establish that this fix is present; it must be released first. |
| 14 | + |
| 15 | +## Shared configuration contract |
| 16 | + |
| 17 | +Both processes need the same backend and physical storage location. For an |
| 18 | +isolated SQLite evaluation, set these variables identically in both launches: |
| 19 | + |
| 20 | +```sh |
| 21 | +export CORTEX_CLAUDE_DIR=/absolute/path/to/disposable-cortex |
| 22 | +export CORTEX_MEMORY_STORE_BACKEND=sqlite |
| 23 | +export CORTEX_MEMORY_DB_PATH="$CORTEX_CLAUDE_DIR/memory.db" |
| 24 | +export CORTEX_MEMORY_SQLITE_FALLBACK_PATH="$CORTEX_CLAUDE_DIR/memory.db" |
| 25 | +``` |
| 26 | + |
| 27 | +These paths are examples for disposable data. This workflow neither migrates |
| 28 | +nor merges existing databases. PostgreSQL deployments must likewise use the |
| 29 | +same explicit database target; cross-process PostgreSQL handoff is not covered |
| 30 | +by the new SQLite tests. |
| 31 | + |
| 32 | +Backend precedence remains: explicit `CORTEX_MEMORY_STORE_BACKEND`, then |
| 33 | +`CORTEX_BACKEND`, then a non-empty database URL, then the saved |
| 34 | +`methodology/backend.json` selection. Without these, existing automatic |
| 35 | +selection remains unchanged. An explicit unreachable PostgreSQL target must |
| 36 | +not silently redirect writes to SQLite. |
| 37 | + |
| 38 | +## ADRs also need shared files |
| 39 | + |
| 40 | +A shared database alone does not share project decision records. Project-mode |
| 41 | +`wiki_adr` stores files under the supplied absolute `project_root`, updates the |
| 42 | +project decision index, and returns `memory_sync: project-files-only` |
| 43 | +(ADR-0056). Both clients must pass the same physical project root with a valid |
| 44 | +`wiki/manifest.json`. Matching project labels in separate worktrees do not |
| 45 | +make their files shared. |
| 46 | + |
| 47 | +Use exact ADR identifiers for handoff. A missing or stale index fails closed; |
| 48 | +initialize or repair it with `wiki_reindex` before relying on exact lookup. |
| 49 | +For global wiki operations, the shared `CORTEX_CLAUDE_DIR` also determines the |
| 50 | +wiki root. |
| 51 | + |
| 52 | +## Tool permissions |
| 53 | + |
| 54 | +The bundled Codex plugin keeps its ten-tool `lean` profile (ADR-0693). |
| 55 | +It can recall a project ADR but cannot create one. An explicitly configured |
| 56 | +`--profile full` MCP process can author decisions. This exposes the full tool |
| 57 | +surface; it is not a narrowly scoped decision-writing profile. |
| 58 | + |
| 59 | +A minimal evaluation is: |
| 60 | + |
| 61 | +1. A full-profile client creates a project ADR with `wiki_adr`. |
| 62 | +2. A second client recalls its exact identifier using the same `project_root`. |
| 63 | +3. Another full-profile client writes a follow-up ADR that cites the first and |
| 64 | + describes the observed outcome. |
| 65 | +4. Both clients retrieve the follow-up and its reference. |
| 66 | + |
| 67 | +The follow-up reference is explicit text. These tests do not establish |
| 68 | +automatic outcome attribution, automatic conflict resolution, or equivalent |
| 69 | +Claude and Codex lifecycle hooks. |
| 70 | + |
| 71 | +## Reproducible checks |
| 72 | + |
| 73 | +The added tests use disposable roots and independent processes: |
| 74 | + |
| 75 | +- `tests_py/test_shared_backend_bootstrap.py`: saved selection and explicit |
| 76 | + override precedence at direct entry-point startup. Before the fix, four of |
| 77 | + nine cases failed; after the fix all nine pass. |
| 78 | +- `tests_py/test_shared_host_decisions.py`: actual MCP calls for full-to-lean |
| 79 | + exact ADR handoff, denied lean authoring, linked follow-up, simultaneous ADR |
| 80 | + allocation, and separation between two explicit project roots. |
| 81 | +- `tests_py/infrastructure/test_shared_host_store.py`: independent SQLite |
| 82 | + processes observe acknowledged writes, retain distinct concurrent records, |
| 83 | + and read persisted content after reopening. |
| 84 | + |
| 85 | +Run these with the repository Python environment and |
| 86 | +`CORTEX_MEMORY_STORE_BACKEND=sqlite`. The storage test bypasses embedding and |
| 87 | +semantic retrieval; its assertions concern committed rows. The MCP clients |
| 88 | +are test clients, not installed Claude or Codex applications. Project-root |
| 89 | +separation is a routing check, not an authorization boundary. |
| 90 | + |
| 91 | +### Test liveness policy |
| 92 | + |
| 93 | +The test harness uses 30-second bootstrap and protocol deadlines, a 90-second |
| 94 | +MCP scenario deadline, and 5 seconds per shutdown stage. These are engineering |
| 95 | +time budgets to fail stalled tests and clean up children before the existing |
| 96 | +300-second pytest ceiling, not algorithm constants or latency benchmarks. |
| 97 | + |
| 98 | +Validation on the local macOS checkout: all 12 new tests and 47 related |
| 99 | +backend, launcher, profile, and ADR tests passed. Ruff lint, formatting, |
| 100 | +and the craftsmanship gate passed. The store protocol test uses POSIX pipe |
| 101 | +selection; these results do not establish Windows coverage. Independent review |
| 102 | +approved the change after subprocess deadlines and cleanup were added. |
| 103 | + |
| 104 | +## Next acceptance step |
| 105 | + |
| 106 | +Run the released or explicitly checkout-backed server through both installed |
| 107 | +hosts against a disposable store. Verify the configured roots, available |
| 108 | +tools, decision creation, exact retrieval, and outcome handoff. Only then |
| 109 | +assess packaging changes and a public directory submission. No live host |
| 110 | +configuration, personal memory data, or marketplace listing is changed here. |
0 commit comments