Perseus Vault

Dauerhafter, verschlüsselter Speicher für KI-Agenten. Ein Rust-Binary, eine Datei, keine Cloud.

Veröffentlicht auf Official MCP Registry · Glama · mcpservers.org · Lulu MCPs · Docker (GHCR)

Geben Sie Ihren Agenten einen Speicher, der die Sitzung überdauert, damit sie aufhören, bereits Gelerntes neu abzuleiten und vergangene Fehler zu wiederholen. Hybrider Abruf (BM25 + dicht + RRF), bi-temporale Historie und AES-256-GCM im Ruhezustand, bereitgestellt als 168 kanonische MCP-Tools, die mit jedem Host funktionieren. Legacy-mimir_*/mneme_*-Aliase wurden im Haupt-Release 2026-27 entfernt und werden nicht separat gezählt. 73,8 % im offiziellen LongMemEval-Harness (vs. Zep 63,8 %, Mem0 49,0 %). Ein Binary. Eine Datei. Kein Docker. Kein Postgres. Keine Cloud. Lokal zuerst, abhörsicher, MIT.

Einzeilige Installation

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

Das war's. Perseus Vault wird in ~/.local/bin/perseus-vault installiert. Starten Sie es:

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

Die Verschlüsselung ist für die Standardinstallation automatisch aktiviert. Der erste Durchlauf erstellt ~/.perseus-vault/secret.key mit Berechtigungen nur für den Besitzer und eine verschlüsselte Datenbank-Canary. Sichern Sie diesen Schlüssel: Er kann nicht wiederhergestellt werden. Explizite --encryption-key-Pfade werden weiterhin unterstützt, und vorhandene Klartext-Datenbanken werden für die Migration mit perseus-vault init --rekey bewahrt. Verwenden Sie doctor, um den tatsächlichen Zustand auf der Festplatte zu überprüfen.

macOS-Hinweis (Apple Silicon). Ein frisch erstelltes oder kopiertes Binary wird beim ersten Start von der OS-Binary-Richtlinie mit SIGKILL beendet (Killed: 9, keine andere Ausgabe) – selbst ohne Quarantäne-Attribut. Der Einzeiler-Installer und der bootstrap.sh-Build-from-Source-Installer signieren Perseus Vault für Sie ad-hoc mit Code. Wenn Sie das Binary selbst erstellen, signieren Sie es einmal nach jedem Neubau:

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 signiert ein bereits signiertes Binary neu (nach jedem Neubau erforderlich); der Schritt ist auf Intel macOS harmlos und auf Linux/Windows unnötig.

Dann verbinden Sie Ihren/Ihre MCP-Client(s) – und die vollständige Recall-/Capture-Schleife – mit einem Befehl:

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

Dies erkennt automatisch Claude Code / Codex / Cursor (übergeben Sie --client <name> für claude-desktop, hermes, windsurf, vscode, zed oder generic; --all-detected verbindet jeden erkannten Client), führt die MCP-Server-Registrierung in die Konfiguration des Clients zusammen, ohne etwas zu überschreiben (eine .bak-perseus-Sicherung wird zuerst geschrieben), weist jeden Client auf eine gemeinsame Speicherdatenbank, registriert die Session-Lifecycle-Hooks (Recall-Injektion bei SessionStart, Hygiene bei Sessionende – der docs/lifecycle-hooks.md-Vertrag) und hängt die Speichernutzungsregeln an CLAUDE.md/AGENTS.md an. Ein erneuter Durchlauf ist ein No-Op; fügen Sie --dry-run hinzu, um eine Vorschau jeder Datei zu erhalten, die es berühren würde.

Oder verbinden Sie einen beliebigen MCP-Host von Hand (Claude Desktop, Cursor, Hermes Agent, Perseus usw.):

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

Related MCP server: GroundMemory

Für Agenten: Verbindung über MCP

Wenn der primäre Verbraucher ein Agent ist, ist die Schnittstelle MCP – der Agent übernimmt den Vault über seinen MCP-Client, und es ist keine CLI-Installation pro Maschine über das Ausführen des Servers selbst hinaus erforderlich:

# 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 verdrahtet die gesamte Recall-/Capture-Schleife für Claude Code / Codex / Cursor / Hermes in einem Befehl. Für die agentenorientierte Fähigkeitskarte – welches Tool welche Aufgabe erledigt und das Planungsgrenzen-Muster – siehe docs/integration/agent-adoption.md.

30-Sekunden-Schnellstart

# 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

Speichermodell und Betriebsgrenzen

Perseus Vault hält drei Ebenen getrennt:

• Impliziter Arbeitskontext ist der aktuelle Prompt, das Transkript und jeder Kontextblock, den ein Client einzufügen wählt. Er ist flüchtig und gehört dem Host; er wird nicht allein dadurch gespeichert, dass der Vault ihn zurückgegeben hat.

• Expliziter dauerhafter Speicher wird durch eine explizite perseus_vault_remember-, perseus_vault_capture-, write- oder capture- Operation geschrieben. Der Vault-Server besitzt den SQLite-Datensatz, die Historie, das Journal, den Verfall, das Archiv und den Bereinigungslebenszyklus.

• Abgeleitete Projektionen umfassen konsolidierte oder synthetisierte Datensätze und exportiertes Markdown. Sie tragen eine Herkunftsangabe, sind aber kein Ersatz für die dauerhaften Quelldatensätze und benötigen möglicherweise eine separate Bereinigung.

perseus-vault prepare und perseus_vault_context lesen dauerhafte Datensätze, um einen begrenzten, aufgabenrelevanten aktiven Arbeitskontext zu erzeugen. Dies ist eine rollierende Momentaufnahme, kein Hintergrundschreibvorgang oder ein Versprechen, dass der Client sie behält: Aktualisieren Sie sie, wenn sich die Aufgabe ändert, und behandeln Sie Prompt-Text nicht als dauerhaften Speicher, es sei denn, eine explizite Capture-/Write-Operation ist erfolgreich. Die Recall-First-Ausgabe ist budgetiert (standardmäßig 1500 Zeichen, 6000 für Hosts mit großem Fenster oder ein explizites max_context_chars); die always_on-Menge ist auf fünf begrenzt. Siehe Aufbewahrungs- und Kontextsemantik.

Lifecycle-Hooks und Client-Installer sind optionale Orchestrierung. Sie fordern servereigenen Recall, Capture, Wartung und Aktualisierungsarbeit an; sie werden nicht zu einem zweiten Speicher oder ändern die Aufbewahrungsrichtlinie. Wenn der Server oder ein Hook nicht verfügbar ist, setzen Sie die Aufgabe ohne injizierten Speicher fort und zeigen Sie den beeinträchtigten Zustand an. Eine Host-Integration kann einen explizit konfigurierten lokalen Fallback haben, aber dieser Fallback muss als rein lokal gekennzeichnet sein und darf nicht als dauerhafter Vault-Recall präsentiert werden; ein fehlgeschlagener expliziter Schreibvorgang darf niemals als persistent gemeldet werden. Für Upgrade-/Wiederherstellungsschritte verwenden Sie das Upgrade- und Migrations-Playbook.

Funktioniert mit jedem MCP-Client

Perseus Vault ist ein standardmäßiger MCP stdio-Server – derselbe perseus-vault serve-Befehl funktioniert überall. Führen Sie perseus-vault doctor aus, um Ihre Installation zu validieren und diese Matrix lokal auszudrucken.

Kopier- und Einfüge-Konfigurationsschnipsel für jeden: docs/clients/.

Dann verdrahten Sie die Recall → Arbeit → Capture → Konsolidieren-Schleife mit den Sitzungsereignissen Ihres Clients (SessionStart/Stop-Hooks für Claude Code, Codex und Cursor, plus einen portablen AGENTS.md-Fallback): docs/lifecycle-hooks.md.

Kombinieren mit einem Memory-Washer (CoalWash) und einem Laufzeit-Ausgabe-Kompaktor (Noisegate) für eine durchgängige Kontextbudget-Kontrolle: docs/integration/context-budget-stack.md.

Prüfen, woran sich der Vault erinnert, woher und unter welcher Autorität: docs/evidence-chain-guidance.md – Evidenzketten, Schreibzeit-Herkunfts-Tags und kontinuierliche Bescheinigung für dauerhaften Speicher.

Speicherbänke (clientübergreifende Isolation, ein Profil)

Agentur, die 50 Clients mit demselben Playbook betreibt? Duplizieren Sie keine Profile – bezeichnen Sie die Speicherbank pro Projekt und behalten Sie ein Hermes-Profil, einen Vault und eine gemeinsame Fähigkeitsbibliothek:

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

Der Hermes-Speicheranbieter (hermes plugins install Perseus-Computing-LLC/hermes-plugin-perseus-vault) löst die Bank einmal pro Sitzung auf und begrenzt jeden Vault-Lese- und Schreibvorgang – Prefetch-Recall, perseus_recall / perseus_remember / perseus_forget, Sitzungsende-Capture – auf einen dedizierten Arbeitsbereich. Banknamen werden deterministisch abgebildet (sha256("memory-bank:" + name)), sodass jede Instanz, die auf denselben Namen zeigt, denselben Arbeitsbereich adressiert, ohne ein Registry verwalten zu müssen. Arbeitsbereiche sind erstklassig auf dem Server: bereichsbezogene Wartung, Deduplizierungsisolierung zwischen Bänken und Autorisierungsmanifeste pro Arbeitsbereich. Die Erkennung spiegelt die Hermes-Projektkontextregeln wider (nächstgelegene .hermes.md gewinnt, begrenzt auf das Git-Root); eine Kontextdatei ohne Direktive bedeutet keine Bank – der konfigurierte Arbeitsbereich bleibt in Kraft.

Warum Perseus Vault

Perseus Vault ist die einzige Speicher-Engine, die gleichzeitig MCP-nativ, lokal-zuerst, null-Abhängigkeiten UND agenten-zuerst ist.

LongMemEval QA (offizieller Harness)

Abrufqualität gemessen am offiziellen LongMemEval-Harness, nicht an einem hausgemachten Skript:

longmemeval_s (500 Fragen), gpt-4o-2024-08-06 Beantworter + LongMemEvals offizieller Richter; Wettbewerberzahlen sind ihre veröffentlichten Werte. Perseus Vaults 73,8 % ist der einfache Mittelwert von 3 Läufen; 79,0 % mit offiziellem CoT. Methodik & inhaltsgehashte (sha256) Ergebnisse →

LOCOMO (mem0s eigener Harness)

Gemessen an mem0s eigenem LOCOMO-Harness (unser Fork), nicht unserem – Kategorien 1–4, 1.540q, Top-200, gpt-5 Beantworter + Richter:

Kat-5 adversarial (446q): Perseus 63,5, Mem0 55,6, Zep 49,8. Unsere Mem0-Messung liegt 9,4 Punkte unter ihrer veröffentlichten Datei (Richter/Plattform-Drift – offengelegt). Vollständige Rangliste →

Bi-temporale Zeitreise (drei Achsen)

Unser stärkstes strukturelles Unterscheidungsmerkmal – vollständige SQL:2011 bi-temporale Historie (Transaktionszeit und Gültigkeitszeit) – gemessen an einem reproduzierbaren, vollständig offline-Durchgang. Es treibt das tatsächlich ausgelieferte Binary über MCP stdio durch die harten Fälle, die Einachsen-Wettbewerber falsch machen (rückwirkende Korrekturen, proaktive zukünftige Fakten, außerhalb der Reihenfolge eintreffende, Glaubens-vs-Wahrheit Abweichung, geschlossene Zeiträume):

Mit einem einzigen Befehl reproduzieren (kein API-Schlüssel, kein Netzwerk, kein LLM):

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

Die PASS/FAIL-Ergebnisse sind deterministisch (Wanduhr-Zeitstempel variieren, Ergebnisse nicht), daher führt ein korrekter Build zu einer identischen signature_sha256. Die festgeschriebene gauntlet_report.json ist die Referenz. Methodik & Datensatz →

Vergleichsmatrix

Vollständiger Vergleich: Perseus Vault vs Mem0 → vs Letta → vs Zep →

Stresstest: 100.000 Entitäten

Perseus Vault bewältigt Produktionslasten auf bescheidener Hardware. Die folgenden Zahlen stammen aus dem festgeschriebenen Artefakt benchmark/scale/report.json: die echte Release-Binärdatei, gesteuert über MCP stdio (ein persistenter Prozess pro Korpusgröße), AMD64 16-Kern, Windows 11, jeder Schreibvorgang dauerhaft, bevor der nächste gesendet wird.

Vollständige Perzentile, as_of-Punktabfragen, zeitlicher Abruf und Kaltstartzahlen finden Sie in benchmark/scale/.

Führen Sie es selbst aus: python benchmark/scale/run.py

Abrufgenauigkeit bei Skalierung: Stichwort bricht ein, Hybrid hält

Geschwindigkeit ist Grundvoraussetzung – die entscheidende Frage für Agentenspeicher ist, taucht die richtige Erinnerung tatsächlich auf? Gemessen an Korpora mit unterschiedlichem Inhalt (eigen, reproduzierbar; siehe benchmark/lambda/), recall@k nach Modus:

100.000 Entitäten (1×H100, nomic-embed-text auf Ollama):

Bei 100.000 Entitäten ist der hybride Abruf perfekt @5, während die Stichwortsuche nur ~1,5 % der Zeit trifft – eine ~66-fache Lücke. Und sie vergrößert sich mit der Skalierung: Bei 10.000 Entitäten lag der Stichwort-Abruf @5 bei 0,008, während der hybride bereits 1,000 erreichte; ein reiner Stichwortspeicher verschlechtert sich leise, während ein Agent Verlauf ansammelt, der hybride (BM25 + dicht + Reciprocal-Rank-Fusion) nicht. Dies ist das Kernargument für den hybriden Abruf von Perseus Vault.

Direkter Vergleich, gleiche Maschine, gleicher Korpus, alle vollständig lokal (1×H100, Ollama – identischer Faktenbestand, Abfragen und Teilstring-Richter für jedes System):

Jeder Mitbewerber wurde aufgesetzt und live auf derselben Maschine gegen dasselbe lokale Ollama (qwen2.5:14b-instruct + nomic-embed-text) ausgeführt – keine Cloud, keine erfundenen Zahlen. Letta lief als letta/letta-Server (mit gebündeltem Postgres/pgvector) und erreichte ebenfalls 1,00. Zeps selbst gehosteter Community Edition Server ist veraltet und seine zep_python-Speicher-API ist jetzt nur noch Zep Cloud, daher haben wir Zeps tatsächliche OSS-Engine gemessen – Graphiti zeitlicher Wissensgraph auf Neo4j – mit Entitäts-/Kantenextraktion und Einbettungen auf demselben lokalen Ollama. Seine 0,20 spiegeln die ehrlichen Kosten des Aufbaus eines Wissensgraphen mit einem lokalen Modell wider (strukturierte Extraktion ist verlustbehaftet: 5 Entitäten / 2 Kanten aus 6 Fakten) – nicht Zep Cloud, das Grenzmodelle verwendet. Vollständiges Artefakt + Methodik: benchmark/lambda/results/competitors.json.

Kaltstart: Eine nackte GPU-Maschine erreicht ihre erste fundierte RAG-Antwort in 3,3 s (Modelle auf der Festplatte bereitgestellt).

Reproduzieren: benchmark/lambda/scale_bench.py und competitors_bench.py.

Bereitstellung neben einem Modellserver auf einem GPU-Host (vLLM auf MI300X/H100)? Siehe die AMD MI300X Bereitstellungsreferenz – gemessene Co-Residency-Zahlen sowie die /dev/shm-, PID-1- und Version-Pinning-Fallstricke, die diese Stapel in der Praxis zum Scheitern bringen.

Framework-Integrationen

Einsatzbereite Adapter, die Perseus Vault zum standardmäßigen Speicher-Backend für beliebte KI-Agenten-Frameworks machen:

Jeder Adapter:

• Verbindet über MCP stdio-Subprozess (persistente Sitzung)

• Bildet die Speicherschnittstelle des Frameworks auf Perseus Vault-Werkzeuge ab

• Enthält eine README-Schnellstartanleitung (5 Minuten bis zur Funktionsfähigkeit)

• Hat bestandene Tests mit simuliertem MCP-Transport

Jedes MCP-kompatible Framework funktioniert direkt mit Perseus Vault. Siehe MCP-Client- und Framework-Integrationen für die vollständige Liste.

150 kanonische MCP-Werkzeuge

Kanonische Produkt- und Werkzeugnamen. Perseus Vault ist der Produktname, und Integrationen verwenden die kanonischen perseus_vault_*-Werkzeuge (z. B. perseus_vault_remember). Die veralteten Namen mimir_* / mneme_* / plutus_* wurden im Hauptrelease 2026-27 entfernt – die kanonischen Namen sind die einzige Schnittstelle. Die Anzahl ist die Anzahl der eindeutigen kanonischen Werkzeuge im Quellregister. Kompatibilitätsaliase sind aufrufbar, werden aber nicht separat gezählt. Die veralteten Namen perseus_vault_* und perseus_vault_* bleiben vollständig aufrufbar – jedes Präfix leitet an denselben Handler weiter – sie werden nur nicht mehr in tools/list angezeigt. Dadurch bleibt das angezeigte Manifest bei einem Namen pro Werkzeug, anstatt es zu verdreifachen (3× Alias-Aufblähung), sodass verbundene Clients nicht bei jeder Anfrage eine verdreifachte Werkzeugschema-Nutzlast neu laden. Um das historische Verhalten der Anzeige aller drei Präfixe wiederherzustellen, setzen Sie PERSEUS_VAULT_TOOL_ALIASES=all (die veraltete Umgebungsvariable PERSEUS_VAULT_TOOL_ALIASES wird ebenfalls beachtet; PERSEUS_VAULT_ hat Vorrang).

Client-Kompatibilität (#633). Clients, die auf die angezeigte Liste prüfen – sie überprüfen tools/list vor dem Aufruf und überspringen Werkzeuge, die sie nicht sehen – werden stillschweigend veraltete perseus_vault_*-Aufrufe gegen einen 2.x-Vault überspringen, obwohl der Aufruf selbst erfolgreich wäre. Bekannter Fall: Die perseus CLI ≤ 1.0.22 kodiert perseus_vault_recall fest und degradiert zu leerem lokalem Abruf. Behebung auf beiden Seiten: Aktualisieren Sie die CLI auf ≥ 1.0.23 (ruft kanonische Namen mit dynamischem Fallback auf) oder setzen Sie PERSEUS_VAULT_TOOL_ALIASES=all auf dem Vault als Brücke, während ältere Clients noch bereitgestellt sind.

Werkzeugbereiche (Anzeigestufen, #1051)

Standardmäßig zeigt tools/list jedes kanonische Werkzeug an. Setzen Sie PERSEUS_VAULT_TOOL_SCOPE, um die angezeigte Oberfläche für token- und aufmerksamkeitsbeschränkte Agenten-Clients einzuschränken:

Bereiche sind nur für die Anzeige: Ein verstecktes Werkzeug bleibt über tools/call vollständig aufrufbar, und die Autorisierung erfolgt über Arbeitsbereichsbindung und Autoritätsmanifeste. Die Stufeneinteilung ist eine 1:1-Nebentabelle (TOOL_SCOPES in src/mcp.rs), CI-erzwungen durch scripts/registry_metadata_check.py – jedes neue Werkzeug muss klassifiziert werden. admin-Stufenwerkzeuge (migrate, purge, erase, vault_import, authority_set / authority_revoke / authority_set_signed) erscheinen nie in einer bereichsbezogenen Liste.

Entitäts-CRUD

Suche & RAG

📖 docs/retrieval-modes.md — eine aufgezählte Referenz für jeden Abrufmodus (Keyword · Dense · Hybrid · Graph · GraphRAG · proaktiv recall_when · temporal as_of): Mechanismus, wann zu verwenden, Aufruf und Beispiele.

Journal

Zustand

Lebenszyklus

Qualität

Keystones (Richtlinienregeln)

Vault & Federation

Metriken & Betrieb

Werkzeuge nach Aufgabe (Agenten-Spickzettel)

Keine Kategorieliste, sondern eine Aufgabenliste. Wählen Sie die Zeile für das, was der Agent zu tun versucht:

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

Live-Updates ohne Sitzungsneustart

perseus-vault serve erkennt, wenn seine eigene Binärdatei während der Sitzung auf der Festplatte ersetzt wird (der normale cargo build / Neuinstallations-Workflow) und weigert sich, Ergebnisse aus dem veralteten Prozess-Image auszuliefern – jedes Werkzeug antwortet mit einem lauten, expliziten Fehler, anstatt mit leeren Ergebnissen zu degradieren (#858, #1045). Zwei Wiederherstellungspfade, beide über dieselbe stdio-Verbindung (kein Client-Neustart):

• Explizit: perseus_vault_handoff_restart {"confirm": true} aufrufen – der Prozess wechselt hot zur neuen Binärdatei und die Sitzung läuft nahtlos weiter, wobei der MCP-Sitzungszustand (Initialisierung + Agentenidentität) erhalten bleibt.

• Automatisch (Opt-in): Starten Sie den Server mit PERSEUS_VAULT_AUTO_HANDOFF=1 und der Wechsel erfolgt transparent beim nächsten Werkzeugaufruf, den die neue Binärdatei direkt beantwortet.

Unter macOS/Linux ist der Wechsel ein echtes exec (gleiche PID, gleiche Pipes). Windows sperrt eine laufende ausführbare Datei, daher ist ein Austausch während der Sitzung dort nicht möglich; Aktualisierung über eine Sitzungsgrenze hinweg. Vollständiger Vertrag und der lokale Entwicklungs-Workflow: docs/specs/live-update-handoff.md.

Manuelle DB-Bearbeitungen. Die oben genannten Wartungsbefehle und der normale MCP-Schreibpfad halten den FTS5-Index automatisch synchron. Die direkte Bearbeitung der Tabelle entities mit sqlite3 (ein manuelles DELETE/UPDATE) umgeht diese Synchronisation und kann verwaiste Indexzeilen hinterlassen – „Geister“-Recall-Treffer für Inhalte, die bereits verschwunden sind. Führen Sie nach einer direkten SQL-Bearbeitung perseus-vault maintain --db <Pfad> (oder perseus-vault reindex) aus, um den FTS-Index abzugleichen.

Flags

Datenbankspeicherort

Der kanonische Datenbankpfad ist:

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

Übergeben Sie in Skripten, MCP-Host-Konfigurationen und Cron-/Erntejobs immer --db (oder setzen Sie $PERSEUS_VAULT_DB_PATH), damit jeder Aufruf auf dieselbe Datei abzielt. Wenn keines gesetzt ist, löst Perseus Vault den Standard in dieser Reihenfolge auf und verwendet das erste, das bereits existiert (damit Aktualisierer und ältere Einzelbenutzerinstallationen erkannt werden, anstatt stillschweigend leer zu starten):

1. ~/.perseus-vault/data/perseus-vault.db — kanonisch (aktueller Name)

2. ~/.perseus-vault/data/perseus-vault.db — vor der Umbenennung

3. ~/.perseus-vault/data/perseus-vault.db — vor der Umbenennung

4. ~/perseus-vault.db — veralteter Einzelbenutzer-Installationsort

Wenn keines existiert, wird ~/.perseus-vault/data/perseus-vault.db erstellt. Wenn mehr als eines davon existiert und Sie --db / $PERSEUS_VAULT_DB_PATH nicht übergeben haben, gibt Perseus Vault eine stderr-Warnung aus, die die gewählte Datei und die anderen ignorierten Dateien nennt, sodass ein mehrdeutiger Multi-Datenbank-Zustand sichtbar und nicht still ist. Die explizite Angabe von --db oder $PERSEUS_VAULT_DB_PATH gewinnt immer und unterdrückt die Warnung.

Ihr KI-Gedächtnis in Obsidian

Perseus Vault ist das Langzeitgedächtnis Ihres KI-Agenten – und es dient gleichzeitig als Ihr zweites Gehirn. Jede Entität, an die sich Ihr Agent erinnert, wird in eine einfache Markdown-Notiz mit YAML-Frontmatter exportiert, sodass das Gedächtnis Ihrer KI zu einer navigierbaren persönlichen Wissensdatenbank in den Tools wird, die Sie bereits verwenden: Obsidian, Logseq oder 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

Öffnen Sie den Vault in Obsidian und Sie erhalten einen Graphen des Wissens Ihres Agenten.

WikiLink-Backlinks. Wenn eine Entität auf eine andere verweist (über perseus_vault_link oder eine depends_on / implements / references-Beziehung), erhält die exportierte Notiz einen Abschnitt ## Links mit [[WikiLink]]-Backlinks, die in der Graphenansicht von Obsidian nativ aufgelöst werden:

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

{"content":"axum service"}

## Links

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

Links werden nach Entitäten-ID aufgelöst (Notizen werden als <id>.md geschrieben), sodass sie niemals brechen, und Obsidian zeigt den menschenlesbaren key als Link-Label an. Öffnen Sie die Graphenansicht und die Architektur, Entscheidungen und Erkenntnisse Ihres Agenten werden zu einer klickbaren Wissenslandkarte.

--watch fragt in einem Intervall den günstigen, deterministischen Zustands-Digest von Perseus Vault ab und exportiert nur neu, wenn sich der Speicher tatsächlich ändert. Es erfasst auf natürliche Weise jeden perseus_vault_remember-Schreibvorgang ohne Dateisystem-Überwachungsabhängigkeit und ohne Kopplung an den Server. Passen Sie das Intervall mit PERSEUS_VAULT_SYNC_INTERVAL_SECS an (Standard: 2s).

Andere PKM-Tools

Im Gegensatz zu reinen Cloud-„Second Brain“-Tools läuft Perseus Vault 100 % lokal, ist in Rust geschrieben, verschlüsselt im Ruhezustand mit AES-256-GCM und wendet Verfallsscoring an, damit veraltete Erinnerungen verblassen – Ihre Wissensdatenbank bleibt Ihre und bleibt aktuell.

Funktionen

Semantische Suche (standardmäßig aktiviert)

• Eingebettete, prozessinterne Embeddings — ein quantisiertes all-MiniLM-L6-v2-Modell (384-dim) ist in die Binärdatei kompiliert, sodass dichte/semantische Suche mit Null Konfiguration und Null Netzwerk funktioniert: kein Ollama, kein API-Schlüssel, kein Modell-Download. Dies ist der Standard-Build (bundled-embeddings-Feature).

• Automatisches Einbetten beim Schreiben (#271) — perseus_vault_remember bettet jede neue (oder inhaltlich geänderte) Entität synchron beim Schreiben ein, unter Verwendung des eingebetteten Modells. Das Einbetten einzelner Entitäten ist deterministisch und LRU-gecacht, daher günstig und ohne Hintergrundaufgaben. Fehler beim Einbetten sind nicht fatal (werden auf stderr protokolliert); der Schreibvorgang ist immer erfolgreich.

• Hybrid ist der Standard-Recall-Modus (#271) — perseus_vault_recall(query=...) ohne mode-Flag wählt automatisch hybrid (dicht + Stichwort, fusioniert über RRF), sofern Embeddings vorhanden sind, und fällt transparent auf die fts5-Stichwortsuche zurück, wenn keine vorhanden sind. Kein manueller perseus_vault_embed-Schritt, keine zu merkenden Flags.

• perseus_vault_semantic_search(query, limit) — ein Ein-Tool-Shortcut für reine dichte, bedeutungsbasierte Suche (kein Stichwort-Fallback), wenn Sie einfach "Dinge wie dieses finden" möchten.

• Optionaler alternativer Embedder — zur Verwendung von Ollama oder einem OpenAI-kompatiblen /v1/embeddings-Endpunkt anstelle des eingebetteten Modells setzen Sie --llm-endpoint (und ggf. --embedding-endpoint / --llm-api-key). Dies ist vollständig optional; standardmäßig wird das eingebettete Modell verwendet.

• Erstellen Sie eine schlanke Binärdatei ohne eingebettete Embeddings via cargo build --no-default-features — der Recall verwendet dann standardmäßig die Stichwortsuche, sofern kein entfernter Embedder konfiguriert ist.

Hybrid Search Interna

• FTS5-Stichwortsuche mit LIKE-Fallback und Porter-Stemming-Expansion

• Dichte Vektorsuche via Kosinus-Ähnlichkeit auf gespeicherten Embeddings

• Reciprocal Rank Fusion (RRF) — Kombination von Stichwort- und Vektorergebnissen

• Query-Expansion — automatische Stemming-Varianten für breiteren Recall

Gedächtnis-Lebenszyklus

Perseus Vault modelliert das Gedächtnis mittels drei biomimetischer Schichten, inspiriert von menschlichen Gedächtnispfaden:

• Welt (Kern): Langsam zerfallende, globale Fakten über die Umgebung.

• Episodisch (Puffer): Schnell zerfallende, sitzungsspezifische Interaktionshistorie.

• Semantisch (Arbeitsgedächtnis): Mittelstark zerfallendes, allgemeines Wissen und gelernte Konzepte.

Sie können mit diesen Schichten direkt über das Tool perseus_vault_recall_layer oder durch Angabe des layer-Parameters in perseus_vault_remember interagieren.

• Ebbinghaus-Vergessen — Erinnerungen verblassen auf natürliche Weise, es sei denn, sie werden abgerufen (Aktualisierung bei Zugriff)

• Schichten-Promotion — Puffer → Arbeitsgedächtnis → Kern basierend auf Zugriffshäufigkeit

• Automatische Archivierung — veraltete Entitäten werden archiviert; purge löscht endgültig + VACUUM

• Immer aktive Entitäten — identitätskritische Erinnerungen für die Sitzungseinspielung fixieren (hart gedeckelt unter Recall-First; recall_when-Auslöser bevorzugen)

• Prospektive Query-Hinweise (#919) — optionale 1–3 natürlichsprachliche Formulierungen pro Entität (hints bei perseus_vault_remember), die zusammen mit dem Body in FTS5 indiziert werden und Wortschatzlücken zwischen natürlichsprachlichen Abfragen und gespeicherten Formulierungen überbrücken. Standardmäßig deaktiviert (PERSEUS_VAULT_HINTS_ENABLED=1); abgelehnt, wenn deaktiviert. Siehe docs/specs/prospective-query-hints.md.

Recall-First-Kontextinjektion

Der Tresor ist die Abfrageschicht — er ruft die wenigen Fakten ab, die ein Durchlauf benötigt, anstatt dem Host einen festen Block zum Einfügen in jeden System-Prompt zu übergeben. perseus_vault_context und perseus-vault prepare sind standardmäßig Recall-First:

• Relevanz-Gating — übergeben Sie query (die aktuelle Aufgabe/Nachricht) und nur Entitäten, deren recall_when-Auslöser oder indizierter Inhalt dazu passen, werden injiziert. Keine Abfrage, keine thematische Injektion: Der Block ist ein kompakter Abrufzeiger, byte-stabil über nicht verwandte Tresor-Schreibvorgänge (präfixcache-freundlich).

• Pro-Modell-Recall-Budget — die Ausgabe wird auf ein Zeichenbudget begrenzt, das aus dem Host-Modell ermittelt wird: Standard-/schlankes Profil 1500 Zeichen; Profil mit großem Fenster ("opus") 6000 Zeichen; max_context_chars überschreibt beides.

• Gedeckelt immer aktiv — always_on: true funktioniert weiterhin für identitätskritische Fakten, aber der Recall-First-Satz ist hart gedeckelt (Top 5) und Überlauf gibt eine Warnung aus, die Sie zu recall_when-Auslösern führt.

• Legacy-Opt-in — der alte, bedingungslose Top-N-Dump ist weiterhin verfügbar mit mode: "always_inject" (--legacy-context für prepare), unbegrenzt, es sei denn, Sie übergeben ein Budget.

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 & Embeddings

• perseus_vault_ask — natürlichsprachliches Q&A über gespeicherte Erinnerungen via jedes LLM (Ollama, OpenAI, usw.)

• perseus_vault_embed — Erzeugen und Speichern dichter Vektoren via Ollama oder OpenAI-kompatiblen /v1/embeddings

• Unterstützt Einzelentitäts- und Batch-Kategorie-Embedding

Verschlüsselung

• AES-256-GCM transparente Verschlüsselung für Entitäts-body_json

• Standardmäßig aktiviert für Neuinstallationen — der Standardschlüssel wird automatisch unter ~/.perseus-vault/secret.key beim ersten Schreibvorgang generiert

• --encryption-key-Flag für explizite Schlüssel; perseus-vault keygen für benutzerdefinierte Schlüsselerzeugung

• Vorhandene Klartext-Datenbanken schlagen fehl mit einem init --rekey-Migrationspfad (oder explizit PERSEUS_VAULT_ALLOW_PLAINTEXT=1)

• FTS5-Index bleibt für die Suche im Klartext

Web-Dashboard

• Integrierter Axum-HTTP-Server (perseus-vault serve --web --port 8767)

• Dashboard mit dunklem Design, Suche, Entitätstabelle, vis.js-Graph, Zeitleiste

• Standardbindung: 127.0.0.1 (verwende --web-bind 0.0.0.0 zum Freigeben)

• Separate SQLite-Verbindung im WAL-Modus für gleichzeitige Lesevorgänge

Externe Konnektoren

• GitHub Issues-Konnektor — Aufnehmen von Issues/PRs pro Repository, ratenbegrenzungsbewusst

• Datei-Überwacher — Durchsuchen von Verzeichnissen nach .md/.txt/.json-Dateien mit Inhalts-Hash-Deduplizierung

• YAML-basierte Konnektorkonfiguration via --connectors-config

Multi-Transport

• stdio (Standard) — null Konfiguration, funktioniert mit jedem MCP-Host

• SSE — Server-Sent Events für HTTP-basierte MCP-Clients

• HTTP — REST-artiger MCP-Endpunkt

• Bearer-Token-Authentifizierung — für SSE/HTTP-Transporte

Perseus-Integration

Perseus Vault ist das Standard-Speicher-Backend für 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

Behörden- und Bundesbeschaffung

Perseus Vault ist von Grund auf für den Regierungseinsatz konzipiert.

Perseus Computing LLC ist ein US-amerikanisches Kleinunternehmen. SAM.gov-Registrierung in Bearbeitung. NAICS: 541715, 541511, 541512.

Datenschutzerklärung

Perseus Vault ist ein lokaler MCP-Server — er läuft vollständig auf Ihrem Rechner.

Datenerfassung

• Keine Datenerfassung. Perseus Vault sammelt, überträgt oder sendet keine Nutzerdaten, Nutzungsstatistiken oder Telemetrie.

• Alle Daten verbleiben in Ihrer lokalen SQLite-Datenbankdatei.

Datennutzung & Speicherung

• Alle Gedächtnisentitäten, Journaleinträge und Zustände werden lokal in einer SQLite-Datenbank unter dem von Ihnen via --db angegebenen Pfad gespeichert.

• Optionale AES-256-GCM-Verschlüsselung im Ruhezustand ist verfügbar — wenn aktviert, werden Entitätskörper vor dem Speichern verschlüsselt.

• Keine Daten werden mit Perseus Computing LLC oer irgendeine dritte Partei geteilt.

Weitergabe an Dritte

• Keine. Perseus Vault ist standrdmäßig vollständig luftspaltlsiert. Keine API-Aufrufe, keine Clod-Dienste, keine externen Netzwerkanfragen.

• Ds optionale Merkmal dicher Vektor-Embeddings verwendet ein lokl kompiliertes Modell — keine externe Embedding-API wird aufgerufen.

Datenaufbewahrung

• Si kontrollieren die Aufbewahrung mit vier unterschiedlichen Lebnenszyklus-Vorgängen (sieh docs/specs/data-boundaries-retention-lifecycle.md): Weiches Löschen (perseus_vault_forget, Inhalt wiederherstellbar), Ablauf (perseus_vault_expire, zeitbasierter status='expired' mit beibehaltenem Inhalt), Schwärzung (perseus_vault_redact, Inhat auf Hash reduziert, Metadaten beibehalten) und physische Löschung (perseus_vault_erase, Entfernung aus allen abgeleiteten Schichten mit dauerhafter Wiederaufnahme-Unterdrückungg). perseus_vault_purge gibt Speicherplatz von archivierten Zeilen frei.

• Keine automatische Off-Machine-Sicherung wird durchgeführt.

Kontakt

• E-Mail: privacy@perseus.observer

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

Release-Überprüfung

Release-Binärdateien werden aus getaggten Commits via GitHub Actions erstellt. Jedes Release liefert:

Release-Binärdatei überprüfen

# 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)

Reproduzierbar aus dem Quellcode bauen

# 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

Lizenz

MIT — siehe LICENSE.