DEV Community: Naman Jain

CLAUDE.md vs agent memory: what each should store

Naman Jain — Sat, 19 Sep 2026 12:54:45 +0000

Originally published at getlockstep.dev.

A team adds another paragraph to CLAUDE.md every time Claude Code makes a mistake.

Six weeks later, the file contains build commands, style rules, a product exception, three temporary migration notes, an old API decision, and a warning that contradicts a newer warning lower down.

Claude has more memory and less clarity.

CLAUDE.md and agent memory are both useful, but they should not store the same things. The simplest way to choose is to ask who needs the information, how long it stays true, and what happens when it changes.

The short answer

Use four separate homes:

Information	Best home	Why
Stable project instructions	CLAUDE.md	Intentional, reviewable, version-controlled guidance
Personal recurring patterns	Auto memory	Useful continuity for one person's Claude sessions
Current task state	Handoff or task note	Temporary, specific, easy to replace
Team decisions	Shared approved record	Needs owner, status, scope, and replacement history

One file can technically hold all four. It usually should not.

What belongs in CLAUDE.md

Claude Code's documentation describes CLAUDE.md as persistent project guidance. Use it for instructions that are both important and durable.

Good entries include:

the command to run tests for this repository;
which package manager the team uses;
the boundary between two services;
where migrations live;
naming or formatting conventions not enforced automatically;
a hard rule such as never logging raw tokens;
a durable architecture invariant that affects most work.

A useful CLAUDE.md sentence tells Claude what to do repeatedly. It should still be correct when a different engineer opens the repository next month.

Keep the file close to the code it governs. If instructions apply only to one package or directory, scope them instead of loading them into every task.

What belongs in agent memory

Auto memory is best for personal, recurring working knowledge that helps Claude collaborate with one user across sessions.

Examples:

you prefer small commits;
you want test output summarized in a particular format;
a local environment has a recurring setup detail;
you routinely ask for a plan before edits;
a harmless tool preference repeats across projects.

This is working continuity, not company policy. A teammate should not inherit your personal preferences as if the team approved them.

Do not use personal memory as the only home for a rule that controls production behavior, customer data, or architecture. Nobody else can reliably review or receive it.

What belongs in a task handoff

A handoff carries temporary execution state:

current objective;
files changed;
evidence gathered;
tests run;
blockers;
unresolved decisions;
next step.

It should make a new session productive without replaying the full transcript. When the task ends, much of it can disappear.

If one item must shape future work, promote it to the right durable home. A new test command may enter CLAUDE.md. An approved product exception may enter the team's decision record.

What should not be buried in CLAUDE.md

Temporary plans

"For this week's migration, route new users through v2" will go stale. Keep it with the task and give it an expiry condition.

Unresolved ideas

A proposed architecture is not an instruction. Label it as proposed and ask the owner before an agent treats it as binding.

Long explanations of every past discussion

Claude needs the verdict and the reason relevant to its task, not every message that preceded them.

Customer or product exceptions with no owner

A sentence such as "enterprise accounts keep legacy access" is dangerous without scope, reason, owner, and status. When the exception ends, who removes the line?

Secrets

Never place credentials, tokens, or private customer data in a repository instruction file.

Where architecture and product decisions belong

Some architecture decisions are stable enough to appear as a short invariant in CLAUDE.md. The full record still needs more:

what the team chose;
why it chose it;
what it rejected;
who owns the call;
what code or behavior it affects;
whether it is active or superseded.

Product decisions matter too. A pricing promise or onboarding rule may constrain several services even though it is not an architecture decision. Product, engineering, support, and coding agents should be able to trace the same current answer.

This is why decision-log tools for product and engineering teams and ADRs complement repository instructions rather than compete with them.

A practical CLAUDE.md structure

A focused file might contain:

# Repository guide

## Commands
- Install: `pnpm install`
- Test affected packages: `pnpm test --filter ...`

## Boundaries
- Billing owns payment state transitions.
- Identity may read account status but must not write billing state.

## Hard invariants
- Never log raw credentials or payment details.
- Any change to guest-checkout ordering must check active checkout decisions.

## Context sources
- Use the issue tracker for current task scope.
- Query the shared decision source before changing checkout or pricing behavior.

This tells Claude how to work and where to find changing truth. It does not pretend the file itself can contain every current decision.

A maintenance test

Review each instruction with four questions:

Does this apply to many future tasks?
Would another teammate agree it is a team instruction?
Is it still current?
Is CLAUDE.md the smallest correct home for it?

If the answer to the first two is no, move it to personal memory or the task handoff. If the answer to the third can change with a product or architecture call, put the full decision in a record with status and an owner.

The same model applies beyond Claude Code. Cursor rules, MCP servers, repository files, and shared decision records each solve a different context job.

Where Lockstep fits

Lockstep is the shared decision layer. It captures possible decisions from Slack, docs, tickets, and code discussions, asks the owner to confirm them, and keeps the approved version tied to what it affects. Claude Code and other MCP-compatible agents can retrieve the relevant active decisions before they work.

It does not replace CLAUDE.md or auto memory. CLAUDE.md tells Claude how this repository works. Auto memory helps one user continue recurring patterns. Lockstep carries the product and architecture calls the whole team must keep consistent.

For cross-tool teams, see how to share memory between Cursor and Claude Code. For live context sources, compare MCP servers for engineering teams.

The best context setup is not the one that remembers the most.

It is the one that gives each kind of information a clear owner, scope, and place to change.

Best MCP memory servers for teams using AI coding agents

Naman Jain — Sat, 19 Sep 2026 12:53:49 +0000

Originally published at getlockstep.dev.

Your team connects a memory server to Claude Code and Cursor. The agents can now save and search notes across sessions.

A week later, one agent remembers that the payments service uses idempotency keys. Another retrieves an old note saying retries are unsafe. A third finds both, cannot tell which is current, and asks the team again.

The memory server worked. It stored and retrieved text. The team still has a decision problem.

That distinction matters when you compare MCP memory servers. Some are good at personal recall. Some build a graph of people, systems, and facts. Some make Markdown notes available to every coding agent. None automatically turns every remembered sentence into a current, approved team decision.

The short answer

Best for	Pick	Why
Small local experiments	MCP reference Memory server	Minimal knowledge graph, easy to inspect, no extra platform
Shared human and agent notes	Basic Memory	Plain Markdown, links, search, local or shared cloud workspace
Hosted semantic recall across clients	Mem0 MCP	Managed HTTPS service with add, search, update, delete, and event tools
Facts and relationships that change over time	Graphiti MCP	Temporal graph with entity, relationship, and hybrid search
Approved product and architecture decisions	A decision system exposed through MCP	Ownership, status, rationale, rejected options, and review are the missing layer

There is no useful universal winner. The right choice depends on whether your team needs a notebook, a search layer, a changing knowledge graph, or a decision record.

What to test before choosing an MCP memory server

Do not start with the longest feature list. Test five things against a real handoff between agents:

Write path: Can Cursor and Claude Code save context without custom glue?
Retrieval: Does a fresh session get the right memory from a plain question?
Scope: Can personal preferences stay separate from team facts and project context?
Change: When a fact changes, can the system show or remove the stale version?
Control: Can a human tell which memory is current, who accepted it, and why?

The fifth test is where general memory products often stop. That is fine if you are storing preferences or research notes. It is risky if the memory changes what a team builds.

1. MCP reference Memory server: best for a small local graph

The official reference server stores entities, directed relations, and observations in a local knowledge graph. Its MCP tools create and delete entities or relations, add observations, read the full graph, and search nodes. The graph is also exposed as an MCP resource, so compatible clients can receive updates.

That makes it a good starting point when you want to understand the mechanics without adopting a larger system. A team can represent a service, an owner, a dependency, and a few known facts. The JSONL storage is easy to move or inspect.

The tradeoff is in the word reference. It is deliberately basic. It does not give a team a rich review workflow, semantic ranking, permissions model, or a human-friendly workspace. Its sample prompt is also framed around remembering user information, not governing shared engineering knowledge.

Pick it when: one person or a small team wants a transparent local proof of concept.

Skip it when: several teams need shared access, review, lifecycle, or strong search over a large corpus.

Source: MCP Knowledge Graph Memory Server

2. Basic Memory: best for notes humans and agents both edit

Basic Memory keeps knowledge in plain Markdown and builds a traversable graph from notes and links. Its MCP tools cover writing, search, recent activity, directory browsing, and context building. It can run locally, and its cloud workspace is designed to let teammates and their AI assistants share the same knowledge base.

That shape works well for runbooks, research, system maps, handoff notes, and durable explanations. A person can edit the same source in a normal file or note app instead of treating memory as an invisible database. Export risk is low because the source remains Markdown.

The main judgment is discipline. A shared notebook can hold two conflicting notes as easily as one correct note. Search and links help an agent find information, but they do not decide which sentence is binding. Teams still need conventions for owners, current status, review dates, and superseded notes.

Pick it when: humans need to read and edit the same knowledge that agents retrieve.

Skip it when: you want memory to be fully managed or need a temporal graph that reasons explicitly about changing facts.

Source: Basic Memory repository and documentation

3. Mem0 MCP: best for managed semantic recall across coding clients

Mem0's hosted MCP server connects over HTTPS and supports Claude Code, Cursor, Codex, Windsurf, VS Code, and other MCP clients. Its tools add and search memories, retrieve or update one memory, delete memories and entities, and inspect memory operation events.

That makes Mem0 attractive when a team wants semantic recall without operating a graph database. Client setup is documented, and a real round-trip test makes it easy to check whether one client can save a memory and another can retrieve it.

The tradeoff is control and meaning. A hosted service is another place for company context to live, so security and retention need review. Semantic similarity also does not tell an agent that a result was approved, superseded, or limited to one release. Metadata can help, but the team has to define and enforce it.

Pick it when: managed hosting and cross-client semantic search matter more than file-based ownership.

Skip it when: policy requires local storage, or the primary need is decision status rather than recall.

Source: Mem0 MCP documentation

4. Graphiti MCP: best for facts that change over time

Graphiti is built around a temporal knowledge graph. Its MCP server can add episodes, extract entities and relationships, and search facts or node summaries with semantic and hybrid search. It supports graph backends including FalkorDB and Neo4j, with HTTP and stdio routes for MCP clients.

The temporal model is the differentiator. If service ownership, dependencies, customer state, or operating facts change, a time-aware graph is better suited than a bag of similar text chunks. It can preserve how a fact evolved instead of overwriting every previous statement.

That power adds operational weight. Teams must run the graph stack, configure model providers, decide entity types, and monitor extraction quality. Graphiti's MCP server is also described as experimental in its own repository. It is a stronger fit for teams already sure that temporal graph retrieval solves a real problem.

Pick it when: relationships change often and queries need to understand what was true when.

Skip it when: your main need is a lightweight shared notebook or a first memory experiment.

Source: Graphiti MCP server documentation

A memory server is not automatically a team memory

A tool can retrieve the sentence "we use PostgreSQL advisory locks" and still leave four questions unanswered:

Was that an idea or an accepted decision?
Which system and release does it apply to?
What constraint made the team choose it?
Has a later decision replaced it?

This is why teams can add more agent memory and still keep re-explaining the same architecture. General memory improves recall. It does not, by itself, establish authority.

If your symptom is broader context loss, see the best tools for AI coding agent context. If you are evaluating the protocol layer, compare the best MCP servers for engineering teams. If agents are reopening settled choices, the more relevant comparison is decision log tools for product and engineering.

How to choose without creating another abandoned system

Run one two-agent test before rollout:

Ask Cursor to save the reason for a real architecture choice.
Start a fresh Claude Code session with no copied chat history.
Ask what the current choice is, why it exists, and what was rejected.
Change the decision through the team's normal approval path.
Ask both agents again.

A usable system should return the current answer, preserve the reasoning, identify the owner or source, and avoid presenting the old answer as equally valid. If it only finds both notes, it solved storage and search, not the team handoff.

Where Lockstep fits

Lockstep is for the narrower problem generic memory does not settle: decisions that the whole team and its agents must follow.

It keeps the accepted choice with its rationale, rejected options, owner, and status, then makes that decision available to agents through MCP. Cursor, Claude Code, and the people reviewing their work can use the same current record instead of treating every retrieved note as equally authoritative.

That does not replace all memory. A team may still use Basic Memory for shared notes, Mem0 for recall, or Graphiti for changing relationships. Lockstep is the decision layer alongside them - the place that answers not only "what do we remember?" but "what did we agree to build?"

How to share memory between Cursor and Claude Code

Naman Jain — Sat, 19 Sep 2026 12:53:05 +0000

Originally published at getlockstep.dev.

You prototype a change in Cursor, then move to Claude Code to finish it.

The branch moves with you. The uncommitted diff moves with you. The reasoning does not.

Claude can inspect what changed, but it cannot see why Cursor rejected the first approach, which test still fails, or which product decision limits the fix. You spend ten minutes rebuilding the brief. If you miss one detail, the second agent may "fix" something the first agent already learned not to touch.

Cursor and Claude Code do not need identical memories. They need a shared handoff and the same active team constraints.

Native memory is not the bridge

Cursor has project rules and its own ways to retain useful context. Claude Code reads CLAUDE.md files and can keep auto memory for recurring personal patterns. Those systems improve continuity inside each tool.

They are not one shared database. A fact one tool learned about your workflow does not automatically become available to the other. A teammate's personal memory may be different again.

Trying to mirror every native memory creates a sync problem and a privacy problem. Personal preferences, temporary observations, and abandoned ideas get mixed with rules the whole team must follow.

The bridge should be smaller and vendor-neutral.

Share four layers, not one giant context file

Stable repository instructions

Put commands, directory boundaries, coding conventions, and hard invariants in a version-controlled file that both tools can read.

AGENTS.md is the simplest neutral baseline. Cursor can also use scoped project rules in .cursor/rules, while Claude Code can use CLAUDE.md. Avoid maintaining the same paragraph manually in three places. Keep shared constants in one source and reserve tool-specific files for tool-specific behavior.

Cursor's documentation explains that project rules are version-controlled and can apply always, by file pattern, by relevance, or manually. Claude Code's documentation similarly treats CLAUDE.md as persistent project guidance. Both are strongest when the instructions are short and stable.

For the broader tool landscape, see the best ways to give AI coding agents your team's context.

Current task handoff

When work moves from Cursor to Claude Code, create a compact handoff:

requested outcome;
branch and files changed;
approaches tried and rejected;
tests run and exact failures;
unresolved questions;
next safe step.

This is working state, not permanent memory. It should help the second agent continue the task without replaying the first conversation.

Live reference data

Issues, production errors, current documentation, and customer records change. Do not copy them into a memory file and assume they stay true. Let the agent query the current source through a focused integration or MCP server.

Our guide to MCP servers for engineering teams compares the common live-context sources and their access models.

Approved team decisions

The most important shared layer is not a transcript. It is the set of product and architecture calls that both agents must honor:

verdict;
reason;
owner;
status;
affected code or behavior;
rejected option;
replacement when the answer changes.

A task handoff may mention one of these decisions, but the decision should live beyond the task. That is what stops the next tool, teammate, or agent from reopening it.

A Cursor-to-Claude Code handoff example

A useful handoff might say:

Goal: move guest checkout analytics to the server. Cursor changed checkout/events.ts and added two tests. The client-only approach was rejected because retries produced duplicate events. One test still fails when payment confirmation arrives asynchronously. Active decision: guest checkout identity is created before payment until migration M-42 ends; Priya owns exceptions. Next step: inspect the server idempotency key before changing the event order.

This gives Claude Code enough to continue. It does not paste 40 pages of chat or ask the model to infer which paragraph matters.

The active decision should also exist in the shared team record, tied to the checkout paths. If the migration ends or Priya changes the call, the record can be superseded without rewriting old handoffs.

Do not sync these things blindly

Full chat histories

A transcript contains exploration, wrong turns, pasted secrets, and statements that were later corrected. More text does not mean clearer authority.

Auto memory from one person's account

Personal memory can include preferences that should not govern another teammate's work. Promote only the stable, team-approved parts.

Generated summaries with no review

A summary can drop the exact exception that made a decision safe. Treat it as a draft handoff. Verify the load-bearing constraints.

Stale copies of live systems

A copied ticket or API document becomes wrong quietly. Link or query the current source instead.

A setup both tools can use today

Create one neutral repo guide. Keep commands, boundaries, and invariants in AGENTS.md or a shared source referenced by both tool-specific files.
Use a handoff template. Make every tool switch carry outcome, current state, evidence, open questions, and next step.
Connect focused live sources. Give agents access only to the issue tracker, docs, or errors the task needs.
Keep decisions outside personal chat history. Record approved calls with owners, status, and scope.
Brief before editing. Have Cursor or Claude retrieve the decisions connected to the files it will change.
Stop on disagreement. A new prompt should not silently override an existing team decision; route the conflict to its owner.

This is also the answer when Cursor loses context mid-project: separate information by job instead of building one ever-growing memory file.

Where Lockstep fits

Lockstep keeps the shared decision layer. It captures possible decisions from Slack, docs, tickets, and code discussions, asks the owner to confirm them, and ties the approved version to what it affects. Cursor, Claude Code, and other MCP-compatible agents can query the same current decisions before they act.

It does not replace Cursor rules, CLAUDE.md, AGENTS.md, or a task handoff. Those carry repository instructions and current execution state. Lockstep carries the team calls that must remain true across tools and sessions.

If your team already has a decision log, compare the available options and their tradeoffs. The useful question is not where the note sits. It is whether both agents receive the active answer before they change the code.

The goal is not perfect memory sync.

It is a handoff that preserves the work, and a shared decision record that preserves the why.

ADRs for AI coding agents: how to make every agent read architecture decisions

Naman Jain — Sat, 19 Sep 2026 12:52:48 +0000

Originally published at getlockstep.dev.

An AI coding agent opens the billing service and finds a synchronous call followed by a queue publish.

The direct call looks redundant. The agent proposes deleting it and relying on the queue. The refactor is smaller, the tests pass, and the code looks cleaner.

Six months earlier, the team made the direct call intentional. One enterprise customer needs an immediate confirmation, while the queue supports downstream work. That choice is written in docs/adr/0017-immediate-billing-confirmation.md.

The ADR exists. The agent never reads it.

This is the gap teams hit after they start writing architecture decision records. A record in the repository is available to an agent, but availability is not the same as context. The agent needs a predictable place to look, a rule that tells it when to look, and a current status it can trust.

The short answer

Use this structure:

repo/
  AGENTS.md
  CLAUDE.md
  .cursor/
    rules/
      architecture-decisions.mdc
  docs/
    adr/
      README.md
      0017-immediate-billing-confirmation.md
      0018-retry-policy.md

Each ADR should hold one significant decision with:

title
status: proposed, accepted, deprecated, or superseded
context and constraints
the decision in active language
consequences and tradeoffs
owner and decision date
links to a replacement when superseded

Then keep the agent rule short:

Before changing service boundaries, persistence, messaging, authentication,
or public API behavior, search `docs/adr/` for relevant accepted decisions.
Read the full matching ADR and any ADR that supersedes it.
If the proposed change conflicts with an accepted ADR, stop and name the
conflict instead of silently rewriting the architecture.

That is enough to create the retrieval habit without loading every ADR into every conversation.

Why ADRs fit AI coding agents

Michael Nygard's original ADR format was designed as a short conversation with a future team member. It separates the forces around a choice from the choice itself and its consequences. A decision stays in the log when it is reversed, but its status changes to superseded and points to the replacement.

That structure is unusually useful for agents. Code shows what the system does now. An ADR can explain:

which constraint shaped the design
which alternatives were considered
which option the team accepted
what downside the team knowingly took on
whether the choice is still current

Without those fields, an agent may treat an intentional compromise as an accident. With them, the agent can compare a proposed edit against the reason the code exists.

Sources: Documenting Architecture Decisions and ADR guidance

Step 1: give every ADR a stable shape

Do not make the agent infer status from prose. Put it near the top.

# ADR 0017: Immediate confirmation before billing events

- Status: Accepted
- Owners: Payments team
- Decided: 2026-02-12
- Scope: services/billing, packages/payments
- Replaces: ADR 0009

## Context

One enterprise flow must receive confirmation inside the request window.
The event queue may be delayed and cannot satisfy that contract.

## Decision

We will keep the synchronous confirmation call. We will publish the billing
 event after confirmation for downstream work.

## Consequences

Requests depend on the confirmation service. The queue cannot become the only
path without changing the enterprise contract.

## Rejected options

- Queue-only confirmation: rejected because delivery time is not bounded.
- Polling: rejected because it increases client complexity and load.

The exact template matters less than consistency. One record should describe one significant choice. Keep it short enough that a person and an agent can read the full record before changing code.

Step 2: keep old ADRs, but make replacement explicit

Deleting or rewriting an old ADR destroys useful history. Leaving it unchanged creates a different failure: search may return the old and new decisions as if both are current.

Use a visible status and reciprocal links:

- Status: Superseded by [ADR 0024](./0024-event-driven-confirmation.md)

The new ADR should say what it replaces. This gives agents a deterministic path from an old search result to the current decision.

adr-tools supports this workflow directly: creating a superseding ADR marks the old one as superseded and links the replacement. You do not need the tool, but you do need the behavior.

Source: adr-tools

Step 3: index the decision log for fast scanning

A large repository may have hundreds of records. Give humans and agents a small index in docs/adr/README.md:

| ADR | Status | Area | Decision |
|---|---|---|---|
| 0017 | Accepted | Billing | Keep synchronous confirmation |
| 0018 | Accepted | Billing | Retry only idempotent operations |
| 0024 | Proposed | Billing | Move confirmation to bounded stream |

The index is a search aid, not the source of truth. The agent still reads the full matching ADR and checks replacement links. Regenerate the index in CI if manual upkeep becomes unreliable.

Step 4: point Claude Code to ADRs without bloating CLAUDE.md

Claude Code reads project CLAUDE.md files at the start of a session. Its current guidance recommends keeping instructions concrete and concise, targeting fewer than 200 lines because larger files consume more context and reduce adherence.

Do not paste your decision history into CLAUDE.md. Add a durable retrieval rule:

## Architecture decisions

Accepted architecture decisions live in `docs/adr/`.
Before changing boundaries, storage, messaging, security, or public APIs:
1. search `docs/adr/README.md` and `docs/adr/` for the affected area;
2. read matching ADRs and their replacement links;
3. name any conflict with an accepted ADR in the plan.

For a monorepo, use path-scoped files in .claude/rules/ so billing decisions load for billing work and frontend decisions load for frontend work. Claude Code also supports importing an AGENTS.md file from CLAUDE.md, which avoids duplicating the common instruction across tools.

Source: Claude Code project memory and CLAUDE.md

Step 5: make Cursor apply the same retrieval rule

Cursor project rules live in .cursor/rules as version-controlled .mdc files. They can be scoped by file patterns or included based on relevance. Cursor recommends focused, actionable rules and explicitly suggests referencing files instead of copying their contents so rules stay short and do not go stale.

A path-scoped rule can look like this:

---
description: Read accepted billing ADRs before changing billing architecture
globs: services/billing/**,packages/payments/**
alwaysApply: false
---

Before planning architecture changes, read `docs/adr/README.md` and matching
records in `docs/adr/`. Follow accepted decisions. If a change conflicts with
one, name the ADR and ask for a new decision rather than ignoring it.

For simple cross-agent instructions, Cursor also reads a root AGENTS.md. Use it as the common pointer, then keep client-specific mechanics in the client-specific rule file.

Source: Cursor Rules documentation

Step 6: separate accepted decisions from proposed ideas

An agent should be allowed to suggest a better design. It should not silently treat its suggestion as the new architecture.

Use a clear flow:

The agent finds the current accepted ADR.
It names the conflict and proposes a replacement.
A human owner reviews the new decision.
The new ADR moves from proposed to accepted.
The previous ADR becomes superseded.
Every agent retrieves the new current record.

This preserves agent initiative without letting the latest generated plan outrank the team's decision.

Step 7: test with a fresh agent, not the session that wrote the ADR

The authoring session already knows the answer. It is a weak test.

Open a new Cursor or Claude Code session and ask:

Why is the synchronous billing confirmation still here?
Which ADR governs retry behavior in services/billing?
Is queue-only confirmation accepted, proposed, or rejected?
What would need a new ADR before this refactor can proceed?

A passing setup returns the current decision, rationale, and status. It follows supersession links. It does not quote an old ADR as current or pretend the instruction file is a hard security control.

Claude's own documentation makes the last point clear: CLAUDE.md shapes behavior but is not guaranteed enforcement. Cursor gives a similar warning that AI guidance should not be the only security control. Use tests, permissions, and policy checks for hard boundaries.

Common mistakes

Loading the full ADR directory into every prompt

This burns context and makes unrelated decisions compete for attention. Load a short index and retrieve the matching records.

Recording only the final choice

"Use Kafka" does not tell a future agent which constraint mattered. Include the forces, rejected options, and consequences.

Mixing proposals with accepted decisions

If both are plain Markdown with no status, search cannot establish authority. Status is part of the data, not decoration.

Updating old ADR text in place

This makes historical links lie and hides why the system changed. Supersede the old record and connect the two.

Assuming a repository file reaches every tool

Claude Code, Cursor, Codex, and other agents load instructions differently. Keep one common record, then add a tested pointer in each client's supported instruction path.

Connect ADRs to the rest of your agent context

ADRs solve one part of the context problem. Stable commands and conventions still belong in project instructions. Temporary work state belongs in a task handoff. Personal preferences belong in personal memory.

For the broader stack, compare the best tools for AI coding agent context, the best MCP servers for engineering teams, and decision log tools for product and engineering.

If teams use both Cursor and Claude Code, the companion guide on sharing memory between Cursor and Claude Code shows where the common pointer and handoff files fit.

Where Lockstep fits

Repository ADRs work well when one codebase and one review flow define the decision boundary. The harder case starts when product, engineering, and several agents must use the same decision across repositories and tools.

Lockstep keeps accepted decisions, rationale, rejected options, owner, and status in one shared record, then makes the current decision available through MCP. The ADR can stay close to code while Lockstep carries the team-level choice to Cursor, Claude Code, and the people reviewing their work.

The goal is simple: a new agent should not merely find architecture documents. It should know which decision is current, why the team made it, and when to stop before changing it.

Cursor keeps losing context mid-project. How to stop re-explaining your codebase

Naman Jain — Sat, 19 Sep 2026 12:52:07 +0000

Originally published at getlockstep.dev.

You spend ten minutes bringing Cursor back up to speed.

The current branch is easy. The missing part is everything around it: why the team kept a duplicated service, which API behavior a customer depends on, why an apparently simpler helper failed last month, and what product agreed to defer.

The agent reads the repository, proposes a clean plan, and unknowingly reopens three decisions the team already made.

This is what Cursor context loss costs. Not only repeated prompting, but repeated decisions.

First, separate the kinds of context

Teams often try to fix the problem by putting more information into one file. That works briefly, then the file becomes another source the agent must interpret.

A better setup separates four jobs.

1. Repository context

This is the stable map of the codebase:

how to run and test it;
important directories and boundaries;
coding conventions;
security and data-handling rules;
hard technical invariants.

Keep this version-controlled and concise. Cursor rules, AGENTS.md, or another repository instruction file can carry it.

2. Task context

This is what the current run needs:

the requested outcome;
the files already changed;
tests run and results;
open questions;
the next safe step.

A short handoff or session summary works well here. Delete or archive it when the task ends.

3. Reference context

This includes live docs, tickets, errors, APIs, and customer facts the agent may need to query. MCP servers or focused retrieval can bring this in only when relevant.

See the best MCP servers for engineering teams for the common options and their access tradeoffs.

4. Decision context

This is the part teams most often miss:

what the team chose;
why it chose it;
which alternative failed;
who owns the call;
what code or product behavior it affects;
whether it is still active.

Decision context must outlive a session, but it should not be mixed into a giant memory dump.

Why a new chat feels like starting over

Cursor can inspect the repository again. It cannot infer every reason behind the repository's current shape.

Suppose the billing code retries one payment state but not another. The asymmetry may look accidental. In reality, finance rejected the second retry after it created duplicate reconciliation work, and product accepted the rougher customer experience until a provider migration.

The code shows the result. It does not show the tradeoff, owner, or expiry condition.

When the original chat disappears from active context, the agent reconstructs the reason from code. That reconstruction can be coherent and wrong.

The same thing happens when work moves between people or between Cursor and Claude Code. Personal chat history does not travel with the repository.

A practical context-loss workflow

Keep rules short and stable

A rule should remain true across many tasks. Good examples include required test commands, a directory ownership boundary, or "never log raw access tokens."

Avoid putting temporary plans or unresolved product calls in a global rule file. If the answer changes next week, the stale rule will look more authoritative than the new conversation.

Our comparison of tools for giving coding agents team context shows where rules, native memory, MCP, and shared decision records each fit.

End each task with a handoff

Before a long session ends, write a short handoff with:

objective;
current state;
completed changes;
evidence and tests;
unresolved questions;
next step.

This saves the next session from replaying the entire chat. It also makes uncertainty visible instead of letting the agent fill gaps.

Promote lasting decisions out of the handoff

A handoff is temporary. If it contains a call that future work must honor, promote that call into a durable decision record.

For example:

Keep guest checkout account creation before payment until the payment-provider migration ends. Owner: Priya. Applies to checkout and identity services. Replaces the January rule. Reason: asynchronous confirmation and recovery behavior in India.

That is small enough to retrieve and clear enough to act on.

Load only relevant decisions

Do not paste the whole company history into every prompt. Connect decisions to repositories, paths, APIs, capabilities, or projects. Then retrieve only the active records that match the task.

This protects the context window and reduces stale collisions.

Stop on conflicts

If a new request says "move account creation after payment" while an active decision says the opposite, the agent should not pick whichever text appeared most recently. It should show the conflict and ask the named owner.

That behavior is the difference between remembering information and respecting a team decision.

Moving between Cursor and Claude Code

Cross-tool continuity works best when the shared parts are vendor-neutral.

Use:

repository files for stable instructions;
a task handoff for work in progress;
MCP or direct integrations for live reference data;
shared decision records for approved product and architecture calls.

Do not depend on a memory feature that only one person's Cursor account can read. The other tool will still start cold.

The same rule applies to parallel agents. If each one has a different slice of history, they can produce changes that are individually sound but collectively inconsistent. Shared memory for multiple agents is primarily a decision problem, not a transcript-sync problem.

Where Lockstep fits

Lockstep captures possible decisions from Slack, docs, tickets, and code discussions, asks the owner to confirm the call, and keeps the approved version tied to what it affects. Cursor, Claude Code, and other MCP-compatible agents can read the same active decisions before they work.

It does not replace Cursor rules or task summaries. Those carry stable repo instructions and temporary execution state. Lockstep carries the team calls that must remain consistent across sessions, tools, and people.

For teams choosing the human-facing system behind those calls, compare decision-log tools for product and engineering.

The goal is not to make Cursor remember everything.

It is to make sure the next session does not unknowingly reverse something your team already decided.

Why Claude Code forgets architecture decisions - and how teams stop re-explaining them

Naman Jain — Sat, 19 Sep 2026 12:52:06 +0000

Originally published at getlockstep.dev.

Claude Code opens a mature service and finds two ways to create a customer account.

One path creates the account before payment. The other waits until payment succeeds. The second path looks cleaner, so the agent proposes making both flows consistent.

The code is not missing. The tests are not missing. What is missing is the decision from six weeks ago: guest checkout must create the account first because a payment provider returns asynchronously in one market, and the team already rejected the cleaner design after it broke recovery.

Someone explains this. Claude fixes the plan. Three sessions later, the same suggestion returns.

This is the failure people describe as "Claude Code forgot our architecture." More precisely, Claude can still read the architecture. It has lost the reasoning that tells it which parts are intentional.

Claude Code remembers code better than reasons

A repository is a strong record of what the system is now. It contains interfaces, tests, comments, dependencies, and patterns that an agent can inspect.

But architecture is more than the current shape of the files. It includes decisions such as:

why one boundary sits in the API instead of the client;
which edge case made the obvious abstraction unsafe;
why the team accepted duplication for now;
which product promise constrains a technical change;
who can approve an exception;
whether an older rule is still active.

Those facts often live in Slack, a planning call, a ticket, a pull request, or one person's memory. A coding session sees only a slice of them.

Anthropic describes context as a finite resource that agents must manage deliberately. Compaction, retrieval, and tools can keep a long task moving, but none can recover a decision that was never stored in a form the next session can identify as current and authoritative. That is why context engineering matters, but it does not remove the need to decide what deserves to survive.

The symptom shows up after the first good session

The first session often feels excellent. The team explains the codebase, the customer constraint, and the plan. Claude works inside that rich context and produces a sound change.

Trouble appears later:

A new session starts with the repository but not the conversation.
An old session is compacted into a shorter summary.
Another engineer opens the same repo with a different personal setup.
The team switches between Claude Code, Cursor, and another agent.
Two agents work in parallel from different slices of the brief.

Each agent can make a locally reasonable choice. The conflict only becomes visible in review, integration, or production.

This is not a model-intelligence problem. It is a team-state problem.

What the common fixes solve - and where they stop

Chat history

Chat history is useful when one person needs to replay a recent session. It preserves detail and can explain how the agent reached a result.

It is a poor source of team truth. A long conversation mixes ideas, corrections, rejected options, pasted customer data, and the final call. The next reader must infer which sentence won. Another teammate may not have the same history at all.

Session summaries

A good summary reduces the cost of continuing work after compaction. It should carry the current objective, completed work, open questions, and important constraints.

But a summary belongs to a run. It can omit the exact reason a design was rejected, and it rarely records who owns a decision or what later replaced it. Use it to resume work, not to govern every future task.

CLAUDE.md

CLAUDE.md is the right baseline for stable instructions Claude should read in a repository: commands, directory structure, coding conventions, hard safety rules, and durable invariants.

It becomes fragile when teams use it as a running decision log. The file grows, old calls remain beside new ones, and product or customer decisions outside the repository never arrive. Nobody can tell whether a sentence is a current rule, an old preference, or one person's note.

The practical split is simple:

put stable operating instructions in CLAUDE.md;
put important decisions in records that can show owner, reason, status, and replacement;
link the two when a decision must shape nearly every task.

For a broader comparison of the available context layers, see the best tools for giving AI coding agents your team's context.

Memory plugins and MCP servers

Memory plugins can preserve facts across sessions, and MCP servers can let an agent query live systems during a task. Both are valuable.

The remaining question is not only whether the agent can retrieve something. It is whether the retrieved statement is approved, current, relevant to this code path, and safe to act on.

A memory system may recall both "keep the legacy endpoint" and "remove the legacy endpoint." A team needs to know which one won and why.

Our guide to the best MCP servers for engineering teams explains where live context fits and why fewer, focused sources usually beat a large tool list.

ADRs

Architecture Decision Records are the strongest existing answer for important technical calls. A good ADR records the context, decision, consequences, and alternatives. It sits near the code and survives sessions.

The weakness is coverage. Someone must notice the decision, write the ADR, update its status, and make sure agents read it. Product decisions, customer promises, and cross-team exceptions may never become ADRs even when they constrain the architecture.

ADRs should stay. The next step is making their current decisions available to every relevant agent, alongside the non-architecture calls that affect the same work.

Save decisions, not entire conversations

When an architecture decision matters to future agent work, preserve a small, clear record:

Verdict: what the team chose.
Reason: why this option won.
Rejected option: what looked plausible but failed, and why.
Owner: who can confirm or change the call.
Scope: the services, paths, APIs, product behavior, or customers it affects.
Evidence: the incident, experiment, requirement, or tradeoff behind it.
Status: proposed, approved, superseded, or expired.
Replacement: the newer decision when the answer changes.

This record is more useful than a giant transcript because an agent can tell what it must honor without replaying the whole discussion.

It also serves the whole team. A product person can see which product promise shaped the architecture. An engineering lead can see who owns an exception. A developer can see why the unusual branch should not be "cleaned up." A coding agent can read the same active constraint before changing the code.

A workflow that survives the next session

A workable team loop looks like this:

Capture the call where it happens. Draft the decision from the Slack thread, ticket, PRD, review, or meeting instead of waiting for someone to remember later.
Ask the owner to confirm it. The system should not turn every sentence into a rule. One person approves the verdict and scope.
Connect it to the code it governs. Name the repository, paths, APIs, or capabilities affected.
Brief the agent before work starts. Retrieve only the active decisions relevant to the task.
Record conflicts instead of guessing. If the request contradicts an approved decision, stop and ask the owner.
Supersede decisions visibly. Keep the history, but mark the current answer clearly.

This is shared decision memory: not a copy of every conversation, and not a personal note file, but the small set of approved team calls that people and agents must carry forward.

When several agents work in parallel, the need becomes sharper. Two AI agents can each produce a reasonable change and still leave one codebase inconsistent if they start from different decisions.

How Lockstep handles the missing layer

Lockstep captures possible decisions from the tools where teams already work, asks the owner to confirm them, and keeps the approved record tied to what it affects. An MCP-compatible agent can retrieve the relevant active decisions before it changes code.

It does not replace CLAUDE.md, ADRs, Git, or your issue tracker. It connects the important calls across those systems and makes their status readable to both people and agents.

If you are choosing where to keep those calls today, compare decision-log tools for product and engineering teams. The best setup is the one your team will both update and read.

Claude Code does not need every conversation your company has ever had. It needs the right active decisions before it acts.

That is how teams stop explaining the same architecture twice.

The Feed Is Coming for GitHub

Naman Jain — Sat, 27 Jun 2026 09:37:29 +0000

Before reels/shorts became mainstream, the common agreement about social media was that the moat was the network effect (friend’ s graph). The valuable thing about Facebook was that your friends were on it, and the friends-of-friends data sitting across all those profiles was an asset nobody thought could be replaced. You opened the app and you went to people’s profiles, walls, the network.

Then the feed (Algorithm) arrived. It started as a convenience layer on top of the graph: here's what happened today, what is trending, what people are posting about, in one place. But over a few years the relationship inverted. The algorithm became the product, and the graph became one input among many that the algorithm uses to decide what to show you. The graph never went away. It just stopped being where the value lived. Your profile, your friends and your likes, posts, comments are now consumed at the internal API layer; the algorithm is their customer.

This keeps happening to systems everyone assumed were permanent as many people are writing about. The clearest case in the enterprise is the CRM. Salesforce and HubSpot won because they owned the database: every call note, every contact, every reason a deal stalled lived in one place, and the cost of leaving climbed every year. That hasn’t changed. What’s changed is that a layer of agents now sits on top: research bots that brief a rep before a call, tools that listen to meetings and write structured notes back into the CRM, an orchestration layer that decides what the rep should look at first. The CRM didn’t die. It became an input to the thing the rep actually opens in the morning.

I think GitHub is next.

Why GitHub won

GitHub is the system of record for code. It has been the obvious, indisputable answer for fifteen-plus years, and the reasons are the same ones that made the CRM sticky. The code lives there. So do the pull requests, the issues, the review history, the CI runs, the CODEOWNERS file; years of accumulated operational context about how a codebase came together. Open source colonized it, which pulled in everyone else. Microsoft paid $7.5 billion for it in 2018 because owning the place where the world’s code lives is one of the great franchises in software

And GitHub did what every dominant platform does: it expanded outward from the database. Actions, Packages, Codespaces, Advanced Security; each new module built on the same spine, each one raising the cost of leaving. Every tool in the marketplace is, in effect, paying rent for the right to plug into GitHub’s data.

The reason the database won is worth stating plainly: code had to live in one place because the human working on it could only look in one place at a time. Concentration was a feature. The gravity came from accumulation.

What changes when the user is an agent

That premise is breaking. The thing increasingly working on the code isn't a human who can look in one place at a time. It's an agent that can look everywhere at once.

To a coding agent, GitHub is a database. A very good one; trusted, well-integrated, a decade of context, but a database. The agent doesn't need the PR review UI, the issues board, the merge-queue interface. It needs structured state it can read and write with low friction. The carefully designed human workflows on top become what an old profile page became after the feed: still there, no longer the point.

And an agent has no trouble pulling from GitHub and the issue tracker and Slack and the design files and the CI logs and production telemetry at once, then reasoning across all of it before it does anything. In the human era, value pooled wherever the data was. In the agent era, value pools wherever the reasoning happens. The layer that reads across every source and decides what to do. That layer treats GitHub as infrastructure.

The switching cost moves with it. “All our code is in GitHub” was the lock-in for fifteen years. “All our decisions, our coordination, our institutional context live in our agent layer” is the lock-in for the next fifteen. GitHub also sees this clearly, which is why it’s racing to build the intelligence layer inside its own walls, Copilot, a coding agent that goes from issue to merge, an MCP registry. It’s the same move Salesforce made: bring the AI inside, keep the value from migrating out. Whether it stays inside their walls is the open question.

The thing GitHub doesn’t store

Here's the gap. GitHub records the artifacts: the diffs, the merged PRs, the final state of the code. It does not record the decisions that produced them.

The thing that steers a codebase isn't the code; it's the decisions. "Auth is JWT, fifteen-minute expiry." "We renamed /login to /session." "Nothing new writes to that table." Those decisions live in people's heads, in Slack threads that scroll away, in docs that went stale the week they were written - and no agent ever reads any of it. GitHub only learns a decision happened after the conflicting code has already merged. By then it's a bug, not a heads-up.

This gets acute the moment more than one agent is involved. Two developers point two agents - maybe Claude Code, maybe Codex, maybe Gemini - at the same system. Agent A renames an endpoint. Agent B, with no idea, keeps calling the old one and ships it. Agent A decides the token scheme; Agent B invents a different one. Nobody coordinated because there was nowhere to coordinate. The system of record holds the code. It holds nothing that lets these agents stay in sync before they act.

Where this points: Lockstep

This is the layer I’m building. Lockstep is the shared decision record every agent reads before it does anything.

When an agent starts a session, the first thing it gets is a briefing: here’s what changed since you were last here, here’s what’s binding; highest blast radius first, so the change that breaks three downstream services surfaces and the cosmetic rename stays quiet. Only then does it write a line of code. Rules files like AGENTS.md and decision docs like ADRs both help, but they’re written once and read rarely; neither carries a fresh decision from one agent to the next before the second one acts.

If that sounds familiar, it should. That briefing is the feed » the prioritised, one-place-to-look surface the VP of Sales now opens instead of a raw account list. Except the user is an agent, the inputs are decisions and contract changes instead of accounts and signals, and the output is code that doesn’t conflict. It works with any MCP-compatible agent, because a coordination layer has no reason to care which vendor is doing the typing; the same way the feed never cared which friend posted.

GitHub keeps the code, for all the reasons it always has. But the value is moving up a layer » to the thing that reads across the whole record and decides what happens next. The friend graph never went away. The CRM isn’t going anywhere. Neither is GitHub. They’re becoming inputs.

The next decade of developer tooling gets built one layer up.