Memex

Sammle verstreute Codex-Gespräche, destilliere dauerhaftes Wissen, verbinde es, indexiere es und bringe die richtige Erinnerung zurück, wenn es darauf ankommt.

Memex ist ein lokales, persönliches Wissenssystem für Codex. Es verwandelt lokale Rollout-Sitzungen in ein durchsuchbares Gesprächsarchiv, dauerhafte Fakten, einen ontologiegestützten Wissensgraphen und begrenzten Kontext, den Codex in späterer Arbeit wiederverwenden kann.

한국어 README · Dokumentation · Installation und Betrieb · Architektur · Schema

Memex ist ein unabhängiges, Codex-natives Projekt, das aus dem MIT-lizenzierten jung-wan-kim/memory-bank abgeleitet ist, das wiederum von obra/episodic-memory abstammt. Es bewahrt die Fähigkeiten des Wissenssystems, nicht den Kompatibilitätscode für Claude Code. Siehe Herkunft und Migration.

Warum 0.1.0?

0.1.0 ist die richtige erste öffentliche Veröffentlichung. Der Funktionsumfang ist substanziell und getestet, aber das Repository ist neu unabhängig und seine Codex-Marketplace-, Host-Adapter- und Installationsverträge können sich vor einer stabilen 1.0.0 noch ändern. Version 1.0.0 bedeutet, dass diese öffentlichen Verträge absichtlich stabil sind, nicht nur, dass viele Funktionen existieren.

Related MCP server: codex-memory-mcp

Funktionen

• Semantische, FTS5/BM25- und hybride Suche über den Verlauf von Codex-Gesprächen

• Deterministische Analyse des gesamten Verlaufs ohne LLM-Aufruf

• Inkrementelle Faktenextraktion, Konfidenzschwellen, Konsolidierung, Revisionen und Herkunft

• Domänen-/Kategorie-Ontologie und typisierte Wissensgraphen-Beziehungen

• Projekt-, globale und explizit angeforderte bereichsübergreifende Projektisolierung

• 1–3-Hop-Graphtraversierung und projektübergreifende Erkenntnisse

• Begrenzte RAG-Kontextinjektion mit Relevanz- und Sitzungs-Deduplizierung

• Transparente begrenzte Lesezugriffe für komprimierte .jsonl.zst-Archive

• Neun MCP-Tools für Gespräche, Fakten, Ontologie, Graph und Herkunft

• Drei Codex-Skills für Abruf, Verlaufsanalyse und Dashboard-Workflows

• Loopback-only-Web-UI mit Fakten, Pipeline-Gesundheit und einer 3D-Wissensgalaxie

• Codex-native SessionStart-, UserPromptSubmit- und SessionEnd-Hooks

Architektur auf einen Blick

flowchart LR
    R[Codex rollout JSONL] --> S[Sync and parser]
    S --> A[Immutable local archive]
    S --> C[(Conversation index)]
    C --> X[Incremental fact extraction]
    X --> F[(Facts and revisions)]
    F --> O[(Ontology and typed relations)]
    C --> Q[Hybrid retrieval]
    F --> Q
    O --> Q
    Q --> M[MCP tools and skills]
    Q --> H[Prompt context hook]
    C --> UI[Loopback Web UI]
    F --> UI
    O --> UI

Quell-Rollouts sind schreibgeschützt. Archive, SQLite/FTS/Vector-Indizes, Fakten und Graphendaten sind abgeleiteter lokaler Zustand. Modellgestützte Arbeit läuft über eine isolierte, ephemere lokale codex exec-Instanz; es gibt keinen Claude-Fallback oder einen separaten API-Key-Anbieter.

Für die detaillierten Mechanismen siehe:

• Systemarchitektur

• Gesprächslebenszyklus

• Faktenlebenszyklus

• Wissensgraph

• Abruf und Kontextinjektion

• MCP und Skills

• Web-UI und 3D-Visualisierung

Anforderungen

• Node.js 22.15 oder neuer

• Eine authentifizierte Codex-CLI

• macOS oder Linux für den aktuellen Hook und die Unix-Socket-Laufzeit

Das Plugin verwendet den gebündelten npx-Launcher von Node, um die neueste Laufzeit von BongSuCHOI/memex#main in den isolierten Cache von npm aufzulösen. Es klont oder baut nicht in Ihrem Projekt, installiert kein globales Paket und schreibt keine Abhängigkeiten in den Codex-Plugin-Cache.

Empfohlene Installation

Installieren Sie direkt aus dem öffentlichen Repository:

codex plugin marketplace add BongSuCHOI/memex
codex plugin add memex@memex

Das ist die vollständige Benutzerinstallation. Sie installiert das Plugin-Manifest, drei Skills, die MCP-Deklaration, Lebenszyklus-Hooks, den CLI-Launcher und den UI-Launcher. Der erste Laufzeitaufruf kann länger dauern, während npx seinen Cache mit nativen SQLite-, Vector- und Embedding-Abhängigkeiten füllt.

Bestehender manueller Marketplace-Ablauf

Das externe Marketplace-Layout bleibt für Entwicklung und Air-Gapped-/lokale Tests unterstützt:

memex-local-marketplace/
├── .agents/plugins/marketplace.json
└── plugins/memex -> /absolute/path/to/memex

Weisen Sie seinen Eintrag auf ./plugins/memex, registrieren Sie ihn mit codex plugin marketplace add /absolute/path/memex-local-marketplace, installieren Sie memex@<marketplace-name>. Der Quell-Installer bleibt für die lokale Entwicklungsvalidierung verfügbar. Das vollständige JSON- und Rollback-Verhalten bleibt in der Betriebsanleitung.

Erstmalige Einrichtung

Nach der Installation starten Sie Codex neu, damit der neu installierte MCP-Server, die Skills und die plugin-verwalteten Hooks in einer frischen Sitzung geladen werden.

Für lesbare Terminalbefehle definieren Sie diese sitzungslokale Shell-Funktion. Sie zielt immer auf die neueste main-Laufzeit und installiert nicht global:

memex() { npx --yes --package=github:BongSuCHOI/memex#main memex "$@"; }

Führen Sie dann die einmalige Korpus-Einrichtung durch:

memex setup
memex sync
memex backfill extract --foreground
memex backfill ontology --foreground
memex backfill embeddings --foreground
memex status

memex setup prüft das effektive Codex-memories-Feature. Wenn der integrierte Speicher aktiviert ist, erklärt Memex das Risiko von doppeltem/konfliktbehaftetem Speicher und empfiehlt, ihn zu deaktivieren. Interaktive Terminals fragen nach Bestätigung; Automatisierung und nicht-interaktive Shells ändern die Einstellung nie ohne das explizite memex setup --disable-codex-memory-Freigabeflag. Die Änderung verwendet den eigenen codex features disable memories-Befehl von Codex und wird danach verifiziert.

Was jede Stufe bewirkt:

1. sync liest vorhandene $CODEX_HOME/sessions, archiviert neue Rollouts und erstellt Gesprächssuchindizes.

2. backfill extract destilliert dauerhafte Fakten aus bereits indizierten Austauschen.

3. backfill ontology klassifiziert Fakten und erstellt die Graphstruktur.

4. backfill embeddings füllt fehlende semantische Vektoren.

5. status meldet die Bereitschaft von Gesprächen, Fakten und Graph getrennt.

Große Verläufe und lokale modellgestützte Extraktion können mehrere Minuten oder länger dauern. Führen Sie die Befehle im Vordergrund aus, um einen eindeutigen Abschluss beim ersten Mal zu gewährleisten. Wenn Sie --background wählen, bedeutet „gestartet“ nicht „fertig“; überprüfen Sie weiterhin memex status, bis die ausstehenden Zähler den erwarteten Zustand erreichen.

Die Marketplace-Installation ändert vor diesem Onboarding-Schritt keine Quell-Rollouts oder abgeleiteten Daten. sync ist idempotent und kann sicher wiederholt werden.

Tägliche Nutzung

memex sync
memex search "why did we choose SQLite?"
memex search --both "authentication migration"
memex stats
memex analyze --top 30 --out ~/memex-report.md
memex status

MCP-Tools und Skills

Das Plugin stellt bereit:

search, read, search_facts, search_ontology, ask_avatar,
trace_fact, explore_graph, cross_project_insights, graph_stats

Projektsensitive Tools erfordern einen kanonischen absoluten Projektpfad oder einen expliziten global/all-Bereich. Der MCP-Prozess errät den Bereich nie aus seinem eigenen Arbeitsverzeichnis. Siehe MCP und Skills für Schemata und Beispiele.

Lokale Web-UI

npx --yes --package=github:BongSuCHOI/memex#main memex-ui
# http://localhost:3847

Routen:

• / — Gespräche, Projekte, Suche und Austausche

• /facts — Fakten, Revisionen, Herkunft und geschützte Mutationen

• /graph — begrenzter Live-3D-Wissensgraph

• /pipeline — Bereitschaft und Rückstandsgesundheit

Der Server bindet nur an Loopback. Siehe Visualisierung.

Aktualisierungen

Vorschau anzeigen, dann den Git-Marketplace-Snapshot aktualisieren und das Plugin neu installieren:

memex update --dry-run
memex update

Der Laufzeit-Launcher folgt bereits der neuesten main; memex update aktualisiert auch den Marketplace-Snapshot, sodass aktualisierte Skills, Hooks und MCP-Metadaten zusammen installiert werden. Starten Sie Codex danach neu. Dauerhafte Memex-Daten bleiben erhalten.

Recall-Herkunft und Sicherheit bei Selbstaufnahme

Memex zeichnet Hook-Recalls als dauerhafte, pro Ereignis memex_recall-Belege auf, die nach Sitzung und Hash der menschlichen Eingabe verschlüsselt sind. Memex-MCP-Abrufergebnisse werden auf dieselbe Weise klassifiziert. Die Herkunft ist auf Beweisebene, nicht auf Umdrehungsebene: menschliche Behauptungen und auf der Whitelist stehende lokale Repository-, Git-Verlaufs- und Testausführungsergebnisse bleiben auch neben einem Recall lernbar; Memex-Ergebnisse, externe/unbekannte Tool-Ausgaben und assistentengenerierte Synthesen nicht. Der vollständige Austausch bleibt durchsuchbar. Dies verhindert die Verstärkung „Recall → Agent-Echo → neuer Fakt → Recall“, während die evidenzgestützte Faktenentwicklung erhalten bleibt.

Deinstallation

Plugin-verwaltete Hooks verschwinden, wenn das Plugin entfernt wird. Wenn eine ältere/manuelle Installation setup-hooks verwendet hat, entfernen Sie nur diese fingerabdruckbasierten Einträge, bevor Sie das Plugin löschen:

npx --yes --package=github:BongSuCHOI/memex#main memex remove-hooks --dry-run
npx --yes --package=github:BongSuCHOI/memex#main memex remove-hooks
codex plugin remove memex@memex --json
codex plugin marketplace remove memex --json

Die Deinstallation bewahrt sowohl $CODEX_HOME/sessions als auch die abgeleiteten Daten von Memex. Überprüfen Sie den genauen Datenpfad, bevor Sie ihn manuell löschen. Siehe die Betriebsanleitung.

Daten und Datenschutz

Standardmäßig bleiben abgeleitete Daten unter ~/.config/memory-bank für die Kompatibilität mit dauerhaften Daten. Auflösungsreihenfolge:

1. MEMORY_BANK_HOME

2. MEMORY_BANK_CONFIG_DIR

3. $XDG_CONFIG_HOME/memory-bank

4. ~/.config/memory-bank

Die Benennung ist historische Speicherkompatibilität, kein Claude-Laufzeitadapter. Siehe Schema und Sicherheitsgrenzen.

Verifizierung

npm run typecheck
npm run build
npm test
npm run test:marketplace
npm run test:package
node --test test/codex-slice.test.mjs
node --test test/*slice.test.mjs
node scripts/validate-plugin.mjs

Codex CLI 0.149.1 stellt codex plugin validate nicht bereit; das Repository dokumentiert diese Versionsgrenze und führt stattdessen einen isolierten Ersatz für installierte Artefakte aus. Aktuelle Belege und verbleibende Grenzen sind in Verifizierung dokumentiert.

Mitwirken

Klonen und bauen Sie nur für Entwicklung oder Beiträge:

git clone https://github.com/BongSuCHOI/memex.git
cd memex
npm ci
npm run build
npm test

Lesen Sie AGENTS.md für Produktinvarianten, Eigentumsgrenzen und erforderliche Prüfungen. Wenn sich das Verhalten ändert, aktualisieren Sie im selben Änderungssatz das Eigentümerdokument, das in der Dokumentationskarte identifiziert ist.

Lizenz

MIT. Upstream-Zuschreibungen und Hinweise Dritter finden Sie in docs/LINEAGE.md und THIRD_PARTY_NOTICES.md.