agent-knowledge 1.7.3 → 1.8.0

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 (44) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/.mcp.json +1 -1
  3. package/CHANGELOG.md +43 -0
  4. package/README.md +43 -18
  5. package/agent-desk-plugin.json +1 -1
  6. package/dist/knowledge/promote.d.ts +145 -0
  7. package/dist/knowledge/promote.d.ts.map +1 -0
  8. package/dist/knowledge/promote.js +517 -0
  9. package/dist/knowledge/promote.js.map +1 -0
  10. package/dist/knowledge/scoring.d.ts +6 -2
  11. package/dist/knowledge/scoring.d.ts.map +1 -1
  12. package/dist/knowledge/scoring.js +7 -3
  13. package/dist/knowledge/scoring.js.map +1 -1
  14. package/dist/knowledge/search.d.ts +32 -5
  15. package/dist/knowledge/search.d.ts.map +1 -1
  16. package/dist/knowledge/search.js +60 -10
  17. package/dist/knowledge/search.js.map +1 -1
  18. package/dist/knowledge/store.d.ts +6 -0
  19. package/dist/knowledge/store.d.ts.map +1 -1
  20. package/dist/knowledge/store.js +10 -0
  21. package/dist/knowledge/store.js.map +1 -1
  22. package/dist/search/mmr.d.ts +54 -0
  23. package/dist/search/mmr.d.ts.map +1 -0
  24. package/dist/search/mmr.js +138 -0
  25. package/dist/search/mmr.js.map +1 -0
  26. package/dist/server.d.ts +307 -0
  27. package/dist/server.d.ts.map +1 -1
  28. package/dist/server.js +336 -301
  29. package/dist/server.js.map +1 -1
  30. package/dist/sessions/indexer.d.ts.map +1 -1
  31. package/dist/sessions/indexer.js +13 -11
  32. package/dist/sessions/indexer.js.map +1 -1
  33. package/dist/tool-handlers.d.ts +10 -3
  34. package/dist/tool-handlers.d.ts.map +1 -1
  35. package/dist/tool-handlers.js +56 -17
  36. package/dist/tool-handlers.js.map +1 -1
  37. package/docs/ARCHITECTURE.md +31 -6
  38. package/docs/SETUP.md +20 -8
  39. package/docs/USER-MANUAL.md +146 -39
  40. package/docs/hooks.md +81 -21
  41. package/package.json +4 -1
  42. package/scripts/hooks/first-prompt-inject.mjs +230 -0
  43. package/scripts/hooks/precompact-flush.mjs +89 -60
  44. package/scripts/hooks/session-start.js +73 -9
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "agent-knowledge",
3
3
  "description": "Cross-session memory for AI coding agents. Git-synced Markdown knowledge base with hybrid semantic + TF-IDF search, typed knowledge graph, and session auto-distillation with secrets scrubbing.",
4
- "version": "1.7.2",
4
+ "version": "1.8.0",
5
5
  "author": {
6
6
  "name": "keshrath"
7
7
  },
package/.mcp.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "mcpServers": {
3
3
  "agent-knowledge": {
4
4
  "command": "npx",
5
- "args": ["-y", "agent-knowledge@^1.7.2"]
5
+ "args": ["-y", "agent-knowledge@^1.8.0"]
6
6
  }
7
7
  }
8
8
  }
package/CHANGELOG.md CHANGED
@@ -1,5 +1,48 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.8.0 (2026-04-18) — agent-UX pass (**breaking**)
4
+
5
+ Three-axis change: retrieval grew a diversity knob and explainability, auto-distillation replaced with a scored + gated promoter, and new lifecycle hooks (pre-compaction flush, session-start wakeup, first-prompt knowledge injection). All six existing MCP tools stay visible.
6
+
7
+ ### Breaking changes
8
+
9
+ - **`knowledge_search` response shape** — now always includes a top-level `mode: "general" | "scoped"` field, plus `{mode, sessions, knowledge}`. Scoped mode (when `scope` is set) returns `knowledge: []` by design — scoped search was always sessions-only, now it says so.
10
+ - **`category_mode` default flipped from `"filter"` to `"boost"`** — passing a `category` hint no longer silently drops non-matching entries. Matching entries get a 1.25× score boost; non-matches stay in the candidate pool. Pass `category_mode: "filter"` for the legacy hard-filter behavior.
11
+ - **Auto-distillation replaced by the scored promoter** — `backgroundIndex` now calls `promote({ mode: "apply" })` instead of `distillSessions()`. Same `autoDistill` config flag governs both, so existing settings carry over; the output gets STRICTER (fewer, higher-signal promotions). The legacy `distillSessions` function is kept for the write-bench but no longer wired into the default pipeline.
12
+
13
+ ### Added
14
+
15
+ - **`knowledge_search` knobs (all opt-in):**
16
+ - `mmr: boolean` — re-rank knowledge hits with Maximal Marginal Relevance to kill near-duplicate clusters in the top-K.
17
+ - `mmr_lambda: number` — 0-1 tradeoff, default 0.7 (1.0 = pure relevance, 0.0 = pure diversity).
18
+ - `explain: boolean` — attach `score_components` to each knowledge hit (`bm25, decay, maturity, confidence, category_boost, mmr_penalty`). Lets the agent reason about why X ranked above Y.
19
+ - **6-signal scored promoter** (`src/knowledge/promote.ts`) — every project-level candidate is scored on `{relevance 0.30, frequency 0.24, queryDiversity 0.15, recency 0.15, consolidation 0.10, conceptualRichness 0.06}`. Three independent gates (`minScore ≥ 0.5`, `minRecallCount ≥ 2`, `minUniqueQueries ≥ 2`) must ALL pass before a candidate is promoted.
20
+ - **`knowledge_admin(action: "promote")`** — invoke the promoter on demand. `promote_mode: "explain"` (default) returns score breakdowns without writing; `promote_mode: "apply"` writes the ones that pass. Overridable gates via `min_score`, `min_recall_count`, `min_unique_queries`.
21
+ - **Grounded rehydration** — promotion checks that the source session file still exists on disk before writing. Prevents promoting content the user has since deleted.
22
+ - **`.dreams/YYYY-MM-DD.md` diary** — every promoter run logs per-candidate signal breakdowns, gate outcomes, and final action into `~/agent-knowledge/.dreams/`. The dir is git-tracked (audit trail) but `.`-prefixed so `listEntries`/search skip it.
23
+ - **`evergreen: true` frontmatter flag** — entries with the flag are exempt from decay in ranking, AND the promoter appends new activity instead of overwriting the body. Use for durable decisions / architecture / identity entries.
24
+ - **`diversity@5` bench metric** — `bench/run.ts` now reports average unique-cluster count in top-5 (token-Jaccard ≥ 0.5 merges) alongside R@5 / R@10. MMR changes must move this metric, not just recall.
25
+ - **`bench/promote-bench.ts`** — self-labeled write-bench. Offline replay of the promoter vs. a naive "ship all candidates" baseline, with auto-labeling by "was the candidate referenced in sessions ≥ cutoff days later?". Outputs precision / recall / F1 per strategy. Side-effect-free (never writes to the KB, never advances the cursor). Intended gate for rolling signal weights or threshold changes.
26
+ - **Pre-compaction memory-flush nudge** — `scripts/hooks/precompact-flush.mjs` now injects an `additionalContext` block into the host's PreCompact response telling the agent to save any unsaved context via `knowledge(action="write", …)` BEFORE compaction summarizes the transcript. Disable with `AGENT_KNOWLEDGE_PRECOMPACT_NUDGE=0` (keeps the disk dump). Set `=off` to suppress both.
27
+ - **SessionStart auto-wakeup** — `scripts/hooks/session-start.js` auto-loads a token-budgeted `knowledge(action="wakeup")` payload into the host's SessionStart `additionalContext` on every session. No more manual wakeup call. Disable with `AGENT_KNOWLEDGE_AUTOWAKE=0`, tune budget with `AGENT_KNOWLEDGE_WAKEUP_BUDGET` (default 800 tokens).
28
+ - **First-prompt knowledge injection** — `scripts/hooks/first-prompt-inject.mjs` (UserPromptSubmit). When the user sends the first real prompt of a session, it's passed through `searchKnowledge(prompt, { mmr: true })` and the top hits are injected as `additionalContext` before the model reads the prompt. Gates: prompt ≥ 10 chars, doesn't start with `/` or `!`, fires at most once per session (marker file at `{dataDir}/.first-prompt-seen/<session_id>`). Fail-open everywhere. Complements `wakeup` (which is query-agnostic) with query-targeted content. Env knobs:
29
+ - `AGENT_KNOWLEDGE_FIRSTPROMPT_INJECT` (default `1`) — set `0` / `false` / `off` to disable.
30
+ - `AGENT_KNOWLEDGE_FIRSTPROMPT_BUDGET` (default `600`, tokens) — clamped to [100, 8000].
31
+ - `AGENT_KNOWLEDGE_FIRSTPROMPT_MAX_HITS` (default `4`) — clamped to [1, 20].
32
+ - **`src/search/mmr.ts`** — new module: `rerankMMR`, `diversityAtK`, `cosineSim`, `jaccardTokenSim`. Reusable for any ranked list.
33
+ - **Extended `bench/fixtures.example.jsonl`** from 5 to 40 sample queries across factual-lookup / multi-hop / temporal / preference / adversarial / workflow categories. Still check-in-safe placeholders — copy to `fixtures.jsonl` and adjust `expected` paths to match your real KB.
34
+ - **Tests:** 45 new (21 for MMR + diversity utils, 16 for promoter signals + gates, 8 for first-prompt-inject hook). 541/541 tests passing.
35
+
36
+ ### Changed
37
+
38
+ - **`computeFinalScore` now accepts an `evergreen` argument** — when true, skips the decay factor. Backward-compatible (parameter is optional).
39
+ - **Signal weights + gate thresholds are exported constants** (`SIGNAL_WEIGHTS`, `DEFAULT_GATES`) — bench + tests pin against them, so changes surface in the diff review.
40
+ - **`searchKnowledge` widens the candidate pool** to 3× `maxResults` when `mmr` is enabled, so MMR has room to pick diverse items.
41
+
42
+ ### Measurement
43
+
44
+ LongMemEval baseline numbers are unchanged (the P0/P1 work is agent-UX + optional retrieval knobs — the default retrieval path is untouched): **R@5 = 97.2% sparse / 98.8% hybrid on `_s`**, **86.0% sparse / 88.4% hybrid on `_m`**. MMR and category-boost changes should be gated on `bench/run.ts` diversity@5 + `bench/promote-bench.ts` F1 before rolling defaults.
45
+
3
46
  ## 1.7.0 (2026-04-13)
4
47
 
5
48
  ### Added
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
4
4
  [![Node >= 20](https://img.shields.io/badge/Node-%3E%3D%2020-brightgreen.svg)](https://nodejs.org)
5
- [![Tests: 420 passing](https://img.shields.io/badge/Tests-420%20passing-brightgreen.svg)]()
5
+ [![Tests: 534 passing](https://img.shields.io/badge/Tests-534%20passing-brightgreen.svg)]()
6
6
  [![MCP Tools: 6](https://img.shields.io/badge/MCP%20Tools-6-blueviolet.svg)]()
7
7
  [![LongMemEval R@5: 98.8%](https://img.shields.io/badge/LongMemEval%20R%405-98.8%25-brightgreen.svg)]()
8
8
 
@@ -50,12 +50,12 @@ No configuration needed. Additional session roots can be added via the `EXTRA_SE
50
50
  - **Multi-tool session search** -- unified search across Claude Code, Cursor, OpenCode, Cline, Continue.dev, and Aider sessions
51
51
  - **Hybrid search** -- semantic vector similarity blended with TF-IDF keyword ranking
52
52
  - **Git-synced knowledge base** -- markdown vault with YAML frontmatter, auto commit and push on writes
53
- - **Auto-distillation** -- session insights automatically extracted and pushed to git with secrets scrubbing
53
+ - **Scored + gated promoter (v1.8)** -- session insights promoted via a 6-signal weighted scorer with three independent gates (`minScore`, `minRecallCount`, `minUniqueQueries`). Runs automatically in background, on demand via `knowledge_admin(action: "promote")`, or benchable offline via `npm run bench:promote`. Emits an auditable `.dreams/YYYY-MM-DD.md` diary every run. Replaces the regex-only distiller.
54
54
  - **Pluggable adapter system** -- add support for new tools by implementing the `SessionAdapter` interface
55
55
  - **Embeddings** -- local (Hugging Face), OpenAI, Claude/Voyage, or Gemini providers
56
56
  - **Fuzzy matching** -- typo-tolerant search using Levenshtein distance
57
57
  - **6 search scopes** -- errors, plans, configs, tools, files, decisions
58
- - **6 MCP tools** -- consolidated action-based interface (knowledge, knowledge_search, knowledge_session, knowledge_graph, knowledge_analyze, knowledge_admin)
58
+ - **6 MCP tools** -- consolidated action-based interface (`knowledge`, `knowledge_search`, `knowledge_session`, `knowledge_graph`, `knowledge_analyze`, `knowledge_admin`)
59
59
  - **Wakeup context (L0+L1)** -- `knowledge` action `wakeup` returns a token-budgeted identity + top-weight entries blob for session-start hydration
60
60
  - **Code graph resolution** -- `calls`, `imports`, `inherits` edge types for code structure; directed BFS traversal (`outbound`/`inbound`/`both`); `bulk_link` for efficient ingestion; `unlink_by_origin` for clearing stale code edges before re-ingest; `code:` prefixed node IDs distinguish code from knowledge
61
61
  - **Temporal knowledge graph** -- edges support `valid_from` / `valid_to` validity windows; `as_of` queries return point-in-time snapshots; `invalidate` action marks facts as ended without deleting them
@@ -134,23 +134,32 @@ node dist/server.js --port 3423
134
134
 
135
135
  ### Knowledge Base
136
136
 
137
- | Tool | Action | Description | Parameters |
138
- | ----------- | -------- | ----------------------------------- | ------------------------------------------------ |
139
- | `knowledge` | `list` | List entries by category and/or tag | `category?`, `tag?` |
140
- | | `read` | Read a specific entry | `path` (required) |
141
- | | `write` | Create/update entry (auto git sync) | `category`, `filename`, `content` (all required) |
142
- | | `delete` | Delete an entry (auto git sync) | `path` (required) |
143
- | | `sync` | Manual git pull + push | -- |
137
+ | Tool | Action | Description | Parameters |
138
+ | ----------- | -------- | ------------------------------------------------------------- | ------------------------------------------------ |
139
+ | `knowledge` | `list` | List entries by category and/or tag | `category?`, `tag?` |
140
+ | | `read` | Read a specific entry | `path` (required) |
141
+ | | `write` | Create/update entry (auto git sync) | `category`, `filename`, `content` (all required) |
142
+ | | `delete` | Delete an entry (auto git sync) | `path` (required) |
143
+ | | `sync` | Manual git pull + push | -- |
144
+ | | `wakeup` | Return L0 identity + L1 top-weighted entries (token-budgeted) | `token_budget?`, `category?` |
144
145
 
145
146
  ### Search
146
147
 
147
- | Tool | Description | Parameters |
148
- | ------------------ | ----------------------------------------------- | ------------------------------------------------------- |
149
- | `knowledge_search` | Hybrid semantic + TF-IDF search across sessions | `query`, `project?`, `role?`, `max_results?`, `ranked?` |
150
- | | Scoped recall (when `scope` is provided) | `query`, `scope`, `project?`, `max_results?` |
148
+ | Tool | Description | Parameters |
149
+ | ------------------ | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
150
+ | `knowledge_search` | General hybrid TF-IDF + semantic (no `scope`) | `query`, `project?`, `role?`, `max_results?`, `ranked?`, `semantic?`, `category?`, `category_mode?`, `mmr?`, `mmr_lambda?`, `explain?` |
151
+ | | Scoped session-only recall (when `scope` set) | `query`, `scope`, `project?`, `max_results?` |
152
+
153
+ Response shape: `{mode: "general" | "scoped", sessions, knowledge}`. Scoped mode returns `knowledge: []` by design.
151
154
 
152
155
  Scopes: `errors`, `plans`, `configs`, `tools`, `files`, `decisions`, `all`.
153
156
 
157
+ v1.8 search knobs:
158
+
159
+ - `mmr: true` applies Maximal Marginal Relevance re-ranking (kills near-duplicate clusters in top-K). `mmr_lambda` 0-1, default 0.7.
160
+ - `category_mode: "boost"` (default) gives matching-category entries a 1.25× score multiplier instead of dropping non-matches. Pass `"filter"` for legacy hard-filter behavior.
161
+ - `explain: true` attaches `score_components: {bm25, decay, maturity, confidence, category_boost, mmr_penalty}` to every knowledge hit.
162
+
154
163
  ### Sessions
155
164
 
156
165
  | Tool | Action | Description | Parameters |
@@ -189,10 +198,26 @@ Scopes: `errors`, `plans`, `configs`, `tools`, `files`, `decisions`, `all`.
189
198
 
190
199
  ### Admin
191
200
 
192
- | Tool | Action | Description | Parameters |
193
- | ----------------- | -------- | ---------------------------- | ------------------------------------------ |
194
- | `knowledge_admin` | `status` | Vector store statistics | -- |
195
- | | `config` | View or update configuration | `git_url?`, `memory_dir?`, `auto_distill?` |
201
+ | Tool | Action | Description | Parameters |
202
+ | ----------------- | -------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
203
+ | `knowledge_admin` | `status` | Vector store statistics | -- |
204
+ | | `config` | View or update configuration | `git_url?`, `memory_dir?`, `auto_distill?` |
205
+ | | `rebuild_embeddings` | Re-embed all knowledge entries (useful on provider switch) | -- |
206
+ | | `prune_orphans` | Delete embeddings for sessions no longer on disk | `vacuum?`, `force_vacuum?` |
207
+ | | `vacuum` | Reclaim free pages in the vector store | -- |
208
+ | | `promote` | Scored + gated promoter (v1.8) | `promote_mode?` (`apply`\|`explain`), `min_score?`, `min_recall_count?`, `min_unique_queries?` |
209
+
210
+ ### Scored promoter (v1.8)
211
+
212
+ Session insights no longer drop into the knowledge base via regex distillation. Instead, every project-level candidate is scored on six signals (relevance 0.30, frequency 0.24, query-diversity 0.15, recency 0.15, consolidation 0.10, conceptual-richness 0.06) and gated on `minScore ≥ 0.5`, `minRecallCount ≥ 2`, `minUniqueQueries ≥ 2`. All three gates must pass. Background auto-promotion is controlled by the same `auto_distill` config flag; invoke on demand with `knowledge_admin(action: "promote")`.
213
+
214
+ - `promote_mode: "explain"` (default) — score + gate candidates, write diary, DO NOT touch the KB.
215
+ - `promote_mode: "apply"` — promote candidates that pass, write diary, git-commit.
216
+ - Every run drops `~/agent-knowledge/.dreams/YYYY-MM-DD.md` with per-candidate signal breakdowns and gate outcomes. The `.`-prefixed dir is git-tracked but excluded from list/search.
217
+ - Grounded rehydration: a candidate is skipped if its source session file no longer exists on disk (prevents promoting deleted content).
218
+ - Entries with `evergreen: true` frontmatter are never overwritten by promotion — activity is appended.
219
+
220
+ Write-bench harness: `npm run bench:promote` — offline replay with auto-labeling by "referenced in later sessions". Compares gated promoter to a naive "ship all" baseline, reports precision / recall / F1. Use it to gate signal-weight or threshold changes before rolling them out.
196
221
 
197
222
  ## REST API
198
223
 
@@ -2,7 +2,7 @@
2
2
  "id": "agent-knowledge",
3
3
  "name": "Knowledge",
4
4
  "icon": "psychology",
5
- "version": "1.7.3",
5
+ "version": "1.8.0",
6
6
  "description": "Knowledge base — entries, sessions, search, graph relationships",
7
7
  "ui": "./dist/ui/app.js",
8
8
  "css": "./dist/ui/styles.css",
@@ -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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAkBH,eAAO,MAAM,cAAc;;;;;;;CAOjB,CAAC;AAEX,eAAO,MAAM,aAAa;;;;CAIhB,CAAC;AAIX,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,UAAU,CAAC;IACrB,cAAc,EAAE,UAAU,CAAC;IAC3B,gBAAgB,EAAE,UAAU,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,eAAe,CAAC;IACzB,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,YAAY,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,wGAAwG;IACxG,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,gCAAgC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6EAA6E;IAC7E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1B,UAAU,EAAE,gBAAgB,EAAE,CAAC;IAC/B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AA6BD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,iBAAiB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC/B,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnB,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnB,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAyFD,wBAAgB,cAAc,CAAC,CAAC,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,GAAG,eAAe,CAwC5E;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,CASzD;AAED,wBAAgB,aAAa,CAC3B,GAAG,EAAE,YAAY,EACjB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,GACjF,YAAY,CAiBd;AA0MD,wBAAsB,OAAO,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,aAAa,CAAC,CAgIlF"}