memory-mcp

개인용 크로스 툴 메모리: 모든 기기의 AI 세션을 검색 가능한 에피소드 아카이브로 저장하고, 큐레이션된 고신뢰 의미적 사실(facts) 계층을 결합하여 MCP 서버로 노출하는 구조입니다. 자체 호스팅 arm64 박스를 대상으로 설계되었으며, WG(WireGuard) 전용 네트워크에서만 동작합니다. 전체 설계는 docs/mcp/memory-mcp-spec.md 문서를 참조하세요.

구성

Related MCP server: Memorium

두 계층, 두 신뢰 수준

• 에피소드 아카이브 (Qdrant memory_archive) : 모든 세션의 모든 청크를 저장합니다. 밀집 벡터(bge-m3, 1024차원)와 희소 벡터(IDF 보정 TF)를 함께 사용하며, RRF로 결합한 하이브리드 검색을 지원합니다. search_archive로 필요할 때만 검색됩니다.

• 의미적 사실 계층 (Postgres) : 출처(provenance)가 명시된 큐레이션 문장들입니다. 기본 조회 대상(search_memory)이며, remember(source: user) 또는 사람의 승인을 거친 증류(source: distilled)로만 저장됩니다 — 증류된 내용은 memoryctl review를 거치기 전에는 활성화되지 않습니다.

MCP 인터페이스

도구(tools): remember, search_memory, search_archive, forget(파괴적이며 쿼리 기반 2단계 진행). 리소스: memory://stats, memory://facts/recent, memory://facts/{id}.

개발

pnpm install
pnpm build        # all packages
pnpm test         # core + server suites (stores are mocked; nothing external touched)
pnpm eval         # golden-set retrieval harness (needs live stores + ingested data)

설정은 환경 변수로 주입되며, packages/core/src/config.ts 파일의 loadConfig가 이 구성을 읽습니다. 세부 항목은 deploy/.env.example을 참조하세요.

운영

cd deploy && cp .env.example .env   # fill in POSTGRES_PASSWORD, STATIC_BEARER, keys
docker compose -f compose.prod.yaml up -d --build
docker compose -f compose.prod.yaml exec memory-mcp memoryctl init
docker compose -f compose.prod.yaml exec memory-mcp memoryctl verify

compose.prod.yaml은 Qdrant와 OpenAI 호환 LLM 게이트웨이가 호스트에서 별도의 외부 컨테이너로 이미 실행 중인 것을 전제합니다. networks: 섹션의 name: 필드를 실제 Docker 네트워크 이름과 일치하도록 수정하세요.

일별 ingest+distill와 야간 백업은 systemd 타이머(deploy/systemd/)로 실행됩니다. 백업은 14일 후 만료되므로 forget으로 삭제된 데이터가 그 기간 내 백업에도 반영되어 제거됩니다.

보안 태세

• WG 전용 바인딩(bind), 정적 베어러(베어러, v1)를 사용합니다. 서버 앞에 호환 가능한 OIDC/JWT 게이트웨이를 갖추게 되면, 게이트웨이 JWT 인증 방식(Step 8)을 향후 인증 모드로 추가할 예정입니다.

• 스크럽(gitleaks + 커스텀 정규식)은 fail-closed 방식이며, 임베딩 또는 저장 전에 반드시 실행됩니다. 파싱 불가한 입력이 있는 파일 전체를 격리하며(원장에 기록), transient인프라 장애업(embedder, Qdrant, gitleaks 사용 불가)는 아무 기록 없이 안전하게 롤백되고 다음 실행에서 파일을 재시도합니다.

• forget은 두 저장소 모두에서 완전 삭제(hard delete) 됩니다.

• 아카이브 청크는 신뢰할 수 없는 데이터 구분자(untrusted-data delimiters) 안에 감싸 반환됩니다 — 과거 대화 기록에는 마치 명령처럼 보이는 텍스트가 포함될 수 있으므로 반드시 데이터로 취급해야 합니다.

취약점 신고는 SECURITY.md 문서를 참조하세요.

기여

이슈와 PR은 언제든 환영합니다. 개발 환경 설정과 프로젝트 규칙은 CONTRIBUTING.md, 변경 이력은 CHANGELOG.md를 참고하세요. 이 프로젝트는 [행동 코드] ( CODE_OF_CONDUCT.md)를 따릅니다.

라이선스

MIT