Add automatic ADR session bootstrap/validation for MCP clients

[heraque]

Summary

I would like to propose a built-in ADR bootstrap/validation workflow inside codebase-memory- mcp, so agents can automatically initialize and validate the project ADR at session start
without relying on client-specific hooks or custom prompt logic.

The goal is to make ADR persistence a first-class server capability, not an agent-side
convention.

Problem

Today, ADR usage is possible through manage_adr, but in practice it depends on the agent or the
user remembering to:

1. inspect the codebase
2. gather architecture context
3. create or update the ADR manually
4. re-check whether the ADR is still current in later sessions

This creates a few problems:

• behavior is inconsistent across clients
• some agents never create an ADR unless explicitly told to
• stale ADRs are easy to miss
• the same project may behave differently in Codex, OpenCode, Claude Code, etc.
• architectural context can be lost across sessions even though the MCP server already has enough
  information to help

Proposed Idea

Introduce a new MCP tool such as:

{
  "name": "session_init"
}

This tool would be called at the beginning of an agent session and would:

- detect whether an ADR already exists
- bootstrap one automatically if missing
- validate whether the ADR is stale compared to current project state
- return a structured summary that the agent can present to the user

## Why this is valuable

This would improve:

- consistency across MCP clients
- architectural continuity between sessions
- onboarding for new repositories
- reliability of agent behavior
- reuse of architecture context already available in the graph/store

Instead of every client inventing its own “remember to create/update an ADR” behavior, the MCP
server would provide one canonical workflow.

## Proposed Behavior

### 1. Missing ADR

If no ADR exists yet:

- gather architecture context from the indexed project
- detect the project stack
- generate an initial ADR skeleton
- persist it
- return status like BOOTSTRAPPED

### 2. Existing ADR

If an ADR already exists:

- inspect the current indexed project state
- compare stack/config/runtime signals against the ADR
- detect whether the ADR looks current or stale
- return status like:
    - CURRENT
    - STALE

### 3. Force update

Optional support for:

- force_update: true

This could refresh inferred sections while preserving user-authored sections such as tradeoffs/
philosophy.

## Suggested Output Shape

Something along these lines:

{
  "status": "BOOTSTRAPPED | CURRENT | STALE",
  "adr_summary": {
    "purpose": "...",
    "stack": ["..."],
    "patterns": ["..."]
  },
  "staleness_diff": {
    "added": [],
    "removed": [],
    "changed": []
  },
  "message": "Human-readable summary for the agent to show the user"
}

## Suggested Data Sources

The tool could reuse existing capabilities rather than inventing a second architecture system:

- get_architecture
- search_graph
- indexed project metadata
- root config files like:
    - go.mod
    - package.json
    - pyproject.toml
    - requirements.txt
    - Cargo.toml
    - pom.xml
    - build.gradle
    - Docker/CI files

## Important Design Principle

I think this should be implemented with the smallest possible scope and without broad refactors.

In particular, a good implementation would ideally:

- preserve manual ADR sections during updates
- avoid changing global project identity semantics unless strictly necessary
- avoid coupling unrelated install/client behavior into the feature itself
- keep the implementation focused on ADR lifecycle, not a general transport/session rewrite

In other words, the value is the ADR workflow itself, not a large re-architecture of the MCP
server.

## Suggested Minimal Scope

A minimal first version could:

- require the project to already be indexed
- bootstrap ADR if missing
- compare current stack/config against ADR if present
- preserve manual sections on update
- return structured output for agents

This alone would already be useful.

## Non-Goals for a first version

Things that do not need to be solved in the first implementation:

- client-specific UX flows
- auto-editing unrelated project docs
- generalized session orchestration beyond ADR
- a large rewrite of transport or server initialization
- perfect stack inference for every ecosystem

## Expected Impact

If this exists in the server itself, any MCP client can benefit:

- Codex
- OpenCode
- Claude Code
- other MCP-compatible agents

That makes ADR support portable and durable instead of prompt-dependent.

## Example User Experience

A user opens a session in an already indexed repo.

The agent calls session_init() first.

Possible result:

- BOOTSTRAPPED: “ADR was missing and has been created from the indexed project state.”
- CURRENT: “ADR is current.”
- STALE: “ADR is stale. A new dependency/config change was detected. Do you want to update it
  before continuing?”

This would be a very strong default workflow for long-lived projects.

## Request

Would maintainers be open to adding an ADR lifecycle tool like this to the MCP server itself?

If yes, I think it would be best to keep the first implementation intentionally small and low-
risk, and then iterate from there.