uvx mnemory

uvx --with "mcp<2" mnemory

{

<p align="center">
  <img src="https://raw.githubusercontent.com/fpytloun/mnemory/HEAD/files/screenshots/ui-dashboard.jpg" alt="대시보드 — 메모리 총량, 세부 분류 및 운영 횟수" width="800" />
  <br><em>유형별, 카테고리별, 역할별로 구분된 메모리 대시보드</em>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/fpytloun/mnemory/HEAD/files/screenshots/ui-search.jpg" alt="검색 — 필터가 적용된 시맨틱 및 AI 기반 검색" width="800" />
  <br><em>필터를 사용한 시맨틱 검색 및 AI 기반 찾기 기능</em>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/fpytloun/mnemory/HEAD/files/screenshots/ui-graph.jpg" alt="그래프 — D3.js 포스 다이렉티드 메모리 관계 시각화" width="800" />
  <br><em>메모리 관계 그래프 시각화</em>
</p>

[모든 스크린샷 및 UI 기능](docs/management-ui.md)을 참고하세요. 여기에는 메모리 브라우저, 상태 확인(health checks), 아티팩트 관리 등이 포함됩니다.

## 지원 클라이언트 (Supported Clients)

mnemory는 모든 MCP 호환 클라이언트와 작동합니다. 일부 클라이언트는 자동 회상/기억을 위한 전용 플러그인도 제공합니다.

| 클라이언트 | MCP | 플러그인 | 설정 가이드 |
|---|---|---|---|
| Claude Code | 예 (Yes) | 예 (Yes) ([hooks](integrations/claude-code/)) | [가이드](docs/clients/claude-code.md) |
| ... | | | |

**MCP** = Model Context Protocol을 통해 작동합니다 (LLM 기반 툴 호출). **플러그인(Plugin)** = 자동 회상/기억을 위한 전용 통합 기능입니다 (LLM 툴 호출 불필요).

## 작동 방식 (How It Works)

**저장(Storing):** 사용자는 정보를 자연스럽게 공유합니다. mnemory는 개별 사실들을 추출하고, 이를 분류하며(유형, 카테고리, 중요도), 기존 메모리와 중복 및 모순 여부를 확인한 후, 검색 가능한 벡터 형태로 모두 단일 LLM 호출 내에 저장합니다.

**검색(Searching):** 질문을 하면 mnemory는 다양한 각도와 연관성을 포괄하는 여러 개의 검색 쿼리를 생성하고, 이를 병렬로 실행하며, 관련성에 따라 결과를 재정렬(rerank)합니다. 시간 인식 기능이 있어

**기억 회상 (Recalling):** 대화 시작 시, 에이전트는 고정된 기억(핵심 사실, 선호도, 정체성)과 최근 컨텍스트를 로드합니다. 대화 중에는 논의하는 내용에 기반하여 관련 기억들이 자동으로 찾아집니다.

**기억 유지 (Maintaining):** 기억은 설정 가능한 TTL(Time-To-Live)을 가집니다 — 컨텍스트는 7일, 에피소드적 기억은 90일 후에 만료됩니다. 자주 접근하는 기억은 살아남습니다 (강화). 내장된 건강 검사기(health checker)는 중복, 모순, 품질 문제를 감지하고 수정합니다.

자세한 내용은 [아키텍처 문서](docs/architecture.md)를 참고하세요.

## 벤치마크 (Benchmark)

[LoCoMo](https://github.com/snap-research/locomo) 벤치마크에서 평가되었습니다 — 4가지 카테고리에 걸쳐 1540개의 QA 질문을 포함하는 10개의 다중 세션 대화:

| 시스템 | single_hop | multi_hop | temporal | open_domain | Overall |
|---|---|---|---|---|---|
| **mnemory** | **63.1** | **53.1** | **74.8** | **78.2** | **73.2** |
| ... | 

설정: 추출을 위해 `gpt-5-mini`, 벡터를 위해 `text-embedding-3-small` 사용. Groq를 통한 `gpt-oss-120b`는 품질이 유사하면서 비용은 약 5배 낮은 예산 대안입니다. 모델 옵션 및 재현을 위한 [`벤치마크/`](benchmarks/) 정보는 [설정 문서](docs/configuration.md#model-selection)를 참조하세요.

## 문서 (Documentation)

| 문서 | 설명 |
|---|---|
| [Quick Start](docs/quickstart.md) | 모든 클라이언트에서 5분 만에 실행 가능 |
| ... | 
## 라이선스 (License)

Apache 2.0