agent-knowledge 1.7.3 → 1.8.1

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.
Files changed (66) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/.mcp.json +1 -1
  3. package/CHANGELOG.md +101 -0
  4. package/README.md +43 -18
  5. package/agent-desk-plugin.json +1 -1
  6. package/dist/dashboard.d.ts.map +1 -1
  7. package/dist/dashboard.js +28 -1
  8. package/dist/dashboard.js.map +1 -1
  9. package/dist/knowledge/analyze.d.ts +18 -0
  10. package/dist/knowledge/analyze.d.ts.map +1 -1
  11. package/dist/knowledge/analyze.js +22 -0
  12. package/dist/knowledge/analyze.js.map +1 -1
  13. package/dist/knowledge/freshness.d.ts +99 -0
  14. package/dist/knowledge/freshness.d.ts.map +1 -0
  15. package/dist/knowledge/freshness.js +303 -0
  16. package/dist/knowledge/freshness.js.map +1 -0
  17. package/dist/knowledge/promote.d.ts +145 -0
  18. package/dist/knowledge/promote.d.ts.map +1 -0
  19. package/dist/knowledge/promote.js +532 -0
  20. package/dist/knowledge/promote.js.map +1 -0
  21. package/dist/knowledge/query-log.d.ts +88 -0
  22. package/dist/knowledge/query-log.d.ts.map +1 -0
  23. package/dist/knowledge/query-log.js +207 -0
  24. package/dist/knowledge/query-log.js.map +1 -0
  25. package/dist/knowledge/scoring.d.ts +22 -2
  26. package/dist/knowledge/scoring.d.ts.map +1 -1
  27. package/dist/knowledge/scoring.js +51 -3
  28. package/dist/knowledge/scoring.js.map +1 -1
  29. package/dist/knowledge/search.d.ts +56 -5
  30. package/dist/knowledge/search.d.ts.map +1 -1
  31. package/dist/knowledge/search.js +88 -10
  32. package/dist/knowledge/search.js.map +1 -1
  33. package/dist/knowledge/store.d.ts +12 -0
  34. package/dist/knowledge/store.d.ts.map +1 -1
  35. package/dist/knowledge/store.js +18 -0
  36. package/dist/knowledge/store.js.map +1 -1
  37. package/dist/search/mmr.d.ts +54 -0
  38. package/dist/search/mmr.d.ts.map +1 -0
  39. package/dist/search/mmr.js +138 -0
  40. package/dist/search/mmr.js.map +1 -0
  41. package/dist/server.d.ts +334 -0
  42. package/dist/server.d.ts.map +1 -1
  43. package/dist/server.js +378 -301
  44. package/dist/server.js.map +1 -1
  45. package/dist/sessions/indexer.d.ts.map +1 -1
  46. package/dist/sessions/indexer.js +13 -11
  47. package/dist/sessions/indexer.js.map +1 -1
  48. package/dist/tool-handlers.d.ts +10 -3
  49. package/dist/tool-handlers.d.ts.map +1 -1
  50. package/dist/tool-handlers.js +150 -21
  51. package/dist/tool-handlers.js.map +1 -1
  52. package/dist/ui/app.js +271 -1
  53. package/dist/ui/render-knowledge.js +3 -3
  54. package/dist/ui/styles.css +209 -0
  55. package/dist/wakeup.d.ts +59 -14
  56. package/dist/wakeup.d.ts.map +1 -1
  57. package/dist/wakeup.js +406 -43
  58. package/dist/wakeup.js.map +1 -1
  59. package/docs/ARCHITECTURE.md +31 -6
  60. package/docs/SETUP.md +20 -8
  61. package/docs/USER-MANUAL.md +205 -59
  62. package/docs/hooks.md +81 -21
  63. package/package.json +4 -1
  64. package/scripts/hooks/first-prompt-inject.mjs +230 -0
  65. package/scripts/hooks/precompact-flush.mjs +89 -60
  66. package/scripts/hooks/session-start.js +73 -9
@@ -0,0 +1,207 @@
1
+ /**
2
+ * Query log — records every `knowledge_search` call so we can surface
3
+ * zero-result queries as "gap" signals. The single best hint for "what
4
+ * knowledge entries are missing?" is the set of things the agent keeps
5
+ * searching for and not finding.
6
+ *
7
+ * Storage: a `query_log` table inside the existing `knowledge-scores.db`
8
+ * SQLite database (same DB path pattern as `EntryScoring`).
9
+ */
10
+ import { join, dirname } from 'path';
11
+ import { mkdirSync } from 'fs';
12
+ import { createRequire } from 'module';
13
+ import { getConfig } from '../types.js';
14
+ import { scrubContent } from './distill.js';
15
+ import { jaccardTokenSim } from '../search/mmr.js';
16
+ const require = createRequire(import.meta.url);
17
+ /**
18
+ * SQLite-backed query log. Tracks `{query, project, results_count,
19
+ * created_at}` for every `knowledge_search` call and exposes a grouped
20
+ * view of zero-result queries.
21
+ */
22
+ export class QueryLog {
23
+ db = null;
24
+ dbPath;
25
+ initialized = false;
26
+ constructor(dbPath) {
27
+ // Share the lightweight scoring DB — same path pattern as EntryScoring.
28
+ this.dbPath = dbPath ?? join(getConfig().dataDir, 'knowledge-scores.db');
29
+ }
30
+ init() {
31
+ if (this.initialized)
32
+ return;
33
+ try {
34
+ if (!this.db) {
35
+ mkdirSync(dirname(this.dbPath), { recursive: true });
36
+ const BetterSqlite3 = require('better-sqlite3');
37
+ this.db = new BetterSqlite3(this.dbPath);
38
+ this.db.pragma('journal_mode = WAL');
39
+ this.db.pragma('foreign_keys = ON');
40
+ }
41
+ this.db.exec(`
42
+ CREATE TABLE IF NOT EXISTS query_log (
43
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
44
+ query TEXT NOT NULL,
45
+ project TEXT,
46
+ results_count INTEGER NOT NULL,
47
+ created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
48
+ );
49
+ CREATE INDEX IF NOT EXISTS idx_query_log_results_created
50
+ ON query_log(results_count, created_at);
51
+ `);
52
+ this.initialized = true;
53
+ }
54
+ catch (err) {
55
+ console.error(`[knowledge] Failed to initialize query log: ${err}`);
56
+ throw err;
57
+ }
58
+ }
59
+ /**
60
+ * Insert a single query entry. The query string is scrubbed via
61
+ * `scrubContent` BEFORE insertion to keep secrets out of the log.
62
+ */
63
+ logQuery(args) {
64
+ this.init();
65
+ if (!this.db)
66
+ throw new Error('Query log database not available');
67
+ const scrubbed = scrubContent(args.query);
68
+ const project = args.project ?? null;
69
+ // Store an explicit ISO-8601 UTC timestamp. SQLite's CURRENT_TIMESTAMP
70
+ // emits `YYYY-MM-DD HH:MM:SS` (no `T`, no `Z`) which doesn't compare
71
+ // lexicographically against JS `toISOString()` strings — passing the
72
+ // timestamp explicitly keeps `since` window queries correct.
73
+ const now = new Date().toISOString();
74
+ this.db
75
+ .prepare(`INSERT INTO query_log (query, project, results_count, created_at)
76
+ VALUES (?, ?, ?, ?)`)
77
+ .run(scrubbed, project, args.resultsCount, now);
78
+ }
79
+ /**
80
+ * Return zero-result queries grouped by similarity.
81
+ *
82
+ * Rows are considered zero-result when `results_count == 0`. Groups are
83
+ * formed greedily — iterate rows ordered by most-recent first, and merge
84
+ * into an existing group when `jaccardTokenSim(query, representative) >
85
+ * threshold`.
86
+ *
87
+ * Each returned group carries:
88
+ * - `query`: the most-recent query text in the group
89
+ * - `count`: total number of rows collapsed into the group
90
+ * - `last_seen`: ISO timestamp of the most-recent row
91
+ * - `similar_queries`: other query texts in the group (may be empty)
92
+ */
93
+ getSearchGaps(args = {}) {
94
+ this.init();
95
+ if (!this.db)
96
+ throw new Error('Query log database not available');
97
+ const since = args.since;
98
+ const minCount = args.minCount ?? 1;
99
+ const threshold = args.groupSimilarity ?? 0.35;
100
+ const rows = since
101
+ ? this.db
102
+ .prepare(`SELECT query, created_at FROM query_log
103
+ WHERE results_count = 0 AND created_at >= ?
104
+ ORDER BY created_at DESC`)
105
+ .all(since)
106
+ : this.db
107
+ .prepare(`SELECT query, created_at FROM query_log
108
+ WHERE results_count = 0
109
+ ORDER BY created_at DESC`)
110
+ .all();
111
+ const groups = [];
112
+ for (const row of rows) {
113
+ let merged = false;
114
+ for (const g of groups) {
115
+ if (jaccardTokenSim(row.query, g.representative) >= threshold) {
116
+ g.members.push(row.query);
117
+ // `rows` is ordered DESC by created_at, so the first row to land
118
+ // in a group is the most recent — don't overwrite `last_seen`.
119
+ merged = true;
120
+ break;
121
+ }
122
+ }
123
+ if (!merged) {
124
+ groups.push({
125
+ representative: row.query,
126
+ last_seen: row.created_at,
127
+ members: [row.query],
128
+ });
129
+ }
130
+ }
131
+ const result = [];
132
+ for (const g of groups) {
133
+ if (g.members.length < minCount)
134
+ continue;
135
+ const similar = g.members
136
+ .slice(1)
137
+ .filter((q) => q !== g.representative)
138
+ // de-duplicate
139
+ .filter((q, i, arr) => arr.indexOf(q) === i);
140
+ const gap = {
141
+ query: g.representative,
142
+ count: g.members.length,
143
+ last_seen: g.last_seen,
144
+ };
145
+ if (similar.length > 0)
146
+ gap.similar_queries = similar;
147
+ result.push(gap);
148
+ }
149
+ // Sort: highest count first, then most recent.
150
+ result.sort((a, b) => {
151
+ if (b.count !== a.count)
152
+ return b.count - a.count;
153
+ return b.last_seen.localeCompare(a.last_seen);
154
+ });
155
+ return result;
156
+ }
157
+ /** Close the database connection. */
158
+ close() {
159
+ try {
160
+ this.db?.close();
161
+ }
162
+ catch (err) {
163
+ console.error(`[knowledge] Failed to close query log DB: ${err}`);
164
+ }
165
+ finally {
166
+ this.db = null;
167
+ this.initialized = false;
168
+ }
169
+ }
170
+ }
171
+ // ── Singleton instance ───────────────────────────────────────────────────────
172
+ let _queryLogInstance = null;
173
+ export function getQueryLog(dbPath) {
174
+ if (!_queryLogInstance) {
175
+ _queryLogInstance = new QueryLog(dbPath);
176
+ }
177
+ return _queryLogInstance;
178
+ }
179
+ /** Reset the singleton (for tests). */
180
+ export function resetQueryLog() {
181
+ if (_queryLogInstance) {
182
+ try {
183
+ _queryLogInstance.close();
184
+ }
185
+ catch {
186
+ /* ignore */
187
+ }
188
+ _queryLogInstance = null;
189
+ }
190
+ }
191
+ /**
192
+ * Best-effort logging. A log failure must never fail the caller; errors
193
+ * are swallowed and written to stderr.
194
+ */
195
+ export function logQuery(args) {
196
+ try {
197
+ getQueryLog().logQuery(args);
198
+ }
199
+ catch (err) {
200
+ console.error('[knowledge] logQuery failed:', err instanceof Error ? err.message : err);
201
+ }
202
+ }
203
+ /** Thin wrapper around the singleton. */
204
+ export function getSearchGaps(args = {}) {
205
+ return getQueryLog().getSearchGaps(args);
206
+ }
207
+ //# sourceMappingURL=query-log.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"query-log.js","sourceRoot":"","sources":["../../src/knowledge/query-log.ts"],"names":[],"mappings":"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"}
@@ -9,6 +9,12 @@ export interface EntryScore {
9
9
  last_accessed: string;
10
10
  maturity: Maturity;
11
11
  created_at: string;
12
+ /**
13
+ * ISO timestamp when the agent explicitly confirmed the entry is still
14
+ * accurate via `knowledge(action: "verify")`. Distinct from `last_accessed`:
15
+ * reads happen incidentally, verification is deliberate.
16
+ */
17
+ verified_at?: string | null;
12
18
  }
13
19
  /**
14
20
  * Compute decay factor based on days since last access.
@@ -20,9 +26,13 @@ export declare function decayFactor(lastAccessed: string): number;
20
26
  */
21
27
  export declare function maturityMultiplier(maturity: Maturity): number;
22
28
  /**
23
- * Compute final score: baseRelevance * decayFactor * maturityMultiplier
29
+ * Compute final score: baseRelevance * decayFactor * maturityMultiplier * confidence
30
+ *
31
+ * Evergreen entries (frontmatter `evergreen: true`) skip the decay factor.
32
+ * Decisions, architecture, and identity entries should carry the flag so
33
+ * their ranking isn't punished by calendar time.
24
34
  */
25
- export declare function computeFinalScore(baseRelevance: number, lastAccessed: string | null, maturity: Maturity, confidence?: string): number;
35
+ export declare function computeFinalScore(baseRelevance: number, lastAccessed: string | null, maturity: Maturity, confidence?: string, evergreen?: boolean): number;
26
36
  /**
27
37
  * Entry scoring backed by SQLite.
28
38
  * Tracks access counts, last-accessed timestamps, and maturity levels.
@@ -33,6 +43,16 @@ export declare class EntryScoring {
33
43
  private initialized;
34
44
  constructor(dbPath?: string);
35
45
  private init;
46
+ /**
47
+ * Stamp an entry as "freshly verified" — the agent has just confirmed its
48
+ * content is still accurate. Creates the entry_scores row if absent.
49
+ * Returns the updated row so the caller can surface the timestamp.
50
+ */
51
+ markVerified(entryPath: string, whenIso?: string): EntryScore;
52
+ /**
53
+ * Days since the entry was last verified. `null` if never verified.
54
+ */
55
+ verificationAgeDays(entryPath: string, nowMs?: number): number | null;
36
56
  /**
37
57
  * Record an access to an entry. Increments access_count, updates
38
58
  * last_accessed, and checks for auto-promotion.
@@ -1 +1 @@
1
- {"version":3,"file":"scoring.d.ts","sourceRoot":"","sources":["../../src/knowledge/scoring.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAYH,MAAM,MAAM,QAAQ,GAAG,WAAW,GAAG,aAAa,GAAG,QAAQ,CAAC;AAE9D,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,QAAQ,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAaD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAMxD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAE7D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,QAAQ,EAAE,QAAQ,EAClB,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAKR;AAED;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAS;gBAEhB,MAAM,CAAC,EAAE,MAAM;IAK3B,OAAO,CAAC,IAAI;IA6BZ;;;OAGG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU;IAiC3C;;OAEG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI;IAsC5C;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAW9C;;OAEG;IACH,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC;IAiBxD,qCAAqC;IACrC,KAAK,IAAI,IAAI;CAUd;AAMD,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAK7D;AAED,uCAAuC;AACvC,wBAAgB,iBAAiB,IAAI,IAAI,CASxC"}
1
+ {"version":3,"file":"scoring.d.ts","sourceRoot":"","sources":["../../src/knowledge/scoring.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAYH,MAAM,MAAM,QAAQ,GAAG,WAAW,GAAG,aAAa,GAAG,QAAQ,CAAC;AAE9D,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,QAAQ,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAaD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAMxD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAE7D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,QAAQ,EAAE,QAAQ,EAClB,UAAU,CAAC,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,OAAO,GAClB,MAAM,CAKR;AAED;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAS;gBAEhB,MAAM,CAAC,EAAE,MAAM;IAK3B,OAAO,CAAC,IAAI;IAuCZ;;;;OAIG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,UAAU;IAiB7D;;OAEG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAYrE;;;OAGG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU;IAiC3C;;OAEG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI;IAsC5C;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAW9C;;OAEG;IACH,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC;IAiBxD,qCAAqC;IACrC,KAAK,IAAI,IAAI;CAUd;AAMD,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAK7D;AAED,uCAAuC;AACvC,wBAAgB,iBAAiB,IAAI,IAAI,CASxC"}
@@ -35,10 +35,14 @@ export function maturityMultiplier(maturity) {
35
35
  return MATURITY_MULTIPLIERS[maturity] ?? 0.5;
36
36
  }
37
37
  /**
38
- * Compute final score: baseRelevance * decayFactor * maturityMultiplier
38
+ * Compute final score: baseRelevance * decayFactor * maturityMultiplier * confidence
39
+ *
40
+ * Evergreen entries (frontmatter `evergreen: true`) skip the decay factor.
41
+ * Decisions, architecture, and identity entries should carry the flag so
42
+ * their ranking isn't punished by calendar time.
39
43
  */
40
- export function computeFinalScore(baseRelevance, lastAccessed, maturity, confidence) {
41
- const decay = lastAccessed ? decayFactor(lastAccessed) : 1;
44
+ export function computeFinalScore(baseRelevance, lastAccessed, maturity, confidence, evergreen) {
45
+ const decay = evergreen ? 1 : lastAccessed ? decayFactor(lastAccessed) : 1;
42
46
  const multiplier = maturityMultiplier(maturity);
43
47
  const confidenceFactor = confidence === 'inferred' ? 0.85 : 1.0;
44
48
  return baseRelevance * decay * multiplier * confidenceFactor;
@@ -75,6 +79,13 @@ export class EntryScoring {
75
79
  created_at TEXT DEFAULT CURRENT_TIMESTAMP
76
80
  );
77
81
  `);
82
+ // v1.8.1 migration: add `verified_at` column if absent. Non-destructive —
83
+ // existing rows get NULL which means "never verified" and is handled
84
+ // explicitly by the scoring helpers.
85
+ const cols = this.db.prepare(`PRAGMA table_info(entry_scores)`).all();
86
+ if (!cols.some((c) => c.name === 'verified_at')) {
87
+ this.db.exec(`ALTER TABLE entry_scores ADD COLUMN verified_at TEXT;`);
88
+ }
78
89
  this.initialized = true;
79
90
  }
80
91
  catch (err) {
@@ -82,6 +93,43 @@ export class EntryScoring {
82
93
  throw err;
83
94
  }
84
95
  }
96
+ /**
97
+ * Stamp an entry as "freshly verified" — the agent has just confirmed its
98
+ * content is still accurate. Creates the entry_scores row if absent.
99
+ * Returns the updated row so the caller can surface the timestamp.
100
+ */
101
+ markVerified(entryPath, whenIso) {
102
+ this.init();
103
+ if (!this.db)
104
+ throw new Error('Scoring database not available');
105
+ const when = whenIso ?? new Date().toISOString();
106
+ this.db
107
+ .prepare(`INSERT INTO entry_scores (entry_path, access_count, last_accessed, maturity, verified_at)
108
+ VALUES (?, 0, NULL, 'candidate', ?)
109
+ ON CONFLICT(entry_path)
110
+ DO UPDATE SET verified_at = excluded.verified_at`)
111
+ .run(entryPath, when);
112
+ return this.db
113
+ .prepare('SELECT * FROM entry_scores WHERE entry_path = ?')
114
+ .get(entryPath);
115
+ }
116
+ /**
117
+ * Days since the entry was last verified. `null` if never verified.
118
+ */
119
+ verificationAgeDays(entryPath, nowMs) {
120
+ this.init();
121
+ if (!this.db)
122
+ return null;
123
+ const row = this.db
124
+ .prepare('SELECT verified_at FROM entry_scores WHERE entry_path = ?')
125
+ .get(entryPath);
126
+ if (!row || !row.verified_at)
127
+ return null;
128
+ const t = new Date(row.verified_at).getTime();
129
+ if (!Number.isFinite(t))
130
+ return null;
131
+ return Math.max(0, ((nowMs ?? Date.now()) - t) / (24 * 3600_000));
132
+ }
85
133
  /**
86
134
  * Record an access to an entry. Increments access_count, updates
87
135
  * last_accessed, and checks for auto-promotion.
@@ -1 +1 @@
1
- {"version":3,"file":"scoring.js","sourceRoot":"","sources":["../../src/knowledge/scoring.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"scoring.js","sourceRoot":"","sources":["../../src/knowledge/scoring.ts"],"names":[],"mappings":"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"}
@@ -5,21 +5,66 @@ export interface SearchOptions {
5
5
  caseSensitive?: boolean;
6
6
  /**
7
7
  * How to use `category`:
8
- * - 'filter' (default, current behavior): only entries in `category` are indexed.
9
- * - 'boost': all entries are indexed; matching-category entries get a score multiplier.
8
+ * - 'filter': only entries in `category` are indexed — silently drops
9
+ * everything else.
10
+ * - 'boost' (DEFAULT): all entries are indexed; matching-category entries
11
+ * get a score multiplier. Prevents the "zero results because the
12
+ * category guess was wrong" failure mode.
10
13
  *
11
- * Hard filters silently discard the right evidence when the metadata
12
- * doesn't match the answer's location. The boost path keeps the candidate
13
- * in the pool while still favoring the matching category.
14
+ * NOTE: The default flipped from 'filter' to 'boost' in v1.8.0 as part of
15
+ * the agent-UX pass. Pass 'filter' explicitly for the legacy hard-filter
16
+ * behavior.
14
17
  */
15
18
  categoryMode?: 'filter' | 'boost';
19
+ /** Apply MMR diversification to the result list. Default: false. */
20
+ mmr?: boolean;
21
+ /** MMR relevance-vs-diversity tradeoff 0-1. Default: 0.7. */
22
+ mmrLambda?: number;
23
+ /** When true, each result carries a `score_components` breakdown. */
24
+ explain?: boolean;
16
25
  }
17
26
  /** Score multiplier applied to entries whose category matches in 'boost' mode. */
18
27
  export declare const CATEGORY_BOOST_MULTIPLIER = 1.25;
28
+ /** Default MMR tradeoff when the caller passes `mmr: true` without `mmrLambda`. */
29
+ export declare const DEFAULT_MMR_LAMBDA = 0.7;
30
+ export interface ScoreComponents {
31
+ bm25: number;
32
+ decay: number;
33
+ maturity: number;
34
+ confidence: number;
35
+ category_boost: number;
36
+ mmr_penalty: number;
37
+ }
38
+ /**
39
+ * Freshness + trust metadata attached to every knowledge hit (v1.8.1).
40
+ *
41
+ * These are automatic signals — no agent action required. The agent can read
42
+ * them to form a trust judgment ("body last edited 120 days ago, still being
43
+ * accessed 8x/week → probably out of date") without us imposing policy via
44
+ * demotion or flags.
45
+ */
46
+ export interface FreshnessMeta {
47
+ /** Days since the underlying markdown file was last modified on disk. */
48
+ body_age_days: number | null;
49
+ /** ISO timestamp of the most recent read via knowledge(action:"read"). */
50
+ last_accessed: string | null;
51
+ /** Number of recorded reads. */
52
+ access_count: number;
53
+ /** ISO timestamp of the last promoter auto-verify (or future explicit verify). */
54
+ verified_at: string | null;
55
+ /** Days since last verified, null if never verified. */
56
+ verification_age_days: number | null;
57
+ /** Evergreen entries are exempt from decay-based demotion; surfaced here for UI. */
58
+ evergreen: boolean;
59
+ }
19
60
  export interface SearchResult {
20
61
  entry: KnowledgeEntry;
21
62
  score: number;
22
63
  excerpt: string;
64
+ /** Populated only when the caller passes `explain: true`. */
65
+ score_components?: ScoreComponents;
66
+ /** Automatic freshness + trust signal — present on every hit. */
67
+ freshness?: FreshnessMeta;
23
68
  }
24
69
  /** Invalidate the knowledge TF-IDF index cache (call on write/delete). */
25
70
  export declare function invalidateKnowledgeIndexCache(): void;
@@ -29,6 +74,12 @@ export declare function invalidateKnowledgeIndexCache(): void;
29
74
  * Uses a cached TF-IDF index (60s TTL, invalidated on write/delete) to
30
75
  * avoid rebuilding the index on every search. Falls back to regex search
31
76
  * if TF-IDF returns no results (useful for exact phrase matches).
77
+ *
78
+ * Scoring:
79
+ * score = bm25 * decay(last_accessed) * maturity(level) * confidence * category_boost
80
+ *
81
+ * When `mmr` is true, the TF-IDF top-K is re-ranked with Maximal Marginal
82
+ * Relevance on token-Jaccard similarity — see search/mmr.ts.
32
83
  */
33
84
  export declare function searchKnowledge(dir: string, query: string, options?: SearchOptions): Array<SearchResult>;
34
85
  //# sourceMappingURL=search.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/knowledge/search.ts"],"names":[],"mappings":"AAGA,OAAO,EAA0B,cAAc,EAAE,MAAM,YAAY,CAAC;AAEpE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;CACnC;AAED,kFAAkF;AAClF,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,cAAc,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAeD,0EAA0E;AAC1E,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD;AAsCD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,aAAkB,GAC1B,KAAK,CAAC,YAAY,CAAC,CA4ErB"}
1
+ {"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/knowledge/search.ts"],"names":[],"mappings":"AAKA,OAAO,EAA0B,cAAc,EAAE,MAAM,YAAY,CAAC;AAGpE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAClC,oEAAoE;IACpE,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,kFAAkF;AAClF,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C,mFAAmF;AACnF,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,yEAAyE;IACzE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,0EAA0E;IAC1E,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,gCAAgC;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,wDAAwD;IACxD,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,oFAAoF;IACpF,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,cAAc,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,eAAe,CAAC;IACnC,iEAAiE;IACjE,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B;AAeD,0EAA0E;AAC1E,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD;AAsCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,aAAkB,GAC1B,KAAK,CAAC,YAAY,CAAC,CAiKrB"}
@@ -1,9 +1,14 @@
1
+ import fs from 'fs';
2
+ import path from 'path';
1
3
  import { BM25Index } from '../search/bm25.js';
2
- import { getEntryScoring, computeFinalScore } from './scoring.js';
4
+ import { getEntryScoring, computeFinalScore, decayFactor, maturityMultiplier } from './scoring.js';
3
5
  import { buildExcerpt } from '../search/excerpt.js';
4
6
  import { listEntries, readEntry } from './store.js';
7
+ import { rerankMMR, jaccardTokenSim } from '../search/mmr.js';
5
8
  /** Score multiplier applied to entries whose category matches in 'boost' mode. */
6
9
  export const CATEGORY_BOOST_MULTIPLIER = 1.25;
10
+ /** Default MMR tradeoff when the caller passes `mmr: true` without `mmrLambda`. */
11
+ export const DEFAULT_MMR_LAMBDA = 0.7;
7
12
  let _knowledgeIndexCache = null;
8
13
  const KNOWLEDGE_INDEX_TTL = 60_000; // 60 seconds, matching session search cache
9
14
  /** Invalidate the knowledge TF-IDF index cache (call on write/delete). */
@@ -42,17 +47,26 @@ function getOrBuildKnowledgeIndex(dir, category) {
42
47
  * Uses a cached TF-IDF index (60s TTL, invalidated on write/delete) to
43
48
  * avoid rebuilding the index on every search. Falls back to regex search
44
49
  * if TF-IDF returns no results (useful for exact phrase matches).
50
+ *
51
+ * Scoring:
52
+ * score = bm25 * decay(last_accessed) * maturity(level) * confidence * category_boost
53
+ *
54
+ * When `mmr` is true, the TF-IDF top-K is re-ranked with Maximal Marginal
55
+ * Relevance on token-Jaccard similarity — see search/mmr.ts.
45
56
  */
46
57
  export function searchKnowledge(dir, query, options = {}) {
47
- const { category, maxResults = 10, caseSensitive = false, categoryMode = 'filter' } = options;
58
+ const { category, maxResults = 10, caseSensitive = false, categoryMode = 'boost', mmr = false, mmrLambda = DEFAULT_MMR_LAMBDA, explain = false, } = options;
48
59
  // In 'boost' mode, build the index over the full corpus (no category restriction).
49
- // In 'filter' mode (default), keep current behavior of restricting the index to one category.
60
+ // In 'filter' mode, keep legacy behavior of restricting the index to one category.
50
61
  const indexCategory = categoryMode === 'boost' ? undefined : category;
51
62
  const { index, documents } = getOrBuildKnowledgeIndex(dir, indexCategory);
52
63
  if (documents.length === 0)
53
64
  return [];
65
+ // Fetch a wider candidate pool when MMR is enabled so diversification has
66
+ // room to operate. Cap at 3× maxResults to avoid pathological long tails.
67
+ const candidatePool = mmr ? Math.min(maxResults * 3, documents.length) : maxResults;
54
68
  // Search using TF-IDF
55
- const tfidfResults = index.search(query, maxResults);
69
+ const tfidfResults = index.search(query, candidatePool);
56
70
  if (tfidfResults.length > 0) {
57
71
  const results = [];
58
72
  const scoring = getEntryScoring();
@@ -68,22 +82,86 @@ export function searchKnowledge(dir, query, options = {}) {
68
82
  const maturity = (scoreInfo?.maturity ?? 'candidate');
69
83
  const lastAccessed = scoreInfo?.last_accessed ?? null;
70
84
  const confidence = doc.entry.confidence;
71
- let finalScore = computeFinalScore(result.score, lastAccessed, maturity, confidence);
85
+ const evergreen = doc.entry.evergreen === true;
86
+ let finalScore = computeFinalScore(result.score, lastAccessed, maturity, confidence, evergreen);
72
87
  // Category boost: in 'boost' mode, give matching-category entries an
73
88
  // edge instead of dropping non-matching entries.
89
+ let categoryBoost = 1;
74
90
  if (categoryMode === 'boost' && category && doc.entry.category === category) {
75
- finalScore *= CATEGORY_BOOST_MULTIPLIER;
91
+ categoryBoost = CATEGORY_BOOST_MULTIPLIER;
92
+ finalScore *= categoryBoost;
93
+ }
94
+ const components = explain
95
+ ? {
96
+ bm25: result.score,
97
+ decay: evergreen ? 1 : lastAccessed ? decayFactor(lastAccessed) : 1,
98
+ maturity: maturityMultiplier(maturity),
99
+ confidence: confidence === 'inferred' ? 0.85 : 1,
100
+ category_boost: categoryBoost,
101
+ mmr_penalty: 1, // updated below if MMR runs
102
+ }
103
+ : undefined;
104
+ // v1.8.1: automatic freshness metadata per hit — surface the trust
105
+ // signals the agent needs to judge whether this entry is still current,
106
+ // without requiring any agent-proactive call. Cheap: scoring row is
107
+ // already loaded above; body mtime is a single fs.statSync. We tolerate
108
+ // stat errors gracefully and emit `null` age.
109
+ let bodyAgeDays = null;
110
+ try {
111
+ const full = path.join(dir, doc.entry.path);
112
+ const stat = fs.statSync(full);
113
+ bodyAgeDays = Math.round(((Date.now() - stat.mtimeMs) / (24 * 3600_000)) * 10) / 10;
114
+ }
115
+ catch {
116
+ /* ignore — file may have been moved */
76
117
  }
77
- results.push({
118
+ const verifiedAt = scoreInfo?.verified_at ?? null;
119
+ const freshness = {
120
+ body_age_days: bodyAgeDays,
121
+ last_accessed: lastAccessed,
122
+ access_count: scoreInfo?.access_count ?? 0,
123
+ verified_at: verifiedAt,
124
+ verification_age_days: verifiedAt
125
+ ? Math.round(((Date.now() - new Date(verifiedAt).getTime()) / (24 * 3600_000)) * 10) / 10
126
+ : null,
127
+ evergreen,
128
+ };
129
+ const res = {
78
130
  entry: doc.entry,
79
131
  score: finalScore,
80
132
  excerpt: buildExcerpt(doc.content, query, { caseSensitive, contextAfter: 200 }),
81
- });
133
+ freshness,
134
+ };
135
+ if (components)
136
+ res.score_components = components;
137
+ results.push(res);
82
138
  }
83
- // Filter out negative scores and re-sort by final score
139
+ // Filter out negative scores and sort by final score
84
140
  const filtered = results.filter((r) => r.score > 0);
85
141
  filtered.sort((a, b) => b.score - a.score);
86
- return filtered;
142
+ // Optional MMR re-ranking — diversifies the top-K at a small relevance cost.
143
+ if (mmr && filtered.length > 1) {
144
+ const reranked = rerankMMR(filtered, {
145
+ k: maxResults,
146
+ lambda: mmrLambda,
147
+ relevance: (r) => r.score,
148
+ sim: (a, b) => jaccardTokenSim(a.entry.content ?? a.excerpt ?? '', b.entry.content ?? b.excerpt ?? ''),
149
+ });
150
+ if (explain) {
151
+ // Track where each item came from for the mmr_penalty component.
152
+ // Items picked first get penalty=1 (no penalty); later picks get
153
+ // a smaller value reflecting diversity cost.
154
+ const originalRank = new Map(filtered.map((r, idx) => [r.entry.path, idx + 1]));
155
+ reranked.forEach((r, newIdx) => {
156
+ const orig = originalRank.get(r.entry.path) ?? newIdx + 1;
157
+ if (r.score_components) {
158
+ r.score_components.mmr_penalty = newIdx === 0 ? 1 : Math.min(1, orig / (newIdx + 1));
159
+ }
160
+ });
161
+ }
162
+ return reranked;
163
+ }
164
+ return filtered.slice(0, maxResults);
87
165
  }
88
166
  // Fallback: regex search for exact phrase matches
89
167
  const flags = caseSensitive ? 'g' : 'gi';
@@ -1 +1 @@
1
- {"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/knowledge/search.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/knowledge/search.ts"],"names":[],"mappings":"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"}