hippo-memory 3.8.0 → 3.9.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 (58) hide show
  1. package/README.md +9 -8
  2. package/dist/api/agent-memories.d.ts +3 -2
  3. package/dist/api/agent-memories.js +21 -5
  4. package/dist/base/memory/agent-memory-report.js +1 -0
  5. package/dist/base/util/secret-detect.d.ts +8 -0
  6. package/dist/base/util/secret-detect.js +31 -11
  7. package/dist/base/util/version.d.ts +1 -1
  8. package/dist/base/util/version.js +1 -1
  9. package/dist/domain/agent-memories/apply.js +2 -1
  10. package/dist/domain/agent-memories/claude-code.d.ts +4 -0
  11. package/dist/domain/agent-memories/claude-code.js +24 -1
  12. package/dist/domain/agent-memories/container-steps.js +19 -3
  13. package/dist/domain/agent-memories/folder-store.d.ts +1 -0
  14. package/dist/domain/agent-memories/handover.js +2 -2
  15. package/dist/domain/agent-memories/keys.d.ts +4 -2
  16. package/dist/domain/agent-memories/keys.js +6 -3
  17. package/dist/domain/agent-memories/legacy.js +15 -8
  18. package/dist/domain/agent-memories/markdown.d.ts +5 -0
  19. package/dist/domain/agent-memories/markdown.js +7 -2
  20. package/dist/domain/agent-memories/note-parts.d.ts +4 -0
  21. package/dist/domain/agent-memories/note-parts.js +232 -0
  22. package/dist/domain/agent-memories/plan.d.ts +9 -4
  23. package/dist/domain/agent-memories/plan.js +35 -15
  24. package/dist/domain/agent-memories/source.d.ts +5 -0
  25. package/dist/domain/agent-memories/source.js +12 -0
  26. package/dist/domain/agent-memories/sync.js +5 -1
  27. package/dist/domain/agent-memories/types.d.ts +5 -1
  28. package/dist/store/sqlite/entries/set-aside.d.ts +2 -2
  29. package/dist/store/sqlite/entries/set-aside.js +5 -3
  30. package/dist/surface/capture/compact.d.ts +1 -1
  31. package/dist/surface/capture/compact.js +1 -1
  32. package/dist/surface/cli/doctor.js +1 -0
  33. package/dist/surface/cli/hook-runtime.d.ts +3 -0
  34. package/dist/surface/cli/hook-runtime.js +13 -0
  35. package/dist/surface/cli/hook.js +3 -0
  36. package/dist/surface/cli/hooks/note-import-worker.d.ts +15 -0
  37. package/dist/surface/cli/hooks/note-import-worker.js +44 -0
  38. package/dist/surface/cli/hooks/note-written.d.ts +4 -0
  39. package/dist/surface/cli/hooks/note-written.js +41 -0
  40. package/dist/surface/cli/hooks/post-compact.js +9 -18
  41. package/dist/surface/cli/hooks/session-end.js +2 -14
  42. package/dist/surface/cli/init.js +3 -0
  43. package/dist/surface/cli/setup.js +2 -0
  44. package/dist/surface/cli/verbs/sessions.d.ts +2 -0
  45. package/dist/surface/cli/verbs/sessions.js +16 -2
  46. package/dist/surface/cli/verbs.d.ts +2 -0
  47. package/dist/surface/hooks-install/json-hooks.js +2 -2
  48. package/dist/surface/hooks-install/rules/claude-hooks.d.ts +3 -2
  49. package/dist/surface/hooks-install/rules/claude-hooks.js +25 -2
  50. package/dist/surface/hooks-install/rules/install-plan.js +1 -0
  51. package/dist/surface/hooks-install/rules/json-hooks.d.ts +4 -2
  52. package/dist/surface/hooks-install/rules/json-hooks.js +3 -2
  53. package/dist/surface/hooks-install/rules/shared.d.ts +3 -0
  54. package/dist/surface/hooks-install/rules/shared.js +5 -0
  55. package/extensions/openclaw-plugin/openclaw.plugin.json +1 -1
  56. package/extensions/openclaw-plugin/package.json +1 -1
  57. package/openclaw.plugin.json +1 -1
  58. package/package.json +1 -1
package/README.md CHANGED
@@ -135,7 +135,7 @@ You, your team and your platform lead read the same store.
135
135
 
136
136
  | Agent | What hippo adds |
137
137
  |---|---|
138
- | Claude Code | `CLAUDE.md` + 8 hooks |
138
+ | Claude Code | `CLAUDE.md` + 9 hooks |
139
139
  | Codex | `AGENTS.md` + 2 hooks |
140
140
  | Cursor | reads `AGENTS.md` |
141
141
  | Pi | reads `AGENTS.md` |
@@ -160,7 +160,7 @@ There's no team result yet, so [open an issue](https://github.com/kitfunso/hippo
160
160
 
161
161
  ## Setup in detail
162
162
 
163
- **Many repos at once.** Read what it changes first. `hippo init --scan <folder>` looks for git repos in the folder and up to three levels below it, skipping dot-folders and `node_modules`. Each repo gets a `.hippo/` store, seeded with lessons from the last 365 days of its commits and with its [agent memories](#agent-memories), and is added to the daily run's list. For the agents it finds, it installs the same user-level hooks as `hippo init`: 8 Claude Code hook entries in `~/.claude/settings.json` and the OpenCode plugin. It also sets up the daily 6:15am run, a crontab line on Linux and macOS or a scheduled task on Windows. It adds no block to any repo's `CLAUDE.md` or `AGENTS.md`. `--no-hooks`, `--no-schedule` and `--no-learn` leave out the hooks, the daily run and the history import.
163
+ **Many repos at once.** Read what it changes first. `hippo init --scan <folder>` looks for git repos in the folder and up to three levels below it, skipping dot-folders and `node_modules`. Each repo gets a `.hippo/` store, seeded with lessons from the last 365 days of its commits and with its [agent memories](#agent-memories), and is added to the daily run's list. For the agents it finds, it installs the same user-level hooks as `hippo init`: 9 Claude Code hook entries in `~/.claude/settings.json` and the OpenCode plugin. It also sets up the daily 6:15am run, a crontab line on Linux and macOS or a scheduled task on Windows. It adds no block to any repo's `CLAUDE.md` or `AGENTS.md`. `--no-hooks`, `--no-schedule` and `--no-learn` leave out the hooks, the daily run and the history import.
164
164
 
165
165
  ```bash
166
166
  hippo init --scan ~
@@ -191,7 +191,7 @@ Run `hippo init` inside one project. This is everything it writes, in the projec
191
191
 
192
192
  - **The project's store.** A `.hippo/` folder: SQLite plus markdown mirrors. On the first run in a git repo it learns lessons from the last 30 days of commits.
193
193
  - **Instruction files.** A block between `<!-- hippo:start -->` and `<!-- hippo:end -->` in the project's `CLAUDE.md` or `AGENTS.md`, only if that file already exists. Codex, Cursor, OpenClaw, OpenCode and Pi read `AGENTS.md`.
194
- - **Claude Code,** when the project has `CLAUDE.md` or `.claude/settings.json`: 8 hook entries in `~/.claude/settings.json`, one each on SessionEnd, UserPromptSubmit, PreCompact, PostCompact and PostToolUseFailure and three on SessionStart. [Framework Integrations](#framework-integrations) says what each one runs.
194
+ - **Claude Code,** when the project has `CLAUDE.md` or `.claude/settings.json`: 9 hook entries in `~/.claude/settings.json`, one each on SessionEnd, UserPromptSubmit, PreCompact, PostCompact, PostToolUseFailure and PostToolUse and three on SessionStart. [Framework Integrations](#framework-integrations) says what each one runs.
195
195
  - **OpenCode,** when the project has `.opencode/` or `opencode.json`: a plugin at `~/.config/opencode/plugins/hippo.ts`.
196
196
  - **Codex,** when the project has `AGENTS.md` or `.codex` and Codex is installed (`$CODEX_HOME`, else `~/.codex`, exists): 2 hook entries in Codex's `hooks.json`, one on UserPromptSubmit that sends your pinned memories plus up to 5 that match the prompt with every prompt and one on SessionStart after a compaction. **Codex runs them only after you trust them once in `/hooks`.** Init also prints `hippo hook install codex`, the opt-in that wraps the Codex launcher to capture sessions; `hippo hook uninstall codex` removes hippo's hooks and the wrapper.
197
197
  - **A daily run at 6:15am,** one per machine: a crontab line on Linux and macOS, a scheduled task named `hippo-daily-runner` on Windows. It runs `hippo learn --git --days 1` and then `hippo sleep` in every project listed in `~/.hippo/workspaces.json`, and init adds this project to that list.
@@ -857,7 +857,7 @@ The command runs with no shell, so each argument reaches the program as written.
857
857
  | `hippo decide "<decision>" --context "<why>"` | Include reasoning |
858
858
  | `hippo decide "<decision>" --supersedes <id>` | Supersede a previous decision |
859
859
  | `hippo hook list` | Show available framework hooks |
860
- | `hippo hook install <target>` | Install hook (claude-code also adds its 8 settings.json hook entries: session start and end, each prompt, compaction, failed tool calls) |
860
+ | `hippo hook install <target>` | Install hook (claude-code also adds its 9 settings.json hook entries: session start and end, each prompt, compaction, failed tool calls, memory notes) |
861
861
  | `hippo hook uninstall <target>` | Remove hook |
862
862
  | `hippo handoff create --summary "..."` | Create a session handoff |
863
863
  | `hippo handoff latest` | Show the most recent handoff |
@@ -887,7 +887,7 @@ The command runs with no shell, so each argument reaches the program as written.
887
887
 
888
888
  On `heartbeat`, `block`, `review` and `complete`, a given `--run` is checked against the card's live run and the command is refused, unchanged, if the two do not match.
889
889
 
890
- `HIPPO_READ_ONLY=1` uses a store without changing it, for example in the test phase of a benchmark. `hippo recall`, `hippo context`, the prompt hook and the MCP read tools give the same answers and write nothing: no recall counts, token-ledger rows, audit rows or mirror files, and a store with a WAL keeps its WAL. `remember`, `supersede`, `refine`, `outcome`, `resolve`, `decide`, `invalidate`, `forget`, `learn`, `promote`, `share` and `import`, and the MCP tools `hippo_remember`, `hippo_outcome`, `hippo_learn`, `hippo_resolve` and `hippo_share`, answer `read-only: not saved (HIPPO_READ_ONLY=1)` and save nothing (the CLI exits 1). `capture`, `capture-error`, `sleep`, `pre-compact`, `post-compact` and `session-end` log one line and do nothing, `hippo serve` does not start, and any other command that writes to the store fails with the store's own read-only error.
890
+ `HIPPO_READ_ONLY=1` uses a store without changing it, for example in the test phase of a benchmark. `hippo recall`, `hippo context`, the prompt hook and the MCP read tools give the same answers and write nothing: no recall counts, token-ledger rows, audit rows or mirror files, and a store with a WAL keeps its WAL. `remember`, `supersede`, `refine`, `outcome`, `resolve`, `decide`, `invalidate`, `forget`, `learn`, `promote`, `share` and `import`, and the MCP tools `hippo_remember`, `hippo_outcome`, `hippo_learn`, `hippo_resolve` and `hippo_share`, answer `read-only: not saved (HIPPO_READ_ONLY=1)` and save nothing (the CLI exits 1). `capture`, `capture-error`, `sleep`, `pre-compact`, `post-compact`, `note-written` and `session-end` log one line and do nothing, `hippo serve` does not start, and any other command that writes to the store fails with the store's own read-only error.
891
891
 
892
892
  ---
893
893
 
@@ -899,7 +899,7 @@ On `heartbeat`, `block`, `review` and `complete`, a given `--run` is checked aga
899
899
 
900
900
  | Framework | Detected by | Patches |
901
901
  |-----------|------------|---------|
902
- | Claude Code | `CLAUDE.md` or `.claude/settings.json` | `CLAUDE.md` + 8 hook entries in `~/.claude/settings.json` (listed below) |
902
+ | Claude Code | `CLAUDE.md` or `.claude/settings.json` | `CLAUDE.md` + 9 hook entries in `~/.claude/settings.json` (listed below) |
903
903
  | Codex | `AGENTS.md` or `.codex` | `AGENTS.md` + `UserPromptSubmit`/`SessionStart(compact)` hooks in Codex's `hooks.json` when Codex is installed (trust them once in `/hooks`); session capture is opt-in with `hippo hook install codex`, which wraps the Codex launcher |
904
904
  | Cursor | `AGENTS.md` | `AGENTS.md`, which Cursor reads from the project root |
905
905
  | OpenClaw | `.openclaw` or `AGENTS.md` | `AGENTS.md`; the native plugin is a separate install: `openclaw plugins install hippo-memory` |
@@ -915,7 +915,7 @@ Setup guides on the website: [Claude Code](https://hippo-memory.com/claude-code/
915
915
  If you prefer explicit control:
916
916
 
917
917
  ```bash
918
- hippo hook install claude-code # patches CLAUDE.md + adds the 8 settings.json hook entries listed below
918
+ hippo hook install claude-code # patches CLAUDE.md + adds the 9 settings.json hook entries listed below
919
919
  hippo hook install codex # patches AGENTS.md + adds hooks to Codex's hooks.json + wraps the detected Codex launcher
920
920
  hippo hook install cursor # patches AGENTS.md
921
921
  hippo hook install openclaw # patches AGENTS.md
@@ -930,7 +930,7 @@ This adds a `<!-- hippo:start -->` ... `<!-- hippo:end -->` block that tells the
930
930
 
931
931
  The block asks for nothing a hook already does, because each extra tool call re-reads the whole context. Re-running `hippo init` swaps a block an older hippo wrote for the current one, as long as nobody edited it. It leaves an edited block alone and says so, and never touches text outside the markers.
932
932
 
933
- For Claude Code, it also adds 8 hook entries to `~/.claude/settings.json`:
933
+ For Claude Code, it also adds 9 hook entries to `~/.claude/settings.json`:
934
934
  - a `SessionEnd` hook that runs `hippo sleep` and then `hippo capture` when the session exits. Capture matches the last 20 user and 10 assistant messages of the transcript against word patterns for decisions, rules, errors and preferences. It uses no model unless you turn on `capture.followUpRules` (see Conversation Capture). The patterns do not read earlier turns, so a correction older than that window becomes a pinned rule only with `hippo remember --pin` by hand. Capture also saves each message you typed whole, so recall still finds the older correction (see What you type).
935
935
  - a `SessionStart` hook that prints the previous session's consolidation log on stderr, where `claude --debug` shows it. When the last sleep failed or a compaction summary was set aside, it shows you one line that points to `hippo doctor`.
936
936
  - a second `SessionStart` hook that runs `hippo session-rules`, which prints the rules you taught under `## Rules from the user` and nothing else. It has no matcher, so a resumed or cleared session and a compaction get the rules again.
@@ -939,6 +939,7 @@ For Claude Code, it also adds 8 hook entries to `~/.claude/settings.json`:
939
939
  - a second `SessionStart` hook (matcher `compact`) that runs `hippo compact-resume`, printing that snapshot back into context right after compaction, if it is under 15 minutes old.
940
940
  - a `PostCompact` hook that runs `hippo post-compact`. It keeps the summary in the store with secrets scrubbed, and saves each item of that list as a memory that sleep never deletes: at most 10 per compaction, skipping an item an earlier compaction already saved and any item that looks like a secret. An item over 500 characters stays in the compaction's record only. It then prints one line, such as "Hippo saved 3 memories from this compaction and restored your task snapshot." If the store is busy, the summary waits in the store's `compactions-spool/` folder and `hippo sleep` finishes the save; `hippo doctor` names any compaction left unfinished for over 10 minutes. It also counts spool files that are waiting, stale (left by a replay that stopped) or set aside as `.bad`. The session that compacted does not have those memories injected back into its own prompts, since it just read them in the summary; `hippo recall` still finds them. The hook prints nothing when there is no store to save to.
941
941
  - a `PostToolUseFailure` hook that runs `hippo capture-error`, which stores a failed tool call as an error memory. It skips interrupts, declined permissions and searches that found nothing, and stores a repeated failure once. It also logs every failure, stored or not, for `hippo failures`: the session, the tool and hashes of the error, never its text. A hash is not anonymous, since anyone who guesses an error's text can check it against the hash. The log keeps 90 days.
942
+ - a `PostToolUse` hook that runs `hippo note-written` when Claude Code writes a memory note (a `.md` file in `projects/<name>/memory/`). A detached worker imports the notes within seconds and logs to `~/.hippo/logs/note-written.log`. An `if` filter keeps Claude Code from starting hippo for any other write.
942
943
 
943
944
  Only Claude Code saves memories at a compaction: hippo installs no `PreCompact` or `PostCompact` hook for Codex, Cursor, OpenCode, OpenClaw or Pi.
944
945
 
@@ -1,9 +1,10 @@
1
1
  import { type ImportReport } from '../base/memory/agent-memory-report.js';
2
2
  import { type SyncOptions } from '../domain/agent-memories/sync.js';
3
3
  export type { SyncOptions };
4
+ export { isClaudeMemoryNote } from '../domain/agent-memories/claude-code.js';
4
5
  /**
5
- * init, sleep, `import --agents` and the daily runner: a local store gets its project pass then the
6
- * user pass; the global store the user pass only.
6
+ * init, sleep and `import --agents`: a local store gets its project pass then the user pass; the
7
+ * global store the home folder's pass then the user pass.
7
8
  */
8
9
  export declare function importForStore(root: string, opts: SyncOptions): Promise<ImportReport>;
9
10
  /** A local store's project pass with legacy adoption; `init --scan` runs it per repository and
@@ -5,17 +5,33 @@ import { emptyReport, mergeReports, } from '../base/memory/agent-memory-report.j
5
5
  import { projectNames } from '../base/scope/project-identity.js';
6
6
  import { claudeTranscriptListing, transcriptNotesProject, } from '../domain/agent-memories/claude-code.js';
7
7
  import { runPass } from '../domain/agent-memories/sync.js';
8
+ export { isClaudeMemoryNote } from '../domain/agent-memories/claude-code.js';
8
9
  /**
9
- * init, sleep, `import --agents` and the daily runner: a local store gets its project pass then the
10
- * user pass; the global store the user pass only.
10
+ * init, sleep and `import --agents`: a local store gets its project pass then the user pass; the
11
+ * global store the home folder's pass then the user pass.
11
12
  */
12
13
  export async function importForStore(root, opts) {
13
- if (opts.machine.isGlobalRoot(root))
14
- return importUserMemories(root, opts);
15
- const report = await importProjectMemories(root, opts);
14
+ const report = opts.machine.isGlobalRoot(root)
15
+ ? await importHomeMemories(root, opts)
16
+ : await importProjectMemories(root, opts);
16
17
  mergeReports(report, await importUserMemories(root, opts));
17
18
  return report;
18
19
  }
20
+ /** The home folder's notes, user-global as a session at home files them, with legacy adoption and
21
+ * no handover: the global store is their own store. */
22
+ async function importHomeMemories(globalRoot, opts) {
23
+ const ctx = context(opts.machine, { projectRoot: opts.machine.home });
24
+ return runPass({
25
+ scope: 'project',
26
+ target: globalRoot,
27
+ invoking: globalRoot,
28
+ list: (a) => a.list(ctx, 'project'),
29
+ legacy: true,
30
+ originProject: '',
31
+ legacyOrigins: [],
32
+ handover: false,
33
+ }, opts);
34
+ }
19
35
  /** A local store's project pass with legacy adoption; `init --scan` runs it per repository and
20
36
  * the user pass once. */
21
37
  export async function importProjectMemories(root, opts) {
@@ -121,6 +121,7 @@ export function summaryLine(report) {
121
121
  total.untagged > 0
122
122
  ? `${plural(total.untagged, 'pinned memory', 'pinned memories')} kept with the note gone`
123
123
  : '',
124
+ total.duplicate > 0 ? `${total.duplicate} already stored` : '',
124
125
  total.secret > 0 ? `${total.secret} skipped for a secret` : '',
125
126
  total.rejected > 0 ? `${total.rejected} skipped as rejected` : '',
126
127
  ].filter((p) => p !== '');
@@ -32,9 +32,17 @@ export declare const DLQ_REDACTED_NOTE = "secret-shaped text redacted, signature
32
32
  * stays byte-identical so its signature still verifies.
33
33
  */
34
34
  export declare function redactPayload(raw: string): string;
35
+ /** Where a text's secret-shaped run starts and ends, as offsets into it. */
36
+ export interface SecretSpan {
37
+ readonly start: number;
38
+ readonly end: number;
39
+ }
35
40
  /**
36
41
  * Stricter redaction for text that leaves the machine: no co-occurrence guard, plus Bearer and
37
42
  * Basic auth headers and JWTs.
38
43
  */
39
44
  export declare function redactSecretsStrict(text: string): string;
45
+ /** The runs redactSecretsStrict would hide, found on the raw text, so a caller cutting the text can
46
+ * keep each run whole. */
47
+ export declare function secretSpans(text: string): SecretSpan[];
40
48
  //# sourceMappingURL=secret-detect.d.ts.map
@@ -126,19 +126,32 @@ const PEM_BEGIN = /-----BEGIN [A-Z ]*PRIVATE KEY-----/g;
126
126
  const PEM_END = /-----END [A-Z ]*PRIVATE KEY-----/g;
127
127
  /** Each PEM/OpenSSH block through its END line, or to the end of a truncated block; one forward
128
128
  * scan, so no ReDoS. */
129
- function redactPemBlocks(text) {
130
- let out = '';
131
- let from = 0;
129
+ function pemBlocks(text) {
130
+ const blocks = [];
132
131
  PEM_BEGIN.lastIndex = 0;
133
132
  for (let begin = PEM_BEGIN.exec(text); begin; begin = PEM_BEGIN.exec(text)) {
134
133
  PEM_END.lastIndex = PEM_BEGIN.lastIndex;
135
134
  const end = PEM_END.exec(text);
136
- out += `${text.slice(from, begin.index)}[REDACTED]`;
137
- from = end ? PEM_END.lastIndex : text.length;
138
- PEM_BEGIN.lastIndex = from;
135
+ const to = end ? PEM_END.lastIndex : text.length;
136
+ blocks.push({ start: begin.index, end: to });
137
+ PEM_BEGIN.lastIndex = to;
138
+ }
139
+ return blocks;
140
+ }
141
+ function redactPemBlocks(text) {
142
+ let out = '';
143
+ let from = 0;
144
+ for (const block of pemBlocks(text)) {
145
+ out += `${text.slice(from, block.start)}[REDACTED]`;
146
+ from = block.end;
139
147
  }
140
148
  return out + text.slice(from);
141
149
  }
150
+ // Global copies, so replace and matchAll see every match.
151
+ const STRICT_PATTERNS = [
152
+ ...SECRET_PATTERNS.map(({ re }) => new RegExp(re.source, re.flags.includes('g') ? re.flags : `${re.flags}g`)),
153
+ ...STRICT_ONLY_PATTERNS,
154
+ ];
142
155
  /**
143
156
  * Stricter redaction for text that leaves the machine: no co-occurrence guard, plus Bearer and
144
157
  * Basic auth headers and JWTs.
@@ -148,12 +161,19 @@ export function redactSecretsStrict(text) {
148
161
  return text;
149
162
  // PEM blocks first: SECRET_PATTERNS only matches the BEGIN line.
150
163
  let result = redactPemBlocks(text);
151
- for (const { re } of SECRET_PATTERNS) {
152
- const flags = re.flags.includes('g') ? re.flags : `${re.flags}g`;
153
- result = result.replace(new RegExp(re.source, flags), '[REDACTED]');
154
- }
155
- for (const re of STRICT_ONLY_PATTERNS)
164
+ for (const re of STRICT_PATTERNS)
156
165
  result = result.replace(re, '[REDACTED]');
157
166
  return result;
158
167
  }
168
+ /** The runs redactSecretsStrict would hide, found on the raw text, so a caller cutting the text can
169
+ * keep each run whole. */
170
+ export function secretSpans(text) {
171
+ const spans = pemBlocks(text);
172
+ for (const re of STRICT_PATTERNS) {
173
+ for (const m of text.matchAll(re)) {
174
+ spans.push({ start: m.index, end: m.index + m[0].length });
175
+ }
176
+ }
177
+ return spans;
178
+ }
159
179
  //# sourceMappingURL=secret-detect.js.map
@@ -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.8.0";
5
+ export declare const PACKAGE_VERSION = "3.9.0";
6
6
  /** The floor a store takes on its first expiring key: the first release with schema v53, set by
7
7
  * hand in that release; scripts/checks/check-expiring-keys-floor.mjs gates it. */
8
8
  export declare const EXPIRING_KEYS_MIN_BINARY = "1.64.0";
@@ -2,7 +2,7 @@
2
2
  * Single source of truth for the package version, written by scripts/sync-version.mjs; never
3
3
  * edit by hand. Read by the db rollback guard, /health, MCP. A constant, not a runtime
4
4
  * package.json read: the published bundle may lack package.json on a path ESM can resolve. */
5
- export const PACKAGE_VERSION = '3.8.0';
5
+ export const PACKAGE_VERSION = '3.9.0';
6
6
  /** The floor a store takes on its first expiring key: the first release with schema v53, set by
7
7
  * hand in that release; scripts/checks/check-expiring-keys-floor.mjs gates it. */
8
8
  export const EXPIRING_KEYS_MIN_BINARY = '1.64.0';
@@ -92,8 +92,9 @@ async function refusalsOf(s, items) {
92
92
  if (item.text.trim().length < MIN_ITEM_CHARS)
93
93
  out.set(item.key, 'short');
94
94
  // Imported rows reach prompts, so the bar is text leaving the machine: Bearer headers and JWTs count too.
95
- else if (redactSecretsStrict(item.text) !== item.text)
95
+ else if (item.flagged === true || redactSecretsStrict(item.text) !== item.text) {
96
96
  out.set(item.key, 'secret');
97
+ }
97
98
  else
98
99
  asked.push(item);
99
100
  }
@@ -11,6 +11,10 @@ export declare const claudeCodeAdapter: Adapter;
11
11
  * inside the hook's time limit.
12
12
  */
13
13
  export declare function claudeTranscriptListing(ctx: AdapterContext, transcriptPath: string): Listing;
14
+ /** Whether `file` is a note in Claude Code's auto memory: a `.md` directly in
15
+ * `<config>/projects/<name>/memory`, the MEMORY.md index left out. A hook runs this on every write,
16
+ * so it reads nothing but the paths. */
17
+ export declare function isClaudeMemoryNote(file: string, machine: Pick<AdapterContext, 'home' | 'env' | 'platform' | 'files'>): boolean;
14
18
  /** The project a session folder's notes belong to: the one Claude named the folder for, the
15
19
  * session's start folder, else cwd or a parent; null when none matches. */
16
20
  export declare function transcriptNotesProject(transcriptPath: string, cwd: string | null, machine: Pick<AdapterContext, 'platform' | 'env' | 'files' | 'projectIdentity'>): ProjectIdentity | null;
@@ -75,6 +75,25 @@ export function claudeTranscriptListing(ctx, transcriptPath) {
75
75
  warnings: [],
76
76
  };
77
77
  }
78
+ /** Whether `file` is a note in Claude Code's auto memory: a `.md` directly in
79
+ * `<config>/projects/<name>/memory`, the MEMORY.md index left out. A hook runs this on every write,
80
+ * so it reads nothing but the paths. */
81
+ export function isClaudeMemoryNote(file, machine) {
82
+ const fold = (name) => (machine.platform === 'win32' ? name.toLowerCase() : name);
83
+ const forms = (p) => [path.resolve(p), machine.files.realPath(p)].map(fold);
84
+ const projects = path.join(claudeConfigDir(machine.home, machine.env), 'projects');
85
+ return forms(projects).some((root) => forms(file).some((candidate) => {
86
+ const rel = path.relative(root, candidate);
87
+ if (rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel))
88
+ return false;
89
+ const [, folder, name, ...deeper] = rel.split(path.sep);
90
+ return (folder === 'memory' &&
91
+ name !== undefined &&
92
+ deeper.length === 0 &&
93
+ markdownNotes(name) &&
94
+ name !== fold('MEMORY.md'));
95
+ }));
96
+ }
78
97
  /** The project a session folder's notes belong to: the one Claude named the folder for, the
79
98
  * session's start folder, else cwd or a parent; null when none matches. */
80
99
  export function transcriptNotesProject(transcriptPath, cwd, machine) {
@@ -177,7 +196,11 @@ const NOTES = {
177
196
  const { yaml, body } = splitFrontmatter(text);
178
197
  if (yaml === null)
179
198
  return null;
180
- return { text: body.trim(), updatedAt: itemTime(frontmatterField(yaml, 'modified'), mtimeMs) };
199
+ const updatedAt = itemTime(frontmatterField(yaml, 'modified'), mtimeMs);
200
+ const title = frontmatterField(yaml, 'name');
201
+ return title === null
202
+ ? { text: body.trim(), updatedAt }
203
+ : { text: body.trim(), updatedAt, title };
181
204
  },
182
205
  };
183
206
  function readFolders(ctx, folders, scope) {
@@ -2,9 +2,10 @@
2
2
  // from the outcomes.
3
3
  import { Layer, createMemory } from '../../base/memory/entry.js';
4
4
  import { calculateStrength } from '../../base/memory/strength.js';
5
- import { itemSource, splitSource, storedText } from './source.js';
5
+ import { fileOfKey, itemSource, splitSource, storedText } from './source.js';
6
6
  export function planSteps(s, w, plan, rows) {
7
7
  const items = new Map(w.container.items.map((item) => [item.key, item]));
8
+ const notes = new Set(w.container.items.map((i) => fileOfKey(i.key)));
8
9
  const item = (key) => found(items.get(key), `planned key ${key} was not read`);
9
10
  const live = (id) => found(rows.live.get(id), `planned row ${id} was not in the lookup`);
10
11
  return [
@@ -12,7 +13,7 @@ export function planSteps(s, w, plan, rows) {
12
13
  ...plan.collapse.map(({ id, by }) => ({ kind: 'supersede', id, by })),
13
14
  ...plan.writes.map((write) => ({
14
15
  kind: 'write',
15
- entry: newRow(s, w, item(write.key)),
16
+ entry: withHistory(newRow(s, w, item(write.key)), (write.carry ?? []).map(live)),
16
17
  supersedes: write.supersedes,
17
18
  })),
18
19
  ...plan.restores.map(({ key, dormantId }) => ({
@@ -24,7 +25,9 @@ export function planSteps(s, w, plan, rows) {
24
25
  ...plan.setAside.map((id) => ({
25
26
  kind: 'setAside',
26
27
  id,
27
- why: items.has(splitSource(live(id).source, w.prefix).key) ? 'note-changed' : 'note-gone',
28
+ why: notes.has(fileOfKey(splitSource(live(id).source, w.prefix).key))
29
+ ? 'note-changed'
30
+ : 'note-gone',
28
31
  })),
29
32
  ];
30
33
  }
@@ -51,6 +54,19 @@ function newRow(s, w, item) {
51
54
  const origin = s.originProject === undefined ? {} : { originProject: s.originProject };
52
55
  return { ...base, created, validFrom: created, ...origin };
53
56
  }
57
+ /** A note that crossed the cap keeps the recall and outcome counts of the rows it replaces. */
58
+ function withHistory(entry, from) {
59
+ if (from.length === 0)
60
+ return entry;
61
+ const sum = (count) => from.reduce((total, row) => total + count(row), 0);
62
+ return {
63
+ ...entry,
64
+ retrievalCount: sum((r) => r.retrievalCount),
65
+ outcomePositive: sum((r) => r.outcomePositive),
66
+ outcomeNegative: sum((r) => r.outcomeNegative),
67
+ outcomeScore: from.find((r) => r.outcomeScore !== null)?.outcomeScore ?? null,
68
+ };
69
+ }
54
70
  /** The snapshot's row as if just recalled, carrying the tool's tag once. */
55
71
  function revived(s, w, snap) {
56
72
  const { now } = s;
@@ -9,6 +9,7 @@ export interface FolderRules {
9
9
  readonly item: (text: string, mtimeMs: number) => {
10
10
  readonly text: string;
11
11
  readonly updatedAt: number;
12
+ readonly title?: string;
12
13
  } | null;
13
14
  }
14
15
  /** Null when the folder is missing; a file that could not be read is `skipped`, so its row is
@@ -3,7 +3,7 @@ import { projectNames } from '../../base/scope/project-identity.js';
3
3
  import { liveUnder } from './container-view.js';
4
4
  import { namesFoldedInto } from './project-folds.js';
5
5
  import { toolReport } from '../../base/memory/agent-memory-report.js';
6
- import { containerId, containerPrefix, splitSource } from './source.js';
6
+ import { containerId, containerPrefix, fileOfKey, splitSource, } from './source.js';
7
7
  export async function handOver(synced, projectRoot, opts, report) {
8
8
  const globalRoot = opts.machine.globalRoot();
9
9
  if (synced.length === 0 || !opts.stores.exists(globalRoot))
@@ -58,7 +58,7 @@ async function handOverPlan(store, work, tenantId, prefixes) {
58
58
  for (const prefix of prefixes) {
59
59
  for (const row of await liveUnder(store, tenantId, prefix)) {
60
60
  rows.push(row);
61
- if (row.tags.includes(tag) && !unread.has(splitSource(row.source, prefix).key)) {
61
+ if (row.tags.includes(tag) && !unread.has(fileOfKey(splitSource(row.source, prefix).key))) {
62
62
  steps.push({ kind: 'setAside', id: row.id, why: 'handover' });
63
63
  }
64
64
  }
@@ -3,9 +3,11 @@ export declare function sha256Hex(text: string): string;
3
3
  * still seen. */
4
4
  export declare function itemHash(text: string): string;
5
5
  /** Keys for a single-file store's items: `<heading slug>/<12 hex of the text>`, `~2`, `~3` on
6
- * repeats. */
6
+ * repeats; a `seen` shared between calls counts the repeats across them. */
7
7
  export declare function textItemKeys(items: readonly {
8
8
  readonly headingSlug: string;
9
9
  readonly text: string;
10
- }[]): string[];
10
+ }[], seen?: Map<string, number>): string[];
11
+ /** A key's heading: all before its last `/`, so `<heading slug>/<12 hex>` gives the slug. */
12
+ export declare function headingOfKey(key: string): string;
11
13
  //# sourceMappingURL=keys.d.ts.map
@@ -11,9 +11,8 @@ export function itemHash(text) {
11
11
  return sha256Hex(text).slice(0, FINGERPRINT_HEX_CHARS);
12
12
  }
13
13
  /** Keys for a single-file store's items: `<heading slug>/<12 hex of the text>`, `~2`, `~3` on
14
- * repeats. */
15
- export function textItemKeys(items) {
16
- const seen = new Map();
14
+ * repeats; a `seen` shared between calls counts the repeats across them. */
15
+ export function textItemKeys(items, seen = new Map()) {
17
16
  return items.map(({ headingSlug, text }) => {
18
17
  const base = `${headingSlug}/${sha256Hex(text).slice(0, ID_SUFFIX_CHARS)}`;
19
18
  const n = (seen.get(base) ?? 0) + 1;
@@ -21,4 +20,8 @@ export function textItemKeys(items) {
21
20
  return n === 1 ? base : `${base}~${n}`;
22
21
  });
23
22
  }
23
+ /** A key's heading: all before its last `/`, so `<heading slug>/<12 hex>` gives the slug. */
24
+ export function headingOfKey(key) {
25
+ return key.slice(0, Math.max(0, key.lastIndexOf('/')));
26
+ }
24
27
  //# sourceMappingURL=keys.js.map
@@ -2,22 +2,28 @@
2
2
  // from.
3
3
  import path from 'node:path';
4
4
  import { duplicateKey } from '../../base/util/same-text.js';
5
- import { maskEmails } from '../../base/util/secret-detect.js';
5
+ import { maskEmails, redactSecretsStrict } from '../../base/util/secret-detect.js';
6
6
  import { liveUnder } from './container-view.js';
7
7
  import { matchLegacy } from './plan.js';
8
- import { MIN_ITEM_CHARS, storedText } from './source.js';
8
+ import { fileOfKey, isPartKey, MIN_ITEM_CHARS, storedText } from './source.js';
9
9
  export const LEGACY_SOURCE_PREFIX = 'claude-memory:';
10
10
  const LEGACY_TAG = 'claude-code-memory';
11
+ // A long note's old row goes to its first part that will be written, so a secret part is passed.
12
+ function noTarget(item) {
13
+ if (item.text.trim().length < MIN_ITEM_CHARS)
14
+ return true;
15
+ return (isPartKey(item.key) && (item.flagged === true || redactSecretsStrict(item.text) !== item.text));
16
+ }
11
17
  function legacyTargets(containers) {
12
18
  const refs = [];
13
19
  const targets = [];
14
20
  for (const container of containers) {
15
- for (const item of container.items) {
16
- if (item.text.trim().length < MIN_ITEM_CHARS)
17
- continue;
21
+ for (const item of container.items.filter((i) => !noTarget(i))) {
22
+ const note = fileOfKey(item.key);
18
23
  targets.push({
19
24
  ref: String(refs.length),
20
- file: path.posix.basename(item.key),
25
+ file: path.posix.basename(note),
26
+ note: `${container.path}\n${note}`,
21
27
  textKey: duplicateKey(storedText(item.text)),
22
28
  });
23
29
  refs.push({ dir: container.path, key: item.key });
@@ -64,8 +70,9 @@ export async function legacyWork(store, tenantId, listings) {
64
70
  };
65
71
  for (const [id, ref] of match.adopt)
66
72
  add('adopt', ref, id);
67
- for (const [ref, id] of match.replace)
68
- add('replace', ref, id);
73
+ for (const [ref, ids] of match.replace)
74
+ for (const id of ids)
75
+ add('replace', ref, id);
69
76
  return { byContainer, adopted: new Set(match.adopt.keys()) };
70
77
  }
71
78
  //# sourceMappingURL=legacy.js.map
@@ -11,4 +11,9 @@ export interface MarkdownItem {
11
11
  export declare function slugHeading(heading: string): string;
12
12
  /** Split markdown into memory items in file order; headings set context and are never items. */
13
13
  export declare function splitMarkdownItems(markdown: string): MarkdownItem[];
14
+ /** A heading line's text, or null for any other line. */
15
+ export declare function markdownHeading(line: string): string | null;
16
+ /** The backtick or tilde run a line opens a fence with, or null. */
17
+ export declare function fenceOf(line: string): string | null;
18
+ export declare function closesFence(line: string, fence: string): boolean;
14
19
  //# sourceMappingURL=markdown.d.ts.map
@@ -51,6 +51,10 @@ function isBlank(line) {
51
51
  function isIndented(line) {
52
52
  return line.startsWith(' ') || line.startsWith('\t');
53
53
  }
54
+ /** A heading line's text, or null for any other line. */
55
+ export function markdownHeading(line) {
56
+ return HEADING.test(line) ? headingText(line) : null;
57
+ }
54
58
  function headingText(line) {
55
59
  // A closing run of '#' counts only after a space, so `## C#` keeps its name.
56
60
  return line
@@ -63,11 +67,12 @@ function headingText(line) {
63
67
  function startsBlock(line) {
64
68
  return RULE.test(line) || HEADING.test(line) || BULLET.test(line);
65
69
  }
66
- function fenceOf(line) {
70
+ /** The backtick or tilde run a line opens a fence with, or null. */
71
+ export function fenceOf(line) {
67
72
  const match = FENCE.exec(line);
68
73
  return match === null ? null : (match[1] ?? match[2] ?? null);
69
74
  }
70
- function closesFence(line, fence) {
75
+ export function closesFence(line, fence) {
71
76
  const trimmed = line.trim();
72
77
  return trimmed.length >= fence.length && trimmed.replaceAll(fence[0], '') === '';
73
78
  }
@@ -0,0 +1,4 @@
1
+ import type { Container } from './types.js';
2
+ /** Each item over the cap replaced by its parts, in note order; other items stay as they are. */
3
+ export declare function splitContainer(container: Container): Container;
4
+ //# sourceMappingURL=note-parts.d.ts.map