Librarian System은 RisuAI에서 장기 기억과 서사 연속성을 안정적으로 관리하기 위한 로컬 서버 + 플러그인 스위트입니다. 핵심 목표는 "기억을 많이 저장"하는 것이 아니라, 근거가 검증된 기억만 안전하게 보존하고 현재 대화에 정확히 연결하는 것입니다.
| 항목 | 내용 |
|---|---|
| 무엇인가요? | RisuAI용 로컬 메모리 인프라입니다. 서버(Librarian System Server)와 6개 플러그인(LIBRA, Flashback, HAYAKU, LIA, RE:TRACE, GRADIA)으로 구성됩니다. |
| 왜 필요한가요? | 긴 대화/분기형 대화에서 기억 혼합, 근거 없는 요약, 상태 불일치 문제를 줄이기 위해서입니다. |
| 무엇이 다른가요? | Source-Bound Proof(원문 근거 검증), Worldline(분기 격리), State Projection(현재 상태 투영), CAS + SQLite WAL(무결성 중심 저장)을 제공합니다. |
| 어떻게 시작하나요? | ① Node.js 설치 → ② 서버 실행 → ③ RisuAI에 플러그인 등록 및 서버 주소(http://127.0.0.1:47630) 연결 |
- 플러그인이 대화에서 기억 후보를 추출합니다.
- 로컬 서버가 스코프/리비전/CAS 규칙으로 저장 무결성을 검증합니다.
- 필요 시 검증된 기억만 다시 조회되어 프롬프트에 반영됩니다.
- 🔗 6종 플러그인 생태계: 장기 서사 기억(
LIBRA), 에피소드 회상(Flashback), 시공간/위치 연속성(HAYAKU), 페르소나·로어 링킹(LIA), 스코프·백업 관리(RE:TRACE), 다중 기억 기반 서사 보조(GRADIA)로 구성된 통합 아키텍처. - 🛡️ 무결성 중심의 로컬 서버 (
node:sqlite): 외부 데이터베이스 설치 없이 Node.js 내장 SQLite(WAL 모드)를 사용하여 CAS(Compare-And-Swap) 리비전 관리, 암호화 해시 검증, 자동 백업 및 복구를 수행합니다. - 🌿 네이티브 분기(Worldline) 완벽 대응: 채팅 분기, 재생성(Reroll), 이어하기 발생 시 이전 세계선의 기억이 섞이지 않도록 스코프와 리비전 경계를 엄격하게 분리·추적합니다.
- 📦 코드(
PROGRAM)와 데이터(DATA)의 완전한 분리: 업데이트 중 오류가 발생해도 기존DATA를 보호하며, 저널 기반 자동 롤백(UPDATER)을 지원합니다. - 💻 크로스 플랫폼 지원: Windows(
.bat), macOS(.command), Linux 및 Android Termux(.sh) 원클릭 런처를 기본 제공합니다.
flowchart TB
subgraph Host["RisuAI 클라이언트 (Browser / WebView)"]
direction TB
subgraph Owners["기억 소유자 플러그인 (Storage Owners)"]
LIBRA["LIBRA<br/>(정본/Micro 기억 · 상태 투영 · 그래프 회상)"]
FB["Flashback<br/>(에피소드 기억 · 채팅 어텐션)"]
HAYAKU["HAYAKU<br/>(장소/인물 연속성 · 위치 추적)"]
end
LIA["LIA<br/>(local_only · 페르소나 수동 갱신)"]
Persona[("RisuAI Persona · 기기 저장소")]
LIA <--> Persona
RETRACE["RE:TRACE<br/>(manager_only · 인계/서버 관리)"]
RETRACE -->|인계 조정| LIBRA & FB & HAYAKU
GRADIA["GRADIA<br/>(읽기 전용 다중 기억 소비자 · 서사 보조)"]
GRADIA -->|검증된 근거 읽기| LIBRA & FB & HAYAKU
end
subgraph Server["Librarian System Data Server v0.5.0 (127.0.0.1:47630)"]
Router["Authenticated HTTP Router<br/>(Scoped Capability Auth / CAS)"]
Coord["Authority Coordinator & Writer Fence"]
SQLite[("DATA/stores/*.sqlite<br/>(WAL Mode / Tombstone / Revision)")]
Backup["Auto Backup & Portable Transfer"]
Router --> Coord --> SQLite
SQLite --> Backup
end
Owners <-->|"Storage SDK<br/>(server_only / plugin_only)"| Router
RETRACE -->|관리 권한| Router
| 컴포넌트 | 버전 | 구분 | 주요 역할 |
|---|---|---|---|
| Librarian System Server | 0.5.0 |
로컬 서버 | SQLite 기반 KV/그래프 저장소, 스코프 카탈로그, 자동 백업 및 무결성 검증 서버 |
| LIBRA | 2.6.15 |
플러그인 (Owner) | 5턴 정본(Canonical) + 매 턴 Micro 기억 추출, 현재 상태(State Head) 투영, 시맨틱/어휘 하이브리드 회상 |
| Flashback Memory | 1.3.16 |
플러그인 (Owner) | 대화 맥락 장기 에피소드 기억, 벡터/키워드 검색, 제로터치 채팅 어텐션 버튼 |
| HAYAKU Locator Continuity | 3.3.11 |
플러그인 (Owner) | 장면 전환·장소 이동·인물 배치 연속성 추적 및 빠른 위치 컨텍스트 복원 |
| LIA Persona Linker | 0.29.4 |
플러그인 (Local owner) | 기기 전용 페르소나 관리·수동 갱신 및 월드 로어북(Lorebook) BM25F 재순위화 |
| RE:TRACE | 1.12.7 |
플러그인 (Manager) | 서버/로컬 스코프 통합 조회, 고정(Pin), 삭제 보호, ZIP 백업 내보내기/복원 관리 GUI |
| GRADIA | 0.28.13 |
플러그인 (Consumer) | LIBRA·Flashback·HAYAKU의 검증된 기억 근거를 읽기 전용으로 통합 소비하는 소설/서사 생성 보조기 |
호환 SDK: Storage SDK
1.8.35· Compute SDK0.3.8
아래 내용은 PROGRAM/plugins/*.js, PROGRAM/server/server.cjs, PROGRAM/server/core/gradia-*-read-session.cjs의 현재 구현을 기준으로 정리했습니다.
- 역할/문제
- 장기 서사 메모리의 정본(canonical)·마이크로 메모리·상태 정보를 유지하고, 회상/인계 시 소스 불변(immutable-source) 규약을 지키는 핵심 Owner입니다.
- 연결 이벤트·API·파일
- 플러그인 파일:
PROGRAM/plugins/LIBRA.js - 서버 API:
POST /v1/libra/graph-lifecycle,POST /v1/kv/batch,POST /v1/flashback/writer,POST /v1/manager/scopes/index - RE:TRACE IPC 채널/액션:
libra_memory_bridge_request_v1/...response_v1,prepare_session_handoff,adopt_session_handoff,verify_session_handoff,rollback_lens_session_handoff - 출력 이벤트 캡처:
addRisuChatListener('output')우선, 레거시 경로 보조
- 플러그인 파일:
- 핵심 메커니즘/흐름
- 대화 출력 이벤트에서 U+A 증거를 수집하고 메모리/상태 후보를 구성
- 스코프/리비전/다이제스트 기반 검증 후 저장 (
plugin_only또는 서버 라우팅) - 핸드오프 시 소스 스냅샷 무결성(fingerprint) 확인 후 대상 채팅에 채택(adopt) 및 검증(verify)
- 사용자 기능
- 정본 메모리 관리, 상태 추적, 회상 보조, RE:TRACE 연계 핸드오프
- 설정/제약
- RE:TRACE 호환 스키마:
retrace.peer_compatibility.v1 - 핸드오프 계약:
libra.handoff_immutable_source_lenses.v2 - 대용량 저장/검증은 Storage SDK 규약과 서버 무결성 상태에 의존
- RE:TRACE 호환 스키마:
- 역할/문제
- 장면/위치/인물 연속성(Locator continuity)과 패킷 기반 기억을 유지하고, 회복(recovery) 및 핸드오프 시 내구성 검증을 수행합니다.
- 연결 이벤트·API·파일
- 플러그인 파일:
PROGRAM/plugins/HAYAKU_Locator_Continuity.js - 서버 API:
POST /v1/flashback/writer,POST /v1/manager/scopes/index,POST /v1/hayaku/read-session/capture,POST /v1/hayaku/read-session/current - RE:TRACE IPC:
hayaku_memory_bridge_request_v1/...response_v1,inspect,adopt_session_handoff,memory_suite_storage_status
- 플러그인 파일:
- 핵심 메커니즘/흐름
- 출력 캡처 이벤트를 기준으로 ledger/packet 상태를 갱신
- 핸드오프 시
expectedRecords·스코프 식별자 검증 후 채택 실행 - 채택 전/후
MemorySuiteStorageBridge.ensureHandoffReady(...)로 저장 경로 일관성 확인
- 사용자 기능
- 위치/상황 연속성 유지, 복구/점검, RE:TRACE를 통한 안전한 세션 인계
- 설정/제약
- 핸드오프 계약:
hayaku.handoff_immutable_source.v1 - 읽기 세션에서 archive/packet을 예산(
maxCorpusBytes, raw/metadata budget) 내 검증적으로 로드
- 핸드오프 계약:
- 역할/문제
- 에피소드형 대화 기억을 장기 보관하고, 현재 채팅 맥락에서 필요한 기억을 재구성하는 Owner입니다.
- 연결 이벤트·API·파일
- 플러그인 파일:
PROGRAM/plugins/Flashback_Memory.js - 서버 API:
POST /v1/flashback/writer,POST /v1/manager/scopes/index,POST /v1/flashback/read-session/capture,POST /v1/flashback/read-session/current - RE:TRACE IPC:
flashback_memory_bridge_request_v1/...response_v1,adopt_session_handoff,memory_suite_prepare_server_scope_delete
- 플러그인 파일:
- 핵심 메커니즘/흐름
- 출력 이벤트 기반으로 회상 후보/세션 상태를 기록
- 서버 모드에서는 writer fence 및 scope pin capability를 활용해 안전 저장
- 핸드오프 채택 시 LIA 연속성 정보(있을 경우)를 함께 검증하여 반영
- 사용자 기능
- 에피소드 기억 저장/회상, 세션 인계 시 보존 검증, 서버 스코프 정리 가드
- 설정/제약
- 핸드오프 계약:
flashback_memory.handoff_immutable_source.v2 - scope 삭제/복구 작업은 RE:TRACE 요청 + 서버 capability 조건을 충족해야 수행
- 핸드오프 계약:
- 역할/문제
- Live Persona 상태를 채팅 스코프와 연결해 페르소나 연속성을 유지하고, 로어 재순위화(BM25F 스타일)·상태 동기화를 담당합니다.
- 연결 이벤트·API·파일
- 플러그인 파일:
PROGRAM/plugins/LIA_Persona_Linker.js - 주요 IPC/스키마:
lia_persona_handoff_request_v1,lia.live_persona_handoff.receipt.v1,retrace.peer_compatibility.v1 - 저장 정책:
local_only· Persona와 갱신 자료를 이 기기에 보관
- 플러그인 파일:
- 핵심 메커니즘/흐름
- 현재 채팅의 Live Persona binding/scope를 확인
- 핸드오프 시
adopt_chat_handoff→ 대상 chat binding 생성/검증 verify_chat_handoff에서 durable readback 및 lineage 일치 여부 재검증
- 사용자 기능
- Live Persona 분기/상속, 페르소나 상태 추적, 세계관 로어 정렬 보조
- 설정/제약
- 핸드오프 계약:
lia.live_persona_handoff_immutable_source.v1 - 자동 분석·갱신 없이 완결된 U+A 5쌍이 쌓이면 갱신 동의를 요청하고, 동의하거나 수동 갱신을 눌렀을 때 분석
- 일부 연산은 현재 캐릭터/채팅 인덱스 API 가용성에 의존하며 불일치 시 fail-closed
- 핸드오프 계약:
- 역할/문제
- 자체적으로 Owner 데이터를 쓰지 않고, LIBRA/HAYAKU/Flashback의 검증된 읽기 세션을 통합해 서사 작성 파이프라인(Shadow/AIDE 단계)을 보조하는 Consumer입니다.
- 연결 이벤트·API·파일
- 플러그인 파일:
PROGRAM/plugins/GRADIA.js - 서버 읽기 전용 API:
POST /v1/libra/read-session/capture|currentPOST /v1/hayaku/read-session/capture|currentPOST /v1/flashback/read-session/capture|current
- 서버 권한 모델:
/bootstrap시x-memory-suite-read-owners로 허용 owner 집합 선언
- 플러그인 파일:
- 핵심 메커니즘/흐름
- 선택한 플러그인 IPC 또는 서버 연결로 owner의 증거를 획득하며, 서버 경로에서는 read-session
capture로 스냅샷을 획득 current호출로 reset epoch/의존성 digest가 여전히 유효한지 확인- 유효한 증거만 프롬프트 주입(읽기 전용, owner 쓰기 금지)
- 선택한 플러그인 IPC 또는 서버 연결로 owner의 증거를 획득하며, 서버 경로에서는 read-session
- 사용자 기능
- 다중 기억 근거를 결합한 장면/서사 작성 보조, 단계별 모델 프리셋/입력 보조
- 설정/제약
mode,multi_pipeline_mode,writing_mode, 다수 LLM/프리셋/로어 관련@arg제공- 서버는 GRADIA를 read-only principal로 제한하며 일반 쓰기/compute 경로를 차단
- 역할/문제
- 플러그인 간 호환성/핸드오프/서버 관리의 허브입니다. 직접 Owner 데이터를 생성하기보다, 각 Owner의 증거/상태를 검증해 안전한 세션 인계를 조정합니다.
- 연결 이벤트·API·파일
- 플러그인 파일:
PROGRAM/plugins/RETRACE.js - 허용 액션 집합(Owner별):
inspect,adopt_session_handoff,prepare_session_handoff,verify_session_handoff,memory_suite_storage_status등 - 서버 관리 API:
/v1/manager/scopes,/v1/manager/scope-pin,/v1/manager/scope-delete/*,/v1/manager/portable/*
- 플러그인 파일:
- 핵심 메커니즘/흐름
- Owner별 compatibility contract(
retrace.peer_compatibility.v1) 수집 - 인계 전 source-immutable/durable-readback 조건 확인
- 인계 후 owner receipt를 교차 검증하고, 서버 스코프 관리 작업(핀/삭제/복원)을 가드된 경로로 실행
- Owner별 compatibility contract(
- 사용자 기능
- 다음 세션 인계, 호환성 매트릭스, 백업/복원/스코프 관리 GUI
- 설정/제약
- 기본 서버 URL 설정 키:
memory_suite_server_url - manager 권한이 필요한 작업은 서버 capability 미충족 시 차단
- 기본 서버 URL 설정 키:
- Owner 계층:
LIBRA/Flashback/HAYAKU가 플러그인·서버 저장을 선택하고,LIA는 기기 전용으로 Persona를 관리 - Orchestrator 계층:
RE:TRACE가 owner IPC를 통해 호환성·인계·관리 작업을 조정 - Consumer 계층:
GRADIA가 owner 데이터를 쓰지 않고 read-session API로 근거만 소비 - Server 계층:
PROGRAM/server/server.cjs가 플러그인 식별(x-memory-suite-plugin)과 capability 토큰으로 권한을 분리하고, KV/manager/admin/read-session 라우트를 제공
Important
일반 배포 ZIP에는 Node.js 실행 파일이 포함되어 있지 않습니다.
서버 실행 전 반드시 Node.js 22.13.0 이상 (현재 LTS 버전 권장)을 설치해야 합니다 (node:sqlite 내장 모듈 사용).
- 공식 다운로드: https://nodejs.org/
- Android Termux 환경: 먼저
sh "PROGRAM/안드로이드_Termux_준비.sh"를 실행하여 환경을 구성하세요.
원하는 폴더에 패키지를 압축 해제한 뒤, 운영체제에 맞는 실행 스크립트를 더블클릭하거나 터미널에서 실행합니다.
| 운영체제 | 포그라운드 실행 | 백그라운드 실행 | 서버 종료 | 상태 확인 |
|---|---|---|---|---|
| Windows | PROGRAM\1_서버_실행.bat |
PROGRAM\서버_백그라운드_실행.bat |
PROGRAM\2_서버_종료.bat |
PROGRAM\서버_상태_확인.bat |
| macOS | PROGRAM/macOS_서버_실행.command |
PROGRAM/서버_백그라운드_실행.sh |
PROGRAM/2_서버_종료.sh |
PROGRAM/서버_상태_확인.sh |
| Linux / Termux | PROGRAM/1_서버_실행.sh |
PROGRAM/서버_백그라운드_실행.sh |
PROGRAM/2_서버_종료.sh |
PROGRAM/서버_상태_확인.sh |
- 기본 바인딩 주소는
http://127.0.0.1:47630(Loopback 전용)입니다.
- RisuAI 실행 후 설정(Settings) → 플러그인(Plugins) 메뉴로 이동합니다.
PROGRAM/plugins/폴더 내에 있는 필요한 플러그인(.js) 파일들을 등록합니다:LIBRA.jsFlashback_Memory.jsHAYAKU_Locator_Continuity.jsLIA_Persona_Linker.jsRETRACE.jsGRADIA.js
- 각 플러그인의 서버 연결 설정에서 Librarian System Server(
http://127.0.0.1:47630)에 연결하고 저장 모드를 선택합니다.
Librarian System은 두 가지 정식 저장 모드와 한 가지 이관용 전환 모드를 제공합니다.
server_only(서버 단독 - 권장)- 모든 기억과 인덱스를 로컬 서버(
DATA/)의 SQLite DB에 안전하게 저장합니다. - 브라우저 용량 제한이 없으며, 자동 백업·스냅샷 복원·정합성 검증을 완벽히 지원합니다.
- 모든 기억과 인덱스를 로컬 서버(
plugin_only(플러그인 단독)- 서버 없이 RisuAI 브라우저 내부 저장소(
pluginStorage/ IndexedDB)와 로컬 JS 연산만 사용합니다.
- 서버 없이 RisuAI 브라우저 내부 저장소(
mirror(레거시 전환 단계)- 현재 서버 부트스트랩 계약(
memory-suite.storage-mode-contract.v2) 기준 운영 모드는plugin_only/server_only이며,mirror는 전환 호환(legacy transition) 용도로만 유지됩니다. - 신규 설정에서는 단독 모드(
plugin_only또는server_only)를 기준으로 사용하세요.
- 현재 서버 부트스트랩 계약(
명령어를 직접 입력할 필요 없이 최상위 폴더의 업데이트 실행 파일을 실행하세요.
- Windows:
업데이트.bat - macOS:
업데이트.command - Linux / Termux:
업데이트.sh
[업데이트 메뉴]
1. 이 폴더의 서버를 최신 버전으로 업데이트
2. 다른 기존 설치 폴더를 업데이트
3. 미완료 업데이트 복구
Warning
데이터 보호 주의사항
- 절대 새 배포판의 빈
DATA폴더를 기존DATA폴더 위에 수동으로 덮어쓰지 마세요. - 업데이터(
UPDATER)가 기존DATA를 자동으로 보존하고, 필요한 경우 안전하게 마이그레이션합니다. - 업데이트 도중 예기치 않게 중단된 경우, 업데이트 메뉴의 **
3. 미완료 업데이트 복구**를 실행하면 이전PROGRAM/DATA쌍으로 안전하게 롤백됩니다. - 서버 업데이터는 RisuAI 앱 내부에 로드된 플러그인을 자동 교체할 수 없으므로, 플러그인 버전이 변경된 경우
PROGRAM/plugins/의 최신.js파일을 RisuAI에 다시 적용해 주세요.
Librarian-System/
├── 0_설치_안내.txt # 빠른 설치 및 업데이트 안내문
├── 업데이트.bat / .command / .sh # 크로스 플랫폼 대화형 업데이터 런처
├── update-manifest.json # 릴리스 버전 및 에셋 무결성 매니페스트
├── SHA256SUMS.txt # 전체 배포 파일 SHA-256 체크섬 목록
├── DATA/ # [사용자 데이터 영역] DB, 설정, 백업, 로그 (수동 덮어쓰기 금지)
├── UPDATER/ # 트랜잭션 기반 자동 업데이트 및 롤백 엔진
└── PROGRAM/ # [실행 프로그램 영역]
├── 1_서버_실행.* # OS별 서버 구동 스크립트
├── 2_서버_종료.* # OS별 서버 안전 종료 스크립트
├── program-manifest.json # 플러그인/SDK 버전 및 파일 해시 명세
├── server/ # Node.js 로컬 서버 코어 (server.cjs, authority, portable 등)
├── plugins/ # RisuAI 설치용 6종 플러그인 번들 (.js)
├── sdk/ # Storage SDK 및 Compute SDK 소스
├── tools/ # 런처, 데이터 준비, RAG 평가, 배포 빌드 도구
├── tests/ # 단위·통합·브라우저·회귀 테스트 스위트
└── docs/ # 아키텍처 설계 계약서 및 릴리스 검증 보고서
# Node.js 런타임 및 SQLite 지원 여부 확인
node PROGRAM/tools/check_node.cjs
# 데이터 폴더 초기화 및 레이아웃 검증
node PROGRAM/tools/platform_launcher.cjs prepare
# 전체 회귀 테스트 런처 (Linux/macOS)
sh PROGRAM/관리도구/전체_자동시험.sh
# 메타데이터 및 패키지 레이아웃 일관성 테스트
node PROGRAM/tests/program_data_layout_test.cjs
node PROGRAM/tests/distribution_metadata_coherence_test.cjs
# 전체 회귀 배치 테스트 실행
python3 PROGRAM/run_regression_batch.py이 프로젝트는 GNU Affero General Public License v3.0 (AGPL-3.0) 라이선스 하에 배포됩니다.