Memorya ng AI agent sa pagitan ng mga session: progress file, decision log, git, at init script

Bakit walang naaalala ang agent

Hindi nag-iimbak ng estado ang modelo sa pagitan ng mga pagtakbo. Lahat ng "alam" ng agent tungkol sa iyong gawain ay nasa context window ng kasalukuyang session: mga file na nabasa, output ng mga utos, at ang usapan sa iyo. Nagsara ang session o umapaw ang context, at ang bagong session ay nagsisimula sa wala at nakikita lamang ang nakasulat sa disk.

Kapaki-pakinabang na modelo: isang magaling na inhinyero na tuwing umaga ay pumapasok na burado ang memorya. Mabilis niyang mauunawaan ang code, pero hindi niya maaalala kung aling arkitektura ang pinili kahapon, bakit tinanggihan ang iba, at kung nasa anong estado ang mga test. Kung walang tala, gugugol siya ng labinlima hanggang dalawampung minuto sa pagsisiyasat, at malamang na muling gagawin ang bagay na sinadya ninyong tanggihan.

Kaya ang memorya ng AI agent ay hindi katangian ng modelo, kundi bahagi ng harness: isang hanay ng mga file at tuntunin na ikaw mismo ang nagdidisenyo. Magandang balita na hindi kailangan ng vector database o espesyal na serbisyo. Sapat na ang ilang Markdown file, git, at disiplina.

Bakit hindi nalulutas ng malaking context window ang problema

Parang sapat na maghintay ng modelong may mas malaking window. Pero pupunuin ng isang komplikadong gawain ang anumang window: binabasa ng agent ang codebase, nag-iipon ng kasaysayan ng desisyon, tumatanggap ng madaldal na output ng test, at pinananatili ang buong usapan. Lumalaki ang pangangailangan kasabay ng window. Problema ito ng arkitektura, hindi ng laki.

May pangalawang epekto. Malapit sa hangganan ng window, maraming modelo ang nagmamadaling tapusin: nilalaktawan ang beripikasyon at pinipili ang simpleng solusyon sa halip na tama. Inilalarawan ito ng Anthropic bilang obserbasyon sa sarili nilang mga modelo, at nag-iiba ang lakas ng epekto sa bawat modelo. Ang mahabang session sa dulo ng context ay hindi lamang panganib na mawala ang impormasyon, kundi panganib din na bumaba ang kalidad ng gawa.

Compaction: ano ang naiingatan at ano ang nawawala

Ang compaction ay pagpapaikli ng maagang bahagi ng usapan sa maikling buod para magkaroon ng puwang sa parehong session. Sa Claude Code, ginagawa ito ng utos na /compact, at awtomatiko rin itong nangyayari kapag malapit na sa limitasyon. Ang /clear, sa kabilang banda, ay binubura ang kasaysayan at nagsisimula muli ang usapan.

Ang problema sa compaction, karaniwang naiingatan ng buod ang "ano" at nawawala ang "bakit." Nananatili sa mga file ang tapos nang code, pero ang pangangatwiran (bakit variant B ang pinili, bakit hindi kinuha ang library, bakit sinadyang laktawan ang optimisasyon) ay napipiga sa ilang salita o nawawala. Ang susunod na hakbang ng agent ay "pinapaganda" ang sadyang desisyon, dahil wala na itong nakikitang dahilan.

Praktikal na tuntunin na walang kumplikadong sukatan: kapag umabot na sa humigit-kumulang 60% ng window ang gawain, itigil ang pagsusulat ng code at ihanda ang paglilipat ng trabaho. Kung 40% pa lang ang nagamit at malapit nang matapos ang gawain, sapat na ang compaction.

Apat na artifact na bumubuo sa memorya ng agent

Sa halip na umasa sa memorya ng modelo, gumawa ng logbook. May apat na bahagi, at may kanya-kanyang tungkulin ang bawat isa.

1. PROGRESS.md — nasaan na tayo.
2. DECISIONS.md — bakit ginawa ito at hindi ang iba.
3. Git commit — libreng checkpoint ng estado.
4. Protocol ng paglipat sa AGENTS.md — ano ang gagawin pagdating at pag-alis.

PROGRESS.md: file ng progreso

Isang tanong lang ang sinasagot nito: sa anong estado ang proyekto ngayon mismo. Binabasa ito ng agent una sa simula ng session at ina-update huli bago umalis. Maikli ang file, at muling isinusulat sa halip na walang hanggang dinadagdagan: nasa git ang kasaysayan.

# PROGRESS.md

## Kasalukuyang layunin
Paghahanap sa catalog ng produkto (feature search-01)

## Estado
- HEAD: 4f2a9c1
- make check: berde, 142/142 na test
- Tapos na: index sa PostgreSQL (tsvector), endpoint na GET /search
- Na-verify: unit test + manwal na curl sa 3 query

## Mga hadlang
- Walang datos ng morpolohiya para sa wikang Kazakh — hinihintay ang desisyon

## Susunod na hakbang
Magdagdag ng pagination sa GET /search, pamantayan: test para sa ikalawang pahina

Pansinin ang apat na field na sapat na para sa paglilipat ng trabaho: hash ng commit, bahagi ng pumapasang test, mga hadlang, at susunod na hakbang. Kung hindi tiyak na maipagpapatuloy ng bagong session ang gawain mula sa file na ito, kulang ang field sa template.

DECISIONS.md: log ng mga desisyon

Dito nakaimbak ang "bakit" na nawawala sa compaction. Format ng tala: desisyon, dahilan, ano ang tinanggihan at bakit, at mga limitasyon.

## 2026-03-14 — Cache ng mga setting ng user sa Redis
- Desisyon: Redis, TTL 5 minuto, aktibong pag-invalidate kapag may isinulat.
- Dahilan: binabasa sa bawat request, napakaliit ng datos.
- Tinanggihan: materialized view sa PostgreSQL — madalas magbago, hindi sulit ang maintenance.
- Limitasyon: huwag i-cache ang mga setting ng bayad.

Ang pinakamahalagang linya dito ay ang "Tinanggihan." Ito ang pumipigil sa susunod na session na "i-optimize" pabalik ang desisyon tungo sa variant na napag-usapan na at itinapon. Hindi tulad ng file ng progreso, lumalaki lamang ang decision log: hindi binubura ang mga lumang tala, minamarkahan lang ang mga ito bilang napalitan ng bago.

Kasaysayan ng git bilang mga checkpoint

Ang mga commit ay mga bersiyonadong snapshot ng estado na bahagi na ng trabaho. Mababasa ng agent ang git log at git diff at mabubuo ang nangyari. Para gumana ang kasaysayan bilang memorya, dapat ipaliwanag ng mensahe ng commit ang layunin, hindi ulitin ang diff.

# masama
git commit -m "update search.py"

# mabuti
git commit -m "search: tsvector index sa halip na LIKE

LIKE '%q%' ay hindi gumagamit ng index, sa 200k na produkto ang query ay 1.8 s.
Hindi pa tapos ang pagination, tingnan ang PROGRESS.md."

Ang maliit at madalas na commit pagkatapos ng bawat berdeng test run ay nagbibigay din ng punto ng pagbabalik. Kung napunta sa maling direksiyon ang session, mas madaling bumalik sa huling na-verify na estado kaysa kalasin ang kalahating-tapos na mga pagbabago.

Protocol ng paglipat sa AGENTS.md

Walang saysay ang mga file ng estado kung hindi nila alam ng agent. Kaya sa input file ng mga tagubilin (AGENTS.md o CLAUDE.md) isinusulat ang maikling protocol: ano ang gagawin pagdating at pag-alis.

## Pagdating sa shift
1. Basahin ang PROGRESS.md at DECISIONS.md.
2. Hanapin ang aktibong gawain sa .agent/feature_list.json.
3. Patakbuhin ang make check — tiyaking pare-pareho ang repositoryo.
4. Ipagpatuloy mula sa "Susunod na hakbang," nang hindi muling binubuksan ang mga naresolba na.

## Pag-alis sa shift
1. Patakbuhin ang make check, i-commit ang berdeng estado.
2. I-update ang PROGRESS.md: HEAD, mga test, mga hadlang, susunod na hakbang.
3. Idagdag ang mga bagong desisyon sa DECISIONS.md.
4. Huwag mag-iwan ng kalahating-tapos sa working tree.

Mas mabuting panatilihing maikli ang protocol: ilang linya lamang sa input file, hindi hiwalay na mahabang dokumento.

Init script: paano pabilisin ang simula ng session

Para hindi na manu-manong buuin ng agent ang larawan, bigyan ito ng isang script na sumusuri sa kapaligiran at nagpi-print ng estado. Dapat idempotent ang script (maaaring patakbuhin nang maraming beses) at magtapos sa malinaw na mensahe ng pagiging handa.

#!/usr/bin/env bash
set -euo pipefail

echo "== 1. Kapaligiran =="
command -v uv >/dev/null || { echo "FAIL: hindi naka-install ang uv"; exit 1; }
uv sync --frozen

echo "== 2. Repositoryo =="
if [ -n "$(git status --porcelain)" ]; then
  echo "WARN: marumi ang working tree"
else
  echo "OK: malinis"
fi
echo "HEAD: $(git log -1 --oneline)"

echo "== 3. Pagsusuri =="
make check

echo "== 4. Estado =="
cat PROGRESS.md

echo "Handa nang magtrabaho"

Sa protocol ng pagdating, sapat na ang isang linya: "patakbuhin ang scripts/init.sh." Sa Claude Code, maaaring i-automate ang pagpapatakbo gamit ang hook sa pagsisimula ng session (event na SessionStart), pero kahit walang hook, susundin ng agent ang script ayon sa tagubilin sa file.

Ano ang ilalagay sa memorya ng agent, at ano ang hindi

Ang pangunahing pagkakamali ay gawing basurahan ang memorya. Bawat linyang binabasa ng agent sa simula ay umuukupa ng puwang sa context, at ang labis ay nagpapalabo sa mahalaga.

Paghiwalayin din ayon sa tagal ng buhay. Bihirang magbago ang mga tuntunin ng proyekto at naaapektuhan nito ang lahat ng gawain: sa input file ng mga tagubilin dapat ito. Madalas magbago ang estado kada session: sa file ng progreso ito dapat. Kapag pinaghalo ang dalawa, mabilis lumaki ang input file sa mga lumang tala.

Unang session: ang initialization bilang hiwalay na yugto

Hindi makatutulong ang memorya sa pagitan ng mga session kung naligaw ang unang session. Karaniwang sitwasyon: sa malinis na repositoryo, isinulat mo ang "idagdag ang paghahanap," at pagkalipas ng kalahating oras, lumalabas na mali ang pagkakaayos ng test framework at hindi tama ang format ng migration. Nandoon na ang paghahanap, pero sira ang pundasyon.

Ang dahilan: magkaiba angina-optimize ng implementasyon at ng initialization. Ang una ay ang bilang ng natapos na feature sa session na ito; ang ikalawa ay ang bilis at pagiging maaasahan ng lahat ng susunod na session. Hilig ng agent ang nakikitang resulta, ibig sabihin ang code. Kaya ihiwalay ang initialization sa sariling session na may malinaw na pamantayan ng pagkatapos na may apat na kondisyon.

• Tumakbo: gumagana ang make setup at make dev mula sa malinis na clone.
• Nagse-suri ng sarili: may make test at kahit isang tunay na test na pumapasa.
• Nakikita ang progreso: umiiral at nababasa ang file ng estado.
• Kayang ipagpatuloy ang gawain: may listahan ng gawain na may pamantayan ng pagtanggap.

Kung madalas kang magsimula ng bagong proyekto, gumawa ng template ng repositoryo: Makefile, test framework, skeleton ng AGENTS.md, folder na .agent/, scripts/init.sh, linter, at CI. Sa ganoon, ang initialization ay magiging tungkol na lang sa partikular na proyekto.

Paano malalaman na gumagana ang memorya

Ang pinakatapat na sukatan ay ang oras mula sa pagsisimula ng bagong session hanggang sa unang makabuluhang pagbabago sa code. Kung walang artifact, karaniwang labinlima hanggang dalawampung minutong pagsisiyasat ito; kung maayos ang paglilipat ng trabaho, dalawa hanggang tatlong minuto. Sukatin nang minsan bago at pagkatapos, at makikita kung sulit ang disiplina.

Ang ikalawang paraan ay ang cold-start test. Magbukas ng bagong session, i-type ang "ituloy," at magtanong ng limang bagay: ano ang kasalukuyang layunin, nasa anong estado ang mga test, anong desisyon ang ginawa sa pangunahing paksa at bakit, ano ang humaharang, at ano ang susunod na hakbang. Kung sasagutin ng agent ang lahat ng lima batay sa mga file, nang walang hula, maayos ang pagkakagawa ng memorya. Bawat sagot na hindi sigurado ay isang nawawalang field sa template.

Mga karaniwang pagkakamali

• Lumalaki lamang ang file ng progreso. Pagkatapos ng isang buwan, daan-daang linya na ng kasaysayan. Isulat itong muli para sa kasalukuyang estado; nasa git ang kasaysayan.
• Walang linyang "tinanggihan." Ang log ng desisyon na walang tinanggihang variant ay hindi nagpoprotekta laban sa paulit-ulit na debate.
• Ina-update ng agent ang estado nang "sa tingin." Isulat kung paano na-verify: ang utos at resulta, hindi ang "gumagana nang maayos."
• Paglilipat ng trabaho sa dulo ng window. Malapit sa hangganan ng context, nagmamadali na ang agent; simulan ang handoff nang maaga, mga 60%.
• Maruming working tree sa paglabas. Ang kalahating-tapos na pagbabago na walang commit ay nalilito ang susunod na session.

Sa madaling sabi

Ang memorya ng AI agent sa pagitan ng mga session ay itinatayo sa mga file, hindi sa modelo: hawak ng PROGRESS.md ang kasalukuyang estado, ng DECISIONS.md ang mga dahilan at tinanggihang variant, ng mga git commit ang mga checkpoint na may paliwanag ng layunin, at ng protocol ng paglipat sa AGENTS.md ang nag-uutos na basahin at i-update ang lahat ng ito. Pinaiikli ng init script ang simula sa isang utos, at sinusuri ng cold-start test kung sapat ang mga tala. Ang logbook ng agent at ang bootstrap contract ay tinatalakay nang praktikal sa kurso ng harness engineering.