pi-braid 0.43.8 → 0.43.11

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.
@@ -0,0 +1,348 @@
1
+ /**
2
+ * Decision grammar: the generic half of the ruling write path.
3
+ *
4
+ * One body of text in, either the standing instruction it carries or `null`.
5
+ * "Generic" is a claim about what the module is allowed to know: sentence
6
+ * spans, the marker table that turns a sentence into a standing instruction,
7
+ * the shapes that are not instructions (a question, a status report, a paste, a
8
+ * hedge, a conversational aside), and the first- and second-person grammar of
9
+ * English. It knows nothing about who wrote the text, which channel carried it,
10
+ * or what the caller's world is made of.
11
+ *
12
+ * The last of those is the one thing a grammar cannot supply, so the caller
13
+ * hands it in as `GrammarVocabulary`: which words name a subject a ruling can be
14
+ * about, which words describe the caller's own machinery, and how an explicit
15
+ * generalization reads. `classifyRulingBody()` applies those three tests at the
16
+ * same two places it applies its own - the turn and the sentence that gets
17
+ * quoted - so a directive aimed at the reader is told apart from a rule about
18
+ * the system by vocabulary this layer never spells.
19
+ *
20
+ * The second half of the module is the store side of the same write path:
21
+ * `deriveTopicTags()` reads a quote and the population it is filed into and
22
+ * returns the words worth carrying as tags. The rule reasons about tokens,
23
+ * document frequency and a generic English stop list, so it belongs next to the
24
+ * grammar rather than in the caller's vocabulary.
25
+ *
26
+ * Pure by construction: no I/O, no clock, no randomness, so its behaviour is a
27
+ * fixture instead of a story.
28
+ */
29
+ import { QUERY_STOP_WORDS } from "./constants.js";
30
+ /** Longest quote the caller receives; past this the quote is cut, not summarized. */
31
+ export const QUOTE_LIMIT = 400;
32
+ /**
33
+ * A body longer than this is a pasted brief, a log or a tool dump, not the
34
+ * sentence an owner states a ruling in. The quote is capped at QUOTE_LIMIT
35
+ * anyway, so a long body can only contribute a fragment whose subject was three
36
+ * paragraphs earlier.
37
+ */
38
+ const MAX_TURN_CHARS = 1200;
39
+ /** Below this a body is an acknowledgement ("ok", "proceed"), never a ruling. */
40
+ const MIN_TURN_WORDS = 3;
41
+ /** A continuation sentence is kept only while the quote stays short enough to read. */
42
+ const CONTINUATION_LIMIT = 200;
43
+ /** The owner's own voice: first person, singular or collective. */
44
+ const FIRST_PERSON = /\b(?:i|i'm|i've|i'll|i'd|we|we're|we've|we'll|we'd|my|our|ours|let's)\b/i;
45
+ /**
46
+ * Second-person address. A directive written to *you* is an instruction for
47
+ * the reader; a rule for the system talks about it, or generalizes explicitly.
48
+ */
49
+ const SECOND_PERSON = /\b(?:you|your|yours|yourself|yourselves)\b/i;
50
+ /**
51
+ * First-person report voice: the speaker narrating what was seen, changed or
52
+ * disabled. Such a sentence can carry "always" or "no longer" by accident ("I
53
+ * still see only ...", "it no longer indexed"), so it is refused unless it opens
54
+ * with a directive.
55
+ */
56
+ const REPORT_VOICE = /\b(?:i|we)\b[^.!?]{0,120}\b(?:noticed|noticing|see|saw|seen|disabled|enabled|changed|updated|merged|pushed|committed|created|deleted|found|think|thought|guess|believe|realised|realized|checked|ran|built|fixed|added|removed|renamed|replaced|read|told|said|mentioned)\b/i;
57
+ /**
58
+ * Conversational openers that carry no decision: thinking aloud. A marker
59
+ * inside one of these ("doesn't really matter") is not a ruling.
60
+ */
61
+ const CONVERSATIONAL = /^\s*(?:or i don'?t know|i don'?t know|not sure|doesn'?t really matter|whatever|never mind|nevermind)\b/i;
62
+ /** A body that reads as a report of work already done, on its first line. */
63
+ const STATUS_OPENER = /^(?:done|finished|merged|shipped|pushed|committed|built|fixed|updated|completed|released|deployed|landed|green|all (?:tests|gates|checks)|tests? (?:pass|green)|gates? (?:pass|green))/i;
64
+ /**
65
+ * Hedged advice: the shape of a recommendation that was floated and not
66
+ * adopted. `should` and `could` are deliberately absent from the durable
67
+ * marker table below - they are how advice is phrased, not how a ruling is
68
+ * stated - so a hedged sentence has to be refused explicitly.
69
+ */
70
+ const HEDGE = /\b(?:maybe|perhaps|might|could|would|possibly|probably|consider|i think|i guess|not sure|unsure|what if|why not|we should probably)\b/i;
71
+ /**
72
+ * Absolute frames that make a hedged sentence a ruling anyway: "maybe we should
73
+ * never post through an API" has still ruled, while "we could consider APIs"
74
+ * has not.
75
+ */
76
+ const ABSOLUTE = /\b(?:never|must|always|only one|required|mandatory|forbidden|banned|not allowed|by default|from now on|going forward)\b/i;
77
+ /**
78
+ * Opening words that make a sentence a question, used only together with a
79
+ * question mark: the mark alone is enough at the end of a body, but a body that
80
+ * opens with a question and closes with a ruling keeps its ruling.
81
+ */
82
+ const INTERROGATIVE_OPENER = /^\s*(?:how|what|why|when|where|which|who|whose|whether)\b/i;
83
+ const QUESTION_OPENER = /^(?:should|shall|can|could|may|might|do|does|did|is|are|was|were|will|would|have|has|how|what|why|when|where|which|who|whose|am|if)\b/i;
84
+ /**
85
+ * Decision frames, in class-priority order. A frame is the grammar of a
86
+ * standing instruction rather than of this turn's work: an absolute (`never`,
87
+ * `always`, `must`, `only one`), a comparison between ways of doing something
88
+ * (`prefer`, `instead of`, `rather than`, `better than`), or a prescription
89
+ * stated in the collective voice (`we need to`, `should`). Bare imperatives are
90
+ * deliberately absent: "investigate X" is a task for this turn, and a table
91
+ * built from every imperative is a task list filed as policy.
92
+ */
93
+ const MARKERS = [
94
+ {
95
+ class: "prohibition",
96
+ pattern: /\b(?:never|don't|do not|must not|may not|not allowed|forbidden|banned|no longer|stop (?:using|doing|running|adding|writing|posting|editing|treating))\b/i,
97
+ },
98
+ {
99
+ class: "preference",
100
+ pattern: /\b(?:prefer|preferably|instead of|rather than|better than|avoid)\b/i,
101
+ },
102
+ {
103
+ class: "requirement",
104
+ pattern: /\b(?:must|should|always|required|mandatory|only one|need(?:s)? to|have to|has to)\b/i,
105
+ },
106
+ {
107
+ class: "policy",
108
+ pattern: /\b(?:by default|default is|from now on|going forward|rule is|policy|standard|convention|principle)\b/i,
109
+ },
110
+ ];
111
+ /** Abbreviations whose period does not end a sentence. */
112
+ const ABBREVIATION = /(?:^|[\s(])(?:e\.g|i\.e|etc|vs|cf|approx|resp|no|dr|mr|mrs|ms|st)\.$/i;
113
+ /**
114
+ * Split a body into contiguous sentence spans.
115
+ *
116
+ * The spans are offsets into the original string, so a quote assembled from
117
+ * them is a byte-for-byte slice of the words - the property the pointer check
118
+ * leans on. Newlines end a sentence; a period does not end one inside a known
119
+ * abbreviation, a number (`3.5`), or a path (`decision-grammar.ts`).
120
+ */
121
+ function sentenceSpans(text) {
122
+ const spans = [];
123
+ let start = 0;
124
+ const push = (end) => {
125
+ if (end > start) {
126
+ const slice = text.slice(start, end);
127
+ if (slice.trim())
128
+ spans.push({ start, end });
129
+ }
130
+ start = end;
131
+ };
132
+ for (let i = 0; i < text.length; i++) {
133
+ const ch = text[i];
134
+ if (ch === "\n") {
135
+ push(i);
136
+ continue;
137
+ }
138
+ if (ch !== "." && ch !== "!" && ch !== "?")
139
+ continue;
140
+ const next = text[i + 1];
141
+ if (next !== undefined && !/\s/.test(next))
142
+ continue;
143
+ if (ch === "." && ABBREVIATION.test(text.slice(Math.max(0, i - 12), i + 1)))
144
+ continue;
145
+ if (ch === "." && /\d$/.test(text[i - 1] ?? "") && /^\d/.test(next ?? ""))
146
+ continue;
147
+ push(i + 1);
148
+ }
149
+ push(text.length);
150
+ return spans;
151
+ }
152
+ /** Words in a string, counted the way a reader would. */
153
+ function wordCount(text) {
154
+ return text.split(/\s+/).filter(Boolean).length;
155
+ }
156
+ /**
157
+ * Is the body a paste - a shell transcript, a code block, a log or a payload?
158
+ *
159
+ * A pasted command is the single most common false ruling: it carries
160
+ * imperatives ("rm -rf"), digits, and often the word "only". The screens are
161
+ * cheap because a ruling sentence is prose, and prose does not start every line
162
+ * with a prompt, a box, or a stack frame.
163
+ */
164
+ function looksPasted(text) {
165
+ if (text.includes("```"))
166
+ return true;
167
+ if (/^\s*[{[]/.test(text))
168
+ return true;
169
+ if (/^\s*(?:\$|%|> |#!)\s/m.test(text))
170
+ return true;
171
+ if (/(?:^|\n)\s*(?:[│├└─]|\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2})/m.test(text))
172
+ return true;
173
+ if (/Traceback \(most recent call last\)|\bat [\w$.]+ \([\w/.-]+:\d+:\d+\)/.test(text))
174
+ return true;
175
+ const lines = text.split("\n").filter((line) => line.trim());
176
+ const commandLines = lines.filter((line) => /^\s*(?:sudo |git |npm |npx |node |python3? |cd |ls |cat |rg |grep |curl |chmod |brew |make |docker |kubectl |export |rm )/.test(line));
177
+ if (commandLines.length >= 2)
178
+ return true;
179
+ // A payload of paths and key=value rows, with almost no sentence structure.
180
+ if (lines.length >= 6 && lines.every((line) => line.length < 200)) {
181
+ const payloadish = lines.filter((line) => /^[\w./-]{2,}\s*[:=]\s*\S/.test(line));
182
+ if (payloadish.length >= lines.length / 2)
183
+ return true;
184
+ }
185
+ return false;
186
+ }
187
+ /** Does the body end in a question, or open with one and carry nothing after it? */
188
+ function isQuestionShaped(text, spans) {
189
+ const trimmed = text.trimEnd();
190
+ if (trimmed.endsWith("?"))
191
+ return true;
192
+ const first = spans[0] ? text.slice(spans[0].start, spans[0].end).trim() : "";
193
+ return QUESTION_OPENER.test(first) && first.includes("?") && spans.length === 1;
194
+ }
195
+ /**
196
+ * The class a sentence marks, or `null` when it marks no standing instruction.
197
+ * First match in table order wins, so "must never" reads as a prohibition and
198
+ * "always prefer" as a preference.
199
+ */
200
+ function markerClass(sentence) {
201
+ for (const { class: kind, pattern } of MARKERS) {
202
+ if (pattern.test(sentence))
203
+ return kind;
204
+ }
205
+ return null;
206
+ }
207
+ /**
208
+ * Assemble the quote: the sentence that carries the marker, plus its immediate
209
+ * continuation while that stays short. Contiguous, never reordered, never
210
+ * stitched from two places in the body.
211
+ */
212
+ function quoteFrom(text, spans, markerIndex) {
213
+ let end = spans[markerIndex].end;
214
+ const next = spans[markerIndex + 1];
215
+ if (next) {
216
+ const candidate = text.slice(spans[markerIndex].start, next.end);
217
+ if (candidate.length <= CONTINUATION_LIMIT)
218
+ end = next.end;
219
+ }
220
+ const quote = text.slice(spans[markerIndex].start, end).trim();
221
+ if (quote.length <= QUOTE_LIMIT)
222
+ return quote;
223
+ return `${quote.slice(0, QUOTE_LIMIT).trimEnd()}...`;
224
+ }
225
+ /**
226
+ * Classify one body that is already known to be owner speech.
227
+ *
228
+ * Returns `null` for everything that is not a standing instruction: a question,
229
+ * a paste, a status report, a hedged recommendation, an acknowledgement, a
230
+ * second-person directive, or a body too long to cut a self-contained sentence
231
+ * from. Returns the class and the verbatim quote otherwise. The caller owns the
232
+ * provenance fields, because the caller is the one that knows where the text
233
+ * came from.
234
+ */
235
+ export function classifyRulingBody(text, vocabulary) {
236
+ if (typeof text !== "string")
237
+ return null;
238
+ const body = text.trim();
239
+ if (!body)
240
+ return null;
241
+ if (wordCount(body) < MIN_TURN_WORDS)
242
+ return null;
243
+ if (body.length > MAX_TURN_CHARS)
244
+ return null;
245
+ if (looksPasted(body))
246
+ return null;
247
+ const spans = sentenceSpans(body);
248
+ if (spans.length === 0)
249
+ return null;
250
+ if (isQuestionShaped(body, spans))
251
+ return null;
252
+ const firstSentence = body.slice(spans[0].start, spans[0].end).trim();
253
+ if (STATUS_OPENER.test(firstSentence))
254
+ return null;
255
+ if (INTERROGATIVE_OPENER.test(firstSentence))
256
+ return null;
257
+ const firstPerson = FIRST_PERSON.test(body);
258
+ if (SECOND_PERSON.test(body) && !vocabulary.generalizes(body))
259
+ return null;
260
+ if (!firstPerson && !vocabulary.namesSubject(body))
261
+ return null;
262
+ if (!firstPerson && vocabulary.talksProcess(body))
263
+ return null;
264
+ for (let index = 0; index < spans.length; index++) {
265
+ const sentence = body.slice(spans[index].start, spans[index].end).trim();
266
+ const kind = markerClass(sentence);
267
+ if (!kind)
268
+ continue;
269
+ if (STATUS_OPENER.test(sentence))
270
+ continue;
271
+ if (CONVERSATIONAL.test(sentence))
272
+ continue;
273
+ if (sentence.includes("?"))
274
+ continue;
275
+ if (SECOND_PERSON.test(sentence) && !vocabulary.generalizes(sentence))
276
+ continue;
277
+ // The same voice test the body passed, applied to the sentence that will
278
+ // be quoted: a bare directive lifted out of a longer message is an
279
+ // instruction for the reader, not a decision about the system.
280
+ const sentenceFirstPerson = FIRST_PERSON.test(sentence);
281
+ if (!sentenceFirstPerson && !vocabulary.namesSubject(sentence))
282
+ continue;
283
+ if (!sentenceFirstPerson && vocabulary.talksProcess(sentence))
284
+ continue;
285
+ if (REPORT_VOICE.test(sentence) &&
286
+ !/^\s*(?:never|always|prefer|must not|by default|from now on)/i.test(sentence)) {
287
+ continue;
288
+ }
289
+ if (HEDGE.test(sentence) && !ABSOLUTE.test(sentence))
290
+ continue;
291
+ const quote = quoteFrom(body, spans, index);
292
+ if (!quote)
293
+ continue;
294
+ return { class: kind, quote };
295
+ }
296
+ return null;
297
+ }
298
+ // ── Tag derivation ──────────────────────────────────────────────────────────
299
+ /** How many tags a ruling carries. */
300
+ export const TAG_LIMIT = 3;
301
+ /** Shortest token a tag may be cut from. */
302
+ const TAG_TOKEN_MIN_LENGTH = 4;
303
+ /**
304
+ * The share of the population past which a token names nothing. A word a
305
+ * quarter of the store already carries is the store's background, not a topic:
306
+ * it would fire on every query and add nothing a reader could act on.
307
+ */
308
+ const TAG_POPULATION_SHARE = 0.25;
309
+ /** Tokens a tag may be cut from: letters, then letters/digits/hyphens. */
310
+ const TAG_TOKEN = /[a-z][a-z0-9-]{3,}/g;
311
+ /**
312
+ * The tags a quote earns from the population it is filed into.
313
+ *
314
+ * Take the quote's tokens of four characters or more, drop the read path's stop
315
+ * words, drop any token more than a quarter of the population carries, and keep
316
+ * the three the population carries most, ties by first occurrence.
317
+ *
318
+ * The ranking is by frequency and not by rarity, and the reason is the read
319
+ * path's own arithmetic: a tag's bonus is a flat constant however rare the
320
+ * token is, so rarity buys nothing a later query will say. Two tokens of equal
321
+ * rarity are worth the same as tags, and the one a question is likelier to name
322
+ * is the one the population's own prose uses more often. That makes the
323
+ * frequency ranking the findability ranking, and it leaves the 25% cap as the
324
+ * only guard against a tag that names nothing.
325
+ */
326
+ export function deriveTopicTags(text, population, limit = TAG_LIMIT) {
327
+ const ceiling = population.total * TAG_POPULATION_SHARE;
328
+ const seen = new Set();
329
+ const candidates = [];
330
+ for (const token of String(text ?? "")
331
+ .toLowerCase()
332
+ .match(TAG_TOKEN) ?? []) {
333
+ if (token.length < TAG_TOKEN_MIN_LENGTH)
334
+ continue;
335
+ if (QUERY_STOP_WORDS.has(token))
336
+ continue;
337
+ if (seen.has(token))
338
+ continue;
339
+ seen.add(token);
340
+ const count = population.count(token);
341
+ if (count > ceiling)
342
+ continue;
343
+ candidates.push({ token, count, first: candidates.length });
344
+ }
345
+ candidates.sort((a, b) => b.count - a.count || a.first - b.first);
346
+ return candidates.slice(0, limit).map((candidate) => candidate.token);
347
+ }
348
+ //# sourceMappingURL=decision-grammar.js.map
@@ -7,6 +7,7 @@
7
7
  import type { CognitiveMemoryType, CognitiveMemoryEntry, CognitiveMemoryStore, MemoryContext, MemoryLink } from "./types.js";
8
8
  export type { CognitiveMemoryType, MemorySource, MemoryContext, MemoryLink, CognitiveMemoryEntry, CognitiveMemoryStore, } from "./types.js";
9
9
  export { formatMemoryTimestamp, formatMemoryEntry, parseStructuredContent, generateAutoTags, } from "./utils.js";
10
+ export { classifyRulingBody, deriveTopicTags, QUOTE_LIMIT, TAG_LIMIT, type GrammarVocabulary, type RulingClass, type RulingShape, type TagPopulation, } from "./decision-grammar.js";
10
11
  export declare function getCognitiveMemory(): CognitiveMemory;
11
12
  export declare class CognitiveMemory {
12
13
  private memoryStore;
@@ -5,7 +5,7 @@
5
5
  * helpers are in sibling modules (types.ts, constants.ts, storage.ts, utils.ts).
6
6
  */
7
7
  import { createLogger } from "../core/logger.js";
8
- import { MAX_ENTRIES, CONSOLIDATION_INTERVAL } from "./constants.js";
8
+ import { MAX_ENTRIES, CONSOLIDATION_INTERVAL, QUERY_MIN_TOKEN_LENGTH, QUERY_STOP_WORDS, MEMORY_TAG_BONUS_WORDS, MEMORY_REFERENCE_DF_FRACTION, } from "./constants.js";
9
9
  import { loadMemory, saveMemory } from "./storage.js";
10
10
  import { generateAutoTags, generateId } from "./utils.js";
11
11
  // MAX_ENTRIES, MIN_UTILITY_THRESHOLD, CATEGORY_BASE_UTILITY are
@@ -13,10 +13,22 @@ import { generateAutoTags, generateId } from "./utils.js";
13
13
  // CONSOLIDATION_INTERVAL stays here.
14
14
  const _log = createLogger("semantic-memory");
15
15
  export { formatMemoryTimestamp, formatMemoryEntry, parseStructuredContent, generateAutoTags, } from "./utils.js";
16
+ export { classifyRulingBody, deriveTopicTags, QUOTE_LIMIT, TAG_LIMIT, } from "./decision-grammar.js";
16
17
  // shouldStore, calculateUtility, pruneMemories, consolidate, and the
17
18
  // constants (MAX_ENTRIES, MIN_UTILITY_THRESHOLD, CATEGORY_BASE_UTILITY)
18
19
  // are now in ./lifecycle.ts. The class below uses them.
19
20
  import { shouldStore, calculateUtility, pruneMemories, consolidate } from "./lifecycle.js";
21
+ /**
22
+ * The tokens a matcher can see: lowercase, split on everything except letters,
23
+ * digits and inner hyphens, and long enough to name something. Splitting the
24
+ * query this way is what lets a question ending in "APIs?" reach the stored
25
+ * token "apis" instead of carrying "apis?" to a substring test that can never
26
+ * match it. The same split runs over content, so a phrase test compares tokens
27
+ * with tokens instead of punctuation with punctuation.
28
+ */
29
+ function matchTokens(text) {
30
+ return (text.toLowerCase().match(/[a-z0-9-]+/g) ?? []).filter((token) => token.length >= QUERY_MIN_TOKEN_LENGTH);
31
+ }
20
32
  // INTENTIONAL: CognitiveMemory is a cross-session knowledge base (memories
21
33
  // from past sessions inform new sessions via memory-recall). The singleton
22
34
  // pattern here means all callers share the same in-memory store, which is
@@ -245,10 +257,33 @@ export class CognitiveMemory {
245
257
  }
246
258
  async recall(query, options) {
247
259
  const lowerQuery = query.toLowerCase();
248
- const queryWords = lowerQuery.split(/\s+/).filter((w) => w.length > 2);
260
+ const queryWords = matchTokens(lowerQuery).filter((word) => !QUERY_STOP_WORDS.has(word));
261
+ const phrase = queryWords.join(" ");
249
262
  const limit = options?.limit ?? 5;
263
+ // Rarity is measured over the live store, once per call: df(w) is the
264
+ // number of entries carrying w, and a matched word weighs ln(1 + N/df). A
265
+ // word no entry carries (df 0) earns the maximum weight, which is what a
266
+ // word the store has never seen should earn. What this buys: a store's
267
+ // common words stop deciding by count, so four of them no longer outweigh
268
+ // the one rare word a question is about.
269
+ const live = this.filterExpired(this.memoryStore.memories);
270
+ const contentTokens = new Map();
271
+ const documentFrequency = new Map();
272
+ for (const memory of live) {
273
+ const tokens = matchTokens(memory.content);
274
+ contentTokens.set(memory.id, tokens);
275
+ for (const token of new Set(tokens)) {
276
+ documentFrequency.set(token, (documentFrequency.get(token) ?? 0) + 1);
277
+ }
278
+ }
279
+ const idf = (word) => Math.log(1 + live.length / Math.max(1, documentFrequency.get(word) ?? 1));
280
+ const phraseWeight = queryWords.reduce((sum, word) => sum + idf(word), 0);
281
+ // A tag stays worth MEMORY_TAG_BONUS_WORDS ordinary terms, measured at the
282
+ // reference document frequency, so the bonus keeps its shipped meaning on
283
+ // the rarity scale.
284
+ const tagBonus = MEMORY_TAG_BONUS_WORDS * Math.log(1 + 1 / MEMORY_REFERENCE_DF_FRACTION);
250
285
  const results = [];
251
- for (const memory of this.filterExpired(this.memoryStore.memories)) {
286
+ for (const memory of live) {
252
287
  if (options?.type && memory.type !== options.type)
253
288
  continue;
254
289
  if (options?.tags?.length && !options.tags.some((t) => memory.tags.includes(t)))
@@ -261,17 +296,22 @@ export class CognitiveMemory {
261
296
  memory.projectId !== options.currentProject) {
262
297
  continue;
263
298
  }
264
- const contentLower = memory.content.toLowerCase();
299
+ const haystack = (contentTokens.get(memory.id) ?? []).join(" ");
265
300
  let matches = 0;
266
- for (const word of queryWords) {
267
- if (contentLower.includes(word))
268
- matches++;
301
+ if (phrase && haystack.includes(phrase)) {
302
+ // The whole normalized query, in order: the strongest lexical signal
303
+ // the store can offer, so it is scored as every term matched.
304
+ matches = phraseWeight;
305
+ }
306
+ else {
307
+ for (const word of queryWords) {
308
+ if (haystack.includes(word))
309
+ matches += idf(word);
310
+ }
269
311
  }
270
- if (contentLower.includes(lowerQuery))
271
- matches += queryWords.length;
272
312
  for (const tag of memory.tags) {
273
313
  if (lowerQuery.includes(tag.toLowerCase()))
274
- matches += 2;
314
+ matches += tagBonus;
275
315
  }
276
316
  const relevance = matches * (0.5 + memory.utility * 0.5);
277
317
  if (relevance > 0) {
@@ -37,6 +37,14 @@ export declare function calculateUtility(type: CognitiveMemoryType, content: str
37
37
  * Prune memories down to MAX_ENTRIES, keeping recent-access and
38
38
  * high-utility entries. Recent (last 5 min) entries are always kept.
39
39
  * Other entries are sorted by utility, then timestamp, and trimmed.
40
+ *
41
+ * A configured partition (`braid.memory.reservedProvenance`) takes its slots
42
+ * first: entries whose `source` starts with the configured prefix may occupy
43
+ * up to `slots` of the cap, and everything else, including class entries that
44
+ * did not win a slot, competes for what remains. The class arrives as
45
+ * configuration because which entries carry provenance is a property of the
46
+ * writer that filed them; the store only reads the prefix as an opaque
47
+ * string. Absent or zero, this function is the prune it always was.
40
48
  */
41
49
  export declare function pruneMemories(memories: CognitiveMemoryEntry[]): CognitiveMemoryEntry[];
42
50
  /**
@@ -13,6 +13,7 @@
13
13
  * a new CognitiveMemoryStore with the consolidated state.
14
14
  */
15
15
  import { jaccardSimilarity } from "./utils.js";
16
+ import { getMemoryReservedProvenance } from "../config/braid-settings.js";
16
17
  // ── Constants ────────────────────────────────────────────────────────────────
17
18
  const GENERIC_CONTENT_PATTERNS = [/auto-captured memory from enforcement/i, /auto-captured/i];
18
19
  // Re-exported for the CognitiveMemory class which also gates on these.
@@ -59,32 +60,56 @@ export function calculateUtility(type, content, importance) {
59
60
  return base * 0.7 + importance * 0.3;
60
61
  }
61
62
  /**
62
- * Prune memories down to MAX_ENTRIES, keeping recent-access and
63
- * high-utility entries. Recent (last 5 min) entries are always kept.
64
- * Other entries are sorted by utility, then timestamp, and trimmed.
63
+ * The order the prune applies: a utility difference larger than 0.1 decides,
64
+ * and inside that tolerance the newer entry wins. Extracted so the reserved
65
+ * partition ranks its own population exactly as the general pool is ranked.
65
66
  */
66
- export function pruneMemories(memories) {
67
+ function byUtilityThenRecency(a, b) {
68
+ if (Math.abs(a.utility - b.utility) > 0.1)
69
+ return b.utility - a.utility;
70
+ return b.timestamp - a.timestamp;
71
+ }
72
+ /**
73
+ * Keep the top `cap` entries: everything touched in the last five minutes is
74
+ * kept outside the competition for slots, and the rest is ranked by
75
+ * byUtilityThenRecency.
76
+ */
77
+ function pruneToCap(memories, cap) {
67
78
  const now = Date.now();
68
79
  const RECENT_ACCESS_MS = 5 * 60 * 1000;
69
80
  const recent = memories.filter((m) => now - m.lastAccessed < RECENT_ACCESS_MS);
70
81
  const others = memories.filter((m) => now - m.lastAccessed >= RECENT_ACCESS_MS);
71
- const sorted = [...others].sort((a, b) => {
72
- if (Math.abs(a.utility - b.utility) > 0.1)
73
- return b.utility - a.utility;
74
- return b.timestamp - a.timestamp;
75
- });
76
- const remainingSlots = Math.max(0, MAX_ENTRIES - recent.length);
82
+ const sorted = [...others].sort(byUtilityThenRecency);
83
+ const remainingSlots = Math.max(0, cap - recent.length);
77
84
  const pruned = sorted
78
85
  .filter((m, i) => i < remainingSlots || m.utility >= MIN_UTILITY_THRESHOLD)
79
86
  .slice(0, remainingSlots);
80
- const combined = [...recent, ...pruned];
81
- return combined
82
- .sort((a, b) => {
83
- if (Math.abs(a.utility - b.utility) > 0.1)
84
- return b.utility - a.utility;
85
- return b.timestamp - a.timestamp;
86
- })
87
- .slice(0, MAX_ENTRIES);
87
+ return [...recent, ...pruned].sort(byUtilityThenRecency).slice(0, cap);
88
+ }
89
+ /**
90
+ * Prune memories down to MAX_ENTRIES, keeping recent-access and
91
+ * high-utility entries. Recent (last 5 min) entries are always kept.
92
+ * Other entries are sorted by utility, then timestamp, and trimmed.
93
+ *
94
+ * A configured partition (`braid.memory.reservedProvenance`) takes its slots
95
+ * first: entries whose `source` starts with the configured prefix may occupy
96
+ * up to `slots` of the cap, and everything else, including class entries that
97
+ * did not win a slot, competes for what remains. The class arrives as
98
+ * configuration because which entries carry provenance is a property of the
99
+ * writer that filed them; the store only reads the prefix as an opaque
100
+ * string. Absent or zero, this function is the prune it always was.
101
+ */
102
+ export function pruneMemories(memories) {
103
+ const { prefix, slots } = getMemoryReservedProvenance();
104
+ const classEntries = prefix && slots > 0
105
+ ? memories.filter((memory) => typeof memory.source === "string" && memory.source.startsWith(prefix))
106
+ : [];
107
+ if (classEntries.length === 0)
108
+ return pruneToCap(memories, MAX_ENTRIES);
109
+ const reserved = [...classEntries].sort(byUtilityThenRecency).slice(0, slots);
110
+ const reservedIds = new Set(reserved.map((memory) => memory.id));
111
+ const general = pruneToCap(memories.filter((memory) => !reservedIds.has(memory.id)), Math.max(0, MAX_ENTRIES - reserved.length));
112
+ return [...reserved, ...general];
88
113
  }
89
114
  /**
90
115
  * Consolidate a memory store: merge near-duplicates, decay old utility.
@@ -0,0 +1,114 @@
1
+ /**
2
+ * Owner speech: the braid half of the ruling write path.
3
+ *
4
+ * Two jobs, both of them specific to this deployment:
5
+ *
6
+ * - **Decide whether a turn is the owner speaking at all.** The corpus holds
7
+ * every user-role turn, and in this transcript tree that includes the
8
+ * system's own voice: dispatch prompts the seat writes to a running agent,
9
+ * and whisper envelopes from braid's subsystems. A directive-language
10
+ * classifier over that input files the seat's own brief text as an owner
11
+ * ruling, with a pointer into a worker session - a store that looks like
12
+ * provenance and is self-quotation. A telegram envelope is the exception:
13
+ * its body is the owner's message in a transport wrapper, so the wrapper is
14
+ * stripped and the body is what gets classified.
15
+ * - **File a ruling in braid's store.** The label stamped into `source`, the
16
+ * pointer shape, the duplicate key and the fixed tags are braid's filing
17
+ * convention, not English grammar, so they live here and the script that
18
+ * writes them carries no domain string of its own.
19
+ *
20
+ * The classification itself is `classifyRulingBody()` in the generic layer.
21
+ * This module supplies the vocabulary that layer cannot know - what a ruling
22
+ * can be about, and which words describe braid's own machinery - and removes
23
+ * the envelope before it ever reaches the grammar.
24
+ *
25
+ * Pure by construction: no I/O, no clock, no randomness.
26
+ */
27
+ import { type GrammarVocabulary, type RulingClass } from "../memory/decision-grammar.js";
28
+ /**
29
+ * One user turn, in the shape the corpus index stores it. Declared here rather
30
+ * than imported from `extensions/memory/session-recall/corpus-index.ts`: `lib/`
31
+ * does not import from `extensions/`, and the classifier needs six fields, not
32
+ * that module's build machinery.
33
+ */
34
+ export interface RulingTurn {
35
+ /** Absolute path of the session file the turn was read from. */
36
+ session: string;
37
+ /** pi's session id; with `line` it is the duplicate key. */
38
+ session_id: string;
39
+ /** Project label the session ran in. */
40
+ project: string;
41
+ /** Entry timestamp, ISO-8601. */
42
+ ts: string;
43
+ /** 1-based line number of the turn inside the session file. */
44
+ line: number;
45
+ /** The owner's words, verbatim. */
46
+ text: string;
47
+ }
48
+ /** A turn the classifier judged to carry an owner ruling. */
49
+ export interface OwnerRulingCandidate {
50
+ class: RulingClass;
51
+ /** The owner's words, contiguous and verbatim, capped with a trailing ellipsis. */
52
+ quote: string;
53
+ session: string;
54
+ session_id: string;
55
+ project: string;
56
+ ts: string;
57
+ line: number;
58
+ }
59
+ /**
60
+ * The label every filed ruling carries at the front of `source`, and the only
61
+ * handle a later run greps for. It is a constant here because the store's
62
+ * retention policy keys on the same prefix: a second spelling would be a class
63
+ * of entry the prune could not see.
64
+ */
65
+ export declare const OWNER_RULING_LABEL = "owner ruling";
66
+ /**
67
+ * The vocabulary this deployment hands the generic grammar. It is the only
68
+ * braid-specific input `classifyRulingBody()` takes, and it is a value rather
69
+ * than a parameter chain so a fixture can classify the same body with and
70
+ * without an envelope and compare.
71
+ */
72
+ export declare const BRAID_VOCABULARY: GrammarVocabulary;
73
+ /**
74
+ * Classify one user turn.
75
+ *
76
+ * Refuses everything that is not owner speech before the grammar runs, then
77
+ * hands the body to the generic classifier with this deployment's vocabulary,
78
+ * and stamps the provenance the pointer and the duplicate key are built from.
79
+ */
80
+ export declare function classifyOwnerRuling(turn: RulingTurn): OwnerRulingCandidate | null;
81
+ /**
82
+ * The pointer the store carries in `source`, in one fixed shape:
83
+ * `owner ruling: <session path>:<line> (<iso ts>, <project>)`.
84
+ *
85
+ * Greppable by prefix, and it resolves: the path and line address the turn the
86
+ * quote came from, so `sed -n '<line>p' '<session path>'` prints the words.
87
+ */
88
+ export declare function rulingPointer(candidate: OwnerRulingCandidate): string;
89
+ /**
90
+ * The pointer as a pattern, so a caller that scans a store for filed rulings
91
+ * reads the label from the same place it writes it instead of spelling it a
92
+ * second time. Groups: 1 the session path, 2 the line number.
93
+ */
94
+ export declare function rulingPointerPattern(): RegExp;
95
+ /**
96
+ * The duplicate key: one turn is one ruling, so `<session_id>:<line>` names it
97
+ * whether the entry was written by this script, by hand, or by a later run.
98
+ */
99
+ export declare function rulingDuplicateKey(candidate: OwnerRulingCandidate): string;
100
+ /**
101
+ * A project label as a tag token: lowercase alphanumerics, single hyphens, no
102
+ * leading/trailing hyphen. `projects/agents/pi-braid` becomes
103
+ * `projects-agents-pi-braid`, which is greppable and cannot collide with a
104
+ * different project's label through punctuation alone.
105
+ */
106
+ export declare function projectTag(label: string): string;
107
+ /**
108
+ * The fixed handles every filed ruling carries: the class a reader filters on,
109
+ * and the project it came from. The quote's own words are added beside these by
110
+ * `deriveTopicTags()`, because a handle names the entry while a topic word is
111
+ * what a later question arrives through.
112
+ */
113
+ export declare function rulingBaseTags(candidate: OwnerRulingCandidate): string[];
114
+ //# sourceMappingURL=owner-speech.d.ts.map