Basic Memory — 설치·사용 가이드 (공식 문서 한글 정리)

11. 한눈에 보기

▸ 무엇인가요: Basic Memory는 AI와 나눈 내용을 마크다운(Markdown, 간단한 기호로 서식을 적는 텍스트 파일) 파일로 남겨 두고, 다음 대화에서 AI가 그 파일을 다시 읽고 이어 쓰게 해 주는 도구입니다. README의 첫 문구는 "Your AI never forgets again."(AI가 다시는 잊지 않습니다)입니다.
▸ 어디에 연결되나요: Claude, Codex, Cursor, ChatGPT 등 MCP(모델 컨텍스트 프로토콜, AI 앱이 바깥 도구를 쓰도록 이어 주는 공개 규약)를 지원하는 프로그램에 연결합니다.
▸ 만든 곳: Basic Machines (깃허브 basicmachines-co).
▸ 라이선스: AGPL-3.0 (깃허브 저장소 표기).
▸ 사용 방법은 두 가지입니다. 원문은 "둘 다 같은 마크다운 위에서 같은 제품이 돌아간다"고 적고 있습니다.
· 설치판(Local install): 내 컴퓨터에 설치합니다. 무료(AGPL-3.0)이고 모든 데이터가 내 디스크에 남습니다. 인터넷과 끊긴 환경(에어갭)에서도 쓸 수 있다고 적혀 있습니다. 공식 문서에는 계정이 필요 없고 설치 직후 바로 쓸 수 있다고 나와 있습니다.
· 클라우드판(Basic Memory Cloud): 회사가 대신 운영하는 유료 구독입니다. 설치 없이 약 30초 만에 AI를 연결하고, 웹·모바일·데스크톱에서 쓰며, 기기 간 동기화·백업·스냅샷(특정 시점 저장본)을 회사가 맡습니다.
▸ Local-first(로컬 우선)란: README는 "Plain text on your disk. Forever."(내 디스크의 평범한 텍스트, 영원히)라고 설명합니다. 설치판은 파일과 내 컴퓨터의 SQLite(파일 하나로 된 작은 데이터베이스) 색인만 쓰며 별도 서버가 필요 없다고 적혀 있습니다. 설치판의 기본 노트 폴더는 ~/basic-memory 입니다.

22. 이런 분께 맞아요 / 이럴 땐 맞지 않아요

▸ 이런 분께 맞아요 (원문 근거)
· AI와 대화할 때마다 앞서 정한 내용을 다시 설명해야 해서 불편한 분. 원문은 대부분의 AI 대화가 일회성이라 답을 받고 나면 모두 잊힌다고 문제를 짚습니다.
· 내 노트를 내 파일로 직접 갖고 싶은 분. 모든 지식이 내가 관리하는 평범한 파일에 남는다고 적혀 있습니다.
· Obsidian(옵시디언, 마크다운 노트 앱)·VS Code 같은 편집기로 AI가 쓴 노트를 직접 보고 고치고 싶은 분.
· Claude, Codex, Cursor 등 여러 AI 도구에서 같은 기억을 함께 쓰고 싶은 분.
· 팀이 하나의 지식 공간을 함께 쓰고 싶은 경우: 클라우드판의 Basic Memory Teams(공유 클라우드 작업 공간)가 안내되어 있습니다.
▸ 이럴 땐 맞지 않을 수 있어요 (원문의 비교표 기준)
· 터미널·파이썬 설치가 부담스러운 경우: 설치판은 uv를 통한 파이썬이 필요합니다. 원문은 이런 경우 "파이썬·JSON·터미널 없이" 쓰는 클라우드판을 권하지만 이는 유료입니다.
· 무료 설치판으로 휴대폰에서도 쓰고 싶은 경우: 비교표에서 설치판의 모바일 접근은 "No"입니다.
· 여러 컴퓨터 사이 자동 동기화·자동 백업이 꼭 필요한 경우: 설치판은 동기화를 Git·Syncthing 등으로 직접 하고(Manual), 백업도 직접 마련해야(Roll your own) 한다고 적혀 있습니다.
· 인터넷과 완전히 끊긴 환경에서 쓰려는 경우 클라우드판은 맞지 않습니다(비교표의 Air-gapped 항목: 클라우드 No, 설치판 Yes).

33. 시작 전에 준비할 것

▸ 설치판
· 파이썬 3.12 이상: README 배지에 "Python 3.12+", 공식 문서에 "Python 3.12 or higher"라고 적혀 있습니다. 확인 명령:
python --version
· uv(파이썬 프로그램을 설치·실행해 주는 도구): README는 uv를 통해 파이썬이 필요하다고 적고, 공식 문서는 astral.sh 안내(https://docs.astral.sh/uv/getting-started/installation/)에서 uv를 먼저 설치하라고 합니다.
· macOS 사용자는 Homebrew(맥용 프로그램 설치 도구)로 설치하는 방법도 공식 문서에 있습니다.
· 운영체제: README의 연결 표에서 Claude Desktop 항목이 "macOS / Windows / Linux"로 적혀 있습니다.
· MCP를 지원하는 AI 앱: Claude Desktop, Claude Code, Codex, Cursor, VS Code 등.
· 계정: 설치판은 필요 없다고 공식 문서에 적혀 있습니다.
· API 키: 기본 사용에 API 키가 필요하다는 설명은 원문에서 확인되지 않았습니다. 다만 선택 기능인 호스팅 재정렬기(LiteLLM 경유)를 쓰면 COHERE_API_KEY 같은 제공자 키를 환경 변수로 넣는 예시가 README에 있습니다.
· 필요한 메모리·디스크 용량 같은 사양: 원문에서 확인되지 않았습니다.
▸ 클라우드판
· basicmemory.com 가입이 필요합니다. 공식 문서에는 MCP 엔드포인트(AI가 접속하는 주소)를 쓰려면 활성 구독이 필요하다고 적혀 있습니다.
· 7일 무료 체험이 있습니다(자세한 조건은 8번 항목).

44. 설치 방법

▸ 설치판 — README 순서
1) uv를 먼저 설치합니다(위 3번의 astral.sh 안내).
2) README의 설치 명령을 그대로 입력합니다.
uv tool install basic-memory --prerelease=allow
· README 설명: --prerelease=allow 는 필수입니다. Basic Memory 0.23은 FastMCP 4의 사전 출시판(정식 출시 전 버전)에 의존하는데, uv는 따로 지시하지 않으면 하위 의존성의 사전 출시판을 받지 않습니다. 이 플래그가 없으면 경고 없이 더 오래된 버전이 설치됩니다. 아래의 모든 uvx / uv tool upgrade 명령에도 같은 플래그를 붙인다고 적혀 있습니다.
3) Postgres(데이터베이스)를 쓰면서 의미 검색용 벡터를 Milvus(벡터 데이터베이스)에 저장하는 경우에는 대신 아래를 씁니다.
uv tool install "basic-memory[milvus]" --prerelease=allow
▸ macOS — 공식 문서(Quickstart: Local)의 Homebrew 방법
brew tap basicmachines-co/basic-memory
brew trust basicmachines-co/basic-memory
brew install basic-memory
· brew trust 는 이 서드파티 저장소(tap)의 코드를 받아들이는 명령입니다. 옛 Homebrew에는 이 명령이 없으니 그때는 건너뛰라고 적혀 있습니다.
▸ 설치 확인 (공식 문서)
basic-memory --version
· 버전이 최신 릴리스보다 낮으면 bm update 를 실행합니다. bm 은 basic-memory 의 짧은 별칭입니다.
▸ 주의: 공식 문서 빠른 시작 페이지는 uv tool install basic-memory 처럼 --prerelease=allow 없이 적혀 있어 README와 다릅니다. README는 0.23부터 이 플래그가 필수라고 밝히고 있으니 설치 전에 두 원문을 모두 확인하세요.
▸ 클라우드판: 설치가 없습니다. basicmemory.com에서 가입하면 앱이 작업 공간을 준비하고 Getting Started(튜토리얼) 프로젝트를 열어 준다고 공식 문서에 적혀 있습니다.

55. 처음 실행해 보기 (MCP 연결)

▸ Claude Desktop — README
1) 설정 파일을 엽니다. README에 적힌 경로(macOS):
~/Library/Application Support/Claude/claude_desktop_config.json
· 공식 문서(Claude Desktop 연동) 표에는 Windows는 %APPDATA%\Claude\claude_desktop_config.json, Linux는 ~/.config/Claude/claude_desktop_config.json 으로 적혀 있습니다.
2) 아래 내용을 넣습니다(README 그대로).
{
"mcpServers": {
"basic-memory": {
"command": "uvx",
"args": ["--prerelease=allow", "basic-memory", "mcp"]
}
}
}
3) Claude Desktop을 다시 시작합니다. 노트는 기본으로 ~/basic-memory 에 저장됩니다.
▸ Claude Code — README
claude mcp add basic-memory -- uvx --prerelease=allow basic-memory mcp
▸ Codex CLI — ~/.codex/config.toml 에 추가
[mcp_servers.basic-memory]
command = "uvx"
args = ["--prerelease=allow", "basic-memory", "mcp"]
· (선택) 같은 표에 default_tools_approval_mode = "approve" 를 넣으면 도구를 미리 승인합니다. 단 쓰기·수정·삭제 같은 파괴적 도구는 여전히 승인이 필요하다고 적혀 있습니다.
▸ Cursor — .cursor/mcp.json(프로젝트) 또는 ~/.cursor/mcp.json(전체)에 Claude Desktop과 같은 mcpServers 블록을 넣습니다.
▸ VS Code — 사용자 설정(JSON)에 "mcp" → "servers" → "basic-memory" 아래 같은 command·args 를 넣습니다.
▸ ChatGPT — Custom GPT actions용 search·fetch 도구를 제공합니다. 자세한 방법은 공식 ChatGPT 연동 안내를 보라고 적혀 있습니다.
▸ Obsidian — 설정이 필요 없습니다. ~/basic-memory(또는 프로젝트 폴더)를 옵시디언에서 열면 AI가 쓴 위키링크·프런트매터·마크다운이 그래프 보기에 나타납니다.
▸ 연결 확인(공식 문서): Claude Desktop 입력창의 search and tools 메뉴에 Basic Memory 도구가 보이면 됩니다. 이어서 아래처럼 물어보세요.
List my projects
▸ README의 첫 질문 예시
"Create a note about our project architecture decisions."
"Find information about JWT auth in my notes."
"What have I been working on this week?"
▸ 클라우드판 연결(공식 문서): Claude Directory 또는 Settings → Customize → Connectors 에서 Basic Memory Cloud 커넥터를 Install 하고 인증합니다. 직접 등록할 때의 원격 MCP 주소는 https://cloud.basicmemory.com/mcp 입니다.

66. 알아 둘 기능

▸ 사람과 AI가 같은 마크다운을 읽고 쓰는 방식 (README 'How it works')
1) 대화 중에 "Make a note on coffee brewing methods."처럼 노트를 부탁합니다.
2) 프로젝트 폴더에 마크다운 파일이 실시간으로 생깁니다.
3) 다음 대화에서 AI가 파일 속 관계(링크)를 따라가 이미 아는 내용을 찾아 이어 갑니다.
4) 사람은 옵시디언이나 편집기에서 같은 파일을 직접 고칠 수 있고, AI도 그 변경을 봅니다.
· 원문 요약: 사람은 마크다운을 고치고, AI는 MCP로 읽고 쓰며, 동기화가 둘을 맞춰 주고, 기준(정본)은 언제나 내 파일입니다.
▸ 노트 문법: 파일 하나가 Entity(개체)입니다. 개체에는 Observations(사실)와 Relations(다른 개체로 가는 링크)가 있고 "그게 문법의 전부"라고 적혀 있습니다.
· 프런트매터(파일 맨 위 --- 사이의 정보): title, type, permalink, tags
· 관찰 예: - [method] Pour over highlights subtle flavors (대괄호는 분류, # 은 태그)
· 관계 예: - requires [[Burr Grinder]] (위키링크로 지식 그래프를 만듦)
▸ 의미 검색: 키워드가 아니라 뜻으로 노트를 찾습니다. 선택적으로 교차 인코더 재정렬(검색 결과 순서를 한 번 더 매기는 기능)을 켤 수 있으며 기본은 꺼져 있습니다.
export BASIC_MEMORY_RERANKER_ENABLED=true
▸ MCP 도구 (README 분류 그대로)
· Content: write_note, read_note, edit_note, move_note, delete_note, read_content, view_note
· Search & discovery: search_notes, recent_activity, list_directory
· Knowledge graph: build_context (memory:// 주소를 따라감)
· Projects: list_memory_projects, list_workspaces, create_memory_project, delete_project
· Schema: schema_infer, schema_validate, schema_diff
· Compatibility & diagnostics: search, fetch, basic_memory_diagnostics
· 모든 도구에 읽기 전용·파괴적·멱등(여러 번 해도 결과가 같음) 같은 동작 힌트가 붙어 있고, 기본은 텍스트 출력이며 output_format="json" 으로 구조화된 응답을 받습니다.
▸ 주요 명령 (README 'CLI essentials')
basic-memory project list
basic-memory project add research ~/research
basic-memory project set-cloud research
basic-memory status
basic-memory doctor
basic-memory import claude conversations
basic-memory import chatgpt
· set-cloud 는 프로젝트를 클라우드로 돌리고(set-local 로 되돌림), doctor 는 파일과 데이터베이스의 일치 여부를 검사합니다. import 는 Claude·ChatGPT 대화 등을 가져옵니다.
▸ 클라우드판에만 있는 것: 웹·모바일·데스크톱 접근, 로컬 폴더와 양방향 동기화(rclone 기반, 충돌 해결 포함), 특정 시점 복원이 되는 스냅샷·백업, Teams 공유 작업 공간. 언제든 로컬 마크다운으로 내보낼 수 있다고 적혀 있습니다.

77. 막힐 때 / 주의할 점

▸ 설치 플래그: --prerelease=allow 를 빼면 경고 없이 옛 버전이 설치된다고 README에 적혀 있습니다.
▸ ENOENT 오류(공식 문서): Claude Desktop이 uvx 를 찾지 못한다는 뜻입니다. which uvx 로 전체 경로를 찾아 설정의 "command" 값을 그 경로로 바꾸라고 안내합니다.
▸ 도구가 안 보일 때(공식 문서): basic-memory --version 으로 설치 확인 → 설정 파일 JSON 문법 확인 → Claude Desktop 완전히 다시 시작.
▸ 권한 오류(공식 문서 예시 명령):
chmod -R u+rw ~/basic-memory
▸ 변경이 반영되지 않을 때: basic-memory status 로 상태를 보고, 색인이 오래됐으면 bm reindex 로 다시 만듭니다(공식 문서).
▸ 자동 업데이트: uv tool·Homebrew 설치본은 기본으로 24시간마다 업데이트를 확인해 조용히 적용합니다. uvx 는 제외됩니다. 끄려면 ~/.basic-memory/config.json 에 아래를 넣습니다.
{ "auto_update": false }
▸ 텔레메트리(사용 통계 전송): README는 클라우드 홍보 노출, 클라우드 로그인 시도와 결과, 홍보 거부 이벤트를 익명으로 최소 수집하며, 파일 내용·노트 제목·지식 데이터·개인 식별 정보·IP 주소는 수집하지 않는다고 밝힙니다. 끄는 방법:
export BASIC_MEMORY_NO_PROMOS=1
▸ 로그 파일: ~/.basic-memory/basic-memory.log (10MB마다 교체, 10일 보관).
▸ 재정렬기: 켜면 응답이 느려질 수 있고 로컬 방식은 처음 실행할 때 모델을 내려받습니다. 설정이 잘못되면 바로 실패하며 조용히 원래 순서로 돌아가지 않는다고 적혀 있습니다.

88. 라이선스와 비용

▸ 라이선스: AGPL-3.0 (저장소 LICENSE 파일). 상업적 이용 조건에 대한 별도 설명은 README에서 확인되지 않았습니다. AGPL-3.0 전문은 gnu.org에서 확인하세요.
▸ 설치판: 무료입니다. README는 "Free forever (AGPL-3.0)"라고 적고, 공식 가격 페이지도 셀프 호스팅은 전체 앱이 무료 오픈소스(AGPL-3.0)라고 적습니다.
▸ 클라우드판 — README에 적힌 그대로
· $15.00/mo, 구독을 유지하는 동안 이 가격으로 고정(정가 $19). 베타 기간에 가입하면 요금이 오르지 않는다고 적혀 있습니다.
· 연간 결제 시 12.50/mo로 표기되어 있습니다.
· 7일 무료 체험. 맞지 않으면 7일째 전에 언제든 취소할 수 있고, 그 뒤에도 언제든 취소·노트 내보내기가 된다고 적혀 있습니다.
· 오픈소스 사용자: 코드 BMFOSS 로 3개월간 20% 추가 할인(약 $11.40/mo).
· 하나의 플랜, 등급 없음, 노트·프로젝트 무제한이라고 적혀 있습니다. Teams도 "Same pricing"(같은 가격)이며 한 명으로 시작해 늘릴 수 있다고 합니다.
▸ 공식 사이트 가격 페이지(basicmemory.com/pricing)의 표기는 README와 다릅니다.
· Team $15/seat/month (10명 이상 $13, 20명 이상 $12), Business $30/seat/month, Agent Infrastructure는 Custom(크레딧·사용량 기반).
· 모든 클라우드 플랜은 7일 체험으로 시작한다고 적혀 있습니다.
· README의 "One plan, no tiers"와 표기가 다르므로 결제 전에 가격 페이지에서 최신 조건을 확인하세요.
▸ 클라우드판으로 AI를 연결(MCP 엔드포인트 사용)하려면 활성 구독이 필요하다고 공식 문서에 적혀 있습니다.

99. 면책 및 원문 확인

이 문서는 원저자의 공식 사이트와 깃허브 문서를 한국어로 옮겨 정리한 안내입니다. 가고파는 이 소프트웨어를 개발·배포·보증하지 않으며, 설치·사용으로 생기는 결과(데이터 손실, 보안 문제, 비용, 라이선스 위반 등)에 책임지지 않습니다. 번역·요약 과정의 오류가 있을 수 있고 원문은 수시로 바뀌므로, 설치 전에 반드시 아래 원문(공식 사이트·깃허브)에서 최신 내용을 확인하세요. 제휴 링크·광고가 없습니다. 추가 안내: Basic Memory Cloud(클라우드판)는 유료 구독 서비스입니다. 가격·무료 체험 조건·할인 코드(BMFOSS)는 README와 공식 사이트에 공개된 내용을 그대로 옮긴 것이며, 가고파의 제휴 코드가 아닙니다. 가격 표기는 README와 공식 가격 페이지가 서로 다르게 적혀 있으니 결제 전에 공식 가격 페이지를 꼭 확인하세요.

원문 주소(복사해서 브라우저 주소창에 붙여넣기):
· 공식 사이트: https://basicmemory.com
· GitHub 저장소: https://github.com/basicmachines-co/basic-memory
· 공식 문서: https://docs.basicmemory.com

이 자료를 보는 방법

이 안내는 인스타그램 카드·릴스에서 다 담지 못한 내용을 담은 무료 자료입니다. 로그인이나 이메일 확인 없이 바로 읽을 수 있고, 링크는 새 창에서 열립니다.

가고파 생활 가이드 시리즈

이 자료는 가고파(Natas Market)가 생활 주제별로 만들어 두는 무료 DM 자료 중 하나입니다. 인스타그램·스레드 카드뉴스에서 줄인 설명을 여기서 자세히 풀어 씁니다.

각 자료는 카드뉴스 1편과 한 세트입니다. 카드에서 “댓글에 ○○ 남겨주세요”로 안내한 경우, 그 키워드를 남기면 이 자료 링크를 받습니다.

자주 묻는 질문