knowmind 0.4.1 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,23 @@
1
1
  # Knowmind CLI — Änderungen
2
2
 
3
+ ## 0.4.2 (2026-10-16)
4
+
5
+ - Liegt ein Ordner im Open Knowledge Format mit Belegen unter `.claims/` in
6
+ einem Git-Repository, prüft `knowmind sync` jeden Beleg, der auf eine Datei
7
+ im Repository zeigt (`repo-lines-v1` für Zeilen, `repo-file-v1` für die ganze
8
+ Datei), gegen den letzten Commit. Haben sich die belegten Zeilen oder die
9
+ belegte Datei seit dem Stand geändert, gegen den die Seite geschrieben wurde,
10
+ oder gibt es die Datei nicht mehr, trägt die Seite danach im Abruf das
11
+ Kennzeichen `drifted`. Zeilen, die nur verschoben wurden, zählen nicht; eine
12
+ umbenannte Datei wird am neuen Ort verglichen.
13
+ - Ist dieser Stand nicht bekannt oder fehlt er in der Historie, etwa in einem
14
+ flachen Klon, nennt `knowmind sync` das in seiner Ausgabe und setzt kein
15
+ Kennzeichen. Außerhalb eines Git-Repositorys gibt `knowmind sync` einen
16
+ Hinweis aus und prüft keine Belege.
17
+ - Das Kennzeichen entfällt beim nächsten Lauf, sobald die Seite gegen den
18
+ aktuellen Stand neu geschrieben oder nach der Änderung erneut geprüft wurde.
19
+ - `knowmind search` und der Hinweis in `AGENTS.md` nennen das neue Kennzeichen.
20
+
3
21
  ## 0.4.1 (2026-10-16)
4
22
 
5
23
  - `knowmind search` zeigt bei Treffern aus Seiten im Open Knowledge Format die
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "knowmind",
3
- "version": "0.4.1",
3
+ "version": "0.4.2",
4
4
  "mcpName": "io.github.Schubeler-Consulting/knowmind",
5
5
  "description": "Knowmind — das Agentengehirn aus Deutschland: CLI + MCP-Server (Langzeitgedächtnis & Wissensgraph für Ihre KI, Server in Deutschland).",
6
6
  "type": "module",
package/src/anzeige.js CHANGED
@@ -3,7 +3,8 @@
3
3
  *
4
4
  * Treffer aus Seiten im Open Knowledge Format tragen seit dem Serverstand vom
5
5
  * 16.10.2026 `metadata.review_flags`: `stale` (Verfallszeitpunkt erreicht),
6
- * `unverified` (keine Prüfung verzeichnet), `superseded` (überholt). Die
6
+ * `unverified` (keine Prüfung verzeichnet), `superseded` (überholt), seit 0.4.2
7
+ * `drifted` (belegter Code geändert). Die
7
8
  * Kopfzeile zeigt sie in eckigen Klammern; ohne Kennzeichen bleibt sie wie
8
9
  * bisher.
9
10
  */
@@ -0,0 +1,161 @@
1
+ /**
2
+ * Belegdrift: Hat sich der Code geändert, auf den die Belege einer OKF-Seite
3
+ * zeigen? (seit 0.4.2)
4
+ *
5
+ * OpenWiki legt zu jeder Seite unter `.claims/<Seite>.json` die belegten
6
+ * Aussagen ab; jeder Beleg nennt eine Datei im Repo und, bei `repo-lines-v1`,
7
+ * einen Zeilenbereich (`repo://src/x.ts#L10-L14`). Den Stand, gegen den die
8
+ * Seite geschrieben wurde, nennt `.page-manifest.json` als `gitHead` je Seite,
9
+ * ersatzweise `.last-update.json`.
10
+ *
11
+ * Gerechnet wird lokal mit git, ohne Sprachmodell: Der Inhalt der belegten
12
+ * Zeilen im Bezugsstand wird mit dem letzten Commit (HEAD) verglichen.
13
+ * `git diff -U0` zwischen beiden Fassungen der Datei liefert die geänderten
14
+ * Zeilenbereiche; berührt einer davon den belegten Bereich, ist der Beleg
15
+ * geändert. Zeilen davor oder danach verschieben den Bereich nur und zählen
16
+ * nicht.
17
+ *
18
+ * Ergebnis je Beleg:
19
+ * unchanged Inhalt der belegten Zeilen gleich (auch nach Verschiebung).
20
+ * changed belegte Zeilen geändert, gelöscht oder im Bereich ergänzt.
21
+ * removed Datei gibt es in HEAD nicht mehr (und keine Umbenennung).
22
+ * unknown Bezugsstand fehlt oder liegt nicht in der Historie (flacher
23
+ * Klon). Das ist keine Drift.
24
+ *
25
+ * Umbenennung: git erkennt sie (`-M`); verglichen wird dann mit der Datei am
26
+ * neuen Ort. Eine Umbenennung allein ist keine Drift, denn die Aussage gilt dem
27
+ * Code, nicht seinem Pfad. Der Beleg trägt dann `moved_to`.
28
+ *
29
+ * Neu bestätigt: Liegt eine Prüfung der Seite (`verified.at`) nach dem letzten
30
+ * Commit, der die Datei seit dem Bezugsstand geändert hat, gilt der Beleg als
31
+ * geprüft und zählt als unverändert. Ein neuer `gitHead` verschiebt den
32
+ * Bezugsstand ohnehin.
33
+ */
34
+ import { execFileSync } from "node:child_process";
35
+
36
+ const HOECHSTZAHL_EINTRAEGE = 10;
37
+
38
+ function git(wurzel, args) {
39
+ return execFileSync("git", args, { cwd: wurzel, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
40
+ }
41
+
42
+ function versuche(fn) {
43
+ try {
44
+ return fn();
45
+ } catch {
46
+ return null;
47
+ }
48
+ }
49
+
50
+ /** Wurzel des Git-Repos, in dem `ordner` liegt, sonst null. */
51
+ export function gitWurzel(ordner) {
52
+ const out = versuche(() => git(ordner, ["rev-parse", "--show-toplevel"]));
53
+ return out ? out.trim() : null;
54
+ }
55
+
56
+ /** Liegt der Commit `ref` in der Historie? */
57
+ export function commitBekannt(wurzel, ref) {
58
+ if (!ref || !/^[0-9a-f]{4,64}$/i.test(ref)) return false;
59
+ return versuche(() => git(wurzel, ["cat-file", "-e", `${ref}^{commit}`])) !== null;
60
+ }
61
+
62
+ /** `repo://pfad#L10-L14` → { pfad, von, bis }; ohne Zeilen nur { pfad }. */
63
+ export function belegOrt(resource) {
64
+ const m = /^repo:\/\/([^#]+?)(?:#L(\d+)(?:-L(\d+))?)?$/.exec(String(resource ?? ""));
65
+ if (!m) return null;
66
+ const pfad = m[1].replace(/^\/+/, "");
67
+ if (!m[2]) return { pfad };
68
+ const von = Number(m[2]);
69
+ return { pfad, von, bis: m[3] ? Number(m[3]) : von };
70
+ }
71
+
72
+ /** Geänderte Bereiche aus `git diff -U0`: [{ alt, anzahl }] in Zeilen der alten Fassung. */
73
+ export function abschnitte(diff) {
74
+ const liste = [];
75
+ for (const z of diff.split("\n")) {
76
+ const m = /^@@ -(\d+)(?:,(\d+))? \+\d+(?:,\d+)? @@/.exec(z);
77
+ if (m) liste.push({ alt: Number(m[1]), anzahl: m[2] === undefined ? 1 : Number(m[2]) });
78
+ }
79
+ return liste;
80
+ }
81
+
82
+ /** Berührt einer der Bereiche die Zeilen von..bis der alten Fassung? */
83
+ export function bereichBeruehrt(liste, von, bis) {
84
+ return liste.some(({ alt, anzahl }) =>
85
+ anzahl > 0
86
+ ? alt <= bis && alt + anzahl - 1 >= von // ersetzt oder gelöscht
87
+ : alt >= von && alt < bis, // eingefügt nach Zeile `alt`, also innerhalb
88
+ );
89
+ }
90
+
91
+ function neuerOrt(wurzel, ref, pfad, merker) {
92
+ const kennung = `${ref}\0${pfad}`;
93
+ if (merker.has(kennung)) return merker.get(kennung);
94
+ let ort = null;
95
+ if (versuche(() => git(wurzel, ["cat-file", "-e", `HEAD:${pfad}`])) !== null) ort = pfad;
96
+ else {
97
+ const status = versuche(() => git(wurzel, ["diff", "-M", "--name-status", ref, "HEAD"])) ?? "";
98
+ for (const z of status.split("\n")) {
99
+ const [art, alt, neu] = z.split("\t");
100
+ if (art?.startsWith("R") && alt === pfad && neu) ort = neu;
101
+ }
102
+ }
103
+ merker.set(kennung, ort);
104
+ return ort;
105
+ }
106
+
107
+ function letzterCommit(wurzel, ref, pfade) {
108
+ const out = versuche(() => git(wurzel, ["log", "-1", "--format=%cI", `${ref}..HEAD`, "--", ...pfade]));
109
+ return out && out.trim() ? Date.parse(out.trim()) : null;
110
+ }
111
+
112
+ /**
113
+ * Prüft einen Beleg. `bestaetigtAm`: späteste Prüfung der Seite (ms) oder null.
114
+ * Rückgabe { status, resource, moved_to? } oder null, wenn der Beleg nicht
115
+ * auf eine Datei im Repo zeigt.
116
+ */
117
+ export function belegPruefen(wurzel, ref, beleg, { bestaetigtAm = null, merker = new Map() } = {}) {
118
+ const ort = belegOrt(beleg?.resource);
119
+ if (!ort) return null;
120
+ const typ = String(beleg?.version ?? "");
121
+ if (!typ.startsWith("repo-lines-v1:") && !typ.startsWith("repo-file-v1:")) return null;
122
+ const ergebnis = (status, extra = {}) => ({ status, resource: beleg.resource, ...extra });
123
+ if (!commitBekannt(wurzel, ref)) return ergebnis("unknown");
124
+ if (versuche(() => git(wurzel, ["cat-file", "-e", `${ref}:${ort.pfad}`])) === null) return ergebnis("unknown");
125
+
126
+ const jetzt = neuerOrt(wurzel, ref, ort.pfad, merker);
127
+ if (!jetzt) return ergebnis("removed");
128
+ const verschoben = jetzt !== ort.pfad ? { moved_to: jetzt } : {};
129
+ const diff = versuche(() => git(wurzel, ["diff", "-U0", "--no-color", `${ref}:${ort.pfad}`, `HEAD:${jetzt}`])) ?? "";
130
+ const liste = abschnitte(diff);
131
+ const betroffen = ort.von === undefined ? liste.length > 0 : bereichBeruehrt(liste, ort.von, ort.bis);
132
+ if (!betroffen) return ergebnis("unchanged", verschoben);
133
+ // Nach der letzten Änderung erneut geprüft? Dann gilt der Beleg als bestätigt.
134
+ const zuletzt = letzterCommit(wurzel, ref, [...new Set([ort.pfad, jetzt])]);
135
+ if (bestaetigtAm !== null && zuletzt !== null && bestaetigtAm >= zuletzt) {
136
+ return ergebnis("unchanged", { ...verschoben, reconfirmed: true });
137
+ }
138
+ return ergebnis("changed", verschoben);
139
+ }
140
+
141
+ /**
142
+ * Drift aller Belege einer Seite. `daten`: Inhalt von `.claims/<Seite>.json`.
143
+ * Rückgabe { ref, checked, unchanged, changed, removed, unknown, items } mit
144
+ * höchstens zehn Einträgen, die nicht unverändert sind.
145
+ */
146
+ export function seitenDrift({ wurzel, ref, daten, bestaetigtAm = null, merker = new Map() }) {
147
+ const anzahl = { unchanged: 0, changed: 0, removed: 0, unknown: 0 };
148
+ const items = [];
149
+ for (const aussage of Array.isArray(daten?.claims) ? daten.claims : []) {
150
+ for (const beleg of Array.isArray(aussage?.evidence) ? aussage.evidence : []) {
151
+ const e = belegPruefen(wurzel, ref, beleg, { bestaetigtAm, merker });
152
+ if (!e) continue;
153
+ anzahl[e.status] += 1;
154
+ if (e.status !== "unchanged" && items.length < HOECHSTZAHL_EINTRAEGE) {
155
+ items.push({ claim: aussage.id ?? null, ...e });
156
+ }
157
+ }
158
+ }
159
+ const checked = anzahl.unchanged + anzahl.changed + anzahl.removed + anzahl.unknown;
160
+ return { ref: ref ?? null, checked, ...anzahl, ...(items.length ? { items } : {}) };
161
+ }
package/src/init.js CHANGED
@@ -90,8 +90,9 @@ function agentsBlock() {
90
90
  " den du am Code prüfst, bevor du dich auf ihn stützt.",
91
91
  "- An Treffern aus Seiten im Open Knowledge Format sagt `review_flags`, ob ein",
92
92
  " Treffer veraltet (`stale`), ungeprüft (`unverified`) oder überholt",
93
- " (`superseded`) ist, auch mehreres zugleich. Eine leere Liste heißt: nichts",
94
- " davon trifft zu.",
93
+ " (`superseded`) ist oder ob der belegte Code geändert oder entfernt wurde, seit",
94
+ " die Seite geschrieben wurde (`drifted`), auch mehreres zugleich. Eine leere",
95
+ " Liste heißt: nichts davon trifft zu.",
95
96
  "- Halte Entscheidungen und Ergebnisse, die über diese Sitzung hinaus gelten, mit",
96
97
  " `knowmind_store_memory` fest. Zwischenstände und Wegwerfversuche gehören nicht",
97
98
  " hinein.",
package/src/okf.js CHANGED
@@ -117,6 +117,18 @@ export function seitenCommit(seiten, rel) {
117
117
  return null;
118
118
  }
119
119
 
120
+ /** Der dokumentierte Commit aus `.last-update.json` (OpenWiki), sonst null. */
121
+ export function letzterStandLesen(wurzel) {
122
+ const pfad = join(wurzel, ".last-update.json");
123
+ if (!existsSync(pfad)) return null;
124
+ try {
125
+ const kopf = JSON.parse(readFileSync(pfad, "utf-8"))?.gitHead;
126
+ return typeof kopf === "string" ? kopf : null;
127
+ } catch {
128
+ return null;
129
+ }
130
+ }
131
+
120
132
  /** Die Seitenliste aus `.page-manifest.json` eines OpenWiki-Verzeichnisses, sonst null. */
121
133
  export function seitenListeLesen(wurzel) {
122
134
  const pfad = join(wurzel, ".page-manifest.json");
package/src/sync.js CHANGED
@@ -16,7 +16,9 @@ import { createHash, randomUUID } from "node:crypto";
16
16
  import { uploadDocument } from "./client.js";
17
17
  import {
18
18
  RESERVIERT, buendelWurzel, kopfLesen, belegeLesen, okfAngaben, seitenCommit, seitenListeLesen,
19
+ verifiziert, letzterStandLesen,
19
20
  } from "./okf.js";
21
+ import { gitWurzel, seitenDrift } from "./belegdrift.js";
20
22
 
21
23
  const DEFAULT_EXTENSIONS = [".md", ".markdown", ".txt"];
22
24
  const MANIFEST_NAME = ".knowmind-manifest.json";
@@ -139,11 +141,32 @@ export function okfSeite(bundle, datei, inhalt) {
139
141
  if (bundle.openwiki && bundle.seiten === undefined) bundle.seiten = seitenListeLesen(bundle.wurzel);
140
142
  const commit = seitenCommit(bundle.seiten, rel);
141
143
  const angaben = okfAngaben({ kopf, inhalt, konzept, version: bundle.version, belege, commit });
144
+
145
+ // Belegdrift (0.4.2): die Belege gegen den Code im Repo rechnen, lokal mit git.
146
+ let drift = null;
147
+ if (angaben?.okf.claims && Array.isArray(belege?.daten?.claims)) {
148
+ if (bundle.git === undefined) bundle.git = gitWurzel(bundle.wurzel);
149
+ if (!bundle.git) drift = { ohneGit: true };
150
+ else {
151
+ if (bundle.letzterStand === undefined) bundle.letzterStand = letzterStandLesen(bundle.wurzel);
152
+ if (!bundle.merker) bundle.merker = new Map();
153
+ const zeiten = verifiziert(kopf?.verified).map((v) => Date.parse(v.at ?? "")).filter((t) => !Number.isNaN(t));
154
+ drift = seitenDrift({
155
+ wurzel: bundle.git,
156
+ ref: commit ?? bundle.letzterStand,
157
+ daten: belege.daten,
158
+ bestaetigtAm: zeiten.length ? Math.max(...zeiten) : null,
159
+ merker: bundle.merker,
160
+ });
161
+ if (drift.checked) angaben.okf.claims.drift = drift;
162
+ }
163
+ }
142
164
  return {
143
165
  angaben,
166
+ drift,
144
167
  titel: angaben && typeof kopf?.title === "string" && kopf.title.trim() ? kopf.title.trim() : null,
145
- // Ändern sich nur die Belege, muss die Seite trotzdem neu hinaus.
146
- belegeRoh: belege?.roh ?? "",
168
+ // Ändern sich nur die Belege oder der Code dahinter, muss die Seite trotzdem neu hinaus.
169
+ belegeRoh: (belege?.roh ?? "") + (drift?.checked ? "\0" + JSON.stringify(drift) : ""),
147
170
  };
148
171
  }
149
172
 
@@ -176,6 +199,7 @@ export async function syncDirectory(dir, options = {}) {
176
199
  let failed = 0;
177
200
  let okfSeiten = 0;
178
201
  let ausgelassen = 0;
202
+ const belegStand = { checked: 0, changed: 0, removed: 0, unknown: 0, ohneGit: false };
179
203
  const failures = [];
180
204
 
181
205
  console.log(`Knowmind sync: ${total} Dateien in ${dir}`);
@@ -193,6 +217,8 @@ export async function syncDirectory(dir, options = {}) {
193
217
  continue;
194
218
  }
195
219
  if (seite?.angaben) okfSeiten += 1;
220
+ if (seite?.drift?.ohneGit) belegStand.ohneGit = true;
221
+ else if (seite?.drift) for (const f of ["checked", "changed", "removed", "unknown"]) belegStand[f] += seite.drift[f];
196
222
  const hash = seite?.angaben ? sha256(content + "\0" + seite.belegeRoh) : sha256(content);
197
223
  const name = frontmatterName(content);
198
224
  let known = manifest.files[rel];
@@ -253,9 +279,18 @@ export async function syncDirectory(dir, options = {}) {
253
279
  if (okfSeiten || ausgelassen) {
254
280
  console.log(`OKF: ${okfSeiten} Seiten mit Herkunft und Prüfstand, ${ausgelassen} Verzeichnislisten und Verläufe ausgelassen.`);
255
281
  }
282
+ if (belegStand.checked) {
283
+ console.log(
284
+ `Belege gegen den Code: ${belegStand.checked} geprüft, ${belegStand.changed} geändert, ` +
285
+ `${belegStand.removed} mit entfernter Datei, ${belegStand.unknown} ohne bekannten Bezugsstand.`,
286
+ );
287
+ }
288
+ if (belegStand.ohneGit) {
289
+ console.log("Hinweis: Das Bündel liegt in keinem Git-Repository; die Belege wurden nicht gegen den Code geprüft.");
290
+ }
256
291
  if (failed > 0) {
257
292
  console.log(`Fehler-Übersicht (max 10):`);
258
293
  failures.slice(0, 10).forEach((f) => console.log(` ${f.file}: ${f.error}`));
259
294
  }
260
- return { uploaded, skipped, failed, failures, okfSeiten, ausgelassen };
295
+ return { uploaded, skipped, failed, failures, okfSeiten, ausgelassen, belegStand };
261
296
  }
@@ -13,7 +13,7 @@
13
13
  "idempotentHint": true,
14
14
  "openWorldHint": false
15
15
  },
16
- "description": "Retrieve relevant knowledge before answering anything that benefits from prior context - decisions, preferences, project state, people, deadlines, past conversations. Hybrid recall (BM25 + pgvector + knowledge graph) over the tenant corpus; returns the top-k memory chunks, each with a relevance score and source reference. Suitable whenever earlier context would improve the answer; use knowmind_recall_at_time when you need what was valid at a past point in time. Passages from pages in Open Knowledge Format carry metadata.review_flags: stale once stale_after is reached, unverified when no verification is recorded, superseded when the page's status is deprecated or superseded; an empty list means none applies. Read scope suffices.",
16
+ "description": "Retrieve relevant knowledge before answering anything that benefits from prior context - decisions, preferences, project state, people, deadlines, past conversations. Hybrid recall (BM25 + pgvector + knowledge graph) over the tenant corpus; returns the top-k memory chunks, each with a relevance score and source reference. Suitable whenever earlier context would improve the answer; use knowmind_recall_at_time when you need what was valid at a past point in time. Passages from pages in Open Knowledge Format carry metadata.review_flags: stale once stale_after is reached, unverified when no verification is recorded, superseded when the page's status is deprecated or superseded or its valid_to is reached, drifted when code cited by the page's claims changed or was removed since the page was written; an empty list means none applies. Read scope suffices.",
17
17
  "inputSchema": {
18
18
  "type": "object",
19
19
  "properties": {
@@ -290,7 +290,7 @@
290
290
  "idempotentHint": true,
291
291
  "openWorldHint": false
292
292
  },
293
- "description": "Time-travel recall: return only memories that were valid at a given instant (valid_from <= as_of <= valid_to, or still open). Answers 'what did the agent know on March 14?'. Use instead of knowmind_recall when the point in time matters; otherwise use knowmind_recall for the current truth. Passages from pages in Open Knowledge Format carry metadata.review_flags (stale, unverified, superseded); stale is judged against as_of. Read scope suffices.",
293
+ "description": "Time-travel recall: return only memories that were valid at a given instant (valid_from <= as_of <= valid_to, or still open). Answers 'what did the agent know on March 14?'. Use instead of knowmind_recall when the point in time matters; otherwise use knowmind_recall for the current truth. Passages from pages in Open Knowledge Format carry metadata.review_flags (stale, unverified, superseded, drifted); stale and superseded are judged against as_of. Read scope suffices.",
294
294
  "inputSchema": {
295
295
  "type": "object",
296
296
  "properties": {
@@ -551,7 +551,7 @@
551
551
  "idempotentHint": true,
552
552
  "openWorldHint": false
553
553
  },
554
- "description": "DEPRECATED, removed on 2027-03-31: use knowmind_recall_memories. This name keeps answering unchanged until then. Retrieve relevant knowledge before answering anything that benefits from prior context - decisions, preferences, project state, people, deadlines, past conversations. Hybrid recall (BM25 + pgvector + knowledge graph) over the tenant corpus; returns the top-k memory chunks, each with a relevance score and source reference. Suitable whenever earlier context would improve the answer; use knowmind_recall_at_time when you need what was valid at a past point in time. Passages from pages in Open Knowledge Format carry metadata.review_flags: stale once stale_after is reached, unverified when no verification is recorded, superseded when the page's status is deprecated or superseded; an empty list means none applies. Read scope suffices.",
554
+ "description": "DEPRECATED, removed on 2027-03-31: use knowmind_recall_memories. This name keeps answering unchanged until then. Retrieve relevant knowledge before answering anything that benefits from prior context - decisions, preferences, project state, people, deadlines, past conversations. Hybrid recall (BM25 + pgvector + knowledge graph) over the tenant corpus; returns the top-k memory chunks, each with a relevance score and source reference. Suitable whenever earlier context would improve the answer; use knowmind_recall_at_time when you need what was valid at a past point in time. Passages from pages in Open Knowledge Format carry metadata.review_flags: stale once stale_after is reached, unverified when no verification is recorded, superseded when the page's status is deprecated or superseded or its valid_to is reached, drifted when code cited by the page's claims changed or was removed since the page was written; an empty list means none applies. Read scope suffices.",
555
555
  "inputSchema": {
556
556
  "type": "object",
557
557
  "properties": {