hippo-memory 2.1.0 → 2.3.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.
@@ -0,0 +1,290 @@
1
+ /** Student t tests for the built-in memory eval. The repositories are fixed and the family is the unit
2
+ * (Amendment 2): a variance-components t over family-by-seed tables with Satterthwaite df, plus the older
3
+ * one-value-per-repository tests (G-1 df).
4
+ * The t distribution is written here because the package carries no statistics library. */
5
+ import { notANumber } from './eval-stats.js';
6
+ const ALPHA = 0.05;
7
+ // Equal repository values can leave float noise in the spread; at this size it reads as no spread at all.
8
+ const FLAT = 1e-12;
9
+ const LANCZOS = [
10
+ 0.99999999999980993, 676.5203681218851, -1259.1392167224028, 771.32342877765313, -176.61502916214059,
11
+ 12.507343278686905, -0.13857109526572012, 9.9843695780195716e-6, 1.5056327351493116e-7,
12
+ ];
13
+ /** log Gamma(z) for z >= 0.5, by the Lanczos series (g 7, nine terms). */
14
+ export function lnGamma(z) {
15
+ const x = z - 1;
16
+ let a = LANCZOS[0];
17
+ for (let i = 1; i < LANCZOS.length; i++)
18
+ a += LANCZOS[i] / (x + i);
19
+ const t = x + 7.5;
20
+ return 0.5 * Math.log(2 * Math.PI) + (x + 0.5) * Math.log(t) - t + Math.log(a);
21
+ }
22
+ // Modified Lentz on the incomplete beta continued fraction; it converges fast where x < (a + 1) / (a + b + 2).
23
+ function betaFraction(a, b, x) {
24
+ const tiny = 1e-300;
25
+ const nonZero = (v) => (Math.abs(v) < tiny ? tiny : v);
26
+ let c = 1;
27
+ let d = 1 / nonZero(1 - ((a + b) * x) / (a + 1));
28
+ let h = d;
29
+ for (let m = 1; m <= 1000; m++) {
30
+ const m2 = 2 * m;
31
+ const even = (m * (b - m) * x) / ((a - 1 + m2) * (a + m2));
32
+ d = 1 / nonZero(1 + even * d);
33
+ c = nonZero(1 + even / c);
34
+ h *= d * c;
35
+ const odd = (-(a + m) * (a + b + m) * x) / ((a + m2) * (a + 1 + m2));
36
+ d = 1 / nonZero(1 + odd * d);
37
+ c = nonZero(1 + odd / c);
38
+ h *= d * c;
39
+ if (Math.abs(d * c - 1) < 1e-15)
40
+ return h;
41
+ }
42
+ throw new Error(`incomplete beta did not converge at a ${a}, b ${b}, x ${x}`);
43
+ }
44
+ /** Regularized incomplete beta I_x(a, b). */
45
+ export function incompleteBeta(x, a, b) {
46
+ if (x <= 0)
47
+ return 0;
48
+ if (x >= 1)
49
+ return 1;
50
+ const front = Math.exp(lnGamma(a + b) - lnGamma(a) - lnGamma(b) + a * Math.log(x) + b * Math.log(1 - x));
51
+ return x < (a + 1) / (a + b + 2) ? (front * betaFraction(a, b, x)) / a : 1 - (front * betaFraction(b, a, 1 - x)) / b;
52
+ }
53
+ // Two-sided tail P(|T| >= |t|), from the beta form so a small p never loses digits to 1 - cdf.
54
+ const twoSidedTail = (t, df) => incompleteBeta(df / (df + t * t), df / 2, 0.5);
55
+ /** Student t cumulative distribution P(T <= t) with `df` degrees of freedom. */
56
+ export function studentTCdf(t, df) {
57
+ const tail = twoSidedTail(t, df) / 2;
58
+ return t > 0 ? 1 - tail : tail;
59
+ }
60
+ /** Student t quantile: the t with P(T <= t) = p, found by bisection on the CDF. */
61
+ export function studentTQuantile(p, df) {
62
+ if (!(p > 0 && p < 1) || !(df > 0)) {
63
+ throw new RangeError(`studentTQuantile needs 0 < p < 1 and df > 0, got p ${p}, df ${df}`);
64
+ }
65
+ if (p < 0.5)
66
+ return -studentTQuantile(1 - p, df);
67
+ let hi = 1;
68
+ while (studentTCdf(hi, df) < p)
69
+ hi *= 2;
70
+ let lo = 0;
71
+ for (let i = 0; i < 200 && hi - lo > 1e-15 * hi; i++) {
72
+ const mid = (lo + hi) / 2;
73
+ if (studentTCdf(mid, df) < p)
74
+ lo = mid;
75
+ else
76
+ hi = mid;
77
+ }
78
+ return (lo + hi) / 2;
79
+ }
80
+ const critical = new Map();
81
+ // The sizer asks for the same few df thousands of times; Satterthwaite df are fractional, so the key is df to
82
+ // three decimals and the quantile is taken at that rounded df, or the cache would never hit.
83
+ function criticalValue(df) {
84
+ const key = Math.round(df * 1000) / 1000;
85
+ let q = critical.get(key);
86
+ if (q === undefined) {
87
+ q = studentTQuantile(1 - ALPHA / 2, key);
88
+ critical.set(key, q);
89
+ }
90
+ return q;
91
+ }
92
+ const sum = (xs) => xs.reduce((s, x) => s + x, 0);
93
+ /** A 95% t interval and a two-sided p against `nullValue`.
94
+ * With no spread the interval is the estimate itself, and p is 1 on the null and 0 off it. */
95
+ function tResult(estimate, se, df, nullValue) {
96
+ if (!Number.isFinite(estimate) || !Number.isFinite(se))
97
+ return notANumber(nullValue, 0);
98
+ const base = { estimate, iterations: 0, dropped: 0, nullValue, df };
99
+ if (se <= FLAT * Math.max(1, Math.abs(estimate))) {
100
+ const onNull = Math.abs(estimate - nullValue) <= FLAT * Math.max(1, Math.abs(nullValue));
101
+ return { ...base, low: estimate, high: estimate, p: onNull ? 1 : 0, se: 0 };
102
+ }
103
+ const half = criticalValue(df) * se;
104
+ return { ...base, low: estimate - half, high: estimate + half, p: twoSidedTail((estimate - nullValue) / se, df), se };
105
+ }
106
+ /** One-sample t test on per-repository values: the mean, se = sd / sqrt(G), G-1 degrees of freedom.
107
+ * Fewer than two repositories give the not-a-number result. */
108
+ export function repositoryT(values, nullValue = 0) {
109
+ const g = values.length;
110
+ if (g < 2)
111
+ return notANumber(nullValue, 0);
112
+ const mean = sum(values) / g;
113
+ const sd = Math.sqrt(sum(values.map((v) => (v - mean) ** 2)) / (g - 1));
114
+ return tResult(mean, sd / Math.sqrt(g), g - 1, nullValue);
115
+ }
116
+ const MAX_PASSES = 1000;
117
+ const CONVERGED = 1e-12;
118
+ function tableOf(units) {
119
+ const families = new Map();
120
+ const seeds = new Map();
121
+ const sums = new Map();
122
+ const indexOf = (ids, key) => {
123
+ if (!ids.has(key))
124
+ ids.set(key, ids.size);
125
+ return ids.get(key);
126
+ };
127
+ for (const u of units) {
128
+ const [f, s] = [indexOf(families, u.family), indexOf(seeds, u.seed)];
129
+ const cell = sums.get(`${f}/${s}`) ?? { f, s, total: 0, count: 0 };
130
+ cell.total += u.value;
131
+ cell.count++;
132
+ sums.set(`${f}/${s}`, cell);
133
+ }
134
+ const cells = [...sums.values()].map((c) => ({ f: c.f, s: c.s, y: c.total / c.count }));
135
+ return { cells, k: families.size, s: seeds.size };
136
+ }
137
+ function levelMeans(cells, size, level, value) {
138
+ const total = Array.from({ length: size }, () => 0);
139
+ const count = Array.from({ length: size }, () => 0);
140
+ for (const c of cells) {
141
+ total[level(c)] += value(c);
142
+ count[level(c)]++;
143
+ }
144
+ return total.map((x, i) => x / count[i]);
145
+ }
146
+ // Writes the centred effects into `effects` and returns the shift, which belongs to the intercept.
147
+ function centreInto(effects, raw) {
148
+ const shift = sum(raw) / raw.length;
149
+ raw.forEach((x, i) => {
150
+ effects[i] = x - shift;
151
+ });
152
+ return shift;
153
+ }
154
+ /** Residual sum of squares about the level means of one factor: the fit with the other factor left out. */
155
+ function rssAbout(cells, size, level) {
156
+ const means = levelMeans(cells, size, level, (c) => c.y);
157
+ return sum(cells.map((c) => (c.y - means[level(c)]) ** 2));
158
+ }
159
+ /** Least squares for y = mu + a_f + b_s on the cells present, by alternating means with a and b centred each pass. */
160
+ function additiveFit(repo, t) {
161
+ const a = Array.from({ length: t.k }, () => 0);
162
+ const b = Array.from({ length: t.s }, () => 0);
163
+ let mu = sum(t.cells.map((c) => c.y)) / t.cells.length;
164
+ for (let pass = 0; pass < MAX_PASSES; pass++) {
165
+ const before = [mu, ...a, ...b];
166
+ const shiftA = centreInto(a, levelMeans(t.cells, t.k, (c) => c.f, (c) => c.y - mu - b[c.s]));
167
+ mu += shiftA;
168
+ const shiftB = centreInto(b, levelMeans(t.cells, t.s, (c) => c.s, (c) => c.y - mu - a[c.f]));
169
+ mu += shiftB;
170
+ mu = sum(t.cells.map((c) => c.y - a[c.f] - b[c.s])) / t.cells.length;
171
+ const change = Math.max(...[mu, ...a, ...b].map((x, i) => Math.abs(x - before[i])));
172
+ if (change < CONVERGED)
173
+ return { mu, rss: sum(t.cells.map((c) => (c.y - mu - a[c.f] - b[c.s]) ** 2)) };
174
+ }
175
+ throw new Error(`additive fit for repository ${repo} did not converge in ${MAX_PASSES} passes`);
176
+ }
177
+ // Union-find over the family-seed graph: n - k - s + 1 counts residual df only when the present cells form one block.
178
+ function isConnected(t) {
179
+ const parent = Array.from({ length: t.k + t.s }, (_, i) => i);
180
+ const root = (i) => {
181
+ while (parent[i] !== i)
182
+ i = parent[i] = parent[parent[i]];
183
+ return i;
184
+ };
185
+ for (const c of t.cells)
186
+ parent[root(c.f)] = root(t.k + c.s);
187
+ return new Set(parent.map((_, i) => root(i))).size === 1;
188
+ }
189
+ function fitRepo(repo, units) {
190
+ const t = tableOf(units);
191
+ const n = t.cells.length;
192
+ const dfE = n - t.k - t.s + 1;
193
+ const base = { k: t.k, s: t.s, n };
194
+ if (t.k < 2 || t.s < 2 || dfE < 1 || !isConnected(t)) {
195
+ return { ...base, est: sum(t.cells.map((c) => c.y)) / n, ms: null };
196
+ }
197
+ const { mu, rss } = additiveFit(repo, t);
198
+ const [dfF, dfQ] = [t.k - 1, t.s - 1];
199
+ // Clamped: both reduced fits nest the additive one, so a negative difference is float noise.
200
+ const ssF = Math.max(0, rssAbout(t.cells, t.s, (c) => c.s) - rss);
201
+ const ssQ = Math.max(0, rssAbout(t.cells, t.k, (c) => c.f) - rss);
202
+ return { ...base, est: mu, ms: { F: ssF / dfF, Q: ssQ / dfQ, E: rss / dfE, dfF, dfQ, dfE } };
203
+ }
204
+ const weighted = (rs, value, df) => sum(rs.map((r) => value(r) * df(r))) / sum(rs.map(df));
205
+ function poolMeanSquares(fitted) {
206
+ return {
207
+ F: weighted(fitted, (r) => r.ms.F, (r) => r.ms.dfF),
208
+ Q: weighted(fitted, (r) => r.ms.Q, (r) => r.ms.dfQ),
209
+ E: weighted(fitted, (r) => r.ms.E, (r) => r.ms.dfE),
210
+ dfF: sum(fitted.map((r) => r.ms.dfF)),
211
+ dfQ: sum(fitted.map((r) => r.ms.dfQ)),
212
+ dfE: sum(fitted.map((r) => r.ms.dfE)),
213
+ sBar: weighted(fitted, (r) => r.n / r.k, (r) => r.ms.dfF),
214
+ kBar: weighted(fitted, (r) => r.n / r.s, (r) => r.ms.dfQ),
215
+ };
216
+ }
217
+ function fitAll(units) {
218
+ const byRepo = new Map();
219
+ for (const u of units) {
220
+ const list = byRepo.get(u.repo);
221
+ if (list)
222
+ list.push(u);
223
+ else
224
+ byRepo.set(u.repo, [u]);
225
+ }
226
+ const repos = [...byRepo].map(([repo, us]) => fitRepo(repo, us));
227
+ return { repos, fitted: repos.filter((r) => r.ms !== null) };
228
+ }
229
+ /** The pooled mean squares the fixed-repository t test reads, for one repository or more; null when none can be fitted.
230
+ * The seed rule and the sizer take their spreads from here, so they cannot drift from the test. */
231
+ export function pooledComponents(units) {
232
+ const { repos, fitted } = fitAll(units);
233
+ if (fitted.length === 0)
234
+ return null;
235
+ return { repos: repos.map(({ k, s, n }) => ({ k, s, n })), ...poolMeanSquares(fitted) };
236
+ }
237
+ // Variance of the mean of the G repository estimates, with Satterthwaite df. Every repository adds its own
238
+ // coefficients (fitted or not); the mean squares are pooled over the fitted ones, weighted by df.
239
+ function varianceOf(repos, fitted) {
240
+ const g = repos.length;
241
+ const { F, Q, E, dfF, dfQ, dfE, sBar, kBar } = poolMeanSquares(fitted);
242
+ const useQ = Q > E;
243
+ let [cF, cQ, cE] = [0, 0, 0];
244
+ for (const r of repos) {
245
+ const family = 1 / (sBar * r.k);
246
+ cF += family;
247
+ cE += 1 / r.n - family;
248
+ if (useQ) {
249
+ const seed = 1 / (kBar * r.s);
250
+ cQ += seed;
251
+ cE -= seed;
252
+ }
253
+ }
254
+ const terms = [[(cF * F) / (g * g), dfF], [(cQ * Q) / (g * g), dfQ], [(cE * E) / (g * g), dfE]]
255
+ .filter(([x]) => x !== 0);
256
+ const v = sum(terms.map(([x]) => x));
257
+ if (v > 0)
258
+ return { v, df: (v * v) / sum(terms.map(([x, d]) => (x * x) / d)) };
259
+ return { v: (cF * F) / (g * g), df: dfF };
260
+ }
261
+ /** Mean of the repository estimates with repositories held fixed: the spread is family and seed variation inside each
262
+ * (additive model y = mu + a_f + b_s), pooled over fitted repositories (two or more families and seeds in
263
+ * one connected block, one residual df); a thinner or split one adds its mean and borrows the pooled spread.
264
+ * Fewer than two repositories or none fitted: NaN. */
265
+ export function fixedRepositoryT(units, nullValue = 0) {
266
+ if (units.some((u) => !Number.isFinite(u.value)))
267
+ return notANumber(nullValue, 0);
268
+ const { repos, fitted } = fitAll(units);
269
+ if (repos.length < 2 || fitted.length === 0)
270
+ return notANumber(nullValue, 0);
271
+ const { v, df } = varianceOf(repos, fitted);
272
+ return tResult(sum(repos.map((r) => r.est)) / repos.length, Math.sqrt(v), df, nullValue);
273
+ }
274
+ /** The pooled ratio sum(t) / sum(c) against 1; its spread is fixedRepositoryT on the residuals (t - R c) / mean(c).
275
+ * The interval is on the log scale (`se` too): with skewed costs the symmetric R +- t se passed 5.2-5.6% at a true
276
+ * 1.10, over the 5% bar, and the log form passed 3.2-4.7%. */
277
+ export function fixedRepositoryRatioT(cells) {
278
+ const [totalT, totalC] = [sum(cells.map((x) => x.t)), sum(cells.map((x) => x.c))];
279
+ if (!(totalT > 0 && totalC > 0))
280
+ return notANumber(1, 0);
281
+ const ratio = totalT / totalC;
282
+ const cBar = totalC / cells.length;
283
+ const residuals = cells.map(({ repo, family, seed, t, c }) => ({ repo, family, seed, value: (t - ratio * c) / cBar }));
284
+ const { se, df } = fixedRepositoryT(residuals, 0);
285
+ if (se === undefined || df === undefined || !Number.isFinite(se))
286
+ return notANumber(1, 0);
287
+ const log = tResult(Math.log(ratio), se / ratio, df, 0);
288
+ return { ...log, estimate: ratio, low: Math.exp(log.low), high: Math.exp(log.high), nullValue: 1 };
289
+ }
290
+ //# sourceMappingURL=repository-t.js.map
@@ -52,23 +52,15 @@ export const HOOKS = {
52
52
  content: `
53
53
  ## Project Memory (Hippo)
54
54
 
55
- Pinned rules and recent writes auto-inject at every prompt via the installed
56
- UserPromptSubmit hook; never re-run that part manually. At the START of a
57
- task (not per prompt), additionally load task-specific context: git-aware
58
- recall over the full store that per-prompt injection does not cover. Also
59
- run it if the hook is not installed:
55
+ The installed UserPromptSubmit hook injects pinned rules and the memories
56
+ that match each prompt, so never load them yourself. If no hippo memory
57
+ block has appeared in this session, run this at the start of a task:
60
58
  \`\`\`bash
61
59
  hippo context --auto --budget 1500
62
60
  \`\`\`
63
61
 
64
- When you find out why something failed, record it right then, while you
65
- work, never as a closing step:
66
- \`\`\`bash
67
- hippo remember "<what went wrong and why>" --error
68
- \`\`\`
69
-
70
62
  The installed hooks store failed tool calls and capture the session when it
71
- ends, so there is nothing to run before you finish.
63
+ ends, so there is nothing to record or run by hand.
72
64
  `.trim(),
73
65
  },
74
66
  'codex': {
@@ -77,11 +69,13 @@ ends, so there is nothing to run before you finish.
77
69
  content: `
78
70
  ## Project Memory (Hippo)
79
71
 
80
- At the start of every task, run:
72
+ When Hippo's prompt hook is installed, it injects pinned rules and the
73
+ memories that match each prompt, so never load them yourself. If no hippo
74
+ memory block has appeared in this session, run this at the start of a task
75
+ and read the output before writing any code:
81
76
  \`\`\`bash
82
77
  hippo context --auto --budget 1500
83
78
  \`\`\`
84
- Read the output before writing any code.
85
79
 
86
80
  On errors or unexpected behaviour, record it right then, while you work,
87
81
  never as a closing step:
@@ -111,6 +105,9 @@ hippo capture --stdin <<< '<decisions, errors, lessons: 2-5 bullets>'
111
105
  // sha256 of each trimmed block an earlier hippo wrote, so init refreshes only blocks nobody edited. Add the old hash
112
106
  // when a block changes.
113
107
  const SHIPPED_HOOK_HASHES = new Map([
108
+ ['c80e760208aed70f6094757736b9a2f496ba5c30d88bc2a7ae3e128b403dcc6b', 'claude-code'],
109
+ ['75937be6b7fdc2b87bcb08b7fec56757808075db129d99eff3e9f769f80a7781', 'claude-code'],
110
+ ['f1e5815a4b7205c43e2db792215df1943e7853635a1e0f4561b150a41b756451', 'codex'],
114
111
  ['c04e48f2896a4fee9ae98f8f832e2d26a3910269df3beb5bcd6baee3cd9db68e', 'claude-code'],
115
112
  ['e6b12bd8983c032e5ca8e95a97aeff4178a5a05026d10acad5b2e1b25d5656dd', 'claude-code'],
116
113
  ['4c64e11d3e5be68fa547c9248d7553feb645a02f7cf13ba02f7275e1854baf44', 'claude-code'],
@@ -101,8 +101,9 @@ export function trailPiece(events) {
101
101
  export const contextCost = {
102
102
  entry: memoryCost,
103
103
  fixed: (budget) => memoriesReserve(budget),
104
- snapshot: (s) => estimateTokens(snapshotPiece(s)),
105
- handoff: (h) => estimateTokens(handoffPiece(h)),
104
+ // hippo_context passes no continuity opt-in, so the mode is always 'full' and the full piece is the price.
105
+ snapshot: (s, _mode) => estimateTokens(snapshotPiece(s)),
106
+ handoff: (h, _mode) => estimateTokens(handoffPiece(h)),
106
107
  trail: (events) => estimateTokens(trailPiece(events)),
107
108
  };
108
109
  // Rows the ranked list already shows drop out of this section, so pricing every row bounds what it prints.
@@ -0,0 +1,4 @@
1
+ export declare const SESSION_ID_RE: RegExp;
2
+ /** An id a pointer may print in a glued `--id=<id>` flag, where even a leading `--` reads as a value. */
3
+ export declare const isPointerSafeId: (id: string) => boolean;
4
+ //# sourceMappingURL=session-id.d.ts.map
@@ -0,0 +1,6 @@
1
+ import { MAX_ID_LEN } from './limits.js';
2
+ // A session id becomes a folder name or a word in a command an agent runs, so only word characters and hyphens pass.
3
+ export const SESSION_ID_RE = /^[\w-]+$/;
4
+ /** An id a pointer may print in a glued `--id=<id>` flag, where even a leading `--` reads as a value. */
5
+ export const isPointerSafeId = (id) => id.length <= MAX_ID_LEN && SESSION_ID_RE.test(id);
6
+ //# sourceMappingURL=session-id.js.map
@@ -2,7 +2,7 @@
2
2
  * Single source of truth for the package version, written by scripts/sync-version.mjs; never edit by hand. Read by the
3
3
  * db rollback guard, /health, MCP.
4
4
  * A constant, not a runtime package.json read: the published bundle may lack package.json on a path ESM can resolve. */
5
- export declare const PACKAGE_VERSION = "2.1.0";
5
+ export declare const PACKAGE_VERSION = "2.3.0";
6
6
  /** The floor a store takes on its first expiring key: the first release with schema
7
7
  * v53, set by hand in that release; scripts/check-expiring-keys-floor.mjs gates it. */
8
8
  export declare const EXPIRING_KEYS_MIN_BINARY = "1.64.0";
@@ -2,7 +2,7 @@
2
2
  * Single source of truth for the package version, written by scripts/sync-version.mjs; never edit by hand. Read by the
3
3
  * db rollback guard, /health, MCP.
4
4
  * A constant, not a runtime package.json read: the published bundle may lack package.json on a path ESM can resolve. */
5
- export const PACKAGE_VERSION = '2.1.0';
5
+ export const PACKAGE_VERSION = '2.3.0';
6
6
  /** The floor a store takes on its first expiring key: the first release with schema
7
7
  * v53, set by hand in that release; scripts/check-expiring-keys-floor.mjs gates it. */
8
8
  export const EXPIRING_KEYS_MIN_BINARY = '1.64.0';