hippo-memory 3.3.2 → 3.4.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.
Files changed (115) hide show
  1. package/dist/api/context/context-pools.js +2 -1
  2. package/dist/api/context/user-rule.js +2 -1
  3. package/dist/api/dashboard/detail.js +2 -1
  4. package/dist/api/dashboard/live.d.ts +0 -4
  5. package/dist/api/dashboard/live.js +0 -8
  6. package/dist/api/memories/conflicts.d.ts +2 -1
  7. package/dist/api/memories/conflicts.js +3 -8
  8. package/dist/api/memories/promote.js +6 -2
  9. package/dist/api/recall/compose.js +2 -1
  10. package/dist/api/recall/rank-stages.js +2 -1
  11. package/dist/api/recall/rows.js +2 -1
  12. package/dist/api/sleep/sleep-run.js +2 -1
  13. package/dist/api/summary-parents.js +2 -1
  14. package/dist/base/memory/ambient.js +2 -1
  15. package/dist/base/memory/entry.d.ts +4 -1
  16. package/dist/base/memory/entry.js +7 -1
  17. package/dist/base/memory/half-life-plan.js +6 -4
  18. package/dist/base/memory/keep-rules.js +2 -1
  19. package/dist/base/memory/liveness.d.ts +7 -0
  20. package/dist/base/memory/liveness.js +6 -0
  21. package/dist/base/memory/markdown.js +15 -5
  22. package/dist/base/memory/memory-audit.js +2 -1
  23. package/dist/base/memory/memory-facts.d.ts +0 -2
  24. package/dist/base/memory/memory-facts.js +0 -2
  25. package/dist/base/memory/merged-row.js +3 -2
  26. package/dist/base/memory/rule-replaces.js +2 -1
  27. package/dist/base/memory/stale-mark.d.ts +9 -0
  28. package/dist/base/memory/stale-mark.js +18 -0
  29. package/dist/base/ports/store/conflicts.d.ts +5 -1
  30. package/dist/base/ports/store/conflicts.js +2 -0
  31. package/dist/base/ports/store/consolidation.d.ts +51 -2
  32. package/dist/base/ports/store/consolidation.js +3 -0
  33. package/dist/base/ports/store/sessions.d.ts +8 -2
  34. package/dist/base/ports/store/sessions.js +6 -0
  35. package/dist/base/ports/store/store-effects.d.ts +3 -0
  36. package/dist/base/scope/live-memory.d.ts +7 -0
  37. package/dist/base/scope/live-memory.js +10 -0
  38. package/dist/base/scope/read-admission.js +2 -1
  39. package/dist/base/util/version.d.ts +1 -1
  40. package/dist/base/util/version.js +1 -1
  41. package/dist/db/continuity-tables.d.ts +6 -1
  42. package/dist/db/continuity-tables.js +27 -15
  43. package/dist/db/migrate.js +8 -4
  44. package/dist/db/migrations/index.d.ts +1 -1
  45. package/dist/db/migrations/index.js +3 -1
  46. package/dist/db/migrations/v61.js +3 -3
  47. package/dist/db/migrations/v62.d.ts +3 -0
  48. package/dist/db/migrations/v62.js +43 -0
  49. package/dist/db/required-objects.js +2 -1
  50. package/dist/db/sql-predicates.d.ts +22 -2
  51. package/dist/db/sql-predicates.js +27 -2
  52. package/dist/domain/agent-memories/apply.js +2 -1
  53. package/dist/domain/agent-memories/container-view.js +2 -1
  54. package/dist/domain/consolidate/conflicts.js +2 -1
  55. package/dist/domain/consolidate/dag-summary.d.ts +2 -0
  56. package/dist/domain/consolidate/dag.d.ts +3 -0
  57. package/dist/domain/consolidate/dag.js +53 -8
  58. package/dist/domain/consolidate/dedupe.js +2 -1
  59. package/dist/domain/consolidate/events.d.ts +2 -0
  60. package/dist/domain/consolidate/llm-passes.js +94 -20
  61. package/dist/domain/consolidate/merge.js +5 -4
  62. package/dist/domain/consolidate/retry-holds.d.ts +14 -0
  63. package/dist/domain/consolidate/retry-holds.js +26 -0
  64. package/dist/domain/consolidate/run.d.ts +8 -0
  65. package/dist/domain/consolidate/run.js +2 -0
  66. package/dist/domain/graph/recall.js +3 -2
  67. package/dist/domain/learn/churn-stale.js +2 -1
  68. package/dist/domain/learn/extract.d.ts +10 -0
  69. package/dist/domain/learn/extract.js +10 -5
  70. package/dist/domain/learn/invalidation.d.ts +1 -1
  71. package/dist/domain/learn/invalidation.js +4 -11
  72. package/dist/domain/objects/decisions.d.ts +2 -2
  73. package/dist/domain/objects/decisions.js +4 -9
  74. package/dist/domain/search/as-of.js +3 -2
  75. package/dist/store/sqlite/capture/compaction-rows.js +9 -2
  76. package/dist/store/sqlite/connectors/quarantine.js +13 -4
  77. package/dist/store/sqlite/consolidation/consolidation-summaries.d.ts +4 -5
  78. package/dist/store/sqlite/consolidation/consolidation-summaries.js +46 -26
  79. package/dist/store/sqlite/consolidation/consolidation.js +5 -0
  80. package/dist/store/sqlite/consolidation/empty-extractions.d.ts +14 -0
  81. package/dist/store/sqlite/consolidation/empty-extractions.js +57 -0
  82. package/dist/store/sqlite/consolidation/rebuild-holds.d.ts +21 -0
  83. package/dist/store/sqlite/consolidation/rebuild-holds.js +68 -0
  84. package/dist/store/sqlite/entries/entry-filter.js +2 -1
  85. package/dist/store/sqlite/entries/entry-reads.js +2 -1
  86. package/dist/store/sqlite/entries/entry-writes.js +6 -5
  87. package/dist/store/sqlite/maintenance/agent-import-steps.js +7 -2
  88. package/dist/store/sqlite/maintenance/project-tags.js +4 -3
  89. package/dist/store/sqlite/recall/candidates.js +10 -4
  90. package/dist/store/sqlite/recall/search-rows.js +4 -3
  91. package/dist/store/sqlite/reports/dashboard-lists.js +3 -2
  92. package/dist/store/sqlite/reports/dashboard-reads.js +5 -3
  93. package/dist/store/sqlite/reports/dashboard-sql.d.ts +0 -3
  94. package/dist/store/sqlite/reports/dashboard-sql.js +2 -9
  95. package/dist/store/sqlite/reports/reports.js +2 -1
  96. package/dist/store/sqlite/review/conflicts.js +7 -1
  97. package/dist/store/sqlite/runtime/rule-sql.js +2 -1
  98. package/dist/store/sqlite/runtime/status-transitions.d.ts +98 -0
  99. package/dist/store/sqlite/runtime/status-transitions.js +105 -0
  100. package/dist/store/sqlite/sessions/goals.js +11 -12
  101. package/dist/store/sqlite/sessions/sessions.d.ts +1 -1
  102. package/dist/store/sqlite/sessions/sessions.js +20 -8
  103. package/dist/surface/cli/conflicts.js +12 -1
  104. package/dist/surface/cli/continuity.js +4 -0
  105. package/dist/surface/cli/print.js +2 -1
  106. package/dist/surface/cli/verbs/objects.js +2 -2
  107. package/dist/surface/dashboard/dashboard-actions.js +1 -1
  108. package/dist/surface/render/sleep-events.js +2 -0
  109. package/dist-ui/assets/index-Cst0ubfs.js +1 -0
  110. package/dist-ui/index.html +1 -1
  111. package/extensions/openclaw-plugin/openclaw.plugin.json +1 -1
  112. package/extensions/openclaw-plugin/package.json +1 -1
  113. package/openclaw.plugin.json +1 -1
  114. package/package.json +1 -1
  115. package/dist-ui/assets/index-Q9SY-1Bj.js +0 -1
@@ -4,6 +4,7 @@ import { DEFAULT_SEARCH_CANDIDATE_LIMIT } from '../../base/rank/search-types.js'
4
4
  import { projectNames } from '../../base/scope/project-identity.js';
5
5
  import { ambientAdmits, ambientEnvelopeAdmits, } from '../../base/scope/read-admission.js';
6
6
  import { NO_QUERY, globalSource } from './context-plan.js';
7
+ import { isSuperseded } from '../../base/memory/liveness.js';
7
8
  /** Most rows per store a no-query context reads; past it, ranking sees the strongest by decay. */
8
9
  const CONTEXT_CANDIDATE_CAP = 2000;
9
10
  /** The page is sized from the rows the budget can pay for: a memory under this many tokens is
@@ -71,7 +72,7 @@ export function ambientAdmission(opts, plan, digestHandoff) {
71
72
  const admit = (e) => ambientAdmits(e, rule);
72
73
  // The two-store search has always ranked a session's own compaction items; only the local search
73
74
  // drops them.
74
- const bothStoresAdmit = (e) => !e.supersededBy && ambientEnvelopeAdmits(e, rule);
75
+ const bothStoresAdmit = (e) => !isSuperseded(e) && ambientEnvelopeAdmits(e, rule);
75
76
  return { rule, admit, bothStoresAdmit };
76
77
  }
77
78
  /**
@@ -2,13 +2,14 @@
2
2
  // cannot pass for one.
3
3
  import { USER_RULE_TAG } from '../../base/memory/entry.js';
4
4
  import { projectId, projectNames } from '../../base/scope/project-identity.js';
5
+ import { isSuperseded } from '../../base/memory/liveness.js';
5
6
  export { USER_RULE_TAG };
6
7
  export function isUserRule(e, viewer) {
7
8
  const own = e.pinned &&
8
9
  e.source === 'capture' &&
9
10
  e.confidence === 'observed' &&
10
11
  e.tags.includes(USER_RULE_TAG) &&
11
- e.supersededBy === null &&
12
+ !isSuperseded(e) &&
12
13
  e.scope === null &&
13
14
  e.tenantId === viewer.tenantId;
14
15
  if (!own)
@@ -1,11 +1,12 @@
1
1
  // The dashboard drawer's detail of one memory, read fresh through the api and stamped with the id
2
2
  // the client holds.
3
3
  import { calculateStrength } from '../../base/memory/strength.js';
4
+ import { isLiveMemory } from '../../base/scope/live-memory.js';
4
5
  import { memoryFacts } from '../../base/memory/memory-facts.js';
5
6
  import { round1 } from '../../base/util/format.js';
6
7
  import { memoryGet } from '../memories/memories.js';
7
8
  import { strengthOf } from '../types.js';
8
- import { BANDS, isLiveMemory, LAYERS, projectIdentity, round3 } from './live.js';
9
+ import { BANDS, LAYERS, projectIdentity, round3 } from './live.js';
9
10
  async function openConflictsOf(store, { reads, tenantId, entry, at }) {
10
11
  const conflicts = (await reads.openConflictsOf(tenantId, entry.id)).map((row) => row.conflict);
11
12
  const otherId = (c) => c.memoryAId === entry.id ? c.memoryBId : c.memoryAId;
@@ -1,12 +1,8 @@
1
- import type { MemoryEntry } from '../../base/memory/entry.js';
2
1
  import type { DashboardChip, Origin } from '../../base/ports/store/dashboard-reads.js';
3
2
  import type { Band, Layer, ProjectKind } from './types.js';
4
3
  export declare const LAYERS: readonly Layer[];
5
4
  export declare const BANDS: readonly Band[];
6
5
  export type Chip = DashboardChip;
7
- /** The one predicate for "shown on the dashboard": not superseded, not archived, not
8
- * quarantined. */
9
- export declare function isLiveMemory(entry: Pick<MemoryEntry, 'supersededBy' | 'kind' | 'scope'>): boolean;
10
6
  /** Wire key, display name and kind of a project. */
11
7
  export interface ProjectIdentity {
12
8
  key: string;
@@ -1,14 +1,6 @@
1
- import { isQuarantineScope } from '../../domain/trust/quarantine.js';
2
1
  export const LAYERS = ['buffer', 'episodic', 'semantic', 'trace'];
3
2
  // Wire order of `Band`, and the order the mockup sorts bands in.
4
3
  export const BANDS = ['pinned', 'strong', 'fading', 'atRisk'];
5
- /** The one predicate for "shown on the dashboard": not superseded, not archived, not
6
- * quarantined. */
7
- export function isLiveMemory(entry) {
8
- return (!entry.supersededBy &&
9
- (entry.kind === 'raw' || entry.kind === 'distilled') &&
10
- !isQuarantineScope(entry.scope));
11
- }
12
4
  /** Wire key, display name and kind for an `origin_project` value. */
13
5
  export function projectIdentity(origin) {
14
6
  if (origin === '')
@@ -1,4 +1,5 @@
1
1
  import type { MemoryConflict } from '../../base/ports/store/conflicts.js';
2
+ import type { ConflictStatus } from '../../base/ports/store/conflicts.js';
2
3
  import type { CallerProject } from '../prompt-hook.js';
3
4
  import type { KeysetPosition } from '../../base/util/keyset.js';
4
5
  import { type ContextWith } from '../types.js';
@@ -44,7 +45,7 @@ export declare function conflictListOpen(ctx: ContextWith<'conflicts'>, opts?: C
44
45
  }): Promise<ConflictPage>;
45
46
  /** One page of conflicts with `status` ('*' for any) in reach, with no scope filter: the host's
46
47
  * own view, so the host admin only. */
47
- export declare function conflictList(ctx: ContextWith<'conflicts'>, status: string, reach?: TenantReach, opts?: ConflictPageOptions): Promise<ConflictPage>;
48
+ export declare function conflictList(ctx: ContextWith<'conflicts'>, status: ConflictStatus | '*', reach?: TenantReach, opts?: ConflictPageOptions): Promise<ConflictPage>;
48
49
  /** Each page a paged list answers from `start`, the largest page at a time, for the verbs that
49
50
  * print every conflict. */
50
51
  export declare function conflictPages(read: (page: ConflictPageOptions) => Promise<ConflictPage>, start?: KeysetPosition): AsyncGenerator<ConflictPage>;
@@ -4,17 +4,11 @@ import { BadRequestError, ConflictError, NotFoundError } from '../../base/errors
4
4
  import { assertWriteRight, canReadScope, passesScopeFilterForRecall, personalScopeOf, scopeReaderOf, } from '../../base/scope/recall-scope.js';
5
5
  import { conflictLoserFate } from '../../domain/consolidate/conflicts.js';
6
6
  import { classifyOriginProject } from '../../base/scope/project-identity.js';
7
- import { isQuarantineScope } from '../../domain/trust/quarantine.js';
7
+ import { isLiveMemory } from '../../base/scope/live-memory.js';
8
8
  import { MAX_LIST_LIMIT } from '../../base/util/limits.js';
9
9
  import { keysetPages, pageLimit } from '../pages.js';
10
10
  import { ALL_TENANTS } from '../../base/util/tenant.js';
11
11
  import { requireHostAdmin } from '../types.js';
12
- function isLive(member) {
13
- return (member !== null &&
14
- !member.supersededBy &&
15
- (member.kind === 'raw' || member.kind === 'distilled') &&
16
- !isQuarantineScope(member.scope));
17
- }
18
12
  /** A row the caller could not read hides its whole pair. */
19
13
  function touchable(actor, row) {
20
14
  return [row.a, row.b].every((member) => member !== null && canReadScope(actor, member.scope));
@@ -41,7 +35,8 @@ export async function conflictResolve(ctx, conflictId, opts) {
41
35
  throw new ConflictError(`conflict ${conflictId} is already resolved`);
42
36
  }
43
37
  const { keep, loser } = sidesOf(row, opts.keepId);
44
- if (!isLive(row.a) || !isLive(row.b)) {
38
+ const { a, b } = row;
39
+ if (!(a !== null && isLiveMemory(a) && b !== null && isLiveMemory(b))) {
45
40
  throw new NotFoundError(`conflict ${conflictId} names a memory that is superseded, archived or quarantined`);
46
41
  }
47
42
  const reason = opts.reason ?? `resolveConflict ${conflictId}: kept ${keep.id}`;
@@ -7,6 +7,7 @@ import { globalTargetOf } from '../infra.js';
7
7
  import { withDetached } from '../detached.js';
8
8
  import { sharedStoreOf } from '../types.js';
9
9
  import { assertWriteRight, canReadScope, isPersonalScope, isQuarantineScope, scopeReaderOf, } from '../../base/scope/recall-scope.js';
10
+ import { isSuperseded } from '../../base/memory/liveness.js';
10
11
  export async function promote(ctx, id) {
11
12
  // Another tenant's row and a row out of the caller's reach read alike, so the reply says nothing
12
13
  // of either.
@@ -88,8 +89,11 @@ function assertSupersedable(ctx, oldId, old) {
88
89
  assertWriteRight(scopeReaderOf(ctx.actor), row, oldId, `Memory not found: ${oldId}`);
89
90
  // The CAS UPDATE closes the race; this check only gives a clearer error in the common
90
91
  // single-writer case.
91
- if (row.supersededBy) {
92
- throw new ConflictError(`Memory ${oldId} is already superseded by ${row.supersededBy}. Supersede that one instead.`);
92
+ if (isSuperseded(row)) {
93
+ const by = row.supersededBy;
94
+ throw new ConflictError(by === ''
95
+ ? `Memory ${oldId} is already superseded.`
96
+ : `Memory ${oldId} is already superseded by ${by}. Supersede that one instead.`);
93
97
  }
94
98
  return row;
95
99
  }
@@ -10,6 +10,7 @@ import { passesScopeFilterForRecall } from '../../base/scope/recall-scope.js';
10
10
  import { anchoringRows, availabilityRows, callerOf, recallAuditMetadata, recallAuditRow, } from './finish.js';
11
11
  import { biasHintEnabled, detectAnchoring, hashQueryText, } from './anchoring.js';
12
12
  import { rankBands, overflowGroups } from './bands.js';
13
+ import { isSuperseded } from '../../base/memory/liveness.js';
13
14
  const DEFAULT_RECALL_LIMIT = 10;
14
15
  export function recallOrigin(opts) {
15
16
  const project = opts.filter?.project;
@@ -97,7 +98,7 @@ function recallResult(options, bands, continuity, suppressedByInterference) {
97
98
  // The SQL load already applied tenant and scope; a recall candidate loader must go through
98
99
  // store.searchRecallEntries.
99
100
  function admitCandidates(opts, all, limit, personalScope) {
100
- const current = all.filter((e) => !e.supersededBy);
101
+ const current = all.filter((e) => !isSuperseded(e));
101
102
  const scope = opts.filter?.scope;
102
103
  let entries;
103
104
  if (scope !== undefined && scope !== '') {
@@ -9,6 +9,7 @@ import { CONFLICT_PEER_MULTIPLIER, SALIENCE_MIN_MULTIPLIER, UTILITY_LENGTH_PENAL
9
9
  import { isJsonNumber } from '../../base/util/json.js';
10
10
  import { indexTokenize, textOverlap, tokenize as tokenizeQuery } from '../../base/util/tokenize.js';
11
11
  import { poolScope } from './rank-search.js';
12
+ import { isSuperseded } from '../../base/memory/liveness.js';
12
13
  /** The stages after the search, in order: graph expansion, re-rank, goal boost, salience, then
13
14
  * the outcome and layer filters. */
14
15
  export async function rankStages(ctx, opts, state, profile) {
@@ -114,7 +115,7 @@ function reorderResults(opts, state) {
114
115
  state.results = newestOnTopicFirst(opts.query, state.results);
115
116
  }
116
117
  if (opts.filterConflicts) {
117
- dropUnless(state, (r) => !r.entry.supersededBy);
118
+ dropUnless(state, (r) => !isSuperseded(r.entry));
118
119
  demoteConflictPeers(opts, state);
119
120
  }
120
121
  if (opts.valueAware && state.results.length >= 1)
@@ -10,6 +10,7 @@ import { fitBudget } from '../../domain/search/finalize.js';
10
10
  import { estimateTokens } from '../../base/util/token-text.js';
11
11
  import { passesCliRecallScopeFilter, passesScopeFilterForRecall, } from '../../base/scope/recall-scope.js';
12
12
  import { CONTINUITY_EVENT_LIMIT } from '../continuity/continuity.js';
13
+ import { isSuperseded } from '../../base/memory/liveness.js';
13
14
  export { DEFAULT_MAX_NEIGHBORS, MAX_HOPS } from '../../domain/graph/recall.js';
14
15
  /** Which stores a recall reads under `ctx`, with `activeScope` (an explicit scope merged with
15
16
  * the detected one), which only boosts. */
@@ -97,7 +98,7 @@ export function recallJsonRow({ r, query, showWhy, isGlobal, now, }) {
97
98
  if (r.entry.layer === Layer.Trace) {
98
99
  base.trace_outcome = r.entry.traceOutcome;
99
100
  }
100
- if (r.entry.supersededBy) {
101
+ if (isSuperseded(r.entry)) {
101
102
  base.superseded = true;
102
103
  base.superseded_by = r.entry.supersededBy;
103
104
  }
@@ -15,6 +15,7 @@ import { errorFields, errorMessage, log } from '../../base/util/log.js';
15
15
  import { ALL_TENANTS } from '../../base/util/tenant.js';
16
16
  import { failedUnitOf } from '../../base/errors/failed-unit.js';
17
17
  import { reportAuditWriteFailure } from '../../base/records/audit-report.js';
18
+ import { isSuperseded } from '../../base/memory/liveness.js';
18
19
  const DEFAULT_SLEEP_PHASES = {
19
20
  consolidate: runConsolidation,
20
21
  deduplicateStore,
@@ -220,7 +221,7 @@ async function summarizeAmbient(ctx, phases, result, pages) {
220
221
  const rules = strengthOf(ctx);
221
222
  const tallies = tallyAmbientEntries([], now, rules);
222
223
  for await (const page of pages()) {
223
- foldAmbientRows(tallies, page.filter((e) => !e.supersededBy), now, rules);
224
+ foldAmbientRows(tallies, page.filter((e) => !isSuperseded(e)), now, rules);
224
225
  }
225
226
  if (tallies.total === 0)
226
227
  return 0;
@@ -1,11 +1,12 @@
1
1
  import { DAG_LEVEL } from '../base/memory/entry.js';
2
2
  import { passesScopeFilterForRecall } from '../base/scope/recall-scope.js';
3
3
  import { classifyOriginProject } from '../base/scope/project-identity.js';
4
+ import { isSuperseded } from '../base/memory/liveness.js';
4
5
  /** The level-2 summaries that may stand in for their children: live, in the caller's scope and
5
6
  * in its project. */
6
7
  export function eligibleSummaryParents(parents, scope, own, project) {
7
8
  return parents.filter((p) => (p.dagLevel ?? 0) === DAG_LEVEL.topic &&
8
- !p.supersededBy &&
9
+ !isSuperseded(p) &&
9
10
  passesScopeFilterForRecall(p.scope ?? null, scope, own) &&
10
11
  (!project || classifyOriginProject(p.originProject, project) !== 'cross-project'));
11
12
  }
@@ -6,6 +6,7 @@ import { Layer } from './entry.js';
6
6
  import { calculateStrength } from './strength.js';
7
7
  import { ERROR_TAG, HIGH_SCHEMA_FIT } from './entry.js';
8
8
  import { DAY_MS } from '../util/time.js';
9
+ import { isSuperseded } from './liveness.js';
9
10
  const STATE_DECIMALS = 3;
10
11
  // Cut points renderAmbientSummary uses to turn the state vector into words.
11
12
  const SUMMARY_THRESHOLD = {
@@ -78,7 +79,7 @@ export function foldAmbientRows(t, entries, currentTime, model) {
78
79
  const freshAfter = currentTime.getTime() - AMBIENT_FRESH_WINDOW_MS;
79
80
  t.total += entries.length;
80
81
  for (const entry of entries) {
81
- if (entry.supersededBy)
82
+ if (isSuperseded(entry))
82
83
  continue;
83
84
  for (const tag of entry.tags)
84
85
  t.tagCounts.set(tag, (t.tagCounts.get(tag) ?? 0) + 1);
@@ -7,7 +7,10 @@ export declare enum Layer {
7
7
  Trace = "trace"
8
8
  }
9
9
  export type EmotionalValence = 'neutral' | 'positive' | 'negative' | 'critical';
10
- export type ConfidenceLevel = 'verified' | 'observed' | 'inferred' | 'stale';
10
+ export declare const CONFIDENCE_LEVELS: readonly ["verified", "observed", "inferred", "stale"];
11
+ export type ConfidenceLevel = (typeof CONFIDENCE_LEVELS)[number];
12
+ /** True when `value` is one of the four stored confidence tiers. */
13
+ export declare function isConfidenceLevel(value: string): value is ConfidenceLevel;
11
14
  export type TraceOutcome = 'success' | 'failure' | 'partial' | null;
12
15
  export declare const MEMORY_KINDS: readonly ["raw", "distilled", "superseded", "archived"];
13
16
  export type MemoryKind = (typeof MEMORY_KINDS)[number];
@@ -7,6 +7,7 @@ import { isJsonString } from '../util/json.js';
7
7
  import { tokenizeMin } from '../util/tokenize.js';
8
8
  import { ID_SUFFIX_CHARS } from '../util/token-text.js';
9
9
  import { calculateStrength, netWrong, PRODUCTION_STRENGTH, } from './strength.js';
10
+ import { isSuperseded } from './liveness.js';
10
11
  export const DEFAULT_SCHEMA_FIT = 0.5;
11
12
  export var Layer;
12
13
  (function (Layer) {
@@ -15,6 +16,11 @@ export var Layer;
15
16
  Layer["Semantic"] = "semantic";
16
17
  Layer["Trace"] = "trace";
17
18
  })(Layer || (Layer = {}));
19
+ export const CONFIDENCE_LEVELS = ['verified', 'observed', 'inferred', 'stale'];
20
+ /** True when `value` is one of the four stored confidence tiers. */
21
+ export function isConfidenceLevel(value) {
22
+ return CONFIDENCE_LEVELS.some((level) => level === value);
23
+ }
18
24
  export const MEMORY_KINDS = ['raw', 'distilled', 'superseded', 'archived'];
19
25
  /** Named dag_level values; level 0 is a raw leaf. */
20
26
  export const DAG_LEVEL = { extracted: 1, topic: 2, entity: 3 };
@@ -238,7 +244,7 @@ export function markRetrieved(entries, now, model) {
238
244
  if (!model.recallStrengthens)
239
245
  return entries;
240
246
  return entries.map((e) => {
241
- if (e.supersededBy)
247
+ if (isSuperseded(e))
242
248
  return e;
243
249
  const wrong = netWrong(e, model) > 0;
244
250
  // Confidence stays untouched: it is an epistemic tier, not a recency signal.
@@ -2,7 +2,9 @@
2
2
  // goes. Pure, so the store runs it inside the move's own write scope and plan, write and audit stay
3
3
  // one transaction.
4
4
  import { deriveHalfLife } from './entry.js';
5
+ import { INVALIDATED_TAG, SUPERSEDED_TAG } from './stale-mark.js';
5
6
  import { LEGACY_TYPED_HALF_LIFE } from './strength.js';
7
+ import { isSuperseded } from './liveness.js';
6
8
  const TYPED_SOURCES = new Set([
7
9
  'decision',
8
10
  'incident',
@@ -15,9 +17,9 @@ const TYPED_SOURCES = new Set([
15
17
  /** Recall bonus over `written`, the half-life `entry` got at write, or null when off it; each
16
18
  * recall added 2 days. */
17
19
  export function halfLifeRecallBonus(entry, written) {
18
- if (entry.supersededBy ||
19
- entry.tags.includes('invalidated') ||
20
- entry.tags.includes('superseded')) {
20
+ if (isSuperseded(entry) ||
21
+ entry.tags.includes(INVALIDATED_TAG) ||
22
+ entry.tags.includes(SUPERSEDED_TAG)) {
21
23
  return null;
22
24
  }
23
25
  const bonus = entry.halfLifeDays - written;
@@ -68,7 +70,7 @@ function planMoves(rows, to) {
68
70
  let count = 0;
69
71
  for (const { entry: e, object } of rows.rows) {
70
72
  count++;
71
- if (e.supersededBy)
73
+ if (isSuperseded(e))
72
74
  copies.add(e.supersededBy);
73
75
  const base = baseTarget(e, rows.from, to);
74
76
  const typed = typedPending ? typedTarget(e, to) : null;
@@ -1,13 +1,14 @@
1
1
  // Which memories sleep may never delete, and how an outcome mark changes an entry.
2
2
  import { AGENT_MEMORY_TOOLS, toolSourcePrefix } from './agent-memory-tools.js';
3
3
  import { CHURN_STALE_TAG } from './entry.js';
4
+ import { isSuperseded } from './liveness.js';
4
5
  import { calculateStrength } from './strength.js';
5
6
  export const KEEP_PAIRS = AGENT_MEMORY_TOOLS.map((t) => ({
6
7
  tag: t.tag,
7
8
  sourcePrefix: toolSourcePrefix(t.id),
8
9
  }));
9
10
  export function isKeptForGood(entry) {
10
- return (!entry.supersededBy &&
11
+ return (!isSuperseded(entry) &&
11
12
  KEEP_PAIRS.some((p) => entry.tags.includes(p.tag) && entry.source.startsWith(p.sourcePrefix)));
12
13
  }
13
14
  export function canAutoDelete(entry) {
@@ -0,0 +1,7 @@
1
+ /** True when the memory has a successor link of any value, a blank one included. */
2
+ export declare function isSuperseded<T extends {
3
+ readonly supersededBy?: string | null;
4
+ }>(entry: T): entry is T & {
5
+ readonly supersededBy: string;
6
+ };
7
+ //# sourceMappingURL=liveness.d.ts.map
@@ -0,0 +1,6 @@
1
+ // A blank link counts as superseded: the CAS guard, recall and three partial indexes read it so.
2
+ /** True when the memory has a successor link of any value, a blank one included. */
3
+ export function isSuperseded(entry) {
4
+ return entry.supersededBy !== null && entry.supersededBy !== undefined;
5
+ }
6
+ //# sourceMappingURL=liveness.js.map
@@ -1,5 +1,5 @@
1
1
  import { DEFAULT_TENANT_ID } from '../util/tenant.js';
2
- import { DEFAULT_SCHEMA_FIT, } from './entry.js';
2
+ import { DEFAULT_SCHEMA_FIT, isConfidenceLevel, } from './entry.js';
3
3
  import { FALLBACK_HALF_LIFE_DAYS } from './strength.js';
4
4
  import { fromWire, toWire } from './memory-wire.js';
5
5
  import { dumpFrontmatter, parseFrontmatter } from '../util/yaml.js';
@@ -79,9 +79,8 @@ export function deserializeEntry(raw, now) {
79
79
  });
80
80
  }
81
81
  function scoringWireOf(data, now) {
82
- // SAFETY: each `as X` narrows a raw YAML field to a MemoryWire union member; frontmatter is only
83
- // written by serializeEntry, so out-of-range values mean hand-edited files, which this parser may
84
- // accept (permissive parse).
82
+ // SAFETY: each `as X` narrows a raw YAML field to a MemoryWire union member, so a hand-edited
83
+ // value outside it parses through. Confidence alone is checked: it becomes a stored tier.
85
84
  return {
86
85
  id: String(data['id']),
87
86
  created: String(data['created'] ?? now.toISOString()),
@@ -101,9 +100,20 @@ function scoringWireOf(data, now) {
101
100
  outcome_negative: Number(data['outcome_negative'] ?? 0),
102
101
  conflicts_with: normalizeStringArray(data['conflicts_with']),
103
102
  pinned: Boolean(data['pinned'] ?? false),
104
- confidence: data['confidence'] ?? 'observed',
103
+ confidence: confidenceOf(data),
105
104
  };
106
105
  }
106
+ function confidenceOf(data) {
107
+ const given = data['confidence'];
108
+ // This parser reads a bare `confidence:` line as '', so it counts as missing like null.
109
+ const value = given === undefined || given === null || given === '' ? 'observed' : given;
110
+ const text = String(value);
111
+ if (isConfidenceLevel(text))
112
+ return text;
113
+ throw new Error(`memory ${String(data['id'])}: unknown confidence ${JSON.stringify(value)}; ` +
114
+ 'use verified, observed, inferred or stale; the file stays on disk, ' +
115
+ 'and deleting hippo.db to rebuild is safe only before any new write');
116
+ }
107
117
  function lineageWireOf(data, now) {
108
118
  // SAFETY: each `as X` narrows a raw YAML field to a MemoryWire union member; frontmatter is only
109
119
  // written by serializeEntry, so out-of-range values mean hand-edited files, which this parser may
@@ -2,6 +2,7 @@
2
2
  import { canAutoDelete, isKeptForGood } from './keep-rules.js';
3
3
  import { automaticDefect, BUNDLE_HEADER, isAutomaticEntry, isCertainReason, isFragment, isReleaseCommitNoise, isShortAndUnspecific, MIN_MEMORY_CHARS, MIN_SUBSTANTIVE_WORDS, storedDefect, substantiveWordCount, } from './memory-quality.js';
4
4
  import { heldTexts } from '../util/same-text.js';
5
+ import { isSuperseded } from './liveness.js';
5
6
  export function auditMemory(entry, backsObject = false) {
6
7
  const issue = classifyMemory(entry);
7
8
  // Error means "auto-remove"; a pinned, raw, kept-for-good or object-backing row is never
@@ -90,7 +91,7 @@ export function repairKeeps(entry, backsObject, protection) {
90
91
  }
91
92
  /** The rows quality repair judges: a superseded or archived row is already out of recall. */
92
93
  export function isRepairCandidate(entry) {
93
- return !entry.supersededBy && entry.kind !== 'archived';
94
+ return !isSuperseded(entry) && entry.kind !== 'archived';
94
95
  }
95
96
  function structured(entry) {
96
97
  return (entry.traceOutcome !== null ||
@@ -3,8 +3,6 @@ import { Layer, type MemoryEntry } from './entry.js';
3
3
  export declare const BAND_AT_RISK = 3;
4
4
  /** Layers in the dashboard's wire order; a layer's index is its place here. */
5
5
  export declare const LAYER_ORDER: readonly [Layer.Buffer, Layer.Episodic, Layer.Semantic, Layer.Trace];
6
- /** Confidence tiers in sort order; any other tier sorts after them. */
7
- export declare const CONFIDENCE_ORDER: readonly ["verified", "observed", "inferred", "stale"];
8
6
  /** Days of created history the dashboard's series spans; an older row counts at its first point. */
9
7
  export declare const SERIES_DAYS = 90;
10
8
  export interface MemoryFacts {
@@ -11,8 +11,6 @@ const BAND_FADING = 2;
11
11
  export const BAND_AT_RISK = 3;
12
12
  /** Layers in the dashboard's wire order; a layer's index is its place here. */
13
13
  export const LAYER_ORDER = [Layer.Buffer, Layer.Episodic, Layer.Semantic, Layer.Trace];
14
- /** Confidence tiers in sort order; any other tier sorts after them. */
15
- export const CONFIDENCE_ORDER = ['verified', 'observed', 'inferred', 'stale'];
16
14
  /** Days of created history the dashboard's series spans; an older row counts at its first point. */
17
15
  export const SERIES_DAYS = 90;
18
16
  const AHEAD_7D_MS = 7 * DAY_MS;
@@ -4,6 +4,7 @@
4
4
  // only once restored.
5
5
  import { generateId } from './entry.js';
6
6
  import { duplicateKey, heldTexts, mergedText } from '../util/same-text.js';
7
+ import { isSuperseded } from './liveness.js';
7
8
  /**
8
9
  * The row that replaces a merged row once its retired texts leave: undefined when it holds none,
9
10
  * null when nothing else is left.
@@ -34,10 +35,10 @@ export function mergedSuccessor(row, retired, retiredIds) {
34
35
  * rejection now covers.
35
36
  */
36
37
  export function successorAfterRetirement(row, byId, rejected) {
37
- if (row.source !== 'consolidation' || row.supersededBy)
38
+ if (row.source !== 'consolidation' || isSuperseded(row))
38
39
  return undefined;
39
40
  const sources = row.parents.flatMap((id) => byId.get(id) ?? []);
40
- const retiredIds = new Set(sources.filter((s) => Boolean(s.supersededBy) || rejected(s.content)).map((s) => s.id));
41
+ const retiredIds = new Set(sources.filter((s) => isSuperseded(s) || rejected(s.content)).map((s) => s.id));
41
42
  const live = new Set(sources.filter((s) => !retiredIds.has(s.id)).map((s) => duplicateKey(s.content)));
42
43
  const gone = new Set(sources.filter((s) => retiredIds.has(s.id)).map((s) => duplicateKey(s.content)));
43
44
  const retired = (text) => (gone.has(duplicateKey(text)) && !live.has(duplicateKey(text))) || rejected(text);
@@ -1,5 +1,6 @@
1
1
  // Not in same-text because it reads the user-rule tag, and base/util may not import base/memory.
2
2
  import { USER_RULE_TAG } from './entry.js';
3
+ import { isSuperseded } from './liveness.js';
3
4
  /** Whether a stated rule replaces this held copy: a live, observed capture row of `ruleProject`
4
5
  * (the rule's project names), unpinned or pinned without the user-rule tag. Any other copy stops
5
6
  * the rule, so a replayed transcript revives nothing and no project loses its row. */
@@ -8,7 +9,7 @@ export function ruleReplaces(row, ruleProject) {
8
9
  row.source === 'capture' &&
9
10
  Boolean(row.originProject) &&
10
11
  ruleProject.includes(row.originProject ?? '') &&
11
- row.supersededBy == null &&
12
+ !isSuperseded(row) &&
12
13
  row.confidence === 'observed');
13
14
  }
14
15
  //# sourceMappingURL=rule-replaces.js.map
@@ -0,0 +1,9 @@
1
+ import type { MemoryEntry } from './entry.js';
2
+ /** The tag invalidation puts on a memory it weakened. */
3
+ export declare const INVALIDATED_TAG = "invalidated";
4
+ /** The tag a decision puts on the memory it replaced. */
5
+ export declare const SUPERSEDED_TAG = "superseded";
6
+ /** The row marked stale under tag `marker`, its half-life halved only when it is not already stale under that
7
+ * marker: repeating the act changes nothing, and a marker copied onto a fresh row does not block the first halving. */
8
+ export declare function markStale(entry: MemoryEntry, marker: string): MemoryEntry;
9
+ //# sourceMappingURL=stale-mark.d.ts.map
@@ -0,0 +1,18 @@
1
+ /** The tag invalidation puts on a memory it weakened. */
2
+ export const INVALIDATED_TAG = 'invalidated';
3
+ /** The tag a decision puts on the memory it replaced. */
4
+ export const SUPERSEDED_TAG = 'superseded';
5
+ /** The row marked stale under tag `marker`, its half-life halved only when it is not already stale under that
6
+ * marker: repeating the act changes nothing, and a marker copied onto a fresh row does not block the first halving. */
7
+ export function markStale(entry, marker) {
8
+ const tagged = entry.tags.includes(marker);
9
+ if (tagged && entry.confidence === 'stale')
10
+ return { ...entry };
11
+ return {
12
+ ...entry,
13
+ confidence: 'stale',
14
+ halfLifeDays: Math.max(1, Math.floor(entry.halfLifeDays / 2)),
15
+ tags: tagged ? entry.tags : [...entry.tags, marker],
16
+ };
17
+ }
18
+ //# sourceMappingURL=stale-mark.js.map
@@ -16,10 +16,14 @@ export interface ConflictRow {
16
16
  readonly a: ConflictMember | null;
17
17
  readonly b: ConflictMember | null;
18
18
  }
19
+ /** Every status a memory conflict row may hold. */
20
+ export declare const CONFLICT_STATUSES: readonly ["open", "resolved"];
21
+ /** One of `CONFLICT_STATUSES`. */
22
+ export type ConflictStatus = (typeof CONFLICT_STATUSES)[number];
19
23
  export interface ConflictListQuery {
20
24
  /** ALL_TENANTS is host admin, which the api checks. */
21
25
  readonly tenantId: TenantId;
22
- /** '*' reads every status. */
26
+ /** Open, resolved, or '*' for every status. */
23
27
  readonly status: string;
24
28
  readonly limit: number;
25
29
  /** Resume after this (updatedAt, id) position; the list runs newest change first. */
@@ -1,3 +1,5 @@
1
+ /** Every status a memory conflict row may hold. */
2
+ export const CONFLICT_STATUSES = ['open', 'resolved'];
1
3
  /** What each Conflicts method does to the store; every adapter honours it. */
2
4
  export const CONFLICTS_EFFECTS = {
3
5
  list: 'read',
@@ -30,8 +30,48 @@ export interface Consolidation {
30
30
  /** Writes the particles over their stored state, as one batch. */
31
31
  saveParticles(particles: PhysicsParticle[]): Promise<void>;
32
32
  /** The `limit` dirty summaries changed last, each with its live children by created then id,
33
- * and whether more were waiting. */
34
- dirtySummaries(limit: number): Promise<DirtySummaries>;
33
+ * and whether more were waiting. With `at`, a summary held past it is skipped and counted in
34
+ * `held`; an adapter that ignores `at` stores no hold unless it has `noteRebuildFailures`. */
35
+ dirtySummaries(limit: number, at?: string): Promise<DirtySummaries>;
36
+ /** Stores one pass's counted rebuild failures in one write; an item lands only while the stored
37
+ * count equals its `priorFailures`. Optional: a store without it keeps no holds and sleep sends
38
+ * every dirty summary as before. */
39
+ noteRebuildFailures?(failed: ReadonlyArray<{
40
+ readonly id: string;
41
+ readonly tenantId: string;
42
+ readonly priorFailures: number;
43
+ readonly failures: number;
44
+ /** The ISO time the summary is next sent to the model; null while it is not held. */
45
+ readonly retryAfter: string | null;
46
+ }>): Promise<void>;
47
+ /** Up to `page.limit` empty extraction marks by source id, after the id `page.after`, and the id
48
+ * to continue after (null on the last page). A mark says extraction found nothing in that
49
+ * text of the source. Optional: a store without it keeps no marks and sleep offers every
50
+ * source as before. */
51
+ emptyExtractions?(page: {
52
+ readonly limit: number;
53
+ readonly after?: string;
54
+ }): Promise<{
55
+ readonly marks: ReadonlyArray<{
56
+ readonly id: string;
57
+ /** The hash of the source text the model found nothing in. */
58
+ readonly digest: string;
59
+ /** The ISO time of that call. */
60
+ readonly at: string;
61
+ }>;
62
+ readonly next: string | null;
63
+ }>;
64
+ /** Stores `mark` and drops the marks of the ids in `clear`, in one write; a mark lands only for
65
+ * a source that is live (neither archived nor superseded), and the marks of sources that are
66
+ * gone or no longer live are dropped with it. Optional, as `emptyExtractions` is. */
67
+ noteEmptyExtractions?(note: {
68
+ readonly mark: ReadonlyArray<{
69
+ readonly id: string;
70
+ readonly digest: string;
71
+ readonly at: string;
72
+ }>;
73
+ readonly clear: readonly string[];
74
+ }): Promise<void>;
35
75
  /** Up to `page.limit` of the L2 topic summaries with no L3 profile above them, oldest first,
36
76
  * after `page.after`. */
37
77
  unprofiledTopicSummaries(page: {
@@ -72,6 +112,9 @@ export declare const CONSOLIDATION_EFFECTS: {
72
112
  readonly particlesByRecall: "read";
73
113
  readonly saveParticles: "write";
74
114
  readonly dirtySummaries: "read";
115
+ readonly noteRebuildFailures: "write";
116
+ readonly emptyExtractions: "read";
117
+ readonly noteEmptyExtractions: "write";
75
118
  readonly unprofiledTopicSummaries: "read";
76
119
  readonly settleSummary: "write";
77
120
  readonly commit: "write";
@@ -137,8 +180,14 @@ export interface DirtySummaries {
137
180
  readonly summaries: ReadonlyArray<{
138
181
  readonly summary: MemoryEntry;
139
182
  readonly children: MemoryEntry[];
183
+ /** The rebuild failures in a row stored for it; 0 when none, and unset by a store that keeps
184
+ * none. */
185
+ readonly failures?: number;
140
186
  }>;
141
187
  readonly more: boolean;
188
+ /** Dirty summaries skipped because their hold had not ended at `at`; unset when `at` was not
189
+ * given or the store keeps no holds. */
190
+ readonly held?: number;
142
191
  }
143
192
  /** The fields one dirty summary settles to; its dirty mark is cleared with them. */
144
193
  export interface SummarySettle {
@@ -7,6 +7,9 @@ export const CONSOLIDATION_EFFECTS = {
7
7
  particlesByRecall: 'read',
8
8
  saveParticles: 'write',
9
9
  dirtySummaries: 'read',
10
+ noteRebuildFailures: 'write',
11
+ emptyExtractions: 'read',
12
+ noteEmptyExtractions: 'write',
10
13
  unprofiledTopicSummaries: 'read',
11
14
  settleSummary: 'write',
12
15
  commit: 'write',