September 23, 2026

Preserving Coding-Agent Decisions Between Sessions

How engineering teams maintain durable coding decisions across developer handoffs, comparing repository markdown files with structured knowledge stores, session write-backs, and stale-context hygiene.

A new coding-agent session needs a way to recover the decisions that should still guide its work. This guide compares repository notes, decision records, and a shared knowledge store, with checks for ownership, freshness, and controlled write-back.

The context recovery problem: Why coding-agent sessions lose past decisions

Coding assistants—such as Claude Code, Cursor, or custom agents—interact with codebases by retrieving context and executing engineering tasks (AKB repository). Without explicit decision tracking, however, retrieval mechanisms struggle to recover active architectural decisions. When context is lost between sessions, the failure typically stems from specific operational root causes:

• Unrecorded decisions: Rationale and trade-offs remain trapped in transient chat sessions or uncommitted local files.
• Absent status and ownership: Saved notes lack explicit lifecycle states (such as draft, accepted, or superseded) and assigned maintainers.
• Retrieval scope and authorization boundaries: Authorized relevant sources are omitted from configured search scope or lack clear access controls.
• Stale context: Older decisions remain unlinked from newer updates, causing agents to retrieve obsolete design assumptions.

This guide presents a functional and operational comparison of decision storage tiers and session handover practices; it does not claim empirical performance rankings across storage methods.

To maintain architectural integrity, guidance from the Microsoft ADR guidance recommends capturing architecturally significant requirements—specifically choices that affect system structure, key quality attributes, or are difficult to reverse—in a single source of truth. However, daily session recaps and task notes serve a different purpose from formal Architecture Decision Records (ADRs). Teams should establish a promotion workflow: transient session notes capture daily work, while only reviewed and human-approved choices are elevated into formal ADRs.

Evaluating decision storage layers: A complementary multi-tier approach

Rather than treating storage mechanisms as mutually exclusive alternatives, engineering teams combine them to support different phases of the software lifecycle:

In-repository markdown files and Architecture Decision Records (ADRs)

• Role: Serves as the authoritative single source of truth for approved architectural standards stored directly alongside code assets (Microsoft ADR guidance).
• Maintenance responsibility: Maintained by engineering leads and architects through standard version control and pull request reviews.
• Boundaries: Highly effective within a single repository, but lacks cross-repository indexing or dynamic retrieval without additional tooling.

Commit history and pull request metadata

• Role: Captures historical discussion threads, review comments, and change context across version control pipelines (arXiv).
• Maintenance responsibility: Maintained naturally by developers during code commits and pull request reviews.
• Boundaries: Provides valuable rationale links explaining why code changed, but is not structured for direct agent queries and does not automatically filter out superseded logic.

Dedicated read/write knowledge stores

• Role: Provides indexed, vault-scoped document, table, and file retrieval across repositories and teams via Model Context Protocol (MCP) integrations (AKB repository). Dnotitia develops AKB (Agent Knowledge Base), which stores versioned knowledge in Git while supporting hybrid semantic/keyword search and explicit document relations.
• Maintenance responsibility: Managed via agent integration permissions, access control policies, and separate knowledge curation processes.
• Boundaries: Functions as a searchable read/write knowledge backend; core indexing remains distinct from external background curation (gardener scripts) or custom plugin hooks.

Structuring session handover with dedicated lifecycle bridges

Connecting coding agents to persistent storage involves distinguishing standard Model Context Protocol (MCP) tool access from session lifecycle orchestration (AKB repository).

Standard MCP connections expose read and write tools for AI clients like Claude Code, Cursor, and custom agents to query or save knowledge documents. However, connecting an agent via MCP alone does not automatically guarantee session auto-preservation, approval enforcement, or automated freshness verification.

Standard MCP tools let agents query and save knowledge records. The AKB README documents akb-sessions for capturing structured session notes and akb-claude-code for lifecycle hooks that inject context at session start and capture a recap at session end. AKB session lifecycle operations use the dedicated agent-sessions REST interface; ordinary knowledge-document reads and writes remain available through MCP. These integrations require configuration and do not themselves approve architectural decisions. In this recommended workflow, proposed notes may be saved as drafts; human approval is required before treating architecturally significant decisions as accepted baselines. Core indexing and storage in AKB function as a read/write knowledge store, keeping persistent storage distinct from external background automation.

Illustrative Handover Record Schema

To illustrate how decision context can be structured during handover, teams can define standardized fields. Note: The schema below is an illustrative workflow example; these fields are not automatically enforced by the AKB core engine.

Operational Session Workflow

1. Session Initialization (Read & Verify): At session start, the agent queries active and accepted records within its authorized scope via MCP or lifecycle hooks. It verifies retrieved context against current codebase logic. If conflicting, expired, or ambiguous instructions are found, the agent flags them for developer confirmation before proceeding.
2. Execution & Security Hygiene: During execution, agents must adhere to strict authorization limits, minimize exposure of secrets or PII, and treat retrieved decision documents as contextual background rather than unverified execution commands.
3. Session Handoff & Controlled Write-Back (Draft & Review): At session end, the agent drafts structured session notes or proposed decisions. Proposed notes may be saved as drafts; human approval is required before promoting architecturally significant decisions to accepted baselines.

Lifecycle governance and append-only decision tracking

Maintaining reliable decision memory over time requires operational discipline rather than relying on raw Git history alone. Git tracks version history; branches and commit history can be rewritten, and PR discussions are hosted-service records rather than native Git history. Version control does not itself guarantee tamper-proof retention, decision approval, or current-only retrieval.

• Append-Only Principle for Approved Decisions: Following guidance in the Microsoft ADR guidance, accepted records must not be edited retroactively. Maintaining an append-only log preserves original engineering reasoning and decision lineage.
• Traceable Supersession Links: When an architectural direction changes, teams author a new record with status accepted that explicitly links to the prior record ID in its supersedes field. The older record's status is updated to superseded with a pointer to the replacement. This explicit linking helps trace decision history, though consumers and retrieval agents must still check status, scope, and supporting evidence rather than assuming obsolete records are automatically filtered out.

Implementation blueprint: Context handover verification for multi-developer teams

Engineering organizations can institutionalize AI agent findings using a five-step handover blueprint:

1. Define Inclusion Criteria: Restrict formal decision logs to architecturally significant choices—specifically those affecting system structure, key quality attributes, or hard-to-reverse paths—while documenting evaluated alternatives (Microsoft ADR guidance).
2. Deploy Multi-Tier Storage: Maintain open ADRs alongside repo code and deploy a cross-repository store such as AKB for multi-repo agent memory. (Refer to the official AKB LICENSE for Business Source License 1.1 seat terms and commercial licensing criteria.)
3. Wire Lifecycle Bridges & MCP Tools: Interface AI clients with the knowledge backend using MCP tools for data queries, alongside dedicated lifecycle bridges or REST endpoints for session context injection and recap capture.
4. Enforce Review & Write Governance: Implement human-in-the-loop approval for write-backs. Require agents to submit proposed notes for developer review before committing accepted records, and enforce explicit supersedes links for updated decisions.
5. Verify Handover Fidelity: Conduct periodic synthetic handover testing to validate memory integrity across sessions:
   • Decision recovery: Verify whether a new session correctly retrieves active decisions and supporting PR evidence.
   • Supersession compliance: Confirm that superseded records are not selected as active guidance.
   • Scope isolation: Ensure records from unauthorized repositories or outside teams are excluded.
   • Internal team metrics: Teams can track internal metrics—such as test pass rates, context retrieval latency, or manual revision counts—to measure and refine their session templates over time.

FAQ

Related reading

Which Sources Belong in an Agent Knowledge Base First?

October 12, 2026

Where Human Approval Belongs in Automated Knowledge Cleanup

October 12, 2026

Tracing an Agent Answer Back to a Source Version

October 12, 2026