Content
# Tool List
> A source-grounded MCP memory runtime and Obsidian-compatible vault template for
> LLM agents.
>
> `llm-vault` helps agents keep long-running project memory without silently
> overwriting uncertainty: immutable raw sources, source summaries, decision
> records, contradiction tracking, confidence-aware retrieval, and human review
> queues are first-class parts of the system.
[](LICENSE)
[](https://www.python.org/)
Read this first: [English](#what-is-this)
## What is this?
`llm-vault` combines an Obsidian-compatible Markdown vault, source-grounded
archival rules, decision records, contradiction preservation, and an MCP memory
runtime backed by DuckDB, BM25, optional Ollama embeddings, and graph expansion.
The core assumption is simple: **LLM output can be wrong by default**. Raw
evidence, citations, uncertainty labels, preserved contradictions, and human
review queues are therefore not optional extras. They are the operating model.
Agents such as Claude, Cursor, Antigravity, and Codex should read
[AGENTS.md](AGENTS.md) before writing to the vault. The full mental model lives in
[00_System/Second Brain Operating Model.md](00_System/Second%20Brain%20Operating%20Model.md).
## Start From A Clean Private Vault
This repository is a framework skeleton plus seed/example knowledge. If you are
turning it into your own private second brain, keep the framework files and
delete the existing seed documents before adding personal memory.
Keep these:
- `00_System/`, `90_Engine/`, `docs/`, `scripts/`
- root docs such as `README.md`, `SETUP.md`, `AGENTS.md`, `LICENSE`
- `.mcp.json.example`, `requirements.txt`, `.gitignore`
- layer `README.md` files and `.gitkeep` placeholders, if present
Delete seed/user-specific content from the knowledge layers:
```bash
find 10_MOC 20_Concepts 30_Projects 40_Decisions \
50_Source_Summaries 60_Open_Questions 70_Contradictions 80_Reviews \
-type f -name '*.md' ! -name 'README.md' -delete
find 05_Inbox 06_Raw \
-type f ! -name 'README.md' ! -name '.gitkeep' -delete
```
Then rebuild the local cache:
```bash
python3 90_Engine/indexer.py --force --embed --report
```
If Ollama is not running yet, omit `--embed` for a BM25-only first pass.
See [SETUP.md](SETUP.md) for MCP client setup and the private/public split. See
[examples/mini-vault](examples/mini-vault) for a tiny source-to-decision demo.
## Architecture
**Markdown is the source of truth; DuckDB is a derived, regenerable cache.** Clients write
Markdown through MCP tools, the indexer compiles it into a DuckDB graph cache, and the
retriever serves layer/confidence-aware hybrid search back to the clients. The cache
(`ltm_cache.db`) is gitignored and rebuilt per machine — only Markdown syncs across devices.
```mermaid
flowchart LR
CLI["LLM clients<br/>Claude · Codex · Antigravity"]
MD["Markdown vault<br/>source of truth · 9-predicate links"]
IDX["indexer.py<br/>incremental compile · MD5 · orphan prune"]
DB[("DuckDB cache · ltm_cache.db<br/>nodes · edges · embeddings")]
RET["retriever.py<br/>BM25 + dense + graph expansion"]
MCP["mcp_server.py<br/>MCP tools"]
OLL["Ollama · bge-m3"]
GIT["git remote<br/>cross-machine sync"]
CLI -->|"create / update / delete"| MD
MD <-->|"pull / push"| GIT
MD --> IDX
OLL -.->|"embed"| IDX
IDX --> DB
DB --> RET
OLL -.->|"query embed"| RET
RET --> MCP
MCP --> CLI
```
## Getting Started
- 설치, 초기 인덱싱, MCP 클라이언트 연결: [SETUP.md](SETUP.md)
- MCP 도구 명세와 AI memory write 흐름: [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md)
- Antigravity 전용 연결 가이드: [docs/ANTIGRAVITY.md](docs/ANTIGRAVITY.md)
- 왜 이 구조가 필요한지: [docs/WHY_LLM_VAULT.md](docs/WHY_LLM_VAULT.md)
- 작은 데모 vault: [examples/mini-vault](examples/mini-vault)
- 기기 간 git 동기화와 선택적 자동 sync: [SETUP.md](SETUP.md#자동-동기화-선택)
## Folder Structure
```text
llm-vault/
├── README.md
├── AGENTS.md
├── SETUP.md
├── docs/
│ ├── ANTIGRAVITY.md
│ ├── MCP_TOOLS.md
│ └── WHY_LLM_VAULT.md
├── examples/
│ └── mini-vault/
├── 00_System/
│ ├── Ontology Specification.md
│ ├── Second Brain Operating Model.md
│ ├── Source Policy.md
│ ├── Ingest Policy.md
│ ├── Review Policy.md
│ └── Naming Convention.md
├── 05_Inbox/
│ └── Raw/
├── 10_MOC/
│ └── Map of Content
├── 20_Concepts/
│ └── 내구성 개념 지식
├── 30_Projects/
│ └── 활성 작업 대시보드
├── 40_Decisions/
│ └── 결정 기록
├── 50_Source_Summaries/
│ └── 원본 압축 이해
├── 60_Open_Questions/
│ └── 미해결 질문
├── 70_Contradictions/
│ └── 모순·낡은 가정 보존
├── 80_Reviews/
│ └── 사람 검증 큐
└── 90_Engine/
├── indexer.py
├── retriever.py
├── mcp_server.py
└── ltm_cache.db
```
## Daily Workflow
node는 사람이 직접 Markdown으로 작성해도 되고, MCP write 도구로 만들 수도 있습니다.
인입(ingest)의 표준 절차는 [Ingest Policy](00_System/Ingest%20Policy.md)를 따릅니다.
- 사람이 편집한 뒤에는 `sync_vault()` 또는 인덱서 실행으로 캐시를 갱신합니다.
- 에이전트가 메모리를 저장할 때는 `list_notes()`로 기존 제목을 확인한 뒤
`create_note()`, `update_note()`, `upsert_edge()`를 사용합니다.
- dangling edge가 생기면 자동 정합이 처리하거나 `reconcile_graph()`로 즉시 정리합니다.
- **모든 source를 concept node로 만들지 않습니다.** 기본 도착지는
`50_Source_Summaries/`이며, 내구성 지식만 `20_Concepts/`로 승격합니다.
- 검색은 **계층/신뢰도 인지**입니다. `06_Raw/`는 전문검색 전용으로 검색되되 강등되고,
낮은 신뢰도·폐기 항목도 강등+표기되며, 검토 계층(`60/70/80`)은 기본 검색에서 빠집니다
(`retrieve_knowledge(..., include_reviews=true)`로 포함). 검토 큐 점검은
`review_queue()`로. 근거: [[2026-06-18-layer-and-confidence-aware-retrieval]].
node 작성 시 edge predicate는 아래 9개만 허용됩니다(안정적 지식 관계에만 사용).
`requires` · `utilizes` · `implemented_by` · `extends` · `abstracts` · `causes` · `contradicts` · `replaces` · `defines`
## Learn More
- 에이전트 지침: [AGENTS.md](AGENTS.md)
- 설계 이유: [docs/WHY_LLM_VAULT.md](docs/WHY_LLM_VAULT.md)
- 운영 모델: [00_System/Second Brain Operating Model.md](00_System/Second%20Brain%20Operating%20Model.md)
- 정책: [Source Policy](00_System/Source%20Policy.md) · [Ingest Policy](00_System/Ingest%20Policy.md) · [Review Policy](00_System/Review%20Policy.md) · [Naming Convention](00_System/Naming%20Convention.md)
- 온톨로지 헌법: [00_System/Ontology Specification.md](00_System/Ontology%20Specification.md)
- 초기 코퍼스(LLM 멘탈 모델): [10_MOC/Karpathy LLM Framework MOC.md](10_MOC/Karpathy%20LLM%20Framework%20MOC.md)
- 설치와 운영: [SETUP.md](SETUP.md) · MCP 도구: [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md)
## License
MIT License. 자세한 내용은 [LICENSE](LICENSE)를 참조하세요.
## Sources
- [Andrej Karpathy](https://karpathy.ai)
- [Intro to Large Language Models](https://www.youtube.com/watch?v=zjkBMFhNj_g)
- [Let's build the GPT Tokenizer](https://www.youtube.com/watch?v=zduSFxRajkE)
- [Software 2.0 Essay](https://karpathy.medium.com/software-2-0-a64152b37c35)
- [llm.c GitHub](https://github.com/karpathy/llm.c)
- [nanoGPT GitHub](https://github.com/karpathy/nanoGPT)
Connection Info
You Might Also Like
No recommendations available