hippo-memory 1.52.9 → 1.53.1

package/README.md

@@ -22,6 +22,8 @@ npm install -g hippo-memory && hippo init
 
 Setting up every git repo under a folder in one go is a second step. The [Quick start](#quick-start) says what it changes, then gives the command.
 
+Package installation alone does not enable automatic preservation on every agent. Complete the documented setup and required host trust; capture and compaction coverage depend on the integration. See [automatic-save coverage](#does-installation-automatically-save-before-compaction).
+
 Having an AI agent install it? Point it at [llms-install.md](llms-install.md): it installs, wires hippo into the agents it finds, and verifies with `hippo doctor`.
 
 ```
@@ -83,7 +85,7 @@ npm install -g hippo-memory
 hippo init
 ```
 
-**Optional: 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 is added to the daily run's list. For the agents it finds, it installs the same user-level hooks as `hippo init`: 7 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.
+**Optional: 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`: 7 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.
 
 ```bash
 hippo init --scan ~
@@ -92,7 +94,7 @@ hippo init --scan ~
 After setup, `hippo sleep` runs when a Claude Code or OpenCode session ends, and in the daily 6:15am job for every project. Codex runs it at session end only if you installed its wrapper. It does five things:
 
 1. **Learns** from today's git commits
-2. **Imports** new entries from the project's Claude Code auto memory
+2. **Imports** what your coding agents remember, about this project and about you ([Agent memories](#agent-memories))
 3. **Consolidates** memories (decay, merge, prune)
 4. **Deduplicates** identical memories, keeping the stronger copy
 5. **Shares** high-value lessons to a global store so they surface in every project
@@ -118,7 +120,7 @@ Run `hippo init` inside one project. This is everything it writes, in the projec
 - **OpenCode,** when the project has `.opencode/` or `opencode.json`: a plugin at `~/.config/opencode/plugins/hippo.ts`.
 - **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 the five most recent ones 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.
 - **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.
-- **Claude Code auto memory.** On the first run, the notes with YAML front matter in this project's own folder under `~/.claude/projects/` are imported into its store. A file that looks like it holds a secret is skipped.
+- **Agent memories.** On every run, the notes your coding agents keep about this project go into its store, and the ones about you go into the global store. [Agent memories](#agent-memories) lists what is read.
 
 ```bash
 cd my-project
@@ -133,7 +135,28 @@ hippo init
 #    Scheduled machine-level daily runner (6:15am) via crontab
 ```
 
-To leave parts out: `--no-hooks` skips the instruction files and hooks, `--no-schedule` the daily run, and `--no-learn` the git history and auto memory import. `HIPPO_SKIP_AUTO_INTEGRATIONS=1` skips the same files and hooks that `--no-hooks` does.
+To leave parts out: `--no-hooks` skips the instruction files and hooks, `--no-schedule` the daily run, and `--no-learn` the git history and agent memory import. `HIPPO_SKIP_AUTO_INTEGRATIONS=1` skips the same files and hooks that `--no-hooks` does.
+
+### Agent memories
+
+Most coding agents now keep their own notes between sessions. Hippo reads them, whatever the tool, so what one agent learned reaches the others. It reads files only and never writes to another tool's folders.
+
+When: `hippo init` (every run), `init --scan`, `init --global`, `hippo setup`, every `hippo sleep` and the daily run. At session end a folder with its own store gets it through sleep; a folder without one sends its project's notes to the global store, marked with the project's name. After a Claude Code compaction, the session's own notes folder is read as well.
+
+What is read, per tool (each tool's own environment variables and settings decide where its home is):
+
+- **Claude Code:** the project's auto memory notes under `~/.claude/projects/<project>/memory/` (front matter required, `MEMORY.md` skipped), and the `autoMemoryDirectory` folder from your user settings.
+- **Codex:** the User Profile, preferences and tips in `~/.codex/memories/memory_summary.md`.
+- **Gemini CLI:** the "Gemini Added Memories" section of `~/.gemini/GEMINI.md`, and the project's auto memory folder when that feature is on.
+- **GitHub Copilot Chat in VS Code:** the memory tool's user memories and the repository memories of this project's workspace.
+- **OpenClaw:** the workspace's `MEMORY.md`.
+- **Qwen Code:** the project's auto memory folder and your user memories.
+
+Each imported memory follows its note. It stays while the note exists, is replaced when the note changes, and is set aside as dormant when the note is deleted (`hippo dormant` lists it and can restore it). A note shorter than 10 characters, one that looks like it holds a secret (an API key, a password, an auth header or a token), and one whose text you rejected with `hippo reject` are skipped. Email addresses are stored masked, and notes are cut at 1,500 characters.
+
+Not read: Windsurf (the file format is not documented, and Cascade reached end of life on 1 July 2026); Cursor, Copilot CLI and GitHub's Copilot Memory (the memories live on the vendor's servers); Kiro (the local store is not documented); Cline and Roo memory banks (files in the repository, which `hippo import --markdown` covers); Amp, Aider, Continue, OpenCode and pi (no memory feature found).
+
+`hippo import --agents` runs the import by hand; in a folder without a store it does what session end does there. With `--dry-run` it shows each tool's home, the folders found and what would change, and writes nothing. To choose tools, set `"agentMemories": { "tools": ["claude-code", "codex"] }` in `.hippo/config.json` (`[]` turns the import off), or `HIPPO_AGENT_MEMORY_TOOLS=claude-code,codex` in the environment (`none` turns it off), which wins over config.
 
 ---
 
@@ -508,8 +531,9 @@ detector flags is deleted, never kept dormant, and a dormant memory nobody resto
 `dormant.retentionDays` (default 180, `0` keeps them forever) is deleted for good. Rejecting
 a value (`hippo reject`) removes its dormant copies too. To delete faded memories straight
 away as before, set `{"dormant":{"enabled":false}}` in `.hippo/config.json`. Sleep never
-removes pinned memories or raw receipts (Slack, GitHub, vault imports) either way, and
-duplicate removal and junk cleanup still delete.
+removes pinned memories, raw receipts (Slack, GitHub, vault imports) or the memories a
+Claude Code compaction saved either way, and duplicate removal and junk cleanup still
+delete other memories. `hippo forget` still deletes a compaction memory.
 
 **See what memory costs in tokens.** Every block of memory text hippo hands an agent (the
 per-prompt hook, the block `hippo compact-resume` restores after compaction, `hippo context`,
@@ -734,7 +758,7 @@ On `heartbeat`, `block`, `review` and `complete`, a given `--run` is checked aga
 | OpenCode | `.opencode/` or `opencode.json` | `AGENTS.md` + TS plugin at `~/.config/opencode/plugins/hippo.ts` (subscribes to `session.idle` + `session.created`) |
 | Pi | `.pi` or `.pi/agent` | `AGENTS.md`; copy the [Pi extension](https://github.com/kitfunso/hippo-memory/tree/master/extensions/pi-extension) for session hooks |
 
-Init patches an instruction file only if it already exists. It also sets up a daily run and imports the project's Claude Code auto memory; [What hippo init changes](#what-hippo-init-changes) lists everything.
+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.
 
 ### Manual install
 
@@ -760,11 +784,13 @@ For Claude Code, it also adds 7 hook entries to `~/.claude/settings.json`:
 - a `SessionEnd` hook that runs `hippo sleep` and then `hippo capture` when the session exits. Capture matches the last 20 user and 10 assistant messages of the transcript against word patterns for decisions, rules, errors and preferences. It uses no model and does not read earlier turns, so record lessons with `hippo remember` as you go.
 - a `SessionStart` hook that prints the previous session's consolidation output
 - a `UserPromptSubmit` hook that runs `hippo context --pinned-only --include-recent 5 --format additional-context` every turn. It re-injects pinned memories (`hippo remember <text> --pin`) plus the 5 newest memories in the store, so fresh same-session lessons appear on the next prompt before you pin them. It does not read your prompt unless you set `{"pinnedInject":{"promptRecall":true}}`, which swaps the 5 newest for memories that match the prompt. The block is rendered without live strength percentages, so it stays byte-identical while its memories do not change, and it is sent only when it changed since the session's last prompt: an unchanged block is skipped, resent every 10 skips (`pinnedInject.refreshTurns`, `0` never resends) and resent after compaction. `{"pinnedInject":{"skipUnchanged":false}}` sends it every turn as before. Opt out entirely with `{"pinnedInject":{"enabled":false}}` in `.hippo/config.json`.
-- a `PreCompact` hook that runs `hippo pre-compact` before the transcript gets summarized. It saves a working-state snapshot (task/summary/next step) so mid-session compaction can't drop it; the `SessionEnd` hook still owns extracting durable memories.
+- a `PreCompact` hook that runs `hippo pre-compact` before the transcript gets summarized. It records the compaction in the store, saves a working-state snapshot (task/summary/next step) so mid-session compaction can't drop it, and asks the summariser to end its summary with a "Memories for hippo" list: the lessons, decisions and corrections from the session that should outlive it. The `SessionEnd` hook still owns extracting durable memories from the transcript.
 - 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.
-- a `PostCompact` hook that runs `hippo post-compact`, which tells you what was saved ("Hippo saved your task snapshot before compacting."). It prints nothing when nothing was saved.
+- 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. 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.
 - 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.
 
+Only Claude Code saves memories at a compaction: hippo installs no `PreCompact` or `PostCompact` hook for Codex, Cursor, OpenCode, OpenClaw or Pi.
+
 To remove: `hippo hook uninstall claude-code`
 
 For Codex, it adds two hooks to `$CODEX_HOME/hooks.json` (else `~/.codex/hooks.json`) and keeps every hook already there:
@@ -885,7 +911,7 @@ The rows from where the data lives to the graph were checked against each tool's
 | Feature | Hippo | [MemPalace](https://github.com/milla-jovovich/mempalace) | [Mem0](https://github.com/mem0ai/mem0) | [Basic Memory](https://github.com/basicmachines-co/basic-memory) | [gbrain](https://hermesatlas.com/projects/garrytan/gbrain) | [Zep](https://www.getzep.com/) | [Letta](https://github.com/letta-ai/letta-code) | [Cognee](https://www.cognee.ai/) | [Memoria](https://github.com/matrixorigin/Memoria) | [EverMind](https://evermind.ai/) |
 |---------|-------|-----------|------|-------------|--------|-----|-------|--------|---------|----------|
 | Where your data lives | Your machine or your server (SQLite) | Your machine (ChromaDB by default) | Where you run it, or Mem0's cloud | Your machine (Markdown files); cloud optional | Your machine (PGLite) or your Postgres | Zep's cloud (your own cloud on Enterprise) | Your machine; cloud backup with /login | Your machine by default; Cognee Cloud optional | Memoria Cloud, or self-hosted (Docker or embedded) | Your machine by default; EverOS Cloud optional |
-| Managed multi-user service | No (self-hosted, with tenants and API keys; the commercial edition adds hosted SaaS) | ? | Yes (hosted platform) | Yes (Teams) | ? (self-hosted server with OAuth) | Yes (Zep Cloud) | ? (cloud backup with /login) | Yes (Cognee Cloud) | ? (Memoria Cloud) | Yes (EverOS Cloud) |
+| Managed multi-user service | No (self-hosted, with tenants and API keys; hosted SaaS is planned for the commercial edition) | ? | Yes (hosted platform) | Yes (Teams) | ? (self-hosted server with OAuth) | Yes (Zep Cloud) | ? (cloud backup with /login) | Yes (Cognee Cloud) | ? (Memoria Cloud) | Yes (EverOS Cloud) |
 | Needs an account or model key | No | No (core path) | Yes (model key; account for the platform) | No (account for the cloud) | No (keyless mode) | Yes (Zep account; Graphiti needs a model key) | Yes (your own model keys) | No (local) | ? (account for Memoria Cloud) | Yes (an LLM key, OpenRouter) |
 | License | MIT | MIT | Apache-2.0 | AGPL-3.0 | MIT | Proprietary cloud (Graphiti: Apache-2.0) | Apache-2.0 | Apache-2.0 | Apache-2.0 | Apache-2.0 (EverOS) + cloud |
 | Runtime | Node.js 22.16+, no runtime deps | Python 3.9+ (ChromaDB by default) | Python or Node.js (server: Postgres + pgvector) | Python (SQLite by default) | Bun (PGLite or Postgres + pgvector) | Managed service (Graphiti: Python + a graph database) | Node.js (npm) | Python (graph and vector stores, or Postgres) | A CLI binary + a MatrixOne database | Python (SQLite + LanceDB) |
@@ -1030,7 +1056,7 @@ node run.mjs --adapter all
 
 ### How do I give Claude Code memory between sessions?
 
-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 7 hook entries to Claude Code's settings that keep your pinned memories plus the five most recent ones in context, save a task snapshot before compaction, store failed tool calls as lessons, and run `hippo sleep` when the session ends, and it sets up a daily 6:15am run. [What hippo init changes](#what-hippo-init-changes) lists everything. 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. To set up every git repo up to three folders below your home directory at once, know what the scan changes first: each repo gets its own store, seeded from a year of its git history, the same hooks go in when one of those repos uses Claude Code, and the daily run is set up, but no block goes into any repo's `CLAUDE.md`. The command is `hippo init --scan ~`; run `hippo init` in the projects where you want the block.
+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 7 hook entries to Claude Code's settings that keep your pinned memories plus the five most recent ones in context, save a task snapshot and the memories a compaction summary lists, store failed tool calls as lessons, and run `hippo sleep` when the session ends, and it sets up a daily 6:15am run. [What hippo init changes](#what-hippo-init-changes) lists everything. 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. To set up every git repo up to three folders below your home directory at once, know what the scan changes first: each repo gets its own store, seeded from a year of its git history, the same hooks go in when one of those repos uses Claude Code, and the daily run is set up, but no block goes into any repo's `CLAUDE.md`. The command is `hippo init --scan ~`; run `hippo init` in the projects where you want the block.
 
 ### How do I give Cursor memory between sessions?
 
@@ -1044,6 +1070,14 @@ Run `npm install -g hippo-memory`, then `hippo init` in the project. If the proj
 
 `hippo init` detects Claude Code, Codex, Cursor, OpenClaw, OpenCode and Pi. It installs hooks for Claude Code and OpenCode, adds 2 hooks to Codex's `hooks.json` when Codex is installed (Codex runs them once you trust them in `/hooks`), and adds instructions to an existing `AGENTS.md` for Codex, Cursor, OpenClaw and Pi. It only patches instruction files that already exist. Any MCP client can use the [MCP server](#mcp-server), and other tools can call the CLI or the HTTP API that `hippo serve` starts.
 
+### Does installation automatically save before compaction?
+
+Package installation alone does not enable automatic preservation on every agent. Complete the documented setup and required host trust; capture and compaction coverage depend on the integration.
+
+With the Claude Code hooks or native plugin configured, PreCompact saves a derivable working-state snapshot and a compaction record; PostCompact extracts the lessons listed in the compaction summary. A snapshot, a compaction record and a useful memory are different outputs, and post-compaction extraction is not a guarantee that every earlier lesson was saved before loss. Hippo's Codex hooks currently provide prompt delivery and post-compaction re-injection, with one-time trust in `/hooks`; they install no PreCompact save hook. Codex session-end capture requires the opt-in wrapper. MCP tool access and instruction files alone do not provide automatic lifecycle capture.
+
+Follow the [integration recipes](https://github.com/kitfunso/hippo-memory/tree/master/integrations) for the exact agent and mode. Automatic pre-loss preservation across all supported agents is planned under AZ4-AZ6 in the [roadmap](https://github.com/kitfunso/hippo-memory/blob/master/ROADMAP.md#current-execution-index); it is not a universal install-only capability today.
+
 ### Can I use hippo as an MCP memory server?
 
 Yes. `hippo mcp` runs the server over stdio, and `npx -y hippo-memory mcp` runs it without a global install. Add it to the MCP config of Claude Desktop, Cursor, Windsurf (now Devin Desktop), Cline or any other client (example [above](#mcp-server)); in Claude Code, run `claude mcp add hippo-memory -- hippo mcp`. The agent gets tools such as `hippo_recall`, `hippo_remember` and `hippo_outcome`.
@@ -1101,9 +1135,9 @@ The interesting problems:
 
 ## Open source and commercial
 
-Hippo is open core, and the line is drawn by who pays. Everything an individual developer or a self-hosted team needs is in this repository under MIT: the CLI, the MCP server, hooks, connectors, the dashboard, tenants, API keys, roles, per-key scope grants, the audit log and zero-touch memory. Code published here stays MIT and stays here.
+Hippo is open core. This repository provides the MIT core for individual developers and self-hosted teams: the CLI, the MCP server, supported hooks and adapters, connectors, the dashboard, tenants, API keys, admin/member roles, per-key scope grants and the audit log. Automatic capture and delivery depend on the configured integration; the all-agent low-touch acceptance work remains planned. Code published here stays MIT and stays here.
 
-A commercial edition for larger companies ships as a separate package under a commercial licence from KITFUNSO LTD. It adds SSO (OIDC and SAML sign-in), SCIM, an org admin view, the pilot report and telemetry join, SIEM export of the audit log, offline licence keys, hosted SaaS, and support with an SLA. Pull requests for those features belong there, not here; see [CONTRIBUTING.md](CONTRIBUTING.md).
+The commercial edition is planned; its private repository is a scaffold, not a released enterprise product. It is intended for larger companies as a separate package under a commercial licence from KITFUNSO LTD. Planned capabilities include SSO (OIDC and SAML sign-in), SCIM, organisation/team/project policy, an org admin view, the pilot report and telemetry join, SIEM export of the audit log, offline licence keys, hosted SaaS, and support with an SLA. Pull requests implementing those commercial features belong there; see [CONTRIBUTING.md](CONTRIBUTING.md). Release availability and independently verified benefit are separate milestones in the [roadmap](https://github.com/kitfunso/hippo-memory/blob/master/ROADMAP.md#current-execution-index).
 
 ## License
 

package/dist/agent-memories/apply.d.ts

@@ -0,0 +1,47 @@
+import type { DatabaseSyncLike } from '../db.js';
+import { type MemoryEntry } from '../memory.js';
+import { type Tally } from './report.js';
+import type { AgentMemoryTool } from './tools.js';
+import type { Container } from './types.js';
+export declare const SYNC_ACTOR = "agent-memories";
+export interface StoreSession {
+    readonly db: DatabaseSyncLike;
+    readonly hippoRoot: string;
+    readonly tenantId: string;
+    readonly baseHalfLifeDays: number;
+    /** Stamped on written rows; undefined lets the store stamp its own project. */
+    readonly originProject: string | undefined;
+    /** Whether the text is already stored live by another path, as seen where the new row goes. */
+    readonly isDuplicate: (text: string) => boolean;
+    readonly dryRun: boolean;
+}
+export interface ContainerWork {
+    readonly tool: AgentMemoryTool;
+    readonly container: Container;
+    /** `containerPrefix(tool, containerId)`: every row of the container has a source starting with it. */
+    readonly prefix: string;
+    /** Legacy rows that take an item's key as they are, by key (plan design 10, first round). */
+    readonly adopt: ReadonlyMap<string, readonly MemoryEntry[]>;
+    /** Legacy rows a new row of the key supersedes, by key (second round). */
+    readonly replace: ReadonlyMap<string, readonly MemoryEntry[]>;
+}
+export interface ContainerOutcome {
+    readonly tally: Tally;
+    /** Rows to mirror after commit, as they now stand. */
+    readonly mirror: readonly MemoryEntry[];
+    /** Rows set aside, whose mirrors are purged after commit. */
+    readonly purge: readonly string[];
+}
+/** Throws SQLITE_BUSY when another writer holds the store past its busy timeout; nothing is written then. */
+export declare function syncContainer(s: StoreSession, work: ContainerWork): ContainerOutcome;
+export type SetAsideWhy = 'note-gone' | 'note-changed' | 'handover';
+export type SetAsideResult = {
+    readonly kind: 'untagged';
+    readonly entry: MemoryEntry;
+} | {
+    readonly kind: 'dormant';
+    readonly id: string;
+};
+/** Design 6's set-aside on the caller's transaction: a pinned row only loses the tag, any other goes dormant, restorable. */
+export declare function setAsideRow(db: DatabaseSyncLike, tag: string, row: MemoryEntry, why: SetAsideWhy): SetAsideResult;
+//# sourceMappingURL=apply.d.ts.map

package/dist/agent-memories/apply.js

@@ -0,0 +1,253 @@
+// One container's sync in one transaction on the caller's handle: lookup, plan, then every write (plan designs 6 to 8).
+import { appendAuditEvent } from '../audit.js';
+import { deleteDormantRow, dormantSnapshotsBySourcePrefix, insertDormantRow, readDormantSnapshot } from '../dormant.js';
+import { gatedWrite } from '../gated-write.js';
+import { Layer, calculateStrength, createMemory } from '../memory.js';
+import { findRejectedValue, rejectionDigest } from '../rejection.js';
+import { redactSecretsStrict } from '../secret-detect.js';
+import { deleteEntryRowInTx, markSummaryDirtyInTx, selectLiveEntriesBySourcePrefix, setEntryTagsInTx, stampOriginProject } from '../store.js';
+import { itemHash } from './keys.js';
+import { planContainer } from './plan.js';
+import { emptyTally } from './report.js';
+import { MIN_ITEM_CHARS, itemSource, splitSource, storedText } from './source.js';
+export const SYNC_ACTOR = 'agent-memories';
+/** Throws SQLITE_BUSY when another writer holds the store past its busy timeout; nothing is written then. */
+export function syncContainer(s, work) {
+    // A dry run takes no lock up front and rolls every write back.
+    s.db.exec(s.dryRun ? 'BEGIN' : 'BEGIN IMMEDIATE');
+    try {
+        const out = new ContainerRun(s, work).run();
+        s.db.exec(s.dryRun ? 'ROLLBACK' : 'COMMIT');
+        return out;
+    }
+    catch (err) {
+        try {
+            s.db.exec('ROLLBACK');
+        }
+        catch { /* already rolled back; keep the original error */ }
+        throw err;
+    }
+}
+/** Design 6's set-aside on the caller's transaction: a pinned row only loses the tag, any other goes dormant, restorable. */
+export function setAsideRow(db, tag, row, why) {
+    const untagged = { ...row, tags: row.tags.filter((t) => t !== tag) };
+    const audit = (metadata) => appendAuditEvent(db, { tenantId: row.tenantId, actor: SYNC_ACTOR, op: 'agent_memory_set_aside', targetId: row.id, metadata });
+    if (row.pinned) {
+        setEntryTagsInTx(db, untagged);
+        audit({ why, untagged: true });
+        return { kind: 'untagged', entry: untagged };
+    }
+    const now = new Date();
+    // Sleep's dormant move skips kept rows, so the steps are written out here without its filter.
+    insertDormantRow(db, { entry: untagged, strength: calculateStrength(row, now), reason: 'source-deleted', dormantAt: now.toISOString() });
+    deleteEntryRowInTx(db, row, SYNC_ACTOR);
+    audit({ why });
+    return { kind: 'dormant', id: row.id };
+}
+class ContainerRun {
+    s;
+    w;
+    tally = emptyTally();
+    mirror = [];
+    purge = [];
+    rows = new Map();
+    items = new Map();
+    tag;
+    constructor(s, w) {
+        this.s = s;
+        this.w = w;
+        this.tag = w.tool.tag;
+        for (const item of w.container.items)
+            this.items.set(item.key, item);
+    }
+    run() {
+        this.adoptLegacy();
+        const live = selectLiveEntriesBySourcePrefix(this.s.db, this.s.tenantId, this.w.prefix);
+        for (const row of [...live, ...[...this.w.replace.values()].flat()])
+            this.rows.set(row.id, row);
+        const refusals = this.refusals();
+        const liveRows = live.map((row) => this.liveRow(row));
+        const plan = planContainer({
+            textKeyed: this.w.container.textKeyed,
+            items: this.w.container.items.map((item) => ({ key: item.key, hash: itemHash(item.text), refused: refusals.has(item.key) })),
+            skipped: this.w.container.skipped,
+            live: liveRows,
+            dormant: this.dormantRows(new Set(liveRows.map((r) => r.key)), refusals),
+            legacy: new Map([...this.w.replace].map(([key, rows]) => [key, rows.map((r) => r.id)])),
+            isDuplicate: (item) => this.s.isDuplicate(storedText(this.item(item.key).text)),
+        });
+        for (const reason of refusals.values())
+            this.tally[reason]++;
+        this.tally.unread += this.w.container.skipped.length;
+        this.apply(plan);
+        return { tally: this.tally, mirror: this.mirror, purge: this.purge };
+    }
+    apply(plan) {
+        this.tally.unchanged += plan.unchanged;
+        this.tally.duplicate += plan.duplicates;
+        for (const id of plan.retag)
+            this.retag(this.row(id));
+        for (const { id, by } of plan.collapse)
+            if (this.supersede(this.row(id), by))
+                this.tally.collapsed++;
+        for (const write of plan.writes)
+            this.write(write);
+        for (const { key, dormantId } of plan.restores)
+            this.restore(key, dormantId);
+        for (const id of plan.setAside)
+            this.setAside(this.row(id));
+    }
+    /** Same text as a current note: the legacy row takes the note's key, keeping its id, recall count and outcomes. */
+    adoptLegacy() {
+        for (const [key, rows] of this.w.adopt) {
+            const item = this.items.get(key);
+            if (item === undefined)
+                continue;
+            const source = itemSource(this.w.prefix, key, item.text);
+            for (const row of rows) {
+                const moved = this.s.db.prepare(`UPDATE memories SET source = ? WHERE id = ? AND tenant_id = ? AND source = ? AND superseded_by IS NULL`).run(source, row.id, row.tenantId, row.source);
+                if (Number(moved.changes ?? 0) === 0)
+                    continue;
+                this.tally.adopted++;
+                this.mirror.push({ ...row, source });
+            }
+        }
+    }
+    refusals() {
+        const out = new Map();
+        for (const item of this.w.container.items) {
+            const reason = this.refusal(item);
+            if (reason !== null)
+                out.set(item.key, reason);
+        }
+        return out;
+    }
+    // The rejection lookup reads the capped text, as the write would store it, so a rejected note writes no audit row.
+    refusal(item) {
+        if (item.text.trim().length < MIN_ITEM_CHARS)
+            return 'short';
+        // Imported rows reach prompts, so the bar is text leaving the machine: Bearer headers and JWTs count too.
+        if (redactSecretsStrict(item.text) !== item.text)
+            return 'secret';
+        if (findRejectedValue(this.s.db, this.s.tenantId, rejectionDigest(storedText(item.text))) !== null)
+            return 'rejected';
+        return null;
+    }
+    liveRow(row) {
+        return { id: row.id, ...splitSource(row.source, this.w.prefix), tagged: row.tags.includes(this.tag), created: row.created };
+    }
+    /** Read only when a present key has no live row, which after the first import is rare. */
+    dormantRows(liveKeys, refusals) {
+        const needed = this.w.container.items.some((item) => !refusals.has(item.key) && !liveKeys.has(item.key));
+        if (!needed)
+            return [];
+        return dormantSnapshotsBySourcePrefix(this.s.db, this.s.tenantId, this.w.prefix)
+            .filter((snap) => !snap.entry.superseded_by)
+            .map((snap) => ({ id: snap.entry.id, ...splitSource(snap.entry.source, this.w.prefix), dormantAt: snap.dormantAt }));
+    }
+    retag(row) {
+        const tagged = { ...row, tags: [...row.tags, this.tag] };
+        setEntryTagsInTx(this.s.db, tagged);
+        this.tally.retagged++;
+        this.mirror.push(tagged);
+    }
+    /** api.supersede's steps on this transaction; false when another writer superseded the row first. */
+    supersede(old, newId) {
+        const result = this.s.db.prepare(`UPDATE memories SET superseded_by = ? WHERE id = ? AND tenant_id = ? AND superseded_by IS NULL`)
+            .run(newId, old.id, old.tenantId);
+        if (Number(result.changes ?? 0) === 0)
+            return false;
+        if (old.dag_parent_id)
+            markSummaryDirtyInTx(this.s.db, old.dag_parent_id, old.tenantId, SYNC_ACTOR);
+        appendAuditEvent(this.s.db, { tenantId: old.tenantId, actor: SYNC_ACTOR, op: 'supersede', targetId: old.id, metadata: { newId } });
+        this.mirror.push({ ...old, superseded_by: newId });
+        return true;
+    }
+    write(planned) {
+        const entry = this.newRow(this.item(planned.key));
+        if (!this.gated(entry))
+            return;
+        this.tally[planned.supersedes.length > 0 ? 'replaced' : 'imported']++;
+        for (const id of planned.supersedes)
+            this.supersede(this.row(id), entry.id);
+    }
+    newRow(item) {
+        const base = createMemory(storedText(item.text), {
+            layer: Layer.Episodic,
+            tags: [this.tag],
+            source: itemSource(this.w.prefix, item.key, item.text),
+            confidence: 'observed',
+            kind: 'distilled',
+            tenantId: this.s.tenantId,
+            baseHalfLifeDays: this.s.baseHalfLifeDays,
+        });
+        // The note's own time when it is earlier than now; the loader reads any form but toISOString as drift.
+        const created = Number.isFinite(item.updatedAt)
+            ? new Date(Math.min(item.updatedAt, Date.parse(base.created))).toISOString()
+            : base.created;
+        const origin = this.s.originProject === undefined ? {} : { origin_project: this.s.originProject };
+        return stampOriginProject(this.s.hippoRoot, { ...base, created, valid_from: created, ...origin });
+    }
+    gated(entry) {
+        const result = gatedWrite(this.s.db, this.s.hippoRoot, entry, { actor: SYNC_ACTOR, worthCheck: false });
+        if (result === 'written') {
+            this.mirror.push(entry);
+            return true;
+        }
+        this.tally[result === 'skipped:rejected' ? 'rejected' : 'secret']++;
+        return false;
+    }
+    /** A deleted note came back unchanged: its old row returns with its id and history, under the sync's own audit op. */
+    restore(key, dormantId) {
+        const snap = readDormantSnapshot(this.s.db, this.s.tenantId, dormantId);
+        const taken = this.s.db.prepare(`SELECT 1 FROM memories WHERE id = ?`).get(dormantId) !== undefined;
+        if (snap === null || taken) {
+            this.write({ key, hash: '', supersedes: [] });
+            return;
+        }
+        const now = new Date();
+        const tags = Array.isArray(snap.entry.tags) ? snap.entry.tags.filter((t) => t !== this.tag) : [];
+        const revived = {
+            ...createMemory('dormant snapshot defaults', { baseHalfLifeDays: this.s.baseHalfLifeDays }),
+            ...snap.entry,
+            tags: [...tags, this.tag],
+            last_retrieved: now.toISOString(),
+        };
+        if (!this.gated(stampOriginProject(this.s.hippoRoot, { ...revived, strength: calculateStrength(revived, now) })))
+            return;
+        deleteDormantRow(this.s.db, this.s.tenantId, dormantId);
+        appendAuditEvent(this.s.db, {
+            tenantId: this.s.tenantId,
+            actor: SYNC_ACTOR,
+            op: 'agent_memory_restore',
+            targetId: dormantId,
+            metadata: { reason: snap.reason, dormantAt: snap.dormantAt },
+        });
+        this.tally.restored++;
+    }
+    setAside(row) {
+        const why = this.items.has(splitSource(row.source, this.w.prefix).key) ? 'note-changed' : 'note-gone';
+        const result = setAsideRow(this.s.db, this.tag, row, why);
+        if (result.kind === 'untagged') {
+            this.tally.untagged++;
+            this.mirror.push(result.entry);
+        }
+        else {
+            this.tally.setAside++;
+            this.purge.push(result.id);
+        }
+    }
+    row(id) {
+        const row = this.rows.get(id);
+        if (row === undefined)
+            throw new Error(`agent memory sync: planned row ${id} was not in the lookup`);
+        return row;
+    }
+    item(key) {
+        const item = this.items.get(key);
+        if (item === undefined)
+            throw new Error(`agent memory sync: planned key ${key} was not read`);
+        return item;
+    }
+}
+//# sourceMappingURL=apply.js.map

package/dist/agent-memories/claude-code.d.ts

@@ -0,0 +1,11 @@
+import type { Adapter, AdapterContext, Listing } from './types.js';
+/** Claude Code's auto memory folder names for a project: its checkout, which subfolders share, or the folder itself outside a repository. */
+export declare function claudeMemoryFolderNames(projectRoot: string, platform: NodeJS.Platform): Set<string>;
+/** Claude Code's rule: a linked worktree shares its main checkout's folder, or the git folder's when that sits outside a checkout (a bare repository, or --separate-git-dir); any other checkout, a submodule included, keeps its own. */
+export declare function claudeCheckoutRoot(top: string, gitDir: string, common: string): string;
+/** Claude Code's folder name for a path: non-alphanumerics made '-', and a name over 200 characters cut to 200 plus a base-36 hash of the whole path. */
+export declare function claudeFolderName(root: string): string;
+export declare const claudeCodeAdapter: Adapter;
+/** Post-compact's read: the session's own notes folder and nothing else, so no git call runs inside the hook's time limit. */
+export declare function claudeTranscriptListing(ctx: AdapterContext, transcriptPath: string): Listing;
+//# sourceMappingURL=claude-code.d.ts.map

package/dist/agent-memories/claude-code.js

@@ -0,0 +1,113 @@
+// Claude Code's auto memory: frontmatter `.md` notes in a per-project folder, plus the `autoMemoryDirectory` user folder.
+import fs from 'node:fs';
+import path from 'node:path';
+import { realpathOrResolve } from '../project-identity.js';
+import { isStringValue } from '../capture.js';
+import { isJsonObject } from '../hooks.js';
+import { expandHome, frontmatterField, itemTime, readTextFile, splitFrontmatter } from './files.js';
+import { markdownNotes, readFolderStore, uniqueFolders } from './folder-store.js';
+import { gitLayout } from './git.js';
+// Keeps a pinned name from carrying a separator or `..` out of the projects folder.
+const PROJECT_DIR_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+/** Claude Code's auto memory folder names for a project: its checkout, which subfolders share, or the folder itself outside a repository. */
+export function claudeMemoryFolderNames(projectRoot, platform) {
+    const roots = [projectRoot, realpathOrResolve(projectRoot)];
+    const layout = gitLayout(projectRoot);
+    if (layout)
+        roots.push(claudeCheckoutRoot(layout.top, layout.gitDir, layout.common));
+    return new Set(roots.map((root) => (platform === 'win32' ? claudeFolderName(root).toLowerCase() : claudeFolderName(root))));
+}
+/** Claude Code's rule: a linked worktree shares its main checkout's folder, or the git folder's when that sits outside a checkout (a bare repository, or --separate-git-dir); any other checkout, a submodule included, keeps its own. */
+export function claudeCheckoutRoot(top, gitDir, common) {
+    if (gitDir === common)
+        return top;
+    if (path.basename(common) === '.git')
+        return path.dirname(common);
+    return fs.existsSync(path.join(common, '.git')) ? top : common;
+}
+/** Claude Code's folder name for a path: non-alphanumerics made '-', and a name over 200 characters cut to 200 plus a base-36 hash of the whole path. */
+export function claudeFolderName(root) {
+    const full = path.resolve(root);
+    const name = full.replace(/[^a-zA-Z0-9]/g, '-');
+    if (name.length <= 200)
+        return name;
+    let hash = 0;
+    for (let i = 0; i < full.length; i++)
+        hash = ((hash << 5) - hash + full.charCodeAt(i)) | 0;
+    return `${name.slice(0, 200)}-${Math.abs(hash).toString(36)}`;
+}
+export const claudeCodeAdapter = {
+    tool: 'claude-code',
+    list(ctx, scope) {
+        const config = ctx.env.CLAUDE_CONFIG_DIR || path.join(ctx.home, '.claude');
+        const warnings = [];
+        const folders = scope === 'project' ? projectFolders(ctx, config) : userFolders(ctx, config, warnings);
+        return { tool: 'claude-code', home: config, containers: readFolders(folders, scope, ctx.platform), warnings };
+    },
+};
+/** Post-compact's read: the session's own notes folder and nothing else, so no git call runs inside the hook's time limit. */
+export function claudeTranscriptListing(ctx, transcriptPath) {
+    const config = ctx.env.CLAUDE_CONFIG_DIR || path.join(ctx.home, '.claude');
+    const folder = path.join(path.dirname(transcriptPath), 'memory');
+    return { tool: 'claude-code', home: config, containers: readFolders([folder], 'project', ctx.platform), warnings: [] };
+}
+function projectFolders(ctx, config) {
+    const projects = path.join(config, 'projects');
+    const names = ctx.projectRoot === undefined ? [] : [...claudeMemoryFolderNames(ctx.projectRoot, ctx.platform)];
+    const pinned = ctx.env.CLAUDE_CODE_PROJECT_DIR_NAME;
+    // Claude reads the pinned name only alongside a pinned config folder.
+    if (ctx.env.CLAUDE_CONFIG_DIR && pinned !== undefined && PROJECT_DIR_NAME.test(pinned))
+        names.push(pinned);
+    const folders = names.map((name) => path.join(projects, name, 'memory'));
+    if (ctx.transcriptPath)
+        folders.push(path.join(path.dirname(ctx.transcriptPath), 'memory'));
+    return folders;
+}
+function userFolders(ctx, config, warnings) {
+    const dir = autoMemoryDirectory(path.join(config, 'settings.json'), ctx.home, warnings);
+    return dir === null ? [] : [dir];
+}
+// User settings only: a cloned repository's own settings must not point the import at another project's notes.
+function autoMemoryDirectory(settings, home, warnings) {
+    if (!fs.existsSync(settings))
+        return null;
+    const file = readTextFile(settings);
+    if (!file.ok) {
+        warnings.push(file.reason);
+        return null;
+    }
+    let json;
+    try {
+        // SAFETY: JSON.parse yields JSON; the object and string checks below decide what is used.
+        json = JSON.parse(file.text);
+    }
+    catch (err) {
+        warnings.push(`${settings}: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    const value = isJsonObject(json) ? json.autoMemoryDirectory : undefined;
+    if (!isStringValue(value) || value === '')
+        return null;
+    const dir = expandHome(value, home);
+    if (path.isAbsolute(dir))
+        return dir;
+    warnings.push(`${settings}: autoMemoryDirectory "${value}" is not absolute or under ~/, so it is ignored`);
+    return null;
+}
+// Claude counts a note only when it carries frontmatter; `modified` there beats the file time.
+const NOTES = {
+    recursive: false,
+    include: markdownNotes,
+    item(text, mtimeMs) {
+        const { yaml, body } = splitFrontmatter(text);
+        if (yaml === null)
+            return null;
+        return { text: body.trim(), updatedAt: itemTime(frontmatterField(yaml, 'modified'), mtimeMs) };
+    },
+};
+function readFolders(folders, scope, platform) {
+    return uniqueFolders(folders, platform)
+        .map((dir) => readFolderStore(dir, scope, NOTES))
+        .filter((c) => c !== null);
+}
+//# sourceMappingURL=claude-code.js.map

package/dist/agent-memories/codex.d.ts

@@ -0,0 +1,3 @@
+import type { Adapter } from './types.js';
+export declare const codexAdapter: Adapter;
+//# sourceMappingURL=codex.d.ts.map

package/dist/agent-memories/codex.js

@@ -0,0 +1,47 @@
+// Codex CLI's memory_summary.md, the one memory file Codex puts in its prompt, read as a single text-keyed file.
+import fs from 'node:fs';
+import path from 'node:path';
+import { codexHomeDir } from '../hooks.js';
+import { readTextFile } from './files.js';
+import { textItemKeys } from './keys.js';
+import { splitMarkdownItems } from './markdown.js';
+// "What's in Memory" only indexes MEMORY.md, so it is left out.
+const KEPT_HEADINGS = new Set(['user profile', 'user preferences', 'general tips']);
+const PROFILE_HEADING = /^##[ \t]+User Profile[ \t]*$/im;
+export const codexAdapter = {
+    tool: 'codex',
+    list(ctx, scope) {
+        const home = codexHomeDir(ctx.home, ctx.env);
+        const containers = [];
+        if (scope === 'user') {
+            const container = readSummary(path.join(home, 'memories', 'memory_summary.md'));
+            if (container !== null)
+                containers.push(container);
+        }
+        return { tool: 'codex', home, containers, warnings: [] };
+    },
+};
+function readSummary(file) {
+    if (!fs.existsSync(file))
+        return null;
+    const read = readTextFile(file);
+    if (!read.ok)
+        return unreadable(file, read.reason);
+    if (!isCodexSummary(read.text)) {
+        return unreadable(file, `${file}: not a Codex memory summary (needs "v1" first and a "## User Profile" heading)`);
+    }
+    const kept = splitMarkdownItems(read.text)
+        .filter((item) => KEPT_HEADINGS.has(item.heading.trim().toLowerCase()))
+        .map((item) => ({ headingSlug: item.headingSlug, text: `${item.heading}: ${item.text}` }));
+    const keys = textItemKeys(kept);
+    const items = kept.map(({ text }, i) => ({ key: keys[i], text, updatedAt: read.mtimeMs }));
+    return { scope: 'user', path: file, readable: true, items, skipped: [], warnings: [], textKeyed: true };
+}
+function isCodexSummary(text) {
+    const first = text.split(/\r?\n/).find((line) => line.trim() !== '');
+    return first?.trim() === 'v1' && PROFILE_HEADING.test(text);
+}
+function unreadable(file, warning) {
+    return { scope: 'user', path: file, readable: false, items: [], skipped: [], warnings: [warning], textKeyed: true };
+}
+//# sourceMappingURL=codex.js.map