hippo-memory 3.2.2 → 3.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.
package/README.md CHANGED
@@ -201,6 +201,15 @@ hippo capture --file conversation.md
201
201
  hippo capture --file conversation.md --dry-run
202
202
  ```
203
203
 
204
+ #### Rules from follow-up turns (opt-in, uses a model)
205
+
206
+ Word patterns miss a rule that has no rule word in it, such as "That file is generated, so changes belong in the template it comes from." With `{"capture": {"followUpRules": "model"}}` in `.hippo/config.json` and `ANTHROPIC_API_KEY` set, a session capture also asks a model which of your sentences state a lasting rule. Hippo stores those sentences, in your own words, as pinned rules.
207
+
208
+ - **What it sends:** your turns after the first one in the session, the last 20, each cut to 1,000 characters. Pasted blocks, fenced code and log lines are removed first, and secrets, email addresses and home paths are masked. The assistant's replies are never sent.
209
+ - **To whom:** Anthropic, with your `ANTHROPIC_API_KEY`, in one call per session capture. A failed call logs one line and capture keeps its pattern rules. A session with no project never makes the call.
210
+ - **On and off:** the default is `"off"`. Set `"model"` to turn it on; set `"off"` again, or unset the key, to turn it off.
211
+ - A capture after each reply (`--turn`, as VS Code's agent mode runs) never calls the model, so those runtimes gain little.
212
+
204
213
  ### Slack ingestion (E1.3)
205
214
 
206
215
  Hippo accepts Slack Events API webhooks at `POST /v1/connectors/slack/events`. Configure `SLACK_SIGNING_SECRET` (validated on every request) and point Slack at `https://<your-host>/v1/connectors/slack/events`. Messages land as `kind='raw'` memories with `slack://team/channel/ts` provenance and a `slack:public:Cxxx` or `slack:private:Cxxx` scope. Source deletions are honored (GDPR). To rotate the secret, put the new one in `SLACK_SIGNING_SECRET` and the old one in `SLACK_SIGNING_SECRET_PREVIOUS`, and set `SLACK_SIGNING_SECRET_PREVIOUS_UNTIL` to an ISO date (`2026-12-01` means 00:00 UTC that day) or timestamp. From then on requests signed with the old secret are refused, with one warning in the log. Left unset, the old secret works for as long as it stays in the environment.
@@ -836,7 +845,7 @@ This adds a `<!-- hippo:start -->` ... `<!-- hippo:end -->` block that tells the
836
845
  The block asks for nothing a hook already does, because each extra tool call re-reads the whole context. Re-running `hippo init` swaps a block an older hippo wrote for the current one, as long as nobody edited it. It leaves an edited block alone and says so, and never touches text outside the markers.
837
846
 
838
847
  For Claude Code, it also adds 7 hook entries to `~/.claude/settings.json`:
839
- - a `SessionEnd` hook that runs `hippo sleep` and then `hippo capture` when the session exits. Capture matches the last 20 user and 10 assistant messages of the transcript against word patterns for decisions, rules, errors and preferences. It uses no model and does not read earlier turns, so a correction older than that window needs a `hippo remember` by hand.
848
+ - a `SessionEnd` hook that runs `hippo sleep` and then `hippo capture` when the session exits. Capture matches the last 20 user and 10 assistant messages of the transcript against word patterns for decisions, rules, errors and preferences. It uses no model unless you turn on `capture.followUpRules` (see Conversation Capture) and does not read earlier turns, so a correction older than that window needs a `hippo remember` by hand.
840
849
  - a `SessionStart` hook that prints the previous session's consolidation log on stderr, where `claude --debug` shows it. When the last sleep failed or a compaction summary was set aside, it shows you one line that points to `hippo doctor`.
841
850
  - a `UserPromptSubmit` hook that runs `hippo context --pinned-only --include-recent 5 --format additional-context` every turn. It re-injects pinned memories (`hippo remember <text> --pin`) plus up to 5 memories that share words with your prompt. When nothing matches, it adds only the pinned ones. Since 1.55.0 this replaces the 5 newest memories, which cut the median block from 847 to 533 tokens in our eval. `{"pinnedInject":{"promptRecall":false}}` brings back the 5 newest, so fresh same-session lessons appear on the next prompt whatever you ask. The block is rendered without live strength percentages, so it stays byte-identical while its memories do not change, and it is sent only when it changed since the session's last prompt: an unchanged block is skipped, resent every 10 skips (`pinnedInject.refreshTurns`, `0` never resends) and resent after compaction. The prompt-matched memories go in a separate block that is never skipped, so they are sent on every prompt they match. `{"pinnedInject":{"skipUnchanged":false}}` sends the pinned block every turn as before. Opt out entirely with `{"pinnedInject":{"enabled":false}}` in `.hippo/config.json`.
842
851
  - a `PreCompact` hook that runs `hippo pre-compact` before the transcript gets summarized. It records the compaction in the store, saves a working-state snapshot (task/summary/next step) so mid-session compaction can't drop it, and asks the summariser to end its summary with a "Memories for hippo" list: the lessons, decisions and corrections from the session that should outlive it. The `SessionEnd` hook still owns extracting durable memories from the transcript.
@@ -128,6 +128,9 @@ const CONFIG_TABLE = [
128
128
  configKey('vectorGraph', block('an object like {"maxVectors": 200000}', D.vectorGraph, (read) => ({
129
129
  maxVectors: read('maxVectors', count(D.vectorGraph.maxVectors)),
130
130
  }))),
131
+ configKey('capture', block('an object like {"followUpRules": "model"}', D.capture, (read) => ({
132
+ followUpRules: read('followUpRules', choice(D.capture.followUpRules, 'off', 'model')),
133
+ }))),
131
134
  ];
132
135
  /** The config a parsed config.json gives: each key it sets over the defaults;
133
136
  * src/host/config-file.ts reads it. */
@@ -150,6 +150,11 @@ export interface HippoConfig {
150
150
  vectorGraph: {
151
151
  maxVectors: number;
152
152
  };
153
+ /** Session capture. `followUpRules: 'model'` sends the person's scrubbed turns after the first to
154
+ * Anthropic (ANTHROPIC_API_KEY), which picks the sentences that state a lasting rule. Default 'off'. */
155
+ capture: {
156
+ followUpRules: 'off' | 'model';
157
+ };
153
158
  /** What the composition root read from the environment for this command or request;
154
159
  * config.json never sets it. */
155
160
  runtime?: RuntimeSettings;
@@ -100,5 +100,8 @@ export const DEFAULT_CONFIG = {
100
100
  vectorGraph: {
101
101
  maxVectors: 200_000,
102
102
  },
103
+ capture: {
104
+ followUpRules: 'off',
105
+ },
103
106
  };
104
107
  //# sourceMappingURL=config.js.map
@@ -22,12 +22,19 @@ export type LlmFailure = {
22
22
  } | {
23
23
  kind: 'empty';
24
24
  };
25
- export type LlmReply = {
25
+ /** What the provider billed for one call; an empty reply is billed too. */
26
+ export interface LlmUsage {
27
+ readonly inputTokens: number;
28
+ readonly outputTokens: number;
29
+ }
30
+ export type LlmReply = ({
26
31
  ok: true;
27
32
  text: string;
28
33
  } | {
29
34
  ok: false;
30
35
  failure: LlmFailure;
36
+ }) & {
37
+ readonly usage?: LlmUsage;
31
38
  };
32
39
  /** One user prompt in, the reply's first text block or a typed failure out. Never throws. */
33
40
  export interface Llm {
@@ -2,7 +2,7 @@
2
2
  * Single source of truth for the package version, written by scripts/sync-version.mjs; never
3
3
  * edit by hand. Read by the db rollback guard, /health, MCP. A constant, not a runtime
4
4
  * package.json read: the published bundle may lack package.json on a path ESM can resolve. */
5
- export declare const PACKAGE_VERSION = "3.2.2";
5
+ export declare const PACKAGE_VERSION = "3.3.0";
6
6
  /** The floor a store takes on its first expiring key: the first release with schema v53, set by
7
7
  * hand in that release; scripts/checks/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
3
3
  * edit by hand. Read by the db rollback guard, /health, MCP. A constant, not a runtime
4
4
  * package.json read: the published bundle may lack package.json on a path ESM can resolve. */
5
- export const PACKAGE_VERSION = '3.2.2';
5
+ export const PACKAGE_VERSION = '3.3.0';
6
6
  /** The floor a store takes on its first expiring key: the first release with schema v53, set by
7
7
  * hand in that release; scripts/checks/check-expiring-keys-floor.mjs gates it. */
8
8
  export const EXPIRING_KEYS_MIN_BINARY = '1.64.0';
@@ -21,6 +21,16 @@ function firstText(reply) {
21
21
  const text = isJsonObject(first) ? first.text : undefined;
22
22
  return isJsonString(text) ? text.trim() : '';
23
23
  }
24
+ /** The reply's billed tokens, or undefined when its usage block is missing or malformed. */
25
+ function usageOf(reply) {
26
+ const usage = reply.usage;
27
+ if (!isJsonObject(usage))
28
+ return undefined;
29
+ const { input_tokens: inputTokens, output_tokens: outputTokens } = usage;
30
+ if (!Number.isInteger(inputTokens) || !Number.isInteger(outputTokens))
31
+ return undefined;
32
+ return { inputTokens: Number(inputTokens), outputTokens: Number(outputTokens) };
33
+ }
24
34
  /** An Llm that calls the Anthropic Messages API with `apiKey`. */
25
35
  export function anthropicLlm(connection) {
26
36
  return { send: (request) => sendMessage(connection, request) };
@@ -64,7 +74,9 @@ async function sendMessage(connection, req) {
64
74
  };
65
75
  }
66
76
  const text = firstText(data);
67
- return text === '' ? { ok: false, failure: { kind: 'empty' } } : { ok: true, text };
77
+ const usage = usageOf(data);
78
+ const reply = text === '' ? { ok: false, failure: { kind: 'empty' } } : { ok: true, text };
79
+ return usage === undefined ? reply : { ...reply, usage };
68
80
  }
69
81
  catch (err) {
70
82
  return { ok: false, failure: { kind: 'unreadable', message: errorMessage(err), cause: err } };
@@ -6,6 +6,7 @@ import { type SessionTurn } from './transcript.js';
6
6
  import type { CaptureDedup } from '../../base/ports/store/capture.js';
7
7
  import type { HeldText } from '../../base/ports/store/types.js';
8
8
  import type { StoreGroups } from '../../base/ports/store.js';
9
+ import type { Llm } from '../../base/ports/llm.js';
9
10
  export interface CaptureOptions {
10
11
  source: 'stdin' | 'file' | 'last-session';
11
12
  filePath?: string;
@@ -43,6 +44,10 @@ export interface CaptureTarget {
43
44
  readonly store: Pick<StoreGroups, 'captures' | 'folderFiles' | 'rejections'>;
44
45
  /** Embeds each captured row, off the capture's path. */
45
46
  readonly embed: (entry: MemoryEntry) => void;
47
+ /** Picks the rules in the person's follow-up turns; without it capture reads word patterns only. */
48
+ readonly llm?: Llm;
49
+ /** Why no `llm` came when the config asked for one; printed inside the capture's log. */
50
+ readonly llmMissing?: string;
46
51
  }
47
52
  export declare function runCapture(target: CaptureTarget, options: CaptureOptions): Promise<void>;
48
53
  /** The items with `scrub` applied to each text, as a path stores them; scrubbing can make two
@@ -11,6 +11,7 @@ import { errorMessage, log, errorFields } from '../../base/util/log.js';
11
11
  import { teeStdStreams } from '../../host/stream-tee.js';
12
12
  import { ALL_TENANTS } from '../../base/util/tenant.js';
13
13
  import { boldTwins, extractFromTexts, isStatedRule, oncePerText, } from './extract.js';
14
+ import { followUpRules, usageLine, withFollowUpRules } from './follow-up.js';
14
15
  import { collectSessionTurns, sessionTail, resolveLastSessionTranscript, } from './transcript.js';
15
16
  import { PRIVATE_DIR } from '../../host/private-dir.js';
16
17
  import { evalClock } from '../../infra/eval-switches.js';
@@ -68,7 +69,7 @@ async function runCaptureCore(target, options) {
68
69
  const read = readCaptureTexts(options);
69
70
  if (read === null)
70
71
  return;
71
- const { texts, userTexts, firstFollowUp } = read;
72
+ const { texts, userTexts, firstFollowUp, followUps } = read;
72
73
  if (texts.every((text) => text.trim().length === 0)) {
73
74
  console.log('No text to capture from.');
74
75
  return;
@@ -77,15 +78,33 @@ async function runCaptureCore(target, options) {
77
78
  // pass could not see (AGENTS.md: no secrets in memories).
78
79
  const scrub = (text) => maskEmails(redactSecretsStrict(text));
79
80
  const scrubbed = texts.map(scrub);
80
- const extracted = scrubbedItems(extractFromTexts(scrubbed, userTexts, firstFollowUp), scrub);
81
+ const dedup = await captureDedup(target.store.folderFiles, options);
82
+ const rules = await modelRules(target, dedup, followUps);
83
+ const patterned = extractFromTexts(scrubbed, userTexts, firstFollowUp);
84
+ const extracted = scrubbedItems(withFollowUpRules(patterned, rules, scrub), scrub);
81
85
  if (extracted.length === 0) {
82
86
  console.log('No actionable items found in the input.');
83
87
  return;
84
88
  }
85
- const dedup = await captureDedup(target.store.folderFiles, options);
86
89
  const held = await storedKeysInView(target.store, dedup, extracted, boldTwins(scrubbed, scrub));
87
90
  printCaptureTally(options, await captureFromCli(target, options, dedup, extracted, held));
88
91
  }
92
+ const warnLine = (line, opts) => log.warn(line, opts?.fields);
93
+ /** The rules the model finds in the person's later turns, when the target has one. */
94
+ async function modelRules({ llm, llmMissing }, { ruleProject = [] }, followUps) {
95
+ if (!llm) {
96
+ if (llmMissing)
97
+ warnLine(llmMissing);
98
+ return [];
99
+ }
100
+ // A rule with no project to belong to would pin into every project.
101
+ if (ruleProject.length === 0)
102
+ return [];
103
+ const { rules, usage } = await followUpRules(followUps, llm, warnLine);
104
+ if (usage)
105
+ console.log(usageLine(usage));
106
+ return rules;
107
+ }
89
108
  async function captureFromCli({ store, config, embed }, options, dedup, extracted, { keys, ruleKeys }) {
90
109
  const writeOpts = {
91
110
  tenantId: options.global ? undefined : options.tenantId,
@@ -163,11 +182,14 @@ function printCaptureTally(options, { captured, skipped, rejected }) {
163
182
  (rejected > 0 ? `, ${rejected} rejected` : '') +
164
183
  ')');
165
184
  }
185
+ /** The raw texts for the chosen source, one per session turn, the person's turns first; null after printing why a
186
+ * last-session capture has nothing.
187
+ * Only a session says who spoke, so a piped or file capture counts no user texts. */
166
188
  function readCaptureTexts(options) {
167
189
  switch (options.source) {
168
190
  case 'stdin': {
169
191
  try {
170
- return { texts: [fs.readFileSync(0, 'utf8')], userTexts: 0 };
192
+ return { texts: [fs.readFileSync(0, 'utf8')], userTexts: 0, followUps: [] };
171
193
  }
172
194
  catch (err) {
173
195
  log.warn(`reading stdin failed: ${errorMessage(err)}`, errorFields(err));
@@ -187,7 +209,7 @@ function readCaptureTexts(options) {
187
209
  process.exitCode = 1;
188
210
  return null;
189
211
  }
190
- return { texts: [fs.readFileSync(options.filePath, 'utf8')], userTexts: 0 };
212
+ return { texts: [fs.readFileSync(options.filePath, 'utf8')], userTexts: 0, followUps: [] };
191
213
  }
192
214
  case 'last-session':
193
215
  return readSessionTexts(options);
@@ -211,9 +233,14 @@ function readSessionTexts(options) {
211
233
  return null;
212
234
  }
213
235
  // The first user turn is the request; a tail that cut it off, or a later slice, holds only replies.
214
- const allUsers = turns.filter((t) => t.role === 'user').length;
215
- const opener = options.fromStart !== false && users.length === allUsers ? 1 : 0;
216
- return { texts: [...users, ...assistants], userTexts: users.length, firstFollowUp: opener };
236
+ const userTurns = turns.filter((t) => t.role === 'user').map((t) => t.text);
237
+ const opener = options.fromStart !== false && users.length === userTurns.length ? 1 : 0;
238
+ return {
239
+ texts: [...users, ...assistants],
240
+ userTexts: users.length,
241
+ firstFollowUp: opener,
242
+ followUps: userTurns.slice(opener),
243
+ };
217
244
  }
218
245
  /** One entry per new text: building can throw, so a held text or a repeat within the batch is
219
246
  * never built. */
@@ -10,6 +10,22 @@ export declare function isStatedRule(item: ExtractedItem): boolean;
10
10
  /** Each text once, where its first copy stood; a later copy that is the person's rule replaces a
11
11
  * first copy that is not, so a preference restated in a reply keeps its rule status. */
12
12
  export declare function oncePerText(items: readonly ExtractedItem[], admit?: (item: ExtractedItem) => boolean): ExtractedItem[];
13
+ /** Whether a line is program output, not the speaker's words. */
14
+ export type NoiseCheck = (line: string, sentenceOpen: boolean) => boolean;
15
+ /** CommonMark fences: a backtick run with a backtick after it is inline code, and only a bare
16
+ * run as long closes. A line `isNoise` drops also ends the paragraph above it; it is told when
17
+ * the prose above left its sentence open, so it can keep a condition with few letters. */
18
+ export declare function proseOnly(text: string, isNoise?: NoiseCheck): string;
19
+ /** The text above has not ended its sentence; "e.g." at its end has not. */
20
+ export declare function leftOpen(previous: string, next: string): boolean;
21
+ /** A sentence as capture stores it: its lead label and closing marks trimmed. */
22
+ export declare function statedText(sentence: string): string;
23
+ /** The sentences a pattern reads in `text`: wrapped lines joined, bold cut, and none that starts
24
+ * inside a cut aside. */
25
+ export declare function statedSentences(text: string, isNoise?: NoiseCheck): string[];
26
+ /** Picked sentences of one turn through the gates a pattern sentence meets, or null; one sentence
27
+ * gives its pattern item's text, so held rows and bold twins match it. */
28
+ export declare function pickedText(sentences: readonly string[]): string | null;
13
29
  /** Captures complete supported statements, each text parsed alone so a fence or heading in one never reaches the next.
14
30
  * The first `userTexts` texts are a person's own words; on a repeat their copy wins, so it keeps `fromUser`,
15
31
  * and a copy that is their rule wins over one that is not.
@@ -55,24 +55,28 @@ const CATEGORIES = [
55
55
  const MAX_CHARS = 500;
56
56
  const BULLET = /^(?:[-*]|\d+\.)\s+(?:\[[ xX]\]\s+)?(.+)/;
57
57
  const LABEL = /^(?:decision|rule|error|bug|gotcha|important|critical|remember|plan):/i;
58
+ const CONTINUED_LEAD = /^(?:[a-z]|\((?!\w{1,2}\)))/;
58
59
  const SENTENCE_END = /[.!?]["')\]]*$/;
59
60
  const SPEC_HEADING_PATTERNS = [
60
61
  new RegExp(String.raw `^#+\s*(?:features?|requirements?|specs?|specifications?|plan|design|architecture|interface|api|todo|` +
61
62
  String.raw `tasks?|implementation|notes?)(?:\s|:|$)`, 'i'),
62
63
  /^(?:features?|requirements?|specs?|specifications?|plan|design|tasks?|implementation)(?:\s*:|$)/i,
63
64
  ];
64
- // A list item may open a fence on its own line: "- ```".
65
- const FENCE_OPEN = /^(?:(?:[-*]|\d+\.)\s+)?(`{3,}|~{3,})(.*)$/;
65
+ // A list item may open a fence on its own line: "- ```", "+ ```" or "1) ```" (CommonMark markers).
66
+ const FENCE_OPEN = /^(?:(?:[-*+]|\d+[.)])\s+)?(`{3,}|~{3,})(.*)$/;
67
+ const INDENTED_CODE = /^(?: {4}|\t)(?!\s*(?:[-*+]|\d+[.)])\s)/;
66
68
  const FENCE_CLOSE = /^(`{3,}|~{3,})\s*$/;
67
69
  // Inline code and abbreviation dots never end a sentence; "etc." does when a capital follows.
68
70
  const NO_BREAK = /(`+)[^`\n]+\1|\b(?:[Ee]\.g|[Ii]\.e|[Vv]s|[Cc]f)\.|\betc\.(?=\s+[a-z])/g;
69
71
  // Pasted text is not the speaker's own; an unclosed block runs to the end.
70
72
  const PASTED_BLOCK = /<pasted_content\b[^>]*>[\s\S]*?(?:<\/pasted_content>|$)/g;
71
73
  /** CommonMark fences: a backtick run with a backtick after it is inline code, and only a bare
72
- * run as long closes. */
73
- function proseOnly(text) {
74
+ * run as long closes. A line `isNoise` drops also ends the paragraph above it; it is told when
75
+ * the prose above left its sentence open, so it can keep a condition with few letters. */
76
+ export function proseOnly(text, isNoise = () => false) {
74
77
  let fence = null;
75
78
  let afterProse = false;
79
+ let previous;
76
80
  return text
77
81
  .replace(PASTED_BLOCK, '\n')
78
82
  .split('\n')
@@ -93,8 +97,16 @@ function proseOnly(text) {
93
97
  }
94
98
  // Quotes, table rows and indented code are not the speaker's own; indented code cannot
95
99
  // interrupt a paragraph or list item.
96
- const dropped = /^\s*[>|]/.test(line) || (!afterProse && /^(?: {4}|\t)(?!\s*(?:[-*]|\d+\.)\s)/.test(line));
100
+ // A colon introduces what follows, so output shown after one stays noise.
101
+ const sentenceOpen = afterProse &&
102
+ previous !== undefined &&
103
+ !previous.endsWith(':') &&
104
+ leftOpen(previous, trimmed);
105
+ const dropped = isNoise(line, sentenceOpen) ||
106
+ /^\s*[>|]/.test(line) ||
107
+ (!afterProse && INDENTED_CODE.test(line));
97
108
  afterProse = !dropped && trimmed !== '' && !/^#{1,6}(?:\s|$)/.test(trimmed);
109
+ previous = trimmed.trimEnd();
98
110
  return dropped ? '' : line;
99
111
  })
100
112
  .join('\n');
@@ -102,14 +114,16 @@ function proseOnly(text) {
102
114
  function masked(text) {
103
115
  return text.replace(NO_BREAK, (span) => 'x'.repeat(span.length));
104
116
  }
105
- /**
106
- * A lowercase line continues the line above only when that line has not ended its sentence; "e.g."
107
- * at a line end has not.
108
- */
117
+ /** The text above has not ended its sentence; "e.g." at its end has not. */
118
+ export function leftOpen(previous, next) {
119
+ return !SENTENCE_END.test(masked(`${previous} ${next}`).slice(0, previous.length));
120
+ }
121
+ /** A lowercase or bracketed line, but not an enumerator like "(1)", continues the line above
122
+ * only when that line left its sentence open. */
109
123
  function continues(line, previous) {
110
- if (previous === undefined || !/^[a-z]/.test(line) || LABEL.test(line))
124
+ if (previous === undefined || !CONTINUED_LEAD.test(line) || LABEL.test(line))
111
125
  return false;
112
- return !SENTENCE_END.test(masked(`${previous} ${line}`).slice(0, previous.length));
126
+ return leftOpen(previous, line);
113
127
  }
114
128
  /** What capture read before it removed bold markers. */
115
129
  const keepAll = () => [];
@@ -254,12 +268,36 @@ function extractFromPatterns(sentence, patterns, category) {
254
268
  const keyed = patterns.some((pattern) => [...sentence.matchAll(new RegExp(pattern.source, `${pattern.flags}g`))].some((match) => !insideBrackets(sentence.slice(0, match.index))));
255
269
  if (!keyed)
256
270
  return null;
257
- const content = sentence
258
- .replace(new RegExp(String.raw `^(?:decision|plan|rule|important|critical|remember|error|bug|gotcha|watch out|careful|warning|` +
259
- String.raw `caveat|trap|don't forget|easy to miss):\s*`, 'i'), '')
271
+ const content = statedText(sentence);
272
+ return content.length <= MAX_CHARS ? { content, category, tags: [category, 'captured'] } : null;
273
+ }
274
+ const LEAD_LABEL = new RegExp(String.raw `^(?:decision|plan|rule|important|critical|remember|error|bug|gotcha|watch out|careful|warning|` +
275
+ String.raw `caveat|trap|don't forget|easy to miss):\s*`, 'i');
276
+ /** A sentence as capture stores it: its lead label and closing marks trimmed. */
277
+ export function statedText(sentence) {
278
+ return sentence
279
+ .replace(LEAD_LABEL, '')
260
280
  .replace(/[.!?\s]+$/, '')
261
281
  .trim();
262
- return content.length <= MAX_CHARS ? { content, category, tags: [category, 'captured'] } : null;
282
+ }
283
+ /** The sentences a pattern reads in `text`: wrapped lines joined, bold cut, and none that starts
284
+ * inside a cut aside. */
285
+ export function statedSentences(text, isNoise) {
286
+ return proseBlocks(proseOnly(text, isNoise), boldPairs).flatMap((block) => {
287
+ const cutByAside = asideCutter(block.text);
288
+ return completeSentences(block)
289
+ .filter(({ sentence, at }) => !cutByAside(sentence, at))
290
+ .map(({ sentence }) => sentence);
291
+ });
292
+ }
293
+ /** Picked sentences of one turn through the gates a pattern sentence meets, or null; one sentence
294
+ * gives its pattern item's text, so held rows and bold twins match it. */
295
+ export function pickedText(sentences) {
296
+ const kept = sentences.filter((sentence) => !sentence.endsWith('?'));
297
+ if (kept.length === 0)
298
+ return null;
299
+ const content = statedText(kept.join(' '));
300
+ return content.length <= MAX_CHARS && assessAutomaticMemory(content).accepted ? content : null;
263
301
  }
264
302
  function extractSpecSections(prose, cuts) {
265
303
  const bullets = [];
@@ -0,0 +1,21 @@
1
+ import { type Llm, type LlmUsage } from '../../base/ports/llm.js';
2
+ import { type LineLog } from '../../base/util/log.js';
3
+ import { type ExtractedItem } from './extract.js';
4
+ /** A rule the model picked, and the whole sentences it came from. */
5
+ export interface FollowUpRule extends ExtractedItem {
6
+ readonly sentences: readonly string[];
7
+ }
8
+ export interface FollowUpRules {
9
+ readonly rules: FollowUpRule[];
10
+ /** What the model call was billed; undefined when no call ran or the reply named none. */
11
+ readonly usage: LlmUsage | undefined;
12
+ }
13
+ /** The rules the model finds in the person's turns after the session's first, the last 20 of
14
+ * them; a failed call or an unreadable reply logs one line and gives none. Never throws. */
15
+ export declare function followUpRules(turns: readonly string[], llm: Llm, log: LineLog): Promise<FollowUpRules>;
16
+ /** One line per model call, in key=value form, so a harness can price it from the capture log. */
17
+ export declare function usageLine(usage: LlmUsage): string;
18
+ /** The pattern items but each one that is a whole sentence of a rule, then the rules; both read
19
+ * after `scrub`, so the comparison sees what is stored. */
20
+ export declare function withFollowUpRules(items: readonly ExtractedItem[], rules: readonly FollowUpRule[], scrub: (text: string) => string): ExtractedItem[];
21
+ //# sourceMappingURL=follow-up.d.ts.map
@@ -0,0 +1,164 @@
1
+ // Follow-up rules: a model picks which sentences of the person's later turns state a lasting rule,
2
+ // by number only, so capture stores the person's own words.
3
+ import { describeLlmFailure, llmFailureFields, } from '../../base/ports/llm.js';
4
+ import { isJsonObject, tryParseJson } from '../../base/util/json.js';
5
+ import { errorFields, errorMessage } from '../../base/util/log.js';
6
+ import { duplicateKey } from '../../base/util/same-text.js';
7
+ import { leftOpen, pickedText, statedSentences, statedText, } from './extract.js';
8
+ import { scrubForSharing } from './share-scrub.js';
9
+ import { detectInstruction } from '../../api/instruction-detect.js';
10
+ const FOLLOW_UP_TURNS = 20;
11
+ const TURN_CHARS = 1000;
12
+ // The prompt was measured on this model; the adapter's default picked task orders as rules (gate 2).
13
+ const MODEL = 'claude-sonnet-5-5';
14
+ // Adaptive thinking spends from the same cap as the reply.
15
+ const MAX_TOKENS = 4096;
16
+ // One attempt: the session-end cursor moves only when capture returns, so a hung call must not hold it.
17
+ const CALL_MS = 20_000;
18
+ // The prompt the held-out study measured, word for word.
19
+ const FROZEN_PROMPT = [
20
+ 'Each message below was typed by a person to a coding agent, after the first message of a session.',
21
+ 'Mark a message lasting if any part of it states something the agent must still follow in a LATER session:',
22
+ 'a way to work, something to always or never do, or a standing fact or requirement about the project ' +
23
+ 'or its output.',
24
+ 'A rule counts even when it sits inside a complaint, a correction or a task request.',
25
+ 'Mark it not lasting when it only asks for, checks on, approves or questions the current task.',
26
+ 'Each message is split into numbered sentences. Return only JSON: ' +
27
+ '[{"i": <message number>, "s": [<numbers of the sentences that state the lasting rule>]}] ' +
28
+ 'for messages with a lasting rule; leave other messages out.',
29
+ '',
30
+ '',
31
+ ].join('\n');
32
+ const LOG_LEAD = /^(?:\d{4}-\d\d-\d\d|\[\d|at [\w$.<>]+ ?\(|(?:[A-Za-z]:)?[^\s:]*[/\\.][^\s:]*:\d+|\$ |> )/;
33
+ /** A line of program output, not prose: the lead of a log, trace or prompt line, or few letters
34
+ * unless the sentence above is still open, as before a numeric condition. */
35
+ function isLogLine(line, sentenceOpen) {
36
+ if (LOG_LEAD.test(line.trimStart()))
37
+ return true;
38
+ const marks = line.replace(/\s/g, '');
39
+ const letters = marks.match(/\p{L}/gu)?.length ?? 0;
40
+ return !sentenceOpen && letters < 0.4 * marks.length;
41
+ }
42
+ /** One turn's numbered sentences, as a pattern reads them, scrubbed for sharing. */
43
+ function sentencesOf(turn) {
44
+ // Scrubbed again after: removing bold can rebuild an address or key the first pass could not see.
45
+ const sentences = statedSentences(scrubForSharing(turn), isLogLine)
46
+ .map(scrubForSharing)
47
+ .filter((piece) => piece.length >= 3);
48
+ // Whole sentences only: a sentence the limit cuts could lose its condition and still read as a rule.
49
+ const whole = [];
50
+ let used = 0;
51
+ for (const sentence of sentences) {
52
+ used += sentence.length + 1;
53
+ if (used > TURN_CHARS + 1)
54
+ break;
55
+ whole.push(sentence);
56
+ }
57
+ const last = whole.at(-1);
58
+ const cut = sentences[whole.length];
59
+ // A sentence with no stop may read on in the one the limit cut, so it could lose a condition too.
60
+ if (last !== undefined && cut !== undefined && leftOpen(last, cut))
61
+ whole.pop();
62
+ return whole;
63
+ }
64
+ function promptOf(turns) {
65
+ const messages = turns.map((sentences, i) => {
66
+ const numbered = sentences.map((sentence, j) => `<s n="${j}">${sentence}</s>`).join('');
67
+ return `<m i="${i}">${numbered}</m>\n`;
68
+ });
69
+ return FROZEN_PROMPT + messages.join('');
70
+ }
71
+ function isPick(value) {
72
+ return (isJsonObject(value) &&
73
+ Number.isInteger(value.i) &&
74
+ Array.isArray(value.s) &&
75
+ value.s.every((n) => Number.isInteger(n)));
76
+ }
77
+ /** The reply's picks, or why it holds none that can be read. */
78
+ function readPicks(text) {
79
+ const start = text.indexOf('[');
80
+ const end = text.lastIndexOf(']');
81
+ if (start < 0 || end < start)
82
+ return { problem: 'the reply held no JSON list' };
83
+ const parsed = tryParseJson(text.slice(start, end + 1));
84
+ if (parsed === undefined)
85
+ return { problem: 'the reply held a JSON list that does not parse' };
86
+ if (!Array.isArray(parsed) || !parsed.every(isPick)) {
87
+ return { problem: 'the reply was not a list of {"i", "s"} picks' };
88
+ }
89
+ return { picks: parsed };
90
+ }
91
+ /** One rule per turn with picks: its picked sentences in turn order; an id out of range is dropped. */
92
+ function rulesOf(turns, picks) {
93
+ const chosen = new Map();
94
+ for (const { i, s } of picks) {
95
+ const sentences = turns[i];
96
+ if (sentences === undefined)
97
+ continue;
98
+ const ids = chosen.get(i) ?? new Set();
99
+ for (const j of s)
100
+ if (j >= 0 && j < sentences.length)
101
+ ids.add(j);
102
+ chosen.set(i, ids);
103
+ }
104
+ return [...chosen.keys()]
105
+ .sort((a, b) => a - b)
106
+ .flatMap((i) => {
107
+ const ids = [...(chosen.get(i) ?? [])].sort((a, b) => a - b);
108
+ const sentences = ids.map((j) => turns[i][j]);
109
+ const content = pickedText(sentences);
110
+ // It prints as the person's order, so text shaped like an injected instruction never becomes one.
111
+ if (content === null || detectInstruction(content).flagged)
112
+ return [];
113
+ return [{ content, category: 'rule', tags: ['follow-up'], fromUser: true, sentences }];
114
+ });
115
+ }
116
+ async function ask(llm, prompt, log) {
117
+ const signal = AbortSignal.timeout(CALL_MS);
118
+ let reply;
119
+ try {
120
+ reply = await llm.send({ model: MODEL, maxTokens: MAX_TOKENS, prompt, signal });
121
+ }
122
+ catch (err) {
123
+ // The port never throws, but capture must outlive an adapter that does.
124
+ log(`follow-up rules skipped: the model call threw: ${errorMessage(err)}`, {
125
+ fields: errorFields(err),
126
+ });
127
+ return { text: null, usage: undefined };
128
+ }
129
+ if (reply.ok)
130
+ return { text: reply.text, usage: reply.usage };
131
+ const cause = signal.aborted
132
+ ? `the model call passed ${CALL_MS / 1000} s`
133
+ : describeLlmFailure(reply.failure);
134
+ log(`follow-up rules skipped: ${cause}`, { fields: llmFailureFields(reply.failure) });
135
+ return { text: null, usage: reply.usage };
136
+ }
137
+ /** The rules the model finds in the person's turns after the session's first, the last 20 of
138
+ * them; a failed call or an unreadable reply logs one line and gives none. Never throws. */
139
+ export async function followUpRules(turns, llm, log) {
140
+ const messages = turns.slice(-FOLLOW_UP_TURNS).map(sentencesOf);
141
+ if (messages.every((sentences) => sentences.length === 0))
142
+ return { rules: [], usage: undefined };
143
+ const { text, usage } = await ask(llm, promptOf(messages), log);
144
+ if (text === null)
145
+ return { rules: [], usage };
146
+ const read = readPicks(text);
147
+ if ('problem' in read) {
148
+ log(`follow-up rules skipped: ${read.problem}`);
149
+ return { rules: [], usage };
150
+ }
151
+ return { rules: rulesOf(messages, read.picks), usage };
152
+ }
153
+ /** One line per model call, in key=value form, so a harness can price it from the capture log. */
154
+ export function usageLine(usage) {
155
+ return `follow-up rules: model=${MODEL} input_tokens=${usage.inputTokens} output_tokens=${usage.outputTokens}`;
156
+ }
157
+ /** The pattern items but each one that is a whole sentence of a rule, then the rules; both read
158
+ * after `scrub`, so the comparison sees what is stored. */
159
+ export function withFollowUpRules(items, rules, scrub) {
160
+ const keyOf = (text) => duplicateKey(scrub(text));
161
+ const held = new Set(rules.flatMap((rule) => rule.sentences.map((s) => keyOf(statedText(s)))));
162
+ return [...items.filter((item) => !held.has(keyOf(item.content))), ...rules];
163
+ }
164
+ //# sourceMappingURL=follow-up.js.map
@@ -1,5 +1,6 @@
1
1
  import type { HookRuntime } from '../../base/session/capture-contract.js';
2
2
  import type { CaptureTarget } from '../capture/command.js';
3
+ import type { WorkerMode } from '../capture/session-worker.js';
3
4
  import type { HeldLog } from '../../api/session-end.js';
4
5
  import { type LogFields } from '../../base/util/log.js';
5
6
  import { type CliFlags } from './flag-values.js';
@@ -53,7 +54,7 @@ export declare function payloadCwdRoot(hippoRoot: string, stdinText: string | un
53
54
  export declare function inPilotHoldout(hippoRoot: string, tenantId: string, sessionId: string | undefined, opts: {
54
55
  write: boolean;
55
56
  }): Promise<boolean>;
56
- /** What capture writes into for a store folder: its port, its config and what embeds the new
57
- * rows. */
58
- export declare function captureTarget(root: string): CaptureTarget;
57
+ /** What capture writes into for a store folder: its port, its config, what embeds the new rows,
58
+ * and the model a whole capture asks for follow-up rules when the folder's config turns it on. */
59
+ export declare function captureTarget(root: string, mode: WorkerMode): CaptureTarget;
59
60
  //# sourceMappingURL=hook-runtime.d.ts.map
@@ -7,6 +7,7 @@ import { bookTokenUse } from '../../api/ledger-db.js';
7
7
  import { sessionPilotArm } from '../../api/pilot-arm.js';
8
8
  import { cliDetached, cliFolder, cliInfra, cliLedgerReach, cliSyncOptions } from './api-context.js';
9
9
  import { detachedEmbedder } from '../../api/embeddings.js';
10
+ import { anthropicLlmFromEnv } from '../../infra/ports.js';
10
11
  import { hookPayloadSessionId, hookPayloadString, isSubagentPayload, } from '../../base/util/hook-payload.js';
11
12
  import { importAtSessionEnd } from '../../api/agent-memories.js';
12
13
  import { currentMachine } from '../../infra/machine.js';
@@ -148,15 +149,22 @@ export async function inPilotHoldout(hippoRoot, tenantId, sessionId, opts) {
148
149
  const reach = cliLedgerReach(hippoRoot);
149
150
  return (await sessionPilotArm(tenantId, sessionId, opts.write, { reach })) === 'holdout';
150
151
  }
151
- /** What capture writes into for a store folder: its port, its config and what embeds the new
152
- * rows. */
153
- export function captureTarget(root) {
152
+ /** What capture writes into for a store folder: its port, its config, what embeds the new rows,
153
+ * and the model a whole capture asks for follow-up rules when the folder's config turns it on. */
154
+ export function captureTarget(root, mode) {
154
155
  const folder = cliFolder(root);
156
+ // A per-reply capture sees only the turns since the last reply, and would pay for a call per reply.
157
+ const askModel = mode === 'full' && folder.config.capture.followUpRules === 'model';
158
+ const llm = askModel ? anthropicLlmFromEnv() : undefined;
155
159
  return {
156
160
  root,
157
161
  store: folder.store,
158
162
  config: folder.config,
159
163
  embed: detachedEmbedder(folder, cliInfra(), cliDetached()),
164
+ llm,
165
+ llmMissing: askModel && llm === undefined
166
+ ? 'capture.followUpRules is "model" but ANTHROPIC_API_KEY is not set; follow-up rules skipped'
167
+ : undefined,
160
168
  };
161
169
  }
162
170
  //# sourceMappingURL=hook-runtime.js.map
@@ -13,7 +13,7 @@ export async function handleCapture({ hippoRoot, tenantId, flags }) {
13
13
  ? await readHookStdin()
14
14
  : { text: undefined, timedOut: false };
15
15
  const useGlobal = boolFlag(flags, 'global');
16
- await runCapture(captureTarget(useGlobal ? hippoHomeDir() : hippoRoot), {
16
+ await runCapture(captureTarget(useGlobal ? hippoHomeDir() : hippoRoot, 'full'), {
17
17
  source: captureSource,
18
18
  filePath: captureFile,
19
19
  transcriptPath,
@@ -85,7 +85,7 @@ async function captureCodexRollout({ hippoRoot, tenantId, store, logFile }, tran
85
85
  sessionTurns: scan?.turns,
86
86
  };
87
87
  try {
88
- await runCapture(captureTarget(store), captureOpts);
88
+ await runCapture(captureTarget(store, 'full'), captureOpts);
89
89
  }
90
90
  catch (err) {
91
91
  reportSessionEndFailure(logFile, 'codex session-end: capture', err);
@@ -43,7 +43,7 @@ function runSessionEndWork({ hippoRoot, tenantId, flags, mode, held, }) {
43
43
  const root = into === ctx ? hippoRoot : ctx.reach?.global?.root;
44
44
  if (root === undefined)
45
45
  return false;
46
- const ended = { tenantId, flags, transcriptPath, turns, originProject, fromStart };
46
+ const ended = { tenantId, flags, transcriptPath, turns, originProject, fromStart, mode };
47
47
  return captureEndedSession(root, ended);
48
48
  },
49
49
  digest: (scan, key, log) => recordSessionDigest(hippoRoot, ctx.store, scan, { key, tenantId, log, config: ctx.config }),
@@ -63,10 +63,10 @@ async function sleepFolderStore(hippoRoot, tenantId, flags, closeLogFile) {
63
63
  }
64
64
  }
65
65
  /** True when capture ran to the end, so a turn close may move its cursor past these turns. */
66
- async function captureEndedSession(store, { tenantId, flags, transcriptPath, turns, originProject, fromStart }) {
66
+ async function captureEndedSession(store, { tenantId, flags, transcriptPath, turns, originProject, fromStart, mode }) {
67
67
  const logFile = stringFlag(flags, 'log-file') ?? null;
68
68
  try {
69
- await runCapture(captureTarget(store), {
69
+ await runCapture(captureTarget(store, mode), {
70
70
  source: 'last-session',
71
71
  transcriptPath,
72
72
  logFile,
@@ -2,7 +2,7 @@
2
2
  "id": "hippo-memory",
3
3
  "name": "Hippo Memory",
4
4
  "description": "Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.",
5
- "version": "3.2.2",
5
+ "version": "3.3.0",
6
6
 
7
7
  "configSchema": {
8
8
  "type": "object",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hippo-memory",
3
- "version": "3.2.2",
3
+ "version": "3.3.0",
4
4
  "type": "module",
5
5
  "description": "Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.",
6
6
  "main": "index.ts",
@@ -2,7 +2,7 @@
2
2
  "id": "hippo-memory",
3
3
  "name": "Hippo Memory",
4
4
  "description": "Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.",
5
- "version": "3.2.2",
5
+ "version": "3.3.0",
6
6
  "configSchema": {
7
7
  "type": "object",
8
8
  "additionalProperties": false,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hippo-memory",
3
- "version": "3.2.2",
3
+ "version": "3.3.0",
4
4
  "description": "Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.",
5
5
  "mcpName": "io.github.kitfunso/hippo-memory",
6
6
  "type": "module",