에이전트 메모리

AI는 코드와 대화를 잘 읽지만, 세션이 끝나면 “이 워크벤치에서 무엇을 할 수 있는지”를 잊습니다. 그래서 이미 한 번 성공한 일(배포·빌드·DB 접속)을 다음 세션에서 “자격증명이 없어 못 한다”고 다시 오판하곤 합니다.

에이전트 메모리는 AI가 검증한 사실을 정확 매칭 서랍에 저장하고 다음 세션에 자동으로 꺼내 쓰게 합니다. RAG(의미 근사 검색)와 경쟁하지 않고 역할을 분담합니다 — 사실 판단은 서랍, 근사 탐색은 도서관.

왜 필요한가 — 실제 사고에서 출발

Blyck 배포는 이 PC에서 직접 가능했고(aws CLI 구성됨, 직접 배포 이력 있음) 절차도 문서화돼 있었습니다. 그런데 에이전트는 매 세션 “자격증명이 없어 배포 못 한다”고 반복 오판했습니다. 원인은 코드 주석만 보고 “별도 단계 = 내가 못 함”으로 추론한 것입니다.

진단해보니 약한 고리는 회상이 아니라 저장이었습니다.

단계	상태	근거
회상(recall)	정상	저장만 됐다면 분명히 읽혔을 것
저장(capture)	실패	”이 PC 배포 가능”이 한 번도 영속 저장된 적 없음

즉 기억을 못 하는 게 아니라 기억할 항목 자체를 안 만든 것. 행동(s3 cp 1회)은 휘발성처럼 보이지만, 그것이 증명하는 능력(“배포 가능”)은 영속·재사용 사실입니다. 이 구분 실패가 사각지대였습니다.

핵심 원칙

메모리는 RAG 수프에 넣지 않는다. 사실/능력 기억은 의미 근사 검색이 아니라 정확 매칭으로 꺼냅니다.
저장은 자각에 의존하지 않는다. 성공한 행동을 자동으로 능력 후보로 승급합니다(단, 승인 게이트).
회상은 자동 주입한다. 관련 기억은 호출 없이 컨텍스트에 들어갑니다.
불가능 단정 전 검증. “못 한다” 말하기 전 메모리 조회 + 싼 프로브로 확인합니다.

비유 — 도서관과 책상 서랍

📚 도서관 검색 (RAG): 코드·대화·로그를 다 쌓아두고 “비슷한 거 찾기”. 양이 많고 근사라 가비지가 섞입니다. → “예전 비슷한 코드 어디 있었지?”용.
🗂️ 책상 위 메모 서랍 (메모리): 검증된 핵심 사실 몇 개만 깔끔히. 정확하고 항상 보입니다. → “이 PC 배포 가능”, “PROD DB 건드리지 말 것”용.

RAG와 메모리는 경쟁이 아니라 분담입니다. 사실 판단은 서랍(1순위), 근사 탐색은 도서관(보조).

타입드 정확 서랍

기억은 workspace.sqlite의 전용 테이블에 타입드 레코드로 저장됩니다.

필드	설명
`type`	`capability` · `decision` · `rule` · `procedure` · `fact`
`scope`	`workspace`(기본) · `global`
`key`	정확 매칭 식별자 (예: `deploy:blyck`)
`body`	사람이 읽는 사실 본문
`confidence`	0~1 (검증됨=1.0)
`proof`	근거 (예: “aws sts 통과; s3 cp 성공”)
`status`	`active` · `stale` · `retired`

저장(capture) — 약한 고리를 3중으로

정착 메모리 저장 제안 카드 — 저장/무시

방식	트리거	가비지 차단
명시적	`memory_write(key, body, type, scope)` MCP 도구	의도적 호출만
자동 승급	성공 이벤트(배포·빌드·인증·DB 접속)를 활동 로그에서 감지 → 후보 생성	승인 게이트
반성 패스	채팅 종료/마일스톤 시 세션 요약 → “배운 영속 사실?” 후보 추출	승인 게이트

세 경로 모두 승인 후에만 서랍에 들어가므로 RAG식 자동 흡입 노이즈가 없습니다.

자동 승급 분류기가 능력 후보로 올리는 성공 이벤트 예:

외부 인증/배포 성공(aws … 성공, gh auth, deploy/publish) → capability
빌드/패키징 성공(npm run dist, 테스트 통과) → capability/procedure
DB/SSH 접속 성공(자격증명 검증) → capability
사용자가 명령형으로 준 규칙(“PROD 건드리지 마”) → rule
너무 사소하거나 일회성(단순 파일 읽기 등)은 제외 — 승인 피로 방지

회상(recall) — 자동 주입

매 턴 컨텍스트를 조립할 때 메모리 회수 단계가 끼어듭니다.

현재 쿼리·활성 패널·프로젝트로 key 정확 매칭 + 가벼운 의미 매칭.
상위 k개 active 기억을 시스템 프롬프트에 자동 주입(별도 호출 불필요).
recency·importance 가중 + decay → 오래 안 쓰인 기억은 stale→retired.

AI 도구 (MCP)

memory_write 직접 저장 결과

도구	권한	역할
`memory_write(key, body, type, scope)`	확인	사실을 서랍에 명시 저장(같은 key 덮어쓰기)
`memory_read(key?/query?)`	읽기(자동)	key 정확 매칭 또는 가벼운 의미 매칭으로 기억 조회

대부분의 회상은 자동 주입으로 처리되므로 memory_read를 일일이 호출할 필요는 없습니다. 자동 주입이 놓친 항목을 보강 조회할 때 씁니다.

decay와 정리

서랍이 비대해지지 않도록 last_seen 기반으로 오래 안 쓰인 기억을 정리합니다.

capability · rule · procedure 는 자동 소멸 면제 — 위 §사고 재발 방지가 목적입니다. 한 번 검증된 능력은 안 쓰여도 사라지지 않습니다.
decision · fact 만 90일→stale, 180일→retired.
명시 조회 시 stale→active 부활.

전체 흐름 — 오늘 사례

[저장] 첫 배포 성공 → 활동 로그 "s3 cp blyck-releases 성공"
   → 승급 분류기 감지 → 후보 {capability, key:"deploy:blyck",
      body:"이 PC 직접 배포 가능: npm run dist → s3 cp → cloudfront invalidate",
      proof:"aws sts 통과; s3 cp 성공"} → [승인] → 서랍에 박힘

[회상] 다음 세션 "배포해줘" → 컨텍스트 조립이 "deploy:blyck" 자동 주입
   → "자격증명 없음" 유추 자체가 불가능 → 사고 재발 0

Claude 파일 메모리와의 관계

이 기능은 Claude Code의 파일 메모리(MEMORY.md + *.md, 매 세션 자동 로드)의 정확·자동회상을 그대로 빌려오되, 그 약점을 보완합니다.

항목	Claude 파일 메모리	Blyck 정착 서랍
저장 위치	마크다운 파일	workspace.sqlite 테이블
저장 트리거	에이전트 판단(수동)	수동 + 행동 자동 승급 + 반성 패스
자동 저장	✗	✓ (성공 이벤트 승급)
가비지	적음	거의 0 (UNIQUE key + 승인)
중복 방지	사람이 인덱스 관리	`UNIQUE(scope, key)` 자동
decay/정리	수동	`last_seen` 기반 stale/retire
도메인 인지	범용	Blyck 활동(배포·DB·SSH) 특화

결정적 차이는 자동 저장입니다. 위 사고는 Claude 파일 메모리가 켜진 상태에서 났습니다 — 회상은 멀쩡했고 약한 고리는 “저장이 판단 의존”이라는 점이었습니다. Blyck은 활동 로그라는 행동 기록이 있어 성공 이벤트를 능력 후보로 자동 승급할 수 있고, 이것이 파일 메모리만으로는 구조적으로 불가능한 부분입니다.

보안

교차채팅 기억은 기본 scope=workspace + 민감정보 필터로, 전역 세션 비이전·읽기 전용 원칙과 충돌하지 않습니다.
시크릿은 메모리 본문에 저장하지 않습니다(OS 암호화 저장소 + 자동 마스킹은 별도 경로).

FAQ

Q. RAG가 있는데 메모리가 왜 또 필요한가요? → RAG는 의미 근사라 사실 판단에 가비지가 섞입니다. “이 PC 배포 가능” 같은 검증된 사실은 정확 매칭 서랍에서 1:1로 꺼내야 안전합니다. 둘은 분담합니다.

Q. 내가 일일이 “기억해”라고 해야 하나요? → 아니요. memory_write로 명시 저장도 되지만, 성공 이벤트는 자동 승급 후보로 떠서 승인만 하면 됩니다. 채팅 종료 시 반성 패스가 규칙도 자동 추출합니다.

Q. 잘못 저장된 기억이 계속 따라다니지 않나요? → 같은 key는 덮어써지고, decision/fact는 decay로 정리됩니다. 잘못된 능력 기억은 memory_write로 갱신하거나 retire하면 됩니다.

Q. 검증된 능력이 안 쓰여서 사라지면 또 사고 나지 않나요? → 그래서 capability·rule·procedure는 자동 소멸 면제입니다. 한 번 검증된 능력은 안 쓰여도 서랍에 남습니다.