Shared Project Memory for AI Coding Assistants: Keep Context When You Switch Tools

1. Where the Problem Starts: The Tooling Is Fine, the Memory Is Locked In

Using two or more AI coding assistants in parallel is already common. People keep a primary tool and a backup for practical reasons: account availability, quota allocation, differences in model capability, or compliance requirements. What actually drains energy is not maintaining two toolchains, it is re-entering context.

The architecture choice you settled on in your primary tool yesterday, the option you rejected, the production incident you already debugged, the code style you agreed on — all of it has to be explained from scratch when you move to the backup tool today. Worse, those conclusions usually exist only inside the history of a single conversation. They belong to the tool, not to the project.

Step back one level and the conclusion is obvious: context is a project asset and should not be parked in the session state of any single tool. Tools get swapped, accounts get throttled, sessions expire — but the technical decisions and domain knowledge of a project should persist.

2. Why Context Gets Lost: Four Structural Reasons

1. State lives inside the process. In most conversational tools, context has the lifetime of a session. Once the session ends or its history is cleared, it is unreachable.
2. There is no standard export/import contract. Session formats are mutually incompatible, so migration cannot be automated; it is copy-paste by hand.
3. Context is narrative, not structured. A block of free text mixes background, conclusions, to-dos, and speculation. Reusing it is hard: it resists retrieval, resists verification, and grows without bound.
4. There are no freshness or confidence markers. A conclusion from three months ago looks exactly like one from last week, so whoever reuses it cannot tell what has already gone stale.

The fix is therefore not “find a tool that remembers everything,” but decouple memory from the tool and put it in the project’s own repository.

3. Design Principles: Treat Context as a Code Asset

• Files are the contract. All memory is stored as plain text (Markdown) inside the project repository. Any tool that can read files gets the context, which makes the setup tool-agnostic by construction.
• Put it under version control. Every change to memory has an author, a timestamp, a reason, and a rollback path, which prevents memory from being quietly corrupted.
• Structure beats narrative. A shared template, explicit fields, and an explicit state machine make memory parseable, verifiable, and searchable.
• Inject on demand rather than dumping everything. The context window is a limited budget. Long-term memory should stay out of the prompt by default and be retrieved only when relevant.
• Sensitive data never enters the repository. Keys, tokens, and real user data do not belong in the memory layer. This is a hard boundary, not a preference.

4. A Four-Layer Memory Model

Splitting “memory” into four layers with different lifecycles and different uses is the core of this design:

Layer	Contents	Change frequency	Injection mode
L1 Long-term constraints	Tech stack, coding conventions, prohibitions, environment agreements	Very low	Loaded by default in every session
L2 Decision records	Architecture choices, trade-offs, reasons for rejection	Low, append-only	Retrieved by tag or task
L3 Knowledge base	Domain terms, interface contracts, pitfalls already hit	Medium	Semantic or keyword retrieval
L4 Session state	Current task progress, next steps, blockers	Very high	Load the “current task” at startup

L4 is the only layer most people actually use — and it is precisely the layer most likely to be lost. Modeling it explicitly as an in-progress task file gives cross-tool handoff a deterministic landing point.

5. Directory Layout and Format Conventions

docs/agent-memory/
├── README.md                  # read/write rules, index, owner
├── constitution.md            # L1: long-term constraints
├── decisions/                 # L2: decision records (incrementing IDs)
│   ├── DEC-0003-cache-layer-choice.md
│   └── DEC-0007-rate-limit-placement.md
├── knowledge/                 # L3: glossary, interface contracts, incident lessons
│   ├── domain-glossary.md
│   └── pitfalls.md
├── tasks/                     # L4: in-progress tasks
│   └── 2026-08-20-login-refactor.md
└── .meta/
    └── manifest.json          # revision, entry list, checksums

Each memory entry uses one shared template so that scripts can validate it field by field:

---
id: DEC-0007
title: Rate limiting belongs in the gateway, not in business services
status: accepted          # proposed | accepted | superseded
updated: 2026-08-27
confidence: high          # high | medium | low (whether re-validation is needed)
supersedes: DEC-0003
tags: [gateway, rate-limiting, observability]
---
## Background
When traffic spikes, business-service thread pools saturate; there is no single
place that enforces a global limit.
## Decision
Enforce centralized rate limiting at the gateway layer, and keep a degradation
switch in the business services.
## Alternatives and why they were rejected
- Rate limiting inside each service: rules are scattered, no global quota is possible.
- A dedicated rate-limiting service: one extra network hop, higher operating cost.
## Impact and rollback
Affects all inbound requests; rollback means disabling the gateway limiter and
restoring service-level quotas.
## Open questions
- [ ] Whether peak quotas cover large promotional events

The point is status and supersedes. When new knowledge arrives, mark the old entry as superseded and point it at the new entry instead of deleting it. Deletion destroys traceability, and traceability is the memory store’s biggest advantage over a chat history.

6. The Write Path: When Memory Actually Gets Persisted

Writes must be driven by explicit triggers, otherwise the memory store degrades into an unmaintained pile of drafts. Usable triggers include:

• End of session: once a task reaches a natural stopping point, write conclusions into L2/L3 and progress into L4.
• Pre-commit hook: before code is committed, check whether the memory store has unsynchronized changes, so you avoid “the code merged but the reasoning was never recorded.”
• External events: incident retrospectives, review outcomes, requirement changes.

Wrapping the persistence step in a command reduces format drift from manual editing:

# End of session: freeze this round's conclusions and write progress back to the task file
memory wrap-up --task current --extract-decisions
# Before starting a new tool: load long-term constraints and the current task brief
memory load --scope project --task current > /tmp/brief.md

7. The Injection Path: Making Every Assistant Read the Memory Automatically

Mainstream AI coding tools generally support an instruction file at the repository root, a global preference file at the user level, and supplementary instruction files placed per directory. Using that shared convention is enough to implement layered injection:

# Project instructions (auto-loaded)
@docs/agent-memory/constitution.md
@docs/agent-memory/knowledge/domain-glossary.md

• Default layer: L1 constraints are always loaded. They are small and change slowly, so the cost is controllable.
• Retrieval layer: L2/L3 are not injected by default; the tool looks up relevant entries by tags or keywords before starting a task.
• Task layer: only the single file under tasks/ marked as in progress is loaded. Read it at handoff, archive it on completion.

For a knowledge base with many entries, keep an index file alongside it (entry ID, title, tags, summary). Read the index first and fetch the body only when needed; this significantly reduces context overhead.

8. Consistency, Conflicts, and Versioning

Running several tools in parallel introduces concurrent-write problems. Three strategies are recommended:

1. Single-writer principle: only one session may hold the write lock at a time (implemented with a lock file or an exclusive branch); all other sessions are read-only.
2. Optimistic locking check: compare the revision in manifest.json before writing; if it does not match, reject the write and ask the caller to sync first.
3. Atomic write: write to a temporary file, then rename, so an interrupted process cannot leave a half-written file.

def append_memory(entry: str, expected_revision: int) -> None:
    m = load_manifest()
    if m.revision != expected_revision:
        raise ConflictError("The memory store was updated by another session; sync before retrying")
    write_entry(entry)
    m.revision += 1
    save_manifest_atomic(m)                 # temp file + rename
    git_commit(f"memory: append {entry.id}")

Add a validation script that runs on a schedule and checks format completeness, duplicate entries, and accepted entries that have not been updated for a long time. That turns “memory rot” into a detectable engineering signal.

9. Privacy and Security Boundaries

• Treat the memory store as a sensitive asset by default: host it in a private repository with explicit read/write permissions and access auditing.
• Define redaction rules: host names, internal addresses, accounts, tokens, and customer identifiers are replaced with placeholders. Intercept them at write time rather than cleaning up afterwards.
• When off-site backup is required, use a private storage bucket from a general-purpose cloud provider with server-side encryption and access logging enabled; object storage offerings such as Baidu AI Cloud’s satisfy persistence and access-control needs. Versioning on top of that also keeps historical snapshots of the memory.
• Keep an explicit “never store” list: credentials, keys, unredacted data, and personal reasoning unrelated to the project.

10. Measuring Whether It Works

Without measurement, you cannot tell whether the approach actually solved the problem. Four metrics are worth tracking:

• Context rebuild time: how long it takes to reach a workable state after switching tools.
• Repeated explanation rounds: how many times you had to restate the same background before the tool understood it.
• Memory hit rate: the share of injected entries that the tool actually referenced, used to judge retrieval precision.
• Stale entry ratio: the share of accepted entries not updated within the agreed period, used to judge maintenance health.

11. Phased Rollout

1. Phase 1 (immediate payoff): create the instruction file at the project root and write down the tech stack, directory conventions, coding standards, and prohibitions as L1 constraints.
2. Phase 2: introduce decision-record and task-file templates, standardize the handoff process, and make “every tool reads the brief first” the norm.
3. Phase 3: add the missing write triggers (pre-commit hook, end-of-session command) and the validation script so the memory store maintains itself.
4. Phase 4: add the retrieval index and cloud backup, and handle concurrent writes and permission governance for multi-person collaboration.

12. Common Pitfalls

• Using the memory store as a log: piling up a timeline without structure. Retrieval noise quickly exceeds the benefit.
• Chasing full injection: long-term memory eats the context budget and degrades output quality instead of improving it.
• Overwriting instead of marking as superseded: rewriting an old conclusion directly loses the information about why it changed.
• Ignoring concurrency: two tools writing at the same time with no revision check is the most common and hardest-to-debug failure source.

Ultimately, sharing context across tools is a transfer of context ownership: take memory out of the tool’s conversation history and give it back to the project repository and version control. Once that is done, the tool becomes a replaceable execution layer, and the project’s knowledge assets stay in your hands.