pi-braid 0.43.7 → 0.43.9

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 (64) hide show
  1. package/CHANGELOG.md +72 -0
  2. package/TOOLS.md +1 -1
  3. package/build-info.json +4 -4
  4. package/dist/extensions/core/prompt-builder/tool-guidelines.js +1 -1
  5. package/dist/extensions/core/skills-tool/auto-inject.d.ts +21 -0
  6. package/dist/extensions/core/skills-tool/auto-inject.js +105 -1
  7. package/dist/extensions/core/skills-tool/index.js +20 -2
  8. package/dist/extensions/core/skills-tool/loading-guidance.d.ts +4 -1
  9. package/dist/extensions/core/skills-tool/loading-guidance.js +4 -1
  10. package/dist/extensions/core/skills-tool/session-records.d.ts +107 -9
  11. package/dist/extensions/core/skills-tool/session-records.js +141 -5
  12. package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.js +5 -1
  13. package/dist/extensions/enforcement/handlers/register-tool-call.js +5 -2
  14. package/dist/extensions/enforcement/verification-judge.d.ts +7 -0
  15. package/dist/extensions/enforcement/verification-judge.js +28 -21
  16. package/dist/extensions/memory/session-recall/ask.d.ts +95 -0
  17. package/dist/extensions/memory/session-recall/ask.js +376 -0
  18. package/dist/extensions/memory/session-recall/corpus-index.d.ts +200 -0
  19. package/dist/extensions/memory/session-recall/corpus-index.js +480 -0
  20. package/dist/extensions/memory/session-recall/index.js +173 -21
  21. package/dist/extensions/memory/session-recall/search.d.ts +29 -0
  22. package/dist/extensions/memory/session-recall/search.js +42 -9
  23. package/dist/lib/ai/payload-hygiene.d.ts +3 -0
  24. package/dist/lib/ai/payload-hygiene.js +34 -2
  25. package/dist/lib/config/braid-paths.d.ts +4 -0
  26. package/dist/lib/config/braid-paths.js +6 -0
  27. package/dist/lib/config/braid-settings.d.ts +44 -0
  28. package/dist/lib/config/braid-settings.js +41 -0
  29. package/dist/lib/detection/tool-loop-detector.d.ts +95 -46
  30. package/dist/lib/detection/tool-loop-detector.js +288 -180
  31. package/dist/lib/memory/constants.d.ts +38 -0
  32. package/dist/lib/memory/constants.js +196 -0
  33. package/dist/lib/memory/index.js +49 -10
  34. package/dist/lib/memory/lifecycle.d.ts +8 -0
  35. package/dist/lib/memory/lifecycle.js +43 -18
  36. package/dist/lib/reasoning/dreamer.d.ts +2 -1
  37. package/dist/lib/reasoning/dreamer.js +12 -7
  38. package/docs/LOCAL_DEV.md +1 -1
  39. package/docs/SETUP.md +2 -0
  40. package/package.json +1 -1
  41. package/src/extensions/core/AGENTS.md +3 -2
  42. package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
  43. package/src/extensions/core/skills-tool/auto-inject.ts +118 -1
  44. package/src/extensions/core/skills-tool/index.ts +21 -1
  45. package/src/extensions/core/skills-tool/loading-guidance.ts +4 -1
  46. package/src/extensions/core/skills-tool/session-records.ts +201 -9
  47. package/src/extensions/enforcement/handlers/analysis/dreamer-handler.ts +5 -1
  48. package/src/extensions/enforcement/handlers/register-tool-call.ts +5 -2
  49. package/src/extensions/enforcement/verification-judge.ts +32 -25
  50. package/src/extensions/memory/AGENTS.md +2 -2
  51. package/src/extensions/memory/session-recall/AGENTS.md +92 -18
  52. package/src/extensions/memory/session-recall/ask.ts +435 -0
  53. package/src/extensions/memory/session-recall/corpus-index.ts +609 -0
  54. package/src/extensions/memory/session-recall/index.ts +202 -21
  55. package/src/extensions/memory/session-recall/search.ts +61 -10
  56. package/src/lib/ai/payload-hygiene.ts +47 -3
  57. package/src/lib/config/braid-paths.ts +7 -0
  58. package/src/lib/config/braid-settings.ts +93 -3
  59. package/src/lib/detection/AGENTS.md +8 -7
  60. package/src/lib/detection/tool-loop-detector.ts +339 -195
  61. package/src/lib/memory/constants.ts +202 -0
  62. package/src/lib/memory/index.ts +59 -8
  63. package/src/lib/memory/lifecycle.ts +50 -16
  64. package/src/lib/reasoning/dreamer.ts +13 -6
@@ -22,6 +22,208 @@ export const MAX_ENTRIES = 200;
22
22
  export const MIN_UTILITY_THRESHOLD = 0.15;
23
23
  export const CONSOLIDATION_INTERVAL = 5;
24
24
 
25
+ // ── Recall scoring ───────────────────────────────────────────────────────────
26
+
27
+ /**
28
+ * Shortest token the matcher looks at. One- and two-character tokens carry no
29
+ * topic in any language this store sees, and matching them turns a query into
30
+ * a scan of nearly every entry.
31
+ */
32
+ export const QUERY_MIN_TOKEN_LENGTH = 3;
33
+
34
+ /**
35
+ * English function words, dropped from a query before matching. They name no
36
+ * topic, and counting each as a full word match is what let a long entry
37
+ * outrank a short quote that shared the question's actual subject.
38
+ *
39
+ * Generic vocabulary only. A word that names anything about this deployment,
40
+ * its files, or its roles belongs to that owner, not in a shared matcher.
41
+ */
42
+ export const QUERY_STOP_WORDS: ReadonlySet<string> = new Set([
43
+ "a",
44
+ "about",
45
+ "above",
46
+ "across",
47
+ "after",
48
+ "against",
49
+ "all",
50
+ "along",
51
+ "also",
52
+ "am",
53
+ "among",
54
+ "an",
55
+ "and",
56
+ "another",
57
+ "any",
58
+ "are",
59
+ "aren't",
60
+ "around",
61
+ "as",
62
+ "at",
63
+ "be",
64
+ "because",
65
+ "been",
66
+ "before",
67
+ "behind",
68
+ "being",
69
+ "below",
70
+ "beneath",
71
+ "beside",
72
+ "between",
73
+ "beyond",
74
+ "both",
75
+ "but",
76
+ "by",
77
+ "can",
78
+ "could",
79
+ "did",
80
+ "do",
81
+ "does",
82
+ "doesn't",
83
+ "doing",
84
+ "done",
85
+ "don't",
86
+ "during",
87
+ "each",
88
+ "either",
89
+ "every",
90
+ "except",
91
+ "few",
92
+ "for",
93
+ "from",
94
+ "had",
95
+ "has",
96
+ "have",
97
+ "having",
98
+ "he",
99
+ "her",
100
+ "hers",
101
+ "him",
102
+ "his",
103
+ "how",
104
+ "however",
105
+ "i",
106
+ "if",
107
+ "in",
108
+ "inside",
109
+ "into",
110
+ "is",
111
+ "isn't",
112
+ "it",
113
+ "its",
114
+ "just",
115
+ "many",
116
+ "may",
117
+ "me",
118
+ "might",
119
+ "mine",
120
+ "more",
121
+ "most",
122
+ "much",
123
+ "must",
124
+ "my",
125
+ "near",
126
+ "neither",
127
+ "no",
128
+ "nor",
129
+ "not",
130
+ "of",
131
+ "off",
132
+ "on",
133
+ "one",
134
+ "only",
135
+ "onto",
136
+ "or",
137
+ "other",
138
+ "our",
139
+ "ours",
140
+ "out",
141
+ "outside",
142
+ "over",
143
+ "own",
144
+ "per",
145
+ "same",
146
+ "shall",
147
+ "she",
148
+ "should",
149
+ "since",
150
+ "so",
151
+ "some",
152
+ "such",
153
+ "than",
154
+ "that",
155
+ "the",
156
+ "their",
157
+ "theirs",
158
+ "them",
159
+ "then",
160
+ "there",
161
+ "these",
162
+ "they",
163
+ "this",
164
+ "those",
165
+ "through",
166
+ "throughout",
167
+ "till",
168
+ "to",
169
+ "too",
170
+ "toward",
171
+ "two",
172
+ "under",
173
+ "until",
174
+ "up",
175
+ "upon",
176
+ "us",
177
+ "very",
178
+ "via",
179
+ "was",
180
+ "wasn't",
181
+ "we",
182
+ "were",
183
+ "weren't",
184
+ "what",
185
+ "when",
186
+ "where",
187
+ "which",
188
+ "while",
189
+ "who",
190
+ "whom",
191
+ "whose",
192
+ "why",
193
+ "will",
194
+ "with",
195
+ "within",
196
+ "without",
197
+ "would",
198
+ "yet",
199
+ "you",
200
+ "your",
201
+ "yours",
202
+ ]);
203
+
204
+ /**
205
+ * What a query-named tag is worth, in matched-word units: two ordinary terms.
206
+ * The shipped matcher counted a word as 1 and a tag as 2, so 2 keeps the
207
+ * shipped meaning now that a word's weight is a rarity weight instead.
208
+ */
209
+ export const MEMORY_TAG_BONUS_WORDS = 2;
210
+
211
+ /**
212
+ * Document-frequency fraction that fixes the "ordinary term" the weights are
213
+ * expressed in: a token carried by this share of the store. At 0.5 the
214
+ * reference weight is ln(1 + 1 / 0.5) = ln 3, and a tag is worth
215
+ * MEMORY_TAG_BONUS_WORDS of those.
216
+ */
217
+ export const MEMORY_REFERENCE_DF_FRACTION = 0.5;
218
+
219
+ /**
220
+ * Defaults for `braid.memory.reservedProvenance`. The partition ships OFF:
221
+ * which entries carry a provenance class is a property of the writer that
222
+ * filed them, so the operator names it with a source prefix. An empty prefix
223
+ * and a zero slot count both mean "no partition", leaving the prune as it was.
224
+ */
225
+ export const RESERVED_PROVENANCE_DEFAULTS = { prefix: "", slots: 0 } as const;
226
+
25
227
  export const CATEGORY_BASE_UTILITY: Record<CognitiveMemoryType, number> = {
26
228
  goal: 0.9,
27
229
  error: 0.8,
@@ -13,7 +13,14 @@ import type {
13
13
  MemoryContext,
14
14
  MemoryLink,
15
15
  } from "./types.js";
16
- import { MAX_ENTRIES, CONSOLIDATION_INTERVAL } from "./constants.js";
16
+ import {
17
+ MAX_ENTRIES,
18
+ CONSOLIDATION_INTERVAL,
19
+ QUERY_MIN_TOKEN_LENGTH,
20
+ QUERY_STOP_WORDS,
21
+ MEMORY_TAG_BONUS_WORDS,
22
+ MEMORY_REFERENCE_DF_FRACTION,
23
+ } from "./constants.js";
17
24
  import { loadMemory, saveMemory } from "./storage.js";
18
25
  import { generateAutoTags, generateId } from "./utils.js";
19
26
 
@@ -43,6 +50,20 @@ export {
43
50
  // are now in ./lifecycle.ts. The class below uses them.
44
51
  import { shouldStore, calculateUtility, pruneMemories, consolidate } from "./lifecycle.js";
45
52
 
53
+ /**
54
+ * The tokens a matcher can see: lowercase, split on everything except letters,
55
+ * digits and inner hyphens, and long enough to name something. Splitting the
56
+ * query this way is what lets a question ending in "APIs?" reach the stored
57
+ * token "apis" instead of carrying "apis?" to a substring test that can never
58
+ * match it. The same split runs over content, so a phrase test compares tokens
59
+ * with tokens instead of punctuation with punctuation.
60
+ */
61
+ function matchTokens(text: string): string[] {
62
+ return (text.toLowerCase().match(/[a-z0-9-]+/g) ?? []).filter(
63
+ (token) => token.length >= QUERY_MIN_TOKEN_LENGTH,
64
+ );
65
+ }
66
+
46
67
  // INTENTIONAL: CognitiveMemory is a cross-session knowledge base (memories
47
68
  // from past sessions inform new sessions via memory-recall). The singleton
48
69
  // pattern here means all callers share the same in-memory store, which is
@@ -331,12 +352,37 @@ export class CognitiveMemory {
331
352
  },
332
353
  ): Promise<Array<{ memory: CognitiveMemoryEntry; relevance: number }>> {
333
354
  const lowerQuery = query.toLowerCase();
334
- const queryWords = lowerQuery.split(/\s+/).filter((w) => w.length > 2);
355
+ const queryWords = matchTokens(lowerQuery).filter((word) => !QUERY_STOP_WORDS.has(word));
356
+ const phrase = queryWords.join(" ");
335
357
  const limit = options?.limit ?? 5;
336
358
 
359
+ // Rarity is measured over the live store, once per call: df(w) is the
360
+ // number of entries carrying w, and a matched word weighs ln(1 + N/df). A
361
+ // word no entry carries (df 0) earns the maximum weight, which is what a
362
+ // word the store has never seen should earn. What this buys: a store's
363
+ // common words stop deciding by count, so four of them no longer outweigh
364
+ // the one rare word a question is about.
365
+ const live = this.filterExpired(this.memoryStore.memories);
366
+ const contentTokens = new Map<string, string[]>();
367
+ const documentFrequency = new Map<string, number>();
368
+ for (const memory of live) {
369
+ const tokens = matchTokens(memory.content);
370
+ contentTokens.set(memory.id, tokens);
371
+ for (const token of new Set(tokens)) {
372
+ documentFrequency.set(token, (documentFrequency.get(token) ?? 0) + 1);
373
+ }
374
+ }
375
+ const idf = (word: string): number =>
376
+ Math.log(1 + live.length / Math.max(1, documentFrequency.get(word) ?? 1));
377
+ const phraseWeight = queryWords.reduce((sum, word) => sum + idf(word), 0);
378
+ // A tag stays worth MEMORY_TAG_BONUS_WORDS ordinary terms, measured at the
379
+ // reference document frequency, so the bonus keeps its shipped meaning on
380
+ // the rarity scale.
381
+ const tagBonus = MEMORY_TAG_BONUS_WORDS * Math.log(1 + 1 / MEMORY_REFERENCE_DF_FRACTION);
382
+
337
383
  const results: Array<{ memory: CognitiveMemoryEntry; relevance: number }> = [];
338
384
 
339
- for (const memory of this.filterExpired(this.memoryStore.memories)) {
385
+ for (const memory of live) {
340
386
  if (options?.type && memory.type !== options.type) continue;
341
387
  if (options?.tags?.length && !options.tags.some((t) => memory.tags.includes(t))) continue;
342
388
 
@@ -351,14 +397,19 @@ export class CognitiveMemory {
351
397
  continue;
352
398
  }
353
399
 
354
- const contentLower = memory.content.toLowerCase();
400
+ const haystack = (contentTokens.get(memory.id) ?? []).join(" ");
355
401
  let matches = 0;
356
- for (const word of queryWords) {
357
- if (contentLower.includes(word)) matches++;
402
+ if (phrase && haystack.includes(phrase)) {
403
+ // The whole normalized query, in order: the strongest lexical signal
404
+ // the store can offer, so it is scored as every term matched.
405
+ matches = phraseWeight;
406
+ } else {
407
+ for (const word of queryWords) {
408
+ if (haystack.includes(word)) matches += idf(word);
409
+ }
358
410
  }
359
- if (contentLower.includes(lowerQuery)) matches += queryWords.length;
360
411
  for (const tag of memory.tags) {
361
- if (lowerQuery.includes(tag.toLowerCase())) matches += 2;
412
+ if (lowerQuery.includes(tag.toLowerCase())) matches += tagBonus;
362
413
  }
363
414
 
364
415
  const relevance = matches * (0.5 + memory.utility * 0.5);
@@ -15,6 +15,7 @@
15
15
 
16
16
  import type { CognitiveMemoryEntry, CognitiveMemoryType, CognitiveMemoryStore } from "./types.js";
17
17
  import { jaccardSimilarity } from "./utils.js";
18
+ import { getMemoryReservedProvenance } from "../config/braid-settings.js";
18
19
 
19
20
  // ── Constants ────────────────────────────────────────────────────────────────
20
21
 
@@ -72,34 +73,67 @@ export function calculateUtility(
72
73
  }
73
74
 
74
75
  /**
75
- * Prune memories down to MAX_ENTRIES, keeping recent-access and
76
- * high-utility entries. Recent (last 5 min) entries are always kept.
77
- * Other entries are sorted by utility, then timestamp, and trimmed.
76
+ * The order the prune applies: a utility difference larger than 0.1 decides,
77
+ * and inside that tolerance the newer entry wins. Extracted so the reserved
78
+ * partition ranks its own population exactly as the general pool is ranked.
78
79
  */
79
- export function pruneMemories(memories: CognitiveMemoryEntry[]): CognitiveMemoryEntry[] {
80
+ function byUtilityThenRecency(a: CognitiveMemoryEntry, b: CognitiveMemoryEntry): number {
81
+ if (Math.abs(a.utility - b.utility) > 0.1) return b.utility - a.utility;
82
+ return b.timestamp - a.timestamp;
83
+ }
84
+
85
+ /**
86
+ * Keep the top `cap` entries: everything touched in the last five minutes is
87
+ * kept outside the competition for slots, and the rest is ranked by
88
+ * byUtilityThenRecency.
89
+ */
90
+ function pruneToCap(memories: CognitiveMemoryEntry[], cap: number): CognitiveMemoryEntry[] {
80
91
  const now = Date.now();
81
92
  const RECENT_ACCESS_MS = 5 * 60 * 1000;
82
93
 
83
94
  const recent = memories.filter((m) => now - m.lastAccessed < RECENT_ACCESS_MS);
84
95
  const others = memories.filter((m) => now - m.lastAccessed >= RECENT_ACCESS_MS);
85
96
 
86
- const sorted = [...others].sort((a, b) => {
87
- if (Math.abs(a.utility - b.utility) > 0.1) return b.utility - a.utility;
88
- return b.timestamp - a.timestamp;
89
- });
97
+ const sorted = [...others].sort(byUtilityThenRecency);
90
98
 
91
- const remainingSlots = Math.max(0, MAX_ENTRIES - recent.length);
99
+ const remainingSlots = Math.max(0, cap - recent.length);
92
100
  const pruned = sorted
93
101
  .filter((m, i) => i < remainingSlots || m.utility >= MIN_UTILITY_THRESHOLD)
94
102
  .slice(0, remainingSlots);
95
103
 
96
- const combined = [...recent, ...pruned];
97
- return combined
98
- .sort((a, b) => {
99
- if (Math.abs(a.utility - b.utility) > 0.1) return b.utility - a.utility;
100
- return b.timestamp - a.timestamp;
101
- })
102
- .slice(0, MAX_ENTRIES);
104
+ return [...recent, ...pruned].sort(byUtilityThenRecency).slice(0, cap);
105
+ }
106
+
107
+ /**
108
+ * Prune memories down to MAX_ENTRIES, keeping recent-access and
109
+ * high-utility entries. Recent (last 5 min) entries are always kept.
110
+ * Other entries are sorted by utility, then timestamp, and trimmed.
111
+ *
112
+ * A configured partition (`braid.memory.reservedProvenance`) takes its slots
113
+ * first: entries whose `source` starts with the configured prefix may occupy
114
+ * up to `slots` of the cap, and everything else, including class entries that
115
+ * did not win a slot, competes for what remains. The class arrives as
116
+ * configuration because which entries carry provenance is a property of the
117
+ * writer that filed them; the store only reads the prefix as an opaque
118
+ * string. Absent or zero, this function is the prune it always was.
119
+ */
120
+ export function pruneMemories(memories: CognitiveMemoryEntry[]): CognitiveMemoryEntry[] {
121
+ const { prefix, slots } = getMemoryReservedProvenance();
122
+ const classEntries =
123
+ prefix && slots > 0
124
+ ? memories.filter(
125
+ (memory) => typeof memory.source === "string" && memory.source.startsWith(prefix),
126
+ )
127
+ : [];
128
+ if (classEntries.length === 0) return pruneToCap(memories, MAX_ENTRIES);
129
+
130
+ const reserved = [...classEntries].sort(byUtilityThenRecency).slice(0, slots);
131
+ const reservedIds = new Set(reserved.map((memory) => memory.id));
132
+ const general = pruneToCap(
133
+ memories.filter((memory) => !reservedIds.has(memory.id)),
134
+ Math.max(0, MAX_ENTRIES - reserved.length),
135
+ );
136
+ return [...reserved, ...general];
103
137
  }
104
138
 
105
139
  /**
@@ -12,6 +12,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
12
12
  import { getExtensionState } from "../state/extension-state.js";
13
13
  import { dreamerCooldownMs as dynamicCooldown } from "../reasoning/advice-tracker.js";
14
14
  import { detectToolLoopFromSequence } from "../detection/tool-loop-detector.js";
15
+ import type { ToolCallLike } from "../detection/tool-loop-detector.js";
15
16
 
16
17
  // ── Types ───────────────────────────────────────────────────────────────────
17
18
 
@@ -131,6 +132,7 @@ export function dream(
131
132
  ctx: ExtensionContext,
132
133
  currentSequence: string[],
133
134
  historicalSequences?: string[][],
135
+ loopSequence?: ToolCallLike[],
134
136
  ): DreamAdvice | null {
135
137
  const state = getState(ctx);
136
138
  const now = Date.now();
@@ -139,12 +141,17 @@ export function dream(
139
141
  if (now - state.lastDreamAt < dynamicCooldown) return null;
140
142
 
141
143
  // Path 1: detect a tool loop in the current sequence (consecutive-
142
- // same-tool heuristic). The threshold, window, cooldown, and message
143
- // format are all owned by lib/detection/tool-loop-detector - the single
144
- // source of truth. Delegating avoids the contradictory-whisper failure:
145
- // separate detectors with separate thresholds firing in one turn hand
146
- // the agent conflicting remedies.
147
- const loopResult = detectToolLoopFromSequence(currentSequence);
144
+ // same-call heuristic). The threshold, window, cooldown, identity rule, and
145
+ // message format are all owned by lib/detection/tool-loop-detector - the
146
+ // single source of truth. Delegating avoids the contradictory-whisper
147
+ // failure: separate detectors with separate thresholds firing in one turn
148
+ // hand the agent conflicting remedies.
149
+ //
150
+ // loopSequence carries the recorded calls (name + argument identity). A
151
+ // caller that holds only the name log passes nothing, and the detector then
152
+ // returns no loop: names cannot show one call repeating, only one name
153
+ // repeating.
154
+ const loopResult = detectToolLoopFromSequence(loopSequence ?? currentSequence);
148
155
  if (loopResult.isLoop) {
149
156
  state.lastDreamAt = now;
150
157
  return {