hippo-memory 2.1.0 → 2.2.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
@@ -78,7 +78,7 @@ claim we retracted.
78
78
 
79
79
  ## Quick start
80
80
 
81
- Start in one project. [What hippo init changes](#what-hippo-init-changes) lists everything the second command writes.
81
+ Start in one project. [What hippo init changes](#what-hippo-init-changes) lists everything the second command writes. A step-by-step version is on the website: [hippo-memory.com/quickstart](https://hippo-memory.com/quickstart/).
82
82
 
83
83
  ```bash
84
84
  npm install -g hippo-memory
@@ -223,11 +223,11 @@ hippo context --auto --budget 1500
223
223
  hippo snapshot clear
224
224
  ```
225
225
 
226
- `hippo context --auto` includes the active task snapshot before long-term memories, so agents get both the immediate thread and the deeper lessons.
226
+ `hippo context --auto` prints the active task snapshot before long-term memories when the calling session saved it, so agents get both the immediate thread and the deeper lessons. A snapshot from another session prints as one line that names the command that shows it.
227
227
 
228
228
  ### Session event trails
229
229
 
230
- Manual snapshots are useful, but real work also needs a breadcrumb trail. Hippo can now store short session events and link them to the active snapshot so context output shows the latest steps, not just the last summary.
230
+ Manual snapshots are useful, but real work also needs a breadcrumb trail. Hippo can now store short session events and link them to the active snapshot so context output shows the latest steps, not just the last summary. The trail prints for the calling session's own snapshot; for another session's, the command in the pointer line prints it.
231
231
 
232
232
  ```bash
233
233
  hippo session log \
@@ -810,6 +810,8 @@ On `heartbeat`, `block`, `review` and `complete`, a given `--run` is checked aga
810
810
 
811
811
  Init patches an instruction file only if it already exists. It also sets up a daily run and imports your coding agents' own memories; [What hippo init changes](#what-hippo-init-changes) lists everything.
812
812
 
813
+ Setup guides on the website: [Claude Code](https://hippo-memory.com/claude-code/) · [Codex](https://hippo-memory.com/codex/) · [Cursor](https://hippo-memory.com/cursor/).
814
+
813
815
  ### Manual install
814
816
 
815
817
  If you prefer explicit control:
@@ -823,7 +825,7 @@ hippo hook install opencode # patches AGENTS.md + installs the opencode TS
823
825
  ```
824
826
 
825
827
  This adds a `<!-- hippo:start -->` ... `<!-- hippo:end -->` block that tells the agent to:
826
- 1. Run `hippo context --auto --budget 1500` at session start
828
+ 1. Run `hippo context --auto --budget 1500` at the start of a task. In Claude Code and Codex, whose prompt hook already injects pinned rules and matching memories, only if no hippo memory block has appeared in the session
827
829
  2. Run `hippo remember "<what went wrong and why>" --error` the moment it finds out why something failed, never as a closing step
828
830
  3. Everywhere but Claude Code, whose own auto memory does this job: run a plain `hippo remember` the moment it learns something that should outlive the session, leaving out secrets and personal details
829
831
  4. Capture a short summary with `hippo capture --stdin` when the session ends, but only where no hook captures the session: Cursor, OpenClaw, OpenCode, Pi, and Codex without its wrapper
@@ -856,11 +858,9 @@ For GitHub Copilot, when `$COPILOT_HOME` (else `~/.copilot`) or a VS Code User f
856
858
  ````markdown
857
859
  ## Project Memory (Hippo)
858
860
 
859
- Pinned rules and recent writes auto-inject at every prompt via the installed
860
- UserPromptSubmit hook; never re-run that part manually. At the START of a
861
- task (not per prompt), additionally load task-specific context: git-aware
862
- recall over the full store that per-prompt injection does not cover. Also
863
- run it if the hook is not installed:
861
+ The installed UserPromptSubmit hook injects pinned rules and the memories
862
+ that match each prompt, so never load them yourself. If no hippo memory
863
+ block has appeared in this session, run this at the start of a task:
864
864
  ```bash
865
865
  hippo context --auto --budget 1500
866
866
  ```
@@ -877,6 +877,8 @@ ends, so there is nothing to run before you finish.
877
877
 
878
878
  ### MCP Server
879
879
 
880
+ Setup for each client: [hippo-memory.com/mcp](https://hippo-memory.com/mcp/).
881
+
880
882
  For any MCP-compatible client (Cursor, Windsurf (now Devin Desktop), Cline, Claude Desktop):
881
883
 
882
884
  ```bash
@@ -991,6 +993,8 @@ The AI-memory category matured fast in 2026. Hippo's specific take (bio-decay, s
991
993
 
992
994
  Different tools answer different questions. Mem0 and Basic Memory implement "save everything, search later." MemPalace implements "store everything, organize spatially for retrieval." gbrain, Zep, and Cognee implement "extract typed entities and relationships into a knowledge graph." Letta implements "the agent edits its own memory blocks." Memoria implements "Git-style version control over the memory state itself." EverMind implements "self-evolving Skill Memory + multi-modal retrieval over hierarchical scopes." Hippo implements "learn what is wrong and stop repeating it." These are complementary takes, not a single-axis ranking: bio-lifecycle (Hippo) + GraphRAG (gbrain/Cognee/Zep) + agent-self-edit (Letta) + memory-VCS (Memoria) + skill-distillation (EverMind) cover different parts of the same problem.
993
995
 
996
+ Side-by-side pages on the website: [hippo vs mem0](https://hippo-memory.com/vs/mem0/) · [hippo vs Zep](https://hippo-memory.com/vs/zep/) · [hippo vs Letta](https://hippo-memory.com/vs/letta/) · [CLAUDE.md vs MEMORY.md](https://hippo-memory.com/vs/claude-memory/).
997
+
994
998
  ---
995
999
 
996
1000
  ## Benchmarks
@@ -1097,7 +1101,7 @@ node run.mjs --adapter all
1097
1101
 
1098
1102
  ### How do I give Claude Code memory between sessions?
1099
1103
 
1100
- Run `npm install -g hippo-memory`, then `hippo init` in the project. If the project has a `CLAUDE.md`, init adds a short block telling Claude to run `hippo context --auto` when a session starts. It also adds hooks to Claude Code's settings that keep your pinned memories in context, save a task snapshot before compaction, and run `hippo sleep` when the session ends. `hippo init --scan ~` gives every git repo under your home folder a store and installs the same hooks, but adds no block to any `CLAUDE.md`. The [Claude Code plugin](https://github.com/kitfunso/hippo-memory/tree/master/extensions/claude-code-plugin) is the alternative to these hooks; use one, not both.
1104
+ Run `npm install -g hippo-memory`, then `hippo init` in the project. If the project has a `CLAUDE.md`, init adds a short block saying the prompt hook injects pinned rules and matching memories, and asking Claude to run `hippo context --auto` at the start of a task only if no hippo memory block has appeared. It also adds hooks to Claude Code's settings that keep your pinned memories in context, save a task snapshot before compaction, and run `hippo sleep` when the session ends. `hippo init --scan ~` gives every git repo under your home folder a store and installs the same hooks, but adds no block to any `CLAUDE.md`. The [Claude Code plugin](https://github.com/kitfunso/hippo-memory/tree/master/extensions/claude-code-plugin) is the alternative to these hooks; use one, not both.
1101
1105
 
1102
1106
  ### How do I give Cursor memory between sessions?
1103
1107
 
package/bin/hippo.js CHANGED
@@ -1,4 +1,8 @@
1
1
  #!/usr/bin/env node
2
- import { runCli } from '../dist/cli.js';
2
+ // node:sqlite warns once per process, and an agent reads the lines on each hippo call.
3
+ const emit = process.emitWarning;
4
+ process.emitWarning = (w, ...rest) =>
5
+ rest[0] === 'ExperimentalWarning' && /SQLite/.test(String(w)) ? undefined : emit.call(process, w, ...rest);
6
+ const { runCli } = await import('../dist/cli.js');
3
7
 
4
8
  runCli();
@@ -1,9 +1,11 @@
1
1
  import { type MemoryEntry } from '../core/memory.js';
2
2
  import { type SessionHandoff } from '../core/handoff.js';
3
3
  import type { SessionEvent, TaskSnapshot } from '../store/rows.js';
4
- import type { AssembleCost, AssembleResult, AssembledContextItem, ContextCost, ContextResultEntry, DrillDownChild, DrillDownCost, DrillDownResult } from './index.js';
4
+ import type { AssembleCost, AssembleResult, AssembledContextItem, ContextCost, ContextResultEntry, ContinuityMode, DrillDownChild, DrillDownCost, DrillDownResult } from './index.js';
5
5
  export declare function snapshotText(s: TaskSnapshot): string;
6
6
  export declare function handoffText(h: SessionHandoff): string;
7
+ export declare function snapshotSectionText(s: TaskSnapshot, mode: ContinuityMode): string;
8
+ export declare function handoffSectionText(h: SessionHandoff, mode: ContinuityMode): string;
7
9
  /** Needs at least one event; the header reads the latest. */
8
10
  export declare function sessionTrailText(events: SessionEvent[]): string;
9
11
  export declare const COMPACT_RESUME_EVENT_CONTENT_CAP = 400;
@@ -42,6 +42,28 @@ export function handoffText(h) {
42
42
  lines.push('');
43
43
  return lines.join('\n');
44
44
  }
45
+ // Another session's state rarely bears on this prompt, so a text reader prints where to read it, not the text.
46
+ const pointerTime = (iso) => iso.slice(0, 16).replace('T', ' ');
47
+ // continuityModeFor sends only a pointer-safe id (or a snapshot with none) here, so these only format.
48
+ function snapshotPointerText(s) {
49
+ const at = pointerTime(s.updated_at);
50
+ const line = s.session_id
51
+ ? `- Session ${s.session_id} saved a task snapshot at ${at} UTC. ` +
52
+ `If this task continues it, run \`hippo session latest --id=${s.session_id}\`.`
53
+ : `- A task snapshot from ${at} UTC names no session. If this task continues it, run \`hippo snapshot show\`.`;
54
+ return ['## Active Task Snapshot\n', line, ''].join('\n');
55
+ }
56
+ function handoffPointerText(h) {
57
+ const line = `- Session ${h.sessionId} left a handoff at ${pointerTime(h.updatedAt)} UTC. ` +
58
+ `If this task continues it, run \`hippo handoff latest --session=${h.sessionId}\`.`;
59
+ return ['## Session Handoff\n', line, ''].join('\n');
60
+ }
61
+ export function snapshotSectionText(s, mode) {
62
+ return mode === 'pointer' ? snapshotPointerText(s) : snapshotText(s);
63
+ }
64
+ export function handoffSectionText(h, mode) {
65
+ return mode === 'pointer' ? handoffPointerText(h) : handoffText(h);
66
+ }
45
67
  /** Needs at least one event; the header reads the latest. */
46
68
  export function sessionTrailText(events) {
47
69
  const latest = events[events.length - 1];
@@ -183,8 +205,8 @@ export function contextCost(format, framing) {
183
205
  + (can.cross ? price(crossProjectHeading(budget)) : 0)
184
206
  + (hook && can.promptRecall ? price(contextHeading('Prompt-Relevant Memory', budget, budget)) : 0)
185
207
  + (!hook && can.ambient ? price(`\n${renderAmbientSummary(WIDEST_AMBIENT)}`) : 0),
186
- snapshot: (s) => price(snapshotText(s)),
187
- handoff: (h) => price(handoffText(h)),
208
+ snapshot: (s, mode) => price(snapshotSectionText(s, mode)),
209
+ handoff: (h, mode) => price(handoffSectionText(h, mode)),
188
210
  trail: (events) => price(sessionTrailText(events)),
189
211
  };
190
212
  }
@@ -4,6 +4,8 @@ import type { MemoryEntry } from '../core/memory.js';
4
4
  import type { DeliveryObserver } from '../store/delivery-recorder.js';
5
5
  import type { AmbientState } from '../core/ambient.js';
6
6
  import type { ProjectRef } from '../core/project-identity.js';
7
+ /** How another session's task snapshot and handoff print: whole, or as a continuity pointer. */
8
+ export type ContinuityMode = 'full' | 'pointer';
7
9
  /**
8
10
  * Options for `getContext`: a budget-bounded bundle of recalled memories, active task snapshot, handoff and recent
9
11
  * events.
@@ -49,6 +51,8 @@ export interface ContextOpts {
49
51
  currentSessionId?: string | null;
50
52
  /** Raw hook-payload prompt; only the pinned-only branch reads it, gated on `pinnedInject.promptRecall`. */
51
53
  prompt?: string;
54
+ /** Default 'full'; under 'pointer' the caller's own session, a shared store and an unsafe id still print whole. */
55
+ continuity?: ContinuityMode;
52
56
  /** What the budget pays for, from the caller that renders the block. Absent = the memory text alone. */
53
57
  cost?: ContextCost;
54
58
  /** @internal The CLI's delivery-ledger observer; it only reads, so selection is the same with or without it. */
@@ -66,8 +70,8 @@ export interface ContextCost {
66
70
  ambient: boolean;
67
71
  }) => number;
68
72
  /** Tokens of the sections printed ahead of the memories, each as printed. */
69
- snapshot: (s: TaskSnapshot) => number;
70
- handoff: (h: SessionHandoff) => number;
73
+ snapshot: (s: TaskSnapshot, mode: ContinuityMode) => number;
74
+ handoff: (h: SessionHandoff, mode: ContinuityMode) => number;
71
75
  trail: (events: SessionEvent[]) => number;
72
76
  }
73
77
  export interface ContextResultEntry {
@@ -92,6 +96,9 @@ export interface ContextResult {
92
96
  tokens: number;
93
97
  activeSnapshot?: TaskSnapshot | null;
94
98
  sessionHandoff?: SessionHandoff | null;
99
+ /** Set only when the snapshot or the handoff prints as the pointer. */
100
+ snapshotMode?: ContinuityMode;
101
+ handoffMode?: ContinuityMode;
95
102
  recentEvents?: SessionEvent[];
96
103
  /** The ambient landscape summary over every live row the read may see in the local and global stores,
97
104
  * not just the rows loaded. Present only when ambient config is on, the caller is not pinned-only, and an entry was
@@ -2,6 +2,7 @@
2
2
  import { DEFAULT_SEARCH_CANDIDATE_LIMIT } from '../store/rows.js';
3
3
  import { freshActiveSnapshot, SNAPSHOT_AMBIENT_MAX_AGE_MS } from '../store/sessions.js';
4
4
  import { estimateTokens } from '../util/token-text.js';
5
+ import { isPointerSafeId } from '../util/session-id.js';
5
6
  import { markRetrieved, COMPACTION_MEMORY_TAG } from '../core/memory.js';
6
7
  import { isWorthSurfacing } from '../core/memory-quality.js';
7
8
  import { evalNow, strengthAblation } from '../core/ablation.js';
@@ -131,14 +132,7 @@ export async function getContext(ctx, opts = {}) {
131
132
  const recorded = plan.pinnedOnly
132
133
  ? { items, ambientState: undefined }
133
134
  : await recordRetrieval(ctx, opts, plan, items, sections.activeSnapshot);
134
- return {
135
- entries: recorded.items,
136
- tokens,
137
- activeSnapshot: sections.shownSnapshot ?? undefined,
138
- sessionHandoff: sections.shownHandoff ?? undefined,
139
- recentEvents: sections.shownEvents.length > 0 ? sections.shownEvents : undefined,
140
- ambientState: recorded.ambientState,
141
- };
135
+ return contextResult(recorded, tokens, sections);
142
136
  }
143
137
  function nothingToInject(plan, pools, noSections) {
144
138
  return (!plan.promptRecallPending && pools.local.entries.length === 0 && pools.global.entries.length === 0 && noSections);
@@ -305,19 +299,52 @@ async function loadTaskSections(ctx, opts, plan, startLeft) {
305
299
  // The same envelope rule ambientAdmitEntry applies to memory rows.
306
300
  const activeSnapshot = raw.snapshot && passesScopeFilterForRecall(rowScope(raw.snapshot), exactScope, ownScope) ? raw.snapshot : null;
307
301
  const sessionHandoff = raw.handoff && passesScopeFilterForRecall(rowScope(raw.handoff), exactScope, ownScope) ? raw.handoff : null;
308
- const recentSessionEvents = raw.events.filter((e) => passesScopeFilterForRecall(rowScope(e), exactScope, ownScope));
309
- const shownSnapshot = activeSnapshot && (!cost || pays(cost.snapshot(activeSnapshot))) ? activeSnapshot : null;
310
- const shownHandoff = sessionHandoff && (!cost || pays(cost.handoff(sessionHandoff))) ? sessionHandoff : null;
302
+ const snapshotMode = continuityModeFor(opts, plan, activeSnapshot?.session_id, 'pointer');
303
+ const handoffMode = continuityModeFor(opts, plan, sessionHandoff?.sessionId, 'full');
304
+ const shownSnapshot = activeSnapshot && (!cost || pays(cost.snapshot(activeSnapshot, snapshotMode))) ? activeSnapshot : null;
305
+ const shownHandoff = sessionHandoff && (!cost || pays(cost.handoff(sessionHandoff, handoffMode))) ? sessionHandoff : null;
306
+ // The pointer's command prints the snapshot session's events, so they drop only when that pointer is shown.
307
+ const recentSessionEvents = shownSnapshot !== null && snapshotMode === 'pointer'
308
+ ? []
309
+ : raw.events.filter((e) => passesScopeFilterForRecall(rowScope(e), exactScope, ownScope));
311
310
  const shownEvents = recentSessionEvents.length > 0 && (!cost || pays(cost.trail(recentSessionEvents))) ? recentSessionEvents : [];
312
311
  plan.obs?.sections(Number(shownSnapshot !== null) + Number(shownHandoff !== null) + Number(shownEvents.length > 0), Number(activeSnapshot !== shownSnapshot) +
313
312
  Number(sessionHandoff !== shownHandoff) +
314
313
  Number(recentSessionEvents.length !== shownEvents.length));
315
- return { activeSnapshot, shownSnapshot, shownHandoff, shownEvents, left: left() };
314
+ return { activeSnapshot, shownSnapshot, snapshotMode, shownHandoff, handoffMode, shownEvents, left: left() };
315
+ }
316
+ // The command must return this reader's row, so own, shared-store, unsafe-id print whole; no id: `hippo snapshot show`.
317
+ function continuityModeFor(opts, plan, sessionId, noIdMode) {
318
+ if (opts.continuity !== 'pointer' || plan.sharedStore)
319
+ return 'full';
320
+ if (!sessionId)
321
+ return noIdMode;
322
+ return sessionId === opts.currentSessionId || !isPointerSafeId(sessionId) ? 'full' : 'pointer';
323
+ }
324
+ // The mode is left out of a full print, so every reader's result reads as before.
325
+ function pointerModes(s) {
326
+ const modes = {};
327
+ if (s.shownSnapshot && s.snapshotMode === 'pointer')
328
+ modes.snapshotMode = 'pointer';
329
+ if (s.shownHandoff && s.handoffMode === 'pointer')
330
+ modes.handoffMode = 'pointer';
331
+ return modes;
332
+ }
333
+ function contextResult(recorded, tokens, s) {
334
+ return {
335
+ entries: recorded.items,
336
+ tokens,
337
+ activeSnapshot: s.shownSnapshot ?? undefined,
338
+ sessionHandoff: s.shownHandoff ?? undefined,
339
+ ...pointerModes(s),
340
+ recentEvents: s.shownEvents.length > 0 ? s.shownEvents : undefined,
341
+ ambientState: recorded.ambientState,
342
+ };
316
343
  }
317
344
  function ambientAdmission(opts, plan, shownHandoff) {
318
345
  const transcriptHandoffSession = shownHandoff?.evidence?.derivedFrom === 'transcript' ? shownHandoff.sessionId : null;
319
346
  const ambientAdmit = (e) => {
320
- // A printed handoff already carries the session's closing message, which its digest would print a second time.
347
+ // A shown handoff, whole or as a pointer, stands for the session's closing message; its command prints it.
321
348
  if (transcriptHandoffSession !== null &&
322
349
  e.source_session_id === transcriptHandoffSession &&
323
350
  isSessionDigestRow(e)) {
@@ -30,7 +30,7 @@ export { DEFAULT_KEY_TTL_DAYS, MAX_TTL_DAYS, authCreate, authCreateSelf, authGra
30
30
  export type { AuthCreateOpts, AuthCreateResult, AuthCreateSelfOpts, AuthCreateSelfResult, AuthGrantResult, AuthRevokeResult, } from './auth/auth.js';
31
31
  export { auditList, auditMemoryQuality, computeCutoff, pruneAuditLog, removeAuditErrors, repairMemoryQuality, repairMemoryQualityOnce, } from './auth/audit.js';
32
32
  export type { AuditListOpts, AuditPass, PruneAuditOpts, PruneAuditResult } from './auth/audit.js';
33
- export type { ContextCost, ContextOpts, ContextResult, ContextResultEntry } from './context-types.js';
33
+ export type { ContextCost, ContextOpts, ContextResult, ContextResultEntry, ContinuityMode } from './context-types.js';
34
34
  export { DEFAULT_CONTEXT_BUDGET, NO_QUERY, ambientSecretAdmit, getContext, oneCopyPerMemory } from './context.js';
35
35
  export { failureSummary, recordTokens, tokenSummary } from './tokens.js';
36
36
  export { forgetDormant, isDormant, listDormant, restoreDormant } from './sleep/dormant.js';
@@ -1,4 +1,4 @@
1
- import { type Context, type ContextResult, type ContextResultEntry, type ContextWith } from './index.js';
1
+ import { type Context, type ContextResult, type ContextResultEntry, type ContextWith, type ContinuityMode } from './index.js';
2
2
  import { type HippoConfig } from '../core/config.js';
3
3
  import { type DeliveryEventType, type DeliveryFault, type DeliveryRecorder } from '../store/delivery-recorder.js';
4
4
  import type { HookRuntime } from '../core/capture-contract.js';
@@ -82,6 +82,8 @@ export interface PromptHookOpts {
82
82
  /** The store serves many people, so the caller is not its owner: no global store, no user-global recent rows,
83
83
  * task state only for the caller's own owner and project, and no ledger rows outside this store. */
84
84
  readonly sharedStore?: true;
85
+ /** Default 'full': a pointer names a command that cannot reach this store, so the caller opts in. */
86
+ readonly continuity?: ContinuityMode;
85
87
  }
86
88
  /** The caps on a hook caller's session id and project names, so a caller other than an HTTP route is bounded too. */
87
89
  export declare function assertCallerIds(sessionId: string, project: CallerProject): void;
@@ -1,10 +1,10 @@
1
1
  // The per-prompt hook's block and ledger rows, rendered here for `hippo context` and for promptHookContext (a remote
2
- // hook route's call). promptHookContext keeps the server-side copy of the CLI's getContext flags (cli/context.ts); the
3
- // CLI parity case in tests/prompt-hook-context.test.ts is all that ties the two.
4
- import { getContext } from './index.js';
2
+ // hook route's call). promptHookContext copies the CLI's getContext flags (cli/context.ts) bar `continuity`: the CLI
3
+ // points for text formats; this prints whole unless its caller opts in. Parity: tests/prompt-hook-context.test.ts.
4
+ import { getContext, } from './index.js';
5
5
  import { BadRequestError } from '../core/api-errors.js';
6
6
  import { isSharedStore, loadConfig } from '../core/config.js';
7
- import { contextBlockLines, contextCost, crossProjectLines, handoffText, sessionTrailText, settleTokens, snapshotText, } from './context-render.js';
7
+ import { contextBlockLines, contextCost, crossProjectLines, handoffSectionText, sessionTrailText, settleTokens, snapshotSectionText, } from './context-render.js';
8
8
  import { createDeliveryRecorder, } from '../store/delivery-recorder.js';
9
9
  import { realpathOrResolve } from '../util/real-path.js';
10
10
  import { MAX_ID_LEN } from '../util/limits.js';
@@ -99,8 +99,8 @@ export function additionalContextOutput(view) {
99
99
  function renderStaticBlock(view, staticItems, staticCrossEntries) {
100
100
  const { result, framing } = view;
101
101
  return settleTokens((t) => [
102
- ...(result.activeSnapshot ? [snapshotText(result.activeSnapshot)] : []),
103
- ...(result.sessionHandoff ? [handoffText(result.sessionHandoff)] : []),
102
+ ...(result.activeSnapshot ? [snapshotSectionText(result.activeSnapshot, result.snapshotMode ?? 'full')] : []),
103
+ ...(result.sessionHandoff ? [handoffSectionText(result.sessionHandoff, result.handoffMode ?? 'full')] : []),
104
104
  ...(result.recentEvents && result.recentEvents.length > 0 ? [sessionTrailText(result.recentEvents)] : []),
105
105
  // No live strength percentage, so an unchanged set of memories renders byte-identically turn after turn.
106
106
  ...(staticItems.length > 0 ? contextBlockLines(staticItems, t, framing, { showStrength: false }) : []),
@@ -251,6 +251,7 @@ export async function promptHookContext(ctx, req, opts = {}) {
251
251
  prompt: isJsonString(prompt) ? prompt : undefined,
252
252
  cost: contextCost('additional-context', HOOK_FRAMING),
253
253
  sharedStore,
254
+ continuity: opts.continuity ?? 'full',
254
255
  });
255
256
  const rendered = hasContextData(result)
256
257
  ? renderAdditionalContext({
@@ -8,7 +8,6 @@ export interface CopilotTurn {
8
8
  role: 'user' | 'assistant';
9
9
  text: string;
10
10
  }
11
- export declare const SESSION_ID_RE: RegExp;
12
11
  /**
13
12
  * The Copilot CLI log for a session, `<copilotHome>/session-state/<id>/events.jsonl`; null for an unsafe id or a
14
13
  * missing file.
@@ -5,8 +5,7 @@ import * as fs from 'fs';
5
5
  import * as path from 'path';
6
6
  import { copilotHomeDir } from '../hooks/shared.js';
7
7
  import { isObjectLike, isStringValue } from '../core/capture-contract.js';
8
- // A session id becomes a folder name, so anything beyond word characters and hyphens could climb out of session-state.
9
- export const SESSION_ID_RE = /^[\w-]+$/;
8
+ import { SESSION_ID_RE } from '../util/session-id.js';
10
9
  // user.message sources that mark text hippo did not get from the human: a hidden skill injection or another agent's
11
10
  // prompt.
12
11
  const INJECTED_SOURCE_PREFIXES = ['skill-', 'agent-'];
@@ -5,7 +5,7 @@ import * as path from 'path';
5
5
  import { homeDir } from '../util/agent-homes.js';
6
6
  import { errorCode, errorMessage, log as logger, errorFields } from '../util/log.js';
7
7
  import { isObjectLike, isStringValue } from '../core/capture-contract.js';
8
- import { SESSION_ID_RE } from './copilot-transcript.js';
8
+ import { SESSION_ID_RE } from '../util/session-id.js';
9
9
  import { blockHash } from '../util/token-text.js';
10
10
  import { MINUTE_MS } from '../util/time.js';
11
11
  /** Null for a missing id or one that could climb out of the sessions folder. */
@@ -10,12 +10,12 @@ import * as api from '../api/index.js';
10
10
  import { DEFAULT_CONTEXT_BUDGET, NO_QUERY } from '../api/context.js';
11
11
  import { cliApiContext } from './api-context.js';
12
12
  import { renderAmbientSummary } from '../core/ambient.js';
13
- import { contextBlockLines, contextCost, crossProjectLines, settleTokens } from '../api/context-render.js';
13
+ import { contextBlockLines, contextCost, crossProjectLines, handoffSectionText, settleTokens, snapshotSectionText, } from '../api/context-render.js';
14
14
  import { additionalContextOutput, flushDeliveryRecorder, hasContextData, startDeliveryRecorder, sessionStartEnvelope, toRenderItems, } from '../api/prompt-hook.js';
15
15
  import { parseLimitFlag, parseCountFlag, parseBudgetFlag, flagIsTrue, stringFlagOrExit, } from './flag-values.js';
16
16
  import { requireInit } from './shared.js';
17
17
  import { errorFields, errorMessage, log } from '../util/log.js';
18
- import { printActiveTaskSnapshot, printSessionEvents, printHandoff, captureConsole } from './print.js';
18
+ import { printSessionEvents, captureConsole } from './print.js';
19
19
  import { hostSessionId, hookStoreRoot, hookRuntime, payloadCwdRoot, runHookWithStores, inPilotHoldout, } from './hook-runtime.js';
20
20
  async function cmdContext(hippoRoot, tenantId, args, flags, stdinText) {
21
21
  const rec = startDeliveryRecorder(cliApiContext(hippoRoot, tenantId), {
@@ -149,6 +149,8 @@ function buildContextOpts(flags, input) {
149
149
  crossProject,
150
150
  currentSessionId: input.session.currentSessionId,
151
151
  prompt: input.session.prompt,
152
+ // JSON stays whole for the programs that parse it; every text format points to another session's state.
153
+ continuity: input.format === 'json' ? 'full' : 'pointer',
152
154
  // JSON is budgeted as the markdown it stands for, so one budget picks the same memories in every format.
153
155
  cost: contextCost(input.format === 'additional-context' || input.format === 'copilot' ? 'additional-context' : 'markdown', input.framing),
154
156
  deliveryObserver: input.rec ?? undefined,
@@ -193,10 +195,10 @@ function renderContextMarkdown(view) {
193
195
  const crossEntries = result.entries.filter((r) => r.category === 'cross-project');
194
196
  const text = settleTokens((t) => captureConsole(() => {
195
197
  if (result.activeSnapshot) {
196
- printActiveTaskSnapshot(result.activeSnapshot);
198
+ console.log(snapshotSectionText(result.activeSnapshot, result.snapshotMode ?? 'full'));
197
199
  }
198
200
  if (result.sessionHandoff) {
199
- printHandoff(result.sessionHandoff);
201
+ console.log(handoffSectionText(result.sessionHandoff, result.handoffMode ?? 'full'));
200
202
  }
201
203
  if (result.recentEvents && result.recentEvents.length > 0) {
202
204
  printSessionEvents(result.recentEvents);
@@ -15,7 +15,8 @@ import { cmdCapture } from '../capture/command.js';
15
15
  import { cmdPreCompact, cmdPostCompact } from '../capture/compact.js';
16
16
  import { transcriptWorkingState } from '../capture/working-state.js';
17
17
  import { collectHandoffEvidence } from '../capture/handoff-evidence.js';
18
- import { copilotTranscriptFor, SESSION_ID_RE } from '../capture/copilot-transcript.js';
18
+ import { copilotTranscriptFor } from '../capture/copilot-transcript.js';
19
+ import { SESSION_ID_RE } from '../util/session-id.js';
19
20
  import { loadTurnPosition, runSessionWorker, saveTurnPosition, turnsAfter, } from '../capture/session-worker.js';
20
21
  import { isStringValue, readSessionEnd, readVscodeStop, } from '../core/capture-contract.js';
21
22
  import { loadConfig } from '../core/config.js';
@@ -52,11 +52,9 @@ export const HOOKS = {
52
52
  content: `
53
53
  ## Project Memory (Hippo)
54
54
 
55
- Pinned rules and recent writes auto-inject at every prompt via the installed
56
- UserPromptSubmit hook; never re-run that part manually. At the START of a
57
- task (not per prompt), additionally load task-specific context: git-aware
58
- recall over the full store that per-prompt injection does not cover. Also
59
- run it if the hook is not installed:
55
+ The installed UserPromptSubmit hook injects pinned rules and the memories
56
+ that match each prompt, so never load them yourself. If no hippo memory
57
+ block has appeared in this session, run this at the start of a task:
60
58
  \`\`\`bash
61
59
  hippo context --auto --budget 1500
62
60
  \`\`\`
@@ -77,11 +75,13 @@ ends, so there is nothing to run before you finish.
77
75
  content: `
78
76
  ## Project Memory (Hippo)
79
77
 
80
- At the start of every task, run:
78
+ When Hippo's prompt hook is installed, it injects pinned rules and the
79
+ memories that match each prompt, so never load them yourself. If no hippo
80
+ memory block has appeared in this session, run this at the start of a task
81
+ and read the output before writing any code:
81
82
  \`\`\`bash
82
83
  hippo context --auto --budget 1500
83
84
  \`\`\`
84
- Read the output before writing any code.
85
85
 
86
86
  On errors or unexpected behaviour, record it right then, while you work,
87
87
  never as a closing step:
@@ -111,6 +111,8 @@ hippo capture --stdin <<< '<decisions, errors, lessons: 2-5 bullets>'
111
111
  // sha256 of each trimmed block an earlier hippo wrote, so init refreshes only blocks nobody edited. Add the old hash
112
112
  // when a block changes.
113
113
  const SHIPPED_HOOK_HASHES = new Map([
114
+ ['c80e760208aed70f6094757736b9a2f496ba5c30d88bc2a7ae3e128b403dcc6b', 'claude-code'],
115
+ ['f1e5815a4b7205c43e2db792215df1943e7853635a1e0f4561b150a41b756451', 'codex'],
114
116
  ['c04e48f2896a4fee9ae98f8f832e2d26a3910269df3beb5bcd6baee3cd9db68e', 'claude-code'],
115
117
  ['e6b12bd8983c032e5ca8e95a97aeff4178a5a05026d10acad5b2e1b25d5656dd', 'claude-code'],
116
118
  ['4c64e11d3e5be68fa547c9248d7553feb645a02f7cf13ba02f7275e1854baf44', 'claude-code'],
@@ -101,8 +101,9 @@ export function trailPiece(events) {
101
101
  export const contextCost = {
102
102
  entry: memoryCost,
103
103
  fixed: (budget) => memoriesReserve(budget),
104
- snapshot: (s) => estimateTokens(snapshotPiece(s)),
105
- handoff: (h) => estimateTokens(handoffPiece(h)),
104
+ // hippo_context passes no continuity opt-in, so the mode is always 'full' and the full piece is the price.
105
+ snapshot: (s, _mode) => estimateTokens(snapshotPiece(s)),
106
+ handoff: (h, _mode) => estimateTokens(handoffPiece(h)),
106
107
  trail: (events) => estimateTokens(trailPiece(events)),
107
108
  };
108
109
  // Rows the ranked list already shows drop out of this section, so pricing every row bounds what it prints.
@@ -0,0 +1,4 @@
1
+ export declare const SESSION_ID_RE: RegExp;
2
+ /** An id a pointer may print in a glued `--id=<id>` flag, where even a leading `--` reads as a value. */
3
+ export declare const isPointerSafeId: (id: string) => boolean;
4
+ //# sourceMappingURL=session-id.d.ts.map
@@ -0,0 +1,6 @@
1
+ import { MAX_ID_LEN } from './limits.js';
2
+ // A session id becomes a folder name or a word in a command an agent runs, so only word characters and hyphens pass.
3
+ export const SESSION_ID_RE = /^[\w-]+$/;
4
+ /** An id a pointer may print in a glued `--id=<id>` flag, where even a leading `--` reads as a value. */
5
+ export const isPointerSafeId = (id) => id.length <= MAX_ID_LEN && SESSION_ID_RE.test(id);
6
+ //# sourceMappingURL=session-id.js.map
@@ -2,7 +2,7 @@
2
2
  * Single source of truth for the package version, written by scripts/sync-version.mjs; never edit by hand. Read by the
3
3
  * db rollback guard, /health, MCP.
4
4
  * A constant, not a runtime package.json read: the published bundle may lack package.json on a path ESM can resolve. */
5
- export declare const PACKAGE_VERSION = "2.1.0";
5
+ export declare const PACKAGE_VERSION = "2.2.0";
6
6
  /** The floor a store takes on its first expiring key: the first release with schema
7
7
  * v53, set by hand in that release; scripts/check-expiring-keys-floor.mjs gates it. */
8
8
  export declare const EXPIRING_KEYS_MIN_BINARY = "1.64.0";
@@ -2,7 +2,7 @@
2
2
  * Single source of truth for the package version, written by scripts/sync-version.mjs; never edit by hand. Read by the
3
3
  * db rollback guard, /health, MCP.
4
4
  * A constant, not a runtime package.json read: the published bundle may lack package.json on a path ESM can resolve. */
5
- export const PACKAGE_VERSION = '2.1.0';
5
+ export const PACKAGE_VERSION = '2.2.0';
6
6
  /** The floor a store takes on its first expiring key: the first release with schema
7
7
  * v53, set by hand in that release; scripts/check-expiring-keys-floor.mjs gates it. */
8
8
  export const EXPIRING_KEYS_MIN_BINARY = '1.64.0';
@@ -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": "2.1.0",
5
+ "version": "2.2.0",
6
6
 
7
7
  "configSchema": {
8
8
  "type": "object",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hippo-memory",
3
- "version": "2.1.0",
3
+ "version": "2.2.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": "2.1.0",
5
+ "version": "2.2.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": "2.1.0",
3
+ "version": "2.2.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",