Giving AI Agents Persistent Memory for Legacy System Development

1. Organize Information into Four Distinct Storage Locations

The author identifies a core problem: when an AI agent works on an 8-year-old order system, context like JDK version, enum definitions, and deployment details must be re-explained in every new session. The solution is to separate information by lifecycle into four explicit locations:

Project entry points and stable conventions → Repository instruction files (e.g., AGENTS.md) and development standards; read when starting related tasks.

Current business behavior and design rationale → Existing business docs, API specs, decision records; consulted by module and question.

Repeatable executable processes → Skill files, project scripts, CI pipelines; invoked at corresponding development stages.

Single-requirement status and evidence → Requirement records, verification logs, release records, handoff summaries; read when continuing work or investigating history.

A fifth candidate location ( knowledge-inbox.md) holds unconfirmed observations (code inferences, colleague tips, unresolved anomalies) until verified and promoted to formal docs. The author emphasizes that simply creating a memory.md file does not make tools understand its purpose — the team must explicitly instruct the agent to read these files via commands or tasks.

2. Build Project Memory from Existing Documentation

Start by inventorying existing README, API specs, deployment guides, test scripts, and CI. Keep current docs in place and add an index. For Codex-style tools, use AGENTS.md as the project entry point with its defined directory scope and priority rules. A gradual structure can evolve:

AGENTS.md          # Project entry & stable conventions
docs/
  README.md        # Documentation index
  project-map.md   # Module & code entry points
  knowledge-inbox.md # Pending observations
  business/order.md # Current order rules & applicable versions
  decisions/       # Key choices & reasons
  engineering/
    development.md # Development standards
    commands.md    # Environment & command registry
    verification.md # Test processes
    acceptance.md  # Business acceptance processes
  operations/
    release.md     # Release & recovery processes
    pitfalls.md    # Exceptions & temporary fallbacks
  changes/REQ-20261030-001/
    spec.md        # This requirement
    progress.md    # Phase progress
    verification.md # Actual check results
    acceptance.md  # Business acceptance results
    release.md     # This release record
    doc-impact.md  # Affected original doc sections
    handoff.md     # Cross-session handoff
.agents/skills/
  legacy-change/SKILL.md
  verify-change/SKILL.md
  prepare-release/SKILL.md
  sync-project-docs/SKILL.md

Begin with just the project entry, doc index, dev/test guides, and a record for the current requirement. Reusable processes gradually become skills; handoff materials are added when sessions or people change. A typo fix needs minimal records; a feature touching permissions, queries, and async export warrants full documentation.

3. Let the Agent Create the First Version of Project Memory

The first memory version should be assembled by the agent from actual project evidence. Start by checking the current branch, commits, uncommitted changes, then locate build entry points, environment config, and key business flows. Verify that documented claims (e.g., "export reuses list query") match the actual code path.

Example prompt to the agent:

Please read-only inventory this project's existing instructions, docs, build scripts, and CI.
Around order query & export, locate pages, APIs, permissions, SQL, and async tasks.

Produce a project memory update plan:
- Which info has formal docs, which needs correction, which is missing.
- Attach code, config, test, or business confirmation for each key conclusion.
- Clearly label facts, inferences, and open questions.

Then maintain relevant docs within current task scope, preserving existing standards.
Unconfirmed items go to pending verification; do not generate test or release success records.

Store information that will change future judgments: e.g., where channel field values originate, why a legacy compatibility branch exists, which environments tests depend on. Each memory entry should include: topic, conclusion, evidence (requirement confirmation, implementation function, test cases), applicable version, confirmation status (candidate/confirmed/superseded), last verified (date, code version, verifier), and pointer to the formal business doc section.

"Confirmed" must specify what was confirmed: code proves current runtime behavior, business confirmation states intended behavior, production records show deployed version. Conflicts among these three should be logged and resolved. Avoid vague statements like "channel filtering already supported"; instead record: "Implemented in commit X, test acceptance pending, not yet in production." Update records when status changes.

Define update triggers: confirmed new business meaning → update requirement & business chapter; verified command → update environment registry; solved recurring issue → add cause & fix; task paused → update handoff. Only save information that affects future decisions; avoid turning every search or tool output into long-term memory.

4. Write Development Conventions as Decision-Influencing Agreements

Derive conventions from recurring team problems: duplicate enums, missing data permissions, modifying list but not export. Document each with location of existing implementation. Example conventions:

Channel definition: Reuse existing dictionary/enum; see order module docs.

Null handling: Normalize optional params first, then validate non-null values.

Data permissions: Follow server-side confirmed data scope; do not expand via request params.

Query semantics: List, count, and export follow the same confirmed filter rules.

Change scope: Preserve unrelated local changes; avoid sneaking in dependency upgrades or large refactors.

Each convention should answer: where it applies, and why it exists. Distinguish scope: team-wide commit format and shared component usage go in repo standards; personal report preferences go in tool-specific personal config or uncommitted local notes. One-off requests stay in the current requirement; only promote to standards after confirmed long-term adoption.

Overly broad rules like "all APIs must retry" are insufficient. Query APIs, file uploads, order creation, and release tasks have different idempotency consequences — define trigger conditions, retry counts, and result verification per case.

The project entry file ( AGENTS.md) stays concise, pointing to relevant docs and processes:

# Project Working Conventions

- Doc entry: docs/README.md, read relevant parts per task.
- Dev standards: docs/engineering/development.md
- Env & commands: docs/engineering/commands.md
- Implement existing requirements: use legacy-change skill
- Verify changes: use verify-change skill
- Prepare release: use prepare-release skill
- After behavior changes: use sync-project-docs skill
- Update original formal docs for business changes; log affected chapters in requirement record.
- On pause/handoff: save necessary state; on resume, verify current code & environment.

Instruction files guide work; automated checks (build, test, static analysis) remain in scripts/CI; permission-controlled operations stay gated by existing auth mechanisms. Both layers must cooperate to enforce conventions in execution results.

5. Turn Repetitive Stages into Callable Skills

Skills capture reusable operational methods: taking on existing requirements, verifying a change, preparing a release, merging new rules into original docs. In Codex's repository skill layout, use .agents/skills/<skill-name>/SKILL.md with name, description, body, optional references/scripts. Tools match skills by description, then read content.

Simplified verify-change skill example:

---
name: verify-change
description: Verify specific code changes, execute checks per impact scope, record actual results.
---

Read relevant requirement, code diff, pre-change failure baseline, and project command registry.
Select build, test, API, or UI checks based on impact scope.

Execute actual checks; record code version, environment, working directory, command,
exit code, result, and evidence location. Re-run affected checks after fixes.

If environment missing, list specific gaps; continue independently doable work.
Record unexecuted, failed, blocked, and passed separately.
When business acceptance needed, organize cases & results per project acceptance process.

The skill orchestrates verification; actual commands stay in the project's command registry. Changing test entry points only requires updating the source, avoiding duplicated commands across skills that drift out of sync.

Four starter skills: legacy-change — Trigger: taking on or implementing an existing requirement. Output: scope, flow, progress, doc impact, handoff. verify-change — Trigger: verifying a specific modification. Output: check results, version, evidence, incomplete items. prepare-release — Trigger: preparing a candidate version for release. Output: artifacts, acceptance links, release & recovery plan. sync-project-docs — Trigger: confirmed business or API changes. Output: original doc updates, obsolete description handling, index maintenance.

Acceptance processes can be read by verification and release prep as needed; no separate skill per stage. Repeated methods go into skills; requirement-specific data and state stay in requirement records. Initially, explicitly ask the agent to use a skill, observe if it finds correct inputs, executes the flow, and leaves results. Adjust based on real issues. Overlapping skills and verbose instructions increase context load; official engineering guidance also stresses providing task-relevant guidance.

6. Keep a Record for Every Collaborative Requirement

For the new requirement "add channel filter to order list, sync support in export", first establish a requirement ID (or reuse existing ticket). Agent confirms current state from formal docs and source code, then writes target behavior into spec.md. Must clarify at minimum:

Omitting or passing blank channel preserves original query behavior.

Current filter accepts WEB, AGENT; unknown non-empty codes return parameter error.

Historical nulls and disabled codes remain; new filter does not rewrite history.

List, count, and export use identical filter conditions; retain original data permissions.

Switching conditions returns to page 1; export uses last committed effective conditions.

If ambiguity exists (e.g., whether export uses editing-time or last-query conditions), confirm here while agent continues preparatory work not dependent on the answer.

Use a single progress table per requirement, but each phase keeps its own status:

Rules & Implementation: pending confirmation / in progress / done — evidence: requirement, code, diffs.

Change Verification: not executed / passed / failed / blocked — evidence: actual commands, environment, output.

Business Acceptance: pending / passed / rejected — evidence: cases, actual results, sign-off.

Doc Sync: pending / synced / N/A — evidence: original text locations & reasons.

Release: not executed / in progress / result unknown / done / rolled back — evidence: platform records, artifacts, env verification.

This prevents a blanket "done" from obscuring incomplete phases. Code can be finished while testing continues; release materials can be ready while missing items are clearly identified. Processes continue work without re-asking for every step; existing authorizations apply within their scope; only genuine missing business info or permissions are confirmed ad hoc.

7. Test Processes Need Both Commands and Expected Results

"Please test thoroughly" is insufficient for stable execution in unfamiliar projects. Maintain a command registry: run location, tool versions, prerequisites, actual command, coverage scope, artifact location. Example: verified Maven multi-module project uses ./mvnw -pl order-service -am test for order tests; frontend build uses existing npm run build. Commands must match real modules/scripts — copying names without verification is inadequate.

Record for each execution:

Check object: requirement ID, code commit, necessary uncommitted diff markers.

Execution environment: working directory, tool & DB versions, config source.

Execution content: actual command, case scope, start/end time.

Execution result: exit code, passed items, failed items, unexecuted items.

Evidence location: logs, test reports, API results, UI screenshots.

Follow-up actions: fix, re-verify, or hand off to whom.

Commit hash alone may not suffice: same HEAD with different local uncommitted code means different test subject. Retain relevant diffs and necessary untracked file markers; artifact tests should record specific artifact digests.

For query functions, establish independent expectations with fixed data. Example: test user has only Org A permissions; dataset includes:

Org A normal WEB orders: 1001, 1004

Org A normal AGENT orders: 1002

Org A historical null/empty/LEGACY orders: 1003, 1006, 1008

Org B WEB orders: 1005

Org A deleted WEB orders: 1007

Assuming other conditions met: no filter → 6 records; filter WEB → 1001, 1004 (count 2); export also only those two. Set page size to 1 to verify pagination and total count. These numbers are expected results; actual list, count, and export must be run to fill in measured results. Mocking Mapper to return two rows does not prove actual SQL and permission conditions are correct.

When test environment unavailable, log missing dependencies, affected cases, and re-verification plan. Pre-existing failures must keep name and cause to distinguish new issues. Scripts must preserve real exit codes; skipping tests or swallowing exceptions to fake success is unacceptable.

Business acceptance verifies actual usage per requirement items: after switching channel on later page, does it return to page 1? After clearing filter, do historical orders reappear? Does export file match expectation? Record acceptance environment, version, executor, evidence; business sign-off by actual responsible person.

Agent can organize and execute authorized verification; acceptance records must reflect real execution and confirmation.

8. Release Skills Must Link Specific Versions and Rollback Procedures

Release prep must answer: what is being released, what has been verified, and where to roll back if issues arise. prepare-release reads requirement, test, acceptance, and doc-impact records, checks they correspond to the current candidate version, then forms a release plan:

Target environment: where this release goes.

Candidate artifacts: frontend/backend versions, build numbers, digests.

Verification & acceptance: linked records, coverage, leftovers.

Change content: code, config, DB schema or data.

Execution plan: steps, order, executors, existing authorization scope.

Observation points: health status, key business results, errors, latency.

Rollback procedure: trigger conditions, rollback version, post-rollback checks.

Current status: preparing / ready / missing specific materials.

Channel filter adds an optional parameter; typically update backward-compatible backend first, then frontend. Actual order must be verified against current implementation.

Rollback must consider frontend-backend coupling. New frontend still sends channel param; if backend rolls back to version without that param, users may select a channel but backend does not filter. Rollback plan must include frontend coordination or disabling the new entry point.

If DB changes involved, separately document compatibility and rollback paths. Rolling back app version does not automatically revert data changes.

When release materials are ready, only record "prepared". After actual execution, write platform operation ID, deployed version, artifact digest, and business check results. Test pass and production health are evidenced separately.

An important state is "result unknown": e.g., release operation sent, client times out waiting for confirmation. First check platform operation records and target environment to confirm if it took effect, then decide next steps. Repeatedly clicking release may trigger a second external operation.

Actions needing retry must pre-define how to persist operation ID or idempotency key, and how to query actual outcome. A single "auto-retry on failure" sentence cannot cover this scenario.

9. Document Exceptions and Fallbacks to Executable Detail

Legacy systems hold critical tribal knowledge: special config sources for an environment, tasks that must not be re-run arbitrarily, compensating actions requiring external state verification first. Log these with applicability scope and exit conditions.

Example fallback entry for lost release confirmation:

ID: FALLBACK-001
Scope: Platform accepted release operation, client timed out, result unknown.
Identification: operation ID, client error, platform records, target artifact digest.
Immediate action: pause duplicate submissions; query actual status first.
Continuation condition: if completed, supplement result; only assess retry after confirming not executed.
Unconfirmable: log unknown state; escalate to person with platform query permission.
Recovery verification: verify deployed version, health status, required business cases.
Owner: actual maintainer or role.
Review condition: first platform onboarding, platform mechanism or deployment method changes.
Exit condition: adjust this entry after reliable result query or idempotency mechanism lands.

Other exceptions follow the same structure: problem, trigger, symptoms, evidence, cause confirmation status, temporary measures, impact, recovery steps, owner, review schedule.

"Export timeout once" is just an observation. Only after root cause analysis (e.g., export task created successfully but response lost) can a targeted handling method for that flow be formed. A fault in one environment does not automatically become a rule for all environments.

Skipped checks especially need logging: what was skipped, why, which conclusions are affected, who will re-verify, when. Skipped items remain unverified until actual re-verification completes.

When saving evidence, record necessary log locations, request correlation IDs, and sanitized results. Credentials obtained via existing management mechanisms; project memory stores only access entry points and variable names.

10. Merge New Requirements into Original Document Bodies

This is the key to long-term effectiveness. If every development adds a "channel filter completion note" while the original order doc still describes old behavior, conflicting materials accumulate within months. The agent's next lookup may hit any of them, directly affecting implementation.

Maintain a doc-impact.md from requirement start, mapping business changes to specific sections of original docs:

New channel param → Order business doc list & export chapters → Update params, default behavior, export scope.

Historical value handling → Channel field & historical compatibility chapter → Add null, disabled value, display conventions.

New tests → Existing test guide & command registry → Add actual execution entry points and case locations.

Release compatibility → Release & recovery process → Add frontend-backend coordinated rollback requirements.

Key design trade-offs → Corresponding decision records → Preserve rationale, impact, alternative relations.

After implementation, sync-project-docs executes updates per this table.

First, verify changes against requirement and code. If implementation diverges from confirmed requirement, fix implementation or confirm target behavior first — avoid writing program defects directly as new rules.

Then modify original body. Original text might be:

Order list queries by status and time range; export uses same business conditions.

New text becomes:

Order list supports status, time range, and optional channelCode filter.
channelCode missing or blank imposes no channel restriction; non-empty values validated against valid channels.
List, count, and export use identical conditions; export not limited by current page.
Historical nulls and disabled channels retained when not filtered; display rules see channel field chapter.

Also mark applicable version. Capability implemented in a code version but not yet deployed to production can be noted as "implemented, pending release" in that version's notes; production status continues to reference actual release records. Rules still applying to old versions remain in explicit compatibility notes.

Then handle sources and conflicts. If API docs are generated from OpenAPI, comments, or other spec files, modify the source and regenerate per project process. Use code search and doc search to find old params, old defaults, and "channel filter not supported" descriptions; decide what to replace, move to history, or keep.

Finally verify linked entry points. Check links, doc index, test guide, acceptance criteria, release config for consistency. Decision records preserve why; new decisions mark replacement relations; current rules maintained in formal body.

After completion, in doc-impact record write modification locations, applicable versions, code or test evidence. Items not needing doc changes also logged with reason (e.g., pure formatting adjustment without business behavior change).

Thus one requirement yields two artifacts: current description in original docs, and change history in requirement record. Next time, read current description first; trace reasons via history.

Code and docs should enter same commit or linked review to reduce drift. After actual deployment, supplement running version and observations.

CI can check local links, required fields, existence of doc-impact record, and timely generated doc updates. Whether body correctly expresses business semantics still requires review against implementation and acceptance criteria. File changes alone do not prove docs are synced.

11. Enable Continuation Across Sessions

Project memory stores stable knowledge; handoff summaries help resume current tasks.

When a session ends, task pauses, or someone else takes over, update handoff.md with:

Goal & requirement ID.

Current branch, code commit, relevant local changes & necessary diff markers.

What's done, which results verifiable where.

What's in progress, specific problems encountered.

Next directly executable steps.

Pending confirmations, incomplete checks or release actions.

External operations issued and whether results are clear.

Summary links to formal docs and original records, avoiding duplicate copying of business rules.

New session starts by reading handoff, then verifying current Git status, relevant files, and necessary external environments. Branch may have updated; issues may have been fixed by colleagues; test env may have recovered. Last summary helps find entry points; continued execution still bases on current state.

Daily habits worth keeping:

After environment recovery, update registry with correct commands & versions; note actual config if temporarily switched.

After a failed attempt, record key operations, observations, conclusions; keep raw long logs separately.

When discovering hidden business rules, log source first; update formal chapter after confirmation.

New fallbacks written with clear trigger & exit conditions; old fallbacks marked retired or replaced after root cause fixed.

After code/config changes, re-evaluate which tests, acceptances, release materials still apply; preserve original records' version ranges.

These habits gradually reduce repeated explanations and let newcomers know which facts are reliable and which work remains incomplete.

12. Start a Trial Run Today with a Small Requirement

Pick a reproducible, well-scoped, easily verifiable task. First get the environment running, record existing failures, then let the agent organize necessary project knowledge along this task.

Walk through requirement, implementation, test, acceptance, doc sync, and release prep end-to-end. Integrate existing platform/team processes directly via their entry points. After trial, only supplement genuinely missing docs and skills.

Ready-to-use starter prompt:

Using this legacy project's existing instructions, docs, scripts, and CI, establish project memory and delivery records matching current requirement scale.

Current requirement: add channel filter to order list, export sync support.

First verify current workspace, run baseline, and relevant business flows. Save stable conventions, current business rules, pending observations, and this task status in appropriate existing locations; add necessary indexes.

Within existing authorization, advance implementation and verification; save real execution results, versions, acceptance, and release prep status. Log exceptions and temporary fallbacks with triggers, impact, and exit conditions.

On completion, update original formal chapters per doc-impact checklist; handle obsolete descriptions and generated doc sources; mark applicable versions & deployment status. If handoff needed, leave current progress, evidence entry points, and next steps.

When key info missing, specify exact gaps; continue independent work. Unexecuted tests, unconfirmed acceptances, and non-occurred releases logged truthfully.

This approach has reference engineering practices. OpenAI's Agents SDK repo maintenance intro combines project instructions, repo skills, and CI to cover verification, doc sync, and release prep for repetitive work.

Returning to the initial order requirement: after one development cycle, channel semantics enter order docs, verification methods enter test process, compatibility choices stay in decision records, release results have corresponding versions, exception handling has queryable logs.

Next time someone says "add another channel", the agent can continue along these entry points, and developers can inspect what it relied on and what was actually completed.

With each completed requirement, let code, project knowledge, and operational processes all move forward one step together.

Supplementary materials provide the article's directory, four skills, and order requirement record template. When integrating into real repos, merge per existing standards and replace teaching examples with actual code evidence and execution results.