Perseus Vault

AI 에이전트를 위한 영구적이고 암호화된 메모리. 하나의 Rust 바이너리, 하나의 파일, 클라우드 없음.

게시처 Official MCP Registry · Glama · mcpservers.org · Lulu MCPs · Docker (GHCR)

에이전트에게 세션이 끝나도 유지되는 메모리를 제공하여, 이미 학습한 내용을 다시 유추하거나 과거 실수를 반복하지 않도록 하세요. 하이브리드 검색(BM25 + dense + RRF), 이중 시간 기록, 저장 시 AES-256-GCM 암호화를 지원하며, 168개의 표준 MCP 도구로 모든 호스트와 호환됩니다. 레거시 mimir_*/mneme_* 별칭은 2026-27 메이저 릴리스에서 제거되었으며 별도로 집계되지 않습니다. LongMemEval 공식 평가에서 73.8% (Zep 63.8%, Mem0 49.0% 대비). 하나의 바이너리. 하나의 파일. Docker 불필요. Postgres 불필요. 클라우드 불필요. 로컬 우선, 에어갭 준비 완료, MIT 라이선스.

한 줄 설치

curl -sSf https://raw.githubusercontent.com/Perseus-Computing-LLC/perseus-vault/main/scripts/install.sh | sh

끝입니다. Perseus Vault가 ~/.local/bin/perseus-vault에 설치됩니다. 실행하세요:

perseus-vault serve --db ~/.perseus-vault/data/perseus-vault.db

기본 설치 시 암호화가 자동으로 활성화됩니다. 첫 번째 실행 시 소유자 전용 권한의 ~/.perseus-vault/secret.key와 암호화된 데이터베이스 카나리가 생성됩니다. 해당 키를 백업하세요: 복구가 불가능합니다. 명시적인 --encryption-key 경로는 계속 지원되며, 기존 일반 텍스트 데이터베이스는 perseus-vault init --rekey를 사용한 마이그레이션을 위해 보존됩니다. doctor를 사용하여 실제 디스크 상태를 확인하세요.

macOS 참고 사항 (Apple Silicon). 새로 빌드되거나 복사된 바이너리는 격리 속성이 없더라도 OS 바이너리 정책에 의해 첫 번째 실행 시 SIGKILL됩니다(Killed: 9, 다른 출력 없음). 한 줄 설치 프로그램과 bootstrap.sh 소스 빌드 설치 프로그램이 Perseus Vault를 임시로 코드 서명합니다. 직접 바이너리를 빌드하는 경우, 재빌드할 때마다 한 번 서명하세요:

cargo build --release
cp target/release/perseus-vault ~/.local/bin/perseus-vault
codesign --force --sign - ~/.local/bin/perseus-vault   # required on Apple Silicon; fixes "Killed: 9"

--force는 이미 서명된 바이너리를 다시 서명합니다(재빌드 시마다 필요). Intel macOS에서는 무해하며 Linux/Windows에서는 불필요합니다.

그런 다음 MCP 클라이언트와 전체 검색/캡처 루프를 한 명령으로 연결하세요:

perseus-vault install-client --hooks --rules

이 명령은 Claude Code / Codex / Cursor를 자동 감지합니다(명시적 클라이언트 지정 시 --client <name> 사용: claude-desktop, hermes, windsurf, vscode, zed, generic; --all-detected는 감지된 모든 클라이언트를 연결합니다). 기존 설정을 덮어쓰지 않고 MCP 서버 등록을 클라이언트 설정에 병합하며(먼저 .bak-perseus 백업이 생성됨), 모든 클라이언트를 하나의 공유 메모리 데이터베이스로 지정하고, 세션 수명 주기 훅(SessionStart 시 검색 주입, 세션 종료 시 정리 — docs/lifecycle-hooks.md 계약 참조)을 등록하며, 메모리 사용 규칙을 CLAUDE.md/AGENTS.md에 추가합니다. 재실행은 아무 영향이 없습니다. --dry-run을 추가하면 수정할 모든 파일을 미리 볼 수 있습니다.

또는 수동으로 MCP 호스트(Claude Desktop, Cursor, Hermes Agent, Perseus 등)에 연결하세요:

{
  "mcpServers": {
    "perseus-vault": {
      "command": "perseus-vault",
      "args": ["serve", "--db", "~/.perseus-vault/data/perseus-vault.db"]
    }
  }
}

Related MCP server: GroundMemory

에이전트용: MCP를 통한 연결

주 소비자가 에이전트인 경우 인터페이스는 MCP입니다. 에이전트는 MCP 클라이언트를 통해 Vault를 채택하며, 서버 자체를 실행하는 것 외에 머신별 CLI 설치가 필요하지 않습니다:

# 1. Run the server (one line)
perseus-vault serve --db ~/.perseus-vault/data/perseus-vault.db &

# 2. Register it in the agent's MCP client config
#    { "mcpServers": { "perseus-vault": {
#        "command": "perseus-vault",
#        "args": ["serve", "--db", "~/.perseus-vault/data/perseus-vault.db"] } } }

# 3. Verify the agent-facing surface
perseus-vault doctor

perseus-vault install-client --hooks --rules는 Claude Code / Codex / Cursor / Hermes에 대한 전체 검색/캡처 루프를 한 명령으로 연결합니다. 에이전트 대상 기능 맵(어떤 도구가 어떤 작업을 수행하는지, 계획 경계 패턴)은 docs/integration/agent-adoption.md를 참조하세요.

30초 빠른 시작

# Start Perseus Vault
perseus-vault serve --db memory.db &
sleep 1

# Remember a fact (via MCP JSON-RPC on stdio)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"perseus_vault_remember","arguments":{"category":"demo","key":"hello","body_json":"{\"text\":\"Hello from Perseus Vault!\"}"}}}' | perseus-vault serve --db memory.db

# Search for it
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"perseus_vault_recall","arguments":{"query":"Hello"}}}' | perseus-vault serve --db memory.db

메모리 모델 및 운영 경계

Perseus Vault는 세 가지 평면을 구분합니다:

• 암시적 작업 컨텍스트는 호스트의 현재 프롬프트, 대화 기록, 그리고 클라이언트가 주입하기로 선택한 컨텍스트 블록입니다. 이는 일시적이며 호스트 소유입니다. Vault가 반환했다고 해서 지속되는 것은 아닙니다.

• 명시적 영구 메모리는 명시적인 perseus_vault_remember, perseus_vault_capture, write, 또는 capture 작업으로 기록됩니다. Vault 서버는 SQLite 레코드, 기록, 저널, 감쇠, 아카이브 및 제거 수명 주기를 소유합니다.

• 파생된 프로젝션은 통합 또는 합성된 레코드와 내보낸 Markdown을 포함합니다. 출처 정보를 제공하지만 영구 소스 레코드를 대체하지 않으며 별도의 정리가 필요할 수 있습니다.

perseus-vault prepare와 perseus_vault_context는 영구 레코드를 읽어 제한된 작업 관련 활성 작업 컨텍스트를 생성합니다. 이는 롤링 스냅샷이며, 백그라운드 쓰기나 클라이언트가 이를 유지하겠다는 약속이 아닙니다. 작업이 변경되면 새로고침하고, 명시적인 캡처/쓰기 작업이 성공하지 않는 한 프롬프트 텍스트를 영구 메모리로 취급하지 마십시오. 검색 우선 출력은 예산이 할당됩니다(기본 1500자, 대형 창 호스트의 경우 6000자, 또는 명시적인 max_context_chars). always_on 세트는 최대 5개로 제한됩니다. 보존 및 컨텍스트 의미론을 참조하세요.

수명 주기 훅과 클라이언트 설치 프로그램은 선택적 오케스트레이션입니다. 이들은 서버 소유의 검색, 캡처, 유지 관리 및 새로고침 작업을 요청합니다. 두 번째 저장소가 되거나 보존 정책을 변경하지 않습니다. 서버나 훅을 사용할 수 없는 경우, 주입된 메모리 없이 작업을 계속하고 성능 저하 상태를 표시합니다. 호스트 통합에는 명시적으로 구성된 로컬 폴백이 있을 수 있지만, 해당 폴백은 로컬 전용으로 표시되어야 하며 영구 Vault 검색으로 제시되어서는 안 됩니다. 실패한 명시적 쓰기는 절대 지속된 것으로 보고되어서는 안 됩니다. 업그레이드/복구 단계는 업그레이드 및 마이그레이션 플레이북을 사용하세요.

모든 MCP 클라이언트와 호환

Perseus Vault는 표준 MCP stdio 서버입니다. 동일한 perseus-vault serve 명령이 모든 곳에서 작동합니다. perseus-vault doctor를 실행하여 설치를 확인하고 이 매트릭스를 로컬에서 출력하세요.

각 클라이언트에 대한 복사-붙여넣기 설정 스니펫: docs/clients/.

그런 다음 검색 → 작업 → 캡처 → 통합 루프를 클라이언트의 세션 이벤트(Claude Code, Codex, Cursor용 SessionStart/Stop 훅, 휴대용 AGENTS.md 폴백 포함)에 연결하세요: docs/lifecycle-hooks.md.

메모리 워셔(CoalWash) 및 런타임 출력 압축기(Noisegate)와 함께 구성하여 종단 간 컨텍스트 예산 제어: docs/integration/context-budget-stack.md.

Vault가 무엇을, 어디서, 어떤 권한으로 기억하는지 감사: docs/evidence-chain-guidance.md — 증거 체인, 쓰기 시간 출처 태그, 영구 메모리에 대한 지속적 증명.

메모리 뱅크 (클라이언트별 격리, 하나의 프로필)

동일한 플레이북으로 50개의 클라이언트를 운영하는 에이전시? 프로필을 복제하지 말고 프로젝트별로 메모리 뱅크를 지정하고 하나의 Hermes 프로필, 하나의 Vault, 하나의 공유 스킬 라이브러리를 유지하세요:

# .hermes.md
memory_bank: acme-seo            # name → deterministic workspace hash
memory_bank_workspace: <64-hex>  # optional explicit workspace override

Hermes 메모리 제공자(hermes plugins install Perseus-Computing-LLC/hermes-plugin-perseus-vault)는 세션당 한 번 뱅크를 확인하고 모든 Vault 읽기 및 쓰기(프리페치 검색, perseus_recall / perseus_remember / perseus_forget, 세션 종료 캡처)를 전용 워크스페이스로 범위를 지정합니다. 뱅크 이름은 결정론적으로 매핑되므로(sha256("memory-bank:" + name)), 동일한 이름을 가리키는 모든 인스턴스는 유지 관리할 레지스트리 없이 동일한 워크스페이스를 주소 지정합니다. 워크스페이스는 서버에서 일급 시민입니다: 범위 지정 유지 관리, 뱅크 간 중복 제거 격리, 워크스페이스별 권한 매니페스트. 검색은 Hermes 프로젝트 컨텍스트 규칙을 미러링합니다(가장 가까운 .hermes.md 우선, git 루트에서 제한). 지시문이 없는 컨텍스트 파일은 뱅크가 없음을 의미합니다 — 구성된 워크스페이스가 계속 적용됩니다.

Perseus Vault를 선택해야 하는 이유

Perseus Vault는 MCP 네이티브, 로컬 우선, 제로 종속성, 그리고 에이전트 우선을 동시에 만족하는 유일한 메모리 엔진입니다.

LongMemEval QA (공식 평가)

자체 제작 스크립트가 아닌 LongMemEval의 공식 평가에서 측정된 검색 품질:

longmemeval_s (500개 질문), gpt-4o-2024-08-06 응답자 + LongMemEval 공식 판정자; 경쟁사 수치는 게시된 값입니다. Perseus Vault의 73.8%는 3회 실행의 단순 평균입니다. 공식 CoT 사용 시 79.0%. 방법론 및 콘텐츠 해시(sha256) 결과 →

LOCOMO (mem0 자체 평가)

mem0 자체 LOCOMO 평가(저희 포크)에서 측정되었습니다. 저희 것이 아닙니다 — 카테고리 1–4, 1,540개 질문, 상위 200개, gpt-5 응답자 + 판정자:

카테고리 5 적대적(446개 질문): Perseus 63.5, Mem0 55.6, Zep 49.8. Mem0 측정값은 게시된 파일보다 9.4포인트 낮습니다(판정자/플랫폼 드리프트 — 공개됨). 전체 리더보드 →

이중 시간 여행 (3축)

저희의 가장 강력한 구조적 차별점 — 완전한 SQL:2011 이중 시간 기록(트랜잭션 시간 및 유효 시간) — 재현 가능하고 완전히 오프라인인 시험에서 측정되었습니다. 실제 출시된 바이너리를 MCP stdio를 통해 구동하여 단일 축 경쟁사가 틀리는 어려운 사례(소급 수정, 사전 미래 날짜 사실, 순서 외 도착, 신념 대 진실 발산, 마감된 기간)를 처리합니다.

단일 명령어로 재현 (API 키, 네트워크, LLM 불필요):

cargo build --release
python benchmark/temporal/gauntlet.py --bin target/release/perseus-vault

PASS/FAIL 판정은 결정론적입니다 (벽시계 타임스탬프는 변하지만 판정은 변하지 않음). 따라서 올바른 빌드는 동일한 signature_sha256로 재실행됩니다. 커밋된 gauntlet_report.json이 참조입니다. 방법론 및 데이터셋 →

비교 매트릭스

전체 비교: Perseus Vault vs Mem0 → vs Letta → vs Zep →

스트레스 테스트: 100K 엔티티

Perseus Vault는 적당한 하드웨어에서 프로덕션 워크로드를 처리합니다. 아래 수치는 커밋된 아티팩트 benchmark/scale/report.json에서 가져온 것입니다: 실제 릴리스 바이너리가 MCP stdio를 통해 구동됨 (코퍼스 크기당 하나의 영구 프로세스), AMD64 16코어, Windows 11, 모든 쓰기는 다음 쓰기가 전송되기 전에 내구성이 확보됩니다.

전체 백분위수, as_of 포인트 조회, 시간적 재현율, 콜드 스타트 수치는 benchmark/scale/에 있습니다.

직접 실행: python benchmark/scale/run.py

규모에 따른 재현율 정확도: 키워드 붕괴, 하이브리드 유지

속도는 기본입니다 — 에이전트 메모리에서 중요한 질문은 *올바른 메모리가 실제로 표면화되는가?*입니다. 고유 콘텐츠 코퍼스(자체 개발, 재현 가능; benchmark/lambda/ 참조)에서 모드별 recall@k를 측정했습니다:

100,000개 엔티티 (1×H100, nomic-embed-text on Ollama):

100K 엔티티에서 하이브리드 재현율은 @5에서 완벽한 반면 키워드 검색은 약 1.5%의 시간만 성공합니다 — 약 66배 차이입니다. 그리고 규모에 따라 더 벌어집니다: 10K 엔티티에서 키워드 재현율 @5는 0.008이었지만 하이브리드는 이미 1.000이었습니다. 키워드 전용 메모리는 에이전트가 기록을 축적함에 따라 조용히 성능이 저하되지만, 하이브리드(BM25 + 밀집 + 상호 순위 융합)는 그렇지 않습니다. 이것이 Perseus Vault의 하이브리드 검색의 핵심 주장입니다.

동일 박스, 동일 코퍼스, 모두 완전 로컬에서 일대일 비교 (1×H100, Ollama — 모든 시스템에 대해 동일한 사실 집합, 쿼리 및 부분 문자열 판정기):

모든 경쟁사는 동일한 박스에서 동일한 로컬 Ollama(qwen2.5:14b-instruct + nomic-embed-text)에 대해 설정 및 실행되었습니다 — 클라우드 없음, 조작된 수치 없음. Letta는 letta/letta 서버(번들 Postgres/pgvector)로 실행되었으며 Perseus Vault와 1.00으로 일치했습니다. Zep의 자체 호스팅 Community Edition 서버는 더 이상 사용되지 않으며 zep_python 메모리 API는 이제 Zep Cloud 전용이므로, 동일한 로컬 Ollama에서 엔티티/에지 추출 및 임베딩을 사용하여 Zep의 실제 OSS 엔진인 Neo4j의 Graphiti 시간적 KG를 측정했습니다. 0.20은 로컬 모델로 지식 그래프를 구축하는 정직한 비용을 반영합니다(구조화된 추출은 손실이 있음: 6개 사실에서 5개 엔티티/2개 에지) — 프론티어 모델을 사용하는 Zep Cloud가 아닙니다. 전체 아티팩트 + 방법론: benchmark/lambda/results/competitors.json.

콜드 스타트: 베어 GPU 박스는 3.3초 만에 첫 번째 근거 기반 RAG 답변에 도달합니다 (모델은 디스크에 스테이징됨).

재현: benchmark/lambda/scale_bench.py 및 competitors_bench.py.

GPU 호스트(vLLM on MI300X/H100)의 모델 서버 옆에 배포하시나요? AMD MI300X 배포 참조를 참조하세요 — 측정된 공동 상주 수치와 실제로 이러한 스택을 손상시키는 /dev/shm, PID-1 및 버전 고정 문제가 포함되어 있습니다.

프레임워크 통합

인기 있는 AI 에이전트 프레임워크의 기본 메모리 백엔드로 Perseus Vault를 만드는 즉시 사용 가능한 어댑터:

각 어댑터:

• MCP stdio 서브프로세스(영구 세션)를 통해 연결

• 프레임워크의 메모리 인터페이스를 Perseus Vault 도구에 매핑

• README 퀵스타트 제공 (5분이면 작동)

• 모의 MCP 전송으로 통과하는 테스트 포함

MCP 호환 프레임워크는 Perseus Vault와 직접 작동합니다. 전체 목록은 MCP 클라이언트 및 프레임워크 통합을 참조하세요.

150개의 정식 MCP 도구

정식 제품 및 도구 이름. Perseus Vault는 제품 이름이며, 통합은 정식 perseus_vault_* 도구(예: perseus_vault_remember)를 사용합니다. 레거시 mimir_* / mneme_* / plutus_* 이름은 2026-27 주요 릴리스에서 제거되었습니다 — 정식 이름이 유일한 인터페이스입니다. 개수는 소스 레지스트리에 있는 고유한 정식 도구의 수입니다. 호환성 별칭은 호출 가능하지만 별도로 계산되지 않습니다. 레거시 perseus_vault_* 및 perseus_vault_* 이름은 완전히 호출 가능한 상태로 유지됩니다 — 모든 접두사가 동일한 핸들러로 디스패치됩니다 — 단지 tools/list에 더 이상 광고되지 않습니다. 이렇게 하면 광고된 매니페스트가 도구당 하나의 이름으로 유지되어 세 배(3배 별칭 블로트)로 늘어나지 않으므로 연결된 클라이언트가 모든 요청에서 세 배로 늘어난 도구 스키마 페이로드를 다시 로드하지 않습니다. 세 가지 접두사를 모두 광고하는 이전 동작을 복원하려면 PERSEUS_VAULT_TOOL_ALIASES=all을 설정하세요(레거시 환경 변수 PERSEUS_VAULT_TOOL_ALIASES도 존중됨; PERSEUS_VAULT_가 우선함).

클라이언트 호환성 (#633). 광고된 목록을 기준으로 게이트하는 클라이언트 — 호출하기 전에 tools/list를 확인하고 보지 못한 도구는 건너뜀 — 2.x 볼트에 대한 레거시 perseus_vault_* 호출을 호출 자체는 성공하더라도 조용히 건너뜁니다. 알려진 사례: perseus CLI ≤ 1.0.22는 perseus_vault_recall을 하드코딩하고 빈 로컬 전용 재현으로 저하됩니다. 양쪽에서 수정: CLI를 ≥ 1.0.23으로 업그레이드(동적 폴백으로 정식 이름 호출)하거나, 이전 클라이언트가 배포된 상태에서 브리지로 볼트에 PERSEUS_VAULT_TOOL_ALIASES=all을 설정하세요.

도구 범위 (광고 계층, #1051)

기본적으로 tools/list는 모든 정식 도구를 광고합니다. PERSEUS_VAULT_TOOL_SCOPE를 설정하여 토큰 및 주의력이 제한된 에이전트 클라이언트를 위해 광고된 표면을 좁힙니다:

범위는 광고 전용입니다: 숨겨진 도구는 tools/call을 통해 완전히 호출 가능하며, 권한 부여는 워크스페이스 바인딩 및 권한 매니페스트와 함께 유지됩니다. 계층 분류는 1:1 사이드 테이블입니다(src/mcp.rs의 TOOL_SCOPES), scripts/registry_metadata_check.py에 의해 CI에서 강제됨 — 모든 새 도구는 분류되어야 합니다. admin 계층 도구(migrate, purge, erase, vault_import, authority_set / authority_revoke / authority_set_signed)는 범위가 지정된 목록에 절대 나타나지 않습니다.

엔티티 CRUD

검색 및 RAG

📖 docs/retrieval-modes.md — 모든 검색 모드(키워드 · 밀집 · 하이브리드 · 그래프 · GraphRAG · 사전 예방적 recall_when · 시간적 as_of)에 대한 하나의 열거형 참조: 메커니즘, 사용 시기, 호출 및 예제.

그래프

Journal

State

Lifecycle

Quality

Keystones (policy rules)

Vault & Federation

메트릭 및 운영

작업별 도구 (에이전트 치트 시트)

카테고리 목록이 아닌 작업 목록입니다. 에이전트가 수행하려는 작업에 해당하는 행을 선택하세요:

CLI

# Server
perseus-vault serve --db /data/perseus-vault.db
perseus-vault serve --web --port 8767 --encryption-key ~/.perseus-vault/secret.key
perseus-vault serve --llm-endpoint http://localhost:11434/api/generate --llm-model llama3
perseus-vault serve --transport sse --port 8787 --mcp-token my-secret-token

# Maintenance (operate directly on DB, no server needed)
perseus-vault stats          --db /data/perseus-vault.db
perseus-vault forget         --db /data/perseus-vault.db --category decision --key stale-choice --reason "superseded"
perseus-vault prune          --db /data/perseus-vault.db --category junk --min-decay 0.1 --dry-run
perseus-vault purge          --db /data/perseus-vault.db --dry-run
perseus-vault decay          --db /data/perseus-vault.db
perseus-vault reindex        --db /data/perseus-vault.db
perseus-vault vault-export   --db /data/perseus-vault.db --vault-dir ./export/
perseus-vault vault-import   --db /data/perseus-vault.db --vault-dir ./export/
perseus-vault obsidian-sync  ~/obsidian-vault/Perseus Vault/          # one-shot export to an Obsidian vault
perseus-vault obsidian-sync  ~/obsidian-vault/Perseus Vault/ --watch  # continuous sync on every memory change

# Key management
perseus-vault keygen --key-file ~/.perseus-vault/secret.key

# #918: read-only TUI inspector (retrieval telemetry, claim cards, entity
# state, decay, bi-temporal history). Never writes; repairs go through the
# governed MCP tools. Requires the default `tui` feature.
perseus-vault inspect --db /data/perseus-vault.db --key-file ~/.perseus-vault/secret.key

세션 재시작 없이 실시간 업데이트

perseus-vault serve는 세션 중간에 자체 바이너리가 디스크에서 교체되는 일반적인 cargo build / 재설치 흐름을 감지하고, 오래된 프로세스 이미지에서 결과를 제공하지 않습니다. 모든 도구는 빈 결과로 저하되는 대신 명확하고 명시적인 오류를 반환합니다 (#858, #1045). 두 가지 복구 경로가 있으며, 둘 다 동일한 stdio 연결에서 작동합니다 (클라이언트 재시작 불필요):

• 명시적: perseus_vault_handoff_restart {"confirm": true} 호출 — 프로세스가 새 바이너리로 핫스왑되고 세션이 중단 없이 계속되며, MCP 세션 상태(초기화 + 에이전트 ID)가 유지됩니다.

• 자동 (옵트인): PERSEUS_VAULT_AUTO_HANDOFF=1로 서버를 시작하면 다음 도구 호출 시 투명하게 스왑이 이루어지며, 새 바이너리가 직접 응답합니다.

macOS/Linux에서 스왑은 진정한 exec입니다 (동일 PID, 동일 파이프). Windows는 실행 중인 실행 파일을 잠그므로 세션 중간 교체가 불가능합니다. 업데이트는 세션 경계를 넘어 수행하세요. 전체 계약 및 로컬 개발 워크플로우: docs/specs/live-update-handoff.md.

수동 DB 편집. 위의 유지보수 동사와 일반적인 MCP 쓰기 경로는 FTS5 인덱스를 자동으로 동기화합니다. sqlite3로 entities 테이블을 직접 편집(수동 DELETE/UPDATE)하면 해당 동기화를 우회하고 고아 인덱스 행이 남을 수 있습니다. 이미 사라진 콘텐츠에 대한 "유령" 회상 결과입니다. 직접 SQL 편집 후에는 perseus-vault maintain --db <경로> (또는 perseus-vault reindex)를 실행하여 FTS 인덱스를 조정하세요.

플래그

데이터베이스 위치

표준 데이터베이스 경로는:

~/.perseus-vault/data/perseus-vault.db

스크립트, MCP 호스트 구성, cron/수집 작업에서 항상 --db를 전달하거나 $PERSEUS_VAULT_DB_PATH를 설정하여 모든 호출이 동일한 파일을 대상으로 하도록 하세요. 둘 다 설정되지 않은 경우, Perseus Vault는 이 순서로 기본값을 확인하고 이미 존재하는 첫 번째 경로를 사용합니다 (업그레이더와 레거시 단일 사용자 설치가 빈 상태로 조용히 시작되지 않도록 포착합니다):

1. ~/.perseus-vault/data/perseus-vault.db — 표준 (현재 이름)

2. ~/.perseus-vault/data/perseus-vault.db — 이름 변경 전

3. ~/.perseus-vault/data/perseus-vault.db — 이름 변경 전

4. ~/perseus-vault.db — 레거시 단일 사용자 설치 위치

어느 것도 존재하지 않으면 ~/.perseus-vault/data/perseus-vault.db를 생성합니다. 이 중 두 개 이상 존재하고 --db/$PERSEUS_VAULT_DB_PATH를 전달하지 않은 경우, Perseus Vault는 선택한 파일과 무시한 다른 파일을 stderr 경고로 출력하여 모호한 다중 데이터베이스 상태가 조용히 넘어가지 않도록 합니다. --db 또는 $PERSEUS_VAULT_DB_PATH를 명시적으로 설정하면 항상 우선 적용되며 경고를 표시하지 않습니다.

Obsidian에서의 AI 메모리

Perseus Vault는 AI 에이전트의 장기 메모리이며, 당신의 두 번째 뇌 역할도 합니다. 에이전트가 기억하는 모든 엔터티는 YAML 프론트매터가 포함된 일반 Markdown 노트로 내보내지므로, AI의 메모리가 이미 사용 중인 도구(Obsidian, Logseq, Notion) 내에서 탐색 가능한 개인 지식 베이스가 됩니다.

# Export your entire memory to an Obsidian vault as linked Markdown notes
perseus-vault obsidian-sync ~/obsidian-vault/Perseus Vault/

# Keep it live — re-export automatically on every memory change
perseus-vault obsidian-sync ~/obsidian-vault/Perseus Vault/ --watch

Obsidian에서 볼트를 열면 에이전트 지식의 그래프를 얻을 수 있습니다.

WikiLink 백링크. 하나의 엔터티가 다른 엔터티에 연결되면 (perseus_vault_link 또는 depends_on / implements / references 관계를 통해), 내보낸 노트에는 ## Links 섹션이 생기고 Obsidian의 그래프 뷰에서 기본적으로 해석되는 [[WikiLink]] 백링크가 포함됩니다:

---
id: cli-de8dfb8364b6
category: architecture
key: api
type: insight
decay_score: 0.5000
---

{"content":"axum service"}

## Links

- [[cli-99756b494c7d|database]] (depends_on)

링크는 엔터티 ID로 확인되므로 (노트는 <id>.md로 작성됨) 절대 깨지지 않으며, Obsidian은 사람이 읽을 수 있는 key를 링크 레이블로 표시합니다. 그래프 뷰를 열면 에이전트의 아키텍처, 결정, 인사이트가 클릭 가능한 지식 맵이 됩니다.

**--watch**는 간격에 따라 Perseus Vault의 저렴하고 결정적인 상태 요약을 폴링하며, 메모리가 실제로 변경될 때만 다시 내보냅니다. 파일시스템 감시자 종속성이나 서버와의 결합 없이 모든 perseus_vault_remember 쓰기를 자연스럽게 포착합니다. PERSEUS_VAULT_SYNC_INTERVAL_SECS로 간격을 조정하세요 (기본값: 2초).

기타 PKM 도구

클라우드 전용 "두 번째 뇌" 도구와 달리, Perseus Vault는 100% 로컬에서 실행되며, Rust로 작성되었고, AES-256-GCM으로 저장 시 암호화하며, 감쇠 점수를 적용하여 오래된 메모리가 희미해집니다. 지식 베이스는 항상 당신의 것이며 신선하게 유지됩니다.

기능

의미 검색 (기본으로 켜짐)

• 번들된 인-프로세스 임베딩 — 양자화된 all-MiniLM-L6-v2 모델(384차원)이 바이너리에 컴파일되어 있어, 별도 설정과 네트워크 없이 밀집/의미 기반 검색이 작동합니다: Ollama, API 키, 모델 다운로드가 필요 없습니다. 이것이 기본 빌드입니다(bundled-embeddings 기능).

• 쓰기 시 자동 임베딩 (#271) — perseus_vault_remember는 각 새(또는 내용이 변경된) 엔티티를 쓰는 즉시 동기적으로 번들 모델을 사용해 임베딩합니다. 단일 엔티티 임베딩은 결정적이며 LRU 캐시되므로 비용이 적고 백그라운드 작업이 추가되지 않습니다. 임베딩 실패는 치명적이지 않으며(stderr에 기록됨), 쓰기는 항상 성공합니다.

• 하이브리드가 기본 회상 모드입니다 (#271) — mode 플래그 없이 perseus_vault_recall(query=...)을 호출하면 임베딩이 존재할 때 자동으로 하이브리드(RRF를 통해 융합된 밀집 + 키워드)를 선택하고, 임베딩이 없을 때는 투명하게 fts5 키워드 검색으로 대체됩니다. 수동 perseus_vault_embed 단계나 기억해야 할 플래그가 없습니다.

• perseus_vault_semantic_search(query, limit) — "이런 것 찾아줘"와 같은 순수 의미 기반 검색(키워드 대체 없음)을 위한 원툴 단축키입니다.

• 선택적 대체 임베더 — 번들 모델 대신 Ollama 또는 OpenAI 호환 /v1/embeddings 엔드포인트를 사용하려면 --llm-endpoint(필요에 따라 --embedding-endpoint / --llm-api-key)를 설정하세요. 이는 완전히 선택 사항이며, 기본적으로 번들 모델이 사용됩니다.

• cargo build --no-default-features를 통해 번들 임베딩 없이 경량 바이너리를 빌드할 수 있습니다. 이 경우 원격 임베더가 구성되지 않으면 회상이 기본적으로 키워드 검색으로 설정됩니다.

하이브리드 검색 내부

• FTS5 키워드 검색 — LIKE 대체 및 Porter 형태소 분석 확장 포함

• 밀집 벡터 검색 — 저장된 임베딩에 대한 코사인 유사도 기반

• 상호 순위 융합(RRF) — 키워드 + 벡터 결과 결합

• 쿼리 확장 — 더 넓은 회상을 위한 자동 형태소 분석 변형

메모리 생애주기

Perseus Vault는 인간의 기억 경로에서 영감을 받은 세 가지 생체 모방 계층을 사용하여 메모리를 모델링합니다:

• 세계 (핵심): 느리게 소멸되는 환경에 대한 전반적 사실.

• 일화 (버퍼): 빠르게 소멸되는 세션별 상호작용 기록.

• 의미 (작업): 중간 속도로 소멸되는 일반 지식 및 학습된 개념.

perseus_vault_recall_layer 도구를 사용하거나 perseus_vault_remember에서 layer 매개변수를 지정하여 이러한 계층과 직접 상호작용할 수 있습니다.

• 에빙하우스 소멸 — 기억은 검색되지 않으면 자연스럽게 사라집니다(접근 시 새로고침).

• 계층 승격 — 접근 빈도에 따라 버퍼 → 작업 → 핵심으로 승격됩니다.

• 자동 보관 — 오래된 엔티티는 보관되며, 영구 삭제 및 VACUUM을 위해 제거할 수 있습니다.

• 항상 켜진 엔티티 — 세션 주입을 위해 정체성에 중요한 기억을 고정합니다(회상 우선 시 하드 캡; recall_when 트리거 선호).

• 예비 쿼리 힌트 (#919) — 엔티티당 선택적 1~3개의 자연어 표현(perseus_vault_remember의 hints)으로, 본문과 함께 FTS5에 색인되어 일반 언어 쿼리와 저장된 표현 간의 어휘 격차를 해소합니다. 기본적으로 비활성화됨(PERSEUS_VAULT_HINTS_ENABLED=1); 비활성화 시 거부됨. docs/specs/prospective-query-hints.md 참조.

회상 우선 컨텍스트 주입

볼트는 쿼리 계층입니다. 호스트에 고정된 블롭을 넘겨 모든 시스템 프롬프트에 포함시키는 대신, 한 턴에 필요한 몇 가지 사실만 검색합니다. perseus_vault_context와 perseus-vault prepare는 기본적으로 회상 우선입니다:

• 관련성 게이팅 — query(현재 작업/메시지)를 전달하면 recall_when 트리거 또는 색인된 내용이 일치하는 엔티티만 주입됩니다. 쿼리가 없으면 주제별 주입이 없습니다: 블록은 간결한 검색 포인터로, 관련 없는 볼트 쓰기 전반에 걸쳐 바이트 안정적입니다(프리픽스 캐시 친화적).

• 모델별 회상 예산 — 출력은 호스트 모델에서 확인된 문자 예산으로 제한됩니다: 기본/경량 프로필 1500자, 대형 창("opus") 프로필 6000자; max_context_chars는 둘 다 재정의합니다.

• 제한된 항상 켜짐 — always_on: true는 정체성에 중요한 사실에 대해 여전히 작동하지만, 회상 우선 세트는 하드 캡(상위 5개)되며 오버플로 시 recall_when 트리거를 사용하도록 안내하는 경고가 발생합니다.

• 레거시 옵트인 — 예산을 전달하지 않는 한, mode: "always_inject"(prepare의 경우 --legacy-context)를 사용하면 이전의 무조건적인 상위-N 덤프를 계속 사용할 수 있습니다.

perseus-vault prepare --task "deploying the payments service" --model claude-sonnet-4-6
perseus-vault prepare --task "..." --max-context-chars 800     # explicit budget
perseus-vault prepare --task "..." --legacy-context            # old dump, opt-in

RAG 및 임베딩

• perseus_vault_ask — 모든 LLM(Ollama, OpenAI 등)을 통해 저장된 기억에 대한 자연어 Q&A

• perseus_vault_embed — Ollama 또는 OpenAI 호환 /v1/embeddings를 통해 밀집 벡터 생성 및 저장

• 단일 엔티티 및 배치 카테고리 임베딩 지원

암호화

• 엔티티 body_json에 대한 AES-256-GCM 투명 암호화

• 새 설치 시 기본 활성화 — 첫 번째 쓰기 시 ~/.perseus-vault/secret.key에 표준 키가 자동 생성됩니다.

• 명시적 키를 위한 --encryption-key 플래그; 사용자 정의 키 생성을 위한 perseus-vault keygen

• 기존 일반 텍스트 데이터베이스는 init --rekey 마이그레이션 경로(또는 명시적 PERSEUS_VAULT_ALLOW_PLAINTEXT=1)로 닫힌 상태에서 실패합니다.

• FTS5 인덱스는 검색을 위해 일반 텍스트로 유지됩니다.

웹 대시보드

• 내장 Axum HTTP 서버 (perseus-vault serve --web --port 8767)

• 검색, 엔티티 테이블, vis.js 그래프, 타임라인이 포함된 다크 테마 대시보드

• 기본 바인드: 127.0.0.1 (노출하려면 --web-bind 0.0.0.0 사용)

• 동시 읽기를 위한 WAL 모드의 별도 SQLite 연결

외부 커넥터

• GitHub 이슈 커넥터 — 저장소별 이슈/PR 수집, 속도 제한 인식

• 파일 감시자 — 콘텐츠 해시 중복 제거로 .md/.txt/.json 파일 디렉토리 스캔

• --connectors-config를 통한 YAML 기반 커넥터 구성

다중 전송

• stdio (기본값) — 별도 설정 불필요, 모든 MCP 호스트와 작동

• SSE — HTTP 기반 MCP 클라이언트를 위한 서버 전송 이벤트

• HTTP — REST 스타일 MCP 엔드포인트

• Bearer 토큰 인증 — SSE/HTTP 전송용

Perseus 통합

Perseus Vault는 Perseus의 기본 메모리 백엔드입니다:

perseus_vault:
  enabled: true
  transport: "stdio"
  command: ["perseus-vault", "serve", "--db", "~/.perseus-vault/data/perseus-vault.db"]
  timeout_s: 30.0
  merge_strategy: "local_first"
  fallback_to_local: true
  context_categories: ["decision", "architecture", "convention"]
  context_limit: 10

정부 및 연방 조달

Perseus Vault는 처음부터 정부 배포를 위해 구축되었습니다.

연방 구매자용: 조달 정보, 규정 준수 상태 및 배포 모델(에어갭, 온프레미스, 기밀 환경)은 docs/federal-buyers.md를 참조하세요.

Perseus Computing LLC는 미국 소유의 소기업입니다. SAM.gov 등록 진행 중. NAICS: 541715, 541511, 541512.

개인정보 보호정책

Perseus Vault는 로컬 우선 MCP 서버입니다 — 사용자 기기에서 완전히 실행됩니다.

데이터 수집

• 데이터 수집 없음. Perseus Vault는 사용자 데이터, 사용 통계 또는 원격 측정 데이터를 수집, 전송 또는 전화 연결하지 않습니다.

• 모든 데이터는 로컬 SQLite 데이터베이스 파일에 남아 있습니다.

데이터 사용 및 저장

• 모든 메모리 엔티티, 저널 항목 및 상태는 --db를 통해 지정한 경로의 로컬 SQLite 데이터베이스에 저장됩니다.

• 선택적 저장 시 AES-256-GCM 암호화를 사용할 수 있습니다. 활성화하면 엔티티 본문이 저장 전에 암호화됩니다.

• 데이터는 Perseus Computing LLC 또는 제3자와 공유되지 않습니다.

제3자 공유

• 없음. Perseus Vault는 기본적으로 완전히 에어갭되어 있습니다. API 호출, 클라우드 서비스, 외부 네트워크 요청이 없습니다.

• 선택적 밀집 벡터 임베딩 기능은 로컬에서 컴파일된 모델을 사용합니다. 외부 임베딩 API가 호출되지 않습니다.

데이터 보존

• 네 가지 별개의 생애주기 작업을 통해 보존을 제어합니다(docs/specs/data-boundaries-retention-lifecycle.md 참조): 소프트 삭제(perseus_vault_forget, 콘텐츠 복구 가능), 만료(perseus_vault_expire, 시간 기반 status='expired', 콘텐츠 유지), 편집(perseus_vault_redact, 콘텐츠를 해시 전용으로 정리, 메타데이터 유지), 물리적 삭제(perseus_vault_erase, 모든 파생 계층에서 제거 및 영구 재수집 억제). perseus_vault_purge는 보관된 행에서 공간을 회수합니다.

• 자동 오프머신 백업은 수행되지 않습니다.

연락처

• 이메일: privacy@perseus.observer

• GitHub: Perseus-Computing-LLC/perseus-vault

릴리스 검증

릴리스 바이너리는 GitHub Actions를 통해 태그된 커밋에서 빌드됩니다. 모든 릴리스에는 다음이 포함됩니다:

릴리스 바이너리 검증

# 1. Verify SHA-256 checksum
sha256sum -c perseus-vault-lite-x86_64-unknown-linux-musl.tar.gz.sha256

# 2. Verify SLSA build provenance (requires gh CLI + OIDC session)
gh attestation verify perseus-vault-lite-x86_64-unknown-linux-musl.tar.gz \
  --repo Perseus-Computing-LLC/perseus-vault

# 3. Confirm the binary identity
./perseus-vault --version
# Should show both the release version AND the git commit hash, e.g.:
#   perseus-vault 2.20.2 (v2.20.2-0-gabcdef1)

# 4. Confirm the doctor reports the same identity
./perseus-vault doctor --db /tmp/test.db | head -1
#   perseus-vault doctor — v2.20.2 (v2.20.2-0-gabcdef1)

소스에서 재현 가능하게 빌드

# The exact same binary (bit-for-bit) requires matching:
#   - Rust toolchain version (see rust-toolchain.toml)
#   - Locked dependencies: `cargo build --locked`
#   - Build flags: `--release` for release builds

cargo build --locked --release
./target/release/perseus-vault --version

라이선스

MIT — LICENSE 참조.