# How to Manage Architecture Decision Records (ADRs) with Codebase-Memory-MCP: A Complete Guide

> Learn to manage Architecture Decision Records ADRs with Codebase-Memory-MCP. Persist ADRs in your code graph database for unified access via MCP tools APIs and Graph UI.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: how-to-guide
- Published: 2026-07-04

---

**Codebase-Memory-MCP treats Architecture Decision Records (ADRs) as first-class artifacts that persist in the same SQLite database as the code graph, enabling unified access via MCP tools, HTTP APIs, and the Graph UI.**

You can **manage Architecture Decision Records (ADRs) with Codebase-Memory-MCP** through three primary interfaces: a JSON-RPC MCP tool (`manage_adr`), RESTful HTTP endpoints (`/api/adr`), and an integrated React-based UI. Regardless of the interface used, all ADR operations target a single SQLite-backed storage layer defined in [`src/store/store.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.h) and implemented in [`src/store/store.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.c).

## Where ADRs Are Stored

Codebase-Memory-MCP persists ADRs inside the **project_summaries** SQLite database, ensuring they survive repository re-indexing and remain version-controlled alongside the code graph.

- **Table schema**: The `adr` table is created automatically during store initialization.
- **Storage limits**: Individual ADRs are capped at **8000 bytes** via the `CBM_ADR_MAX_LENGTH` constant defined in [`src/store/store.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.h).
- **Migration path**: The system performs a one-time migration from the legacy file [`/.codebase-memory/adr.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main//.codebase-memory/adr.md) into the SQLite store (implemented in [`src/mcp/mcp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c), lines 54-68).

## Core Storage API Functions

The underlying C API provides deterministic CRUD operations and markdown parsing utilities. All functions are declared in [`src/store/store.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.h) and implemented in [`src/store/store.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.c):

- **`cbm_store_adr_store`**: Insert or replace an entire ADR for a project.
- **`cbm_store_adr_get`**: Retrieve ADR content and timestamps.
- **`cbm_store_adr_delete`**: Remove an ADR from the store.
- **`cbm_store_adr_update_sections`**: Update specific sections of an ADR (used by the *sections* mode).
- **`cbm_adr_parse_sections`** / **`cbm_adr_render`**: Pure-function helpers that parse markdown sections into structured data and render them back to canonical text.
- **`cbm_adr_validate_content`** / **`cbm_adr_validate_section_keys`**: Enforce ADR format compliance and valid section names.

## Interfaces for Managing ADRs

### MCP Tool Interface

The `manage_adr` JSON-RPC tool exposed by the MCP server ([`src/mcp/mcp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c)) provides the primary programmatic interface.

**Supported modes**:
- **`get`** (default): Returns the stored ADR content. If none exists, returns `"status":"no_adr"` with a helpful hint.
- **`update`** (or `store`): Writes supplied markdown into the store, returning `"status":"updated"` on success.
- **`sections`**: Parses the stored ADR and returns a JSON array of section keys for UI navigation.

The implementation handles read-write store connections automatically, opening a separate RW handle when the default store is read-only ([`src/mcp/mcp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c), lines 77-88).

### HTTP API Endpoints

The built-in HTTP server ([`src/ui/http_server.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/http_server.c), lines 43-99) exposes RESTful endpoints for language-agnostic access:

- **GET `/api/adr?project=NAME`**: Returns JSON `{ "has_adr": true, "content": "...", "updated_at": "..." }` or `{ "has_adr": false }` via `cbm_store_adr_get`.
- **POST `/api/adr`**: Accepts JSON body `{ "project":"NAME","content":"..." }` and persists the ADR using `cbm_store_adr_store`.

### Graphical UI Integration

The React-based Graph UI surfaces ADR management in **StatsTab.tsx** (line 66), rendering an **ADR button** that opens a modal editor. This frontend consumes the `/api/adr` endpoints, ensuring consistency between manual edits and programmatic updates.

## Working with ADR Sections

Codebase-Memory-MCP recognizes **canonical sections** to enforce consistent documentation structure. The parser ([`src/store/store.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.c), lines 21-53) respects the following canonical keys: `PURPOSE`, `STACK`, `ARCHITECTURE`, `PATTERNS`, `TRADEOFFS`, and `PHILOSOPHY`. Non-canonical sections are ordered alphabetically.

The **sections mode** enables granular updates without rewriting the entire document. When using `mode="sections"`, the system parses existing content, merges the provided section updates, and re-renders the canonical ordering before storage.

## Practical Usage Examples

### Command-Line via MCP Tool

Store a new ADR with canonical sections:

```bash
cbm_mcp manage_adr '{
  "project":"my-app",
  "mode":"update",
  "content":"## PURPOSE\nProvide a cache.\n\n## STACK\nC++\n\n## ARCHITECTURE\nShared memory.\n"

}'

```

Retrieve the current ADR:

```bash
cbm_mcp manage_adr '{"project":"my-app","mode":"get"}'

```

List available section headers:

```bash
cbm_mcp manage_adr '{"project":"my-app","mode":"sections"}'

```

Update only the STACK section:

```bash
cbm_mcp manage_adr '{
  "project":"my-app",
  "mode":"sections",
  "content":"## STACK\nUpdated to use Rust.\n"

}'

```

### HTTP API Access

Fetch an ADR via curl:

```bash
curl -s "http://localhost:8080/api/adr?project=my-app" | jq .

```

Save or replace an ADR:

```bash
curl -X POST -H "Content-Type: application/json" \
  -d '{"project":"my-app","content":"## PURPOSE\nNew cache design.\n"}' \

  http://localhost:8080/api/adr

```

### Programmatic Section Parsing in C

Parse ADR sections for custom tooling:

```c
#include "store.h"

cbm_adr_sections_t secs = cbm_adr_parse_sections(adr_content);
for (int i = 0; i < secs.count; ++i) {
    printf("Section %s:\n%s\n\n", secs.keys[i], secs.values[i]);
}
cbm_adr_sections_free(&secs);

```

This uses `cbm_adr_parse_sections` to respect canonical ordering while extracting structured data.

## Summary

- **Unified Storage**: ADRs live in the SQLite `adr` table within the project_summaries database, ensuring they persist through re-indexing operations ([`src/pipeline/pipeline.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/pipeline/pipeline.c), lines 110-115).
- **Triple Interface**: Manage ADRs via the `manage_adr` MCP tool, `/api/adr` HTTP endpoints, or the React Graph UI.
- **Section-Aware**: Canonical sections (PURPOSE, STACK, ARCHITECTURE, etc.) are enforced by `cbm_adr_parse_sections` and `cbm_adr_render`.
- **Size Limits**: Individual ADRs cannot exceed 8000 bytes (`CBM_ADR_MAX_LENGTH`).
- **Legacy Support**: Automatic migration from [`.codebase-memory/adr.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.codebase-memory/adr.md) to SQLite preserves existing documentation.

## Frequently Asked Questions

### What is the maximum size for an ADR in Codebase-Memory-MCP?

The maximum size is **8000 bytes**, defined by the `CBM_ADR_MAX_LENGTH` constant in [`src/store/store.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.h). Attempts to store content exceeding this limit will be rejected by the validation layer (`cbm_adr_validate_content`).

### How do I update only a specific section of an ADR without rewriting the entire file?

Use the **sections mode** via the MCP tool or API. Pass `mode="sections"` with only the headers you want to update. The system parses the existing ADR, merges your changes, and re-renders the document while preserving canonical ordering.

### Will my ADRs survive if I re-index the project?

Yes. Because ADRs are stored in the SQLite database alongside the code graph, the pipeline ([`src/pipeline/pipeline.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/pipeline/pipeline.c)) preserves them during full re-indexes. The ADR table is separate from the transient index data.

### Can I access ADRs without using the MCP protocol?

Yes. The HTTP server exposed by Codebase-Memory-MCP provides RESTful access via `GET` and `POST` requests to `/api/adr`. This enables integration with shell scripts, CI/CD pipelines, or custom web applications without requiring JSON-RPC clients.