도움말:S3 연구 메모리/메모 사용법: 두 판 사이의 차이

2026년 7월 20일 (월) 14:08 기준 최신판

이 페이지는 저장소 문서에서 자동으로 동기화됩니다. 위키에서 직접 편집하지 마세요.

S3 연구 메모리는 프로젝트 일지나 실험 원본을 모으는 곳이 아닙니다. 다른 작업에서도 다시 참고할 만한 시행착오를 짧은 메모로 남깁니다.

먼저 검색하기

브라우저 메인 화면의 검색창에는 궁금한 점을 문장으로 입력할 수 있습니다. 표현이 달라도 관련된 메모를 함께 찾습니다. 검색 결과는 그 아래 지식 그래프 중앙에 한 군집으로 모이고, 결과가 아닌 메모는 흐리게 표시됩니다. 점을 누르면 연결 수와 관계 유형을 볼 수 있고, 두 번 누르면 메모가 열립니다. 검색 결과 해제를 누르면 전체 그래프로 돌아갑니다. 전체 그래프는 연결된 메모를 중앙에 모으고 연결이 없는 메모를 바깥쪽에 조밀하게 배치합니다. 연결된 메모의 제목은 처음부터 표시됩니다. 제목 필터, 관계 필터, 확대와 이동도 사용할 수 있습니다.

본문까지 찾으려면 Special:Search, 에이전트에서는 search_lessons를 사용합니다. 프로젝트 이름보다 현상과 원인을 나타내는 말로 찾는 편이 잘 맞습니다.

메모리 단편화, retry storm, lock contention, cold start

같은 내용이 이미 있으면 새 메모를 만들지 않습니다. 기존 메모에 자료를 더하거나, 내용이 다른 이유를 관계로 연결하면 됩니다.

브라우저에서 메모 쓰기

로그인한 뒤 다음 화면을 엽니다.

/index.php/연구_메모리#create-a-lesson

문서 ID에는 영문 소문자, 숫자, 밑줄, 하이픈만 씁니다. Lesson:은 입력하지 않습니다.

gpu_allocator_fragmentation

문서 ID는 에이전트가 메모를 인용할 때도 쓰므로 날짜, 사람 이름, 프로젝트에서만 통하는 줄임말은 피하세요. 화면에 보이는 제목은 나중에 바꿀 수 있습니다.

입력란에는 다음 내용을 적습니다.

화면	필드	적을 내용
제목	`title`	메모의 결론이 드러나는 짧은 제목
궁금했던 점	`question`	시도를 시작한 이유
해본 것	`attempt`	실제로 바꿨거나 비교한 것
당시 조건	`context`	장비, 버전, 설정, 워크로드 등 결과에 영향을 준 조건
실제 결과	`observation`	직접 확인한 수치나 동작
왜 그랬는지	`interpretation`	가능한 원인과 아직 확실하지 않은 부분
다음에 기억할 것	`reusable_lesson`	다른 작업에서도 써먹을 한 문장
언제 맞는지	`applicability`	맞는 조건과 예외
신뢰도	`confidence`	자료의 질에 따라 `low`, `medium`, `high` 중 선택
관련 자료	`evidence`	아래에 연결할 자료를 짧게 설명
자료 출처	`record_origin`	직접 얻은 내용은 `lab`, 외부 자료를 정리했으면 `imported`

관찰과 해석은 나눠 쓰세요. 예를 들어 동시 compaction 16개에서 p99가 18 ms에서 71 ms로 늘었다는 관찰입니다. 공유 writeback 제한 때문에 queue가 묶였다는 해석이며, 새 자료가 나오면 달라질 수 있습니다.

저장한 메모는 바로 검색되고 메인 화면의 지식 그래프와 최근 메모에도 나타납니다.

자료 연결하기

메모마다 자료를 하나 이상 연결합니다. 원본 전체를 위키에 복사하지 말고 나중에 다시 찾을 수 있는 위치를 적으세요.

입력란	내용
자료 ID	메모 안에서 겹치지 않는 짧은 ID
출처	저장소, 커밋, 실행 ID, 문서 절, 시간 구간 등
URL	바로 열 수 있는 주소가 있을 때만 입력
자료 종류	`paper`, `code`, `dataset`, `log`, `benchmark`, `other` 중 선택
확인 범위	`full_text`, `official_abstract`, `partial_source`, `metadata_only` 중 선택
메모	이 자료에서 확인할 부분과 한계

git yonsei-s3/kernel-probes@4f19a2e, results/lockstat/run-031/summary.json

확인 범위는 자료에서 실제로 읽은 범위이며 Lesson의 종합 신뢰도인 confidence와 다릅니다. 서지정보만 확인했다면 metadata_only로 표시하고 기술 내용을 추측하지 않습니다. not_recorded는 이전 근거에 값이 없을 때 표시되는 호환값이므로 새 근거에는 선택하지 않습니다. 브라우저 양식에도 not_recorded 기본값이 없고 새 근거에 선택할 수 없습니다. MCP로 새 근거를 붙일 때는 나머지 네 값 중 하나를 명시해야 합니다.

latest, 대시보드, 작성자만 아는 로컬 경로처럼 시간이 지나면 찾기 어려운 표현은 피합니다. 비밀번호, 토큰, 개인 정보, 공개할 수 없는 대화, 대용량 원시 데이터도 본문에 넣지 않습니다.

근거를 검증한 기록 남기기

자료를 실제로 읽어 Lesson 주장을 확인했다면 기존 evidence를 고치지 말고 새 검증 기록을 붙입니다. 같은 evidence를 나중에 다시 확인했다면 이전 기록을 수정·삭제하지 않고 새 기록을 append-only로 붙입니다. evidence별 마지막 기록이 현재 판정입니다.

입력란	내용
evidence ID	검사한 기존 근거 ID
evidence digest	읽기 시점의 evidence 내용 digest
확인 범위	이번에 실제로 검사한 `verification_basis`
자료 식별자	파일, 커밋, 데이터 버전, 문서 버전 등 고정 식별자
자료 SHA-256	실제로 검사한 정확한 바이트의 SHA-256
위치	페이지, 절, 라인, 실험 구간 등 주장을 확인한 위치
확인 범위와 한계	읽은 범위와 제외한 부분
판정	`supports`, `contradicts`, `inconclusive` 중 하나
연결 주장	자료가 실제로 확인한 Lesson 필드

원본 파일을 검사했다면 그 파일 바이트를 해시합니다. 원본 대신 저장·정규화한 텍스트를 검사했다면 그 정확한 텍스트의 UTF-8 바이트를 해시합니다. 이 경우 변환 방법과 보존한 산출물을 자료 식별자와 확인 범위에 명시합니다. MediaWiki revision의 저장 계정과 시각이 권위 출처입니다. 검증 기록의 출처는 현재 저장 계정과 정확히 같아야 하고, 기록 시각은 revision 저장 시각 전후 5분 안이며 이전 기록보다 늦어야 하는 보조 필드입니다. 기존 출처와 시각은 수정할 수 없습니다.

high confidence는 full_text 또는 official_abstract를 기반으로 한 supports 검증이 observation, interpretation, reusable_lesson 세 필드를 모두 뒷받침할 때만 사용합니다. observation, interpretation, reusable_lesson을 수정한 후 결과 confidence가 medium 또는 high이면 실제로 바꾸는 주장과 연결한 같은 강도의 검증이 필요합니다. contradicts나 inconclusive는 지지 근거로 세지 않습니다. 결과 confidence가 low인 교정은 기존 confidence를 낮추는 경우를 포함해 not_recorded가 아닌 basis evidence로 할 수 있습니다.

다른 메모와 연결하기

관계는 출발 메모 관계값 대상 메모 순서로 읽습니다.

관계	뜻
`supports`	대상 메모와 맞는 자료나 원인을 보탬
`contradicts`	대상 메모의 주요 주장과 관찰이 충돌함
`analogous_to`	분야는 달라도 같은 원인이나 실패 형태를 보임
`failed_because`	대상 메모에 적힌 이유로 시도가 실패함
`works_when`	대상 메모의 조건에서 방법이 잘 작동함
`suggests`	다음 가설이나 시도를 제안함
`supersedes`	새 메모가 이전 안내를 대신함. 상태는 자동으로 바뀌지 않음

연결 이유에는 두 메모가 닮거나 충돌하는 지점을 한두 문장으로 씁니다. 관련성이 애매하면 억지로 연결하지 않아도 됩니다.

메모 고치기

메모 화면에서 메모 편집을 누릅니다. 잘못 적은 수치나 해석을 고치고, 수정 요약에 이유를 짧게 남기세요. 이전 내용은 MediaWiki 이력에서 확인할 수 있습니다. 에이전트가 고칠 때는 현재 revision과 근거를 다시 읽은 뒤 revise_lesson을 사용합니다. 같은 논문의 보강 내용을 evidence note나 새 Technical Review 메모에 숨기지 않습니다. 새 근거를 먼저 붙였다면 attach_evidence 응답의 current_revision_id를 다음 revise_lesson의 expected_revision_id로 사용합니다. 그 사이 다른 변경이 있었다면 get_lesson을 다시 읽고 변경안을 재계산합니다.

MCP로 찾기

처음에는 결과를 3~5개만 받고 필요한 필드만 요청하는 편이 빠릅니다.

S3 Research Memory에서 tail latency와 관련된 메모를 최대 5개 찾아 줘.
id, title, reusable_lesson, applicability, confidence, citations만 반환해.

후보를 고른 뒤 get_lesson으로 자세히 읽고, 관계는 find_related_lessons, 다른 분야의 비슷한 사례는 find_analogies로 찾습니다. 근거 note와 추가 정보를 확인하려면 citation_detail=full을 지정합니다. get_lesson의 revision ID는 이어지는 조건부 수정과 감사에 사용합니다. 답변에 메모를 사용했다면 반환된 자료 인용도 같이 보관하세요.

서버에서 의미 검색을 켠 경우에는 표현이 다른 문제도 찾도록 다음처럼 요청할 수 있습니다. 기본 검색은 계속 legacy이므로 hybrid_v1을 직접 지정합니다.

search_lessons를 retrieval_mode=hybrid_v1로 실행해,
문제의 제약과 해결 원리가 비슷한 메모를 최대 5개 찾아 줘.
effective_mode와 semantic_status도 알려 줘.

서버 담당자가 S3RM_SEARCH_SCOPES_JSON을 설정한 경우에는 scope를 함께 지정할 수 있습니다. scope는 미리 정한 분야·출처·기간 필터를 호출자의 필터와 교집합으로 적용하며 접근 권한을 바꾸지 않습니다. 검색 품질을 재현해 비교하려면 make evaluate-retrieval QUERY_FILE=queries.json을 사용합니다. 파일에는 query, expected_ids와 선택적인 retrieval_mode, scope만 넣고, 명령은 읽기 전용 검색만 실행합니다.

의미 유사도는 저장된 관계나 사실이 아닙니다. 후보의 적용 조건과 근거를 get_lesson으로 확인한 뒤 실제 관계를 남길지 판단하세요.

외부 자료 후보 수집

code checkout, 문서 디렉터리와 Slack export는 다음처럼 읽기 전용 후보로 수집할 수 있습니다.

make collect-candidates ARGS='--code-root /path/to/repo --docs-root /path/to/docs'
make collect-candidates ARGS='--slack-export /path/to/slack-export.json'
make collect-candidates ARGS='--code-root /path/to/repo --checkpoint /path/to/state'

후보에는 source, locator, 제목과 비밀값이 마스킹된 본문만 들어갑니다. 후보를 자동으로 Lesson으로 저장하지 않으며, 실제 자료를 확인한 뒤 중앙 MCP에서 evidence를 명시적으로 붙입니다.

여러 검색 facet을 병렬로 실행하려면 다음 명령을 사용합니다.

make research-query QUERY='cache stampede' ARGS='--scope papers'

S3RM_RESEARCH_LLM_URL과 S3RM_RESEARCH_LLM_MODEL을 설정하고 ARGS='--synthesize' 를 추가하면 선택적 rerank와 synthesis를 사용합니다. synthesis는 검색 결과에 존재하는 Lesson ID만 인용할 수 있습니다.

에이전트에게 작성을 맡길 때

쓰기 토큰이 있는 에이전트는 create_lesson_draft, link_lessons, attach_evidence, record_evidence_verification, revise_lesson을 쓸 수 있습니다. 에이전트가 만든 메모와 revision은 저장 즉시 검색됩니다. 상태 변경, 삭제, 이동, 관리자 작업은 MCP에서 할 수 없습니다. 다섯 쓰기 도구는 모두 operation_id가 필요합니다. 같은 Lesson 안에서 일반 쓰기, revision, 검증 기록은 ID 충돌 범위를 공유합니다. 같은 종류·요청의 정확한 재시도일 때만 같은 ID와 같은 요청을 보내고, 다른 작업에는 새 ID를 사용합니다. Lesson 생성에는 구조화된 initial_evidence가 필수이며 Lesson 본문과 같은 revision에 저장됩니다.

자동화 작업·워크플로·CI·도구 호출의 성공·실패 상태, 재시도, 인증·연결 오류와 실행 로그 자체는 Lesson으로 저장하지 않습니다. 실패 자체가 연구 대상이고 단일 실행을 넘어 재사용할 원인과 적용 조건을 확인 가능한 근거로 일반화한 독립 주장일 때만 저장합니다.

자료 위치와 확인한 사실을 먼저 제공하고 다음을 요청하세요.

같은 메모가 있는지 먼저 검색
관찰과 해석을 분리
맞는 조건과 예외를 명시
자료를 추측하지 않기
검증 기록이 있다면 자료 digest·위치·범위·판정·연결 주장을 함께 확인
작업이 끝나면 Lesson: ID 반환
여러 건을 바꿨다면 audit_lessons로 revision·내용·근거·관계를 확인

반환된 ID를 브라우저에서 열어 내용과 자료 위치를 확인합니다. 틀린 부분은 같은 ID의 새 revision으로 고칩니다. 출처만 추가할 때는 evidence, 독립된 새 주장일 때만 새 Lesson과 관계를 사용합니다. 감사는 저장된 구조, digest, 검증 수령 기록의 일관성을 확인하며 외부 자료의 사실 진위를 자동으로 판정하지 않습니다.

도구 입력과 응답 형식은 MCP 클라이언트 안내, 필드와 관계의 기계 계약은 아키텍처에 있습니다.

@@ 6번째 줄: / 6번째 줄: @@
 === 먼저 검색하기 ===
-브라우저 메인 화면에서는 궁금한 점을 자연어 검색창에 문장으로 입력할 수 있습니다. 서버에서 의미 검색을 사용할 수 있으면 표현이 달라도 가까운 메모를 찾습니다. 그 아래 지식 그래프에서 점을 누르면 연결 수와 관계 유형을 볼 수 있고, 두 번 누르면 메모가 열립니다. 제목 검색, 관계 필터, 확대와 이동도 사용할 수 있습니다.
+브라우저 메인 화면의 검색창에는 궁금한 점을 문장으로 입력할 수 있습니다. 표현이 달라도 관련된 메모를 함께 찾습니다. 검색 결과는 그 아래 지식 그래프 중앙에 한 군집으로 모이고, 결과가 아닌 메모는 흐리게 표시됩니다. 점을 누르면 연결 수와 관계 유형을 볼 수 있고, 두 번 누르면 메모가 열립니다. <code><nowiki>검색 결과 해제</nowiki></code>를 누르면 전체 그래프로 돌아갑니다. 전체 그래프는 연결된 메모를 중앙에 모으고 연결이 없는 메모를 바깥쪽에 조밀하게 배치합니다. 연결된 메모의 제목은 처음부터 표시됩니다. 제목 필터, 관계 필터, 확대와 이동도 사용할 수 있습니다.
 본문까지 찾으려면 <code><nowiki>Special:Search</nowiki></code>, 에이전트에서는 <code><nowiki>search_lessons</nowiki></code>를 사용합니다. 프로젝트 이름보다 현상과 원인을 나타내는 말로 찾는 편이 잘 맞습니다.
@@ 168번째 줄: / 168번째 줄: @@
 effective_mode와 semantic_status도 알려 줘.
 </nowiki></pre>
+서버 담당자가 <code><nowiki>S3RM_SEARCH_SCOPES_JSON</nowiki></code>을 설정한 경우에는 <code><nowiki>scope</nowiki></code>를 함께 지정할 수 있습니다. scope는 미리 정한 분야·출처·기간 필터를 호출자의 필터와 교집합으로 적용하며 접근 권한을 바꾸지 않습니다. 검색 품질을 재현해 비교하려면 <code><nowiki>make evaluate-retrieval QUERY_FILE=queries.json</nowiki></code>을 사용합니다. 파일에는 <code><nowiki>query</nowiki></code>, <code><nowiki>expected_ids</nowiki></code>와 선택적인 <code><nowiki>retrieval_mode</nowiki></code>, <code><nowiki>scope</nowiki></code>만 넣고, 명령은 읽기 전용 검색만 실행합니다.
 의미 유사도는 저장된 관계나 사실이 아닙니다. 후보의 적용 조건과 근거를 <code><nowiki>get_lesson</nowiki></code>으로 확인한 뒤 실제 관계를 남길지 판단하세요.
+=== 외부 자료 후보 수집 ===
+code checkout, 문서 디렉터리와 Slack export는 다음처럼 읽기 전용 후보로 수집할 수 있습니다.
+<pre><nowiki>
+make collect-candidates ARGS='--code-root /path/to/repo --docs-root /path/to/docs'
+make collect-candidates ARGS='--slack-export /path/to/slack-export.json'
+make collect-candidates ARGS='--code-root /path/to/repo --checkpoint /path/to/state'
+</nowiki></pre>
+후보에는 source, locator, 제목과 비밀값이 마스킹된 본문만 들어갑니다. 후보를 자동으로 Lesson으로 저장하지 않으며, 실제 자료를 확인한 뒤 중앙 MCP에서 evidence를 명시적으로 붙입니다.
+여러 검색 facet을 병렬로 실행하려면 다음 명령을 사용합니다.
+<pre><nowiki>
+make research-query QUERY='cache stampede' ARGS='--scope papers'
+</nowiki></pre>
+<code><nowiki>S3RM_RESEARCH_LLM_URL</nowiki></code>과 <code><nowiki>S3RM_RESEARCH_LLM_MODEL</nowiki></code>을 설정하고 <code><nowiki>ARGS=&#x27;--synthesize&#x27;</nowiki></code> 를 추가하면 선택적 rerank와 synthesis를 사용합니다. synthesis는 검색 결과에 존재하는 Lesson ID만 인용할 수 있습니다.
 === 에이전트에게 작성을 맡길 때 ===
 쓰기 토큰이 있는 에이전트는 <code><nowiki>create_lesson_draft</nowiki></code>, <code><nowiki>link_lessons</nowiki></code>, <code><nowiki>attach_evidence</nowiki></code>, <code><nowiki>record_evidence_verification</nowiki></code>, <code><nowiki>revise_lesson</nowiki></code>을 쓸 수 있습니다. 에이전트가 만든 메모와 revision은 저장 즉시 검색됩니다. 상태 변경, 삭제, 이동, 관리자 작업은 MCP에서 할 수 없습니다. 다섯 쓰기 도구는 모두 <code><nowiki>operation_id</nowiki></code>가 필요합니다. 같은 Lesson 안에서 일반 쓰기, revision, 검증 기록은 ID 충돌 범위를 공유합니다. 같은 종류·요청의 정확한 재시도일 때만 같은 ID와 같은 요청을 보내고, 다른 작업에는 새 ID를 사용합니다. Lesson 생성에는 구조화된 <code><nowiki>initial_evidence</nowiki></code>가 필수이며 Lesson 본문과 같은 revision에 저장됩니다.
+자동화 작업·워크플로·CI·도구 호출의 성공·실패 상태, 재시도, 인증·연결 오류와 실행 로그 자체는 Lesson으로 저장하지 않습니다. 실패 자체가 연구 대상이고 단일 실행을 넘어 재사용할 원인과 적용 조건을 확인 가능한 근거로 일반화한 독립 주장일 때만 저장합니다.
 자료 위치와 확인한 사실을 먼저 제공하고 다음을 요청하세요.