hippo-memory 1.68.0 → 1.69.0

package/dist/hooks/copilot.js

@@ -1,10 +1,11 @@
-// GitHub Copilot: hippo's hooks file, one MCP server key and an instructions block, all under the Copilot home folder.
+// GitHub Copilot: hippo's hooks file, one MCP server key and an instructions block under the Copilot home folder,
+// plus the MCP server and an instructions file in each VS Code User folder.
 import * as fs from 'fs';
 import * as path from 'path';
 import { isDeepStrictEqual } from 'node:util';
 import { readJsonFile } from '../json.js';
 import { HOOK_MARKERS, hippoBlock } from '../cli/hook-blocks.js';
-import { copilotHomeDir, isJsonObject } from './shared.js';
+import { copilotHomeDir, isJsonObject, vscodeUserDirs } from './shared.js';
 import { installJsonHooks, resolveJsonHookPaths, uninstallJsonHooks, writeSettingsFile } from './json-hooks.js';
 const MCP_KEY = 'hippo';
 /** Copilot drops what a per-prompt hook prints, so per-task recall goes through the MCP tool the block names. */
@@ -19,32 +20,75 @@ reason, a user preference, why something failed), call the \`hippo_remember\`
 tool right then, while you work, never as a closing step. Set \`error\` to true
 for a failure. Leave out secrets and personal details.
 
+The installed hooks load pinned memories when a session starts and capture
+the session as you work, so there is nothing to run before you finish.
+`.trim();
+/** Every Copilot text a release has written, so install upgrades an old block and uninstall still removes it; add the old text when the text changes. */
+const SHIPPED_COPILOT_INSTRUCTIONS = [
+    COPILOT_INSTRUCTIONS,
+    `
+## Project Memory (Hippo)
+
+At the start of each task, call the \`hippo_recall\` tool with a short query that
+names the task. Read the memories it returns before you write any code.
+
+When you learn something that should outlive this session (a decision and its
+reason, a user preference, why something failed), call the \`hippo_remember\`
+tool right then, while you work, never as a closing step. Set \`error\` to true
+for a failure. Leave out secrets and personal details.
+
 The installed hooks load pinned memories when a session starts, store failed
 tool calls and capture the session when it ends, so there is nothing to run
 before you finish.
-`.trim();
+`.trim(),
+];
+/** VS Code attaches a User `*.instructions.md` file to every chat request its `applyTo` glob matches. */
+const withApplyToAll = (text) => `---\napplyTo: "**"\n---\n${text}\n`;
+export const VSCODE_INSTRUCTIONS = withApplyToAll(COPILOT_INSTRUCTIONS);
+function isHipposVscodeInstructions(text) {
+    return SHIPPED_COPILOT_INSTRUCTIONS.some((shipped) => text === withApplyToAll(shipped));
+}
+function profileDirs(userDir) {
+    const dir = path.join(userDir, 'profiles');
+    if (!fs.existsSync(dir))
+        return [];
+    return fs.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => path.join(dir, e.name)).sort();
+}
 export function copilotPaths() {
     const home = copilotHomeDir();
     return {
         hooks: resolveJsonHookPaths('copilot').settings,
         mcpConfig: path.join(home, 'mcp-config.json'),
         instructions: path.join(home, 'copilot-instructions.md'),
+        vscode: vscodeUserDirs().map((userDir) => ({
+            userDir,
+            mcpConfig: path.join(userDir, 'mcp.json'),
+            instructions: path.join(userDir, 'prompts', 'hippo.instructions.md'),
+            profiles: profileDirs(userDir),
+        })),
     };
 }
 /** Windows gets npm's .cmd shim, as the Codex hooks do, since a PowerShell execution policy can block hippo.ps1. */
-function hippoMcpServer() {
-    return { type: 'local', command: process.platform === 'win32' ? 'hippo.cmd' : 'hippo', args: ['mcp'], env: {}, tools: ['*'] };
+function hippoCommand() {
+    return process.platform === 'win32' ? 'hippo.cmd' : 'hippo';
 }
-/** Only a server hippo wrote counts as hippo's: a user's own "hippo" key with another command or args is never touched. */
-function isHipposServer(entry) {
-    return isJsonObject(entry) && (entry.command === 'hippo' || entry.command === 'hippo.cmd') && isDeepStrictEqual(entry.args, ['mcp']);
+/** The Copilot CLI's mcp-config.json keeps servers under "mcpServers", each with an env and a tool list. */
+export const COPILOT_CLI_MCP = { key: 'mcpServers', server: () => ({ type: 'local', command: hippoCommand(), args: ['mcp'], env: {}, tools: ['*'] }) };
+/** VS Code's mcp.json keeps stdio servers under "servers"; it has no "mcpServers" key. */
+export const VSCODE_MCP = { key: 'servers', server: () => ({ type: 'stdio', command: hippoCommand(), args: ['mcp'] }) };
+/** Only a server hippo wrote counts as hippo's: another command, other args, or any key or value setup does not write (an env you added) makes it the user's. */
+function isHipposServer(entry, host) {
+    if (!isJsonObject(entry) || !('command' in entry) || !('args' in entry))
+        return false;
+    const ours = host.server();
+    return Object.entries(entry).every(([key, value]) => (key === 'command' ? value === 'hippo' || value === 'hippo.cmd' : isDeepStrictEqual(value, ours[key])));
 }
-/** What to paste under "mcpServers" when hippo cannot edit the file itself. */
-export function copilotMcpSnippet() {
-    return `"${MCP_KEY}": ${JSON.stringify(hippoMcpServer())}`;
+/** What to paste under the host's key when hippo cannot edit the file itself. */
+export function copilotMcpSnippet(host = COPILOT_CLI_MCP) {
+    return `"${MCP_KEY}": ${JSON.stringify(host.server())}`;
 }
 /** Null for a file with comments, one that is not JSON, or one whose shape a merge would overwrite; a missing file reads as empty. */
-function readMcpConfig(file) {
+function readMcpConfig(file, host) {
     let config = {};
     if (fs.existsSync(file)) {
         try {
@@ -52,45 +96,47 @@ function readMcpConfig(file) {
         }
         catch (err) {
             // Only a parse failure means the text is not JSON hippo can merge; EACCES or EISDIR is thrown with its own message.
-            if (err instanceof SyntaxError)
+            if (!(err instanceof SyntaxError))
+                throw err;
+            // An empty file is a new one with no servers yet, not one with comments.
+            if (fs.readFileSync(file, 'utf8').trim() !== '')
                 return null;
-            throw err;
         }
     }
     if (!isJsonObject(config))
         return null;
-    if (config.mcpServers === undefined)
-        config.mcpServers = {};
-    const servers = config.mcpServers;
+    if (config[host.key] === undefined)
+        config[host.key] = {};
+    const servers = config[host.key];
     return isJsonObject(servers) ? { config, servers } : null;
 }
 /** Adds hippo's server and keeps every other key; a file hippo cannot parse, or a "hippo" key it did not write, stays as it is. */
-export function mergeMcpServer(file) {
-    const read = readMcpConfig(file);
+export function mergeMcpServer(file, host = COPILOT_CLI_MCP) {
+    const read = readMcpConfig(file, host);
     if (read === null)
         return 'unreadable';
     const existing = read.servers[MCP_KEY];
     if (existing !== undefined)
-        return isHipposServer(existing) ? 'present' : 'user-owned';
-    read.servers[MCP_KEY] = hippoMcpServer();
+        return isHipposServer(existing, host) ? 'present' : 'user-owned';
+    read.servers[MCP_KEY] = host.server();
     writeSettingsFile(file, read.config);
     return 'added';
 }
 /** Removes the "hippo" key only when hippo wrote it. */
-export function removeMcpServer(file) {
+export function removeMcpServer(file, host = COPILOT_CLI_MCP) {
     if (!fs.existsSync(file))
         return 'absent';
-    const read = readMcpConfig(file);
+    const read = readMcpConfig(file, host);
     if (read === null)
         return 'unreadable';
     const existing = read.servers[MCP_KEY];
     if (existing === undefined)
         return 'absent';
-    if (!isHipposServer(existing))
+    if (!isHipposServer(existing, host))
         return 'user-owned';
     delete read.servers[MCP_KEY];
     if (Object.keys(read.servers).length === 0)
-        delete read.config.mcpServers;
+        delete read.config[host.key];
     writeSettingsFile(file, read.config);
     return 'removed';
 }
@@ -100,7 +146,7 @@ export function isMcpFailure(status) {
 function hasErrnoCode(err) {
     return 'code' in err && typeof err.code === 'string';
 }
-/** One mcp-config.json step; a filesystem error comes back as a failure, so the hooks file and the block still install. */
+/** One MCP config step; a filesystem error comes back as a failure, so the hooks file and the instructions still install. */
 function mcpStep(step) {
     try {
         return step();
@@ -111,9 +157,8 @@ function mcpStep(step) {
         throw err;
     }
 }
-// A later release adds the hash of each earlier Copilot text here, as SHIPPED_HOOK_HASHES does for the other agents.
 function isCopilotBlock(inner) {
-    return inner === COPILOT_INSTRUCTIONS;
+    return SHIPPED_COPILOT_INSTRUCTIONS.includes(inner);
 }
 /** Replaces only the text between the markers, in the file's own line ending, or appends a block after the user's text. */
 function withCopilotBlock(text, found) {
@@ -166,13 +211,49 @@ export function removeInstructionsBlock(file) {
         fs.writeFileSync(file, left, 'utf8');
     return 'removed';
 }
+/** The file is hippo's alone, so it is written whole; an earlier hippo text is upgraded, and any other text already there stays. */
+export function ensureVscodeInstructions(file) {
+    if (fs.existsSync(file)) {
+        const old = fs.readFileSync(file, 'utf8');
+        if (old === VSCODE_INSTRUCTIONS)
+            return 'present';
+        if (!isHipposVscodeInstructions(old))
+            return 'kept';
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, VSCODE_INSTRUCTIONS, 'utf8');
+    return 'written';
+}
+/** Deletes the file only when it still holds exactly what a hippo release wrote. */
+export function removeVscodeInstructions(file) {
+    if (!fs.existsSync(file))
+        return 'absent';
+    if (!isHipposVscodeInstructions(fs.readFileSync(file, 'utf8')))
+        return 'kept';
+    fs.rmSync(file);
+    return 'removed';
+}
+/** The CLI's folder holds more than the hooks folder setup makes for VS Code, so a rerun on a VS Code-only machine still finds no CLI. */
+export function isCopilotCliPresent(home = copilotHomeDir()) {
+    if (fs.statSync(home, { throwIfNoEntry: false })?.isDirectory() !== true)
+        return false;
+    const entries = fs.readdirSync(home);
+    return entries.length !== 1 || entries[0] !== 'hooks';
+}
 export function installCopilot() {
     const paths = copilotPaths();
+    // Read before the hooks install, which makes the folder on a machine with only VS Code.
+    const cli = isCopilotCliPresent();
     return {
         paths,
         hooks: installJsonHooks('copilot').installedSessionStart,
-        mcp: mcpStep(() => mergeMcpServer(paths.mcpConfig)),
-        instructions: ensureInstructionsBlock(paths.instructions),
+        mcp: cli ? mcpStep(() => mergeMcpServer(paths.mcpConfig)) : null,
+        instructions: cli ? ensureInstructionsBlock(paths.instructions) : null,
+        vscode: paths.vscode.map((dir) => ({
+            paths: dir,
+            mcp: mcpStep(() => mergeMcpServer(dir.mcpConfig, VSCODE_MCP)),
+            instructions: ensureVscodeInstructions(dir.instructions),
+        })),
     };
 }
 export function uninstallCopilot() {
@@ -182,6 +263,11 @@ export function uninstallCopilot() {
         hooks: uninstallJsonHooks('copilot'),
         mcp: mcpStep(() => removeMcpServer(paths.mcpConfig)),
         instructions: removeInstructionsBlock(paths.instructions),
+        vscode: paths.vscode.map((dir) => ({
+            paths: dir,
+            mcp: mcpStep(() => removeMcpServer(dir.mcpConfig, VSCODE_MCP)),
+            instructions: removeVscodeInstructions(dir.instructions),
+        })),
     };
 }
 //# sourceMappingURL=copilot.js.map

package/dist/hooks/json-hooks.d.ts

@@ -63,6 +63,8 @@ export interface InstallResult {
 }
 /** The paths for `target` under the current home directory; reads and writes nothing. */
 export declare function resolveJsonHookPaths(target: JsonHookTarget): JsonHookPaths;
+/** The events in hippo's Copilot hooks file, in file order, for setup to name. */
+export declare function copilotHookEvents(): string[];
 /** Adds hippo's hooks to `target`'s settings file and migrates older hippo entries; a file that is not JSON stays untouched. */
 export declare function installJsonHooks(target: JsonHookTarget): InstallResult;
 /** Swaps the file in with one rename, so a crash mid-write cannot leave a truncated settings.json that Claude Code cannot parse. */

package/dist/hooks/json-hooks.js

@@ -35,7 +35,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { isJsonObject, HIPPO_SLEEP_MARKER, HIPPO_LAST_SLEEP_MARKER, HIPPO_CAPTURE_MARKER, HIPPO_SESSION_END_MARKER, HIPPO_PINNED_INJECT_MARKER, HIPPO_PINNED_INJECT_COMMAND, HIPPO_PRE_COMPACT_MARKER, HIPPO_COMPACT_RESUME_MARKER, HIPPO_CAPTURE_ERROR_MARKER, HIPPO_POST_COMPACT_MARKER, homeDir, claudeConfigDir, codexHomeDir, copilotHomeDir, defaultPreCompactLogPath } from './shared.js';
+import { isJsonObject, HIPPO_SLEEP_MARKER, HIPPO_LAST_SLEEP_MARKER, HIPPO_CAPTURE_MARKER, HIPPO_SESSION_END_MARKER, HIPPO_PINNED_INJECT_MARKER, HIPPO_PINNED_INJECT_COMMAND, HIPPO_PRE_COMPACT_MARKER, HIPPO_COMPACT_RESUME_MARKER, HIPPO_CAPTURE_ERROR_MARKER, HIPPO_POST_COMPACT_MARKER, homeDir, claudeConfigDir, codexHomeDir, copilotHooksFile, defaultPreCompactLogPath } from './shared.js';
 import { isJsonString, readJsonFile } from '../json.js';
 import { escapeRegex } from '../escape.js';
 import { errorMessage, log } from '../log.js';
@@ -58,7 +58,7 @@ export function resolveJsonHookPaths(target) {
             };
         case 'copilot':
             return {
-                settings: path.join(copilotHomeDir(), 'hooks', 'hippo.json'),
+                settings: copilotHooksFile(),
                 logFile: path.join(logsDir, 'copilot-sleep.log'),
                 display: 'Copilot',
             };
@@ -214,10 +214,19 @@ function copilotHooksTable() {
             sessionStart: copilotCommandHook('context --pinned-only --include-recent 5 --format copilot', 10),
             postToolUseFailure: copilotCommandHook('capture-error --runtime copilot', 10),
             preCompact: copilotCommandHook('pre-compact --runtime copilot', 30),
+            // VS Code maps no camelCase preCompact. The Copilot CLI may run both names, so pre-compact skips a snapshot saved seconds before.
+            PreCompact: copilotCommandHook('pre-compact --runtime copilot', 30),
+            // VS Code's per-reply Stop. --turn acts on a VS Code payload only, so the Copilot CLI's agentStop does nothing.
+            agentStop: copilotCommandHook('session-end --runtime copilot --turn', 30),
             sessionEnd: copilotCommandHook('session-end --runtime copilot', 30),
         },
     };
 }
+/** The events in hippo's Copilot hooks file, in file order, for setup to name. */
+export function copilotHookEvents() {
+    const hooks = copilotHooksTable().hooks;
+    return isJsonObject(hooks) ? Object.keys(hooks) : [];
+}
 /** Hippo owns this whole file, so install writes the full table and a second install changes no byte. */
 function installCopilotHooks(settingsPath) {
     const result = nothingInstalled('copilot', settingsPath);

package/dist/hooks/shared.d.ts

@@ -30,7 +30,13 @@ export declare function copilotHomeDir(home?: string, env?: Readonly<Record<stri
 export declare function claudeConfigDir(home?: string, env?: Readonly<Record<string, string | undefined>>): string;
 /** Codex counts as installed only when its config folder exists: Codex itself refuses a CODEX_HOME that is not a folder. */
 export declare function isCodexPresent(home?: string): boolean;
-/** Copilot counts as installed only when its config folder exists, so setup never creates ~/.copilot on a machine without it. */
+/** hippo's own hooks file, in the hooks folder the Copilot CLI reads. */
+export declare function copilotHooksFile(): string;
+/** Where VS Code's agent finds hippo.json: its docs name ~/.copilot/hooks as the user hooks folder, whatever COPILOT_HOME says. */
+export declare function vscodeUserHooksFile(home?: string): string;
+/** The VS Code User folders that exist; Stable and Insiders keep their own, and only an edition the user has run has one. */
+export declare function vscodeUserDirs(env?: Readonly<Record<string, string | undefined>>, home?: string): string[];
+/** Copilot counts as installed only when its config folder or a VS Code User folder exists, so setup never creates ~/.copilot on a machine with neither. */
 export declare function isCopilotPresent(home?: string): boolean;
 /** Codex hashes each hook and skips new or changed ones until the user reviews them in `/hooks`, so the reminder says what they would trust. */
 export declare const CODEX_TRUST_LINE = "The per-prompt hook sends your pinned memories plus up to 5 that match the prompt. Codex runs hippo's hooks only after you trust them once in `/hooks`.";

package/dist/hooks/shared.js

@@ -2,6 +2,7 @@ import { envHomeDir, processEnv } from '../env.js';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import { vscodeDataFolders } from '../agent-memories/copilot.js';
 /** JSON-value plain-object check (excludes arrays and null); `constructor` avoids the `typeof` tag banned by anti-slop/no-runtime-typeof. */
 export function isJsonObject(value) {
     return value !== undefined && value !== null && !Array.isArray(value) && value.constructor === Object;
@@ -36,9 +37,23 @@ export function claudeConfigDir(home = os.homedir(), env = processEnv()) {
 export function isCodexPresent(home = homeDir()) {
     return fs.statSync(codexHomeDir(home), { throwIfNoEntry: false })?.isDirectory() === true;
 }
-/** Copilot counts as installed only when its config folder exists, so setup never creates ~/.copilot on a machine without it. */
+/** hippo's own hooks file, in the hooks folder the Copilot CLI reads. */
+export function copilotHooksFile() {
+    return path.join(copilotHomeDir(), 'hooks', 'hippo.json');
+}
+/** Where VS Code's agent finds hippo.json: its docs name ~/.copilot/hooks as the user hooks folder, whatever COPILOT_HOME says. */
+export function vscodeUserHooksFile(home = os.homedir()) {
+    return path.join(home, '.copilot', 'hooks', 'hippo.json');
+}
+/** The VS Code User folders that exist; Stable and Insiders keep their own, and only an edition the user has run has one. */
+export function vscodeUserDirs(env = processEnv(), home = os.homedir()) {
+    return vscodeDataFolders({ env, home, platform: process.platform })
+        .map((dir) => path.join(dir, 'User'))
+        .filter((dir) => fs.statSync(dir, { throwIfNoEntry: false })?.isDirectory() === true);
+}
+/** Copilot counts as installed only when its config folder or a VS Code User folder exists, so setup never creates ~/.copilot on a machine with neither. */
 export function isCopilotPresent(home = os.homedir()) {
-    return fs.statSync(copilotHomeDir(home), { throwIfNoEntry: false })?.isDirectory() === true;
+    return fs.statSync(copilotHomeDir(home), { throwIfNoEntry: false })?.isDirectory() === true || vscodeUserDirs(processEnv(), home).length > 0;
 }
 /** Codex hashes each hook and skips new or changed ones until the user reviews them in `/hooks`, so the reminder says what they would trust. */
 export const CODEX_TRUST_LINE = "The per-prompt hook sends your pinned memories plus up to 5 that match the prompt. Codex runs hippo's hooks only after you trust them once in `/hooks`.";
@@ -76,7 +91,7 @@ export function detectInstalledTools() {
         { name: 'opencode', configDir: '~/.config/opencode', detected: exists('.config', 'opencode'), kind: 'plugin', notes: 'installs a TS plugin at ~/.config/opencode/plugins/hippo.ts' },
         { name: 'openclaw', configDir: '~/.openclaw', detected: exists('.openclaw'), kind: 'plugin', notes: 'install via `openclaw plugins install hippo-memory`' },
         { name: 'codex', configDir: '~/.codex', detected: isCodexPresent(home), kind: 'wrapper', notes: 'memory hooks in hooks.json, and wraps the detected codex launcher for session-end consolidation' },
-        { name: 'copilot', configDir: copilotHomeDir(), detected: isCopilotPresent(), kind: 'json-hook', notes: 'hooks in hooks/hippo.json, the MCP server in mcp-config.json and a block in copilot-instructions.md' },
+        { name: 'copilot', configDir: copilotHomeDir(), detected: isCopilotPresent(), kind: 'json-hook', notes: 'hooks in hooks/hippo.json, the MCP server in mcp-config.json and a block in copilot-instructions.md; for VS Code, the server in each User mcp.json and prompts/hippo.instructions.md' },
         { name: 'cursor', configDir: '~/.cursor', detected: exists('.cursor'), kind: 'markdown-instruction', notes: 'no hook API - patches AGENTS.md in the project' },
         { name: 'pi', configDir: '~/.pi', detected: exists('.pi'), kind: 'markdown-instruction', notes: 'no hook API - patches AGENTS.md in the project' },
     ];

package/dist/mcp/memory-tools.d.ts

@@ -1,5 +1,5 @@
 import { type ToolCall } from './protocol.js';
-export declare function runRememberTool({ args, ctx, hippoRoot, config, tenantId }: ToolCall): string;
-export declare function runOutcomeTool({ args, ctx, hippoRoot, tenantId }: ToolCall): string;
+export declare function runRememberTool({ args, ctx, hippoRoot, config, tenantId }: ToolCall): Promise<string>;
+export declare function runOutcomeTool({ args, ctx, hippoRoot, tenantId }: ToolCall): Promise<string>;
 export declare function runLearnTool({ args, ctx, hippoRoot, tenantId }: ToolCall): string;
 //# sourceMappingURL=memory-tools.d.ts.map

package/dist/mcp/memory-tools.js

@@ -1,6 +1,6 @@
 // Write-side tool handlers: hippo_remember, hippo_outcome and hippo_learn.
 import { log } from '../log.js';
-import { readEntry } from '../store/entry-reads.js';
+import { storeFor } from '../store-port.js';
 import { countCreatedSinceLastSleep } from '../store/index-and-stats.js';
 import { consolidate } from '../consolidate/sleep.js';
 import { outsideRequestStores, runWithRequestStores, scopedBusyWait } from '../db.js';
@@ -8,7 +8,7 @@ import { resolveTenantId } from '../tenant.js';
 import { remember as apiRemember, outcome as apiOutcome, learn as apiLearn, MCP_LEARN } from '../api.js';
 import { mcpActor } from './protocol.js';
 import { lastRecalledIds, autoSleepInFlight, resolveClientKey } from './session-state.js';
-export function runRememberTool({ args, ctx, hippoRoot, config, tenantId }) {
+export async function runRememberTool({ args, ctx, hippoRoot, config, tenantId }) {
     const text = String(args.text || '');
     if (!text)
         return 'No text provided.';
@@ -28,16 +28,17 @@ export function runRememberTool({ args, ctx, hippoRoot, config, tenantId }) {
         actor: mcpActor(ctx),
         store: ctx?.store,
     };
-    const result = apiRemember(apiCtx, {
+    const result = await apiRemember(apiCtx, {
         content: text,
         tags,
         personal: args.personal === true,
         project: ctx?.project,
     });
-    const entry = readEntry(hippoRoot, result.id, tenantId);
+    const [entry] = await storeFor(apiCtx).entriesByIds([result.id], tenantId);
     // Auto-sleep: one run per store at a time, triggered by what arrived since the last one.
-    // Consolidation is host-wide, so only the host tenant's writes may start it.
-    if (ctx?.autoSleep !== false &&
+    // Consolidation is host-wide, so only the host tenant's writes may start it. It runs on hippo.db, so another store skips it.
+    if ((ctx?.store === undefined || ctx.store.kind === 'sqlite') &&
+        ctx?.autoSleep !== false &&
         config.autoSleep.enabled &&
         tenantId === resolveTenantId({}) &&
         !autoSleepInFlight.has(hippoRoot) &&
@@ -57,7 +58,7 @@ export function runRememberTool({ args, ctx, hippoRoot, config, tenantId }) {
     const warnings = (result.warnings ?? []).map((w) => `\nWarning: ${w}`).join('');
     return `Remembered [${result.id}] (half-life: ${halfLife}d, tags: ${tagStr})${warnings}`;
 }
-export function runOutcomeTool({ args, ctx, hippoRoot, tenantId }) {
+export async function runOutcomeTool({ args, ctx, hippoRoot, tenantId }) {
     const good = Boolean(args.good);
     const clientKey = resolveClientKey(ctx);
     const ids = lastRecalledIds.get(clientKey) ?? [];
@@ -73,7 +74,7 @@ export function runOutcomeTool({ args, ctx, hippoRoot, tenantId }) {
         actor: mcpActor(ctx),
         store: ctx?.store,
     };
-    const { applied } = apiOutcome(apiCtx, ids, good);
+    const { applied } = await apiOutcome(apiCtx, ids, good);
     return `Applied ${good ? 'positive' : 'negative'} outcome to ${applied} memories`;
 }
 export function runLearnTool({ args, ctx, hippoRoot, tenantId }) {

package/dist/mcp/request.js

@@ -64,9 +64,9 @@ const TOOL_HANDLERS = new Map([
     ['hippo_assemble', { handler: runAssembleTool }],
     ['hippo_drill', { handler: runDrillTool }],
     ['hippo_predict_baserate', { handler: runPredictBaserateTool }],
-    ['hippo_remember', { handler: runRememberTool }],
-    ['hippo_outcome', { handler: runOutcomeTool }],
-    ['hippo_context', { handler: runContextTool }],
+    ['hippo_remember', { handler: runRememberTool, storeReady: 'entryWrites' }],
+    ['hippo_outcome', { handler: runOutcomeTool, storeReady: 'entryWrites' }],
+    ['hippo_context', { handler: runContextTool, storeReady: 'contextReads' }],
     ['hippo_status', { handler: runStatusTool }],
     ['hippo_learn', { handler: runLearnTool }],
     ['hippo_conflicts', { handler: runConflictsTool }],

package/dist/memory.d.ts

@@ -190,6 +190,8 @@ export declare function deriveHalfLife(base: number, entry: Partial<MemoryEntry>
  * cumulative reward signal, inspired by R-STDP in spiking networks.
  */
 export declare function applyOutcome(entry: MemoryEntry, good: boolean): MemoryEntry;
+/** applyOutcome as a served outcome applies it: a good outcome reconfirms the entry, so its churn-stale tag goes. */
+export declare function entryAfterOutcome(entry: MemoryEntry, good: boolean): MemoryEntry;
 /**
  * Generate a random memory ID using crypto.randomUUID().
  */

package/dist/memory.js

@@ -277,6 +277,13 @@ export function applyOutcome(entry, good) {
     updated.strength = calculateStrength(updated);
     return updated;
 }
+/** applyOutcome as a served outcome applies it: a good outcome reconfirms the entry, so its churn-stale tag goes. */
+export function entryAfterOutcome(entry, good) {
+    const updated = applyOutcome(entry, good);
+    if (!good || !updated.tags.includes(CHURN_STALE_TAG))
+        return updated;
+    return { ...updated, tags: updated.tags.filter((t) => t !== CHURN_STALE_TAG) };
+}
 /**
  * Generate a random memory ID using crypto.randomUUID().
  */

package/dist/prompt-recall.d.ts

@@ -30,4 +30,9 @@ export declare const RAREST_TERM_COUNT = 8;
 /** Terms sorted by ascending FTS doc count (rarest first), zero-count terms dropped, ties by term.
  *  Pure: `docCount` (an FTS lookup in the caller) does the only I/O. */
 export declare function rarestPromptTerms(terms: Iterable<string>, docCount: (term: string) => number, maxTerms?: number): string[];
+/** The pieces FTS5's unicode61 tokenizer indexes a term as, so `journal_mode` is `journal` and `mode`. */
+export declare function ftsTermParts(term: string): string[];
+/** The rarest terms as a space-joined FTS query, given each part's document count; a term counts as its rarest part,
+ *  an upper bound on rows holding the whole term, and a term with no parts counts 0, so it is dropped. */
+export declare function rarestFtsQuery(terms: readonly string[], docCount: (part: string) => number, maxTerms?: number): string;
 //# sourceMappingURL=prompt-recall.d.ts.map

package/dist/prompt-recall.js

@@ -64,4 +64,17 @@ export function rarestPromptTerms(terms, docCount, maxTerms = RAREST_TERM_COUNT)
         .slice(0, maxTerms)
         .map((x) => x.t);
 }
+/** The pieces FTS5's unicode61 tokenizer indexes a term as, so `journal_mode` is `journal` and `mode`. */
+export function ftsTermParts(term) {
+    return term.split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+}
+/** The rarest terms as a space-joined FTS query, given each part's document count; a term counts as its rarest part,
+ *  an upper bound on rows holding the whole term, and a term with no parts counts 0, so it is dropped. */
+export function rarestFtsQuery(terms, docCount, maxTerms = RAREST_TERM_COUNT) {
+    const termCount = (t) => {
+        const parts = ftsTermParts(t);
+        return parts.length === 0 ? 0 : Math.min(...parts.map(docCount));
+    };
+    return rarestPromptTerms(terms, termCount, maxTerms).join(' ');
+}
 //# sourceMappingURL=prompt-recall.js.map

package/dist/raw-archive.d.ts

@@ -18,7 +18,7 @@ export interface ArchiveOpts {
  * append-only trigger lets the delete through, then deletes the row. All in one
  * write scope, which nests inside an outer transaction (e.g. batchWriteAndDelete).
  *
- * Throws if the row does not exist or is not `kind='raw'`.
+ * Throws if the row does not exist or is not `kind='raw'`. Returns the archived_at it wrote.
  */
-export declare function archiveRawMemory(db: DatabaseSyncLike, id: string, opts: ArchiveOpts): void;
+export declare function archiveRawMemory(db: DatabaseSyncLike, id: string, opts: ArchiveOpts): string;
 //# sourceMappingURL=raw-archive.d.ts.map

package/dist/raw-archive.js

@@ -34,6 +34,7 @@ function moveRowToArchive(db, id, row, opts) {
     // Archived text must be unsearchable at commit, so a failed purge fails (and rolls back) the whole archive.
     if (isFtsAvailable(db))
         db.prepare(`DELETE FROM memories_fts WHERE id = ?`).run(id);
+    return archivedAt;
 }
 // Emit the archive_raw audit event inside the SAVEPOINT so the audit row is
 // committed atomically with the row deletion. Use the row's own tenant_id
@@ -62,14 +63,14 @@ function auditArchive(db, id, row, opts) {
  * append-only trigger lets the delete through, then deletes the row. All in one
  * write scope, which nests inside an outer transaction (e.g. batchWriteAndDelete).
  *
- * Throws if the row does not exist or is not `kind='raw'`.
+ * Throws if the row does not exist or is not `kind='raw'`. Returns the archived_at it wrote.
  */
 export function archiveRawMemory(db, id, opts) {
     const row = loadRawRow(db, id);
     // A SAVEPOINT when already inside a transaction (e.g. batchWriteAndDelete), so a throw here
     // rolls back only this archive.
-    withWriteScope(db, 'archive_raw', () => {
-        moveRowToArchive(db, id, row, opts);
+    return withWriteScope(db, 'archive_raw', () => {
+        const archivedAt = moveRowToArchive(db, id, row, opts);
         auditArchive(db, id, row, opts);
         // Archiving a child under a level-2 summary marks the parent dirty, inside the
         // SAVEPOINT so the dirty-mark commits atomically with the archive.
@@ -84,6 +85,7 @@ export function archiveRawMemory(db, id, opts) {
         if (opts.afterArchive) {
             opts.afterArchive(db, id);
         }
+        return archivedAt;
     });
 }
 //# sourceMappingURL=raw-archive.js.map

package/dist/recall-scope.d.ts

@@ -60,6 +60,8 @@ export declare function assertClientScope(scope: string | null | undefined): voi
 export declare function canTouchScope(actor: {
     owner?: string;
 }, scope: string | null): boolean;
+/** canTouchScope for a caller known by its own personal scope, as a store method receives it. */
+export declare function ownScopeTouches(ownScope: string | null, scope: string | null): boolean;
 /**
  * Recall-side scope filter — the canonical JS half of the recall default-deny
  * rule (the SQL half lives in `loadSearchRows` via `loadRecallSearchEntries`).
@@ -68,11 +70,6 @@ export declare function canTouchScope(actor: {
  * - When `requested` is undefined/empty: default-deny on any
  *   `<source>:private:*` scope and on the `RECALL_DEFAULT_DENY_SCOPES`
  *   quarantine buckets. `null` and public scopes pass, and so does `ownScope`, the caller's own personal scope.
- *
- * @internal Exported for test parity with
- * `RECALL_DEFAULT_DENY_SCOPES` (single-source-of-truth verification). NOT part
- * of the public API surface; not re-exported from `src/index.ts`. Subject to
- * change without semver bump.
  */
 export declare function passesScopeFilterForRecall(scope: string | null, requested: string | undefined, ownScope?: string | null): boolean;
 export interface SqlFragment {

package/dist/recall-scope.js

@@ -83,7 +83,11 @@ export function assertClientScope(scope) {
 }
 /** True when `actor` may change or delete a row in `scope`: any non-personal scope, or its own personal one. */
 export function canTouchScope(actor, scope) {
-    return !isPersonalScope(scope) || scope === personalScopeOf(actor);
+    return ownScopeTouches(personalScopeOf(actor), scope);
+}
+/** canTouchScope for a caller known by its own personal scope, as a store method receives it. */
+export function ownScopeTouches(ownScope, scope) {
+    return !isPersonalScope(scope) || scope === ownScope;
 }
 /**
  * Recall-side scope filter — the canonical JS half of the recall default-deny
@@ -93,11 +97,6 @@ export function canTouchScope(actor, scope) {
  * - When `requested` is undefined/empty: default-deny on any
  *   `<source>:private:*` scope and on the `RECALL_DEFAULT_DENY_SCOPES`
  *   quarantine buckets. `null` and public scopes pass, and so does `ownScope`, the caller's own personal scope.
- *
- * @internal Exported for test parity with
- * `RECALL_DEFAULT_DENY_SCOPES` (single-source-of-truth verification). NOT part
- * of the public API surface; not re-exported from `src/index.ts`. Subject to
- * change without semver bump.
  */
 export function passesScopeFilterForRecall(scope, requested, ownScope) {
     if (requested !== undefined && requested !== '') {

package/dist/server/routes/memories.js

@@ -29,7 +29,7 @@ export async function handleCreateMemory({ req, res, opts }) {
     if (personalRaw !== undefined && !isJsonBoolean(personalRaw)) {
         throw new HttpError(400, 'personal must be a boolean');
     }
-    const result = remember(ctx, {
+    const result = await remember(ctx, {
         content,
         kind: kindRaw,
         scope: getString(body, 'scope'),
@@ -69,7 +69,7 @@ export async function handleArchiveMemory({ req, res, opts }, archiveMatch) {
     if (!reason) {
         throw new HttpError(400, 'reason is required');
     }
-    const result = archiveRaw(ctx, archiveMatch.id, reason);
+    const result = await archiveRaw(ctx, archiveMatch.id, reason);
     sendJson(res, 200, result);
     return;
 }
@@ -81,7 +81,7 @@ export async function handleSupersedeMemory({ req, res, opts }, supersedeMatch)
     if (!content) {
         throw new HttpError(400, 'content is required');
     }
-    const result = supersede(ctx, supersedeMatch.id, content);
+    const result = await supersede(ctx, supersedeMatch.id, content);
     sendJson(res, 200, result);
     return;
 }
@@ -95,7 +95,7 @@ export async function handlePromoteMemory({ req, res, opts }, promoteMatch) {
 export async function handleForgetMemory({ req, res, opts }, idMatch) {
     validateIdSegment(idMatch.id, 'memory id');
     const ctx = await buildContextWithAuth(req, opts);
-    const result = forget(ctx, idMatch.id);
+    const result = await forget(ctx, idMatch.id);
     sendJson(res, 200, result);
     return;
 }
@@ -132,11 +132,14 @@ export async function handleApplyOutcome({ req, res, opts }) {
         ids = idsRaw;
     }
     if (ids !== undefined) {
-        const { applied } = outcome(ctx, ids, good);
+        const { applied } = await outcome(ctx, ids, good);
         sendJson(res, 200, { applied });
     }
     else {
-        const result = outcomeForLastRecall(ctx, good);
+        // The last recall's ids live in hippo.db alone, so a client of another store must send the ids its recall returned.
+        if (ctx.store !== undefined && ctx.store.kind !== 'sqlite')
+            throw new HttpError(501, 'this store keeps no last recall: send the ids your recall returned');
+        const result = await outcomeForLastRecall(ctx, good);
         sendJson(res, 200, result);
     }
     return;