Memory Model Guide

RAGit은 메모리를 거대한 대화 원문 한 덩어리로 다루지 않습니다. 메모리를 용도별로 분리해서, 에이전트가 모든 원시 로그와 도구 출력, 과거 대화를 다시 프롬프트에 밀어 넣지 않고도 작업을 이어갈 수 있게 만듭니다.

The Problem

에이전트는 팀원이 프로젝트를 기억하듯이 자연스럽게 기억하지 못합니다. 세션 원문 로그는 “무슨 일이 있었는지”는 알려줄 수 있지만, “지금 무엇이 중요한지”를 바로 알려주기에는 적합하지 않습니다.

사용자 입장에서 진짜 필요한 질문은 더 단순합니다.

• 내가 하려던 일은 무엇이었는가?
• 아직 지켜야 할 제약은 무엇인가?
• 끝나지 않은 일은 무엇인가?
• 나중에도 다시 써야 할 지식은 무엇인가?

RAGit은 이 질문들에 직접 답하기 위해 메모리를 분리합니다. 과거 전체를 재생하는 대신, 다시 이어가기 위한 구조를 만드는 방식입니다.

The Mental Model

이 그림이 이 문서의 가장 빠른 정신 모델입니다. 위층은 임시 작업대, 가운데층은 지금 이어야 할 작업 상태, 아래층은 나중에도 다시 찾아야 할 프로젝트 지식입니다. 현재 MVP에서 RAGit은 특히 가운데와 아래층에 더 많은 무게를 둡니다.

메모리는 세 층으로 생각하면 이해하기 쉽습니다.

• Short-term memory는 작업대입니다. 세션 중간의 임시 메모, 거친 아이디어, 아직 정리되지 않은 관찰이 머무는 곳입니다.
• Working memory는 내일 다시 이어야 할 활성 상태입니다. 목표, 제약, 열린 루프, 다음 행동이 여기에 있어야 합니다.
• Long-term memory는 나중에도 다시 찾아야 할 프로젝트 지식입니다. 안정화된 결정, 용어, 계획이 여기에 들어갑니다.

현재 MVP에서 RAGit은 두 번째와 세 번째 층을 더 강하게 다룹니다. Working memory는 작업을 다시 이어가기 위한 것이고, long-term memory는 검증된 지식을 다시 찾기 위한 것입니다. Short-term memory는 개념적으로 존재하지만, 아직은 1급 검색 계층이 아니라 일시적인 작업대에 더 가깝습니다.

Why Two Places Exist

RAGit이 메모리를 두 곳에 두는 이유는, 프로젝트가 서로 다른 두 종류의 메모리 동작을 필요로 하기 때문입니다.

• .ragit/memory/**는 control plane입니다. 세션 wrap과 현재 working state를 저장합니다. 이 영역은 작업 재개에는 적합하지만, 일반 검색용 지식 베이스로 쓰기 위한 곳은 아닙니다.
• docs/memory/**는 searchable corpus입니다. 승격된 결정, 용어, 계획을 일반 문서처럼 저장하고 ingest와 snapshot 검색에 참여시킵니다.

이 분리는 신호 대 잡음비를 보호합니다. Working memory는 “지금 무엇이 살아 있는가”에 집중하고, long-term memory는 “나중에도 찾아야 할 것”에 집중합니다.

Command Flow

왼쪽 레인은 지금 작업을 다시 이어가기 위한 연속성이고, 오른쪽 레인은 나중에도 찾아야 할 지식입니다. memory recall은 이 둘 사이의 다리 역할을 하며, 현재 working state를 먼저 잡고 그 위에 관련 snapshot retrieval 결과를 얹습니다.

Exact path sketch

CONTROL PLANE (.ragit/memory/**)             SEARCHABLE CORPUS (docs/memory/**)
 
session work
   |
   +--> memory wrap ------> sessions/ + working/
   |
next-session goal
   |
   +--> memory recall <--- working/ + snapshot retrieval
   |                     --> recall packet
   |
stable knowledge
   |
   +--> memory promote --------------------> decisions/ glossary/ plans
                                              |
                                              +--> review + git commit
                                                       |
                                                       +--> ingest --> searchable snapshot hits

How Commands Map

• memory wrap은 나중에 다시 이어야 할 작업 상태를 기록합니다. 세션 히스토리를 저장하고 현재 working state를 갱신합니다.
• memory recall은 작업 재개에 필요한 최소 패킷을 복원합니다. 과거 전체를 재생하는 대신, 지금 활성화된 working state를 먼저 잡고 여기에 관련 있는 snapshot-scoped retrieval 결과를 보탭니다.
• memory promote는 안정화된 지식을 durable document로 바꿉니다. 세션의 세부사항이 프로젝트 기억으로 결정화되는 단계입니다. Promote는 새 worktree 파일을 ingest하지 않습니다. 문서를 검토하고 커밋한 뒤, 첫 snapshot이면 ragit ingest --all, trusted base가 있으면 지원되는 증분 ingest를 실행하십시오.

핵심은 이렇습니다. wrap은 연속성을 위한 것이고, recall은 복원을 위한 것이며, promote는 결정화를 위한 것입니다.

정확한 Snapshot Retrieval이 불가능할 때

memory recall만 degraded read를 허용합니다. 정확한 HEAD manifest 또는 canonical store를 사용할 수 없으면 recall은 snapshotSha: null, snapshot.status: unavailable을 반환하고 warnings에 operational error code를 포함합니다.

Degraded packet은 working memory와 reviewed artifact-derived content만 사용합니다. 순위는 keyword, authority, recency로 계산하며 embedding이나 canonical store를 호출하지 않습니다. 이 결과를 snapshot-backed durable knowledge로 해석하면 안 됩니다. query와 context pack은 이 경로를 사용하지 않고 strict failure를 반환합니다.

A Simple Example

하루가 끝날 때 auth migration 작업을 멈춘다고 가정해 보겠습니다.

memory wrap을 사용하면 현재 목표, snapshot 계약은 유지해야 한다는 제약, token refresh 관련 열린 루프, 내일의 다음 행동을 저장할 수 있습니다. 이 상태는 .ragit/memory/**에 남습니다.

다음 날 아침에는 모든 메모를 다시 읽고 싶지 않습니다. memory recall을 사용하면 현재 working state와 함께, 저장소 안의 관련 결정이나 계획 문서 같은 검색 결과를 묶어서 가져옵니다. 이렇게 만들어진 recall packet이 어디서부터 다시 시작해야 하는지를 알려줍니다.

이후 어떤 규칙이 충분히 안정화되면, 예를 들어 “refresh token 처리는 snapshot mutation 밖에 남겨야 한다” 같은 결론이 생기면 memory promote를 사용합니다. 그 규칙은 docs/memory/** 아래의 장기기억 문서가 되고, 검토·커밋·ingest 이후부터 일반 프로젝트 지식처럼 다시 검색할 수 있습니다.

Common Misunderstandings

왜 .ragit/memory/**를 바로 검색하지 않나요?

Working state는 자주 바뀌고, 살아 있는 작업을 다시 이어주기 위한 운영 상태이기 때문입니다. 자동으로 장기지식이 되어야 하는 영역이 아닙니다.

왜 promote를 wrap과 분리하나요?

모든 세션 메모가 장기기억이 될 필요는 없기 때문입니다. Promote는 searchable corpus를 깨끗하게 유지하기 위한 의도적인 승격 단계입니다.

언제 promote해야 하나요?

미래 세션이 원래 세션 히스토리를 다시 열지 않아도 그 내용을 찾아야 할 때 승격하면 됩니다. 현재 MVP 기준으로는 안정된 결정, 재사용할 용어, 나중에도 검색할 가치가 있는 계획이 대표적입니다.

working memory와 snapshot은 같은 것인가요?

아닙니다. Snapshot은 “이 커밋에서 무엇이 검색 가능한가?”에 답하고, working memory는 “지금 내가 무엇을 이어가고 있는가?”에 답합니다.

왜 working memory와 long-term memory를 둘 다 유지하나요?

두 계층이 복원하는 문제가 다르기 때문입니다. Working memory는 작업의 관성을 복원하고, long-term memory는 오래 가는 지식을 복원합니다.