hippo-memory 3.1.1 → 3.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/dist/api/context/context-plan.d.ts +2 -0
  2. package/dist/api/context/context-plan.js +8 -2
  3. package/dist/api/context/context-pools.d.ts +3 -0
  4. package/dist/api/context/context-pools.js +12 -0
  5. package/dist/api/context/context-render.d.ts +6 -0
  6. package/dist/api/context/context-render.js +24 -9
  7. package/dist/api/context/context-types.d.ts +6 -3
  8. package/dist/api/context/context.js +5 -4
  9. package/dist/api/context/user-rule.d.ts +12 -0
  10. package/dist/api/context/user-rule.js +24 -0
  11. package/dist/api/context/user-rules-get.d.ts +10 -0
  12. package/dist/api/context/user-rules-get.js +25 -0
  13. package/dist/api/index.d.ts +1 -0
  14. package/dist/api/index.js +1 -0
  15. package/dist/api/memories/remember.js +2 -2
  16. package/dist/api/prompt-hook.d.ts +11 -0
  17. package/dist/api/prompt-hook.js +26 -10
  18. package/dist/api/session-end.d.ts +1 -1
  19. package/dist/api/session-end.js +5 -3
  20. package/dist/base/memory/entry.d.ts +5 -0
  21. package/dist/base/memory/entry.js +8 -1
  22. package/dist/base/ports/store/capture.d.ts +3 -0
  23. package/dist/base/ports/store/ledger.d.ts +2 -2
  24. package/dist/base/ports/store/types.d.ts +3 -1
  25. package/dist/base/util/same-text.d.ts +7 -0
  26. package/dist/base/util/same-text.js +12 -0
  27. package/dist/base/util/version.d.ts +1 -1
  28. package/dist/base/util/version.js +1 -1
  29. package/dist/store/sqlite/capture/captures.js +33 -8
  30. package/dist/store/sqlite/entries/entry-writes.d.ts +5 -0
  31. package/dist/store/sqlite/entries/entry-writes.js +13 -0
  32. package/dist/store/sqlite/ledger/token-ledger.js +7 -1
  33. package/dist/store/sqlite/recall/candidates.js +3 -0
  34. package/dist/store/sqlite/sharing/copy-rows.d.ts +2 -0
  35. package/dist/store/sqlite/sharing/copy-rows.js +2 -1
  36. package/dist/surface/capture/command.d.ts +9 -2
  37. package/dist/surface/capture/command.js +67 -48
  38. package/dist/surface/capture/extract.d.ts +9 -2
  39. package/dist/surface/capture/extract.js +80 -20
  40. package/dist/surface/capture/transcript.js +6 -1
  41. package/dist/surface/cli/context.d.ts +7 -0
  42. package/dist/surface/cli/context.js +17 -10
  43. package/dist/surface/cli/hook.js +3 -0
  44. package/dist/surface/cli/hooks/session-end-worker.js +5 -3
  45. package/dist/surface/cli/init.js +3 -0
  46. package/dist/surface/cli/memory-import.js +2 -1
  47. package/dist/surface/cli/session-rules.d.ts +3 -0
  48. package/dist/surface/cli/session-rules.js +45 -0
  49. package/dist/surface/cli/setup.js +2 -0
  50. package/dist/surface/cli/verbs/sessions.d.ts +1 -0
  51. package/dist/surface/cli/verbs/sessions.js +10 -2
  52. package/dist/surface/cli/verbs.d.ts +1 -0
  53. package/dist/surface/hooks-install/rules/claude-hooks.js +11 -3
  54. package/dist/surface/hooks-install/rules/install-plan.js +1 -0
  55. package/dist/surface/hooks-install/rules/json-hooks.d.ts +2 -0
  56. package/dist/surface/hooks-install/rules/shared.d.ts +2 -0
  57. package/dist/surface/hooks-install/rules/shared.js +2 -0
  58. package/dist-ui/assets/{index-DWo8WuPW.js → index-DvZmCHQ5.js} +2 -2
  59. package/dist-ui/assets/{react-BZPdts19.js → react-BpaniaUk.js} +2 -2
  60. package/dist-ui/index.html +2 -2
  61. package/extensions/openclaw-plugin/openclaw.plugin.json +1 -1
  62. package/extensions/openclaw-plugin/package.json +1 -1
  63. package/openclaw.plugin.json +1 -1
  64. package/package.json +2 -2
@@ -38,6 +38,8 @@ export interface ContextPlan {
38
38
  promptRecallPending: boolean;
39
39
  cost: ContextCost | undefined;
40
40
  price: (entry: MemoryEntry, isGlobal: boolean, promptRecall?: boolean) => number;
41
+ /** Whether a row prints as the person's own rule for this caller. */
42
+ isUserRule: (entry: MemoryEntry, isGlobal: boolean) => boolean;
41
43
  obs: DeliveryObserver | undefined;
42
44
  /** The instant the whole read scores strength at, by the model its Context runs under. */
43
45
  now: Date;
@@ -5,6 +5,7 @@ import { classifyOriginProject, projectId, projectNames, } from '../../base/scop
5
5
  import { DEFAULT_CONFIG } from '../../base/config/config.js';
6
6
  import { promptSearchTerms } from '../../base/rank/prompt-recall.js';
7
7
  import { personalScopeOf } from '../../base/scope/recall-scope.js';
8
+ import { isUserRule } from './user-rule.js';
8
9
  import { finiteOr } from '../../domain/context/select-policy.js';
9
10
  import { strengthOf } from '../types.js';
10
11
  /** The operator's global store, which planContext proved present before it set hasGlobal. */
@@ -50,7 +51,7 @@ export function globalSource(ctx) {
50
51
  }
51
52
  /** Prices one entry against the budget: the caller's cost model when it gave one, else a token
52
53
  * estimate. */
53
- function entryPricer(cost, currentProject) {
54
+ function entryPricer(cost, currentProject, userRule) {
54
55
  return (entry, isGlobal, promptRecall) => cost
55
56
  ? cost.entry({
56
57
  entry,
@@ -58,6 +59,7 @@ function entryPricer(cost, currentProject) {
58
59
  promptRecall,
59
60
  origin: entry.originProject ?? null,
60
61
  category: classifyOriginProject(entry.originProject, currentProject),
62
+ userRule: userRule(entry, isGlobal),
61
63
  })
62
64
  : estimateTokens(entry.content);
63
65
  }
@@ -97,7 +99,8 @@ export function planContext(ctx, opts, local) {
97
99
  // connection.
98
100
  const promptRecallPending = pinnedOnly && Boolean(opts.prompt?.trim()) && config.pinnedInject.promptRecall === true;
99
101
  const cost = opts.cost;
100
- const price = entryPricer(cost, currentProject);
102
+ const userRule = (entry, isGlobal) => isUserRule(entry, { tenantId: ctx.tenantId, project: currentProject, isGlobal });
103
+ const price = entryPricer(cost, currentProject, userRule);
101
104
  return {
102
105
  local,
103
106
  pinnedOnly,
@@ -117,6 +120,7 @@ export function planContext(ctx, opts, local) {
117
120
  promptRecallPending,
118
121
  cost,
119
122
  price,
123
+ isUserRule: userRule,
120
124
  obs: opts.deliveryObserver,
121
125
  now: ctx.infra.clock(),
122
126
  strength: strengthOf(ctx),
@@ -157,6 +161,8 @@ export function openBlockBudget(plan, opts, budget) {
157
161
  cross: plan.includeCrossProject,
158
162
  promptRecall: promptRecallPending,
159
163
  ambient: !pinnedOnly && config.ambient.enabled,
164
+ // Unknown until the rows load; userRuleReserve pays it then.
165
+ userRule: false,
160
166
  }))
161
167
  : blockBudget;
162
168
  }
@@ -25,5 +25,8 @@ interface LoadPoolsOptions {
25
25
  readonly left: number;
26
26
  }
27
27
  export declare function loadPools(ctx: Context, { plan, admission, recallRequest, left }: LoadPoolsOptions): Promise<ContextPools>;
28
+ /** The tokens of the user-rule heading: nothing unless a loaded row prints under it. SHORTCUT: paid
29
+ * when the pool holds a user rule, even if the ranking then leaves it out; one heading of slack. */
30
+ export declare function userRuleReserve(plan: ContextPlan, pools: ContextPools): number;
28
31
  export {};
29
32
  //# sourceMappingURL=context-pools.d.ts.map
@@ -110,6 +110,18 @@ export async function loadPools(ctx, { plan, admission, recallRequest, left }) {
110
110
  : { entries: [] };
111
111
  return { local, global };
112
112
  }
113
+ /** The tokens of the user-rule heading: nothing unless a loaded row prints under it. SHORTCUT: paid
114
+ * when the pool holds a user rule, even if the ranking then leaves it out; one heading of slack. */
115
+ export function userRuleReserve(plan, pools) {
116
+ const { cost } = plan;
117
+ const held = pools.local.entries.some((e) => plan.isUserRule(e, plan.primaryIsGlobal)) ||
118
+ pools.global.entries.some((e) => plan.isUserRule(e, true));
119
+ if (!cost || !held)
120
+ return 0;
121
+ // The headings are priced apart, so the two totals differ by the user-rule heading alone.
122
+ const can = { cross: false, promptRecall: false, ambient: false };
123
+ return cost.fixed(0, { ...can, userRule: true }) - cost.fixed(0, { ...can, userRule: false });
124
+ }
113
125
  // With prompt recall on, eligibility reports a row the quality floor drops.
114
126
  function refusalReporter(plan, isGlobal) {
115
127
  const { obs } = plan;
@@ -37,6 +37,12 @@ export declare function contextBlockLines(items: ReadonlyArray<{
37
37
  heading?: string;
38
38
  strength?: StrengthModel;
39
39
  }): string[];
40
+ export declare const USER_RULES_HEADING = "## Rules from the user";
41
+ /** The person's own rule as a plain instruction: no confidence, date or tags to read it as an old
42
+ * note. */
43
+ export declare function userRuleLine(e: MemoryEntry): string;
44
+ /** The section that opens a block; no rules print nothing, and the blank line closes it. */
45
+ export declare function userRuleLines(entries: readonly MemoryEntry[]): string[];
40
46
  export declare function crossProjectHeading(entries: number): string;
41
47
  export declare function crossProjectLine(item: Pick<ContextResultEntry, 'entry' | 'origin'>): string;
42
48
  /** An explicit header lets agents and humans tell borrowed context from project memory; no items
@@ -167,6 +167,18 @@ export function contextBlockLines(items, totalTokens, framing, opts) {
167
167
  })),
168
168
  ];
169
169
  }
170
+ export const USER_RULES_HEADING = '## Rules from the user';
171
+ // The person's reply lead ("No:", "Yes, keep doing that:") reads as an answer, not as an order.
172
+ const CORRECTION_LEAD = /^(?:No|Yes, keep doing that):\s*/;
173
+ /** The person's own rule as a plain instruction: no confidence, date or tags to read it as an old
174
+ * note. */
175
+ export function userRuleLine(e) {
176
+ return `- ${shownContent({ ...e, content: e.content.replace(CORRECTION_LEAD, '') })}`;
177
+ }
178
+ /** The section that opens a block; no rules print nothing, and the blank line closes it. */
179
+ export function userRuleLines(entries) {
180
+ return entries.length === 0 ? [] : [USER_RULES_HEADING, ...entries.map(userRuleLine), ''];
181
+ }
170
182
  export function crossProjectHeading(entries) {
171
183
  return `\n## Other-project memory (explicitly requested, ${entries} entries)\n`;
172
184
  }
@@ -262,16 +274,19 @@ export function contextCost(format, framing, now) {
262
274
  const hook = format === 'additional-context';
263
275
  const price = printedTokens;
264
276
  return {
265
- entry: (item) => price(item.category === 'cross-project' && !(hook && item.promptRecall)
266
- ? crossProjectLine(item)
267
- : contextLine({
268
- item: { entry: item.entry, isGlobal: item.isGlobal ?? false },
269
- framing,
270
- showStrength: !hook,
271
- now,
272
- strengthPct: FULL_STRENGTH_PCT,
273
- })),
277
+ entry: (item) => price(item.userRule
278
+ ? userRuleLine(item.entry)
279
+ : item.category === 'cross-project' && !(hook && item.promptRecall)
280
+ ? crossProjectLine(item)
281
+ : contextLine({
282
+ item: { entry: item.entry, isGlobal: item.isGlobal ?? false },
283
+ framing,
284
+ showStrength: !hook,
285
+ now,
286
+ strengthPct: FULL_STRENGTH_PCT,
287
+ })),
274
288
  fixed: (budget, can) => price(contextHeading('Project Memory', budget, budget)) +
289
+ (can.userRule ? price(`${USER_RULES_HEADING}\n`) : 0) +
275
290
  (can.cross ? price(crossProjectHeading(budget)) : 0) +
276
291
  (hook && can.promptRecall
277
292
  ? price(contextHeading('Prompt-Relevant Memory', budget, budget))
@@ -66,14 +66,17 @@ export interface ContextOptions {
66
66
  }
67
67
  /** Budget prices in the text a caller prints, so the budget bounds what reaches the model. */
68
68
  export interface ContextCost {
69
- /** Tokens of one entry as printed. */
70
- entry: (item: Pick<ContextResultEntry, 'entry' | 'isGlobal' | 'promptRecall' | 'origin' | 'category'>) => number;
69
+ /** Tokens of one entry as printed; `userRule` marks a row that prints as the person's own rule. */
70
+ entry: (item: Pick<ContextResultEntry, 'entry' | 'isGlobal' | 'promptRecall' | 'origin' | 'category'> & {
71
+ userRule?: boolean;
72
+ }) => number;
71
73
  /** Tokens of the headers and footer the block can print at this budget, reserved before any
72
- * entry. */
74
+ * entry. `userRule` is true only when the view holds a user rule. */
73
75
  fixed: (budget: number, can: {
74
76
  cross: boolean;
75
77
  promptRecall: boolean;
76
78
  ambient: boolean;
79
+ userRule: boolean;
77
80
  }) => number;
78
81
  /** Tokens of the sections printed ahead of the memories, each as printed. */
79
82
  snapshot: (s: TaskSnapshot, mode: ContinuityMode) => number;
@@ -10,7 +10,7 @@ import { selectBySearch } from './context-search.js';
10
10
  import { strengthenOf } from '../recall/finish.js';
11
11
  import { keepShownIds } from '../recall/last-recalled.js';
12
12
  import { NO_QUERY, sourceOf, globalSource, planContext, promptRecallRequest, openBlockBudget, } from './context-plan.js';
13
- import { ambientAdmission, loadPools } from './context-pools.js';
13
+ import { ambientAdmission, loadPools, userRuleReserve } from './context-pools.js';
14
14
  import { loadTaskSections, pointerModes } from './context-task-state.js';
15
15
  /** Tokens a context block may use when the caller sets no budget; the hook command and the CLI
16
16
  * default match it. */
@@ -39,11 +39,12 @@ export async function assembleContext(ctx, opts) {
39
39
  const noSections = !sections.shownSnapshot && !sections.shownHandoff && sections.shownEvents.length === 0;
40
40
  if (nothingToInject(plan, pools, noSections))
41
41
  return { entries: [], tokens: 0 };
42
+ const left = Math.max(0, sections.left - userRuleReserve(plan, pools));
42
43
  const picked = plan.pinnedOnly
43
- ? selectPinned({ opts, plan, left: sections.left, pools, admission })
44
+ ? selectPinned({ opts, plan, left, pools, admission })
44
45
  : plan.query === NO_QUERY
45
- ? selectStrongest(plan, sections.left, pools)
46
- : await selectBySearch(ctx, { plan, left: sections.left, pools, admission });
46
+ ? selectStrongest(plan, left, pools)
47
+ : await selectBySearch(ctx, { plan, left, pools, admission });
47
48
  if (picked === null)
48
49
  return { entries: [], tokens: 0 };
49
50
  const { items, tokens } = finalizeSelection(picked, plan);
@@ -0,0 +1,12 @@
1
+ import { USER_RULE_TAG, type MemoryEntry } from '../../base/memory/entry.js';
2
+ import { type ProjectRef } from '../../base/scope/project-identity.js';
3
+ export { USER_RULE_TAG };
4
+ /** Who reads the block, and where the row lives: a row's origin is the project id capture stamped,
5
+ * so it can be any name the project had; '' is no project. */
6
+ export interface UserRuleViewer {
7
+ readonly tenantId: string;
8
+ readonly project: ProjectRef;
9
+ readonly isGlobal: boolean;
10
+ }
11
+ export declare function isUserRule(e: MemoryEntry, viewer: UserRuleViewer): boolean;
12
+ //# sourceMappingURL=user-rule.d.ts.map
@@ -0,0 +1,24 @@
1
+ // Which rows print as the person's own rules: only capture sets the tag, so a row nobody typed
2
+ // cannot pass for one.
3
+ import { USER_RULE_TAG } from '../../base/memory/entry.js';
4
+ import { projectId, projectNames } from '../../base/scope/project-identity.js';
5
+ export { USER_RULE_TAG };
6
+ export function isUserRule(e, viewer) {
7
+ const own = e.pinned &&
8
+ e.source === 'capture' &&
9
+ e.confidence === 'observed' &&
10
+ e.tags.includes(USER_RULE_TAG) &&
11
+ e.supersededBy === null &&
12
+ e.scope === null &&
13
+ e.tenantId === viewer.tenantId;
14
+ if (!own)
15
+ return false;
16
+ // A project store's rows are that project's; capture leaves their origin unset (session-end.ts).
17
+ const origin = e.originProject ?? null;
18
+ const names = projectId(viewer.project) === '' ? [] : projectNames(viewer.project);
19
+ if (!viewer.isGlobal)
20
+ return origin === null || names.includes(origin);
21
+ // A global row is a rule only in the project capture stamped on it; a null origin matches none.
22
+ return origin !== null && names.includes(origin);
23
+ }
24
+ //# sourceMappingURL=user-rule.js.map
@@ -0,0 +1,10 @@
1
+ import type { MemoryEntry } from '../../base/memory/entry.js';
2
+ import type { Context } from '../types.js';
3
+ import type { ContextOptions } from './context-types.js';
4
+ /** What a user-rules read needs to know of its caller. */
5
+ export type UserRulesOptions = Pick<ContextOptions, 'currentProject' | 'currentSessionId'>;
6
+ /** The tenant's user rules for the current project from the project store and the global store,
7
+ * oldest first, each id once; empty when pinned injection is off. Skips the budgeted selection, so
8
+ * a long list is never cut. */
9
+ export declare function userRulesGet(ctx: Context, opts: UserRulesOptions): Promise<MemoryEntry[]>;
10
+ //# sourceMappingURL=user-rules-get.d.ts.map
@@ -0,0 +1,25 @@
1
+ import { compareEntryIdentity } from '../../base/rank/compare.js';
2
+ import { planContext, sourceOf } from './context-plan.js';
3
+ import { ambientAdmission, loadPools } from './context-pools.js';
4
+ /** The tenant's user rules for the current project from the project store and the global store,
5
+ * oldest first, each id once; empty when pinned injection is off. Skips the budgeted selection, so
6
+ * a long list is never cut. */
7
+ export async function userRulesGet(ctx, opts) {
8
+ if (!ctx.config.pinnedInject.enabled)
9
+ return [];
10
+ const pinned = { ...opts, pinnedOnly: true, includeRecent: 0 };
11
+ const plan = planContext(ctx, pinned, sourceOf(ctx.store));
12
+ const admission = ambientAdmission(pinned, plan, null);
13
+ const pools = await loadPools(ctx, { plan, admission, recallRequest: undefined, left: 0 });
14
+ const rules = new Map();
15
+ const keep = (rows, isGlobal) => {
16
+ for (const e of rows) {
17
+ if (plan.isUserRule(e, isGlobal) && !rules.has(e.id))
18
+ rules.set(e.id, e);
19
+ }
20
+ };
21
+ keep(pools.local.entries, plan.primaryIsGlobal);
22
+ keep(pools.global.entries, true);
23
+ return [...rules.values()].sort((a, b) => Date.parse(a.created) - Date.parse(b.created) || compareEntryIdentity(a, b));
24
+ }
25
+ //# sourceMappingURL=user-rules-get.js.map
@@ -35,6 +35,7 @@ export { auditList, auditMemoryQuality, computeCutoff, auditPrune, auditRemoveEr
35
35
  export type { AuditListOptions, AuditPass, PruneAuditOptions, PruneAuditResult, } from './auth/audit.js';
36
36
  export type { ContextCost, ContextOptions, ContextResult, ContextResultEntry, ContinuityMode, } from './context/context-types.js';
37
37
  export { DEFAULT_CONTEXT_BUDGET, contextGet } from './context/context.js';
38
+ export { userRulesGet, type UserRulesOptions } from './context/user-rules-get.js';
38
39
  export { NO_QUERY } from './context/context-plan.js';
39
40
  export { contextProjectFor, type ProjectFacts } from './context/context-project.js';
40
41
  export { failureSummary, recordTokens, tokenSummary } from './tokens.js';
package/dist/api/index.js CHANGED
@@ -24,6 +24,7 @@ export { rawArchive, rawArchiveForEvent, promote, supersede } from './memories/p
24
24
  export { DEFAULT_KEY_TTL_DAYS, MAX_TTL_DAYS, authCreate, authCreateSelf, authGrant, authKeyTenant, authListAllTenants, authListRows, authRevoke, authUngrant, } from './auth/auth.js';
25
25
  export { auditList, auditMemoryQuality, computeCutoff, auditPrune, auditRemoveErrors, memoryQualityRepair, memoryQualityRepairOnce, } from './auth/audit.js';
26
26
  export { DEFAULT_CONTEXT_BUDGET, contextGet } from './context/context.js';
27
+ export { userRulesGet } from './context/user-rules-get.js';
27
28
  export { NO_QUERY } from './context/context-plan.js';
28
29
  export { contextProjectFor } from './context/context-project.js';
29
30
  export { failureSummary, recordTokens, tokenSummary } from './tokens.js';
@@ -2,7 +2,7 @@
2
2
  // instruction check.
3
3
  import { detectInstruction, INSTRUCTION_LIKE_TAG, UNTRUSTED_ORIGIN_TAG, } from '../instruction-detect.js';
4
4
  import { quarantineScopeFor } from '../../domain/trust/quarantine.js';
5
- import { createMemory, } from '../../base/memory/entry.js';
5
+ import { createMemory, withoutUserTag, } from '../../base/memory/entry.js';
6
6
  import { computeSalience } from '../../base/memory/salience.js';
7
7
  import { vetSecrets } from '../../base/util/secret-detect.js';
8
8
  import { assertCallerProject } from '../../base/scope/project-identity.js';
@@ -55,7 +55,7 @@ function prepareRemember(ctx, opts, untrusted) {
55
55
  ? detectInstruction(vetted.content)
56
56
  : { flagged: false, reason: null };
57
57
  const flagged = !untrusted && memberShares(ctx, opts) && detectInstruction(vetted.content).flagged;
58
- const tags = trustTagged(opts.tags, untrusted, flagged);
58
+ const tags = trustTagged(opts.tags && withoutUserTag(opts.tags), untrusted, flagged);
59
59
  const local = opts.local ?? {};
60
60
  const created = createMemory(vetted.content, {
61
61
  layer: local.layer,
@@ -7,10 +7,14 @@ import { type JsonValue } from '../base/util/json.js';
7
7
  import { type LedgerReach } from './ledger-db.js';
8
8
  import type { MemoryEntry } from '../base/memory/entry.js';
9
9
  import type { PilotArm } from '../base/session/pilot-arm.js';
10
+ import { type ProjectRef } from '../base/scope/project-identity.js';
10
11
  /** What one render needs once api.contextGet has answered. */
11
12
  export interface ContextView {
12
13
  readonly config: HippoConfig;
13
14
  readonly tenantId: string;
15
+ /** The reader's project, with every name capture may have stamped its rows with; a user rule
16
+ * belongs to this project alone. */
17
+ readonly project: ProjectRef;
14
18
  readonly ledgerSessionId: string | undefined;
15
19
  readonly payloadSessionId: string | undefined;
16
20
  readonly pinnedOnly: boolean;
@@ -47,6 +51,13 @@ export declare function toRenderItems(entries: ContextResultEntry[]): RenderItem
47
51
  /** The hook format's stdout, '' when nothing is sent: a skippable static block (snapshot,
48
52
  * handoff, events, pins, recent-N) and a never-skipped recall block. */
49
53
  export declare function additionalContextOutput(view: ContextView): Promise<string>;
54
+ /** The rows that print as the person's own rules, and the rest: a rule prints once, in its own
55
+ * section. */
56
+ export interface UserRuleSplit {
57
+ readonly userRules: MemoryEntry[];
58
+ readonly others: ContextResultEntry[];
59
+ }
60
+ export declare function splitUserRules(view: Pick<ContextView, 'tenantId' | 'project' | 'result'>): UserRuleSplit;
50
61
  /**
51
62
  * The project a hook caller runs in: its id, the folder name its older rows carry, and any other
52
63
  * names it resolves to.
@@ -1,12 +1,13 @@
1
1
  import { assembleContext } from './context/context.js';
2
2
  import { sharedStoreOf, strengthOf } from './types.js';
3
3
  import { BadRequestError } from '../base/errors/api-errors.js';
4
- import { contextBlockLines, contextCost, crossProjectLines, handoffSectionText, sessionTrailText, settleTokens, snapshotSectionText, } from './context/context-render.js';
4
+ import { contextBlockLines, contextCost, crossProjectLines, handoffSectionText, sessionTrailText, settleTokens, snapshotSectionText, userRuleLines, } from './context/context-render.js';
5
+ import { isUserRule } from './context/user-rule.js';
5
6
  import { MAX_ID_LEN } from '../base/util/limits.js';
6
7
  import { isJsonString } from '../base/util/json.js';
7
8
  import { bookLedgerTurn, bookLedgerTurnPerRow, ledgerLastSent, ledgerReachOf, takeDelivery, } from './ledger-db.js';
8
9
  import { sessionPilotArm } from './pilot-arm.js';
9
- import { assertCallerProject, MAX_PROJECT_ALIASES } from '../base/scope/project-identity.js';
10
+ import { assertCallerProject, MAX_PROJECT_ALIASES, } from '../base/scope/project-identity.js';
10
11
  import { shouldSkipUnchanged } from '../base/session/skip-unchanged.js';
11
12
  import { hookPayloadString, isSubagentPayload } from '../base/util/hook-payload.js';
12
13
  import { blockHash, estimateTokens } from '../base/util/token-text.js';
@@ -44,9 +45,10 @@ export function toRenderItems(entries) {
44
45
  export async function additionalContextOutput(view) {
45
46
  return (await renderAdditionalContext(view)).stdout;
46
47
  }
47
- function renderStaticBlock(view, staticItems, staticCrossEntries) {
48
+ function renderStaticBlock(view, userRules, staticItems, staticCrossEntries) {
48
49
  const { result, framing } = view;
49
50
  return settleTokens((t) => [
51
+ ...userRuleLines(userRules),
50
52
  ...(result.activeSnapshot
51
53
  ? [snapshotSectionText(result.activeSnapshot, result.snapshotMode ?? 'full')]
52
54
  : []),
@@ -73,28 +75,41 @@ function renderRecallBlock(recallItems, framing, now) {
73
75
  heading: 'Prompt-Relevant Memory',
74
76
  }).join('\n'));
75
77
  }
78
+ export function splitUserRules(view) {
79
+ const isRule = (r) => isUserRule(r.entry, {
80
+ tenantId: view.tenantId,
81
+ project: view.project,
82
+ isGlobal: r.isGlobal ?? false,
83
+ });
84
+ return {
85
+ userRules: view.result.entries.filter(isRule).map((r) => r.entry),
86
+ others: view.result.entries.filter((r) => !isRule(r)),
87
+ };
88
+ }
76
89
  function renderBlocks(view) {
77
- const { result, framing } = view;
78
- const staticEntries = result.entries.filter((r) => r.category !== 'cross-project' && !r.promptRecall);
79
- const staticCrossEntries = result.entries.filter((r) => r.category === 'cross-project' && !r.promptRecall);
90
+ const { framing } = view;
91
+ const { userRules, others } = splitUserRules(view);
92
+ const staticEntries = others.filter((r) => r.category !== 'cross-project' && !r.promptRecall);
93
+ const staticCrossEntries = others.filter((r) => r.category === 'cross-project' && !r.promptRecall);
80
94
  const staticItems = toRenderItems(staticEntries);
81
- const recallItems = toRenderItems(result.entries.filter((r) => r.promptRecall));
95
+ const recallItems = toRenderItems(others.filter((r) => r.promptRecall));
82
96
  return {
97
+ userRules,
83
98
  staticItems,
84
99
  recallItems,
85
- staticBlock: renderStaticBlock(view, staticItems, staticCrossEntries),
100
+ staticBlock: renderStaticBlock(view, userRules, staticItems, staticCrossEntries),
86
101
  recallBlock: renderRecallBlock(recallItems, framing, view.now),
87
102
  };
88
103
  }
89
104
  async function renderAdditionalContext(view) {
90
105
  const { rec } = view;
91
- const { staticItems, recallItems, staticBlock, recallBlock } = renderBlocks(view);
106
+ const { userRules, staticItems, recallItems, staticBlock, recallBlock } = renderBlocks(view);
92
107
  if (!staticBlock.trim() && !recallBlock.trim()) {
93
108
  rec?.delivered({ state: 'empty' });
94
109
  return NOTHING_RENDERED;
95
110
  }
96
111
  const surface = view.pinnedOnly ? 'hook' : 'context';
97
- const staticCount = staticItems.length;
112
+ const staticCount = userRules.length + staticItems.length;
98
113
  const sendStatic = staticBlock.trim().length > 0 &&
99
114
  !(await skipUnchangedStatic({ view, surface, staticBlock, recallBlock, staticCount }));
100
115
  const finalStatic = sendStatic ? staticBlock : '';
@@ -231,6 +246,7 @@ export async function buildPromptHookContext(ctx, req, opts = {}) {
231
246
  ? await renderAdditionalContext({
232
247
  config: ctx.config,
233
248
  tenantId: ctx.tenantId,
249
+ project: req.project,
234
250
  ledgerSessionId,
235
251
  payloadSessionId: ledgerSessionId,
236
252
  pinnedOnly: true,
@@ -67,7 +67,7 @@ export interface SessionEndWork<Turn, Scan extends {
67
67
  currentProject: () => ProjectRef;
68
68
  /** Captures `turns`, or the whole transcript when undefined, into `into`; false when it
69
69
  * failed, having said why. */
70
- capture: (into: Context, turns: readonly Turn[] | undefined, originProject: ProjectRef | undefined) => Promise<boolean>;
70
+ capture: (into: Context, turns: readonly Turn[] | undefined, originProject: ProjectRef | undefined, fromStart: boolean) => Promise<boolean>;
71
71
  digest: (scan: Scan | null, key: string, log: LineLog) => Promise<void>;
72
72
  workingState: (log: LineLog) => ReturnType<SessionClose['workingState']>;
73
73
  evidence: () => HandoffEvidence;
@@ -197,7 +197,7 @@ async function sleepStep(ctx, w) {
197
197
  /** Captures the session into `into`; a reply's close takes only the turns after the session's
198
198
  * cursor, then moves it, so each reply is extracted once. */
199
199
  async function captureStep(ctx, into, scan, w) {
200
- const capture = async (turns) => {
200
+ const capture = async (turns, fromStart = true) => {
201
201
  // With no transcript of its own, capture would read this as a manual run and scan every
202
202
  // project.
203
203
  if (!w.transcriptPath) {
@@ -205,7 +205,7 @@ async function captureStep(ctx, into, scan, w) {
205
205
  return false;
206
206
  }
207
207
  // In the global store, rows would otherwise read as user-global and show up in every project.
208
- return w.capture(into, turns, hasOwnStore(ctx) ? undefined : w.currentProject());
208
+ return w.capture(into, turns, hasOwnStore(ctx) ? undefined : w.currentProject(), fromStart);
209
209
  };
210
210
  if (w.mode !== 'turn') {
211
211
  await capture(scan?.turns);
@@ -220,7 +220,9 @@ async function captureStep(ctx, into, scan, w) {
220
220
  w.log('skip capture: no new turns since the last reply');
221
221
  return;
222
222
  }
223
- if (await capture(fresh))
223
+ // A slice that starts after the first turn holds only replies to the agent.
224
+ const fromStart = fresh.length === scan.turns.length;
225
+ if (await capture(fresh, fromStart))
224
226
  w.cursor.save(w.sessionId, w.transcriptPath, scan.turns);
225
227
  }
226
228
  /** Books re-reads, sleeps, captures, digests and closes one ended session of the folder `ctx`
@@ -78,6 +78,11 @@ export declare const ERROR_TAG = "error";
78
78
  export declare const EXTRACTED_TAG = "extracted";
79
79
  export declare const COMPACTION_MEMORY_TAG = "compaction-memory";
80
80
  export declare const COMPACTION_SOURCE_PREFIX = "compaction:";
81
+ /** Tag on a rule the person stated, which only capture may set. */
82
+ export declare const USER_RULE_TAG = "from-user";
83
+ /** `tags` without the user-rule tag, for every tag a person types: a typed tag must not make a row
84
+ * print as the person's own rule. */
85
+ export declare function withoutUserTag(tags: readonly string[]): string[];
81
86
  /** A memory counts as high schema fit strictly above this. */
82
87
  export declare const HIGH_SCHEMA_FIT = 0.7;
83
88
  /** The base half-life scaled by the PLAN.md signals: an error tag, and high or low schema fit. */
@@ -26,6 +26,13 @@ export const ERROR_TAG = 'error';
26
26
  export const EXTRACTED_TAG = 'extracted';
27
27
  export const COMPACTION_MEMORY_TAG = 'compaction-memory';
28
28
  export const COMPACTION_SOURCE_PREFIX = 'compaction:';
29
+ /** Tag on a rule the person stated, which only capture may set. */
30
+ export const USER_RULE_TAG = 'from-user';
31
+ /** `tags` without the user-rule tag, for every tag a person types: a typed tag must not make a row
32
+ * print as the person's own rule. */
33
+ export function withoutUserTag(tags) {
34
+ return tags.filter((t) => t !== USER_RULE_TAG);
35
+ }
29
36
  /** A memory counts as high schema fit strictly above this. */
30
37
  export const HIGH_SCHEMA_FIT = 0.7;
31
38
  const HIGH_FIT_HALF_LIFE_FACTOR = 1.5;
@@ -125,7 +132,7 @@ function assertValidMemoryInput(content, options) {
125
132
  export function createSuccessor(old, content, opts, now) {
126
133
  const fields = {
127
134
  layer: opts.layer ?? old.layer,
128
- tags: opts.tags ?? [...old.tags],
135
+ tags: withoutUserTag(opts.tags ?? old.tags),
129
136
  pinned: opts.pinned ?? old.pinned,
130
137
  source: old.source,
131
138
  confidence: 'verified',
@@ -38,6 +38,9 @@ export interface CaptureDedup {
38
38
  readonly tenantId: TenantId;
39
39
  readonly project?: readonly string[];
40
40
  readonly everyScope?: boolean;
41
+ /** The names of the project a stated rule is written for: a held copy of one of them gives way
42
+ * to the rule. None replaces nothing. */
43
+ readonly ruleProject?: readonly string[];
41
44
  }
42
45
  /** Each method opens hippo.db with the hook's wait, so a busy store costs the hook a bounded
43
46
  * delay. */
@@ -36,10 +36,10 @@ export interface LedgerTurn {
36
36
  /** Written after the rows, whatever became of them. */
37
37
  readonly delivery?: DeliveryEventInput;
38
38
  }
39
- /** Where a block was sent: `hook`/`hook_recall` (per-prompt hook), `compact_resume`,
39
+ /** Where a block was sent: `hook`/`hook_recall` (per-prompt hook), `compact_resume`, `session_start`,
40
40
  * `context`/`recall` (CLI), `mcp_*`, `http_*`, and `pilot` (session pilot arm row,
41
41
  * src/api/pilot-arm.ts; not a send, so in no surface list). */
42
- export type TokenSurface = 'hook' | 'hook_recall' | 'compact_resume' | 'context' | 'recall' | 'mcp_recall' | 'mcp_context' | 'http_recall' | 'http_context' | 'http_assemble' | 'pilot';
42
+ export type TokenSurface = 'hook' | 'hook_recall' | 'compact_resume' | 'session_start' | 'context' | 'recall' | 'mcp_recall' | 'mcp_context' | 'http_recall' | 'http_context' | 'http_assemble' | 'pilot';
43
43
  /** What happened to a block: `inject` (sent), `skip` (identical to the last injected block),
44
44
  * `reset` (host compacted, next must send), `reread` (tokens later calls read again, booked at
45
45
  * session end), `arm` (pilot assignment; `block_hash` is `hippo` or `holdout`, `items` the
@@ -113,7 +113,9 @@ export interface AuditEvent {
113
113
  metadata: JsonObject;
114
114
  }
115
115
  /** A stored text the capture dedup reads; `pinned` is optional so an adapter that omits it still fits. */
116
- export type HeldText = Pick<MemoryEntry, 'content' | 'source' | 'originProject'> & Partial<Pick<MemoryEntry, 'pinned'>>;
116
+ export type HeldText = Pick<MemoryEntry, 'content' | 'source' | 'originProject'> & Partial<Pick<MemoryEntry, 'pinned' | 'id' | 'supersededBy'>> & {
117
+ confidence?: string;
118
+ };
117
119
  /** One project name, or every name a project's rows carry. */
118
120
  export type OriginFilter = string | readonly string[];
119
121
  /** The api_keys fields a tenant, revocation, rank or self-service ownership check reads. */
@@ -15,6 +15,13 @@ export declare function mergedText(header: string, texts: readonly string[]): st
15
15
  * whole after its header.
16
16
  */
17
17
  export declare function heldTexts(entry: Text): string[];
18
+ /** Whether a stated rule replaces this held copy rather than giving way to it: a live, unpinned,
19
+ * observed capture row of one of `ruleProject`, the names of the rule's project. A superseded,
20
+ * pinned, typed, verified, no-project or other-project copy stops the rule, so a replayed
21
+ * transcript revives nothing and no project loses its row. */
22
+ export declare function ruleReplaces(row: Text & Partial<Pick<MemoryEntry, 'originProject' | 'supersededBy'>> & {
23
+ confidence?: string;
24
+ }, ruleProject: readonly string[]): boolean;
18
25
  /** Keys of every text a row holds word for word: its own, plus each source text inside a
19
26
  * sleep-merged row. */
20
27
  export declare function heldTextKeys(entry: Text): string[];
@@ -38,6 +38,18 @@ export function heldTexts(entry) {
38
38
  .slice(1)
39
39
  .map((t) => t.replace(/\n {2}/g, '\n'));
40
40
  }
41
+ /** Whether a stated rule replaces this held copy rather than giving way to it: a live, unpinned,
42
+ * observed capture row of one of `ruleProject`, the names of the rule's project. A superseded,
43
+ * pinned, typed, verified, no-project or other-project copy stops the rule, so a replayed
44
+ * transcript revives nothing and no project loses its row. */
45
+ export function ruleReplaces(row, ruleProject) {
46
+ return (row.pinned !== true &&
47
+ row.source === 'capture' &&
48
+ Boolean(row.originProject) &&
49
+ ruleProject.includes(row.originProject ?? '') &&
50
+ row.supersededBy == null &&
51
+ row.confidence === 'observed');
52
+ }
41
53
  /** Keys of every text a row holds word for word: its own, plus each source text inside a
42
54
  * sleep-merged row. */
43
55
  export function heldTextKeys(entry) {
@@ -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.1.1";
5
+ export declare const PACKAGE_VERSION = "3.2.1";
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.1.1';
5
+ export const PACKAGE_VERSION = '3.2.1';
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';