<p align="center">
  <img src="../assets/hero-banner-dark.svg" alt="TrueMemory" width="800">
</p>

<p align="center">
  <em>당신의 AI가 처음부터 가지고 있었어야 할 기억.</em>
</p>

<p align="center">
  <a href="../README.md"><img alt="English" src="https://img.shields.io/badge/English-d9d9d9"></a>
  <a href="./README.zh-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/简体中文-d9d9d9"></a>
  <a href="./README.hi.md"><img alt="हिन्दी" src="https://img.shields.io/badge/हिन्दी-d9d9d9"></a>
  <a href="./README.es.md"><img alt="Español" src="https://img.shields.io/badge/Español-d9d9d9"></a>
  <a href="./README.fr.md"><img alt="Français" src="https://img.shields.io/badge/Français-d9d9d9"></a>
  <a href="./README.ar.md"><img alt="العربية" src="https://img.shields.io/badge/العربية-d9d9d9"></a>
  <a href="./README.bn.md"><img alt="বাংলা" src="https://img.shields.io/badge/বাংলা-d9d9d9"></a>
  <a href="./README.pt-BR.md"><img alt="Português" src="https://img.shields.io/badge/Português-d9d9d9"></a>
  <a href="./README.ru.md"><img alt="Русский" src="https://img.shields.io/badge/Русский-d9d9d9"></a>
  <a href="./README.ja.md"><img alt="日本語" src="https://img.shields.io/badge/日本語-d9d9d9"></a>
  <a href="./README.ko.md"><img alt="한국어" src="https://img.shields.io/badge/한국어-d9d9d9"></a>
  <a href="./README.de.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>
  <a href="./README.id.md"><img alt="Bahasa Indonesia" src="https://img.shields.io/badge/Indonesia-d9d9d9"></a>
  <a href="./README.vi.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/Tiếng Việt-d9d9d9"></a>
  <a href="./README.tr.md"><img alt="Türkçe" src="https://img.shields.io/badge/Türkçe-d9d9d9"></a>
  <a href="./README.it.md"><img alt="Italiano" src="https://img.shields.io/badge/Italiano-d9d9d9"></a>
  <a href="./README.th.md"><img alt="ไทย" src="https://img.shields.io/badge/ไทย-d9d9d9"></a>
  <a href="./README.pl.md"><img alt="Polski" src="https://img.shields.io/badge/Polski-d9d9d9"></a>
  <a href="./README.uk.md"><img alt="Українська" src="https://img.shields.io/badge/Українська-d9d9d9"></a>
  <a href="./README.nl.md"><img alt="Nederlands" src="https://img.shields.io/badge/Nederlands-d9d9d9"></a>
</p>

<p align="center">
  <a href="https://github.com/buildingjoshbetter/TrueMemory"><img src="https://img.shields.io/github/stars/buildingjoshbetter/TrueMemory?style=social" alt="Stars"></a>
  <a href="https://pypi.org/project/truememory/"><img src="https://img.shields.io/badge/installs-7.3k+-brightgreen" alt="Installs"></a>
  <a href="https://arxiv.org/abs/2605.04897"><img src="https://img.shields.io/badge/arXiv-2605.04897-b31b1b" alt="arXiv"></a>
  <a href="https://discord.gg/ZJ74JB2gVW"><img src="https://img.shields.io/badge/Discord-Join%20us-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/LoCoMo-93.0%25-blueviolet" alt="LoCoMo">
  <img src="https://img.shields.io/badge/LongMemEval-92.0%25-blue" alt="LongMemEval">
  <img src="https://img.shields.io/badge/BEAM--1M-76.6%25_(SOTA)-orange" alt="BEAM-1M">
</p>

<p align="center">
  <a href="#왜-truememory인가">왜</a> · <a href="#빠른-시작">빠른 시작</a> · <a href="#truememory-비교">비교</a> · <a href="#티어">티어</a> · <a href="#벤치마크">벤치마크</a> · <a href="#python-api">API</a> · <a href="#문서">문서</a> · <a href="#자주-묻는-질문">FAQ</a>
</p>

<p align="center">
  <img src="../assets/terminal-demo.svg" alt="TrueMemory terminal demo" width="750">
</p>

---

## 왜 TrueMemory인가

**노이즈 속에서 신호를 찾아냅니다.** AI는 수천 개의 메시지를 봅니다. TrueMemory는 어떤 것이 실제로 중요한지 파악하고 나머지는 버립니다. 수동 태깅도, 프롬프트 엔지니어링도 필요 없습니다. 그냥 알아냅니다.

**시간이 지날수록 더 정확해집니다.** 정적인 데이터베이스가 아닙니다. 당신과 함께 성장하는 살아있는 기억입니다. 생각이 바뀌면 모순을 해결하고, 오래된 사실을 업데이트하며, 알고 있는 것을 통합합니다. 오래 사용할수록 더 좋아집니다.

**생각할 필요 없이 작동합니다.** TrueMemory는 대화에서 자동으로 기억을 캡처하고 다음 세션에 올바른 기억을 자동으로 주입합니다. 수동으로 저장하거나 검색할 필요가 없습니다. 그냥 일어납니다.

**100% 로컬입니다.** 머신에 있는 하나의 SQLite 파일. 기기 밖으로 아무것도 나가지 않습니다. 클라우드 없음, API 키 불필요. 당신의 데이터는 당신의 것입니다.

> **TrueMemory 없이:** "어떤 프레임워크를 쓰고 있나요?" 이번 주에 12번째 질문. 에이전트는 매 세션을 기억상실 상태로 시작합니다. 당신의 이름도, 스택도, 어제 말한 것도 아무것도 모릅니다.
>
> **TrueMemory와 함께:** 에이전트는 이미 당신이 FastAPI를 사용하고, Pydantic v2를 선호하며, auth 미들웨어가 `src/auth/`에 있다는 것을 알고 있습니다. 당신의 수정 사항, 선호도, 결정 사항을 모든 세션에 걸쳐 영원히 기억합니다.

---

## TrueMemory 비교

| 시스템 | LoCoMo | LongMemEval | 로컬 우선 | 자동 캡처 | 라이선스 |
|--------|--------|-------------|:-----------:|:------------:|---------|
| **TrueMemory Pro** | **93.0%** | **92.0%** | ✅ | ✅ | AGPL-3.0 |
| **TrueMemory Base** | **87.7%** | **84.1%** | ✅ | ✅ | AGPL-3.0 |
| Mem0 | 61.4% | — | 부분적 | ❌ | Apache-2.0 |
| Supermemory | 65.4% | — | ❌ | ❌ | Cloud API |
| MemOS | 75.8% | — | ✅ | ❌ | Apache-2.0 |
| ReadAgent | 79.5% | — | ❌ | ❌ | Research |

> 모든 벤치마크는 독립적으로 재현 가능합니다. 스크립트는 [`benchmarks/`](../benchmarks/)에 포함되어 있습니다.

---

## 빠른 시작

### Claude Code / Claude CLI / Cursor / Codex CLI / Gemini CLI용

```bash
curl -LsSf https://raw.githubusercontent.com/buildingjoshbetter/TrueMemory/main/install.sh | sh
```

> 격리된 환경에 모든 것을 설치합니다. ~1.5GB의 AI 모델을 다운로드합니다. 어떤 데이터도 머신 밖으로 나가지 않습니다. sudo가 필요 없습니다.

<details><summary>터미널이 처음이신가요? 단계별 안내를 보려면 여기를 클릭하세요.</summary>

1. **터미널을 엽니다:** Mac: `Cmd + Space`에서 `Terminal` 입력. Linux: `Ctrl + Alt + T`. Windows: PowerShell 열기.
2. **위 명령어를 붙여넣고** Enter를 누릅니다.
3. **모델 다운로드에 3-5분 기다립니다.**
4. **AI 도구를 완전히 종료하고** 다시 엽니다 (Mac: `Cmd+Q`).
5. **"Set up TrueMemory"를 입력하고** 티어를 선택합니다.

**Windows (PowerShell):**
```powershell
irm https://raw.githubusercontent.com/buildingjoshbetter/TrueMemory/main/install.ps1 | iex
```

</details>

끝입니다. TrueMemory는 이제부터 대화를 자동으로 기억합니다.

### 개발자용 (Python 라이브러리)

```bash
pip install truememory
```

```python
from truememory import Memory

m = Memory()
m.add("Prefers dark mode and TypeScript", user_id="alex")
print(m.search("preferences", user_id="alex"))
```

---

## 티어

같은 아키텍처, 세 가지 티어. 모두 한 번의 설치에 포함됩니다. "switch to Pro" 또는 "switch to Base"라고 말하면 언제든지 전환할 수 있습니다.

| | Edge | Base | Pro |
|---|------|------|-----|
| **LoCoMo** | 89.6% | 92.0% | **93.0%** |
| **LongMemEval** | — | — | **92.0%** |
| **BEAM-1M** | — | — | **76.6% (SOTA)** |
| **임베딩 모델** | 8 MB 경량 | 600 MB 고정밀 | 600 MB 고정밀 |
| **리랭커** | 22M 파라미터 | 149M 파라미터 | 149M 파라미터 |
| **HyDE 검색** | — | — | ✅ (LLM API 키 필요) |
| **실행 환경** | 모든 머신, CPU만 | 4 GB+ RAM | 4 GB+ RAM + API 키 |

**Edge**는 어디서든 작동합니다. **Base**는 완전히 오프라인인 가장 강력한 티어입니다. **Pro**는 최고 점수를 위한 AI 기반 쿼리 확장을 추가합니다.

---

## 벤치마크

<p align="center">
  <img src="../assets/charts/leaderboard-bar.png" alt="Benchmark Leaderboard" width="700" />
</p>

세 가지 주요 벤치마크에서 테스트되었으며, 모든 시스템이 동일한 답변 모델(GPT-4.1-mini), 심사 모델(GPT-4o-mini, 3회 다수결), 스코어링 파이프라인을 공유합니다.

| 벤치마크 | 테스트 내용 | TrueMemory Pro |
|-----------|--------------|:--------------:|
| [LoCoMo](https://github.com/snap-research/locomo) | 10개 대화에 걸친 1,540개 질문 | **93.0%** |
| [LongMemEval](https://github.com/xiaowu0162/LongMemEval) | 500개 멀티세션 질문 | **92.0%** |
| [BEAM-1M](https://github.com/mohammadtavakoli78/BEAM) | 1M+ 토큰에서 700개 질문 | **76.6% (SOTA)** |
| BEAM-10M | 10M 토큰에서 200개 질문 | **65.0%** |

### 모든 결과를 직접 재현하세요

모든 벤치마크 스크립트는 독립 실행형이며 [Modal](https://modal.com)에서 실행됩니다.

- **[LoCoMo 스크립트](../benchmarks/locomo/scripts/)** — 8개 시스템 (TrueMemory, Mem0, Zep, Engram 등)
- **[LoCoMo 결과](../benchmarks/locomo/BENCHMARK_RESULTS.md)** — 카테고리별 분석, 레이턴시, 비용
- **[LoCoMo 평가 설정](../benchmarks/locomo/EVAL_CONFIG.md)** — 정확한 모델, 프롬프트, 파라미터
- **[LongMemEval 스크립트](../benchmarks/longmemeval/)** — oracle + strict 변형
- **[LongMemEval 결과](../benchmarks/longmemeval/results/)** — TM Pro 6회 실행 + 경쟁사 5개 결과
- **[BEAM-1M 스크립트](../benchmarks/beam/bench_truememory_pro_beam1m.py)** — 1M+ 토큰에서 35개 대화
- **[BEAM-10M 스크립트](../benchmarks/beam/bench_truememory_pro_beam10m.py)** — 10M 토큰에서 10개 대화
- **[BEAM 결과](../benchmarks/beam/)** — 3회 실행 (1M) + 1회 실행 (10M)

모든 벤치마크는 동일한 평가 파이프라인을 사용합니다. 숨겨진 것은 없습니다. 전체 세부사항: [LoCoMo](../benchmarks/locomo/EVAL_CONFIG.md) | [LongMemEval](../benchmarks/longmemeval/README.md) | [BEAM](../benchmarks/beam/README.md)

---

## 호환 도구

<p align="center">
  <strong>Claude Code</strong> · <strong>Claude CLI</strong> · <strong>Cursor</strong> · <strong>Codex CLI</strong> · <strong>Gemini CLI</strong> · <strong>Claude Desktop</strong>
</p>

라이프사이클 훅이 대화를 자동으로 캡처합니다. 수동 작업이 필요 없습니다. 기억은 하나의 SQLite 파일에 로컬로 보관됩니다.

---

## Python API

```python
from truememory import Memory

m = Memory()

m.add("Prefers dark mode and TypeScript", user_id="alex")
m.add("Works at Anthropic as a senior engineer", user_id="alex")

results = m.search("What are Alex's preferences?", user_id="alex")
results = m.search_deep("career history?", user_id="alex")  # multi-round, higher accuracy
```

| 메서드 | 설명 |
|--------|-------------|
| `m.add(content, user_id)` | 기억 저장 |
| `m.search(query, user_id)` | 검색 (6단계 파이프라인 + 리랭커) |
| `m.search_deep(query, user_id)` | 멀티라운드 에이전트 검색 |
| `m.get(id)` / `m.get_all(user_id)` | 기억 가져오기 |
| `m.update(id, content)` / `m.delete(id)` | 수정 또는 삭제 |
| `m.stats()` | 시스템 통계 |

[전체 API 레퍼런스 →](../docs/python-api.md)

---

## 문서

| | |
|---|---|
| [시작하기](../docs/guides/getting-started.md) | 설치부터 첫 번째 기억까지 |
| [Python API 레퍼런스](../docs/python-api.md) | `Memory` 클래스 전체 레퍼런스 |
| [MCP 도구 레퍼런스](../docs/mcp-tools.md) | 8개 MCP 도구 전체 |
| [CLI 레퍼런스](../docs/cli.md) | `truememory-mcp` 및 `truememory-ingest` |
| [환경 변수](../docs/env-vars.md) | 모든 `TRUEMEMORY_*` 설정 옵션 |
| [아키텍처 심층 분석](../docs/architecture.md) | 6단계 검색 파이프라인, 인코딩 게이트 |
| [티어 선택 가이드](../docs/guides/tier-selection.md) | Edge vs Base vs Pro |
| [디버깅](../docs/guides/debugging.md) | 로그, 트레이스, 일반적인 문제 |

---

## 자주 묻는 질문

<details><summary><strong>데이터는 어디에 저장되나요? 클라우드로 전송되는 것이 있나요?</strong></summary>

모든 것은 `~/.truememory/memories.db`에 로컬로 저장됩니다. Edge와 Base 티어는 외부 호출을 전혀 하지 않습니다. Pro는 쿼리 확장을 위해 검색 쿼리 텍스트만 LLM에 전송합니다. 기억 내용은 절대 전송되지 않습니다.
</details>

<details><summary><strong>Python이 설치되어 있어야 하나요?</strong></summary>

아니요. 설치 프로그램은 [uv](https://docs.astral.sh/uv/)를 사용하여 샌드박스된 Python 3.12을 관리합니다. 시스템 Python은 건드리지 않습니다.
</details>

<details><summary><strong>더 큰 컨텍스트 윈도우를 사용하면 안 되나요?</strong></summary>

컨텍스트 윈도우는 비용이 많이 들고, 느리며, 매 세션 시작 시 비어 있습니다. TrueMemory는 컨텍스트 토큰 제로, 200ms 미만으로 즉각적인 리콜을 제공합니다.
</details>

<details><summary><strong>TrueMemory는 텔레메트리를 수집하나요?</strong></summary>

익명 사용 텔레메트리(도구 호출, 세션 수, 플랫폼 정보)가 기본적으로 활성화되어 있습니다. 기억 내용, 쿼리, 파일 경로, API 키는 **절대** 추적하지 않습니다. 비활성화: `export TRUEMEMORY_TELEMETRY=off`
</details>

---

## 60초 만에 시작하기

```bash
pip install truememory
```

질문이 있으신가요? [토론을 열어주세요](https://github.com/buildingjoshbetter/TrueMemory/discussions). TrueMemory가 시간을 절약해 주었다면, [별을 남겨주세요 ⭐](https://github.com/buildingjoshbetter/TrueMemory)

---

## 기여자분들께 감사드립니다

<table>
  <tr>
    <td align="center"><a href="https://github.com/buildingjoshbetter"><img src="https://avatars.githubusercontent.com/u/236675935?v=4" width="80" alt="buildingjoshbetter"/><br><sub>buildingjoshbetter</sub></a></td>
    <td align="center"><a href="https://github.com/SoilChang"><img src="https://avatars.githubusercontent.com/u/12407044?v=4" width="80" alt="SoilChang"/><br><sub>SoilChang</sub></a></td>
    <td align="center"><a href="https://github.com/Huntehhh"><img src="https://avatars.githubusercontent.com/u/66277108?v=4" width="80" alt="Huntehhh"/><br><sub>Huntehhh</sub></a></td>
    <td align="center"><a href="https://github.com/mseep-ai"><img src="https://avatars.githubusercontent.com/u/207640208?v=4" width="80" alt="mseep-ai"/><br><sub>mseep-ai</sub></a></td>
    <td align="center"><a href="https://github.com/adityajha2005"><img src="https://avatars.githubusercontent.com/u/147301021?v=4" width="80" alt="adityajha2005"/><br><sub>adityajha2005</sub></a></td>
    <td align="center"><a href="https://github.com/shivamverma1999"><img src="https://avatars.githubusercontent.com/u/33162868?v=4" width="80" alt="shivamverma1999"/><br><sub>shivamverma1999</sub></a></td>
    <td align="center"><a href="https://github.com/Adarsh-031"><img src="https://avatars.githubusercontent.com/u/185399508?v=4" width="80" alt="Adarsh-031"/><br><sub>Adarsh-031</sub></a></td>
    <td align="center"><a href="https://github.com/nareshkarthigeyan"><img src="https://avatars.githubusercontent.com/u/130460278?v=4" width="80" alt="nareshkarthigeyan"/><br><sub>nareshkarthigeyan</sub></a></td>
  </tr>
</table>

---

## 연구

TrueMemory는 검색 중심 에이전트 메모리에 관한 동료 심사 연구 논문으로 뒷받침됩니다.

**[Storage Is Not Memory: A Retrieval-Centered Architecture for Agent Recall](https://arxiv.org/abs/2605.04897)** — arXiv 2605.04897

```bibtex
@article{adler2025storage,
  title   = {Storage Is Not Memory: A Retrieval-Centered Architecture for Agent Recall},
  author  = {Sauron Labs},
  journal = {arXiv preprint arXiv:2605.04897},
  year    = {2025},
  url     = {https://arxiv.org/abs/2605.04897}
}
```

---

## 커뮤니티

- [Discord에 참여하세요](https://discord.gg/ZJ74JB2gVW) 도움, 피드백, 최신 소식을 받으세요
- 업데이트를 위해 X에서 [@Building_Josh](https://x.com/Building_Josh) 팔로우
- 회사 소식은 [@Sauron_Labs](https://x.com/Sauron_Labs) 팔로우
- 질문이나 아이디어는 [토론을 열어주세요](https://github.com/buildingjoshbetter/TrueMemory/discussions)
- 논문 읽기: [arXiv](https://arxiv.org/abs/2605.04897) · [Google Scholar](https://scholar.google.com/citations?user=YOUR_ID) · [Semantic Scholar](https://www.semanticscholar.org/)
- [truememory.net](https://truememory.net) · [sauronlabs.ai](https://sauronlabs.ai) 방문

TrueMemory가 시간을 절약해 주었다면, [별을 남겨주세요 ⭐](https://github.com/buildingjoshbetter/TrueMemory)

---

## 라이선스

[AGPL-3.0](../LICENSE). 개인 및 연구 용도는 무료입니다. 상업적 사용은 별도의 라이선스가 필요합니다. josh@sauronlabs.ai로 연락해 주세요.

---

<p align="center">
  <em>TrueMemory, <a href="https://sauronlabs.ai"><strong>sauron</strong></a> 회사</em>
</p>
