@pcircle/memesh 4.5.1 → 4.6.1

package/.claude-plugin/marketplace.json

@@ -7,17 +7,19 @@
     {
       "name": "memesh",
       "source": "./",
-      "description": "MeMesh — Local memory for Claude Code and MCP coding agents. One SQLite file, zero cloud required.",
-      "version": "4.5.1",
+      "description": "MeMesh — agentic memory for coding agents. Captured from the agent's real work via hooks, recalled when it acts. One SQLite file, zero cloud required.",
+      "version": "4.6.1",
       "author": {
         "name": "PCIRCLE AI"
       },
-      "homepage": "https://pcircle.com/memesh-llm-memory",
+      "homepage": "https://github.com/PCIRCLE-AI/memesh",
       "license": "MIT",
       "keywords": [
         "claude-code",
         "mcp",
         "knowledge-graph",
+        "agentic-memory",
+        "agent-memory",
         "ai-memory"
       ]
     }

package/.claude-plugin/plugin.json

@@ -1,17 +1,19 @@
 {
   "name": "memesh",
-  "description": "MeMesh — Local memory for Claude Code and MCP coding agents. One SQLite file, zero cloud required.",
+  "description": "MeMesh — agentic memory for coding agents. Captured from the agent's real work via hooks, recalled when it acts. One SQLite file, zero cloud required.",
   "author": {
     "name": "PCIRCLE AI"
   },
-  "version": "4.5.1",
-  "homepage": "https://pcircle.com/memesh-llm-memory",
-  "repository": "https://github.com/PCIRCLE-AI/memesh-llm-memory",
+  "version": "4.6.1",
+  "homepage": "https://github.com/PCIRCLE-AI/memesh",
+  "repository": "https://github.com/PCIRCLE-AI/memesh",
   "license": "MIT",
   "keywords": [
     "claude-code",
     "mcp",
     "knowledge-graph",
+    "agentic-memory",
+    "agent-memory",
     "ai-memory"
   ]
 }

package/AGENTS.md

@@ -0,0 +1,116 @@
+# Using MeMesh — for AI agents
+
+MeMesh is persistent memory shared by every MCP host on this machine — one
+SQLite database at `~/.memesh/knowledge-graph.db`. A memory stored from one
+host is recallable from all of them. Not installed yet? Follow
+[llms-install.md](llms-install.md).
+
+## The loop that pays for itself
+
+1. **Session start — load, don't re-explore.** Call the `briefing` tool once
+   (CLI: `memesh briefing`). It returns the assembled work topology for the
+   current project: goal / next / blocked / done, decisions, lessons,
+   knowledge, recent activity. Read that instead of re-reading the repo to
+   reconstruct context.
+2. **When the user states a goal, a next step, or a blocker — record it.**
+   Call the `task_state` tool (CLI: `memesh task --goal "…" --next "…"`). It
+   is injected at the start of the next session and acted on as fact.
+   - An empty string **clears** a field: pass `blocked: ""` (CLI:
+     `memesh task --blocked ""`) once a blocker is resolved.
+   - **Record only what the user actually said.** Never infer goal / next /
+     done from files edited or commands run — a guessed value becomes a wrong
+     instruction to a future session with nothing to contradict it. Leave a
+     field out if it was not said.
+3. **"What do you remember?"** — call `briefing` and relay its content. Do
+   not answer from your own conversation context.
+
+## All 9 MCP tools
+
+| Tool | Purpose |
+|---|---|
+| `remember` | Store knowledge as an entity with observations, tags, and relations |
+| `recall` | Search stored knowledge (words are OR-ed, ranked by relevance); empty query lists recent |
+| `forget` | Archive an entity (soft-delete), or remove one observation via the `observation` parameter |
+| `export` | Export memories as portable JSON for sharing or backup |
+| `import` | Import a JSON export; `merge_strategy` (required): skip / append / overwrite |
+| `learn` | Record a structured lesson: error, root cause, fix, prevention |
+| `task_state` | Read or update where the work stands: goal / next / blocked / done |
+| `briefing` | The assembled work topology for a project — call once at session start |
+| `user_patterns` | Analyze work schedule, tool preferences, and focus areas from memory |
+
+## Memory hygiene
+
+- **Reuse a stable `name` to append.** Calling `remember` with an existing
+  name appends observations and dedupes tags. A fresh name for every update
+  creates duplicates that recall must wade through.
+- **Replacing a decision**: `remember` the new one with a relation of type
+  `supersedes` pointing at the old — the old entity is archived (recoverable),
+  not left active to contradict the new one.
+- **Two memories that cannot both be true**: relation type `contradicts` —
+  both then surface as a conflict every time either is recalled.
+- **One wrong fact in an otherwise good entity**: `forget` with the
+  `observation` parameter removes just that fact and keeps the entity active.
+  Prefer it over archiving the whole entity.
+
+## What you must never invent
+
+- If MeMesh is unavailable or a recall returns nothing, **say so and work
+  without it** — never fabricate a memory, and never cite a `[mem:id]`
+  handle that was not actually shown to you. A wrong "remembered" fact is
+  worse than no memory: it arrives wearing the authority of the graph.
+- Recall windows are bounded (the `limit` parameter, 30 by default), so do
+  not infer graph-wide counts or "there is no memory about X" from the
+  number of hits one query returns. Absence of results is absence of
+  results, not evidence of absence — vary the wording or narrow by tag
+  before concluding anything.
+- Every recall answer carries a `retrieval` block that says how it was
+  produced — read it instead of guessing: `truncated: true` means the
+  window filled and more may exist; `degraded: true` means semantic search
+  is configured but could not run, so you are seeing keyword-only results
+  right now (worth telling the user, and `memesh doctor` explains why).
+
+## What Claude Code already does — do not double-write
+
+Under Claude Code with the MeMesh plugin, hooks capture automatically:
+
+- **SessionStart** injects the work topology (the same block `briefing`
+  returns) at the top of the session.
+- **PreToolUse (Edit|Write)** surfaces memories related to the file being
+  edited.
+- **PostToolUse (Bash)** records git commits with diff stats.
+- **Stop** captures session knowledge and turns failures into lessons.
+- **PreCompact** saves important knowledge before history is compressed.
+- **UserPromptSubmit** detects "remember this" intent in the prompt.
+- **PreToolUse (Bash)** fires accepted lesson-guards: a fenced warning
+  citing the source lesson (`[mem:id]`) when a command matches a mistake
+  the graph has recorded. Heed it, and cite the lesson if it changes what
+  you do.
+
+So under Claude Code: skip step 1 of the loop (the topology is already
+injected), and do not `remember` commits or session summaries by hand. Manual
+calls are for what hooks cannot see — decisions and their rationale, lessons
+worth keeping, and user-stated task state.
+
+Other hosts (Codex CLI, Gemini CLI, Cursor, …) have no hooks: there the loop
+is fully manual, and it is worth running.
+
+## Working on this repository (contributing agents)
+
+The sections above are for agents whose user installed memesh. If you are an
+agent making changes to this codebase, [CLAUDE.md](CLAUDE.md) is the entry
+point; the policy it carries, compressed:
+
+- **Blast radius picks the process.** One module, no security surface, no
+  cross-surface behaviour → implement, run the affected tests + typecheck,
+  read your own diff. Anything wider → the full gate (`npm run
+  verify:release`), break-test the guards you add, docs in the same PR.
+- **Findings first, with evidence.** Reviews and QA reports lead with what is
+  wrong and prove it (file:line, actual output). Verdicts are `PASS`,
+  `PASS_WITH_CONCERNS`, or `FAIL` — the same vocabulary `memesh doctor` uses.
+- **No runtime claim without runtime evidence.** Paste the runner's output;
+  read exit codes, not grepped fragments.
+- **Delegation is disjoint.** Two writers never touch one file; file-editing
+  subagents work in isolated worktrees and never commit or push — the
+  orchestrator reads every diff before it lands.
+- **Internal notes stay local.** Plans and scratch analyses are never
+  committed and never appear in commit messages or release notes.

package/README.de.md

@@ -1,9 +1,9 @@
-🌐 [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Tiếng Việt](README.vi.md) | [Español](README.es.md) | [ภาษาไทย](README.th.md)
+🌐 [English](README.md) | [繁體中文](README.zh-TW.md) | [Deutsch](README.de.md)
 
 <p align="center">
-  <h1 align="center">MeMesh LLM Memory</h1>
+  <h1 align="center">MeMesh</h1>
   <p align="center">
-    <strong>Lokaler Speicher für Claude Code und MCP-Coding-Agenten.</strong><br />
+    <strong>Agentischer Speicher für Coding-Agenten.</strong><br />
     Eine SQLite-Datei. Kein Docker. Keine Cloud erforderlich.
   </p>
   <p align="center">
@@ -16,32 +16,38 @@
 
 ---
 
-> [!IMPORTANT]
-> **Aktiv entwickeltes Projekt** — Funktionen entwickeln sich kontinuierlich weiter und können sich zwischen Releases ändern. Bei Bugs oder Feature-Wünschen bitte [ein Issue eröffnen](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues).
+**MeMesh** — Open-Source-**agentischer Speicher** für Claude Code & MCP-Coding-Agenten: erfasst aus der echten Arbeit des Agenten, injiziert in dem Moment, in dem er handelt, ehrlich gehalten, wenn er sich selbst widerspricht. Eine SQLite-Datei. Keine Cloud.
 
-## Das Problem
+## Installation
 
-Ihr Coding-Agent vergisst, was zwischen Sessions passiert ist. Jede Architekturentscheidung, jede Bugfix, jeder fehlgeschlagene Test und jede hart erarbeitete Erkenntnis muss erneut erklärt werden. Claude Code startet von vorne, entdeckt alte Constraints neu und verschwendet Context auf Dinge, die es längst wissen sollte.
+**In Claude Code** — diese zwei Zeilen im Chat eingeben (Hooks, Memory-Tools und der `/memesh`-Skill werden automatisch verdrahtet):
 
-**MeMesh gibt Coding-Agenten persistenten, durchsuchbaren und evolvirenden lokalen Speicher.**
+```
+/plugin marketplace add PCIRCLE-AI/memesh
+/plugin install memesh@pcircle-memesh
+```
 
-Dieses Paket ist die lokale Speicherschicht der MeMesh-Produktfamilie. Es ist bewusst klein und Open-Source gestaltet: Installation via npm, Speicherung im Wissensgraphen unter `~/.memesh/knowledge-graph.db`, Anbindung an Claude Code oder jeden MCP-kompatiblen Client. Gehostete Workspace- und Enterprise-Betriebssystem-Produkte bleiben separat von diesem README und der Roadmap.
+Claude Code neu starten. Eine `◉ MeMesh`-Statuszeile am Anfang der nächsten Session bedeutet: es zeichnet auf.
 
----
+**Im Terminal** — die `memesh`-CLI, das Dashboard und der `memesh-mcp`-Server für Codex / Gemini / Cursor (braucht [Node 22.13+](https://nodejs.org)):
 
-## Beleg — 95.60% R@5 auf LongMemEval-S
+```bash
+npm install -g @pcircle/memesh
+memesh doctor        # prüft diese Installation Ende-zu-Ende
+```
 
-MeMeshs Retrieval-Engine ist **FTS5 alleine** (kein LLM, keine Embeddings auf dem Hot Path), gemessen am öffentlichen [LongMemEval-S](https://huggingface.co/datasets/xiaowu0162/longmemeval) Benchmark (500 Fragen, MIT-lizenziert):
+Die meisten Claude-Code-Nutzer wollen am Ende **beides** — gemeinsame Datenbank, kein Konflikt. Details, weitere Agenten, Upgrades: siehe „In 60 Sekunden starten" unten.
 
-| System | R@5 | Quelle |
-|---|---|---|
-| **MeMesh (Mode A, via `recallEnhanced()`)** | **95.60%** | [benchmarks/longmemeval/RESULTS.md](benchmarks/longmemeval/RESULTS.md) |
-| MemPalace | 96.6% | Eigenangabe des Anbieters |
-| Supermemory | ~82% | Schätzung des Anbieters |
-| Zep | 63.8% | LongMemEval-Paper |
-| Mem0 | 49.0% | LongMemEval-Paper |
+## Das Problem
 
-Reproduktionsbefehle, Datensatz-SHA256, rohe Ergebnisse pro Frage und Analyse bekannter Fehlschläge finden sich vollständig in [`benchmarks/longmemeval/`](benchmarks/longmemeval/). In ~10 Sekunden reproduzierbar.
+Ihr Coding-Agent vergisst nicht nur Fakten zwischen Sessions — er **wiederholt Arbeit**. Er schlägt erneut den Ansatz vor, den Sie letzten Monat abgelehnt haben, stolpert über denselben fehlschlagenden Test, entdeckt die Constraint wieder, die im März die Produktion kaputt gemacht hat, und bittet Sie, die Architektur erneut zu erklären, die er selbst mitentworfen hat.
+
+Das ist kein Chatverlauf-Problem, sondern ein Agenten-Speicher-Problem. Was zwischen Sessions überleben muss, ist die *Arbeit*: Entscheidungen mit ihren Gründen, Fehlschläge mit ihren Behebungen und die Verbindungen dazwischen.
+
+**MeMesh ist dieser Speicher.** Hooks erfassen ihn aus dem, was der Agent tatsächlich tut (Sessions, Commits, Fehlschläge — keine manuellen Notizen), Recall injiziert ihn in dem Moment, in dem der Agent handelt (Session-Start, vor Dateibearbeitungen), und die Wissensgraph-Schicht hält ihn über die Zeit ehrlich (Supersession, LLM-beurteilte Konflikterkennung). Installation via npm, der Speicher liegt in `~/.memesh/knowledge-graph.db`, Anbindung an Claude Code oder jeden MCP-kompatiblen Client.
+
+> [!IMPORTANT]
+> **Aktiv entwickeltes Projekt** — Funktionen entwickeln sich kontinuierlich weiter und können sich zwischen Releases ändern. Bei Bugs oder Feature-Wünschen bitte [ein Issue eröffnen](https://github.com/PCIRCLE-AI/memesh/issues).
 
 ---
 
@@ -65,7 +71,7 @@ flowchart TB
     subgraph paths["Two install paths"]
       direction LR
       A["<b>Path A — /plugin install</b><br/>───────────────<br/>Lives in <code>~/.claude/plugins/</code><br/><br/>• MCP tools in chat<br/>• Auto-capture hooks<br/>• <code>/memesh</code> skill<br/>• Session-start banner"]:::pathA
-      B["<b>Path B — npm install -g</b><br/>───────────────<br/>Lives in <code>$(npm prefix -g)/bin/</code><br/><br/>• <code>memesh</code> shell command<br/>• <code>memesh-mcp</code>, <code>-http</code>, <code>-view</code> bins<br/>• For Cursor / Cline / other MCP"]:::pathB
+      B["<b>Path B — npm install -g</b><br/>───────────────<br/>Lives in <code>$(npm prefix -g)/bin/</code><br/><br/>• <code>memesh</code> shell command<br/>• <code>memesh-mcp</code>, <code>-http</code> bins<br/>• For Cursor / Cline / other MCP"]:::pathB
     end
 
     DB[("Shared memory DB<br/><code>~/.memesh/knowledge-graph.db</code><br/>Same data, both paths see it")]:::db
@@ -113,12 +119,14 @@ Wenn du memesh nur im Claude-Code-Chat verwendest (nie `memesh` im Terminal tipp
 Wenn Sie Claude Code nutzen, installieren Sie MeMesh als Plugin direkt in der CLI:
 
 ```
-/plugin marketplace add PCIRCLE-AI/memesh-llm-memory
+/plugin marketplace add PCIRCLE-AI/memesh
 /plugin install memesh@pcircle-memesh
 ```
 
 Claude Code verdrahtet Hooks, Skills und den MCP-Server automatisch. Sie erhalten Auto-Capture in der Session, proaktives Recall, den `/memesh`-Skill in der Unterhaltung und `remember` / `recall` / `forget` / `learn` als MCP-Tools für den Agenten.
 
+**Prüfen:** Claude Code neu starten und eine beliebige Session beginnen. Eine Statuszeile wie `◉ MeMesh ready · no memories for "your-project" yet` erscheint oben — diese Zeile IST das funktionierende Plugin; kein separater Befehl nötig. (Mit vorhandenen Memories zeigt sie stattdessen Zähler.)
+
 ### Option B — npm global (optionale Optimierung)
 
 Wenn Sie das Binary direkt im `PATH` möchten (damit `memesh` in jedem Terminal ohne `npx`-Verzögerung läuft) oder `memesh-mcp` als stdio-Befehl mit festem Pfad für MCP-Clients außerhalb von Claude Code (Cursor, Cline) bereitstellen wollen:
@@ -129,15 +137,54 @@ npm install -g @pcircle/memesh
 
 ### Schritt 1.5: MeMesh in Claude Code einbinden (empfohlen, einmalig)
 
-`npm install -g` legt die CLI in den PATH und registriert den MCP-Server, aber MeMeshs Claude-Code-Session-Hooks werden **nicht** automatisch verdrahtet. Ohne diese Hooks können Sie `memesh remember` / `recall` manuell verwenden, aber die **Auto-Capture-Schleife** (Session → Lektionen → proaktive Erinnerung in der nächsten Session) bleibt stumm.
+`npm install -g` legt die CLI in den PATH — aber nichts ist damit in Claude Code eingebunden: Das npm-Paket führt bewusst keine Install-Skripte aus; MCP-Server und Hooks in Claude Code registriert das Plugin (Option A). Was der npm-Pfad selbst verdrahten kann, sind die Session-Hooks. Ohne diese Hooks können Sie `memesh remember` / `recall` manuell verwenden, aber die **Auto-Capture-Schleife** (Session → Lektionen → proaktive Erinnerung in der nächsten Session) bleibt stumm.
+
+```bash
+memesh setup                 # erkennt Claude Code / Codex / Gemini, bietet die Verdrahtung an, prüft danach
+```
+
+Oder die Einzelschritte von Hand:
 
 ```bash
 memesh install-hooks         # fügt memesh-Hooks zu ~/.claude/settings.json hinzu
-memesh doctor                # bestätigt, dass „Hooks wired into Claude Code" PASST
+memesh setup --check         # Prüfung auf Maschinenebene: liest die Host-Configs, ändert nichts
 ```
 
 Die Hooks existieren neben Ihren bestehenden Custom-Hooks unter `~/.claude/hooks/` — `install-hooks` schreibt additiv und überschreibt nie Ihre Einträge. Zum Entfernen: `memesh uninstall-hooks`.
 
+### Dieselben Memories aus Codex CLI und Gemini CLI
+
+`memesh-mcp` ist ein gewöhnlicher stdio-MCP-Server — jeder MCP-fähige Host kann ihn nutzen, nicht nur Claude Code. Mit installierter Option B (`memesh-mcp` im `PATH`) einmal pro Host registrieren:
+
+```bash
+# OpenAI Codex CLI — schreibt [mcp_servers.memesh] in ~/.codex/config.toml
+codex mcp add memesh -- memesh-mcp
+
+# Google Gemini CLI — User-Scope, funktioniert in jedem Ordner
+gemini mcp add -s user memesh memesh-mcp
+```
+
+Jeder Host liest und schreibt dieselbe `~/.memesh/knowledge-graph.db` — eine in Claude Code gespeicherte Memory ist aus Codex oder Gemini abrufbar, und umgekehrt. Prüfen:
+
+```bash
+codex mcp list       # memesh sollte als enabled gelistet sein
+gemini mcp list      # memesh sollte "Connected" zeigen
+```
+
+> **Als konfigurierten Befehl `memesh-mcp` verwenden, NICHT `npx -p @pcircle/memesh`.** `npx -p` löst zum *lokalen* Paket auf, sobald das Arbeitsverzeichnis des Hosts in einem Checkout dieses Repositories liegt — und führt dann stillschweigend dessen aktuellen Stand statt des installierten Release aus.
+
+### Native Integration: Hermes Agent
+
+**Hermes Agent** (NousResearch) verfügt über ein erstklassiges `MemoryProvider`-Pluginsystem — MeMesh integriert sich auf derselben Ebene wie Hermes' eigene eingebaute Memory-Backends (honcho, mem0, hindsight), nicht als HTTP-Bridge. Anders als im MCP-Modus, wo Sie Tools manuell aufrufen, führt Hermes' Provider-System `recall`/`remember` bei jedem Turn automatisch aus.
+
+Die Integration mappt Hermes' `prefetch()`- und `sync_turn()`-Hooks direkt auf MeMesh' HTTP-API. Vollständiger Leitfaden mit Provider-Codestruktur, Konfiguration und vier echten Fallstricken aus einem Live-Deployment: **[docs/platforms/hermes-agent.md](docs/platforms/hermes-agent.md)**
+
+### Native Integration: OpenClaw
+
+**OpenClaw** verfügt über ein erstklassiges Memory-Capability-Pluginsystem — MeMesh integriert sich auf derselben Ebene wie OpenClaw's eigene eingebaute Backends (LanceDB), nicht als HTTP-Bridge. Das Plugin registriert sich über `api.registerMemoryCapability()` und stellt `memory_recall`/`memory_store`/`memory_forget`-Tools sowie automatisches Recall beim `before_prompt_build`-Hook bereit.
+
+**Hauptunterschied zu Hermes**: OpenClaw's Auto-Capture ist schwellenwertgesteuert (max. 3 Memories/Turn bei Trigger), nicht bei jedem Turn. Die Integration mappt auf MeMesh' HTTP-API (`/v1/recall`, `/v1/remember`, `/v1/forget`). Vollständiger TypeScript-Plugin-Vertrag, Konfigurationsform und Fallstricke: **[docs/platforms/openclaw.md](docs/platforms/openclaw.md)**
+
 ### Schritt 2: Entscheidung speichern
 
 ```bash
@@ -172,17 +219,43 @@ memesh serve
 ```
 
 <p align="center">
-  <img src="docs/images/dashboard-search.png" alt="MeMesh Search — find any memory instantly" width="100%" />
+  <img src="docs/images/dashboard-search.png" alt="MeMesh — find any memory instantly" width="100%" />
 </p>
 
 <p align="center">
-  <img src="docs/images/dashboard-analytics.png" alt="MeMesh Analytics — health score, timeline, patterns, knowledge coverage" width="100%" />
+  <img src="docs/images/dashboard-analytics.png" alt="MeMesh analytics — health score, timeline, patterns, knowledge coverage" width="100%" />
 </p>
 
 <p align="center">
   <img src="docs/images/dashboard-graph.png" alt="MeMesh Graph — interactive knowledge graph with type filters and ego mode" width="100%" />
 </p>
 
+### Sehen, was es sich gemerkt hat
+
+Ein Befehl zeigt jederzeit, was Ihr Agent über das aktuelle Projekt weiß — wo die Arbeit stand, Entscheidungen, Lektionen, jüngste Aktivität (verpackt als Referenzdaten):
+
+```bash
+memesh briefing
+```
+
+```text
+Where "your-project" was left off (today):
+- Goal: Ship the payment retry logic
+- Next: Open the PR once CI is green
+
+Decisions and direction for "your-project":
+- [decision] Use FTS5 as the retrieval baseline
+```
+
+Denselben Block erhält Claude Code automatisch beim Session-Start, und jeder andere MCP-Client über das `briefing`-Tool — der Agent startet orientiert, statt das Repository neu zu lesen, und Sie erklären letzte Woche nicht noch einmal. Das Dashboard (`memesh serve`) ist die vollständige visuelle Ansicht.
+
+### Ihre Daten
+
+- **Eine lokale Datei.** Alles liegt in `~/.memesh/knowledge-graph.db` — SQLite, auf Ihrer Festplatte. Kein Cloud-Konto; nichts verlässt Ihren Rechner, außer Sie konfigurieren selbst einen Cloud-Embedder oder ein LLM.
+- **Backup = diese eine Datei kopieren.** Wiederherstellen = zurückkopieren.
+- **Aufzeichnung jederzeit pausieren**: `export MEMESH_AUTO_CAPTURE=false`.
+- **Alles löschen**: `~/.memesh/` entfernen.
+
 ---
 
 ## Für wen ist das gedacht?
@@ -251,9 +324,25 @@ Tools in beliebige API-Aufrufe einfügen
 
 ---
 
+## Benchmarks — 95.60% R@5 auf LongMemEval-S
+
+MeMeshs Retrieval-Engine ist **FTS5 alleine** (kein LLM, keine Embeddings auf dem Hot Path), gemessen am öffentlichen [LongMemEval-S](https://huggingface.co/datasets/xiaowu0162/longmemeval) Benchmark (500 Fragen, MIT-lizenziert):
+
+| System | R@5 | Quelle |
+|---|---|---|
+| **MeMesh (Mode A, via `recallEnhanced()`)** | **95.60%** | [benchmarks/longmemeval/RESULTS.md](benchmarks/longmemeval/RESULTS.md) |
+| MemPalace | 96.6% | Eigenangabe des Anbieters |
+| Supermemory | ~82% | Schätzung des Anbieters |
+| Zep | 63.8% | LongMemEval-Paper |
+| Mem0 | 49.0% | LongMemEval-Paper |
+
+Reproduktionsbefehle, Datensatz-SHA256, rohe Ergebnisse pro Frage und Analyse bekannter Fehlschläge finden sich vollständig in [`benchmarks/longmemeval/`](benchmarks/longmemeval/). In ~10 Sekunden reproduzierbar.
+
+---
+
 ## Was läuft in Claude Code automatisch ab
 
-Sie müssen nicht manuell alles speichern. MeMesh verfügt über **6 Hooks**, die Wissen während der Arbeit erfassen und injizieren:
+Sie müssen nicht manuell alles speichern. MeMesh verfügt über **7 Hooks**, die Wissen während der Arbeit erfassen und injizieren:
 
 | Wenn | Was MeMesh tut |
 |------|------------------|
@@ -262,6 +351,7 @@ Sie müssen nicht manuell alles speichern. MeMesh verfügt über **6 Hooks**, di
 | **Nach jedem `git commit`** | Erfasst Ihre Änderungen mit Diff-Statistiken |
 | **Wenn Claude stoppt** | Erfasst bearbeitete Dateien und behobene Fehler; generiert automatisch strukturierte Lektionen aus Fehlern |
 | **Vor Context-Verdichtung** | Speichert Wissen, bevor es durch Context-Limits verloren geht |
+| **Vor riskanten Befehlen und Edits** | Löst die von Ihnen akzeptierten Lektions-Guards aus — eine Warnung genau in dem Moment, in dem sich ein erfasster Fehler wiederholen würde |
 
 > **Jederzeit abschalten:** `export MEMESH_AUTO_CAPTURE=false`
 
@@ -290,17 +380,14 @@ Wenn npm eine installierte Version als veraltet kennzeichnet (typischerweise ein
 
 ## Dashboard
 
-8 Reiter, 11 Sprachen, keine externen Abhängigkeiten. Zugang unter `http://localhost:3737/dashboard` wenn der Server läuft.
+5 Reiter, 11 Sprachen, keine externen Abhängigkeiten. Zugang unter `http://localhost:3737/dashboard` wenn der Server läuft.
 
 | Reiter | Was Sie sehen |
 |--------|-------------|
-| **Insights** | Speicher-Insights — wöchentliche Zusammenfassungen und Mustervorschläge der Dreamer-Engine; Ein-Klick-Akzeptieren/Ablehnen |
-| **Search** | Volltextsuche + Vektorsimilarität über alle Memories |
-| **Browse** | Paginierte Liste aller Entitäten mit Archiv-/Restore-Funktion |
-| **Analytics** | Memory Health Score, 30-Tage-Timeline, PM-Velocity + KG-Konnektivitätskennzahlen, Arbeitsmuster, Bereinigungsvorschläge |
+| **Home** | Was memesh für Sie getan hat — Dreamer-Insights zuerst: wöchentliche Zusammenfassungen und Mustervorschläge mit Ein-Klick-Akzeptieren/Ablehnen; die komplette Analyse (Memory Health Score, 30-Tage-Timeline, PM-Velocity + KG-Konnektivität, Arbeitsmuster) liegt in einem bei Bedarf ausklappbaren Bereich |
+| **Memories** | Die ganze Bibliothek hinter einer Oberfläche — Sofortfilter plus Enter für server-gerankte Suche (Volltext + Vektor), Scope-Chips für die Arbeitsebene (Ziele/Entscheidungen/Lektionen/Pläne) vs. Belege vs. alle vs. archiviert, ein Cluster-Kompositionsbalken, aufklappbare Details pro Zeile (Lektionen behalten ihre strukturierte Fehler/Grundursache/Behebung/Prävention-Ansicht), Archivieren/Wiederherstellen inline |
+| **Project** | Die Geschichte eines Projekts — die Roadmap-Ansicht (Phasen, Meilensteine, Schlüssellektionen) hinter einem Projektwähler |
 | **Graph** | Interaktiver kraft-gerichteter Wissensgraph mit Typfiltern, Suche, Ego-Modus, Aktualitäts-Heatmap |
-| **Lessons** | Strukturierte Lektionen aus vergangenen Fehlern (Fehler, Grundursache, Behebung, Prävention) |
-| **Manage** | Entitäten archivieren und wiederherstellen |
 | **Settings** | LLM-Provider-Konfiguration, sofortiger Sprachwahlschalter |
 
 ---
@@ -333,7 +420,7 @@ Importierte Bundles bleiben durchsuchbar, aber MeMesh injiziert importierte Memo
 > — **3er-Startup mit gemeinsamer Wissensbasis**
 
 > "Das Dashboard zeigte mir, dass 90 % meiner Memories automatisch generierte Session-Logs waren. Ich begann, `remember` bewusst für Architekturentscheidungen zu nutzen. Ein Spielwechsel."
-> — **Entwickler, der den Analytics-Reiter entdeckte**
+> — **Entwickler, der das Analytics-Panel entdeckte**
 
 ---
 
@@ -360,10 +447,11 @@ Standardmäßig macht MeMesh reines Keyword-Recall (FTS5) — kein API-Schlüsse
 
 ```bash
 memesh config set embedder.provider openai          # or: ollama
-memesh config set embedder.model text-embedding-3-small
 ```
 
-Der Embedder wird **unabhängig vom Chat-LLM** konfiguriert — `llm.provider` zu ändern ändert nie stillschweigend deine Embeddings. Wechselst du zu einer anderen Dimension (z. B. 768 → 1536), baut MeMesh den Vektorindex beim nächsten Schreibvorgang automatisch neu auf. Unterstützte `embedder.provider`-Werte: `ollama` (lokal), `openai` (gehostet). Ohne Einstellung bleibt das Recall bei der Keyword-Suche.
+Der Embedder wird **unabhängig vom Chat-LLM** konfiguriert — `llm.provider` zu ändern ändert nie stillschweigend deine Embeddings. Jeder Anbieter legt sein Modell und seine Dimension selbst fest (`ollama` → nomic-embed-text mit 768, `openai` → text-embedding-3-small mit 1536); das Modell ist nicht separat wählbar, weil ein Vektorindex auf eine Dimension festgelegt ist und ein zweites Modell Vektoren aus einem anderen Embedding-Raum hineinschreiben würde.
+
+Wechselst du zu einer anderen Dimension (z. B. 768 → 1536), wird **nichts gelöscht**. MeMesh behält den bestehenden Index und weist beim Öffnen darauf hin, `memesh reindex` auszuführen: der neue Index wird neben dem alten aufgebaut und erst übernommen, wenn jede Erinnerung einen Vektor hat — ein abgebrochener Neuaufbau kostet dich also nichts und wird an der Abbruchstelle fortgesetzt. In diesem Zeitraum ist die semantische Suche aus und das Recall läuft nur über die Keyword-Suche; `recall` meldet das als `degraded`, statt eine Suche vorzugeben. Unterstützte `embedder.provider`-Werte: `ollama` (lokal), `openai` (gehostet). Ohne Einstellung bleibt das Recall bei der Keyword-Suche.
 
 | | Stufe 0 (Standard) | Stufe 1 (Smart Mode) |
 |---|---|---|
@@ -376,7 +464,7 @@ Der Embedder wird **unabhängig vom Chat-LLM** konfiguriert — `llm.provider` z
 
 ---
 
-## Alle 7 Memory-Tools
+## Alle 9 Memory-Tools
 
 | Tool | Was es tut |
 |------|-------------|
@@ -386,6 +474,8 @@ Der Embedder wird **unabhängig vom Chat-LLM** konfiguriert — `llm.provider` z
 | `export` | Memories als JSON zwischen Projekten oder Teamkollegen teilen |
 | `import` | Memories mit Merge-Strategien importieren (Skip / Overwrite / Append) |
 | `learn` | Strukturierte Lektionen aus Fehlern erfassen (Fehler, Grundursache, Behebung, Prävention) |
+| `task_state` | Arbeitsstand lesen oder festhalten — Ziel, nächster Schritt, Blocker, gerade Erledigtes |
+| `briefing` | Die zusammengesetzte Arbeits-Topologie — derselbe Block, den Claude Code beim Session-Start erhält, für jeden MCP-Client |
 | `user_patterns` | Arbeitsmuster analysieren — Zeitplan, Tools, Stärken, Lernbereiche |
 
 ---
@@ -417,19 +507,22 @@ Der Plugin-Marketplace von Claude Code fixiert Versionen zum Installationszeitpu
 
 **Option A — `/plugin` UI**: `memesh@pcircle-memesh` deinstallieren, dann neu installieren. Claude Code holt die neueste Marketplace-Version.
 
-**Option B — Einzeiler-Skript** (kein UI-Klicken, idempotent):
+**Option B — ein Befehl** (kein UI-Klicken, idempotent; braucht die npm-CLI, `npm install -g @pcircle/memesh`):
+
+```bash
+memesh upgrade-plugin
+```
+
+Der Befehl findet die installierte Plugin-Version, prüft die Voraussetzungen und führt das mitgelieferte Upgrade-Skript aus. Voraussetzungen: `node`, `npm` und `rsync` im PATH (macOS bringt rsync mit; Debian/Ubuntu: `sudo apt install rsync`).
+
+Nur-Plugin-Nutzer ohne npm-CLI können das Skript weiter von Hand starten — die installierte Version in den Pfad einsetzen:
 
 ```bash
-# Wenn deine Plugin-Installation v4.2.5 oder neuer ist, ist das Skript enthalten:
 bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
 
-# Bei Installationen vor v4.2.5 (also v4.2.4 oder v4.2.3)
-# ist das Skript noch nicht im Plugin. Nutze stattdessen die npm-global-Kopie:
+# Installationen vor v4.2.5 enthalten das Skript noch nicht; nutze
+# stattdessen die npm-global-Kopie (siehe oben „Installationspfade auf einen Blick"):
 bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
-
-# (Das setzt voraus, dass du auch `npm install -g @pcircle/memesh` ausgeführt hast.
-# Falls nicht, ist jetzt ein guter Moment dafür — siehe oben „Installationspfade auf
-# einen Blick" für die Gründe, warum die meisten Nutzer beide Pfade wollen.)
 ```
 
 Das Skript fast-forwarded den Marketplace-Cache, legt die neue Version unter `~/.claude/plugins/cache/` ab, installiert Runtime-Dependencies und zeigt `installed_plugins.json` neu. Starte danach Claude Code neu, damit der MCP-Server sich neu verbindet.
@@ -443,8 +536,8 @@ Beim Session-Start erscheint ein einzeiliges Banner (pro Version alle 24h gedros
 ## Beitragen
 
 ```bash
-git clone https://github.com/PCIRCLE-AI/memesh-llm-memory
-cd memesh-llm-memory && npm install && npm run build
+git clone https://github.com/PCIRCLE-AI/memesh
+cd memesh && npm install && npm run build
 npm test
 npm run test:e2e-dashboard
 ```