knowl

Lokal zuerst. Typisiert. Und im Moment, in dem es nicht mehr stimmt, außer Dienst gestellt.

Schnellstart · Warum Ablösung · Was gespeichert wird · Funktionen · Agenteneinrichtung · Betrachter · Anforderungen · Vollständige Referenz →

Coding-Agenten beginnen jede Sitzung im leeren Zustand, daher schreiben Teams Dinge auf – und diese Notizen werden nur immer mehr. Sechs Monate später meldet der Speicher immer noch die Datenbank, von der du letzten Frühling migriert bist, weil ihm nie jemand mitgeteilt hat, dass diese Entscheidung vorbei ist.

Knowl ist ein dauerhafter sitzungsübergreifender Speicher für Claude Code, Cursor und Codex: ein repository-lokaler Speicher für typisierte Wissensatome — Entscheidungen, Einschränkungen, Architektur, Fakten, Ziele, Zustände und Fähigkeiten – gelesen und geschrieben über einen MCP-Speicherserver oder die knowl-CLI, bei der eine Ersetzung ihren Vorgänger zum Zeitpunkt des Schreibens außer Dienst stellt, anstatt daneben zu liegen.

Schnellstart

Erfordert Node.js 22 oder höher.

npm install -g @dat999zx/knowl
cd your-project
knowl init

knowl init erstellt .knowl/, installiert die Projekt-Guidance-Dateien, aktualisiert .gitignore und bietet MCP- und Lifecycle-Einrichtung für die erkannten Agenten an – Claude Code, Codex, Cursor, Gemini CLI, Claude Desktop. Es wärmt auch das lokale Einbettungsmodell auf, ist aber nie von diesem Download abhängig.

Zeichne etwas auf, das es wert ist, behalten zu werden:

knowl decide "Use SQLite" "Use SQLite for local project memory." \
  --reasoning "Keeps storage repository-local and simple to operate." \
  --alternatives PostgreSQL MongoDB \
  --tags database local-first

Lies es zurück, von der CLI oder von einem verbundenen Agenten:

knowl query "why sqlite"     # search project memory
knowl state                  # the active memory, as a hierarchy
knowl status                 # repository, memory, AI, and workspace status
knowl doctor                 # check setup, retrieval, and agent registration

Starte dann eine neue Agentensitzung, damit der Host die Guidance und MCP-Registrierung übernimmt. Die CLI und knowl_query lesen denselben Speicher unter denselben Governance-Regeln.

Related MCP server: Mnemoverse Memory

Die Idee: Speicher, der sich selbst außer Dienst stellt

Die meisten Speichersysteme sind append-only. Das Speichern von "wir sind zu SQLite gewechselt" lässt "wir verwenden PostgreSQL" aktiv und auffindbar, also erhält der Agent beides und wählt nach Rang aus. Knowl behandelt einen Schreibvorgang zum selben Thema als Korrektur: Der Vorgänger wird als superseded markiert, fällt aus der normalen Abfrage heraus und bleibt über knowl timeline abfragbar.

Dieses einzelne Verhalten macht den Großteil des Genauigkeitsunterschieds aus. Im MemoryAgentBench-Konfliktlösungskorpus – 455 Fakten, 100 Fragen, welche Tatsache aktuell ist, Top-5-Abfrage, kein LLM-Reader:

Gleicher Korpus, gleicher Ranker, gleicher Abfragepfad. Die einzige Variable ist, ob die veraltete Tatsache noch aktiv ist. Dies ist eine Abfrageebenen-Messung in Knowls eigenem Rahmenwerk: Es fragt, ob die aktuelle Tatsache zuerst zurückkommt, ohne Modell im Kreislauf.

Ende-zu-Ende verifiziert, im eigenen Rahmenwerk des Benchmarks

Weil eine selbst erzielte Zahl weniger wert ist als eine, die jemand anderes erzielt hat, wurde dieselbe Behauptung erneut innerhalb des MemoryAgentBench-Rahmenwerks ausgeführt, von dessen eigenem Code bewertet, mit einem LLM, das las, was Knowl zurückgab – der schwierigere, vollständige Ende-zu-Ende-Aufbau, im größten Kontext, den die Aufgabe bietet:

18.332 Fakten, 100 Fragen, Substring exakte Übereinstimmung. Jede Zeile verwendet gpt-4o-mini als Reader, Knowls eingeschlossen – das Papier gibt dies für alle RAG- und Speicher-Agenten an, also sind diese vergleichbar. Knowls Wert wurde hier gemessen; jeder andere Wert stammt aus dem MemoryAgentBench-Papier, Tabelle 2. Systeme, die das Papier bei dieser Aufgabe nicht bewertet, sind nicht aufgeführt.

Das Abschalten der Ablösung im selben Rahmenwerk senkt Knowl auf 73, und die Lücke bleibt über eine 40-fache Änderung der Korpustgröße bestehen:

Die beiden Abschnitte messen unterschiedliche Dinge und sind nicht miteinander vergleichbar: 98 % ist Abfrage-Top-1 bei 6K ohne Reader, 90 ist Ende-zu-Ende-Genauigkeit bei 262K mit einem. Nur der zweite ist mit den oben veröffentlichten Systemen vergleichbar. Siehe Benchmarks für das Protokoll, die eingecheckten Ergebnisse und was die Aufgabe nicht abdeckt – einschließlich Multi-Hop, wo Knowl 7 gegen eine Abfrageobergrenze von 14 Punkten erzielt.

Ablösung ist eine Korrektur, keine Löschung: Der Eintrag, seine Aussagen und seine Historie bleiben alle erhalten.

Kein Mock-up – dieselbe Sequenz gegen die veröffentlichte CLI, aufgezeichnet von demo.tape:

Was gespeichert wird

Jedes Atom hat genau eine von sieben Kategorien:

Neben dem Inhalt behält jedes Atom einen Status (active, deprecated, rejected, archived, superseded), ein Aktualitätsflag, Vertrauen, Tags, Quell-Commit, betroffene Pfade und optionale Nachweise, die auf Dateien, Commits, Tests, Befehle, URLs oder indizierte Codesymbole verweisen. Datei- und Symbolnachweise werden von selbst veraltet, wenn sich der Code bewegt, was bedeutet, dass ein Atom zugibt, dass es veraltet sein könnte, anstatt eine Version des Repositorys zu behaupten, die es nicht mehr gibt.

Was Knowl bewusst nicht speichert, sind deine Gespräche. Die Lifecycle-Erfassung zeichnet begrenzte Ereignisse und Zusammenfassungen auf – niemals Prompts, Transkripte, stdout oder Umgebungsvariablen. Die Roh-Transkriptsuche existiert als opt-in, standardmäßig ausgeschalteter Index über Dateien, die der Host bereits geschrieben hat.

→ Wissensmodell-Referenz

Einen Agenten verbinden

knowl serve legt den Speicher über stdio MCP offen; knowl init registriert ihn für Sie. Der Arbeitsablauf, den die installierte Anleitung von Agenten verlangt, ist kurz:

1. Fragen Sie den Speicher mit den Wörtern ab, die das Thema benennen, bevor Sie Repository-Dateien lesen.

2. Verwenden Sie einen aktiven Treffer direkt; inspizieren Sie Dateien nur bei einem Fehlschlag, Konflikt oder veraltetem Ergebnis.

3. Speichern Sie dauerhafte Erkenntnisse, festgelegte Ziele und wiederkehrende Diagnosen, während Sie vorgehen, und korrigieren Sie widersprüchliches Wissen, anstatt es zu duplizieren.

In der Praxis sieht das so aus – eine neue Sitzung, kein Kontext, nichts eingefügt:

You     why did we pick SQLite over Postgres?

Agent   → knowl_query "sqlite postgres database choice"
        ← decision · Use SQLite · active · fresh
          "Keeps storage repository-local and simple to operate."
          alternatives: PostgreSQL, MongoDB
          tags: database, local-first

        SQLite keeps the store repository-local and simple to operate.
        Postgres and MongoDB were both considered and rejected on that
        basis.

Der Agent antwortete, bevor er eine einzige Datei öffnete, und er kannte die Optionen, die Sie verworfen hatten – was der Code ihm nicht sagen kann, weil abgelehnte Alternativen keine Spur in einer Codebasis hinterlassen.

Wo Hooks verfügbar sind, übernehmen sie den Sitzungslebenszyklus: Bootstrapping, Kontext, Erfassung, Checkpoints und Abschluss geschehen, ohne dass der Agent aufgefordert wird. Wo sie nicht verfügbar sind, decken knowl task run, task start, task checkpoint und task finish dasselbe manuell ab.

knowl init schreibt die MCP-Registrierung für jeden erkannten Host. Um eine manuell zu verdrahten, ist der Eintrag überall gleich:

{
  "mcpServers": {
    "knowl": { "command": "knowl", "args": ["serve"] }
  }
}

Verwenden Sie unter Windows knowl.cmd als Befehl. Codex liest denselben Eintrag unter mcp_servers.

→ MCP-Werkzeuge und -Ressourcen · Lebenszyklus-Referenz

Wofür Knowl da ist

Knowl hat eine Aufgabe: die technische Wahrheit eines Repositorys für die daran arbeitenden Agenten genau zu halten. Nicht Benutzerpräferenzen, nicht Chatverlauf – die Entscheidungen, Einschränkungen und Architektur einer Codebasis, und welche davon heute noch gültig sind.

Drei Entscheidungen folgen daraus:

• Typisiert, nicht Freitext. Eine Entscheidung trägt die Begründung und die abgelehnten Alternativen. Eine Einschränkung ist eine Regel, die weiterhin gelten muss. Ein state-Atom wird erwartungsgemäß veralten. Der Abruf kann nach diesen Unterschieden bewerten; er kann nicht nach Absätzen in einer Notizdatei bewerten.

• Verwaltet, nicht nur anhängend. Status, Aktualität, Herkunft, Konfliktidentität und Ersetzung ermöglichen es dem Speicher, Ihnen mitzuteilen, dass etwas aufgehört hat, wahr zu sein. Das ist der ganze Unterschied zwischen Wissen und einem ständig wachsenden Haufen Notizen.

• Repository-lokal, kein Dienst. Die Datenbank sitzt neben dem Code, den sie beschreibt. Kein Konto, kein ausgehender Datenverkehr, kein Anbieter zwischen Ihnen und Ihrer eigenen Projekthistorie.

Knowl ist bewusst keine Personalisierungsschicht. Es hat keine Meinung über Ihre Benutzer und führt keine eigenen Transkripte.

Funktionen

Alles untenstehende funktioniert von der CLI und von jedem MCP-verbundenen Agenten aus, gegen dieselbe lokale Datenbank. Kein Konto, kein Server, kein API-Schlüssel. Jeder Punkt verlinkt in die vollständige Referenz für die Details – und für die Grenzen.

♻️ Wissen, das sich selbst korrigiert

Sieben typisierte Atomtypen, bei denen ein Schreiben auf dasselbe Thema seinen Vorgänger ersetzt, anstatt daneben zu stehen. Dieses eine Verhalten ist der 90-vs-73-Unterschied. Belege, die an eine Datei oder ein Symbol angehängt sind, werden von selbst veraltet, wenn der Code sich bewegt.

conflicts · timeline · query --as-of · pr --since · index-code

🎯 Abruf für Agenten optimiert

Vektorprimär mit einem begrenzten BM25-Fallback, neu bewertet nach Aktualität, Status und Konfidenz, sodass die aktuelle Antwort gewinnt, nicht nur die ähnliche. Das Einbettungsmodell ist lokal und optional – ohne es erhalten Sie immer noch einen Schlüsselwortabruf, und nichts verlässt die Maschine.

query · context --token-budget · config set-model · access

⏱️ Arbeit, die die Sitzung überlebt

Auf Claude Code, Codex und Cursor übernehmen Hooks Bootstrapping, Erfassung, Checkpoints und Abschluss, ohne dass der Agent aufgefordert wird. Ein sauberer Abschluss destilliert bis zu acht langlebige Kandidaten. Parken Sie einen Arbeitsstrom unter einem Schlüssel und nehmen Sie ihn in jeder Sitzung, von jedem Verzeichnis aus wieder auf.

task run · handoff · park · resume <key>

🔗 Arbeitsbereiche

Ihr API-Repo hat etwas gelernt, das das Frontend-Repo braucht. Verknüpfen Sie sie, und eine Abfrage verteilt sich, während jedes Repository seine eigene Datenbank und seine eigene Eigentümerschaftsgrenze behält. Öffnen Sie ein gemeinsames Peer-Atom vollständig nach ID, oder schließen Sie die Arbeit dieses Repos von hier aus ab, indem Sie es im Aufruf benennen. Wissen, das ein Repo bereits besitzt, wird nur geteilt, wenn Sie es promoten.

workspace init · workspace add · workspace promote --apply

📦 Wiederverwendbare Prozeduren

Packen Sie eine Prozedur mit ihren Skripten unter .knowl/skills/ und lesen Sie sie, bevor sie jemals ausgeführt wird. Fassen Sie mehrere Atome deterministisch zu einer Architekturzusammenfassung zusammen, ohne dass ein KI-Anbieter beteiligt ist.

skill list · skill read · skill run · synthesize

💾 Ihre Daten und wie Sie sie zurückbekommen

Prüfsummengeschützter JSONL-Export und -Import mit vier expliziten Richtlinien für den Fall, dass dasselbe Atom an zwei Orten geändert wurde. Die Wiederherstellung überprüft Schema, Größe, SHA-256 und SQLite-Integrität, bevor sie etwas anrührt, und erstellt zuerst einen Schnappschuss vor der Wiederherstellung.

export · import --on-divergence · snapshot create · gc · doctor

Die Befehle, die man am ersten Tag kennen sollte:

knowl query "auth design"              # search project memory
knowl state                            # the active memory, as a hierarchy
knowl conflicts                        # items that contradict each other
knowl timeline <item-id>               # every version an atom ever had
knowl context --token-budget 1500      # a fixed-size briefing for an agent
knowl pr --since origin/main           # knowledge your diff may invalidate
knowl doctor                           # setup, retrieval, and registration

• Sieben Atomtypen – oben aufgeführt. Struktur statt einer ständig wachsenden Notizdatei.

• Automatische Ersetzung – ein Schreiben auf dasselbe Thema ersetzt seinen Vorgänger. Dies ist der 90-vs-73-Unterschied oben.

• Konfliktidentität – markieren Sie ein Atom als exklusiv, und Knowl verweigert eine zweite aktive Antwort auf dieselbe Frage, anstatt beide stillschweigend zu halten. knowl conflicts

• Vollständige Historie – jede Version, die ein Atom jemals hatte, überlebt als unveränderliche Behauptung. knowl timeline <item-id>

• Zeitreise – fragen Sie, was das Projekt an einem vergangenen Datum angenommen hat: knowl query "auth design" --as-of 2026-01-01T00:00:00Z

• Belege – hängen Sie Dateien, Symbole, Commits, Tests, Befehle oder URLs an ein Atom an. Datei- und Symbolbelege werden von selbst veraltet, wenn der Code sich bewegt.

• Abweichungserkennung – knowl pr --since origin/main kennzeichnet Wissen, das Ihr Diff möglicherweise ungültig gemacht hat, bevor Sie es zusammenführen.

• Code-Intelligenz – inkrementeller Tree-sitter-Index über .ts / .tsx / .js / .jsx, sodass Belege auf symbol://-Locators verweisen können, nicht nur auf Zeilennummern. knowl index-code

• Geheimnissichere Schreibvorgänge – jeder Schreibvorgang wird auf erkannte Geheimnisse, sensitive Pfade und übermäßig großen Inhalt geprüft, bevor er landet. Langlebiger Speicher ist der letzte Ort, an dem eine Anmeldeinformation landen sollte.

→ Wissensmodell · Belege und Abweichung

• Vektorprimäre Bewertung mit einem begrenzten BM25-Fallback, neu bewertet nach Aktualität, Status, Konfidenz und Neuheit – sodass die aktuelle Antwort gewinnt, nicht nur die ähnliche. (Dies ist der Agent/MCP-Pfad; ein knowl query in einem einzelnen Repo von der CLI aus ist lexikalisch.)

• Läuft offline. Das Einbettungsmodell ist lokal und optional; ohne es erhalten Sie immer noch einen Schlüsselwortabruf. Der Abruf sendet Ihre Abfrage nirgendwohin.

• Fünf gebündelte Einbettungsvoreinstellungen, darunter eine mehrsprachige für über 200 Sprachen, plus custom für Ihr eigenes ONNX-Modell. knowl config set-model <model>

• Unterstützung für exakte Kennungen – Dateinamen, Element-IDs und symbol://-Locators treffen trotzdem, wenn die semantische Ähnlichkeit schwach ist.

• Token-budgetierte Kontextpakete – übergeben Sie einem Agenten ein festgelegtes Briefing, bei dem Einschränkungen zuerst angeheftet werden, sodass nicht verhandelbare Regeln nie abgeschnitten werden: knowl context --query "auth rollout" --token-budget 1500

• Nutzungsfeedback – Agenten berichten, ob ein Ergebnis geholfen hat, und knowl access zeigt, was stark genutzt wird, was veraltet ist und was ständig Korrekturen verursacht.

→ Abruf und Kontext

• Automatischer Lebenszyklus auf Claude Code, Codex und Cursor – Bootstrapping, Erfassung, Checkpoints und Abschluss geschehen über Hooks, ohne dass der Agent aufgefordert wird.

• Arbeitsschleifen für alles andere – knowl task start, checkpoint, finish, oder wickeln Sie einen einzelnen Befehl mit knowl task run "Run tests" -- npm test ein.

• Promotion am Sitzungsende – ein sauberer Abschluss destilliert bis zu acht langlebige Kandidaten aus der Sitzung, und ein Befehl, der dreimal erfolgreich war, wird zu einem skill-Atom, das ihn beschreibt.

• Übergabe – hinterlassen Sie einen Stab für die nächste Sitzung in diesem Repo. Er wird einmal ausgeliefert und dann archiviert.

• Fortsetzungsschlüssel – parken Sie einen Arbeitsstrom unter einem kurzen Schlüssel, den Sie behalten, und nehmen Sie ihn in jeder Sitzung, von jedem Verzeichnis aus, beliebig oft später wieder auf. knowl resume <key>

• Optionale Transkriptsuche – standardmäßig aus, und aus bedeutet, dass nichts auf der Festplatte existiert. Schalten Sie sie ein, und der Text vergangener Sitzungen wird durchsuchbar, sodass ein Speicherfehlschlag zu einer langsameren Suche herabgestuft wird, anstatt zu Amnesie.

→ Aufgaben, Sitzungen und Lebenszyklus

Ihr API-Repo hat etwas gelernt, das das Frontend-Repo braucht. Verknüpfen Sie sie, und eine Abfrage verteilt sich – während jedes Repository seine eigene Datenbank und seine eigene Eigentümerschaftsgrenze behält.

knowl workspace init product      # create the workspace
knowl workspace add product       # run inside each repo that joins it
                                  # ...or --default-visibility repo to keep its writes private

knowl workspace promote                               # pick what to share from a list
knowl workspace promote --category decision --apply   # or name it outright

Durch den Beitritt zu einem Arbeitsbereich wird das Wissen geteilt, das das Repo von da an schreibt, und teilt dies mit, wenn es das tut; übergeben Sie --default-visibility repo, um abzulehnen. Was das Repo bereits weiß, wird nur geteilt, wenn Sie es promoten. Peer-Ergebnisse sind mit dem Repo gekennzeichnet, das sie besitzt, und ein gemeinsames kann vollständig nach ID geöffnet werden – ohne seine affectedPaths oder Belege, die gegen einen Checkout aufgelöst werden, in dem Sie nicht stehen. Ein Peer, der fehlt oder nicht lesbar ist, wird übersprungen und offengelegt, niemals ein Grund für das Scheitern Ihrer lokalen Suche.

Das Schreiben in ein Geschwister ist beabsichtigt und nicht zufällig. Ein Agent benennt das Repo im Aufruf, und dieser eine Aufruf läuft als dieses Repo – sein Speicher, seine Konfiguration, seine Eigentumsregeln, als sein eigenes gekennzeichnet – genau wie sich das cd-ing dorthin für die CLI immer verhalten hat. Nichts benennen, und eine fremde ID wird wie zuvor abgelehnt. So oder so bleibt das private Wissen eines Repos privat, bis es promotet wird.

→ Arbeitsbereiche

• Dateigestützte Fähigkeiten – Packen Sie eine Prozedur mit ihren Skripten unter .knowl/skills/ und prüfen Sie sie, bevor sie jemals ausgeführt wird. knowl skill list · read · run

• Deterministische Synthese – Fassen Sie mehrere Atome zu einer Architekturübersicht zusammen, ohne dass ein KI-Anbieter beteiligt ist: knowl synthesize --scope storage

→ Fähigkeiten und Synthese

• Portabler Export/Import – Prüfsummen-basiertes JSONL mit vier expliziten Divergenzstrategien für den Fall, dass dasselbe Atom an zwei Stellen geändert wurde. knowl export · knowl import --on-divergence newer

• Verifizierte Snapshots – knowl snapshot create schreibt ein Prüfsummen-Manifest; die Wiederherstellung überprüft Schema-Version, Größe, SHA-256 und SQLite-Integrität, bevor etwas berührt wird, und erstellt zuerst einen Vor-Wiederherstellungs-Snapshot.

• Garbage Collection, die standardmäßig eine Vorschau anzeigt und kürzlich verwendete Daten schützt. knowl gc

• knowl doctor – Ein Befehl, der Setup, Konfiguration, Integrität, Schema, Abruf, Vektorabdeckung, Agentenregistrierung und Workspace-Integrität prüft.

• Optionaler KI-Einsatz – Konfigurieren Sie einen Anbieter für knowl ask und die Rohtext-Erfassung. Jede oben genannte Funktion funktioniert auch ohne.

→ Portabilität und Wartung · Optionaler KI-Einsatz

Anschauen: der lokale Viewer

knowl view startet einen schreibgeschützten Inspektor auf 127.0.0.1 mit einem neuen Zugriffstoken pro Start – die Kenntnis des Ports allein reicht nicht aus, um etwas zu lesen.

knowl view

Suchen, nach Kategorie filtern, veraltete Ringe erkennen, eine Nachbarschaft fokussieren und ein Atom öffnen, um seine Belege und seinen Zeitverlauf zu lesen. Der Graph verknüpft Atome durch gemeinsame Tags und kategoriebasierte Kanten – ein Navigationshilfsmittel, kein Kausal- oder Beleg-Graph. Er zeigt den vollständigen lokalen Inhalt über alle Status hinweg, daher ist die Loopback-Bindung die Datenschutzgrenze: Setzen Sie ihn nicht hinter einen öffentlichen Proxy oder Tunnel.

→ Lokaler Viewer

Alles andere

27 MCP-Tools (plus 3 bei aktivierter Transkriptsuche, 1 bei Verbindung mit einem Cloud-Workspace, 1 bei Verknüpfung mit einem lokalen Workspace und 1 bei aktivierter Änderungsauswirkungsanalyse)

und zwei Ressourcen-URIs · die vollständige CLI, von knowl status bis knowl audit · ein schreibgeschütztes Integritätsaudit · Abruf-Evaluierung, die Sie selbst mit den eingecheckten Governance- und 500-Fall-Regressions-Suiten mit knowl eval ausführen können.

→ CLI-Referenz · MCP-Tools · Benchmarks

Anforderungen und lokale Daten

Node.js 22 oder höher. Alles, was Knowl für ein Projekt schreibt, befindet sich unter .knowl/, das knowl init zu .gitignore hinzufügt:

Workspace-Manifeste befinden sich außerhalb der Mitglieds-Repositories, da ihre Checkout-Pfade maschinenlokal sind. Exporte und Snapshots werden nur geschrieben, wenn Sie danach fragen.

Dokumentation

Alles oben ist die Zusammenfassung. Die vollständige Referenz ist ein Dokument, das jedes Subsystem im Detail abdeckt – einschließlich der Teile, die bewusst eingeschränkt sind, was normalerweise das ist, was Sie tatsächlich wissen müssen.

Mitwirken

Siehe CONTRIBUTING.md für das Setup, die vor einem Pull-Request auszuführenden Prüfungen und die Konventionen, die dieser Codebase folgt. Mitwirkende werden gebeten, einmalig bei ihrem ersten Pull-Request der Contributor License Agreement zuzustimmen.

Lizenz

Knowl ist unter der Apache License 2.0 lizenziert. Apache-2.0 gewährt keine Markenrechte.