memory-protocol

name	memory-protocol
description	Memory operation rules — file-based recall/store protocol, field requirements, type registry
version	4.0.0
trigger	메모리 저장, 과거 기록 검색, 메모리 조회, store memory, recall memory, search past decisions
allowed-tools	["Read","Write","Grep","Glob","Bash"]

Quick Reference

• Recall: Grep → Glob 순서, 또는 md-recall-memory.sh <query> [path] [limit] [mode] [hop]
• Store: md-store-memory.sh <title> <content> [tags] [type] [keywords] [contextual_desc] [related]
• A-Mem 필드: contextual_description, keywords, related (2-hop 검색용)
• 중복 방지: 동일 title/slug → 자동 스킵 (Nemori Predict-Calibrate)
• 스키마: .hxsk/memories/_schema/*.schema.json, type-relations.yaml

---

Memory Protocol

Goal: .hxsk/memories/ 파일 기반 메모리 시스템의 사용 규칙을 중앙 정의하여 모든 스킬과 훅이 일관된 메모리 패턴을 따르도록 한다. Scope: search/store 순서, 필수 필드, type 레지스트리, A-Mem 확장 필드, 2-hop 검색. 모든 메모리는 마크다운 파일로 저장/검색.

---

Recall Protocol

메모리 조회는 반드시 Grep 텍스트 검색 → 태그 필터링 순서를 따른다.

1. Grep 검색 (우선)

세션/태스크 시작 시 broad context를 먼저 가져온다:

# .hxsk/memories/ 전체에서 키워드 검색
grep -rli "{keyword}" .hxsk/memories/ | sort -r | head -5

또는 Grep 도구 사용:

Grep(pattern: "{keyword}", path: ".hxsk/memories/", output_mode: "files_with_matches")

2. 태그 기반 필터 (보충)

특정 타입이나 태그로 좁혀야 할 때:

Glob(pattern: ".hxsk/memories/{type}/*.md")

Grep(pattern: "tags:.*{tag}", path: ".hxsk/memories/", output_mode: "files_with_matches")

3. 훅 기반 검색 (자동화)

훅에서 사용할 때:

# 기본 검색 (compact 모드, 2-hop)
bash scripts/md-recall-memory.sh "{query}" "$PROJECT_DIR" 5

# 상세 검색 (full 모드)
bash scripts/md-recall-memory.sh "{query}" "$PROJECT_DIR" 5 full

# 1-hop만 (related 추적 안함)
bash scripts/md-recall-memory.sh "{query}" "$PROJECT_DIR" 5 compact 1

4. 2-hop 이웃 검색 (A-Mem)

검색된 메모리의 related 필드를 자동 추적하여 연결된 메모리도 함께 반환:

# hop=2 (기본값): related 필드의 메모리도 포함
bash scripts/md-recall-memory.sh "auth" "." 5 compact 2

Output에서 [→related] 표시로 2-hop 결과 구분 가능.

When to Recall

Timing	Required	Example
Session start	YES (자동: session-start.sh)	프로젝트 컨텍스트 검색
Task start	YES	관련 과거 작업/결정 검색
Debug start	YES	유사 버그/eliminated hypotheses 검색
Plan creation	YES	과거 deviation/execution-summary 검색
Arch review	YES	과거 architecture-decision 검색
Before store	NO	중복 방지 목적으로 선택적

---

Storage Protocol

Required Fields

모든 메모리 파일은 아래 YAML frontmatter를 필수 포함:

Field	Description	Required
title	메모리 제목 (markdown 헤더로도 반복)	✓
tags	YAML 배열 (최소 2개)	✓
type	Type Registry에서 선택	✓
created	ISO-8601 타임스탬프	✓
contextual_description	A-Mem: 1줄 요약 (200자 제한)	자동생성
keywords	A-Mem: LLM 생성 검색 키워드	권장
related	A-Mem Link: 관련 메모리 파일명 배열	선택

파일 저장 방법

방법 1: 훅 사용 (권장, A-Mem 확장)

# 기본
bash scripts/md-store-memory.sh "{title}" "{content}" "{tag1,tag2}" "{type}"

# A-Mem 확장 필드 포함
bash scripts/md-store-memory.sh "{title}" "{content}" "{tags}" "{type}" "{keywords}" "{contextual_desc}" "{related}"

중복 방지 (Nemori Predict-Calibrate):

• 동일 날짜+title이면 [SKIP:DUPLICATE] 반환하고 저장 안 함
• 중복 시 기존 파일 경로 출력

방법 2: 직접 파일 생성

---
title: "{title}"
tags:
  - tag1
  - tag2
type: {type}
created: {ISO-8601}
---

## {title}

{content}

파일 경로: .hxsk/memories/{type}/{YYYY-MM-DD}_{slug}.md

Storage Triggers

Trigger	Type	Timing
Bug root cause found	root-cause	Immediate
Architecture decision	architecture-decision	Immediate
Pattern discovered	pattern-discovery	Immediate
Security finding	security-finding	Immediate
Hypothesis eliminated	debug-eliminated	Immediate
Plan deviation	deviation	On commit
Execution summary	execution-summary	On commit
Health event	health-event	On event
Session end	session-summary	Auto (hook)
Pre-compact snapshot	session-snapshot	Auto (hook)
Debug blocked (3-strike)	debug-blocked	Immediate
Bootstrap record	bootstrap	On complete

---

Importance Scoring

파일 기반 시스템에서 중요도는 content의 상세도와 태그 풍부도로 결정된다. 중요도를 높이려면 content에 맥락과 증거를 풍부하게 기술한다.

중요도 수준	Content 전략
Critical	아키텍처 결정 근거, 영향 범위, 대안 비교 등 상세 기술
High	근본 원인, 발견 패턴의 증거와 재현 경로 포함
Medium	배제 가설의 증거, 이탈 사유 간결히 기술
Low	요약 수준 (세션 요약, 자동 스냅샷)

---

Relationship Handling

A-Mem Link (권장)

related 필드를 사용하여 메모리 간 연결:

related:
  - 2024-01-15_auth-token-expired
  - 2024-01-16_jwt-validation-fix

연관 조회 (2-hop)

md-recall-memory.sh가 자동으로 related 필드를 추적:

# hop=2 (기본): 검색 결과 + related 메모리
bash scripts/md-recall-memory.sh "auth" "." 5 compact 2

태그 기반 연결 (레거시)

태그에 related:{slug} 패턴도 여전히 지원:

tags:
  - debug
  - root-cause
  - related:2024-01-15_auth-token-expired

---

Type Relations (Ontology)

Note: 아래 검색 체인은 설계 레퍼런스이며, 현재 자동 구현되지 않음. md-recall-memory.sh의 2-hop 검색은 related 필드 기반이며, 체인 자동 순회는 미구현.

.hxsk/memories/_schema/type-relations.yaml에서 14개 타입 간 관계 정의:

Relation	의미	예시
resolves	A가 B 문제를 해결	root-cause → debug-eliminated
informs	A가 B 결정에 영향	architecture-decision → pattern-discovery
triggers	A 발생 시 B 생성	debug-blocked → health-event
generates	A에서 B 도출	root-cause → pattern-discovery

Search Chains (최적화된 검색 순서)

debugging_chain: [debug-blocked, debug-eliminated, root-cause, pattern-discovery]
architecture_chain: [bootstrap, architecture-decision, pattern-discovery]
session_chain: [session-snapshot, session-summary, session-handoff]

---

Schema Validation

.hxsk/memories/_schema/ 디렉토리에 JSON Schema 정의:

• base.schema.json: 공통 필드 (A-Mem 확장 포함)
• root-cause.schema.json: 근본 원인 전용 필드
• architecture-decision.schema.json: ADR 스타일 필드
• session-summary.schema.json: Nemori 서사 형태 필드

---

Type Registry

Type	Description	Primary Tags	Directory
architecture-decision	아키텍처 결정 사항	arch,decision	memories/architecture-decision/
root-cause	디버깅 근본 원인	debug,root-cause	memories/root-cause/
debug-eliminated	배제된 가설	debug,eliminated	memories/debug-eliminated/
debug-blocked	3-strike로 차단된 조사	debug,blocked,3-strike	memories/debug-blocked/
health-event	컨텍스트 건강 이벤트	health,context	memories/health-event/
session-handoff	세션 인수인계 정보	handoff,session	memories/session-handoff/
execution-summary	실행 결과 요약	execution,summary	memories/execution-summary/
deviation	계획 대비 이탈	deviation,plan	memories/deviation/
pattern-discovery	발견된 패턴/학습	pattern,learning	memories/pattern-discovery/
bootstrap	프로젝트 초기 설정 기록	bootstrap,setup	memories/bootstrap/
session-summary	세션 종료 요약	session,auto	memories/session-summary/
session-snapshot	Pre-compact 스냅샷	session-snapshot,pre-compact	memories/session-snapshot/
security-finding	보안 발견 사항	security,finding	memories/security-finding/
general	기타	context-dependent	memories/general/

---

Anti-Patterns

Anti-Pattern	Why	Instead
Grep 없이 바로 파일 열기	관련 없는 파일 읽는 시간 낭비	Grep 검색 → 관련 파일만 Read
content에 title 미포함	검색 시 맥락 부족	## {title}\n\n{content} 형식 사용
단일 태그 사용	검색 정밀도 저하	최소 2개 태그 (type + domain)
매 커밋마다 자동 저장	noise > signal	Trigger 테이블의 시점만 저장
중복 저장	디렉토리 비대화	저장 전 Grep으로 중복 확인 (선택적)