Git backend

✅ 라이브 (서버)

vault_* / sync_* 도구는 api.ainote.dev 서버에서 동작합니다 — JSON-RPC POST /api/mcp 또는 @ainote/sdk (ai.vault.* / ai.sync.*)로 호출하세요. (일부 vault 도구는 연결된 git-backed vault가 필요. 참고: @ainote/mcp npm 패키지 구버전엔 번들이 안 됐을 수 있으니 직접 JSON-RPC 또는 SDK 사용 권장.)

ainote 의 vault 는 너의 GitHub private repository 다. ainote 는 git 트래픽을 proxy 하지 않는다 — 저장·버전·clone/push 는 GitHub 이 담당하고, ainote 는 파일 인덱싱·검색·MCP 통합만 한다. 철학: 파일이 주인, DB 는 인덱스, git 이 접착제.

구조

GitHub (github.com)
└── <owner>/
    └── <vault-repo>  ← 사용자 소유 private repo
        ├── *.md      ← 노트/핸드오프/메모리
        └── ...

vault 1개 = GitHub private repo 1개. 사용자가 GitHub 에서 직접 clone 하고, push 하면 GitHub webhook 이 ainote 를 깨워 재인덱싱한다. ainote 서버에 bare repo 를 두거나 git 요청을 중계하지 않는다.

연결 (GitHub App)

git-backed vault 를 쓰려면 먼저 ainote GitHub App 을 설치한다.

1. vault_connect_status — 설치 여부 확인. 미설치면 install_url 반환.
2. install_url 로 App 설치 (사용자 계정 또는 org 선택).
3. vault_create { name } — 사용자 계정 아래 private repo 를 새로 만들어 vault 로 연결. slug 는 name 에서 파생되어 repo 이름이 된다.

// vault_connect_status → 미연결 예시
{ "connected": false, "install_url": "https://github.com/apps/ainoteapp/installations/new" }

Clone

vault_clone { name } 은 vault 의 GitHub HTTPS clone URL 을 돌려준다. 인증은 ainote 가 아니라 네 GitHub 자격증명으로 한다.

// vault_clone { "name": "personal" } →
{
  "clone_url_https": "https://github.com/<owner>/<repo>.git",
  "clone_url_ssh":   "git@github.com:<owner>/<repo>.git",
  "command": "git clone https://github.com/<owner>/<repo>.git ~/vaults/personal"
}

# 반환된 URL 로 직접 clone (GitHub 인증)
git clone https://github.com/<owner>/<repo>.git ~/vaults/personal

인증

GitHub 표준 인증을 그대로 쓴다. ainote MCP 키는 clone/push 에 관여하지 않는다.

• gh auth login (GitHub CLI)
• SSH key — https://github.com/settings/keys 에 등록
• Personal Access Token (PAT) — HTTPS clone 시 비밀번호 대신

표준 git 명령

clone 후엔 그냥 GitHub repo 다:

cd ~/vaults/personal
git log --oneline
git diff
git checkout -b experimental
git push origin experimental
git tag -a v1 -m "snapshot" && git push --tags

특정 시점 복원:

git checkout <tag-or-sha>

ainote MCP 도구(vault_sync 등)는 기본 main 브랜치를 읽고 쓴다. 다른 브랜치는 git CLI 로 직접 다룬다.

다중 디바이스 / 백업

vault 가 이미 GitHub 에 있으므로 GitHub 자체가 원격·백업이다. 새 기기는 vault_clone 이 준 URL 로 clone 하면 된다. 추가로 다른 호스트에 미러하려면 GitHub 를 소스로 두고 미러 push:

cd ~/vaults/personal
git remote add mirror git@gitlab.com:me/notes-mirror.git
git push mirror main       # cron 으로 정기 push

push 는 GitHub 으로, ainote 재인덱싱은 GitHub webhook 으로 자동 처리된다.

크기 / 한도

vault 는 GitHub repo 이므로 GitHub 의 저장소 정책(repo/파일 크기, LFS 등)을 그대로 따른다. ainote 는 인덱스만 유지하므로 별도 vault 용량 한도를 두지 않는다. 대용량 바이너리는 GitHub 권장대로 Git LFS 사용.

관련 도구

• vault_connect_status — GitHub App 설치 여부 확인
• vault_create — 사용자 계정 아래 private repo vault 생성
• vault_clone — vault 의 GitHub clone URL 회수
• vault_sync — vault 파일 read/write (기본 main)