basicmachines-co/basic-memory

AI conversations that actually remember. Never re-explain your project to your AI again. Join our Discord: https://discord.gg/tyvKNccgqN

Basic Memory – LLM을 위한 지속 가능한 검색 가능한 지식

무엇인가요 – Basic Memory는 오픈소스이며, 로컬 우선의 지식 기반으로, 대규모 언어 모델(LLM) 에이전트가 인간이 편집하는 동일한 Markdown 파일을 읽고 쓸 수 있게 해줍니다. 파일은 일반 텍스트이므로 완전한 소유권을 유지할 수 있지만, 의미적 검색 인덱스, wikilink에서 생성된 작은 지식 그래프, 그리고 어떤 AI 클라이언트(Claude, Codex, Cursor, VS Code, ChatGPT 등)도 호출할 수 있는 MCP 호환 도구 세트도 제공합니다.

왜 중요한가요 – 대부분의 LLM 워크플로우는 일시적입니다: 대화가 끝나면 모델은 모든 것을 잊어버립니다. Basic Memory는 대화 기록을 구조화되고 검색 가능한 노트로 전환하여 세션, 기기, 심지어 클라우드 호스팅 동기화를 넘어 지속되도록 합니다. 데이터가 일반 Markdown에 저장되므로, Obsidian, VS Code, Vim 등 어떤 에디터든 사용할 수 있으며, 독점 형식에 갇히지 않습니다.

핵심 기능 (README에 설명됨)

일반 텍스트, 로컬 우선 저장 – 모든 노트는 디스크 상의 일반 Markdown 파일입니다.
양방향 동기화 – 인간이 파일을 편집하고, LLM 에이전트는 MCP 도구를 통해 파일을 생성, 편집, 이동, 삭제할 수 있습니다. 동기화 레이어(옵션 클라우드 서비스)가 여러 기기 간 일관성을 유지합니다.
wikilink을 통한 지식 그래프 – [[링크]] 구문은 모델이 탐색할 수 있는 엔티티와 관계를 생성합니다.
의미적 검색 – 하이브리드 전문 검색 + 벡터 검색(FastEmbed 임베딩)에, 더 높은 품질 결과를 위한 선택적 cross-encoder 재정렬 기능이 포함되어 있습니다.
MCP 네이티브 도구 세트 – write_note, read_note, search_notes, schema_infer 등 각 명령어에 행동 힌트(읽기 전용, 파괴적, 동일성, 오픈월드)가 주어져, 에이전트가 시도 오류 없이 기능을 탐색할 수 있습니다.
클라우드 옵션 – 호스팅 버전(Basic Memory Cloud)은 웹, 모바일, 데스크톱 접근, 자동 백업, rclone 기반 충돌 해결을 제공하며 월 $15(7일 무료 체험, OSS 할인 코드 BMFOSS로 3개월간 20% 할인).
확장 가능한 통합 – Claude Code, Hermes, OpenClaw 공식 플러그인 및 어떤 MCP 호환 에이전트에도 추가 가능한 일반 '스킬' 제공.
스키마 유틸리티 – schema_infer, schema_validate, schema_diff를 통해 노트에 구조를 추론하고 강제할 수 있습니다.
CLI 개선 – JSON 출력, 프로젝트 인식 명령어, 빠른 상태 확인을 위한 대시보드 제공.

시작하기 (빠른 경로)

경로	단계	비용
클라우드	1️⃣ 웹 앱 열기, 2️⃣ AI 클라이언트(Claude, Codex, Cursor 등) 연결	$15/월 (7일 무료 체험, OSS 할인 코드 `BMFOSS`로 3개월간 20% 할인)
로컬 설치	`uv tool install basic-memory --prerelease=allow` (또는 `pip install basic-memory`) → AI 클라이언트의 `mcpServers` 항목 설정 → `bm` 명령어 실행	무료 (AGPL-3.0)

README는 특정 클라이언트(Claude Desktop, Claude Code, Codex CLI, Cursor, VS Code, ChatGPT, Obsidian)에 서버를 추가하는 방법도 보여줍니다. 설정 후 다음과 같은 프롬프트를 입력할 수 있습니다:

우리 프로젝트 아키텍처 결정에 대한 노트를 생성하세요.
내 노트에서 JWT 인증에 대한 정보를 찾아주세요.
지난 주에 무엇을 작업했나요?

LLM은 적절한 Markdown 파일을 자동으로 작성하거나 검색합니다.

일반적인 사용 사례

개인 지식을 위한 RAG – 회의 기록, 설계 결정, 코드 스니펫을 저장하고, 어떤 LLM도 문맥적으로 검색할 수 있도록 합니다.
팀 전체 공유 컨텍스트 – 클라우드 워크스페이스를 통해 모든 팀원이 동일한 노트를 볼 수 있으며, 에이전트는 인간과 봇 간에 작업을 이관할 수 있습니다.
에이전트 주도 문서화 – 코드 변경 시 LLM이 자동으로 문서를 생성하거나 업데이트(write_note, edit_note)할 수 있습니다.
AI 강화 워크플로우의 빠른 프로토타이핑 – Hermes, OpenClaw 등에 MCP 도구를 쉽게 통합해 새로운 API 레이어를 작성할 필요 없이 사용할 수 있습니다.
오프라인 환경 – 보안 기계에서 로컬 버전을 실행; 데이터는 호스트에서 절대 나가지 않습니다.

설치 및 실행 세부 정보

패키지 매니저 – uv를 통한 추천 설치(uv tool install …). PyPI에도 공개(pip install basic-memory).
Python 버전 – Python 3.12 이상 필요.
옵션 벡터 스토어 – 대규모 의미적 인덱스를 위해 milvus 추가 설치(basic-memory[milvus]).
의존성 – FastMCP 3.0, FastEmbed 임베딩, SQLite(기본) 또는 Postgres 벡터 스토어, 대규모 배포용 옵션 Milvus.
실행 – basic-memory mcp로 MCP 서버 시작; CLI(bm …)는 이와 통신. just 레시피(just package-check 등)로 호스트 네이티브 에이전트 패키지가 올바르게 빌드되는지 검증.

라이선스 및 커뮤니티

라이선스 – AGPL-3.0(소스 코드는 자유롭게 이용 가능, 수정 사항은 동일한 라이선스로 공유해야 함).
오픈소스 배지 – PyPI 버전 배지, 테스트 워크플로우 배지, Ruff 린팅 배지, MCP 서버/개발 배지로 CI 활성화 여부를 표시.
커뮤니티 – Model Context Protocol(MCP) 톱리스트에 등재되었으며, DeepWiki에 항목 있음. 사용자(TrainerDay, Caleb Picker Consulting, @groksrc)의 후기들이 README에 포함되어 있음.

결론

Basic Memory는 LLM 에이전트를 위한 실용적이고 파일 기반의 기억 계층을 제공하며, 일반 Markdown을 검색 가능하고 그래프 인식 가능한 지식 기반으로 전환합니다. 인간과 AI 모두가 편집할 수 있습니다. 완전히 로컬에서 무료로 실행하거나, 적은 구독료로 관리형 클라우드 서비스로 사용 가능하여, 개인 개발자, 연구소, 소규모 팀이 AI 워크플로우에 지속적이고 통제 가능한 컨텍스트를 원할 때 이상적입니다.