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

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 and implemented in 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.
• Migration path: The system performs a one-time migration from the legacy file /.codebase-memory/adr.md into the SQLite store (implemented in 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 and implemented in 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) 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, lines 77-88).

HTTP API Endpoints

The built-in HTTP server (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, 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:

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:

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

List available section headers:

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

Update only the STACK section:

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

}'

HTTP API Access

Fetch an ADR via curl:

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

Save or replace an ADR:

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:

#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, 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 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. 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) 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}