agent-knowledge

Sitzungsübergreifender Speicher und Abruf für KI-Codierungsassistenten -- funktioniert sofort mit Claude Code, Cursor, OpenCode, Cline, Continue.dev und Aider. Git-synchronisierte Wissensdatenbank, hybride semantische+TF-IDF-Suche, automatische Destillation mit Schwärzung von Geheimnissen.

Benchmark: R@5 = 97.2% (sparse) / 98.8% (hybrid) auf longmemeval_s und 86.0% (sparse) / 88.4% (hybrid) auf dem schwierigeren longmemeval_m-Split — das öffentliche akademische Benchmark LongMemEval (Wu et al. 2024, ICLR 2025), volle 500 Fragen pro Split, kein LLM, kein API-Schlüssel, läuft vollständig offline. +8.6pp bis +13.2pp R@5 gegenüber der offiziellen flat-bm25-Basislinie des Papers in einer direkten Reproduktion. Vollständige Tabelle nach Kategorien, Reproduktionsanweisungen und Details zum Paper-Vergleich finden Sie in bench/README.md.

Warum

KI-Codierungssitzungen sind vergänglich. Wenn eine Sitzung endet, ist alles, was sie gelernt hat – Architekturentscheidungen, Debugging-Einblicke, Projektkontext – verloren. Die nächste Sitzung beginnt von Null.

agent-knowledge löst dies mit zwei komplementären Systemen:

1. Wissensdatenbank – ein git-synchronisierter Markdown-Speicher mit strukturierten Einträgen (Entscheidungen, Arbeitsabläufe, Projektkontext), der über Sitzungen und Maschinen hinweg bestehen bleibt.

2. Sitzungssuche – TF-IDF-bewertete Volltextsuche über Sitzungstranskripte aller Ihrer Codierungswerkzeuge, sodass Agenten sich daran erinnern können, was zuvor passiert ist – unabhängig davon, welches Werkzeug verwendet wurde.

Related MCP server: Doclea MCP

Unterstützte Werkzeuge

Sitzungen aller gängigen KI-Codierungsassistenten werden automatisch erkannt – wenn ein Werkzeug installiert ist, erscheinen seine Sitzungen automatisch.

Keine Konfiguration erforderlich. Zusätzliche Sitzungswurzeln können über die Umgebungsvariable AGENT_KNOWLEDGE_EXTRA_SESSION_ROOTS hinzugefügt werden (durch Kommas getrennte Pfade).

Funktionen

• Host-unabhängige Sitzungssuche -- einheitliche Suche über alle gängigen KI-Codierungsassistenten (Claude Code, Cursor, Codex CLI, Aider, Continue.dev, Cline, OpenCode). Kein Hostname ist in der Konfiguration fest verdrahtet – die Adapter-Registry prüft beim Start installierte Host-Wurzeln.

• Hybride Suche -- semantische Vektorähnlichkeit kombiniert mit TF-IDF-Keyword-Ranking

• Git-synchronisierte Wissensdatenbank -- Markdown-Speicher mit YAML-Frontmatter, automatisches Commit und Push bei Schreibvorgängen

• Automatische Veraltungserkennung -- knowledge_analyze(action: "stale_by_code_activity") kreuzreferenziert Dateipfade, die in jedem Eintragstext erwähnt werden, mit filesModified in aktuellen Sitzungszusammenfassungen. Gepaart mit einer Präzisionsschicht für Symbolpräsenz: Bezeichner, die der Eintrag zitiert (Inline-Backticks + Codeblöcke), werden in der berührten Datei überprüft; wenn sie weiterhin existieren, wird die Konfidenz um ×0,3 herabgestuft. Einträge mit evergreen: true sind ausgenommen.

• Verfolgung von Suchlücken -- knowledge_analyze(action: "search_gaps") zeigt Null-Ergebnis-Abfragen der letzten since_days, gruppiert nach Token-Jaccard-Ähnlichkeit. Das klarste Signal für „Welche Einträge sollte ich als Nächstes schreiben?".

• Kontextpacker mit Abschnittspriorität -- knowledge(action: "wakeup") erstellt ein mehrteiliges Bündel (identity → active_tasks → recent_decisions → known_gotchas → last_session_summary → top_weighted → semantic_fallback) innerhalb eines Token-Budgets (Standard 800, überschreibbar über token_budget oder AGENT_KNOWLEDGE_WAKEUP_BUDGET). Nicht genutztes Abschnittsbudget wird auf spätere Abschnitte umverteilt.

• Bewerteter und abgesicherter Promoter -- Sitzungseinblicke werden über einen gewichteten Bewerter mit 6 Signalen und drei unabhängigen Toren (minScore, minRecallCount, minUniqueQueries) gefördert. Läuft automatisch im Hintergrund, auf Anfrage über knowledge_admin(action: "promote") oder offline testbar über npm run bench:promote. Gibt bei jedem Lauf ein prüfbares .dreams/YYYY-MM-DD.md-Tagebuch aus.

• Plugbares Adaptersystem -- Unterstützung für neue Werkzeuge durch Implementierung der SessionAdapter-Schnittstelle

• Embeddings -- lokale (Hugging Face), OpenAI, Claude/Voyage oder Gemini-Anbieter

• Fuzzy-Matching -- tolerante Suche bei Tippfehlern mittels Levenshtein-Distanz

• 6 Suchbereiche -- Fehler, Pläne, Konfigurationen, Werkzeuge, Dateien, Entscheidungen

• 6 MCP-Werkzeuge -- konsolidierte aktionsbasierte Schnittstelle (knowledge, knowledge_search, knowledge_session, knowledge_graph, knowledge_analyze, knowledge_admin)

• Evergreen-Einträge -- evergreen: true im Frontmatter befreit einen Eintrag vom Verfall im Ranking UND macht ihn unter Promotion nur anhängbar. Das Dashboard zeigt auf diesen Karten ein Pinn-Nadel-Abzeichen.

• Autorenzuordnung -- optionales author: <string>-Frontmatter erscheint als dezenter Chip auf jeder Karte.

• Code-Graph-Auflösung -- calls, imports, inherits-Kantentypen für Codestruktur; gerichtete BFS-Traversierung (outbound/inbound/both); bulk_link für effiziente Erfassung; unlink_by_origin zum Löschen veralteter Code-Kanten vor erneuter Erfassung; code:-präfixierte Knoten-IDs unterscheiden Code von Wissen

• Temporaler Wissensgraph -- Kanten unterstützen valid_from / valid_to-Gültigkeitsfenster; as_of-Abfragen liefern Punkt-in-der-Zeit-Schnappschüsse; invalidate-Aktion markiert Fakten als beendet, ohne sie zu löschen

• Hybride Bewertungsverstärkungen -- Verstärkungen für Eigennamen und zeitliche Nähe zusätzlich zur TF-IDF + semantischen Mischung, begrenzt auf +66,7%, Kurzschluss, wenn keine Signale vorhanden sind

• Kategorie als Verstärkung (nicht Filter) -- Opt-in zu category_mode: "boost", sodass eine falsche Kategorievermutung die richtige Antwort herabstuft, anstatt sie zu verwerfen

• Wörtliche Sitzungsindizierung -- Nachrichten-Chunks (≥30 Zeichen) werden in den Vektorspeicher eingebettet, sodass rohe Konversation abrufbar ist; umschaltbar mit AGENT_KNOWLEDGE_INDEX_VERBATIM=false

• Konfigurierbare Git-URL -- knowledge_admin(action: "config") für Laufzeit-Setup, gespeichert am XDG/AppData-Speicherort

• Maschinenübergreifende Persistenz -- Wissen wird über Git synchronisiert, Sitzungen werden aus dem lokalen Speicher jedes Werkzeugs gelesen

• Echtzeit-Dashboard -- durchsuchen, suchen und verwalten unter localhost:3423

• Schwärzung von Geheimnissen -- API-Schlüssel, Tokens, Passwörter, private Schlüssel werden vor dem Git-Push automatisch geschwärzt

• Wissensgraph -- Beziehungskanten zwischen Einträgen (related_to, supersedes, depends_on, contradicts, specializes, part_of, alternative_to, builds_on) mit BFS-Traversierung

• Konfidenz-/Verfallbewertung -- Einträge werden nach Zugriffshäufigkeit und Aktualität bewertet; automatische Beförderung von Kandidat zu etabliert zu bewährt

• Speicherkonsolidierung -- TF-IDF-Duplikaterkennung beim Schreiben (warnt vor ähnlichen Einträgen) plus knowledge_analyze(action: "consolidate") für Stapel-Dedup-Scan

• Reflexionszyklus -- knowledge_analyze(action: "reflect") zeigt unverbundene Einträge und generiert strukturierte Aufforderungen für den Agenten, neue Graphverbindungen zu identifizieren

• Automatische Verlinkung beim Schreiben -- neue Einträge werden automatisch mit den 3 ähnlichsten vorhandenen Einträgen verlinkt, wenn die Kosinus-Ähnlichkeit > 0,7 ist

• Konfidenz-Metadaten — Einträge mit extracted (benutzergeschrieben) oder inferred (automatisch destilliert, 0,85× Suchrang-Multiplikator) gekennzeichnet; das Feld confidence_score trägt die Modellsicherheit 0-1

• Wissensanalyse — knowledge_analyze-Aktionen god_nodes (am stärksten verbundene Einträge), bridges (kategorieübergreifende Verbinder), gaps (isolierte Einträge)

• Wissenszusammenfassung — knowledge_analyze(action: "brief") gibt eine gecachte Zusammenfassung von ~200 Token zurück (Kernkonzepte, aktive Projekte, aktuelle Entscheidungen, veraltete und Lückenanzahl) für die Orientierung zu Sitzungsbeginn

• Kantenherkunft — Graphkanten verfolgen origin (manuell, Auto-Link, Destillat, Reflexion), sodass die Analyse Benutzerurteil von automatisierten Heuristiken unterscheiden kann

• Deterministische Vorextraktion bei der Destillation — Sitzungszusammenfassungen enthalten jetzt Git-Commits, Fehlermuster, aufgerufene URLs und geänderte Pakete, die per Regex aus Bash-/Werkzeugausgabe extrahiert werden (keine LLM-Kosten)

• Frische-Metadaten bei jedem Suchergebnis — jedes Wissensergebnis trägt freshness: { body_age_days, last_accessed, access_count, verified_at, verification_age_days, evergreen }. Der Agent liest das Vertrauenssignal und entscheidet; wir erlegen keine Richtlinien-Herabstufung auf.

• Kategoriespezifische Verfallsfenster — der Filter „Unused" und das Bytype-Diagramm berücksichtigen kategoriespezifische Schwellenwerte (Projekte 180d, Personen 365d, Entscheidungen 90d, Arbeitsabläufe 60d, Notizen 30d), sodass identitätsgeprägte Inhalte nicht nur deshalb veraltet aussehen, weil sie nicht wöchentlich erneut gelesen werden.

• Lebenszyklus-Hooks — SessionStart Auto-Wakeup + Erfassungs-Frischeprüfung, UserPromptSubmit gezielte Injektion beim ersten Prompt, PreCompact Speicher-Leerungs-Hinweis + Destillat, SessionEnd Destillat. Insgesamt sechs Hook-Skripte, alle fail-open, jedes über eine AGENT_KNOWLEDGE_*-Umgebungsvariable umschaltbar. Siehe docs/HOOKS.md.

• Ersetzt Host-Auto-Speicher — auf Hosts mit einem Sitzungsspeichersystem (Claude Codes ~/.claude/projects/*/memory/, ähnlich in anderen IDEs) leiten Sie dauerhafte Benutzerfakten und Feedback stattdessen an agent-knowledge weiter. Auto-Speicher ist maschinenlokal und für andere Maschinen unsichtbar; agent-knowledge ist git-synchronisiert, maschinenübergreifend, durchsuchbar und erscheint im Wakeup. Siehe den Claude-Code-Integrationshinweis in docs/USER-MANUAL.md.

Codebasis-Erfassung

Die knowledge-ingest-Fähigkeit befüllt oder aktualisiert die Wissensdatenbank aus einem Codebasis-Verzeichnis. Sie verwendet tree-sitter für die strukturelle Extraktion ohne Token (Klassen, Funktionen, Importe, Aufrufgraphen, Begründungskommentare), gruppiert dann Dateien in Subsysteme und erstellt Wissenseinträge + Graphkanten über vorhandene MCP-Werkzeuge. Nachfolgende Läufe sind inkrementell – nur geänderte Dateien werden erneut verarbeitet.

/knowledge-ingest ./my-project

Verwendet den Agent Skills Standard – funktioniert mit Claude Code, OpenCode, Cursor, Codex CLI und Gemini CLI. Einzelheiten finden Sie im Erfassungsleitfaden.

Unterstützte Sprachen: TypeScript, JavaScript, Python, Go, Rust, Java, C, C++.

Schnellstart

Installation über npm

npm install -g agent-knowledge

Oder aus dem Quellcode klonen

git clone https://github.com/keshrath/agent-knowledge.git
cd agent-knowledge
npm install && npm run build

Option 1: MCP-Server (für KI-Agenten)

Fügen Sie dies zu Ihrer MCP-Client-Konfiguration hinzu (Claude Code, Cline usw.):

{
  "mcpServers": {
    "agent-knowledge": {
      "command": "npx",
      "args": ["agent-knowledge"]
    }
  }
}

Das Dashboard startet automatisch unter http://localhost:3423 bei der ersten MCP-Verbindung.

Siehe Einrichtungsleitfaden für clientspezifische Anweisungen (Claude Code, Cursor, Windsurf, OpenCode).

Option 2: Eigenständiger Server (für REST/WebSocket-Clients)

node dist/server.js --port 3423

MCP-Werkzeuge (6)

Wissensdatenbank

Suche

Antwortformat: {mode: "general" \| "scoped", sessions, knowledge}. Der eingeschränkte Modus gibt per Design knowledge: [] zurück.

Bereiche (scopes): errors, plans, configs, tools, files, decisions, all.

Suchoptionen:

• mmr: true wendet ein Maximal-Marginal-Relevance-Reranking an (entfernt nahezu doppelte Cluster in den Top-K). mmr_lambda 0-1, Standard 0.7.

• category_mode: "boost" (Standard) gibt Einträgen mit passender Kategorie einen 1,25-fachen Score-Multiplikator, anstatt Nicht-Übereinstimmungen zu verwerfen. Übergeben Sie "filter" für ein striktes Filterverhalten.

• explain: true fügt jedem Wissens-Treffer score_components: {bm25, decay, maturity, confidence, category_boost, mmr_penalty} hinzu.

Sitzungen

Wissensgraph

Wissenstypen: related_to, supersedes, depends_on, contradicts, specializes, part_of, alternative_to, builds_on Codestrukturtypen: calls, imports, inherits

Traversierungsrichtungen: outbound (Quelle→Ziel), inbound (Ziel→Quelle), both (Standard, ungerichtet)

Analyse

Verwaltung

Bewerteter Promoter

Jeder projektbezogene Kandidat wird anhand von sechs Signalen bewertet (Relevanz 0,30, Häufigkeit 0,24, Abfragevielfalt 0,15, Aktualität 0,15, Konsolidierung 0,10, konzeptioneller Reichtum 0,06) und anhand von minScore ≥ 0,5, minRecallCount ≥ 2, minUniqueQueries ≥ 2 geprüft. Alle drei Schwellenwerte müssen erfüllt sein. Die automatische Promotion im Hintergrund wird über dasselbe Konfigurationsflag auto_distill gesteuert; bei Bedarf mit knowledge_admin(action: "promote") aufrufen.

• promote_mode: "explain" (Standard) — Kandidaten bewerten + prüfen, Tagebuch schreiben, Wissensbasis NICHT verändern.

• promote_mode: "apply" — Kandidaten, die die Prüfung bestehen, promoten, Tagebuch schreiben, Git-Commit erstellen.

• Jeder Lauf schreibt ~/agent-knowledge/.dreams/YYYY-MM-DD.md mit Signalaufschlüsselungen und Prüfergebnissen pro Kandidat. Das mit . beginnende Verzeichnis ist git-verfolgt, aber von Liste/Suche ausgeschlossen.

• Fundierte Rehydrierung: Ein Kandidat wird übersprungen, wenn seine Quellsitzungsdatei nicht mehr auf der Festplatte vorhanden ist (verhindert das Promoten gelöschter Inhalte).

• Einträge mit evergreen: true-Frontmatter werden durch Promotion nie überschrieben — Aktivität wird angehängt.

Write-Bench-Testumgebung: npm run bench:promote — Offline-Wiedergabe mit automatischer Beschriftung durch „in späteren Sitzungen referenziert". Vergleicht den geprüften Promoter mit einer naiven „alles veröffentlichen"-Basislinie und berichtet Präzision / Recall / F1. Verwenden Sie dies, um Signalgewichtungs- oder Schwellenwertänderungen zu prüfen, bevor Sie sie ausrollen.

REST-API

Architektur

graph LR
    subgraph Storage
        KB[(Knowledge Base<br/>~/agent-knowledge<br/>Git Repository)]
    end

    subgraph Session Sources
        CC[(Claude Code<br/>JSONL)]
        CU[(Cursor<br/>JSONL)]
        OC[(OpenCode<br/>SQLite)]
        CL[(Cline<br/>JSON)]
        CD[(Continue.dev<br/>JSON)]
        AI[(Aider<br/>MD / JSONL)]
    end

    subgraph agent-knowledge
        KM[Knowledge Module<br/>store / search / git]
        AD[Session Adapters<br/>auto-discovery]
        SE[Search Engine<br/>TF-IDF + Fuzzy]
        DS[Dashboard<br/>:3423]
        MCP[MCP Server<br/>stdio]
    end

    subgraph Clients
        AG[Agent Sessions]
        WB[Web Browser]
    end

    KB <-->|git pull/push| KM
    CC --> AD
    CU --> AD
    OC --> AD
    CL --> AD
    CD --> AD
    AI --> AD
    AD --> SE
    KM --> MCP
    SE --> MCP
    KM --> DS
    SE --> DS
    MCP --> AG
    DS --> WB

Wissensgraph

Einträge und Codesymbole können über typisierte, gewichtete Kanten verbunden werden, die in einer dedizierten edges-SQLite-Tabelle gespeichert sind. Elf Beziehungstypen werden unterstützt — 8 für Wissenskanten und 3 für Codestruktur:

Wissen: related_to, supersedes, depends_on, contradicts, specializes, part_of, alternative_to, builds_on Codestruktur: calls, imports, inherits

• knowledge_graph(action: "link") erstellt oder aktualisiert eine Kante (mit optionaler Stärke 0-1)

• knowledge_graph(action: "unlink") entfernt Kanten (optional nach Typ gefiltert)

• knowledge_graph(action: "list") listet Kanten für einen Eintrag oder Beziehungstyp auf

• knowledge_graph(action: "traverse") führt eine gerichtete BFS-Traversierung ab einem Starteintrag durch. Unterstützt direction (outbound, inbound, both) und rel_type-Filter

• knowledge_graph(action: "bulk_link") erstellt Kanten in Stapelverarbeitung in einer einzigen Transaktion (für die Code-Graph-Erfassung)

• knowledge_graph(action: "unlink_by_origin") löscht alle Kanten mit einem bestimmten Ursprung (zum Löschen veralteter Code-Kanten vor der erneuten Erfassung)

Code-Graph

Codestruktur-Kanten werden von der knowledge-ingest-Fähigkeit während der Codebasis-Erfassung erstellt. Sie verwenden Knoten-IDs mit code:-Präfix:

code:src/auth/middleware.ts                    # file node
code:src/auth/middleware.ts::validateToken      # symbol node

Abfragebeispiele:

# Who calls validateToken?
knowledge_graph({ action: "traverse", entry: "code:src/auth.ts::validateToken", direction: "inbound", rel_type: "calls", depth: 3 })

# What breaks if I change this function?
knowledge_graph({ action: "traverse", entry: "code:src/auth.ts::validateToken", direction: "inbound", rel_type: "calls", depth: 5 })

# Combined: callers + knowledge context (decisions, design rationale)
knowledge_graph({ action: "traverse", entry: "code:src/auth.ts::validateToken", depth: 2 })

Automatische Verknüpfung

Wenn knowledge mit action: "write" einen Eintrag erstellt oder aktualisiert, findet es automatisch die 3 ähnlichsten vorhandenen Einträge über Kosinus-Ähnlichkeit und erstellt related_to-Kanten für jedes Paar mit einem Wert über 0,7.

Konfidenz- & Abkling-Bewertung

Jeder Wissenseintrag hat einen Konfidenzwert, der in der entry_scores-SQLite-Tabelle verfolgt wird. Suchergebnisse werden wie folgt eingestuft:

finalScore = baseRelevance * 0.5^(daysSinceLastAccess / 90) * maturityMultiplier

Einträge reifen automatisch basierend auf der Zugriffszahl:

Häufig aufgerufene Einträge steigen im Suchranking; veraltete Einträge verlieren mit der Zeit an Gewicht.

Suchfunktionen

TF-IDF-Ranking -- Ergebnisse werden nach Term Frequency-Inverse Document Frequency bewertet. Seltene Begriffe erhöhen die Relevanz. Globaler Index wird 60 Sekunden lang zwischengespeichert.

Fuzzy-Matching -- Levenshtein-Editierdistanz mit gleitendem Fenster. Konfigurierbarer Schwellenwert (Standard 0,7).

Bereichsbezogener Abruf über knowledge_search mit dem Parameter scope:

Integrationen

REST-Schreib-Endpunkt

POST /api/knowledge akzeptiert { category, filename, content } und führt die vollständige Schreib-Pipeline aus: git pull → Datei schreiben → Einbettungsindex → Auto-Link → git push → Duplikatprüfung. Gibt { path, autoLinks?, duplicateWarnings?, git } mit Status 201 zurück.

Dies ermöglicht HTTP-basierte Schreibvorgänge von anderen Diensten ohne MCP-Verbindung.

agent-tasks KnowledgeBridge

agent-tasks verfügt über eine eingebaute KnowledgeBridge, die bei Aufgabenabschluss automatisch learning- und decision-Artefakte an agent-knowledge überträgt. Einträge landen in decisions/ mit Frontmatter-Tags (agent-tasks, Projektname, Artefakttyp), werden automatisch mit Einbettungen indiziert und automatisch mit ähnlichen Einträgen verlinkt. Keine Konfiguration erforderlich — wenn agent-knowledge unter localhost:3423 läuft, funktioniert es.

Tests

npm test              # 563 tests across 35 files
npm run test:watch    # Watch mode
npm run lint          # ESLint on src/ and tests/
npm run typecheck     # tsc --noEmit
npm run check         # typecheck + lint + format + test

Umgebungsvariablen

Alle Umgebungsvariablen stehen unter dem Präfix AGENT_KNOWLEDGE_*. Kein Hostname ist fest verdrahtet — die Adapter-Registry erkennt installierte KI-Coding-Hosts automatisch (.claude, .cursor, .codex, .aider, .continue, OpenCode) ohne Konfiguration.

Kern

Einbettungen

API-Schlüssel

Projektbezogene Überschreibungen haben Vorrang vor den Standard-Schlüsseln. Setzen Sie einen von beiden; die projektbezogene Form ermöglicht es, agent-knowledge mit einem anderen Schlüssel auszuführen als den Rest Ihrer Umgebung.

Hooks

Externe Tool-Überschreibungen

Dokumentation

• Setup-Guide — Installation, Client-Einrichtung (Claude Code, OpenCode, Cursor, Windsurf), Hooks, Skills

• Ingestions-Guide — Codebase-Ingestions-Skill, tree-sitter-Extraktion, inkrementelle Updates

• Architektur — Quellstruktur, Designprinzipien, Datenbankschema

• Dashboard — Web-UI-Ansichten und Funktionen

• Changelog

Lizenz

MIT