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.
- package/.claude-plugin/plugin.json +1 -1
- package/.mcp.json +1 -1
- package/CHANGELOG.md +43 -0
- package/README.md +43 -18
- package/agent-desk-plugin.json +1 -1
- package/dist/knowledge/promote.d.ts +145 -0
- package/dist/knowledge/promote.d.ts.map +1 -0
- package/dist/knowledge/promote.js +517 -0
- package/dist/knowledge/promote.js.map +1 -0
- package/dist/knowledge/scoring.d.ts +6 -2
- package/dist/knowledge/scoring.d.ts.map +1 -1
- package/dist/knowledge/scoring.js +7 -3
- package/dist/knowledge/scoring.js.map +1 -1
- package/dist/knowledge/search.d.ts +32 -5
- package/dist/knowledge/search.d.ts.map +1 -1
- package/dist/knowledge/search.js +60 -10
- package/dist/knowledge/search.js.map +1 -1
- package/dist/knowledge/store.d.ts +6 -0
- package/dist/knowledge/store.d.ts.map +1 -1
- package/dist/knowledge/store.js +10 -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 +307 -0
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +336 -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 +56 -17
- package/dist/tool-handlers.js.map +1 -1
- package/docs/ARCHITECTURE.md +31 -6
- package/docs/SETUP.md +20 -8
- package/docs/USER-MANUAL.md +146 -39
- 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
|
@@ -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.
|
|
4
|
+
"version": "1.8.0",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "keshrath"
|
|
7
7
|
},
|
package/.mcp.json
CHANGED
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)
|
|
4
4
|
[](https://nodejs.org)
|
|
5
|
-
[]()
|
|
6
6
|
[]()
|
|
7
7
|
[]()
|
|
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
|
-
- **
|
|
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
|
|
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
|
|
138
|
-
| ----------- | -------- |
|
|
139
|
-
| `knowledge` | `list` | List entries by category and/or tag
|
|
140
|
-
| | `read` | Read a specific entry
|
|
141
|
-
| | `write` | Create/update entry (auto git sync)
|
|
142
|
-
| | `delete` | Delete an entry (auto git sync)
|
|
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
|
|
148
|
-
| ------------------ |
|
|
149
|
-
| `knowledge_search` |
|
|
150
|
-
| | Scoped recall (when `scope`
|
|
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
|
|
193
|
-
| ----------------- |
|
|
194
|
-
| `knowledge_admin` | `status`
|
|
195
|
-
| | `config`
|
|
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
|
|
package/agent-desk-plugin.json
CHANGED
|
@@ -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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"}
|