[FEATURE] Transition from Single decisions-log.md to ADR-style Index + Individual Records

[Claudio-Osorio]

TLDR: Using ADR files (reading index only) instead of decisions-log.md to improve efficiency and reduce noise.

The current implementation of project memory relies on a single, append-only file located at .opencode/context/project/decisions-log.md. While simple to implement, this approach may present significant scaling issues for AI agents and collaborative development.

The Problem
Context Window Bloat: As a project matures (e.g., reaching 100+ decisions), the log consumes an increasing number of tokens. Forcing the agent to read the entire log to understand one specific decision is inefficient and costly.

"Lost in the Middle" Bias: Large language models often lose focus on information buried in the middle of long documents. A single massive log decreases the agent’s ability to accurately retrieve specific architectural constraints.

Template Corruption: There is a risk of agents overwriting the structural boilerplate of the single file during long-form append operations.

The Proposal: ADR Index + Granular Files
Shift to an Architectural Decision Record (ADR) pattern similar to standard industry practices (e.g., ), optimized for RAG (Retrieval-Augmented Generation).

Proposed Structure:
.opencode/context/project/decisions-index.md: A lightweight "Registry" containing a table or list of decision titles, dates, and tags (e.g., #auth, #database, #ui).

.opencode/context/project/adr/NNNN-name.md: Individual, numbered files for each decision.

Benefits for AI Agents:
Efficiency: Agents can scan the small decisions-index.md to identify which specific ADR file is relevant to their current task, loading only that file into memory.

Precision: By isolating decisions, the agent receives a higher "signal-to-noise" ratio, leading to more accurate code generation that respects project constraints.

Immutability: Once an ADR is written, it is rarely changed unless superseded by a new file, protecting the integrity of the project's "long-term memory."

[darrenhinde]

This idea is simple but has a lot of positives.

We are at a turning point where making a system to make all of this more manageable and configurable is needed.

We will need to make sure the user doesn’t need to remember to maintain this and other context files and might be alerted when things are out of date or growing.

The system is already quite hard for most to manage and need to start planning how we make it easier for users to know the state of their project or global states etc.

Are there any good policies you have for maintaining such file?

One issue could look like:
‘’’
ADR #7: "Use JWT for auth"
ADR #12: "Use session cookies for auth"
Both marked Accepted = SILENT CONFLICT ❌

Agents get confused. Users see contradictions.
Nothing tells them which to follow.
‘’’

So need to have a systematic way to update and keep relevance to keep file size compact n relevant.

[Claudio-Osorio]

So far, I have seen a few approaches: ADR vs Living Docs vs Decision Registry. They all have pros and cons. I believe ADR fits this project the best.

AI is much better at explaining this than I could ever be but, my experience with ADR has been great. The agent catches itself before making critical mistakes that cost a lot of tokens/prompts.

My setup (used in Antigravity) consists of 3 main components:

1. ADR Template
2. ADR Master Index
3. ADR Instructions

The first time the project is scanned the ADR can be generated. This process can be as thorough as needed.
If the 3 components are robust and the ADR are precise small decisions taken given a specific context, many of the issues could be prevented.
Additionally, if a new ADR contradicts an existing one, the output must include TWO file operations: 1. Create the new ADR. 2. Append a 'Deprecated By [New ID]' status to the header of the old ADR. This takes less effort while being straightforward.

The template should carefully point out the tech stack and problem in question. If it's "Auth" then "Auth" becomes one of the tags and is also present on the Index file. Before any new ADR is created, a robust check will be performed to make sure there is no ambiguity or contradiction with any of the other ADR given the context.

Simple example of an Index.
| 011 | NextAuth Hybrid Authentication | frontend, auth, social, nextauth, jwt |
| 012 | API URL Trailing Slash Convention | api, conventions, routing, django-ninja |
| 013 | Backend Session Gating | frontend, auth, race-condition, context |
| 014 | Image Optimization & Standardization | backend, images, performance, privacy, webp |