05 메모리 & 지식 Markdown
Memory & Documentation Policy
Memory Bank는 자동 기억·검색 레이어, 정본 문서는 사람이 믿고 따르는 레이어 — 역할 분리와 승격 경로
한눈에 보기
이 문서는 “어디에 무엇을 기록할 것인가”를 정하는 정책입니다. 자동 색인되는 기억과 사람이 따르는 정본 문서를 분리하고, 둘 사이의 승격 경로를 명시합니다.
- 핵심 질문: 대화 맥락, 큐레이션 지식, 정본 문서, 행동 규칙은 각각 어디에 저장하는가?
- 읽는 대상: 에이전트 메모리·문서 체계를 설계하려는 운영자
- 연결 문서: Memory & Knowledge Pipeline, Public / Private Boundary, WORKLOG & Failure Learning
원칙
Memory Bank는 자동 기억/검색 레이어이고, 노트 시스템과 프로젝트 docs/는 사람이 믿고 따르는 정본 문서 레이어입니다.
역할 분리
| 레이어 | 역할 | 저장 대상 | 기본 행동 |
|---|---|---|---|
| Memory Bank | 과거 대화, 시도, 판단 맥락 검색 | conversation archive, facts, search index | 자동 색인과 검색에 맡긴다 |
| 노트 시스템 / PKB | 큐레이션된 지식 후보와 history | 결정 요약, 회고, 과거 문서 스냅샷 | 필요한 것만 저장한다 |
| Project docs | 현재 따라야 하는 정본 | INTENT, DESIGN, ADR, 운영 가이드 | 변경과 함께 갱신한다 |
| Rules / Skills | 에이전트 행동 정책 | 규칙 원천 core/extensions, 런타임 commands/skills | 검증된 반복 패턴만 승격한다 |
공개/비공개 경계
| 구분 | 저장소 | 책임 |
|---|---|---|
| 비공개 운영 원천 | ai-rules | 에이전트 행동 규칙, 프로젝트 규칙 생성, 문서화 정책 |
| 비공개 지식 원천 | pkb-wiki | 캡처로 승격한 결정, 실패 학습, 운영 노하우 |
| 비공개 배포 원천 | keystone-hub | 커맨드, 스킬, 훅, settings, 로컬/회사/머신별 배포 자산 |
| 공개 웹사이트 | keystone-portfolio | 공개 가능한 운영 철학, 시스템 설명, 사례, 포트폴리오 |
| 공개 OSS 원천 | ai-rules-public | 배포 가능한 규칙 패키지, 예제, 공개 문서 |
공개 Astro 사이트 역할은 keystone-portfolio로 수렴하고, 내부 운영 정책은 ai-rules와 pkb-wiki에서 먼저 확정합니다. keystone-portfolio는 public packaging layer이며 운영 정책의 원천이 아닙니다.
공개 문서는 whitelist 방식으로 고릅니다. 내부 경로, 토큰, 계정, 회사/고객명, 스케줄러 세부, raw 로그는 공개하지 않습니다.
기본 정책
- 일반 세션 로그는 노트 시스템에 자동 저장하지 않는다.
- “나중에 기억” 목적은 Memory Bank를 우선한다.
- 노트 시스템에는 raw log가 아니라 사람이 읽을 수 있는 후보 노트만 남긴다.
- 프로젝트의 현재 규칙, 절차, API 계약, 운영 방법은 노트가 아니라 프로젝트
docs/에 남긴다. - 에이전트가 반드시 따라야 하는 반복 규칙은
docs/에 머물지 말고 rule/skill 후보로 승격한다.
무엇을 문서화할지
문서화한다:
- 앞으로 반복해서 쓸 절차
- 다른 세션이나 다른 에이전트가 그대로 따라야 하는 운영 방법
- 설계/API/DB/권한/배포 계약
- 바뀌면 비용이 큰 결정
- 같은 실패를 막는 재발 방지책
- 사람에게 설명해야 하는 현재 상태
문서화하지 않는다:
- 단순 작업 진행 로그
- 터미널 출력 원문
- 검증되지 않은 아이디어
- Memory Bank 검색으로 충분한 대화 맥락
- 완료 후 다시 읽을 가능성이 낮은 세션 요약
승격 경로
대화/작업 맥락
-> Memory Bank 자동 색인
-> 필요 시 캡처 명령으로 후보 노트
-> 반복 가치가 있으면 docs/guide, docs/decisions, WORKLOG, FAILURE_LOG
-> 여러 프로젝트에 적용되면 core/extensions, command/skill로 승격명령 사용 기준
| 상황 | 사용할 것 | 이유 |
|---|---|---|
| 과거 결정/대화 찾기 | Memory Bank 검색 | 자동 색인된 맥락 검색 |
| 세션에서 남길 결론 정리 | 캡처 명령 | raw log 대신 큐레이션 |
| 현재 프로젝트 규칙 변경 | 프로젝트 docs/, 규칙 원본 | 정본 문서 |
| 설계/계약 변경 | design-doc, ADR/DESIGN | 구현 전 합의 |
| 원본 transcript 보존 | 로그 export 명령 | 감사/증거/재현용 예외 |
| 반복 실패 방지 | FAILURE_LOG, casebook, hook 후보 | 재발 방지 |
로그 export 예외 기준
원본 transcript exporter는 아래 목적이 없으면 실행하지 않습니다.
- 감사나 외부 공유를 위한 증거 보존
- Memory Bank 장애 조사
- 원본 세션 transcript를 재현 자료로 패키징
- 사용자가 원본 로그 export를 직접 요청
일상적인 세션 기록은 로그 export가 아니라 Memory Bank와 캡처 명령으로 처리합니다.
문서 작성 템플릿
# 제목
## 현재 결론
무엇을 하기로 했는가.
## 이유
왜 이 방식이 맞는가.
## 적용 범위
어떤 프로젝트/도구/상황에 적용되는가.
## 실행 방법
명령어, 경로, 체크리스트.
## 주의점
실수하기 쉬운 부분, 예외, 금지 사항.
## 마지막 확인
YYYY-MM-DD 기준 확인.운영 체크
세션 종료 전에 아래 중 하나라도 맞으면 문서 승격을 검토합니다.
- 다음 세션에서 같은 설명을 다시 해야 할 가능성이 높다.
- 작업 결과가 코드만으로 설명되지 않는다.
- 새 운영 절차나 금지 규칙이 생겼다.
- Memory Bank가 찾아도 정본으로 삼기에는 위험하다.
- 다른 프로젝트에도 반복 적용할 가능성이 있다.
Source Notes
이 문서는 KeystoneHub 규칙 원천의 Memory Bank and Documentation Policy를 공개용으로 정리한 것입니다. 내부 도구 명령어와 로컬 경로는 일반 표현으로 바꿨습니다. Provenance: keystone-native.