memory promote

무엇을 하는 명령인가

memory promote는 promotion candidate를 받아 docs/memory/** 아래 durable doc으로 기록합니다. 새 worktree 파일을 ingest하지 않으며, 이후 검색 가능하게 만들려면 문서를 검토하고 커밋한 뒤 ingest해야 합니다.

언제 쓰는가 / 언제 쓰지 않는가

언제 쓰는가

• decision, glossary term, plan이 durable project memory가 되어야 할 때
• 미래 세션이 원래 세션 히스토리를 열지 않고도 그 지식을 찾을 수 있어야 할 때

언제 쓰지 않는가

• 아직 가설 수준의 메모일 때. memory wrap으로 working memory에 두십시오.
• 현재 작업 복원만 필요할 때. memory recall을 사용하십시오.

기본 구문

pnpm ragit memory promote --input <path|-> \
  [--dry-run] [--format text|json|both] [--cwd <path>]

인자와 옵션

• --input <path|->: promotion candidate를 설명하는 필수 JSON payload입니다.
• --dry-run: 후보와 생성될 문서를 실제 쓰기 없이 검증합니다.
• --format text|json|both: 출력 형식을 선택합니다.
• --cwd <path>: 다른 저장소를 대상으로 실행합니다.

입력/출력 계약

{
  "promotionCandidates": [
    {
      "type": "adr",
      "title": "Keep refresh handling outside manifest mutation",
      "summary": "Separates active auth refresh logic from snapshot writes.",
      "rationale": "Preserves snapshot contract stability.",
      "nextReviewAt": "2026-06-01"
    }
  ]
}

• JSON 출력에는 createdFiles, plannedFiles, sourceHeadSha, ingested, dryRun, warnings가 포함됩니다.
• --dry-run은 어떤 문서 파일이 생성될지를 사전에 보여줍니다.
• Promote는 ingested: false를 보고합니다. Apply가 성공하면 생성 문서를 커밋하고, 첫 snapshot이면 ragit ingest --all, trusted base가 있으면 지원되는 증분 ingest를 실행하라는 warning을 반환합니다.

대표 사용 예시

사람용 터미널 예시:

pnpm ragit memory promote --input promotion-batch.json
git add docs/memory
git commit -m "promote durable memory"
pnpm ragit ingest --all

에이전트 호출 예시:

pnpm ragit memory promote --input promotion-batch.json --dry-run --format json

실패/주의 사항

• promote는 docs/memory/**를 깨끗하게 유지하기 위한 의도적 필터입니다. raw scratch note에는 사용하지 마십시오.
• payload는 유효한 candidate type과 필드를 따라야 합니다.
• Promote된 문서는 검토·커밋·ingest 이후에만 searchable retrieval에 반영됩니다. 이전 HEAD 아래에 uncommitted worktree content를 인덱싱하면 안 됩니다.

관련 명령

• memory wrap
• ingest
• Memory Model Guide