MemoryMesh

개인 데이터를 위한 범용 MCP 허브. 로컬 우선, 기본적으로 비공개이며, 앞으로 구축할 에이전트의 메모리 계층으로 설계되었습니다.

MemoryMesh는 로컬 파일을 인덱싱하며(향후 버전에서는 이메일, 캘린더, 브라우저 기록, 채팅 로그도 지원 예정), Model Context Protocol을 통해 이를 노출합니다. MCP를 지원하는 모든 클라이언트(Claude Desktop, Cursor, Claude Code 또는 직접 만든 에이전트)는 데이터를 클라우드로 단 1바이트도 전송하지 않고도 사용자가 실제로 소유한 데이터에 대해 의미론적 질문을 할 수 있습니다.

이것은 단일 목적의 RAG가 아닌 허브입니다. 전송, 임베딩 모델, 파서, 청킹 전략 모두 깔끔한 인터페이스 뒤에서 교체 가능하므로, 동일한 허브가 "내 메모 검색"에서 "내 에이전트 OS를 위한 모든 것 기억하기"로 성장할 수 있습니다.

왜 이 프로젝트가 존재하는가

개인 데이터는 수십 개의 앱에 파편화되어 있습니다. 어떤 AI 에이전트도 통합되고 비공개적인 방식으로 이 모든 데이터에 접근할 수 없습니다. Anthropic의 MCP는 프로토콜을 정의했고, MemoryMesh는 모든 것을 연결하는 허브의 공백을 메웁니다. 설정이 아닌 전제 조건으로서의 개인정보 보호를 갖춘 로컬 허브입니다.

Related MCP server: NOUZ MCP Server

작동 방식

                   ┌──────────────────────────────┐
  MCP clients ───▶ │         MemoryMesh           │
(Claude Desktop,   │  ┌────────────────────────┐  │
 Cursor, agents)   │  │ MCP Tools (FastMCP):   │  │
                   │  │  search_memory         │  │
                   │  │  list_sources          │  │
                   │  │  get_document          │  │
                   │  │  index_now             │  │
                   │  └──────────┬─────────────┘  │
                   │             ▼                 │
                   │     Search Engine             │
                   │   dense + BM25 → RRF          │
                   │             │                 │
                   │   ┌─────────┴──────────┐      │
                   │   ▼                    ▼      │
                   │ ChromaDB            BM25      │
                   │ (embeddings)     (sparse)     │
                   │   ▲                    ▲      │
                   │   └──────── Indexer ───┘      │
                   │                ▲              │
                   │           Watchdog            │
                   └────────────────┬──────────────┘
                                    ▼
                             Your filesystem

인덱싱 파이프라인: 파일 감시자가 변경 사항 감지 → SHA-256 중복 제거로 변경되지 않은 파일 건너뜀 → 파서(txt/md/pdf/docx/코드) → 스마트 청커(코드용 tree-sitter, 마크다운용 제목별, 텍스트용 재귀적) → sentence-transformers를 통한 임베딩 → ChromaDB + BM25 인덱스에 upsert.

검색 파이프라인: 쿼리 → dense 검색(ChromaDB) + sparse 검색(BM25) 오버패치 → Reciprocal Rank Fusion (k=60) → 경로, 미리보기, 점수 및 메타데이터가 포함된 상위 k개 결과.

차별점

대부분의 유사 도구들은 최적화할 한 가지 차원만 선택합니다. MemoryMesh는 다음 모든 요소를 동시에 충족하는 유일한 도구입니다:

MCP 네이티브란 나중에 덧붙인 것이 아니라 처음부터 MCP를 위해 구축되었음을 의미합니다. 4개의 도구(search_memory, list_sources, get_document, index_now)는 버전 간에 깨지지 않는 안정적인 API를 가집니다.

인프라로 설계됨이란 아키텍처가 다중 에이전트 액세스, 에이전트별 권한, 동일한 허브를 쿼리하는 하드웨어 에이전트(ESP32, Arduino)를 예상하고 있음을 의미합니다. 로드맵을 참조하세요.

상태

퀵스타트

전제 조건: Python 3.11+ 및 uv.

# Install from PyPI
pip install memorymesh-mcp

또는 개발을 위해 복제하세요:

# Clone and install
git clone https://github.com/kilhubprojects/memory-mesh.git
cd memory-mesh
uv sync

# Initialize state directory and copy example config
uv run memorymesh init

# Edit config.yaml — point it at the folders you want indexed
# (see Configuration section below)

# Index a folder
uv run memorymesh index ~/Documents

# Test a search
uv run memorymesh search "how did I configure the debounce"

데몬으로 실행 (실시간 인덱싱)

uv run memorymesh start --transport streamable-http --detach
uv run memorymesh status
# edit a file in one of your sources — it gets indexed within ~2s
uv run memorymesh search "the sentence you just typed"
uv run memorymesh stop

Claude Desktop에 연결

Claude Desktop 설정에 추가하세요:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "memorymesh": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/absolute/path/to/memory-mesh",
        "memorymesh", "serve", "--stdio"
      ]
    }
  }
}

Claude Desktop을 재시작하세요. 4개의 도구가 자동으로 나타납니다.

MCP 도구

모든 도구는 하위 호환됩니다. v0.1 시그니처는 고정되어 있으며, v0.2에서 extended_preview를 추가하는 것은 기존 기능을 깨뜨리지 않는 추가 사항입니다.

구성

모든 설정은 config.yaml에 있습니다. 완전히 주석 처리된 참조는 config.example.yaml을 참조하세요. 주요 하이라이트:

sources:
  - name: documents
    path: ~/Documents
    recursive: true
    extensions: [.txt, .md, .pdf, .docx]

  - name: projects
    path: ~/Projects
    recursive: true
    extensions: [.py, .js, .ts, .go, .rs, .md]

embeddings:
  model: all-MiniLM-L6-v2   # swap to paraphrase-multilingual-MiniLM-L12-v2 for PT/EN

search:
  mode: hybrid               # hybrid | dense | sparse
  top_k: 10

server:
  transport: stdio           # stdio | streamable-http

전역 무시 목록은 기본적으로 민감한 경로를 보호합니다: .env, *.key, id_rsa*, secrets/, .ssh/, .aws/, .git/, node_modules/.

벤치마크

벤치마크는 v0.2가 세 플랫폼 모두에서 CI를 통과한 후 여기에 게시될 예정입니다. 목표는 "내 컴퓨터에서 빠르다"가 아닌 재현 가능한 수치입니다.

스크립트는 이미 benchmarks/에 있으며 로컬에서 실행 가능합니다:

• bench_indexing.py — 합성 코퍼스에서의 인덱싱 처리량 (청크/초, MB/초)

• bench_search_latency.py — 하이브리드/dense/sparse 모드 전반의 p50/p95/p99 검색 지연 시간

• bench_embedding_models.py — 세 가지 임베딩 모델 간의 속도 대 품질 비교

개인정보 보호 및 보안

버전이 바뀌어도 변하지 않는 세 가지 확고한 약속:

1. 데이터는 기기를 떠나지 않습니다. 텔레메트리 없음. 명시적으로 동의하지 않는 한 외부 API 호출이 없으며, 호출하더라도 로그에 WARNING이 표시됩니다.

2. HTTP 리스너는 기본적으로 127.0.0.1에만 바인딩됩니다. 다른 인터페이스에 노출하려면 명시적인 구성 재정의가 필요합니다.

3. 로그에는 일반 텍스트로 된 문서 내용이나 쿼리가 포함되지 않습니다. 감사 로그는 쿼리가 아닌 쿼리 해시를 기록합니다.

저장 데이터 암호화는 로드맵에 있습니다. OS 수준에서 디스크가 암호화되어 있다면 MemoryMesh가 설계된 위협 모델에 대해 보호받고 있는 것입니다.

로드맵

자세한 내용은 ROADMAP.md를 참조하세요.

문제 해결

• 텍스트 파일에서 UnicodeDecodeError 발생 — MemoryMesh는 UTF-8, UTF-8 BOM, cp1252, latin-1 순서로 시도합니다. 여전히 실패하면 로그에 기록되고 건너뛰며, 충돌하지 않습니다.

• 네트워크 드라이브 / WSL 마운트에서 감시자가 작동하지 않음 — config.yaml에서 watcher.use_polling: true로 설정하세요.

• Tesseract를 찾을 수 없음 — 시스템 전체에 설치하고 PATH에 있는지 확인하세요. Windows: UB-Mannheim 설치 프로그램.

• 구성 변경 후 임베딩 모델 불일치 — memorymesh reindex --all을 실행하세요. ChromaDB에 저장된 모델 ID가 구성과 일치하지 않으면 CLI가 시작을 거부합니다.

이 프로젝트에 대하여

MemoryMesh는 **바이브 코딩(vibe coding)**을 사용하여 구축된 개인 프로젝트입니다. LLM과 긴밀하게 협력하여 고속으로 코드를 작성하고, 각 단계에서 구조화된 아키텍처 검토를 거쳤습니다. 프로세스: LLM이 코드를 제안하고, 아키텍트가 정확성, 설계 격차, 사양 위반을 검토하며, 테스트 스위트가 확인합니다. (재조정 시스템의 시작 순서, BM25 캡슐화 위반, CLI의 잘못된 생성자 kwargs 등) 빠져나간 버그들은 프로덕션에서 실행되기 전에 검토 과정에서 포착되었습니다.

이것이 검토 단계를 진지하게 받아들일 때의 바이브 코딩 모습입니다: 172개의 테스트 스위트, 실제 하이브리드 검색 파이프라인, 재조정 시스템, 그리고 에이전트 OS로 이어지도록 설계된 아키텍처.

기여

MemoryMesh는 아직 외부 기여를 받지 않습니다. 아직 CI나 기여 가이드가 마련되지 않았습니다. 이는 v0.2에서 변경될 예정입니다. 저장소를 지켜보거나 그때 다시 확인해 주세요.

라이선스

MIT. LICENSE를 참조하세요.

감사의 말

아키텍처는 LlamaIndex, LangChain, PrivateGPT, AnythingLLM, MemGPT, Haystack을 연구하여 각 도구가 무엇을 잘하고 무엇을 못하는지 이해함으로써 정보를 얻었습니다. 또한 MCP 네이티브가 실제로 어떤 모습인지 보여준 chroma-mcp와 MCP Python SDK에 감사드립니다.