Recovering Instructions, Rules, and Long-Term Memory When Migrating AI Coding Tools

Developers gradually build a personal way of working with AI coding tools. It may include coding style, commit conventions, testing requirements, directory structures, frequently used scripts, project background, and preferences formed through long-term collaboration.

These details may look like ordinary text files, but they are often more valuable than chat history. Chat history records what happened in the past, while global instructions, project rules, and long-term memory determine how the tool should work in the future. If an account is restricted, service policies change, or a team switches tools, the difficult part is not reinstalling software. It is carrying years of accumulated context to the new environment without losing its meaning.

This article does not focus on any specific product or promote or evaluate a particular platform. Instead, it presents a migration method that applies to most AI coding tools.

1. Migration Is About Restoring Work Semantics, Not Copying Files

When migrating for the first time, many people simply copy the old tool’s configuration directory into the new tool’s directory. This often fails because different tools use different directory structures, configuration fields, loading orders, and memory formats.

An older tool may separate information into the following categories:

• Global instructions: Behavioral requirements that apply to every project
• Project rules: Requirements that apply only within a specific repository or directory
• Long-term memory: Background information inferred from previous collaboration
• Skills or templates: Procedures for recurring types of tasks
• Session history: Previous conversations and execution records
• Plugin configuration: External commands, extensions, or environment variables

Even when a new tool supports importing data, it may not recognize every category. Long-term memory and project rules are especially unlikely to follow a universal format. Direct copying can cause several problems:

1. Rules are placed in a directory the tool does not load.
2. Global rules are treated as project rules, creating unnecessary restrictions.
3. Original priorities are lost, causing instructions to override one another unexpectedly.
4. Markdown, JSON, or plain-text structures are incompatible.
5. Sensitive information is migrated unnecessarily, increasing exposure.
6. Rules appear to exist but have no effect during actual work.

The goal of migration should therefore not be to make files appear in a new directory. It should be to restore the original collaboration semantics in the new tool.

2. First Step: Inventory the Old Environment

Do not immediately copy the entire configuration directory. Start by creating an inventory. A useful approach is to organize the data by both scope and information value.

Classify by Scope

Global content

This applies to all projects, such as:

• Preferred programming languages and frameworks
• Required code formatting conventions
• Whether tests must be added
• Files that must not be modified
• Preferred response language
• General principles for handling errors

Project-level content

This applies only to a specific repository, such as:

• Project directory structure
• Build and test procedures
• Service startup commands
• Database migration procedures
• API design conventions
• Historical context for specific modules
• Compatibility logic that must not be changed

Task-level content

This supports a particular type of work, such as:

• Code review checklists
• Pre-release verification procedures
• Troubleshooting steps
• Documentation templates
• Database change conventions
• Security audit requirements

This classification prevents indiscriminate copying. If every piece of information is inserted into every session, context length increases and the tool may incorrectly apply a special requirement from one project to another.

Classify by Information Value

Divide the existing content into three groups:

• Must migrate: Core development standards, project constraints, and critical background
• Recommended: Frequently used templates, troubleshooting procedures, and review checklists
• Can be discarded: Obsolete rules, duplicate content, and records from one-time tasks

Migration is not the same as archival backup. For rules that are no longer valid, the best approach is to clean them up before migration rather than copy them unchanged.

3. Second Step: Create an Intermediate Format

Because tools do not share a universal memory exchange standard, the safest approach is to create an intermediate layer that does not depend on any specific platform.

For example:

ai-context/
├── global/
│   ├── coding-style.md
│   ├── communication.md
│   └── safety.md
├── projects/
│   ├── project-a/
│   │   ├── overview.md
│   │   ├── rules.md
│   │   ├── commands.md
│   │   └── constraints.md
│   └── project-b/
├── workflows/
│   ├── code-review.md
│   ├── release-checklist.md
│   └── incident-response.md
└── migration-manifest.json

The global directory stores general preferences, projects stores project context, and workflows stores reusable procedures. The manifest records the source, purpose, and destination of each item.

A manifest can use a structure like this:

{
  "items": [
    {
      "source": "Global rules from the old environment",
      "target": "Global instructions in the new environment",
      "scope": "global",
      "status": "pending"
    },
    {
      "source": "Build instructions for Project A",
      "target": "Project rules for Project A",
      "scope": "project",
      "status": "pending"
    }
  ]
}

This intermediate format has three key advantages:

1. It does not depend on the old tool’s directory structure.
2. It can be reused when adopting a third tool in the future.
3. It supports review, redaction, and version control before import.

4. Third Step: Resolve Rule Conflicts and Priorities

Rule conflicts are one of the easiest migration issues to overlook. An old environment may contain global instructions, project instructions, and temporary requests, each with a different level of authority.

A practical priority order is:

1. Security and compliance requirements
2. Mandatory project-level rules
3. Global development standards
4. Task-specific preferences
5. Communication and formatting preferences

For example, a global rule may say to minimize file changes, while a project rule requires the API documentation to be updated at the same time. The project rule should override the global preference, but neither can override a higher-level security requirement.

To reduce ambiguity, rewrite vague statements as executable rules.

Not recommended:

Write clean and规范 code.

Recommended:

Before submitting code, describe the scope of the changes, potential risks, and verification method.
When adding a public function, include at least one normal-path test and one error-path test.

A useful rule should contain four elements:

• The triggering condition
• The action that must be performed
• The action that is prohibited
• What to do when the requirement cannot be satisfied

For example:

When modifying the database schema:
1. Check the existing migration files first.
2. Do not modify a migration that has already been released.
3. After adding a migration, describe rollback risks.
4. If compatibility cannot be confirmed, pause the change and ask for clarification.

Rules written this way are easier for different tools to interpret and more suitable for team-wide use.

5. Fourth Step: Clean Long-Term Memory

Long-term memory is not the same as a database of facts. It may include outdated information, incorrect assumptions, and project states that are no longer valid.

Consider adding the following fields to each memory item:

Topic:
Content:
Source:
Scope:
Last confirmed:
Confidence:
Still valid:

For example, an old memory item may state that a project uses a particular runtime version. If the project has already been upgraded, retaining that item may cause the tool to generate incorrect commands.

During cleanup, pay particular attention to:

• Background information from completed projects
• Outdated dependency versions
• Temporary branches or one-off solutions
• Passwords, tokens, and private keys
• Unverified assumptions
• Content that conflicts with current team standards
• Duplicate rules with inconsistent conclusions

Sensitive information requires special care. Access credentials should never be stored in long-term memory, project rules, or a repository. The fact that an old tool could read them does not make the practice safe. Use environment variables, a credential management system, or a controlled secret-injection mechanism instead.

6. Fifth Step: Validate Behavior After Import

After migration, do not check only whether the files exist. Verify that the new tool actually uses the imported content.

Create a fixed set of test tasks.

Validate Global Rules

Give the tool a simple code-generation task and check whether it:

• Uses the preferred programming language
• Follows naming conventions
• Adds tests when required
• Uses the correct response language and structure

Validate Project Rules

Within the target project, ask the tool to explain the directory structure or modify a small module. Observe whether it can:

• Identify how the project is started
• Follow the build process
• Avoid protected files
• Use the correct test command
• Explain potential compatibility risks

Validate Long-Term Memory

Ask about historical project context without including the expected answer in the question. For example, ask why a module retains its current design. Check whether the tool can distinguish confirmed facts from information that still needs verification.

Validate Conflict Handling

Deliberately make a request that conflicts with a project rule. Check whether the tool can:

• Detect the conflict
• Explain which rule has priority
• Refuse unsafe or non-compliant operations
• Suggest a practical alternative

If the tool merely mentions a rule in its response but does not follow it in practice, the import location, format, or loading mechanism is still incorrect.

7. Use Scripts Carefully

When there are only a few rules, manual organization is usually the most reliable approach. For larger teams or repositories with many files, a local conversion script can help with tasks such as:

• Scanning the old configuration directory
• Identifying global, project-level, and task-level files
• Removing sensitive fields
• Generating the intermediate format
• Detecting duplicates and conflicts
• Creating a migration manifest
• Producing a report for manual review

Automation should follow the principle that machines process structure while people judge meaning. A script can identify file types, paths, and duplicate content, but it cannot reliably determine whether a rule is obsolete or whether a statement is only a temporary conclusion.

Script output must therefore be reviewed by a person, especially for:

• Permission-related rules
• Production environment procedures
• Security restrictions
• Database operations
• Dependency upgrade policies
• Text containing personal or enterprise-sensitive information

8. Turn Migration into a Maintainable System

A one-time migration solves only the immediate problem. A better approach is to place important context under version control from that point forward.

Consider creating a dedicated context repository with the following practices:

• Keep global and project rules separate.
• Track every change through commits.
• Record the update time and maintainer for important rules.
• Remove obsolete memories at least once every quarter.
• Never place sensitive information in the repository.
• Add validation cases for major rule changes.
• Maintain separate adapters for different tools.

An ideal architecture looks like this:

Unified context source
        │
        ├── Tool adapter A
        ├── Tool adapter B
        └── Tool adapter C

The unified context source stores the authoritative content. Adapters only convert directories, fields, and loading methods for each tool. If another migration is required later, the context does not need to be reorganized from scratch.

Conclusion

AI coding tools can change, accounts can be recreated, and platforms can be replaced. Development standards, project background, and collaboration knowledge should not be locked to a single account or local directory.

When dealing with service restrictions, policy changes, team transitions, or tool upgrades, the safest approach is not to copy configuration files at the last minute. It is to build a context asset system that is independent, auditable, verifiable, and maintainable.

The migration process can be summarized in five principles:

1. Inventory before copying.
2. Abstract before adapting.
3. Clean before importing.
4. Validate behavior before declaring success.
5. Turn one-time migration into long-term version management.

When instructions, rules, and memory are no longer tied to one tool, developers gain more than access to an AI assistant. They gain an engineering collaboration knowledge base that can be reused across environments.