Switching AI Coding Assistants Without Losing Context: A Local Memory Layer Design

1. The Real Problem Isn’t Too Many Tools — It’s Memory Locked Inside a Session

Running several AI coding assistants at the same time — one as the primary, one as a backup, or a split by task type — is already the norm for many teams. But as soon as you go multi-tool, a new kind of overhead appears:

• Repeated explanations. The approach you agreed on with your primary assistant this week, the reason a certain area was declared off-limits, the odd behavior of one particular API — all of it has to be explained again in the other assistant.
• Decision drift. The same question gets discussed twice in two sessions, the two conversations reach different conclusions, and nobody is sure which one counts.
• Repeat mistakes. A path that was already proven to be a dead end gets re-explored from scratch in a new session.
• No audit trail. Three months later, someone asks “why did we design it this way,” and the only source is chat history — which is usually no longer accessible.

Broken down, there are three root causes:

1. Lifecycle mismatch. An assistant’s session memory is bound to a single task. Once the task ends, or the context is compacted, or the window overflows, high-value information decays. A project’s fact lifecycle is months; a session’s lifecycle is tens of minutes.
2. Proprietary formats. Memory lives in each tool’s internal context representation. No other tool can read it directly, so migration means a human moving text through the clipboard.
3. Writing depends on self-discipline. Any mechanism that requires “write a daily summary” or “remember to recap” fails once the initial enthusiasm fades, because it puts the cost of memory on the person.

The conclusion is clear: what’s needed is a memory layer centered on local files and independent of any specific tool. Tools are replaceable execution units; files are the single source of truth for project facts.

2. Five Design Principles

Setting the constraints before writing code is what keeps the knowledge base from becoming another document directory nobody maintains.

1. Files are the source of truth. Everything that must survive across sessions eventually lands in a plain-text file. Any tool can read it and write to it, with no proprietary format and no cloud account required.
2. Layered storage, progressive disclosure. Long-lived stable information, daily events, and retrieval entry points belong in different files. Their sizes differ by orders of magnitude, and mixing them makes every load pay unnecessary context cost.
3. Event-driven, not calendar-driven. Writes are triggered only at the moment something is worth keeping. There is no daily check-in obligation. The human holds the trigger; the assistant does the execution.
4. Append first, modify rarely. Log-style content only allows appends and correction annotations. Rewriting is discouraged, which makes the store naturally suited to version control and gives it a traceable history.
5. Auditable by humans. Memory content must be prose a person can read directly, not a structured blob only a machine can parse.

3. Layered Directory Structure

knowledge-base/
├── CONTEXT.md              # Static context: goals, tech stack, directory conventions, common commands
├── CONVENTIONS.md          # Collaboration conventions: naming, commit granularity, prohibitions, glossary
├── decisions/              # Optional: records of important decisions (background / options / conclusion / impact)
└── daily-log/
    ├── INDEX.md            # Monthly index: date -> overview of entries for the month
    ├── 2026-04.md          # Current-month index (split by month once entries grow)
    └── 2026-04-22.md       # Daily event log

The three layers have completely different roles:

Layer	Write frequency	Typical size	Main reader
CONTEXT.md / CONVENTIONS.md	Very low; updated at project milestones	100–200 lines	Loaded in full at the start of every session
decisions/	Low; only for major trade-offs	20–40 lines each	Retrieved on demand
daily-log/	High; can be triggered at any time	A few to a few dozen paragraphs a day	Retrieved by date and keyword

The key point is hot/cold separation: fast-growing logs don’t pollute the static background that gets loaded every time, and the static files don’t go stale quickly from being stuffed with daily entries.

4. The Static Layer: Say the “Say It Again Every Time” Things Once

The goal of CONTEXT.md is to bring any brand-new session to a usable level of understanding within three minutes. Keep only stable facts in it:

• The problem the project solves, the current phase, the definition of done
• Tech stack and key version constraints (version numbers are often the source of conflicts)
• Directory responsibilities and module boundaries
• Common commands for build, test, formatting, and migrations
• Explicit off-limits areas: modules that must not be changed, dependency types that must not be introduced, runtime assumptions that are incompatible
• A glossary: mapping business jargon to the actual names used in code

Two practical details:

• Control the size. The static layer is a token tax paid on every load. Once it goes past a hundred or two hundred lines, consider splitting it or converting inline copies into link-style references.
• One source, many readers. Don’t maintain a near-identical file per tool. Have different tools read the same file (a link in the same directory, or a fixed read from the repository root), and add a consistency check to the version-control pipeline so two copies never quietly diverge.

5. The Event Layer: Compress the Cost of Memory to One Sentence

This is the core mechanism of the whole design. The only interaction in day-to-day use is:

Log this: today I aligned with the owner on the approach — the core principle is to guarantee idempotency first, then talk about throughput; next step is to add contract tests.

After that one sentence, the assistant should execute a fixed sequence:

Input: one natural-language description of an event
  ↓
1. Get the time     Call a system time capability to obtain the current time; guessing from the model's own knowledge is forbidden
  ↓
2. Extract a topic  Pick a 4–10 word topic, produce e.g. "14:37 | Approach aligned"
  ↓
3. Structure it     Fill in four fields: Background / Conclusion / Evidence / Next steps (omit empty ones)
  ↓
4. Check duplicates Search topics and keywords in today's file; if there is a hit, update the existing paragraph instead of appending again
  ↓
5. Persist          Append to the daily log; if today's file does not exist, create the heading first
  ↓
6. Update index     Add one entry to the monthly index: date + topic + keywords
  ↓
7. Read back        Echo the final paragraph back to the user for confirmation

A few constraints that are easy to overlook but matter a lot:

• The time must come from a tool call. If you let the model “guess” the current date, it will almost certainly be wrong across day and month boundaries — and once the date in a log is wrong, every subsequent date-based retrieval fails.
• Deduplication takes priority over appending. The same decision being “logged” over and over is the most common way this system rots. One keyword search before writing costs far less than cleaning up afterwards.
• Fixed paragraph format. A fixed format makes entries quick to scan and gives index and retrieval scripts a stable basis for parsing.

Paragraph template example:

## 14:37 | Approach aligned
- **Background**: The bulk import API produced duplicate writes under large data volumes.
- **Conclusion**: Introduce an idempotency key on the write side first, then discuss throughput optimization.
- **Evidence**: The duplicated data came from retries, not from concurrency.
- **Next steps**: Add contract tests covering retry scenarios (owner: TBD).
Keywords: approach / alignment / idempotency / retry / decision

The keyword line looks redundant, but it is what makes a 30-second hit possible three months later — the body is the narrative, the keywords are the retrieval surface.

6. The Retrieval Layer: Narrow by Date, Then Locate the Paragraph

Once the logs have grown to a few dozen files, retrieval has to be layered, following the same idea as a database’s separation of index and data:

• Level 1: narrow by time. Check INDEX.md or the monthly index and use keywords (architecture, auth, rate limiting, performance) to find candidate dates. Index entries stay on one line, holding only “date + topic + keywords.”
• Level 2: locate by paragraph. Open the candidate date file and use a keyword to hit the specific paragraph heading.

Index entry example:

- 2026-04-22 | Approach aligned | idempotency / retry / decision
- 2026-04-22 | Production incident review | cache / stampede / degradation
- 2026-04-23 | Dependency upgrade evaluation | version / compatibility / rollback

If you only have a dozen days of logs, a plain full-text search for a keyword under daily-log/ is usually faster than going through the index. The index only starts paying off at scale, but retrofitting it later is very expensive, so the advice is to start writing it on day one.

7. Tool-Switching and Cold-Start SOP

With a memory layer in place, switching tools stops being a re-explanation and becomes a load. Fixed handoff procedure:

1. Load the static layer: read CONTEXT.md and CONVENTIONS.md to establish the project baseline.
2. Load recent activity: read the last 3–7 days of logs to pick up work in progress and temporary constraints.
3. Targeted retrieval: for the current task, hit relevant historical paragraphs by keyword, especially “what options were already rejected.”
4. Confirm understanding: have the assistant restate the current goal, constraints, and off-limits areas in its own words, and verify them once by hand.
5. Write-back obligation: any new decision, new constraint, or new pitfall produced in this session must be persisted as a “log this” entry before the session ends — otherwise the next switch loses it again.

Item 5 is what decides whether the whole mechanism holds up over time. A read-only memory base degrades into a stale snapshot within a week or two.

8. Consistency and Maintenance

• One timezone, one naming scheme. Use a single timezone and YYYY-MM-DD.md naming across the base, and never merge files across months; this keeps scripting simple.
• Put it under version control. Plain text plus append-style writes is a natural fit for distributed version control: changes can be diffed, reviewed, and rolled back.
• Archive periodically. Each quarter, summarize the logs by topic and promote stable conclusions into CONTEXT.md or decisions/, leaving only the stream of facts in the logs. Archiving is the only thing that keeps a memory base from growing without bound.
• Format checks. Write a small checker: date-based filenames are valid, paragraphs carry time and a heading, index entries and log entries correspond one to one, and no orphan files exist. Running it in the pipeline is more reliable than manual inspection.
• Sensitive-information red line. The memory base contains no credentials, tokens, connection strings, or internal addresses. Convention files are typically read by several tools across several machines, so a full upload or sync multiplies the exposure surface. A secret scan before committing is a necessary step.
• Sharing across devices. For individual use, a version-control repository is enough. For team scenarios that need centralized retention, long-term archiving, and access auditing, general cloud capabilities such as object storage or log services can host it (for example, Baidu AI Cloud’s object storage service can serve as an archive and backup backend), with monitoring and alerting on write anomalies. This is ordinary infrastructure usage and has nothing to do with the specific coding assistant.

9. Common Pitfalls

1. Writing long documents nobody reads. The value of memory depends on its probability of being retrieved, not on how many words it contains. A five-line structured record beats a 2,000-word essay.
2. Index disconnected from content. Appending to the body without updating the index turns the index into misleading information within weeks — worse than having no index at all.
3. Letting the model infer the time. This is the easiest mistake to make and the most hidden in its consequences.
4. Writing without deduplication. Once the same conclusion has been recorded five times, the credibility of retrieval results drops noticeably.
5. Trying to record everything. The test for “worth logging” should be: could this possibly change a decision three months from now? Meeting minutes don’t qualify.

10. How to Tell Whether It Works

Don’t evaluate by feel. Use three observable metrics:

• Repeat explanations: how many times per week you re-explain the same background to an assistant; this should keep falling.
• Decision look-up time: from “why did we do it this way” to having the answer; target is under 30 seconds.
• Switch cost: the number of conversation turns needed to become productive after switching tools; this should approach 1–2.

Summary: The replaceability of AI coding assistants is improving fast, so parking a project’s long-term understanding inside any single tool’s session is fragile. The steadier approach is to externalize memory as a local knowledge layer with minimal structure, an open format, and versionability: a few static background files carry the baseline, an event-driven log accumulates change, a two-level index keeps history easy to hit, and a fixed handoff procedure lets any tool pick up the work cheaply. Tools get swapped, models get upgraded, but a project memory that is continuously maintained keeps appreciating over time.