> For the complete documentation index, see [llms.txt](https://genos-docs.gitbook.io/default/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://genos-docs.gitbook.io/default/v1.9.2/basic-tutorials/guides/application/dev-chat/long-term-memory.md).

# 개인화 장기 메모리

개인화 장기 메모리는 대화에서 장기간 유효한 사실을 저장하고, 이후 질문과 관련된 기억을 찾아 답변에 반영하는 기능이다. 이름·소속·응답 선호·업무 규칙·진행 중 작업·합의처럼 다음 대화에서도 도움이 되는 정보가 대상이다.

* **사용자 동의** — 기본 OFF. 동의한 사용자만 저장·검색
* **서비스 활성화** — 채팅 서비스 revision별 사용 여부와 추출 방식 설정
* **자동 활용** — Agent가 첫 답변을 만들기 전에 관련 기억 검색
* **자동 저장** — 턴 종료 또는 nightly 배치에서 저장할 사실 추출
* **직접 관리** — 마이페이지에서 색인 상태 확인·상세 조회·정정·삭제

## 1. 사용자 동의

관리자 콘솔의 **마이페이지 > 개인 설정**에서 **장기 메모리 개인화**를 켠다.

기본값은 OFF다. OFF 상태에서는 새 메모리를 저장하거나 기존 메모리를 대화에 활용하지 않는다.

<figure><img src="/files/7oNMLiJjWN2tiHezKBxo" alt="장기 메모리 동의 OFF"><figcaption><p>장기 메모리 동의 OFF</p></figcaption></figure>

동의를 켜면 저장된 메모리 목록이 표시되고, 메모리가 활성화된 채팅 서비스에서 저장·검색이 시작된다.

<figure><img src="/files/qg6zCs4nmSYJLhOoaWsC" alt="장기 메모리 동의 ON"><figcaption><p>장기 메모리 동의 ON</p></figcaption></figure>

동의를 철회해도 기존 메모리는 즉시 삭제되지 않는다. 다시 활용하지 않으며, 필요한 항목은 마이페이지에서 직접 삭제할 수 있다.

## 2. 채팅 서비스 설정

서비스 관리자는 채팅 서비스 **생성** 또는 **새 버전 생성** 화면의 **운영 정책 > 장기 메모리**에서 기능을 설정한다.

<figure><img src="/files/iCbEJLP8Y3HjpXGdmnwA" alt="채팅 서비스 장기 메모리 설정"><figcaption><p>채팅 서비스 장기 메모리 설정</p></figcaption></figure>

| 설정        | 설명                                     |
| --------- | -------------------------------------- |
| 장기 메모리    | 해당 서비스 revision의 메모리 기능 master ON/OFF  |
| 매턴 추출     | 각 대화 턴 완료 후 비동기로 사실 추출                 |
| 새벽 배치     | 지정한 시·분(KST)에 최근 완료 턴을 다시 확인해 미처리 건 추출 |
| 추출 코드서빙   | 자동 추출에 사용할 memory-mcp 코드서빙             |
| 크레딧 차감 주체 | 추출 LLM·임베딩 비용을 사용자 또는 시스템에 귀속          |

설정 시 주의사항:

* master가 OFF면 자동 recall, 공개 메모리 Tool, 매턴·nightly 추출 모두 중지된다.
* 매턴 추출은 서비스 설정과 별개로 **시스템 설정 > 메모리 — 전역 매턴 추출 허용**도 ON이어야 한다.
* nightly는 매턴 추출의 누락·일시 중단을 보완하며, 매턴과 같은 대화 턴을 중복 저장하지 않는다.
* 색인과 검색은 **플랫폼 전역 임베딩 서빙**을 사용한다(전 서비스 공통 단일 벡터 공간). 서비스별 임베딩 선택 항목은 제공하지 않으며, 이 전역 임베딩은 **시스템 설정(`/admin/config`) > 메모리 — 전역 임베딩 서빙**에서 슈퍼관리자가 지정한다. 배포 없이 즉시(최대 60초) 반영되며, 값을 바꾸면 기존에 색인된 벡터는 이전 임베딩 공간이라 재색인이 필요하다(운영 절차).
* 새 버전을 저장·배포해야 설정이 실제 채팅 실행에 반영된다.

## 3. Flowise 설정

### 자동 recall

매 사용자 턴마다 관련 기억을 기본 컨텍스트로 공급하려면 Flowise의 각 **Agent 노드**에서 자동 recall을 켠다.

1. `enableLongTermRecall` 활성화
2. `longTermMemoryMCPServerConfig`에 memory-mcp 연결 지정
3. 검색 범위·개수·score 기준 설정
4. 주입 방식과 컨텍스트 템플릿 설정
5. workflow 저장·배포

| Agent 설정                        | 기본값           | 설명                                  |
| ------------------------------- | ------------- | ----------------------------------- |
| `longTermRecallScope`           | `personal`    | 개인 공통·현재 서비스 복수 선택. 둘 다 선택하면 통합 검색  |
| `longTermRecallTopK`            | `8`           | 최종 주입할 최대 기억 수                      |
| `longTermRecallThreshold`       | `0`           | 최소 검색 score. `0`은 score 기준 제외 없음    |
| `longTermRecallInjectionMode`   | `userContext` | 검색 결과를 현재 질문 앞의 참고 컨텍스트로 주입         |
| `longTermRecallContextTemplate` | 기본 템플릿        | 안전 안내·구분자·검색 결과를 포함한 전체 recall 프롬프트 |

템플릿은 recall 관련 문구 전체를 설정한다. 실제 기억을 전달하도록 `{memories}` 또는 `{memories_json}` 중 하나는 반드시 포함해야 한다.

| 치환값               | 내용                                                                                                        | 권장                   |
| ----------------- | --------------------------------------------------------------------------------------------------------- | -------------------- |
| `{memories}`      | 번호가 붙은 메모리 JSON 목록. 각 항목에 `memory_id`, `memory_type`, `temporal_relevance`, `source_event_ids`, `fact` 포함 | 기본                   |
| `{memories_json}` | 같은 항목의 JSON 배열                                                                                            | 구조화 입력이 유리한 모델에서 선택  |
| `{query_time}`    | MCP가 검색을 수행한 시각                                                                                           | 시간 기준을 명시해야 할 때만 선택  |
| `{count}`         | 최종 메모리 항목 수                                                                                               | 디버깅·출력 형식상 필요할 때만 선택 |
| `{safety}`        | memory-mcp가 반환한 데이터 취급 안내                                                                                 | 기존 템플릿 호환용           |

기본 템플릿은 안전 안내와 `[BEGIN/END_RETRIEVED_LONG_TERM_MEMORY]` 구분자, `{memories}`만 포함한다. 검색 시각은 모델이 이미 가진 현재 시각과 중복될 수 있고 결과 수는 목록에서 알 수 있으므로 기본값에서 제외한다. 시간 해석을 모델에 명시적으로 고정해야 하거나 템플릿을 진단할 때만 추가한다.

`userContext`가 기본 권장값이다. 완성된 템플릿을 애플리케이션의 고정 system 정책보다 낮은 권한의 참고 데이터로 전달한다. `system` 모드는 완성된 템플릿 전체를 기존 system prompt 뒤에 병합하므로, 호환이 필요한 경우에만 선택한다.

자동 recall은 **각 Agent 노드·iteration의 첫 LLM 호출 전에 한 번** 실행된다. 이후 같은 Agent 실행에서 Tool을 여러 번 호출해도 최초 검색 snapshot을 계속 사용한다. Tool 결과를 바탕으로 새 검색이 필요하면 아래 공개 `recall` Tool을 별도로 호출한다.

### 메모리 Tool

Agent가 필요에 따라 추가 검색하거나 사용자의 명시적 요청을 저장하게 하려면 **GenOS Long-term Memory** Tool 노드를 Agent의 Tools 입력에 연결한다.

<figure><img src="/files/lezb0EV8kud0pYpaMfge" alt="Flowise GenOS Long-term Memory 노드"><figcaption><p>Flowise GenOS Long-term Memory 노드</p></figcaption></figure>

공개 액션:

| 액션       | 용도                     |
| -------- | ---------------------- |
| `recall` | 첫 LLM 호출 이후 추가 기억 검색   |
| `detail` | 검색 결과의 단건 상세 조회        |
| `save`   | Agent가 명시적으로 선택한 사실 저장 |

`remember`는 턴 종료·nightly 자동 추출용 내부 액션이므로 Flowise 선택 목록과 Agent Tool 표면에 표시하지 않는다. Tool 노드의 `검색 범위`는 `recall`에만 적용하며 개인·현재 서비스를 복수 선택할 수 있다. LLM이 호출 인자로 범위를 바꾸지 못하도록 노드 설정으로 고정하고, 서비스 범위는 신뢰된 현재 서비스 신원으로 검증한다.

자동 recall만 필요하면 Tool 노드는 필수가 아니다. 반대로 Tool 노드만 연결하면 Agent가 `recall`을 선택한 턴에만 검색하므로, 매 턴 기본 검색이 필요할 때는 Agent 자동 recall도 켠다.

## 4. 채팅에서 확인

GenOS에 로그인한 사용자로 배포된 채팅 서비스를 실행한다. Flowise 편집기의 자체 테스트 채팅은 GenOS 사용자·서비스 신원이 없어 장기 메모리 E2E 확인 용도로 사용하지 않는다.

### 자동 저장

사용자가 선호·규칙·진행 작업 등을 말하면, 매턴 추출 또는 nightly가 대화 완료 후 저장 가치를 판정한다. 사용자가 “기억해줘”라고 말하지 않아도 이후에 반복해서 유용할 사실이면 자동 저장 대상이 될 수 있다.

명시적 “기억해줘” 요청은 Agent에 `save` Tool이 연결되어 있고 Agent가 이를 선택할 때 즉시 저장된다. Tool이 없거나 선택되지 않아도 턴 종료 자동 추출 경로가 다시 검토한다.

기존 기억과 유사한 사실은 무조건 추가하지 않는다. 같은 사실의 근거 병합, 세부정보 갱신, 이전 사실 대체·만료 중 하나를 판정하고 `valid_from`·`valid_to`로 이력을 남긴다.

### 자동 검색

새 질문이 시작되면 Agent가 사용자·범위를 제한한 뒤 관련 기억을 검색한다. score threshold, top-k, 유효기간, 민감도 정책을 통과한 기억만 현재 실행에 주입한다.

<figure><img src="/files/cS1czTFvxUui1q9JR5h8" alt="채팅에서 자동 recall 확인"><figcaption><p>채팅에서 자동 recall 확인</p></figcaption></figure>

검색 결과가 없거나 memory-mcp 호출이 실패하면 해당 턴의 장기 메모리만 생략하고 채팅은 계속한다. 검색된 기억은 현재 Agent 실행의 참고 컨텍스트이며 대화 이력에 영구 복사되지 않는다.

## 5. 마이페이지에서 관리

### 목록과 색인 상태

**마이페이지 > 개인 설정**에서 전체·개인·서비스 범위로 목록을 확인한다.

<figure><img src="/files/qg6zCs4nmSYJLhOoaWsC" alt="메모리 목록과 인덱스 상태"><figcaption><p>메모리 목록과 인덱스 상태</p></figcaption></figure>

| 표시     | 설명                                                                                |
| ------ | --------------------------------------------------------------------------------- |
| 사실     | 저장된 핵심 내용. 민감도 `pii`·`restricted`만 목록에서 마스킹(대소문자 무시)하고 `normal`·`unknown`은 그대로 표시 |
| 유형     | PROFILE, PREFERENCE, RULE, TASK 등 분류                                              |
| 범위     | 개인 또는 서비스 resource 유형                                                             |
| 유효     | 현재 사실 또는 과거·대체된 이력                                                                |
| 인덱스 상태 | 검색 인덱스 반영·복구 상태                                                                   |

주요 인덱스 상태:

* `indexed` — 현재 벡터 검색 표면 반영 완료. 실제 답변 참조 여부는 질문 관련도와 정책 필터에 따라 달라짐
* `pending`·`indexing` — 최초 색인 처리 중
* `stale` — 내용·스키마 변경 후 재색인 대기
* `failed` — 색인 실패, 운영 재색인 대상
* `excluded` — candidate 또는 민감도 정책상 검색 제외
* `delete_pending` — 삭제할 벡터 정리 대기

`index_state`는 검색 인덱스 상태다. 권한·현재성·유효기간의 정본은 MariaDB이며, `indexed` 항목도 recall 시 다시 검증한다.

행의 **상세**를 펼치면 구조화 정보와 읽기 전용 원문 JSON을 함께 확인할 수 있다. 본인 확인·정정을 위해 상세에서는 민감 항목의 원문도 표시된다.

<figure><img src="/files/tslz0rslaanH8YckUqjs" alt="메모리 구조화 상세와 원문 JSON"><figcaption><p>메모리 구조화 상세와 원문 JSON</p></figcaption></figure>

### 정정

행의 **정정**을 누르면 의미 내용 중 허용된 필드를 JSON으로 편집할 수 있다.

<figure><img src="/files/sE2WVK9bS2XivIcixOfi" alt="메모리 정정"><figcaption><p>메모리 정정</p></figcaption></figure>

편집 가능 예: `statement`, `raw_content`, `normalized_fact`, `keywords`, `entities`, `memory_subtype`, `sensitivity`, `confidence`, 시간·근거 메타데이터.

ID·소유자·scope·발생시각·audit 같은 불변 필드는 편집할 수 없다. 저장 시 Weaviate 반영이 실패하면 MariaDB 수정도 취소되어 이전 상태를 유지한다. 대상 벡터가 이미 없다면 복구할 검색 표면이 없으므로 MariaDB 메모리도 삭제하고 경고를 표시한다.

### 삭제

하나 이상의 행을 체크한 뒤 **선택 삭제**를 누른다. 삭제는 되돌릴 수 없으므로 확인 다이얼로그에서 한 번 더 확인한 뒤 실행된다.

<figure><img src="/files/0orgf3IXUDKf2OOtuEzy" alt="선택 삭제"><figcaption><p>선택 삭제</p></figcaption></figure>

삭제는 soft-delete 후 일반 목록과 recall에서 제외한다. Weaviate 호출 실패 시 MariaDB는 변경하지 않으며 오류 메시지를 표시한다. 벡터가 이미 없으면 MariaDB 항목을 함께 정리하고 경고 메시지를 표시한다.

## 6. 개인정보와 장애 동작

* 미동의 사용자의 저장·검색 요청은 실행하지 않는다.
* 사용자와 서비스 신원은 로그인·gateway·workflow에서 검증한 값만 사용한다.
* 모든 조회·검색·정정·삭제는 사용자와 canonical scope를 함께 제한한다.
* MariaDB의 의미 content는 암호화하며, `pii`·`restricted` 기억은 평문 벡터 색인에서 제외한다.
* 민감도(sensitivity)는 저장 시 `normal`·`pii`·`restricted` 세 값으로 정규화하며, 이 셋을 벗어난 값은 최저 등급으로 강등하지 않고 안전하게 `unknown`으로 보정한다(추후 별도 재분류 대상). `unknown`은 `normal`과 동일하게 색인·검색에 포함하고 목록에서 마스킹하지 않는다.
* 동의 철회는 수집·검색 중지이며 자동 전체 삭제가 아니다.
* 목록·상세 조회는 memory-mcp 상태와 독립적이다.
* 검색 장애는 채팅을 계속하고, 자동 색인 장애는 `index_state`와 정기 재색인으로 복구한다.
* 수동 정정·삭제는 검색 표면과 정본이 서로 다른 상태로 남지 않도록 실패 시 취소 또는 보상한다.

## 동작 흐름

```
[저장]
대화 완료
  → 매턴 enqueue 또는 nightly 미처리 턴 회수
  → 사실 추출·저장 가치 판정
  → 기존 기억과 insert/merge/update/replace/expire 조정
  → MariaDB 암호화 정본 저장
  → Weaviate 검색 색인

[검색]
새 사용자 질문
  → 서비스·동의·신원·scope 확인
  → Weaviate hybrid 후보 검색
  → MariaDB에서 현재성·유효기간·민감도 재검증
  → threshold·중복 제거·top-k·토큰 제한
  → Agent의 첫 LLM 호출 컨텍스트에 주입
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://genos-docs.gitbook.io/default/v1.9.2/basic-tutorials/guides/application/dev-chat/long-term-memory.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.