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.
- package/.claude-plugin/plugin.json +1 -1
- package/.mcp.json +1 -1
- package/CHANGELOG.md +101 -0
- package/README.md +43 -18
- package/agent-desk-plugin.json +1 -1
- package/dist/dashboard.d.ts.map +1 -1
- package/dist/dashboard.js +28 -1
- package/dist/dashboard.js.map +1 -1
- package/dist/knowledge/analyze.d.ts +18 -0
- package/dist/knowledge/analyze.d.ts.map +1 -1
- package/dist/knowledge/analyze.js +22 -0
- package/dist/knowledge/analyze.js.map +1 -1
- package/dist/knowledge/freshness.d.ts +99 -0
- package/dist/knowledge/freshness.d.ts.map +1 -0
- package/dist/knowledge/freshness.js +303 -0
- package/dist/knowledge/freshness.js.map +1 -0
- package/dist/knowledge/promote.d.ts +145 -0
- package/dist/knowledge/promote.d.ts.map +1 -0
- package/dist/knowledge/promote.js +532 -0
- package/dist/knowledge/promote.js.map +1 -0
- package/dist/knowledge/query-log.d.ts +88 -0
- package/dist/knowledge/query-log.d.ts.map +1 -0
- package/dist/knowledge/query-log.js +207 -0
- package/dist/knowledge/query-log.js.map +1 -0
- package/dist/knowledge/scoring.d.ts +22 -2
- package/dist/knowledge/scoring.d.ts.map +1 -1
- package/dist/knowledge/scoring.js +51 -3
- package/dist/knowledge/scoring.js.map +1 -1
- package/dist/knowledge/search.d.ts +56 -5
- package/dist/knowledge/search.d.ts.map +1 -1
- package/dist/knowledge/search.js +88 -10
- package/dist/knowledge/search.js.map +1 -1
- package/dist/knowledge/store.d.ts +12 -0
- package/dist/knowledge/store.d.ts.map +1 -1
- package/dist/knowledge/store.js +18 -0
- package/dist/knowledge/store.js.map +1 -1
- package/dist/search/mmr.d.ts +54 -0
- package/dist/search/mmr.d.ts.map +1 -0
- package/dist/search/mmr.js +138 -0
- package/dist/search/mmr.js.map +1 -0
- package/dist/server.d.ts +334 -0
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +378 -301
- package/dist/server.js.map +1 -1
- package/dist/sessions/indexer.d.ts.map +1 -1
- package/dist/sessions/indexer.js +13 -11
- package/dist/sessions/indexer.js.map +1 -1
- package/dist/tool-handlers.d.ts +10 -3
- package/dist/tool-handlers.d.ts.map +1 -1
- package/dist/tool-handlers.js +150 -21
- package/dist/tool-handlers.js.map +1 -1
- package/dist/ui/app.js +271 -1
- package/dist/ui/render-knowledge.js +3 -3
- package/dist/ui/styles.css +209 -0
- package/dist/wakeup.d.ts +59 -14
- package/dist/wakeup.d.ts.map +1 -1
- package/dist/wakeup.js +406 -43
- package/dist/wakeup.js.map +1 -1
- package/docs/ARCHITECTURE.md +31 -6
- package/docs/SETUP.md +20 -8
- package/docs/USER-MANUAL.md +205 -59
- package/docs/hooks.md +81 -21
- package/package.json +4 -1
- package/scripts/hooks/first-prompt-inject.mjs +230 -0
- package/scripts/hooks/precompact-flush.mjs +89 -60
- package/scripts/hooks/session-start.js +73 -9
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Automatic staleness detector driven by code activity in session summaries.
|
|
3
|
+
*
|
|
4
|
+
* The Telegram-level pain point that inspired this feature: "new entries go
|
|
5
|
+
* in fine, but old entries don't update themselves — on fast-moving projects
|
|
6
|
+
* my knowledge system ends up working AGAINST me."
|
|
7
|
+
*
|
|
8
|
+
* v1.8.1 answer (fully automatic, no agent action required):
|
|
9
|
+
* 1. For each knowledge entry, extract the file paths it mentions in its
|
|
10
|
+
* body (reuses the same FILE_PATH_RE pattern used for session summary
|
|
11
|
+
* extraction so we stay consistent).
|
|
12
|
+
* 2. For each recent session (default: last 30d), the existing
|
|
13
|
+
* `getSessionSummary` gives us `filesModified` — paths touched during
|
|
14
|
+
* that session's tool_result output.
|
|
15
|
+
* 3. If entry X mentions `src/auth.ts` AND recent sessions modified
|
|
16
|
+
* `src/auth.ts` AFTER the entry's body was last edited, X is a
|
|
17
|
+
* staleness candidate. Surface via `knowledge_analyze(action:
|
|
18
|
+
* "stale_by_code_activity")`.
|
|
19
|
+
*
|
|
20
|
+
* The signal is inherently noisy — a file being edited doesn't prove the
|
|
21
|
+
* entry's CLAIM about it is now wrong. But it's the strongest automatic
|
|
22
|
+
* signal we can derive without regex-scanning full transcripts (a tarpit
|
|
23
|
+
* ruled out during design review) or requiring an LLM judge.
|
|
24
|
+
*
|
|
25
|
+
* Entries with `evergreen: true` are exempt — the whole point of evergreen
|
|
26
|
+
* is "this doesn't decay even when the surrounding code churns".
|
|
27
|
+
*/
|
|
28
|
+
export interface StalenessSignal {
|
|
29
|
+
/** Knowledge entry path (relative to memoryDir). */
|
|
30
|
+
entry: string;
|
|
31
|
+
/** Entry title (best-effort from frontmatter). */
|
|
32
|
+
title: string;
|
|
33
|
+
/** File paths the entry mentions that have been modified in recent sessions. */
|
|
34
|
+
touched_files: string[];
|
|
35
|
+
/** Distinct session IDs whose tool output touched one of `touched_files`. */
|
|
36
|
+
touching_sessions: Array<{
|
|
37
|
+
session_id: string;
|
|
38
|
+
project: string;
|
|
39
|
+
start_time: string;
|
|
40
|
+
files: string[];
|
|
41
|
+
}>;
|
|
42
|
+
/** Days since the entry's body file was last modified on disk. */
|
|
43
|
+
body_age_days: number;
|
|
44
|
+
/**
|
|
45
|
+
* Days between the entry's body last-modified time and the EARLIEST
|
|
46
|
+
* touching session. A large positive number means the entry body hasn't
|
|
47
|
+
* been updated to reflect later code activity.
|
|
48
|
+
*/
|
|
49
|
+
lag_days: number;
|
|
50
|
+
/**
|
|
51
|
+
* Heuristic confidence 0–1. Scales with number of touching sessions and
|
|
52
|
+
* the lag, saturates at 5+ sessions and 60+ days. Multiplied by the
|
|
53
|
+
* symbol-evidence factor (see `symbol_evidence`) to downweight cases
|
|
54
|
+
* where the entry's named identifiers still appear in the touched file.
|
|
55
|
+
*/
|
|
56
|
+
confidence: number;
|
|
57
|
+
/**
|
|
58
|
+
* Precision-layer evidence explaining the final confidence.
|
|
59
|
+
* - `not_applicable`: entry quoted no identifiers we could verify.
|
|
60
|
+
* - `all_present`: every named symbol still appears in the touched files
|
|
61
|
+
* (confidence × 0.3 — entry's specific claims likely still hold).
|
|
62
|
+
* - `partial`: some named symbols missing (confidence scaled by missing ratio).
|
|
63
|
+
* - `all_missing`: no named symbols found in touched files (full confidence).
|
|
64
|
+
*/
|
|
65
|
+
symbol_evidence: 'not_applicable' | 'all_present' | 'partial' | 'all_missing';
|
|
66
|
+
/** Named identifiers the entry quotes (in backticks or fenced blocks). */
|
|
67
|
+
symbols_checked: string[];
|
|
68
|
+
/** Subset of `symbols_checked` NOT found in any touched file (candidate drift). */
|
|
69
|
+
symbols_missing: string[];
|
|
70
|
+
}
|
|
71
|
+
export interface FreshnessOptions {
|
|
72
|
+
/** Only consider sessions that started within this many days. Default 30. */
|
|
73
|
+
sinceDays?: number;
|
|
74
|
+
/** Minimum number of touching sessions before an entry qualifies. Default 1. */
|
|
75
|
+
minTouchingSessions?: number;
|
|
76
|
+
/** Maximum entries to scan (cost bound). Default 500. */
|
|
77
|
+
maxEntries?: number;
|
|
78
|
+
/** Category filter (e.g. only "decisions"). Default: all. */
|
|
79
|
+
category?: string;
|
|
80
|
+
/**
|
|
81
|
+
* Dependency-injection hook for tests. When provided, skips `listSessions`
|
|
82
|
+
* + `getSessionSummary` and reads from the caller-supplied array. Each
|
|
83
|
+
* entry is `{session_id, project, start_time, filesModified[]}`.
|
|
84
|
+
*/
|
|
85
|
+
sessionSource?: Array<{
|
|
86
|
+
session_id: string;
|
|
87
|
+
project: string;
|
|
88
|
+
start_time: string;
|
|
89
|
+
filesModified: string[];
|
|
90
|
+
}>;
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* Scan knowledge entries for code-activity-driven staleness signals.
|
|
94
|
+
*
|
|
95
|
+
* Cost bound: `maxEntries` × `recentSessionCount`. On a 100-entry KB with 50
|
|
96
|
+
* recent sessions the work is ~5000 set intersections, tolerable.
|
|
97
|
+
*/
|
|
98
|
+
export declare function staleByCodeActivity(options?: FreshnessOptions): StalenessSignal[];
|
|
99
|
+
//# sourceMappingURL=freshness.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"freshness.d.ts","sourceRoot":"","sources":["../../src/knowledge/freshness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AA8FH,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,6EAA6E;IAC7E,iBAAiB,EAAE,KAAK,CAAC;QACvB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,EAAE,CAAC;KACjB,CAAC,CAAC;IACH,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,eAAe,EAAE,gBAAgB,GAAG,aAAa,GAAG,SAAS,GAAG,aAAa,CAAC;IAC9E,0EAA0E;IAC1E,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,mFAAmF;IACnF,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,aAAa,CAAC,EAAE,KAAK,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,aAAa,EAAE,MAAM,EAAE,CAAC;KACzB,CAAC,CAAC;CACJ;AAID;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,gBAAqB,GAAG,eAAe,EAAE,CA0LrF"}
|
|
@@ -0,0 +1,303 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Automatic staleness detector driven by code activity in session summaries.
|
|
3
|
+
*
|
|
4
|
+
* The Telegram-level pain point that inspired this feature: "new entries go
|
|
5
|
+
* in fine, but old entries don't update themselves — on fast-moving projects
|
|
6
|
+
* my knowledge system ends up working AGAINST me."
|
|
7
|
+
*
|
|
8
|
+
* v1.8.1 answer (fully automatic, no agent action required):
|
|
9
|
+
* 1. For each knowledge entry, extract the file paths it mentions in its
|
|
10
|
+
* body (reuses the same FILE_PATH_RE pattern used for session summary
|
|
11
|
+
* extraction so we stay consistent).
|
|
12
|
+
* 2. For each recent session (default: last 30d), the existing
|
|
13
|
+
* `getSessionSummary` gives us `filesModified` — paths touched during
|
|
14
|
+
* that session's tool_result output.
|
|
15
|
+
* 3. If entry X mentions `src/auth.ts` AND recent sessions modified
|
|
16
|
+
* `src/auth.ts` AFTER the entry's body was last edited, X is a
|
|
17
|
+
* staleness candidate. Surface via `knowledge_analyze(action:
|
|
18
|
+
* "stale_by_code_activity")`.
|
|
19
|
+
*
|
|
20
|
+
* The signal is inherently noisy — a file being edited doesn't prove the
|
|
21
|
+
* entry's CLAIM about it is now wrong. But it's the strongest automatic
|
|
22
|
+
* signal we can derive without regex-scanning full transcripts (a tarpit
|
|
23
|
+
* ruled out during design review) or requiring an LLM judge.
|
|
24
|
+
*
|
|
25
|
+
* Entries with `evergreen: true` are exempt — the whole point of evergreen
|
|
26
|
+
* is "this doesn't decay even when the surrounding code churns".
|
|
27
|
+
*/
|
|
28
|
+
import fs from 'fs';
|
|
29
|
+
import path from 'path';
|
|
30
|
+
import { listEntries, readEntry } from './store.js';
|
|
31
|
+
import { listSessions, getSessionSummary } from '../sessions/summary.js';
|
|
32
|
+
import { getConfig } from '../types.js';
|
|
33
|
+
// ── Extract file paths from entry body ──────────────────────────────────────
|
|
34
|
+
// Same pattern used for session summaries (sessions/summary.ts). Keep them
|
|
35
|
+
// aligned — matching behaviour means an entry's mentions and a session's
|
|
36
|
+
// touches are comparable.
|
|
37
|
+
const FILE_PATH_RE = /(?:^|[\s"'`(])([./~]?(?:[\w.-]+\/)+[\w.-]+\.(?:ts|tsx|js|jsx|py|rs|go|java|vue|svelte|css|scss|html|json|yaml|yml|toml|md|txt|sh|sql|prisma|graphql|proto))\b/g;
|
|
38
|
+
function extractFilePathsFromBody(text) {
|
|
39
|
+
const paths = new Set();
|
|
40
|
+
FILE_PATH_RE.lastIndex = 0;
|
|
41
|
+
let match;
|
|
42
|
+
while ((match = FILE_PATH_RE.exec(text)) !== null) {
|
|
43
|
+
// Normalise leading './' and '~/' so an entry written as `./src/x.ts`
|
|
44
|
+
// matches a session's `src/x.ts`.
|
|
45
|
+
let p = match[1];
|
|
46
|
+
if (p.startsWith('./'))
|
|
47
|
+
p = p.slice(2);
|
|
48
|
+
if (p.startsWith('~/'))
|
|
49
|
+
p = p.slice(2);
|
|
50
|
+
paths.add(p);
|
|
51
|
+
}
|
|
52
|
+
return Array.from(paths);
|
|
53
|
+
}
|
|
54
|
+
// ── Symbol extraction for precision layer ──────────────────────────────────
|
|
55
|
+
//
|
|
56
|
+
// File-activity alone is a noisy signal: every formatting / rename / import
|
|
57
|
+
// touch flags entries that still describe the file correctly. We tighten
|
|
58
|
+
// precision by extracting SYMBOLS the entry names (identifiers inside inline
|
|
59
|
+
// backticks and inside fenced code blocks) and checking whether those names
|
|
60
|
+
// still appear literally in the touched file. If all named symbols are still
|
|
61
|
+
// present, the entry's concrete claims probably still hold and we downweight
|
|
62
|
+
// the signal even if the file was edited; if named symbols are missing, that
|
|
63
|
+
// is real drift and we keep full confidence.
|
|
64
|
+
//
|
|
65
|
+
// Kept intentionally cheap (no tree-sitter): regex + substring on the file
|
|
66
|
+
// content. Good enough to cut a large share of false positives at zero new
|
|
67
|
+
// native dependencies. Tree-sitter-backed version is a candidate for v1.9.
|
|
68
|
+
const INLINE_CODE_RE = /`([^`\n]{2,80})`/g;
|
|
69
|
+
const FENCED_BLOCK_RE = /```[\s\S]*?```/g;
|
|
70
|
+
const IDENT_IN_FENCE_RE = /\b([A-Za-z_][A-Za-z0-9_]{2,})\b/g;
|
|
71
|
+
const IDENT_STRICT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
|
|
72
|
+
/**
|
|
73
|
+
* Extract identifier-shaped tokens the entry uses. Only backticked items
|
|
74
|
+
* (inline or inside fenced blocks) qualify — prose camelCase is too noisy.
|
|
75
|
+
* Strips URLs, file paths, and punctuation-bearing strings.
|
|
76
|
+
*/
|
|
77
|
+
function extractSymbols(text) {
|
|
78
|
+
const symbols = new Set();
|
|
79
|
+
// Inline backticks: `someFunction`, `Foo.bar`, `SOME_CONST`.
|
|
80
|
+
INLINE_CODE_RE.lastIndex = 0;
|
|
81
|
+
let m;
|
|
82
|
+
while ((m = INLINE_CODE_RE.exec(text)) !== null) {
|
|
83
|
+
const raw = m[1].trim();
|
|
84
|
+
// Reject: paths, URLs, spaces, multi-word prose in backticks.
|
|
85
|
+
if (/[\s/\\]/.test(raw))
|
|
86
|
+
continue;
|
|
87
|
+
// Dotted identifier like `Foo.bar` — take the last segment (what grep will match).
|
|
88
|
+
const last = raw.split('.').pop() || raw;
|
|
89
|
+
if (IDENT_STRICT_RE.test(last) && last.length >= 3)
|
|
90
|
+
symbols.add(last);
|
|
91
|
+
}
|
|
92
|
+
// Fenced blocks: pull identifiers from the contents, skipping the
|
|
93
|
+
// language hint and obvious prose.
|
|
94
|
+
FENCED_BLOCK_RE.lastIndex = 0;
|
|
95
|
+
while ((m = FENCED_BLOCK_RE.exec(text)) !== null) {
|
|
96
|
+
const block = m[0];
|
|
97
|
+
IDENT_IN_FENCE_RE.lastIndex = 0;
|
|
98
|
+
let im;
|
|
99
|
+
while ((im = IDENT_IN_FENCE_RE.exec(block)) !== null) {
|
|
100
|
+
const tok = im[1];
|
|
101
|
+
// Skip language labels + SQL-ish keywords + common filler; let
|
|
102
|
+
// anything ≥4 chars and not all-lowercase-short-word through.
|
|
103
|
+
if (tok.length < 4)
|
|
104
|
+
continue;
|
|
105
|
+
if (/^(the|and|for|this|that|with|from|into|when|else|true|false|null|undefined)$/i.test(tok))
|
|
106
|
+
continue;
|
|
107
|
+
symbols.add(tok);
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
return Array.from(symbols);
|
|
111
|
+
}
|
|
112
|
+
// ── Main detector ──────────────────────────────────────────────────────────
|
|
113
|
+
/**
|
|
114
|
+
* Scan knowledge entries for code-activity-driven staleness signals.
|
|
115
|
+
*
|
|
116
|
+
* Cost bound: `maxEntries` × `recentSessionCount`. On a 100-entry KB with 50
|
|
117
|
+
* recent sessions the work is ~5000 set intersections, tolerable.
|
|
118
|
+
*/
|
|
119
|
+
export function staleByCodeActivity(options = {}) {
|
|
120
|
+
const sinceDays = options.sinceDays ?? 30;
|
|
121
|
+
const minTouchingSessions = options.minTouchingSessions ?? 1;
|
|
122
|
+
const maxEntries = options.maxEntries ?? 500;
|
|
123
|
+
const category = options.category;
|
|
124
|
+
const config = getConfig();
|
|
125
|
+
const cutoffMs = Date.now() - sinceDays * 24 * 3600_000;
|
|
126
|
+
// 1. Gather entries + their mtimes + their mentioned file paths.
|
|
127
|
+
const entries = listEntries(config.memoryDir, category).slice(0, maxEntries);
|
|
128
|
+
const bundles = [];
|
|
129
|
+
for (const entry of entries) {
|
|
130
|
+
if (entry.evergreen)
|
|
131
|
+
continue; // explicit exemption
|
|
132
|
+
try {
|
|
133
|
+
const full = path.join(config.memoryDir, entry.path);
|
|
134
|
+
const stat = fs.statSync(full);
|
|
135
|
+
const { content } = readEntry(config.memoryDir, entry.path);
|
|
136
|
+
const filesMentioned = new Set(extractFilePathsFromBody(content));
|
|
137
|
+
if (filesMentioned.size === 0)
|
|
138
|
+
continue; // entries without code refs can't be stale via this signal
|
|
139
|
+
bundles.push({
|
|
140
|
+
path: entry.path,
|
|
141
|
+
title: entry.title || entry.path,
|
|
142
|
+
evergreen: Boolean(entry.evergreen),
|
|
143
|
+
mtimeMs: stat.mtimeMs,
|
|
144
|
+
filesMentioned,
|
|
145
|
+
symbols: extractSymbols(content),
|
|
146
|
+
});
|
|
147
|
+
}
|
|
148
|
+
catch {
|
|
149
|
+
// Skip unreadable entries; they're a separate class of problem.
|
|
150
|
+
continue;
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
if (bundles.length === 0)
|
|
154
|
+
return [];
|
|
155
|
+
const recent = [];
|
|
156
|
+
const normalisePath = (raw) => {
|
|
157
|
+
let p = raw;
|
|
158
|
+
if (p.startsWith('./'))
|
|
159
|
+
p = p.slice(2);
|
|
160
|
+
if (p.startsWith('~/'))
|
|
161
|
+
p = p.slice(2);
|
|
162
|
+
return p;
|
|
163
|
+
};
|
|
164
|
+
if (options.sessionSource) {
|
|
165
|
+
for (const s of options.sessionSource) {
|
|
166
|
+
const startMs = new Date(s.start_time).getTime();
|
|
167
|
+
if (!Number.isFinite(startMs) || startMs < cutoffMs)
|
|
168
|
+
continue;
|
|
169
|
+
if (s.filesModified.length === 0)
|
|
170
|
+
continue;
|
|
171
|
+
const normalised = new Set();
|
|
172
|
+
for (const raw of s.filesModified)
|
|
173
|
+
normalised.add(normalisePath(raw));
|
|
174
|
+
recent.push({
|
|
175
|
+
session_id: s.session_id,
|
|
176
|
+
project: s.project,
|
|
177
|
+
start_time: s.start_time,
|
|
178
|
+
startMs,
|
|
179
|
+
filesModified: normalised,
|
|
180
|
+
});
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
else {
|
|
184
|
+
const sessions = listSessions();
|
|
185
|
+
for (const sess of sessions) {
|
|
186
|
+
if (sess.startTime === 'unknown')
|
|
187
|
+
continue;
|
|
188
|
+
const startMs = new Date(sess.startTime).getTime();
|
|
189
|
+
if (!Number.isFinite(startMs) || startMs < cutoffMs)
|
|
190
|
+
continue;
|
|
191
|
+
const summary = getSessionSummary(sess.sessionId, sess.project);
|
|
192
|
+
if (!summary || summary.filesModified.length === 0)
|
|
193
|
+
continue;
|
|
194
|
+
const normalised = new Set();
|
|
195
|
+
for (const raw of summary.filesModified)
|
|
196
|
+
normalised.add(normalisePath(raw));
|
|
197
|
+
recent.push({
|
|
198
|
+
session_id: sess.sessionId,
|
|
199
|
+
project: sess.project,
|
|
200
|
+
start_time: sess.startTime,
|
|
201
|
+
startMs,
|
|
202
|
+
filesModified: normalised,
|
|
203
|
+
});
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
if (recent.length === 0)
|
|
207
|
+
return [];
|
|
208
|
+
// 3. Join — for each entry, find sessions whose modified files intersect
|
|
209
|
+
// the entry's mentions AND whose start is AFTER the entry body's mtime.
|
|
210
|
+
const signals = [];
|
|
211
|
+
const nowMs = Date.now();
|
|
212
|
+
for (const bundle of bundles) {
|
|
213
|
+
const touchingFiles = new Set();
|
|
214
|
+
const touchingSessions = [];
|
|
215
|
+
let earliestTouchMs = Number.POSITIVE_INFINITY;
|
|
216
|
+
for (const sess of recent) {
|
|
217
|
+
if (sess.startMs <= bundle.mtimeMs)
|
|
218
|
+
continue;
|
|
219
|
+
const overlap = [];
|
|
220
|
+
for (const f of sess.filesModified) {
|
|
221
|
+
if (bundle.filesMentioned.has(f))
|
|
222
|
+
overlap.push(f);
|
|
223
|
+
}
|
|
224
|
+
if (overlap.length === 0)
|
|
225
|
+
continue;
|
|
226
|
+
for (const f of overlap)
|
|
227
|
+
touchingFiles.add(f);
|
|
228
|
+
touchingSessions.push({
|
|
229
|
+
session_id: sess.session_id,
|
|
230
|
+
project: sess.project,
|
|
231
|
+
start_time: sess.start_time,
|
|
232
|
+
files: overlap,
|
|
233
|
+
});
|
|
234
|
+
if (sess.startMs < earliestTouchMs)
|
|
235
|
+
earliestTouchMs = sess.startMs;
|
|
236
|
+
}
|
|
237
|
+
if (touchingSessions.length < minTouchingSessions)
|
|
238
|
+
continue;
|
|
239
|
+
const bodyAgeDays = Math.max(0, (nowMs - bundle.mtimeMs) / (24 * 3600_000));
|
|
240
|
+
const lagDays = Number.isFinite(earliestTouchMs)
|
|
241
|
+
? Math.max(0, (earliestTouchMs - bundle.mtimeMs) / (24 * 3600_000))
|
|
242
|
+
: 0;
|
|
243
|
+
// Baseline confidence from volume + lag: saturate at 5 sessions / 60d.
|
|
244
|
+
const sessionFactor = Math.min(1, touchingSessions.length / 5);
|
|
245
|
+
const lagFactor = Math.min(1, lagDays / 60);
|
|
246
|
+
let confidence = sessionFactor * lagFactor;
|
|
247
|
+
// Precision layer: check whether symbols the entry NAMES still appear
|
|
248
|
+
// in the touched files. Entries that name e.g. `recordAccess` get
|
|
249
|
+
// downweighted when that identifier still lives in the current source
|
|
250
|
+
// — the file was edited but the claim survived.
|
|
251
|
+
let symbolEvidence = 'not_applicable';
|
|
252
|
+
let symbolsMissing = [];
|
|
253
|
+
if (bundle.symbols.length > 0) {
|
|
254
|
+
let combined = '';
|
|
255
|
+
for (const file of touchingFiles) {
|
|
256
|
+
try {
|
|
257
|
+
combined += '\n' + fs.readFileSync(path.resolve(file), 'utf-8');
|
|
258
|
+
}
|
|
259
|
+
catch {
|
|
260
|
+
// File may live outside the knowledge cwd or be gone — that's a
|
|
261
|
+
// strong staleness signal on its own, but the existing file-
|
|
262
|
+
// activity path already surfaced it. Don't also credit symbols.
|
|
263
|
+
}
|
|
264
|
+
}
|
|
265
|
+
if (combined.length > 0) {
|
|
266
|
+
const missing = bundle.symbols.filter((s) => !combined.includes(s));
|
|
267
|
+
const missingRatio = missing.length / bundle.symbols.length;
|
|
268
|
+
if (missingRatio === 0) {
|
|
269
|
+
// Every named identifier still present → entry's concrete claims
|
|
270
|
+
// likely intact; strongly downweight.
|
|
271
|
+
confidence *= 0.3;
|
|
272
|
+
symbolEvidence = 'all_present';
|
|
273
|
+
}
|
|
274
|
+
else if (missingRatio === 1) {
|
|
275
|
+
symbolEvidence = 'all_missing';
|
|
276
|
+
}
|
|
277
|
+
else {
|
|
278
|
+
// Scale linearly: half missing → keep half-weight.
|
|
279
|
+
confidence *= 0.3 + 0.7 * missingRatio;
|
|
280
|
+
symbolEvidence = 'partial';
|
|
281
|
+
}
|
|
282
|
+
symbolsMissing = missing;
|
|
283
|
+
}
|
|
284
|
+
}
|
|
285
|
+
signals.push({
|
|
286
|
+
entry: bundle.path,
|
|
287
|
+
title: bundle.title,
|
|
288
|
+
touched_files: Array.from(touchingFiles).sort(),
|
|
289
|
+
touching_sessions: touchingSessions.sort((a, b) => a.start_time.localeCompare(b.start_time)),
|
|
290
|
+
body_age_days: Math.round(bodyAgeDays * 10) / 10,
|
|
291
|
+
lag_days: Math.round(lagDays * 10) / 10,
|
|
292
|
+
confidence: Math.round(confidence * 100) / 100,
|
|
293
|
+
symbol_evidence: symbolEvidence,
|
|
294
|
+
symbols_checked: bundle.symbols,
|
|
295
|
+
symbols_missing: symbolsMissing,
|
|
296
|
+
});
|
|
297
|
+
}
|
|
298
|
+
// Sort highest-confidence first — that's the "probably stale, look here"
|
|
299
|
+
// queue ordering the agent or dashboard should honour.
|
|
300
|
+
signals.sort((a, b) => b.confidence - a.confidence);
|
|
301
|
+
return signals;
|
|
302
|
+
}
|
|
303
|
+
//# sourceMappingURL=freshness.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"freshness.js","sourceRoot":"","sources":["../../src/knowledge/freshness.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Scored-and-gated promotion pass.
|
|
3
|
+
*
|
|
4
|
+
* Replaces the regex-only auto-distillation with a scored candidate pipeline.
|
|
5
|
+
* Each project-level insight (extracted by existing distill.ts machinery) is
|
|
6
|
+
* scored on six weighted signals and held against three independent gates.
|
|
7
|
+
* Only candidates that clear ALL gates are promoted to durable knowledge
|
|
8
|
+
* entries.
|
|
9
|
+
*
|
|
10
|
+
* Signal weights (v1.8 starting point — tune against the self-labeled write
|
|
11
|
+
* bench, not by intuition):
|
|
12
|
+
* Relevance 0.30
|
|
13
|
+
* Frequency 0.24
|
|
14
|
+
* Query diversity 0.15
|
|
15
|
+
* Recency 0.15
|
|
16
|
+
* Consolidation 0.10
|
|
17
|
+
* Conceptual richness 0.06
|
|
18
|
+
*
|
|
19
|
+
* Gates (default thresholds; overridable per call):
|
|
20
|
+
* minScore ≥ 0.5
|
|
21
|
+
* minRecallCount ≥ 2 (number of source sessions)
|
|
22
|
+
* minUniqueQueries ≥ 2 (number of distinct topic fingerprints)
|
|
23
|
+
*
|
|
24
|
+
* Grounded rehydration: before promoting, every source session file is
|
|
25
|
+
* checked to still exist on disk. Missing sources ⇒ skip + diary entry.
|
|
26
|
+
* Prevents promoting content the user has since deleted.
|
|
27
|
+
*
|
|
28
|
+
* Evergreen exemption: entries with `evergreen: true` frontmatter are never
|
|
29
|
+
* OVERWRITTEN by promotion — the merger appends a fresh Recent-Activity
|
|
30
|
+
* block below the existing content instead of replacing it.
|
|
31
|
+
*
|
|
32
|
+
* Diary: every run writes `~/agent-knowledge/.dreams/YYYY-MM-DD.md` with per-
|
|
33
|
+
* candidate score breakdown and gate outcomes. The `.`-prefixed directory is
|
|
34
|
+
* git-tracked (audit trail) but excluded from listEntries/search (not part
|
|
35
|
+
* of the retrievable corpus).
|
|
36
|
+
*/
|
|
37
|
+
export declare const SIGNAL_WEIGHTS: {
|
|
38
|
+
readonly relevance: 0.3;
|
|
39
|
+
readonly frequency: 0.24;
|
|
40
|
+
readonly queryDiversity: 0.15;
|
|
41
|
+
readonly recency: 0.15;
|
|
42
|
+
readonly consolidation: 0.1;
|
|
43
|
+
readonly conceptualRichness: 0.06;
|
|
44
|
+
};
|
|
45
|
+
export declare const DEFAULT_GATES: {
|
|
46
|
+
readonly minScore: 0.5;
|
|
47
|
+
readonly minRecallCount: 2;
|
|
48
|
+
readonly minUniqueQueries: 2;
|
|
49
|
+
};
|
|
50
|
+
export interface SignalBreakdown {
|
|
51
|
+
relevance: number;
|
|
52
|
+
frequency: number;
|
|
53
|
+
queryDiversity: number;
|
|
54
|
+
recency: number;
|
|
55
|
+
consolidation: number;
|
|
56
|
+
conceptualRichness: number;
|
|
57
|
+
}
|
|
58
|
+
export interface GateResult {
|
|
59
|
+
value: number;
|
|
60
|
+
threshold: number;
|
|
61
|
+
passed: boolean;
|
|
62
|
+
}
|
|
63
|
+
export interface GateOutcomes {
|
|
64
|
+
minScore: GateResult;
|
|
65
|
+
minRecallCount: GateResult;
|
|
66
|
+
minUniqueQueries: GateResult;
|
|
67
|
+
}
|
|
68
|
+
export interface PromoteCandidate {
|
|
69
|
+
/** Normalized project name — the candidate's durable identity. */
|
|
70
|
+
id: string;
|
|
71
|
+
/** A short human-readable signature for display. */
|
|
72
|
+
label: string;
|
|
73
|
+
/** Source session IDs that contributed to this candidate. */
|
|
74
|
+
sessionIds: string[];
|
|
75
|
+
/** ISO timestamp of the earliest source session. */
|
|
76
|
+
firstSeen: string;
|
|
77
|
+
/** ISO timestamp of the latest source session. */
|
|
78
|
+
lastSeen: string;
|
|
79
|
+
signals: SignalBreakdown;
|
|
80
|
+
/** Weighted composite score in [0, 1]. */
|
|
81
|
+
score: number;
|
|
82
|
+
gates: GateOutcomes;
|
|
83
|
+
passed: boolean;
|
|
84
|
+
/** Populated when `mode === 'apply'` and promotion succeeded. */
|
|
85
|
+
promotedPath?: string;
|
|
86
|
+
/** Populated when the candidate was skipped — reason string. */
|
|
87
|
+
skipReason?: string;
|
|
88
|
+
}
|
|
89
|
+
export interface PromoteOptions {
|
|
90
|
+
/** "explain" scores candidates but never writes; "apply" writes those that pass. Default: "explain". */
|
|
91
|
+
mode?: 'apply' | 'explain';
|
|
92
|
+
/** Gate threshold overrides. */
|
|
93
|
+
minScore?: number;
|
|
94
|
+
minRecallCount?: number;
|
|
95
|
+
minUniqueQueries?: number;
|
|
96
|
+
/** Write the diary markdown to ~/agent-knowledge/.dreams/. Default: true. */
|
|
97
|
+
writeDiary?: boolean;
|
|
98
|
+
/**
|
|
99
|
+
* Consider sessions starting on/after this cutoff only. Useful for
|
|
100
|
+
* replay benches; omit for "since last run".
|
|
101
|
+
*/
|
|
102
|
+
sinceIso?: string | null;
|
|
103
|
+
/**
|
|
104
|
+
* When true, read cursor state but do NOT advance it on success. Keeps
|
|
105
|
+
* replays idempotent. Default: mode === 'apply' advances, 'explain' does not.
|
|
106
|
+
*/
|
|
107
|
+
advanceCursor?: boolean;
|
|
108
|
+
}
|
|
109
|
+
export interface PromoteResult {
|
|
110
|
+
runStartedAt: string;
|
|
111
|
+
runFinishedAt: string;
|
|
112
|
+
mode: 'apply' | 'explain';
|
|
113
|
+
candidates: PromoteCandidate[];
|
|
114
|
+
promotedPaths: string[];
|
|
115
|
+
skippedIds: string[];
|
|
116
|
+
diaryPath: string | null;
|
|
117
|
+
totals: {
|
|
118
|
+
candidates: number;
|
|
119
|
+
passed: number;
|
|
120
|
+
promoted: number;
|
|
121
|
+
skipped: number;
|
|
122
|
+
};
|
|
123
|
+
}
|
|
124
|
+
export interface RawAggregate {
|
|
125
|
+
id: string;
|
|
126
|
+
sessionIds: string[];
|
|
127
|
+
topics: string[];
|
|
128
|
+
topicFingerprints: Set<string>;
|
|
129
|
+
tools: Set<string>;
|
|
130
|
+
files: Set<string>;
|
|
131
|
+
errorPatterns: Set<string>;
|
|
132
|
+
gitCommits: Set<string>;
|
|
133
|
+
firstSeen: string;
|
|
134
|
+
lastSeen: string;
|
|
135
|
+
latestSessionFile: string | null;
|
|
136
|
+
}
|
|
137
|
+
export declare function computeSignals(a: RawAggregate, now: number): SignalBreakdown;
|
|
138
|
+
export declare function compositeScore(s: SignalBreakdown): number;
|
|
139
|
+
export declare function evaluateGates(agg: RawAggregate, score: number, thresholds: {
|
|
140
|
+
minScore: number;
|
|
141
|
+
minRecallCount: number;
|
|
142
|
+
minUniqueQueries: number;
|
|
143
|
+
}): GateOutcomes;
|
|
144
|
+
export declare function promote(options?: PromoteOptions): Promise<PromoteResult>;
|
|
145
|
+
//# sourceMappingURL=promote.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"promote.d.ts","sourceRoot":"","sources":["../../src/knowledge/promote.ts"],"names":[],"mappings":"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"}
|