Seven-Layer Memory for AI Coding Assistants: Designing Lightweight State Files

In AI-assisted software development, generating a code snippet is often not the hardest part. The real challenge is keeping the system aligned with project goals, technical constraints, change history, and current task status over hours or even days of continuous work.

As projects grow, relying only on the context window quickly becomes problematic. The system may need to inspect the directory structure, analyze multiple source files, track previous changes, understand build errors, and remember constraints mentioned earlier in the conversation. Even if the context window can be expanded, that does not mean all information should remain in every prompt. Larger contexts can also increase input costs, retrieval noise, and attention fragmentation.

A more reliable approach is to treat memory as a layered information management system rather than a single conversation history. The seven-layer memory model described here is not tied to a specific product. It is a general architecture for AI coding assistants, code agents, and automated development systems.

Why a Context Window Is Not Permanent Memory

A context window answers the question, “How much information can the system see during the current request?” It does not answer, “How much useful knowledge can the system preserve over time?”

These concepts can be distinguished as follows:

• Context: Information directly visible during the current reasoning process.
• Memory: Information filtered, compressed, and persisted for future use.
• Knowledge base: An external collection of materials intended for broader retrieval.
• State: Data describing current progress, unfinished work, and next actions.

If the entire repository, complete conversation history, and every command output are placed into the context, three problems commonly appear.

First, information density decreases. Important design constraints can be buried under logs, duplicated code, and irrelevant files.

Second, historical information may conflict. When early requirements, temporary decisions, and final implementations all remain together, it becomes difficult to determine which statements are still valid.

Third, maintenance costs increase. Sending large amounts of content with every request increases processing time, resource usage, and the chance of failure.

Mature systems therefore tend to use a combination of on-demand reading, layered storage, and dynamic compression instead of permanently accumulating all history in the conversation.

The Basic Structure of Seven-Layer Memory

1. Current Working Memory

Current working memory contains information directly related to the active task, such as:

• Files the user has asked to modify.
• Confirmed error symptoms.
• The interface or data structure currently being used.
• The steps planned for the current operation.
• The result of the most recent action.

This layer is highly time-sensitive, narrow in scope, and high in priority. It should not contain the entire project. It should retain only what is necessary to complete the current action.

For example, when investigating an API error, current working memory may need the request parameters, response data, relevant function, and reproduction steps. It does not necessarily need the entire frontend directory.

2. Session Memory

Session memory preserves stable constraints from the current conversation, including user preferences, confirmed approaches, rejected alternatives, and task objectives.

Examples include:

• The code must support a specific language version.
• The database schema must not be changed.
• Tests must cover failure paths.
• Asynchronous processing has been selected.
• A particular implementation approach was rejected after discussion.

The key requirement is to distinguish facts from suggestions. Facts can usually be carried forward directly, while suggestions should be revalidated in a new task. Without this distinction, the system may mistake a temporary discussion point for a final design decision.

3. Project Memory

Project memory describes long-term, repository-level information, such as directory responsibilities, module boundaries, build procedures, test entry points, configuration locations, and deployment workflows.

This information changes relatively slowly but is reused frequently. By storing it separately, the system can read a project summary first and then inspect specific files as needed, reducing repeated repository scans.

Project memory should not record every implementation detail. Its primary purpose is to explain how to locate information. Instead of storing all business logic, it is more useful to record:

• The responsibility of each core module.
• Which directories contain generated files.
• Which configuration files must not be edited directly.
• Where the test and static analysis commands are defined.
• Which components should be checked first when a problem occurs.

4. Decision Memory

Decision memory records important technical choices and the reasons behind them. This layer is often missing from automated development systems, despite its high value.

A complete decision record should include at least:

• The decision.
• The underlying problem.
• The alternatives that were considered.
• The final choice.
• The reason for selecting it.
• Potential downstream effects.
• Its scope and conditions under which it may no longer apply.

For example, a record should not simply say, “Use caching.” It should explain that short-lived caching was added to a read path with infrequent data changes to reduce repeated queries, that the cache is actively invalidated after successful writes, and that the approach does not apply to strongly consistent read scenarios.

This allows the system to understand not only what was done, but why it was done. It also reduces the chance that previously rejected approaches will be proposed repeatedly.

5. Task Memory

Task memory stores the execution state of the current requirement and is well suited to structured management. Common fields include:

• Task objective.
• Completed items.
• Outstanding items.
• Current blockers.
• Risks.
• Validation results.
• Next action.

Compared with a long natural-language description, a task list is easier to update automatically and makes it easier to resume work after an interrupted session.

For example:

Goal: Fix configuration loading failure
Completed:
- Located the configuration parsing module
- Reproduced the exception caused by an empty field
Remaining:
- Add input validation
- Add exception tests
- Run the complete test suite
Risk:
- Legacy configurations may depend on permissive parsing behavior
Next:
- Add compatibility tests before changing the parsing logic

6. Semantic Retrieval Memory

As a project grows, the system cannot rely only on fixed file paths. It must also retrieve relevant information based on the meaning of a question.

Semantic retrieval memory can index:

• The purpose of functions and classes.
• The meaning of configuration settings.
• Error logs and solutions.
• Historical change explanations.
• Test cases.
• Key conclusions from design documents.

Retrieved content should not be injected into the context in its entirety. It should first be ranked and reduced. A practical process is:

1. Extract keywords and intent from the user’s question.
2. Filter candidates using file paths, symbol names, and modification times.
3. Rank the candidates by relevance.
4. Remove duplicate passages.
5. Keep only the evidence needed to support the current decision.
6. Read a larger range of the original file only when necessary.

Semantic similarity does not always indicate business relevance. Two modules may both contain the word “cache,” while one handles page caching and the other handles database caching. The retrieval system must consider directory structure, call relationships, and surrounding context.

7. Archive and Long-Term Experience Memory

Archive memory stores completed information that may be useful again, including incident-handling experience, migration considerations, testing pitfalls, and summaries of historical changes.

This layer should not grow indefinitely. Long-term memory requires periodic compression, duplicate removal, deletion of obsolete rules, and metadata indicating when information was last updated and how reliable it is.

Each memory entry can include metadata such as:

Source: Code inspection / User confirmation / Test result
Updated: When the task was completed
Confidence: High / Medium / Low
Scope: Specific module or entire project
Invalidation condition: Configuration structure changes

These fields help the system assess risk when reusing old experience instead of blindly applying historical conclusions.

Why a Small State File Can Be Critical

A state file containing only a few hundred lines can be valuable not because it stores a large amount of content, but because it preserves high-density, actionable information.

It is more like a navigation index than a copy of the project. A useful state file typically includes:

1. Project overview.
2. Current task.
3. Core constraints.
4. Key directory descriptions.
5. Recent decisions.
6. Current risks.
7. Validation commands.
8. Outstanding work.
9. Known failure causes.
10. Recommended next steps.

This type of file is effective because it compresses important information scattered across conversations, code, and logs into a summary that can be read quickly. When starting a new task, the system can read the state file first and load source code only as needed, significantly reducing irrelevant context.

However, a small file is not a universal solution. If it is not maintained, it becomes outdated memory. Clear update rules are therefore essential.

Memory Writing: What Should Be Preserved?

Not every piece of information belongs in long-term memory. The following questions can help determine whether information should be saved:

• Will it be reused in future tasks?
• Will it affect the choice of a technical solution?
• Can it reduce the cost of diagnosing a future problem?
• Has it been confirmed by testing or explicitly by the user?
• Is it likely to remain valid for a meaningful period?
• Can it replace the original content with a shorter expression?

Suitable candidates include final decisions, stable constraints, recurring error causes, and validated operating procedures.

Poor candidates include temporary guesses, complete command output, repeated code fragments, unverified assumptions, and one-time intermediate results.

A “candidate memory” mechanism can be useful. New information first enters a temporary area and is promoted to formal memory only after it has been confirmed, reused, or validated through testing.

Memory Retrieval: Summary First, Evidence Second

Memory should be read from broad context to specific evidence.

First, read the project overview and current task to establish direction.

Second, use task keywords to locate relevant modules, decisions, and historical issues.

Third, inspect a small amount of original code to verify that the summary is still accurate.

Fourth, when conflicts appear, prioritize the latest code, test results, and explicit user requirements.

Fifth, write new conclusions from the task back to the state file or the appropriate memory layer.

This process prevents the system from making decisions based solely on an outdated summary. Memory supports reasoning, but it must not replace verification against current code and actual results.

Handling Conflicting, Outdated, or Incorrect Memory

The most dangerous memory problem is not failing to remember something. It is remembering something incorrectly and continuing to use it.

A practical priority order is:

1. The user’s explicit current requirement.
2. Current code and actual test results.
3. The latest project decisions.
4. Recent task records.
5. Older experience-based summaries.
6. Unverified assumptions.

When two records conflict, the system should document the conflict rather than silently overwrite one of them. For example:

Conflict:
- Old record: The module supports two configuration formats
- Current code: Only one format parser remains
Action:
- Use the current code and test results as the source of truth
- Mark the old record as outdated
- Check whether compatibility documentation is needed

Explicit conflict handling reduces the risk of propagating incorrect information.

Practical Engineering Guidance

A project can begin with a simple directory structure:

project-notes/
  overview.md
  current-task.md
  decisions.md
  known-issues.md
  archive/

There is no need to introduce a complex database or vector retrieval system immediately. Start with a clear file structure, fixed templates, and human-readable formats to validate whether the workflow is useful.

Several principles are especially important:

• Update the current state after every task.
• Record the reasoning behind important decisions.
• Check whether summaries are outdated after code changes.
• Store conclusions and diagnostic clues instead of lengthy logs.
• Allow humans to correct automatically generated content.
• Remove or mask sensitive information.
• Track memory files in version control, but never commit secrets or personal data.

As project size and task volume increase, additional capabilities such as full-text search, semantic indexing, change graphs, and automatic summarization can be introduced.

Conclusion

A long context window does not automatically solve the problems of long-term collaboration. A more effective approach is to manage information according to its time sensitivity, scope, and reliability. The system should know what must be used immediately, what can be retrieved on demand, what should be preserved over time, and what is no longer valid.

The core of a seven-layer memory architecture is not accumulating more text. It is establishing an information lifecycle that can be updated, verified, and traced. A lightweight state file is not merely a note-taking document; it can serve as a project navigator, task recovery mechanism, and decision index.

For development teams, the first priority should not be building a complex form of fully automatic memory. It should be creating stable memory-writing rules, a clear state structure, and a strict validation process. Only when memory remains consistent with real code, test results, and current requirements can an AI coding assistant remain continuous, reliable, and controllable across large projects and multiple development sessions.