LTM Vault 저장소 기능 상세 보고서
작성일: 2026-07-02
1. 요약
이 저장소는 LLM 에이전트를 위한 출처 기반 장기기억 프레임워크다. 단순히 대화 기록을 저장하거나 벡터 검색으로 다시 찾는 저장소가 아니라, 원본 증거, 요약, 개념, 프로젝트 상태, 의사결정, 모순, 검토 큐를 계층적으로 관리하는 LLM-native second brain 구조를 제공한다.
핵심 목적은 LLM이 장기간 프로젝트를 수행하면서 과거 맥락을 잃지 않되, 추측이나 오래된 정보가 검증된 사실처럼 굳어지는 것을 막는 것이다. 이를 위해 이 저장소는 다음 기능을 하나의 운영 모델로 묶는다.
- Obsidian 호환 Markdown vault
- 불변 raw source 보존
- source summary 기반 해석 계층
- 결정 기록과 supersede 방식의 변경 이력
- 모순 보존과 사람 검토 큐
- 9개 predicate 기반 지식 그래프
- DuckDB 기반 로컬 검색 캐시
- BM25, dense embedding, graph expansion을 결합한 검색
- MCP 도구를 통한 에이전트 읽기/쓰기 인터페이스
2. 이 저장소는 어떤 종류의 레포인가
이 저장소는 애플리케이션 서버나 일반 문서 저장소라기보다, LLM 에이전트가 장기 기억을 안전하게 읽고 쓸 수 있도록 만든 프레임워크 템플릿이다. 프레임워크에는 운영 정책, 폴더 계층, 인덱서, 검색기, MCP 서버, 예제 vault, 설치 문서가 포함된다.
저장소가 다루는 대상은 단순한 개념 노트에 한정되지 않는다. AI 연구 노트, 디버깅 로그, 프로젝트 결정, 이론 변화, 행정 기록, 스크린샷, 채팅 로그, 개인 워크플로우 기록처럼 장기간 다시 참조할 수 있는 자료를 모두 다룰 수 있도록 설계되어 있다.
다만 기본 철학은 명확하다. LLM 출력은 기본적으로 틀릴 수 있다. 따라서 기억 시스템은 “무엇을 기억했는가”만 저장하는 것이 아니라, “그 주장의 출처는 무엇인가”, “검토되었는가”, “모순이 있는가”, “낡은 결정인가”까지 함께 보존해야 한다.
3. 해결하려는 문제
일반적인 채팅 기록 저장이나 단순 RAG 시스템은 유사한 텍스트를 찾아주는 데는 유용하지만, 장기 프로젝트 운영에서 중요한 질문에 충분히 답하지 못한다.
- 이 주장은 어디에서 왔는가?
- 원본 증거인가, 요약인가, 에이전트의 추론인가?
- 이미 대체된 결정인가?
- 사람 검토가 필요한 낮은 신뢰도의 주장인가?
- 기존 지식과 충돌하는가?
- LLM이 직접 기억을 추가해도 지식 그래프가 오염되지 않는가?
이 저장소는 이런 질문을 폴더 구조, frontmatter, source policy, review policy, graph predicate, 검색 랭킹 정책으로 명시적으로 표현한다. 목표는 단순 회상이 아니라 감사 가능한 회상이다.
4. 저장소의 주요 구성
| 경로 | 역할 |
|---|---|
00_System/ | 운영 모델, 출처 정책, 인입 정책, 검토 정책, 명명 규칙, 온톨로지 명세 |
05_Inbox/ | 아직 정리되지 않은 미가공 입력물 |
06_Raw/ | 이관 후 수정하지 않는 원본 증거 |
10_MOC/ | 여러 노드를 탐색하기 위한 Map of Content |
20_Concepts/ | 지속적으로 재사용할 수 있는 개념 지식 |
30_Projects/ | 활성 프로젝트의 상태와 다음 행동을 보여주는 대시보드 |
40_Decisions/ | 중요한 선택과 근거를 기록하는 decision record |
50_Source_Summaries/ | raw source를 압축하고 해석한 source summary |
60_Open_Questions/ | 아직 해결되지 않은 질문 |
70_Contradictions/ | 충돌하는 주장과 낡은 가정 |
80_Reviews/ | 사람 검토가 필요한 낮은 신뢰도 주장, 환각 의심, 판단 대기 항목 |
90_Engine/ | Markdown을 인덱싱하고 검색/MCP 도구로 노출하는 런타임 |
docs/ | 설치, MCP 도구, 설계 이유 등 사용자 문서 |
examples/mini-vault/ | source에서 summary, decision, retrieval까지 이어지는 최소 예제 |
5. 계층 모델
이 저장소의 핵심은 자료를 성격별 계층으로 나누는 것이다. 모든 정보를 하나의 노트 폴더에 넣지 않고, 원본과 해석, 결정과 검토, 모순과 질문을 분리한다.
05_Inbox = 미처리 인입
06_Raw = 불변 원본 증거
50_Summaries = 원본을 압축한 source summary
30_Projects = 활성 작업 대시보드
20_Concepts = 내구성 있는 개념 지식
40_Decisions = 중요한 선택과 근거
60_Questions = 미해결 질문
70_Conflicts = 모순과 낡은 가정
80_Reviews = 사람 검증 큐
90_Engine = 인덱싱, 검색, MCP 런타임이 구조의 중요한 점은 06_Raw/와 해석 계층을 구분한다는 것이다. 원본은 증거이고, 요약과 개념은 해석이다. 해석은 바뀔 수 있지만 원본은 감사와 재검증을 위해 그대로 남겨야 한다.
6. 데이터 흐름
표준 데이터 흐름은 다음과 같다.
사람 / LLM / 도구 출력
-> 05_Inbox
-> 06_Raw
-> 50_Source_Summaries
-> 20_Concepts / 30_Projects / 40_Decisions
-> 60_Open_Questions / 70_Contradictions / 80_Reviews
-> 90_Engine 인덱싱
-> MCP 검색 및 쓰기 도구예를 들어 디버깅 세션을 기록한다면, 원 로그는 06_Raw/code-logs/에 보존하고, 핵심 원인과 해결 과정을 50_Source_Summaries/code-logs/에 요약한다. 이 내용이 특정 프로젝트 상태를 바꾸면 30_Projects/ 대시보드를 갱신하고, 중요한 아키텍처 선택이라면 40_Decisions/에 결정 기록을 추가한다. 불확실한 가정은 80_Reviews/로 보내고, 기존 지식과 충돌하면 70_Contradictions/에 보존한다.
7. Source-Grounded Memory 기능
이 저장소의 기억은 출처 기반이다. 중요한 사실 주장은 가능한 한 raw source 경로나 외부 URL을 가리켜야 한다.
7.1 Raw source 보존
06_Raw/는 증거 계층이다. 채팅 로그, 코드 diff, 에러 로그, 논문, 스크린샷, 프로젝트 로그, 행정 기록, 수기 노트, 링크 스냅샷이 여기에 들어갈 수 있다. 이관된 raw 파일은 수정하거나 삭제하지 않는 것이 원칙이다.
7.2 Source summary
50_Source_Summaries/는 raw source를 사람이 읽고 다시 쓰기 쉬운 형태로 압축하는 계층이다. 원본 전체를 매번 읽지 않아도 되도록 핵심 주장, 근거, 불확실성, 후속 조치를 정리한다. source summary는 원본을 대체하지 않고, 원본을 가리키는 해석 노드 역할을 한다.
7.3 해석과 원본의 분리
LLM이 만든 요약이나 결론은 source 자체가 아니다. 이 구분은 장기기억 시스템에서 매우 중요하다. 요약이 틀렸다면 요약을 고쳐야지 원본을 고치면 안 된다. 이 원칙이 있어야 나중에 에이전트가 기억을 검색했을 때 원래 증거까지 되짚어볼 수 있다.
8. 결정 기록 기능
40_Decisions/는 중요한 선택을 기록하는 계층이다. 예를 들어 아키텍처 방향, 도구 선택, 데이터 모델 변경, 운영 정책 변경처럼 나중에 “왜 이렇게 했는가”를 물을 수 있는 내용이 여기에 들어간다.
결정 기록의 핵심은 조용히 덮어쓰지 않는 것이다. 기존 결정이 바뀌면 기존 파일을 몰래 수정하는 대신, 새 결정 기록을 만들고 이전 결정을 대체했다는 관계를 남긴다. 이 방식은 프로젝트의 의사결정 역사를 보존한다.
9. 모순 및 검토 큐 기능
이 저장소는 모순을 숨기지 않는다. 서로 충돌하는 주장이나 낡은 가정은 70_Contradictions/에 보존한다. LLM 시스템에서는 그럴듯하지만 검증되지 않은 내용이 쉽게 섞일 수 있으므로, 불확실한 내용은 80_Reviews/에 보내 사람 검토 대상으로 만든다.
검토 큐는 다음과 같은 상황에 쓰인다.
- 신뢰도가 낮은 주장
- 환각 가능성이 있는 요약 또는 결론
- 사람 판단이 필요한 항목
- 중복 개념 후보
- 아직 결론 내리기 어려운 해석
이 기능의 목적은 불확실성을 제거하는 것이 아니라, 불확실성을 보이는 상태로 관리하는 것이다.
10. 9-Predicate 지식 그래프
이 저장소는 Markdown 노트 사이의 안정적인 의미 관계를 9개 predicate로 표현한다.
| Predicate | 의미 |
|---|---|
defines | A가 B의 정의 출처다 |
causes | A가 B를 유발한다 |
utilizes | A가 B를 도구나 자원으로 사용한다 |
implemented_by | A가 B로 구현된다 |
replaces | A가 B를 대체한다 |
requires | A가 존재하거나 작동하려면 B가 필요하다 |
extends | A가 B를 같은 층위에서 확장한다 |
contradicts | A와 B가 양립하기 어렵다 |
abstracts | A가 B의 복잡성을 한 층 위에서 단순화한다 |
중요한 제약은 이 그래프가 모든 연결을 표현하기 위한 것이 아니라는 점이다. raw source, inbox, 일시적인 연관을 억지로 그래프에 넣지 않는다. 그래프는 내구성 있는 지식 관계에만 사용한다.
11. 인덱싱 기능
90_Engine/indexer.py는 Markdown vault를 DuckDB 캐시로 컴파일한다. Markdown 파일이 source of truth이고, DuckDB는 재생성 가능한 파생 캐시다.
인덱서의 주요 기능은 다음과 같다.
- Markdown frontmatter 파싱
- node 테이블 생성 및 갱신
- edge DSL 파싱
- 9개 predicate 제약 검증
- MD5 기반 변경 감지
- Ollama embedding 생성 및 캐싱
- 계층별 인덱싱 정책 적용
- dangling edge 탐지
계층별 정책도 중요하다. 05_Inbox/는 인덱싱하지 않고, 06_Raw/는 전문검색 대상으로는 인덱싱하지만 그래프 노드로 취급하지 않는다. 해석 계층은 노드와 엣지 대상으로 인덱싱된다.
12. 검색 기능
90_Engine/retriever.py는 단순 벡터 검색이 아니라 여러 신호를 결합한 검색을 수행한다.
12.1 검색 방식
검색은 크게 세 단계로 동작한다.
- BM25 sparse search로 텍스트 유사 후보를 찾는다.
- Ollama embedding 기반 dense search로 의미 유사 후보를 찾는다.
- seed node 주변의 그래프를 확장해 관련 지식 서브그래프를 만든다.
결과는 JSON 메타데이터와 XML로 감싼 Markdown 본문을 함께 제공하는 capsule 형태로 반환된다. 에이전트는 이 결과를 읽고 어떤 노드가 어떤 계층에 속하는지, 신뢰도와 상태가 무엇인지 확인할 수 있다.
12.2 계층/신뢰도 인지 검색
검색 랭킹은 단순 유사도만 보지 않는다. 계층, 신뢰도, 상태를 함께 반영한다.
20_Concepts/,50_Source_Summaries/는 검증된 해석 지식으로 높게 평가한다.06_Raw/는 검색 가능하지만 원본 자료이므로 강등한다.60/70/80검토 계층은 기본 검색에서는 제외하고, 필요할 때만 포함한다.confidence: low,status: superseded,status: rejected같은 항목은 숨기지 않고 낮게 랭크한다.
이 방식은 검토되지 않은 기억이 확정 지식처럼 검색되는 것을 줄인다.
13. MCP 도구 기능
90_Engine/mcp_server.py는 LLM 클라이언트가 vault를 읽고 쓸 수 있도록 MCP 도구를 제공한다. 기능은 크게 읽기 도구와 쓰기 도구로 나뉜다.
13.1 읽기 도구
| 도구 | 기능 |
|---|---|
retrieve_knowledge | 자연어 질문으로 관련 지식 서브그래프 검색 |
sync_vault | 사람이 편집한 Markdown을 DuckDB 캐시로 동기화 |
vault_stats | 노드 수, 엣지 수, 임베딩 커버리지, predicate 분포 확인 |
review_queue | 질문, 모순, 검토 큐 항목을 상태별로 조회 |
13.2 쓰기 도구
| 도구 | 기능 |
|---|---|
list_notes | 기존 노드 제목과 위치 확인 |
create_note | 새 Markdown node 생성 후 증분 인덱싱 |
update_note | 기존 node의 본문, 메타데이터, 엣지 갱신 |
upsert_edge | source node에 edge 하나 추가 |
remove_edge | source node에서 edge 하나 제거 |
delete_node | node 파일과 DB 캐시 항목 삭제 |
reconcile_graph | 전체 엣지를 재구성해 dangling edge 정리 |
쓰기 도구는 직접 DB를 조작하는 대신 Markdown 파일을 생성하거나 수정하고, 인덱서를 통해 DuckDB 캐시를 갱신한다. 이 구조 덕분에 Markdown이 계속 진실의 원천으로 남는다.
14. 자동 정합 기능
쓰기 도구는 빠른 증분 인덱싱을 기본으로 한다. 새 노드와 그 노드가 내보내는 edge는 즉시 반영되지만, 기존 노드가 새 노드를 향하던 dangling edge는 전체 재구성 전까지 남을 수 있다.
이를 줄이기 위해 자동 정합 상태를 DB 옆 상태 파일에 저장하고, 검색 시점에 조건이 맞으면 force=True, embed=False 재정합을 한 번 수행한다. 즉시 정합이 필요할 때는 reconcile_graph(embed=False)를 호출할 수 있다.
15. 평가 및 튜닝 기능
90_Engine/eval_retrieval.py는 검색 품질을 측정하기 위한 스캐폴드다. 검색 정책의 가중치와 필터는 고정된 절대값이 아니라 00_System/Retrieval Policy.yaml에서 조정할 수 있는 값이다.
평가 지표에는 다음이 포함된다.
- MRR@5
- Recall@5
- review leakage rate
- raw overexposure rate
이 기능은 검색 결과가 너무 raw에 치우치거나, 검토 큐 항목을 부적절하게 노출하거나, 필요한 결정/개념을 찾지 못하는 문제를 조정하기 위한 것이다.
16. 예제 vault 기능
examples/mini-vault/는 이 프레임워크의 최소 동작을 보여주는 예제다. raw source를 넣고, source summary를 만들고, 개념이나 결정으로 승격하고, 검색 결과에서 계층과 상태가 어떻게 드러나는지 확인하는 용도다.
이 예제의 목적은 실제 개인 지식을 담는 것이 아니라, 프레임워크 사용자가 안전한 인입 경로와 검색 동작을 빠르게 이해하도록 돕는 것이다.
17. 일반 RAG와의 차이
이 저장소는 일반 RAG 시스템과 목표가 다르다. RAG는 보통 “질문과 비슷한 텍스트를 찾는 것”에 집중한다. 이 저장소는 거기에 더해 다음 질문을 함께 다룬다.
- 이 텍스트는 원본인가, 요약인가, 결정인가, 검토 항목인가?
- 이 주장은 신뢰도가 높은가?
- 이 결정은 아직 유효한가?
- 모순되는 다른 주장이 있는가?
- 에이전트가 이 내용을 확정 지식처럼 사용해도 되는가?
따라서 이 저장소의 핵심 가치는 검색 성능만이 아니라, 기억을 장기적으로 안전하게 운영하는 규율에 있다.
18. 에이전트 사용 흐름
에이전트가 이 저장소를 사용할 때의 권장 흐름은 다음과 같다.
- 과거 맥락이나 결정 이유가 필요한 질문을 받으면
retrieve_knowledge로 먼저 검색한다. - 기억을 새로 저장할 필요가 있으면
list_notes로 기존 노드와 중복 여부를 확인한다. - 내구성 있는 개념이면
create_note또는update_note를 사용한다. - 단순 관계 추가는
upsert_edge를 사용한다. - 불확실한 주장은 확정 노드로 만들지 않고
80_Reviews/로 보낸다. - 모순은 한쪽을 지우지 않고
70_Contradictions/에 보존한다. - 사람이 직접 Markdown을 편집했다면
sync_vault로 캐시를 갱신한다. - 중요한 검색 직전에는 필요에 따라
reconcile_graph로 그래프 정합을 맞춘다.
19. 이 저장소가 아닌 것
이 저장소는 다음과 다르다.
- 단순 채팅 로그 백업 저장소가 아니다.
- 모든 문서를 벡터 DB에 밀어 넣는 RAG 예제가 아니다.
- 모든 생각을 concept node로 승격시키는 개인 위키가 아니다.
- 검증되지 않은 LLM 출력을 확정 지식으로 축적하는 메모리 시스템이 아니다.
- DuckDB를 원본 저장소로 쓰는 앱이 아니다. 원본은 Markdown이고 DuckDB는 재생성 가능한 캐시다.
20. 최소 성공 기준
이 저장소가 의도대로 동작한다면 다음을 확인할 수 있어야 한다.
- raw source가 graph node로 오염되지 않고 보존된다.
- source summary가 raw source를 명확히 가리킨다.
- 중요한 결정이 별도 decision record로 남는다.
- 기존 결정이 바뀔 때 이력이 보존된다.
- 모순이 한쪽으로 덮이지 않고 visible하게 남는다.
- 낮은 신뢰도 주장이 review queue에 들어간다.
- 검색 결과가 layer, status, confidence 정보를 함께 제공한다.
- 에이전트가 MCP 도구를 통해 읽기와 쓰기를 수행할 수 있다.
- Markdown을 다시 인덱싱해 DuckDB 캐시를 재생성할 수 있다.
21. 결론
이 저장소는 LLM 에이전트가 장기 프로젝트에서 사용할 수 있는 기억 시스템의 뼈대다. 핵심은 “많이 저장하는 것”이 아니라, 출처와 불확실성을 잃지 않은 채 오래 쓸 수 있는 기억을 만드는 것이다.
이를 위해 원본 보존, source summary, 결정 기록, 모순 보존, 검토 큐, 9-predicate 그래프, 계층/신뢰도 인지 검색, MCP write/read 도구가 하나의 운영 모델로 연결되어 있다. 따라서 이 저장소는 단순 문서 모음이 아니라, 사람과 LLM 에이전트가 함께 장기기억을 관리하기 위한 auditable memory runtime이다.
참고 문서
README.mdAGENTS.md00_System/Second Brain Operating Model.md00_System/Source Policy.md00_System/Ingest Policy.md00_System/Review Policy.md00_System/Ontology Specification.mddocs/MCP_TOOLS.mddocs/WHY_LLM_VAULT.md90_Engine/indexer.py90_Engine/retriever.py90_Engine/mcp_server.py