hippo-memory 1.68.0 → 1.70.0

package/README.md

@@ -257,7 +257,7 @@ hippo handoff create \
   --summary "Finished schema migration, tests green" \
   --next "Wire handoff injection into context output" \
   --session sess_20260403 \
-  --artifact src/db.ts
+  --artifact src/db/index.ts
 
 hippo handoff latest              # show the most recent handoff
 hippo handoff show 3              # show a specific handoff by ID
@@ -577,7 +577,8 @@ read from the store the token ledger writes to: the project's local store when i
 else the global store. Each per-prompt hook call then records one event (session, turn
 number, whether the block was sent, reused, empty or disabled, counts and token totals) and
 one row per candidate memory: emitted, reused or rejected, with the stage and the
-reason it was dropped. With prompt recall on, recent memories dropped by the quality filter
+reason it was dropped. Each accepted `hippo pre-compact` and `hippo compact-resume` call
+records one event too, with no candidate rows. With prompt recall on, recent memories dropped by the quality filter
 are not recorded yet. It holds ids, hashes, counts and reasons only, never prompt or memory
 text; the prompt hash is unsalted, so a very short prompt can be guessed. A ledger failure prints one stderr line and never changes what the hook prints. Rows
 older than 90 days are pruned; at a heavy 300 prompts a day that is about 190 MB per store.
@@ -783,6 +784,8 @@ hippo watch "npm run build"
 | `hippo dashboard` | Open web dashboard at localhost:3333 (memory health by project, and the card board); open the printed URL, which carries a per-start access token |
 | `hippo dashboard --port <n>` | Use custom port |
 | `hippo mcp` | Start MCP server (stdio transport) |
+| `hippo serve` | Start the HTTP API server for this store on `127.0.0.1:6789` (`--port <n>` or `HIPPO_PORT`; `--host <host>`, which off loopback needs `HIPPO_REQUIRE_AUTH=1`) |
+| `hippo serve --tls-cert <file> --tls-key <file>` | Serve HTTPS with that PEM certificate and key (or set `HIPPO_TLS_CERT` and `HIPPO_TLS_KEY`). Without them a network bind still starts, and warns once that API keys and memory text travel in cleartext unless a TLS-terminating proxy sits in front |
 
 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.
 
@@ -844,7 +847,7 @@ For Codex, it adds two hooks to `$CODEX_HOME/hooks.json` (else `~/.codex/hooks.j
 
 **Codex runs a new or changed hook only after you trust it, so open `/hooks` in Codex once and trust both;** `hippo doctor` reminds you. The per-prompt hook was checked against a real Codex request; the compaction hook follows Codex's documented `compact` start source and has not been watched end to end in Codex. Each hook also carries a `commandWindows` form (`hippo.cmd ...`), because Codex runs hooks through PowerShell on Windows, where the execution policy can block npm's `hippo.ps1`. hippo only ever appends these two entries and never rewrites one, since Codex treats a changed command as a new hook to trust. To remove: `hippo hook uninstall codex`, which takes out only hippo's exact commands and leaves every other hook, including one of yours that runs hippo.
 
-For GitHub Copilot, once `$COPILOT_HOME` (else `~/.copilot`) exists, `hippo setup` writes hippo's own `hooks/hippo.json`, adds a `hippo` server to `mcp-config.json` and puts a block in `copilot-instructions.md` that asks the agent to call `hippo_recall` and `hippo_remember`. The Copilot CLI, including its sessions inside VS Code, uses all four hooks, the server and the block. VS Code's Local agent runs only the session-start hook and reads neither of the other files, so it gets no pre-compact snapshot or end-of-session capture yet, and its recall tools need hippo added to VS Code's own `mcp.json`. The hooks, that `mcp.json` recipe and how to remove it all: [integrations/copilot.md](integrations/copilot.md).
+For GitHub Copilot, when `$COPILOT_HOME` (else `~/.copilot`) or a VS Code User folder exists, `hippo setup` writes hippo's own `hooks/hippo.json`. When the Copilot folder was there before setup, it also adds a `hippo` server to `mcp-config.json` and a block to `copilot-instructions.md`. The block asks the agent to call `hippo_recall` and `hippo_remember`. The Copilot CLI, including its sessions inside VS Code, uses the session-start, tool-failure, pre-compact and session-end hooks, the server and the block. VS Code's agent mode (the Local agent, VS Code 1.109.3 or later) reads the same hooks file. It gets session start, the pre-compact snapshot and a capture after every reply. Setup also adds hippo to VS Code's own `mcp.json` and writes `prompts/hippo.instructions.md`, so its recall tools and instructions work too. The hooks, the VS Code files and how to remove them: [integrations/copilot.md](integrations/copilot.md).
 
 ### What the hook adds (Claude Code example)
 

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

@@ -1,7 +1,7 @@
-import type { DatabaseSyncLike } from '../db.js';
-import { type MemoryEntry } from '../memory.js';
+import { type DatabaseSyncLike } from '../db/index.js';
+import { type MemoryEntry } from '../core/memory.js';
 import { type Tally } from './report.js';
-import type { AgentMemoryTool } from './tools.js';
+import type { AgentMemoryTool } from '../core/agent-memory-tools.js';
 import type { Container } from './types.js';
 export declare const SYNC_ACTOR = "agent-memories";
 export interface StoreSession {

package/dist/agent-memories/apply.js

@@ -1,14 +1,15 @@
 // 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, replaceDormantEntry } 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 { appendAuditEvent } from '../store/audit.js';
+import { withTrialScope, withWriteScope } from '../db/index.js';
+import { deleteDormantRow, dormantSnapshotsBySourcePrefix, insertDormantRow, readDormantSnapshot, replaceDormantEntry } from '../store/dormant.js';
+import { gatedWrite } from '../trust/gated-write.js';
+import { Layer, calculateStrength, createMemory } from '../core/memory.js';
+import { findRejectedValue, rejectionDigest } from '../store/rejection.js';
+import { redactSecretsStrict } from '../util/secret-detect.js';
 import { stampOriginProject } from '../store/entry-row.js';
-import { deleteEntryRowInTx, setEntryTagsInTx } from '../store/entry-writes.js';
-import { selectLiveEntriesBySourcePrefix } from '../store/entry-reads.js';
-import { markSummaryDirtyInTx } from '../summary-dirty.js';
+import { deleteEntryRowInTx, renameEntrySourceAndOriginAt, renameEntrySourceAt, setEntryTagsInTx, supersedeEntryAt } from '../store/entry-writes.js';
+import { entryIdTakenAt, selectLiveEntriesBySourcePrefix } from '../store/entry-reads.js';
+import { markSummaryDirtyInTx } from '../store/summary-dirty.js';
 import { itemHash } from './keys.js';
 import { planContainer } from './plan.js';
 import { emptyTally } from './report.js';
@@ -16,20 +17,8 @@ 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;
-    }
+    const run = () => new ContainerRun(s, work).run();
+    return s.dryRun ? withTrialScope(s.db, 'sync_container', run) : withWriteScope(s.db, 'sync_container', run);
 }
 /** 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) {
@@ -110,8 +99,7 @@ class ContainerRun {
                 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)
+                if (renameEntrySourceAt(this.s.db, row.tenantId, row.id, row.source, source) === 0)
                     continue;
                 this.tally.adopted++;
                 this.mirror.push({ ...row, source });
@@ -124,8 +112,7 @@ class ContainerRun {
         let moved = 0;
         for (const row of selectLiveEntriesBySourcePrefix(this.s.db, this.s.tenantId, old)) {
             const source = this.w.prefix + row.source.slice(old.length);
-            const done = this.s.db.prepare(`UPDATE memories SET source = ?, origin_project = COALESCE(?, origin_project) WHERE id = ? AND tenant_id = ? AND source = ?`).run(source, origin, row.id, row.tenantId, row.source);
-            if (Number(done.changes ?? 0) === 0)
+            if (renameEntrySourceAndOriginAt(this.s.db, row.tenantId, row.id, { from: row.source, to: source, origin }) === 0)
                 continue;
             moved++;
             this.mirror.push({ ...row, source, origin_project: origin ?? row.origin_project });
@@ -178,9 +165,7 @@ class ContainerRun {
     }
     /** 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)
+        if (!supersedeEntryAt(this.s.db, old.tenantId, old.id, newId))
             return false;
         if (old.dag_parent_id)
             markSummaryDirtyInTx(this.s.db, old.dag_parent_id, old.tenantId, SYNC_ACTOR);
@@ -225,7 +210,7 @@ class ContainerRun {
     /** 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;
+        const taken = entryIdTakenAt(this.s.db, dormantId);
         if (snap === null || taken) {
             this.write({ key, hash: '', supersedes: [] });
             return;

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

@@ -1,7 +1,5 @@
-import { type ProjectIdentity } from '../project-identity.js';
+import { type ProjectIdentity } from '../core/project-identity.js';
 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. */

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

@@ -1,16 +1,20 @@
 // 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, resolveProjectIdentity } from '../project-identity.js';
-import { isStringValue } from '../capture-contract.js';
-import { claudeConfigDir, isJsonObject } from '../hooks/shared.js';
+import { resolveProjectIdentity } from '../core/project-identity.js';
+import { realpathOrResolve } from '../util/real-path.js';
+import { isStringValue } from '../core/capture-contract.js';
+import { claudeConfigDir } from '../hooks/shared.js';
 import { expandHome, frontmatterField, itemTime, readTextFile, splitFrontmatter } from './files.js';
 import { markdownNotes, readFolderStore, uniqueFolders } from './folder-store.js';
 import { gitLayout } from './git.js';
+import { isJsonObjectLiteral } from '../util/json.js';
+import { errorMessage } from '../util/log.js';
+const NAME_SLUG_MAX_CHARS = 200;
 // 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) {
+function claudeMemoryFolderNames(projectRoot, platform) {
     const roots = [projectRoot, realpathOrResolve(projectRoot)];
     const layout = gitLayout(projectRoot);
     if (layout)
@@ -34,7 +38,7 @@ export function claudeFolderName(root) {
     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)}`;
+    return `${name.slice(0, NAME_SLUG_MAX_CHARS)}-${Math.abs(hash).toString(36)}`;
 }
 export const claudeCodeAdapter = {
     tool: 'claude-code',
@@ -126,10 +130,10 @@ function autoMemoryDirectory(settings, home, warnings) {
         json = JSON.parse(file.text);
     }
     catch (err) {
-        warnings.push(`${settings}: ${err instanceof Error ? err.message : String(err)}`);
+        warnings.push(`${settings}: ${errorMessage(err)}`);
         return null;
     }
-    const value = isJsonObject(json) ? json.autoMemoryDirectory : undefined;
+    const value = isJsonObjectLiteral(json) ? json.autoMemoryDirectory : undefined;
     if (!isStringValue(value) || value === '')
         return null;
     const dir = expandHome(value, home);

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

@@ -1,3 +1,5 @@
-import type { Adapter } from './types.js';
+import type { Adapter, AdapterContext } from './types.js';
+/** VS Code's user-data resolution: portable install first, then the app-data override, then the platform default. */
+export declare function vscodeDataFolders(ctx: Pick<AdapterContext, 'env' | 'home' | 'platform'>): string[];
 export declare const copilotAdapter: Adapter;
 //# sourceMappingURL=copilot.d.ts.map

package/dist/agent-memories/copilot.js

@@ -4,10 +4,11 @@ import path from 'node:path';
 import { readTextFile } from './files.js';
 import { readFolderStore } from './folder-store.js';
 import { gitLayout } from './git.js';
+import { errorMessage } from '../util/log.js';
 const PRODUCTS = ['Code', 'Code - Insiders'];
 const MEMORY_TOOL = ['github.copilot-chat', 'memory-tool', 'memories'];
 /** VS Code's user-data resolution: portable install first, then the app-data override, then the platform default. */
-function dataFolders(ctx) {
+export function vscodeDataFolders(ctx) {
     const { env, home, platform } = ctx;
     if (env.VSCODE_PORTABLE)
         return [path.join(env.VSCODE_PORTABLE, 'user-data')];
@@ -48,7 +49,7 @@ function workspaceFolder(file, platform, warnings) {
         return fileUriToPath(json.folder, platform);
     }
     catch (err) {
-        warnings.push(`${file}: ${err instanceof Error ? err.message : String(err)}`);
+        warnings.push(`${file}: ${errorMessage(err)}`);
         return null;
     }
 }
@@ -85,7 +86,7 @@ function projectContainers(data, ctx, matches, warnings) {
         ids = fs.readdirSync(storage, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort();
     }
     catch (err) {
-        warnings.push(`${storage}: ${err instanceof Error ? err.message : String(err)}`);
+        warnings.push(`${storage}: ${errorMessage(err)}`);
         return [];
     }
     const found = [];
@@ -103,7 +104,7 @@ function projectContainers(data, ctx, matches, warnings) {
 export const copilotAdapter = {
     tool: 'copilot',
     list(ctx, scope) {
-        const data = dataFolders(ctx);
+        const data = vscodeDataFolders(ctx);
         const warnings = [];
         const found = [];
         if (scope === 'user') {

package/dist/agent-memories/files.js

@@ -1,6 +1,7 @@
 // Read-only file access shared by the adapters: size, binary and failure checks live in one place.
 import fs from 'node:fs';
 import path from 'node:path';
+import { errorMessage } from '../util/log.js';
 export const MAX_ITEM_BYTES = 256 * 1024;
 const MAX_DEPTH = 8;
 /** A file's text, or why it was skipped: empty, too big, holds a NUL byte (not text), or unreadable. */
@@ -20,7 +21,7 @@ export function readTextFile(file) {
         return { ok: true, text: buf.toString('utf8'), mtimeMs: stat.mtimeMs };
     }
     catch (err) {
-        return { ok: false, reason: `${file}: ${err instanceof Error ? err.message : String(err)}` };
+        return { ok: false, reason: `${file}: ${errorMessage(err)}` };
     }
 }
 /** Files in a folder as '/'-separated relative paths, sorted; dot entries skipped, symlinked folders not followed. */
@@ -35,7 +36,7 @@ export function listFiles(dir, opts) {
         return { status: 'ok', files: files.sort() };
     }
     catch (err) {
-        return { status: 'unreadable', reason: `${dir}: ${err instanceof Error ? err.message : String(err)}` };
+        return { status: 'unreadable', reason: `${dir}: ${errorMessage(err)}` };
     }
 }
 function walk(root, rel, depthLeft, out) {

package/dist/agent-memories/gemini.js

@@ -1,13 +1,14 @@
 // Gemini CLI: the "Gemini Added Memories" section of GEMINI.md, and the auto-memory folder that projects.json names.
 import fs from 'node:fs';
 import path from 'node:path';
-import { isStringValue } from '../capture-contract.js';
-import { isJsonObject } from '../hooks/shared.js';
+import { isStringValue } from '../core/capture-contract.js';
 import { readTextFile, splitFrontmatter } from './files.js';
 import { markdownNotes, readFolderStore } from './folder-store.js';
 import { gitLayout } from './git.js';
 import { textItemKeys } from './keys.js';
 import { splitMarkdownItems } from './markdown.js';
+import { isJsonObjectLiteral } from '../util/json.js';
+import { errorMessage } from '../util/log.js';
 const SECTION = 'gemini added memories';
 export const geminiAdapter = {
     tool: 'gemini',
@@ -58,7 +59,7 @@ function projectSlug(ctx, projectRoot, home, warnings) {
         projects = parseIndex(read.text);
     }
     catch (err) {
-        warnings.push(`${index}: ${err instanceof Error ? err.message : String(err)}`);
+        warnings.push(`${index}: ${errorMessage(err)}`);
         return null;
     }
     // The git top level is only asked for when the folder itself has no entry, since it spawns git.
@@ -74,8 +75,8 @@ function projectSlug(ctx, projectRoot, home, warnings) {
 function parseIndex(text) {
     // SAFETY: JSON.parse yields JSON; the object checks below decide what is used.
     const data = JSON.parse(text);
-    const projects = isJsonObject(data) ? data.projects : undefined;
-    if (!isJsonObject(projects))
+    const projects = isJsonObjectLiteral(data) ? data.projects : undefined;
+    if (!isJsonObjectLiteral(projects))
         throw new Error('expected { "projects": { "<absolute path>": "<slug>" } }');
     return projects;
 }

package/dist/agent-memories/keys.js

@@ -1,17 +1,18 @@
 // Hashes and keys for imported items, shared by the sync and the single-file adapters so they never drift apart.
 import { createHash } from 'node:crypto';
+import { FINGERPRINT_HEX_CHARS, ID_SUFFIX_CHARS } from '../util/token-text.js';
 export function sha256Hex(text) {
     return createHash('sha256').update(text.replace(/\r\n/g, '\n'), 'utf8').digest('hex');
 }
 /** The `#<hash>` part of a source: 16 hex of the full text, so an edit past the content cap is still seen. */
 export function itemHash(text) {
-    return sha256Hex(text).slice(0, 16);
+    return sha256Hex(text).slice(0, FINGERPRINT_HEX_CHARS);
 }
 /** Keys for a single-file store's items: `<heading slug>/<12 hex of the text>`, `~2`, `~3` on repeats. */
 export function textItemKeys(items) {
     const seen = new Map();
     return items.map(({ headingSlug, text }) => {
-        const base = `${headingSlug}/${sha256Hex(text).slice(0, 12)}`;
+        const base = `${headingSlug}/${sha256Hex(text).slice(0, ID_SUFFIX_CHARS)}`;
         const n = (seen.get(base) ?? 0) + 1;
         seen.set(base, n);
         return n === 1 ? base : `${base}~${n}`;

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

@@ -1,5 +1,5 @@
-import type { DatabaseSyncLike } from '../db.js';
-import type { MemoryEntry } from '../memory.js';
+import type { DatabaseSyncLike } from '../db/index.js';
+import type { MemoryEntry } from '../core/memory.js';
 import type { Listing } from './types.js';
 export declare const LEGACY_SOURCE_PREFIX = "claude-memory:";
 export interface ContainerLegacy {

package/dist/agent-memories/legacy.js

@@ -1,7 +1,7 @@
 // Rows the old Claude import wrote (`claude-memory:<file>`), taken over by the notes they came from (plan design 10).
 import path from 'node:path';
-import { duplicateKey } from '../same-text.js';
-import { maskEmails } from '../secret-detect.js';
+import { duplicateKey } from '../util/same-text.js';
+import { maskEmails } from '../util/secret-detect.js';
 import { selectLiveEntriesBySourcePrefix } from '../store/entry-reads.js';
 import { matchLegacy } from './plan.js';
 import { MIN_ITEM_CHARS, storedText } from './source.js';

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

@@ -1,4 +1,4 @@
-import { type ToolId } from './tools.js';
+import { type ToolId } from '../core/agent-memory-tools.js';
 import type { Scope } from './types.js';
 export interface Tally {
     imported: number;

package/dist/agent-memories/report.js

@@ -1,5 +1,5 @@
 // What a sync did, per tool, and the one line a command prints about it (plan design 11).
-import { AGENT_MEMORY_TOOLS } from './tools.js';
+import { AGENT_MEMORY_TOOLS } from '../core/agent-memory-tools.js';
 export function emptyTally() {
     return {
         imported: 0, replaced: 0, restored: 0, setAside: 0, untagged: 0, unchanged: 0, adopted: 0, renamed: 0, collapsed: 0, retagged: 0,

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

@@ -1,4 +1,4 @@
-import { type ToolId } from './tools.js';
+import { type ToolId } from '../core/agent-memory-tools.js';
 import type { Scope } from './types.js';
 export declare const CONTENT_CAP = 1500;
 export declare const MIN_ITEM_CHARS = 10;

package/dist/agent-memories/source.js

@@ -1,16 +1,17 @@
 // An imported row's source, `agent-memory:<tool>:<container>/<item>#<hash>`, and the stored text: plan design 3 and 4.
-import { realpathOrResolve } from '../project-identity.js';
-import { truncateCodePointSafe } from '../transcript-tail.js';
-import { maskEmails } from '../secret-detect.js';
+import { realpathOrResolve } from '../util/real-path.js';
+import { truncateCodePointSafe } from '../util/transcript-tail.js';
+import { maskEmails } from '../util/secret-detect.js';
 import { itemHash, sha256Hex } from './keys.js';
-import { toolSourcePrefix } from './tools.js';
+import { toolSourcePrefix } from '../core/agent-memory-tools.js';
+import { ID_SUFFIX_CHARS } from '../util/token-text.js';
 export const CONTENT_CAP = 1500;
 export const MIN_ITEM_CHARS = 10;
 /** `p-`/`u-` and 12 hex of the real path, so no user path reaches a row; `origin` parts projects sharing a folder in the global store. */
 export function containerId(dir, scope, platform, origin = '') {
     const real = realpathOrResolve(dir).replace(/\\/g, '/');
     const folder = platform === 'win32' ? real.toLowerCase() : real;
-    return `${scope === 'project' ? 'p' : 'u'}-${sha256Hex(origin === '' ? folder : `${folder}\n${origin}`).slice(0, 12)}`;
+    return `${scope === 'project' ? 'p' : 'u'}-${sha256Hex(origin === '' ? folder : `${folder}\n${origin}`).slice(0, ID_SUFFIX_CHARS)}`;
 }
 export function containerPrefix(tool, container) {
     return `${toolSourcePrefix(tool)}${container}/`;

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

@@ -1,5 +1,5 @@
 import { type ImportReport } from './report.js';
-import { type ToolId } from './tools.js';
+import { type ToolId } from '../core/agent-memory-tools.js';
 import type { Adapter } from './types.js';
 export declare const ADAPTERS: readonly Adapter[];
 /** Overrides config because `hippo init` creates the store in the same command that imports (plan design 11). */

package/dist/agent-memories/sync.js

@@ -1,20 +1,20 @@
 // Runs the adapters and routes each container to its store: the project pass, the user pass and their call sites (plan designs 2, 8, 11).
-import { processEnv } from '../env.js';
+import { processEnv } from '../util/env.js';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { errorMessage } from '../log.js';
-import { loadConfig } from '../config.js';
-import { closeHippoDb, isSqliteBusy, openHippoDb, outsideRequestStores } from '../db.js';
-import { namesFoldedInto } from '../project-merge.js';
-import { isGlobalStoreRoot, originInSql, projectNames, resolveGlobalRootDir, resolveProjectIdentity } from '../project-identity.js';
-import { duplicateKey, heldTextKeys } from '../same-text.js';
+import { errorMessage } from '../util/log.js';
+import { loadConfig } from '../core/config.js';
+import { closeHippoDb, isSqliteBusy, openHippoDb, outsideRequestStores, withWriteScope } from '../db/index.js';
+import { namesFoldedInto } from '../sharing/project-merge.js';
+import { isGlobalStoreRoot, projectNames, resolveGlobalRootDir, resolveProjectIdentity } from '../core/project-identity.js';
+import { duplicateKey, heldTextKeys } from '../util/same-text.js';
 import { removeEntryMirrors } from '../store/mirrors.js';
 import { initStore, isInitialized } from '../store/open.js';
 import { writeEntryMirrors } from '../store/entry-writes.js';
-import { selectLiveEntriesBySourcePrefix } from '../store/entry-reads.js';
+import { selectLiveEntriesBySourcePrefix, selectRowsOutsideSourcePrefixAt } from '../store/entry-reads.js';
 import { updateStats } from '../store/index-and-stats.js';
-import { resolveTenantId } from '../tenant.js';
+import { resolveTenantId } from '../store/tenant.js';
 import { setAsideRow, syncContainer } from './apply.js';
 import { claudeCodeAdapter, claudeTranscriptListing, transcriptNotesProject } from './claude-code.js';
 import { codexAdapter } from './codex.js';
@@ -25,7 +25,7 @@ import { openclawAdapter } from './openclaw.js';
 import { qwenCodeAdapter } from './qwen-code.js';
 import { addTally, emptyReport, mergeReports, toolReport } from './report.js';
 import { containerId, containerPrefix, splitSource } from './source.js';
-import { AGENT_MEMORY_SOURCE_PREFIX, AGENT_MEMORY_TOOLS, isToolId, toolSourcePrefix } from './tools.js';
+import { AGENT_MEMORY_SOURCE_PREFIX, AGENT_MEMORY_TOOLS, isToolId, toolSourcePrefix } from '../core/agent-memory-tools.js';
 export const ADAPTERS = [claudeCodeAdapter, codexAdapter, geminiAdapter, copilotAdapter, openclawAdapter, qwenCodeAdapter];
 /** Overrides config because `hippo init` creates the store in the same command that imports (plan design 11). */
 export const TOOLS_ENV = 'HIPPO_AGENT_MEMORY_TOOLS';
@@ -204,7 +204,7 @@ function syncStore(pass, listings, store, opts, report) {
                 out.tally.unreadable++;
                 continue;
             }
-            const work = containerWork(tool, container, opts.machine.platform, legacy, partition ?? '', earlier);
+            const work = containerWork(tool, container, { platform: opts.machine.platform, legacy, origin: partition ?? '', earlier });
             const outcome = syncOne(session, work, out, report);
             if (outcome === null)
                 continue;
@@ -214,7 +214,9 @@ function syncStore(pass, listings, store, opts, report) {
                 afterCommit(store.root, outcome, report);
         }
         if (session.dryRun)
-            out.unlisted += unlistedRows(store.db, tenantId, tool, pass.scope, listing, opts.machine.platform, partition === null ? null : [partition, ...earlier]);
+            out.unlisted += unlistedRows(store.db, tenantId, {
+                tool, scope: pass.scope, listing, platform: opts.machine.platform, partition: partition === null ? null : [partition, ...earlier],
+            });
     }
     if (remembered > 0 && !session.dryRun)
         bumpRemembered(store.root, remembered, report);
@@ -225,7 +227,8 @@ function earlierNames(db, tenantId, id, legacyOrigins) {
     const names = [id, ...legacyOrigins];
     return [...legacyOrigins, ...namesFoldedInto(db, tenantId, names)].filter((n) => n !== '' && n !== id);
 }
-function containerWork(tool, container, platform, legacy, origin, earlier) {
+function containerWork(tool, container, options) {
+    const { platform, legacy, origin, earlier } = options;
     const none = new Map();
     const own = tool.id === 'claude-code' ? legacy?.byContainer.get(container.path) : undefined;
     const prefixOf = (name) => containerPrefix(tool.id, containerId(container.path, container.scope, platform, name));
@@ -286,15 +289,11 @@ function duplicateCheck(store, tenantId, origins, adopted) {
     };
 }
 function otherPathKeys(store, tenantId, origins, adopted) {
-    const visible = store.global ? ` AND (origin_project = '' OR ${originInSql(origins)})` : '';
-    const params = store.global ? [tenantId, AGENT_MEMORY_SOURCE_PREFIX, ...origins] : [tenantId, AGENT_MEMORY_SOURCE_PREFIX];
-    // SAFETY: the SELECT names the three columns of the row type.
-    const rows = store.db.prepare(`SELECT id, content, source FROM memories
-      WHERE tenant_id = ? AND superseded_by IS NULL AND substr(source, 1, ${AGENT_MEMORY_SOURCE_PREFIX.length}) != ?${visible}`).all(...params);
+    const rows = selectRowsOutsideSourcePrefixAt(store.db, tenantId, AGENT_MEMORY_SOURCE_PREFIX, store.global ? origins : null);
     return new Set(rows.filter((r) => !adopted.has(r.id)).flatMap(heldTextKeys));
 }
-/** Dry run only: kept rows of this scope in containers this run did not list (a moved project's old folder); `partition` limits it to one project's names. */
-function unlistedRows(db, tenantId, tool, scope, listing, platform, partition) {
+function unlistedRows(db, tenantId, options) {
+    const { tool, scope, listing, platform, partition } = options;
     const listed = listing.containers.flatMap((c) => (partition ?? ['']).map((name) => containerPrefix(tool.id, containerId(c.path, c.scope, platform, name))));
     return selectLiveEntriesBySourcePrefix(db, tenantId, `${toolSourcePrefix(tool.id)}${scope === 'project' ? 'p' : 'u'}-`)
         .filter((row) => row.tags.includes(tool.tag) && !listed.some((p) => row.source.startsWith(p)))
@@ -314,7 +313,7 @@ function handOver(synced, projectRoot, opts, report) {
         const names = projectNames(resolveProjectIdentity(projectRoot));
         const origins = [...new Set([...names, ...namesFoldedInto(db, tenantId, names), ''])];
         for (const work of synced)
-            handOverContainer(db, globalRoot, tenantId, work, origins, opts.machine.platform, report);
+            handOverContainer(db, globalRoot, tenantId, work, { origins, platform: opts.machine.platform, report });
     }
     catch (err) {
         report.warnings.push(`global copies not handed over: ${isSqliteBusy(err) ? 'the global store was busy' : errorMessage(err)}`);
@@ -324,13 +323,13 @@ function handOver(synced, projectRoot, opts, report) {
             closeHippoDb(db);
     }
 }
-function handOverContainer(db, root, tenantId, work, origins, platform, report) {
+function handOverContainer(db, root, tenantId, work, options) {
+    const { origins, platform, report } = options;
     // A note the local pass could not read has no local row yet, so its global copy stays until it does.
     const unread = new Set(work.container.skipped);
     const mirror = [];
     const purge = [];
-    db.exec('BEGIN IMMEDIATE');
-    try {
+    withWriteScope(db, 'hand_over_container', () => {
         for (const origin of origins) {
             const prefix = containerPrefix(work.tool.id, containerId(work.container.path, work.container.scope, platform, origin));
             for (const row of selectLiveEntriesBySourcePrefix(db, tenantId, prefix)) {
@@ -343,15 +342,7 @@ function handOverContainer(db, root, tenantId, work, origins, platform, report)
                     purge.push(result.id);
             }
         }
-        db.exec('COMMIT');
-    }
-    catch (err) {
-        try {
-            db.exec('ROLLBACK');
-        }
-        catch { /* already rolled back; keep the original error */ }
-        throw err;
-    }
+    });
     toolReport(report, work.tool.id).tally.handedOver += mirror.length + purge.length;
     afterCommit(root, { mirror, purge }, report);
 }

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

@@ -1,4 +1,4 @@
-import type { ToolId } from './tools.js';
+import type { ToolId } from '../core/agent-memory-tools.js';
 export type Scope = 'project' | 'user';
 /** All an adapter may know about the machine; it reads nothing else from the process, so tests can fake it all. */
 export interface AdapterContext {

package/dist/api/assemble.d.ts

@@ -1,4 +1,4 @@
-import type { CallerProject } from '../prompt-hook.js';
+import type { CallerProject } from './prompt-hook.js';
 import type { Context } from './types.js';
 export declare const DEFAULT_ASSEMBLE_BUDGET = 4000;
 export interface AssembleOpts {
@@ -88,5 +88,5 @@ export interface AssembleResult {
  *   - no raws exist for the session
  *   - all rows fail the scope/tenant filter
  */
-export declare function assemble(ctx: Context, sessionId: string, opts?: AssembleOpts): AssembleResult;
+export declare function assemble(ctx: Context, sessionId: string, opts?: AssembleOpts): Promise<AssembleResult>;
 //# sourceMappingURL=assemble.d.ts.map