hippo-memory 1.60.0 → 1.62.0

package/dist/api/drill-down.js

@@ -0,0 +1,126 @@
+// DAG drill-down from a summary to its children.
+import { readEntry, loadChildrenOf } from '../store/entry-reads.js';
+import { estimateTokens } from '../token-ledger.js';
+import { passesScopeFilterForRecall } from '../recall-scope.js';
+/**
+ * Walk one step down the DAG from a level-2 (or higher) summary to its direct
+ * children. Companion to `recall(... summarizeOverflow: true)` — when recall
+ * surfaces a summary with `substitutedFor: [...]`, the caller drills into the
+ * summary id to recover the original detail.
+ *
+ * Tenant scope: only summaries owned by `ctx.tenantId` are reachable. The same
+ * scope filter that recall applies is enforced on the children — a level-2
+ * summary in `slack:public:CGEN` cannot leak `slack:private:*` children even
+ * if the underlying DAG accidentally linked across scopes.
+ *
+ * Returns a discriminated `DrillDownOutcome`: `DrillDownResult` on success,
+ * or `{failure: '...'}` for `not_found` (covers genuinely-missing AND wrong-
+ * tenant, intentionally indistinguishable), `not_drillable` (id is a leaf
+ * row), or `scope_blocked` (caller has no scope grant for the row's scope).
+ *
+ * Pre-v1.6.4 returned null for all four cases. JS callers migrate via
+ * `'failure' in result` checks; HTTP route maps `not_drillable` to 422.
+ */
+export function drillDown(ctx, summaryId, opts = {}) {
+    const limit = opts.limit ?? 50;
+    // v0.30 / E5: depth defaults 1 (backward compat); hard cap 10 levels
+    // prevents pathological deep trees. CLI/HTTP/MCP reject invalid values.
+    const depth = Math.max(1, Math.min(Math.trunc(opts.depth ?? 1), 10));
+    const summary = readEntry(ctx.hippoRoot, summaryId, ctx.tenantId);
+    // No unscoped cross-tenant probe here — readEntry's null return covers
+    // both "doesn't exist" and "exists in another tenant" by design.
+    // Distinguishing them via an unscoped lookup would leak existence to
+    // unauthorised tenants. The two cases collapse into not_found.
+    if (!summary)
+        return { failure: 'not_found' };
+    if ((summary.dag_level ?? 0) < 2)
+        return { failure: 'not_drillable' };
+    if (!passesScopeFilterForRecall(summary.scope ?? null, undefined)) {
+        // codex round 3 P1: collapse to not_found. A distinguishable
+        // "scope_blocked" tells a no-scope caller "this row exists, just
+        // not for you" — same existence-leak the HTTP 404 collapse was
+        // already preventing. Match the HTTP behaviour at the API level.
+        return { failure: 'not_found' };
+    }
+    const { collected, level0DirectCount } = collectDescendants(ctx, summaryId, depth);
+    const summaryOut = {
+        id: summary.id,
+        content: summary.content,
+        // v0.30 / E5: the STORED direct-child count; the legacy fallback counts
+        // level-0 children, never the BFS-depth-N total (independent-review MED #4).
+        descendantCount: summary.descendant_count ?? level0DirectCount,
+        earliestAt: summary.earliest_at ?? null,
+        latestAt: summary.latest_at ?? null,
+    };
+    const all = collected.map((c) => ({
+        id: c.id,
+        content: c.content,
+        layer: c.layer,
+        dagLevel: c.dag_level ?? 0,
+        created: c.created,
+    }));
+    const { children, truncated } = capChildren(all, summaryOut, opts, limit);
+    return {
+        summary: summaryOut,
+        children,
+        // v0.30 / E5: totalChildren = BFS-collected count (depth-aware). For
+        // depth=1 this equals the eligible direct-children count (backward
+        // compat). For depth>1 it is the cumulative count across levels.
+        totalChildren: collected.length,
+        truncated,
+    };
+}
+// BFS with a visited set: dag_parent_id is not unique, so a misconfigured tree could emit a child twice past depth 1.
+// The level-0 count is kept apart so a legacy summary's descendantCount fallback counts direct children only.
+function collectDescendants(ctx, summaryId, depth) {
+    const collected = [];
+    const visited = new Set([summaryId]);
+    let frontier = [summaryId];
+    let level0DirectCount = 0;
+    for (let level = 0; level < depth; level++) {
+        const nextFrontier = [];
+        for (const parentId of frontier) {
+            const kids = loadChildrenOf(ctx.hippoRoot, parentId, ctx.tenantId);
+            const eligibleKids = kids.filter((c) => passesScopeFilterForRecall(c.scope ?? null, undefined));
+            for (const k of eligibleKids) {
+                if (visited.has(k.id))
+                    continue;
+                visited.add(k.id);
+                collected.push(k);
+                nextFrontier.push(k.id);
+                if (level === 0)
+                    level0DirectCount++;
+            }
+        }
+        if (nextFrontier.length === 0)
+            break;
+        frontier = nextFrontier;
+    }
+    return { collected, level0DirectCount };
+}
+/** Global cumulative token budget first, then the `limit` cap. */
+function capChildren(all, summaryOut, opts, limit) {
+    let children = all;
+    let truncated = false;
+    if (opts.budget !== undefined) {
+        const out = [];
+        let used = 0;
+        const room = opts.budget - (opts.cost?.fixed(summaryOut, all.length) ?? 0);
+        for (const c of all) {
+            const t = opts.cost ? opts.cost.child(c) : estimateTokens(c.content);
+            if (out.length > 0 && used + t > room) {
+                truncated = true;
+                break;
+            }
+            out.push(c);
+            used += t;
+        }
+        children = out;
+    }
+    if (children.length > limit) {
+        children = children.slice(0, limit);
+        truncated = true;
+    }
+    return { children, truncated };
+}
+//# sourceMappingURL=drill-down.js.map

package/dist/api/forget.d.ts

@@ -0,0 +1,57 @@
+import type { RejectedValueRow } from '../rejection.js';
+import type { Context } from './types.js';
+/**
+ * Delete a memory by id. `deleteEntry` threads ctx.actor.subject into its internal
+ * audit hook, so exactly one 'forget' event lands with the supplied actor.
+ *
+ * Tenant scope: deleteEntry looks up the row by id alone, so without an
+ * explicit tenant guard a Bearer for tenant A could delete tenant B's row
+ * by guessing or leaking the id. Pre-check the row's tenant_id and deny
+ * cross-tenant access with a not-found error (no info leak about whether
+ * the id exists in another tenant).
+ */
+export interface ForgetResult {
+    ok: true;
+    id: string;
+}
+export declare function forget(ctx: Context, id: string): ForgetResult;
+export interface RejectOpts {
+    /** By-id form: reject the CURRENT content of an existing memory. */
+    memoryId?: string;
+    /** Pre-emptive form: reject a value not currently stored (or already gone). */
+    value?: string;
+    /** Required — the tombstone stores no content; reason is its only identity. */
+    reason: string;
+}
+export interface RejectResult {
+    digest: string;
+    removedIds: string[];
+}
+/**
+ * Reject a value: tombstone its normalized digest so a matching write is
+ * refused everywhere (remember/capture/import/sync) until `unreject`. Two
+ * forms — pass exactly one:
+ *  - `memoryId`: reject the CURRENT content of an existing memory. Removes
+ *    that row and every other live row in the tenant whose normalized
+ *    digest matches (not just the id passed).
+ *  - `value`: pre-emptive form — tombstone content that may not currently
+ *    be stored (or is already gone). Zero removals.
+ *
+ * `reason` is required (the tombstone stores no content; reason is its
+ * only human-readable identity). Throws if the memory id is not found in
+ * `ctx.tenantId`, or if both/neither of `memoryId`/`value` are given.
+ */
+export declare function reject(ctx: Context, opts: RejectOpts): RejectResult;
+/**
+ * Delete a tombstone by exact digest or unambiguous prefix, restoring the
+ * value's writability — the only v1 escape hatch (no per-write force flag).
+ * Throws if `digestOrPrefix` matches no tombstone, is blank, or matches
+ * more than one (use a longer prefix).
+ */
+export declare function unreject(ctx: Context, digestOrPrefix: string): {
+    ok: boolean;
+    digest: string;
+};
+/** List every rejected-value tombstone for `ctx.tenantId`, newest first. */
+export declare function listRejections(ctx: Context): RejectedValueRow[];
+//# sourceMappingURL=forget.d.ts.map

package/dist/api/forget.js

@@ -0,0 +1,87 @@
+// Forget a memory, and reject or unreject a value so it cannot be stored again.
+import { openHippoDb, closeHippoDb } from '../db.js';
+import { BadRequestError, NotFoundError } from '../api-errors.js';
+import { deleteEntry } from '../store/delete-and-batch.js';
+import { updateStatsUnlessBusy } from '../store/index-and-stats.js';
+import { rejectValue, unrejectValue, listRejectionsForTenant } from '../reject-flow.js';
+import { selectMemoryTenant } from '../store/tenant-lookup.js';
+export function forget(ctx, id) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        if (selectMemoryTenant(db, id) !== ctx.tenantId) {
+            throw new NotFoundError(`memory not found: ${id}`);
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    const removed = deleteEntry(ctx.hippoRoot, id, { actor: ctx.actor.subject });
+    if (!removed) {
+        throw new NotFoundError(`memory not found: ${id}`);
+    }
+    // Counted here, not in the CLI: both callers of this function (cmdForget and
+    // the HTTP route) are the two paths of one user command, so neither can miss
+    // it. api.remember cannot take the same move; see the server route.
+    updateStatsUnlessBusy(ctx.hippoRoot, { forgotten: 1 }, `removed ${id}`);
+    return { ok: true, id };
+}
+/**
+ * Reject a value: tombstone its normalized digest so a matching write is
+ * refused everywhere (remember/capture/import/sync) until `unreject`. Two
+ * forms — pass exactly one:
+ *  - `memoryId`: reject the CURRENT content of an existing memory. Removes
+ *    that row and every other live row in the tenant whose normalized
+ *    digest matches (not just the id passed).
+ *  - `value`: pre-emptive form — tombstone content that may not currently
+ *    be stored (or is already gone). Zero removals.
+ *
+ * `reason` is required (the tombstone stores no content; reason is its
+ * only human-readable identity). Throws if the memory id is not found in
+ * `ctx.tenantId`, or if both/neither of `memoryId`/`value` are given.
+ */
+export function reject(ctx, opts) {
+    if (opts.memoryId !== undefined) {
+        // Tenant scope, same not-found-shaped denial as forget/promote above:
+        // rejectValue itself also tenant-checks the id, but pre-checking here
+        // keeps the error message consistent with the rest of this module.
+        const db = openHippoDb(ctx.hippoRoot);
+        try {
+            if (selectMemoryTenant(db, opts.memoryId) !== ctx.tenantId) {
+                throw new NotFoundError(`memory not found: ${opts.memoryId}`);
+            }
+        }
+        finally {
+            closeHippoDb(db);
+        }
+    }
+    const result = rejectValue({
+        hippoRoot: ctx.hippoRoot,
+        tenantId: ctx.tenantId,
+        actor: ctx.actor.subject,
+        reason: opts.reason,
+        memoryId: opts.memoryId,
+        value: opts.value,
+    });
+    return { digest: result.digest, removedIds: result.removedIds };
+}
+/**
+ * Delete a tombstone by exact digest or unambiguous prefix, restoring the
+ * value's writability — the only v1 escape hatch (no per-write force flag).
+ * Throws if `digestOrPrefix` matches no tombstone, is blank, or matches
+ * more than one (use a longer prefix).
+ */
+export function unreject(ctx, digestOrPrefix) {
+    const outcome = unrejectValue(ctx.hippoRoot, ctx.tenantId, digestOrPrefix, ctx.actor.subject);
+    if (outcome.status === 'not_found') {
+        throw new NotFoundError(`no rejected value matches: ${digestOrPrefix}`);
+    }
+    if (outcome.status === 'ambiguous') {
+        throw new BadRequestError(`"${digestOrPrefix}" matches ${outcome.candidates.length} tombstones; use a longer prefix`);
+    }
+    return { ok: true, digest: outcome.digest };
+}
+/** List every rejected-value tombstone for `ctx.tenantId`, newest first. */
+export function listRejections(ctx) {
+    return listRejectionsForTenant(ctx.hippoRoot, ctx.tenantId);
+}
+//# sourceMappingURL=forget.js.map

package/dist/api/goals.d.ts

@@ -0,0 +1,18 @@
+import { type CompleteGoalOpts, type Goal, type PushGoalOpts } from '../goals.js';
+import type { Context } from './types.js';
+/** What a new goal carries; its tenant is always the caller's. */
+export type GoalPushOpts = Omit<PushGoalOpts, 'tenantId'>;
+/** Push a goal onto `sessionId`'s stack in the caller's tenant. */
+export declare function goalPush(ctx: Context, opts: GoalPushOpts): Goal;
+/** The caller's goals for `sessionId`: active ones, or every status when `all` is set. */
+export declare function goalList(ctx: Context, opts: {
+    sessionId: string;
+    all: boolean;
+}): Goal[];
+/** Complete a goal by id; a no-op for an unknown or already completed goal. Host admin only. */
+export declare function goalComplete(ctx: Context, goalId: string, opts: CompleteGoalOpts): void;
+/** Suspend an active goal by id. Host admin only. */
+export declare function goalSuspend(ctx: Context, goalId: string): void;
+/** Resume a suspended goal by id, suspending the oldest active one past the depth cap. Host admin only. */
+export declare function goalResume(ctx: Context, goalId: string): void;
+//# sourceMappingURL=goals.d.ts.map

package/dist/api/goals.js

@@ -0,0 +1,33 @@
+// The per-session goal stack that recall boosts: push, list, complete, suspend and resume.
+import { ForbiddenError } from '../api-errors.js';
+import { completeGoal, getActiveGoals, getSessionGoals, pushGoal, resumeGoal, suspendGoal, } from '../goals.js';
+/** Push a goal onto `sessionId`'s stack in the caller's tenant. */
+export function goalPush(ctx, opts) {
+    return pushGoal(ctx.hippoRoot, { ...opts, tenantId: ctx.tenantId });
+}
+/** The caller's goals for `sessionId`: active ones, or every status when `all` is set. */
+export function goalList(ctx, opts) {
+    const scope = { sessionId: opts.sessionId, tenantId: ctx.tenantId };
+    return opts.all ? getSessionGoals(ctx.hippoRoot, scope) : getActiveGoals(ctx.hippoRoot, scope);
+}
+/** Complete a goal by id; a no-op for an unknown or already completed goal. Host admin only. */
+export function goalComplete(ctx, goalId, opts) {
+    requireHostAdmin(ctx);
+    completeGoal(ctx.hippoRoot, goalId, opts);
+}
+/** Suspend an active goal by id. Host admin only. */
+export function goalSuspend(ctx, goalId) {
+    requireHostAdmin(ctx);
+    suspendGoal(ctx.hippoRoot, goalId);
+}
+/** Resume a suspended goal by id, suspending the oldest active one past the depth cap. Host admin only. */
+export function goalResume(ctx, goalId) {
+    requireHostAdmin(ctx);
+    resumeGoal(ctx.hippoRoot, goalId);
+}
+// Goal ids are not tenant-scoped in the store, so acting on one by id is a cross-tenant power.
+function requireHostAdmin(ctx) {
+    if (!ctx.actor.hostAdmin)
+        throw new ForbiddenError('Only the host admin can change a goal by id');
+}
+//# sourceMappingURL=goals.js.map

package/dist/api/learn.d.ts

@@ -0,0 +1,31 @@
+import type { Context } from './types.js';
+/** How a surface writes what it learns. */
+export interface LearnProfile {
+    readonly tags: readonly string[];
+    readonly source: string;
+    /** Also invalidate what a migration subject supersedes, score schema fit, path-tag, count and embed each row. */
+    readonly full: boolean;
+}
+export declare const CLI_LEARN: LearnProfile;
+export declare const MCP_LEARN: LearnProfile;
+export interface LearnOpts {
+    repoPath: string;
+    days: number;
+    profile: LearnProfile;
+}
+export interface LearnResult {
+    /** `no-commits`: an empty git log; `no-lessons`: a log with no lesson-shaped subject. */
+    status: 'not-a-repo' | 'no-commits' | 'no-lessons' | 'scanned';
+    added: number;
+    skipped: number;
+    rejected: number;
+    lowInfo: number;
+    /** Each lesson whose migration target weakened at least one memory, in scan order. */
+    invalidations: Array<{
+        from: string;
+        count: number;
+    }>;
+}
+/** Learn from `repoPath`'s last `days` of commits into the caller's tenant. Host admin only. */
+export declare function learn(ctx: Context, opts: LearnOpts): LearnResult;
+//# sourceMappingURL=learn.d.ts.map

package/dist/api/learn.js

@@ -0,0 +1,88 @@
+// Git auto-learn: fix/revert/bug commit subjects become memories. `hippo learn`, init, sleep and MCP hippo_learn share it.
+import { ForbiddenError } from '../api-errors.js';
+import { fetchGitLog, extractLessons, partitionLessons, isGitRepo } from '../autolearn.js';
+import { loadConfig } from '../config.js';
+import { embedMemory } from '../embeddings.js';
+import { extractInvalidationTarget, invalidateMatching } from '../invalidation.js';
+import { computeSchemaFit, createMemory, Layer } from '../memory.js';
+import { extractPathTags } from '../path-context.js';
+import { RejectedValueError } from '../rejection.js';
+import { duplicateKey, longestWord, storedTextKeys } from '../same-text.js';
+import { loadTextsHoldingWords } from '../store/candidates.js';
+import { loadAllEntries } from '../store/entry-reads.js';
+import { writeEntry } from '../store/entry-writes.js';
+import { updateStats } from '../store/index-and-stats.js';
+// SHORTCUT: two profiles keep each surface's rows as they were; fold MCP onto the CLI profile once it may invalidate.
+export const CLI_LEARN = Object.freeze({ tags: Object.freeze(['error', 'git-learned']), source: 'git-learn', full: true });
+export const MCP_LEARN = Object.freeze({ tags: Object.freeze(['git-learned']), source: 'git', full: false });
+/** Learn from `repoPath`'s last `days` of commits into the caller's tenant. Host admin only. */
+export function learn(ctx, opts) {
+    // It reads the host's own git history, which belongs to the host, not to the caller's tenant.
+    if (!ctx.actor.hostAdmin)
+        throw new ForbiddenError('hippo_learn requires a host admin');
+    const none = { added: 0, skipped: 0, rejected: 0, lowInfo: 0, invalidations: [] };
+    if (!isGitRepo(opts.repoPath))
+        return { status: 'not-a-repo', ...none };
+    const gitLog = fetchGitLog(opts.repoPath, opts.days);
+    if (!gitLog.trim())
+        return { status: 'no-commits', ...none };
+    const config = loadConfig(ctx.hippoRoot);
+    const parsed = extractLessons(gitLog, config.gitLearnPatterns);
+    if (parsed.length === 0)
+        return { status: 'no-lessons', ...none };
+    // The gate filters the loop input, so a dropped lesson neither stores nor invalidates; docs/decisions git-learn-gate-placement says why.
+    const { kept, dropped } = partitionLessons(parsed);
+    return { status: 'scanned', lowInfo: dropped.length, ...writeLessons(ctx, kept, opts, config) };
+}
+function writeLessons(ctx, lessons, opts, config) {
+    const { hippoRoot, tenantId } = ctx;
+    const { profile } = opts;
+    // Schema fit needs every row; without it, only rows holding a lesson's longest word can be its copy.
+    const existing = profile.full ? loadAllEntries(hippoRoot, tenantId) : undefined;
+    const keys = storedTextKeys(existing ?? loadTextsHoldingWords(hippoRoot, tenantId, lessons.map(longestWord)));
+    const pathTags = profile.full ? extractPathTags(opts.repoPath) : [];
+    const counts = { added: 0, skipped: 0, rejected: 0, invalidations: [] };
+    for (const lesson of lessons) {
+        if (keys.has(duplicateKey(lesson))) {
+            counts.skipped++;
+            continue;
+        }
+        const target = profile.full ? extractInvalidationTarget(lesson) : null;
+        if (target) {
+            const { invalidated } = invalidateMatching(hippoRoot, target, tenantId);
+            if (invalidated > 0)
+                counts.invalidations.push({ from: target.from, count: invalidated });
+        }
+        const entry = createMemory(lesson, {
+            layer: Layer.Episodic,
+            tags: [...profile.tags],
+            source: profile.source,
+            confidence: 'observed',
+            schema_fit: existing && computeSchemaFit(lesson, [...profile.tags], existing),
+            tenantId,
+            baseHalfLifeDays: config.defaultHalfLifeDays,
+        });
+        for (const tag of pathTags)
+            if (!entry.tags.includes(tag))
+                entry.tags.push(tag);
+        // A refused lesson must not abort the rest of the git-log scan.
+        try {
+            writeEntry(hippoRoot, entry, { actor: ctx.actor.subject });
+        }
+        catch (err) {
+            if (err instanceof RejectedValueError) {
+                counts.rejected++;
+                continue;
+            }
+            throw err;
+        }
+        if (profile.full)
+            updateStats(hippoRoot, { remembered: 1 });
+        keys.add(duplicateKey(lesson));
+        if (profile.full)
+            void embedMemory(hippoRoot, entry);
+        counts.added++;
+    }
+    return counts;
+}
+//# sourceMappingURL=learn.js.map

package/dist/api/outcome.d.ts

@@ -0,0 +1,61 @@
+import type { Context } from './types.js';
+/**
+ * Apply a positive/negative outcome to a list of recently-recalled memory ids.
+ * Used by the MCP `hippo_outcome` tool and the HTTP `POST /v1/outcome` route.
+ * Tenant-scoped: ids that don't belong to ctx.tenantId are silently skipped
+ * (matches the prior MCP semantics — a stale id from another tenant doesn't
+ * crash the call). Each successful outcome emits one audit_log row with
+ * op='outcome' tagged with ctx.actor.subject.
+ *
+ * Returns `{applied, appliedIds}`. `appliedIds` is the tenant-filtered subset
+ * of input ids that actually had `applyOutcome` run on them (i.e. ids whose
+ * `readEntry(..., ctx.tenantId)` resolved). Callers that surface the id list
+ * over a multi-tenant boundary (HTTP /v1/outcome last-recall path, Python SDK)
+ * MUST return `appliedIds` instead of the raw input list — otherwise the
+ * non-applied (cross-tenant) ids leak to the caller. Added in v1.11.4 to
+ * close that disclosure path on POST /v1/outcome.
+ *
+ * `opts.traceId` (LC1, docs/plans/2026-08-02-lc1-recall-trace-persistence.md):
+ * OPTIONAL additive opt so a programmatic caller can link this outcome to
+ * the recall_traces row it judges. NOT applied unconditionally — an SDK
+ * caller passing explicit ids with no preceding CLI/context recall would
+ * otherwise get linked to a stale, unrelated trace. `outcomeForLastRecall`
+ * supplies this automatically from `last_trace_id`; every other caller
+ * (server.ts explicit-ids path, MCP hippo_outcome) omits it and gets no
+ * linkage, which is correct.
+ */
+export interface OutcomeResult {
+    applied: number;
+    appliedIds: string[];
+}
+export declare function outcome(ctx: Context, ids: ReadonlyArray<string>, good: boolean, opts?: {
+    traceId?: number;
+}): OutcomeResult;
+/**
+ * Apply an outcome to the ids most recently returned by `recall()`.
+ *
+ * Reads `loadIndex(ctx.hippoRoot).last_retrieval_ids` (per-hippoRoot local
+ * state; not tenant-scoped at the index layer) and forwards to `outcome()`,
+ * which DOES tenant-filter via `readEntry(..., ctx.tenantId)`. Cross-tenant
+ * ids in `last_retrieval_ids` are silently skipped, matching the MCP
+ * `hippo_outcome` semantics.
+ *
+ * **Tenant-safe response shape (v1.11.4 security fix):** the returned `ids`
+ * field contains ONLY the tenant-filtered subset that actually had outcomes
+ * applied (i.e. `appliedIds` from the inner `outcome()` call). Earlier
+ * versions returned the raw `last_retrieval_ids` regardless of tenant, which
+ * leaked cross-tenant memory IDs to the caller via POST /v1/outcome's
+ * no-body last-recall response. The fix is at this helper so all callers
+ * (CLI cmdOutcome, HTTP /v1/outcome, MCP `hippo_outcome` if added later)
+ * inherit the tenant-safe contract.
+ *
+ * Do NOT tighten `loadIndex` with `tenantId` inside this helper — doing so
+ * would break the (correct) cross-tenant-silent-skip behavior covered by
+ * the test in `tests/api-outcome-for-last-recall.test.ts`.
+ */
+export interface OutcomeForLastRecallResult {
+    applied: number;
+    ids: string[];
+}
+export declare function outcomeForLastRecall(ctx: Context, good: boolean): OutcomeForLastRecallResult;
+//# sourceMappingURL=outcome.d.ts.map

package/dist/api/outcome.js

@@ -0,0 +1,66 @@
+// Outcome feedback on recalled memories.
+import { openHippoDb, closeHippoDb } from '../db.js';
+import { writeEntry } from '../store/entry-writes.js';
+import { readEntry } from '../store/entry-reads.js';
+import { loadIndex } from '../store/index-and-stats.js';
+import { applyOutcome, CHURN_STALE_TAG } from '../memory.js';
+import { appendAuditEvent } from '../audit.js';
+import { recordTraceOutcome } from '../recall-trace.js';
+export function outcome(ctx, ids, good, opts) {
+    const appliedIds = [];
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        for (const id of ids) {
+            const entry = readEntry(ctx.hippoRoot, id, ctx.tenantId);
+            if (!entry)
+                continue;
+            let updated = applyOutcome(entry, good);
+            if (good && updated.tags.includes(CHURN_STALE_TAG)) { // FE2: a good outcome reconfirms the entry
+                updated = { ...updated, tags: updated.tags.filter((t) => t !== CHURN_STALE_TAG) };
+            }
+            writeEntry(ctx.hippoRoot, updated, { actor: ctx.actor.subject });
+            appendAuditEvent(db, {
+                tenantId: ctx.tenantId,
+                actor: ctx.actor.subject,
+                op: 'outcome',
+                targetId: id,
+                metadata: { good },
+            });
+            appliedIds.push(id);
+        }
+        // LC1: link the outcome to its trace, recording only the ids actually
+        // credited (post tenant-filtering, matches appliedIds). Lives in its own
+        // append-only table so audit_log pruning can never erase training data.
+        if (opts?.traceId !== undefined && appliedIds.length > 0) {
+            recordTraceOutcome(db, {
+                traceId: opts.traceId,
+                tenantId: ctx.tenantId,
+                outcome: good ? 'positive' : 'negative',
+                memoryIds: appliedIds,
+            });
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    return { applied: appliedIds.length, appliedIds };
+}
+export function outcomeForLastRecall(ctx, good) {
+    const idx = loadIndex(ctx.hippoRoot);
+    const ids = idx.last_retrieval_ids;
+    if (ids.length === 0)
+        return { applied: 0, ids: [] };
+    // LC1 F1(d) structural fix (docs/plans/2026-08-02-lc1-recall-trace-persistence.md):
+    // read the trace id from the SAME `loadIndex` snapshot already in hand
+    // (idx.last_trace_id) — a single-snapshot read, not a second DB round
+    // trip via a now-deleted readLastTraceId helper. The value is already
+    // strict-parsed by buildIndexFromDb's parseLastTraceId (store.ts): every
+    // consumer gets a clean positive-integer string or null, never a garbage
+    // value that could reach outcome() and INSERT trace_id=0/NaN. null on a
+    // fresh store / pre-v40 flow / api.recall-only usage — outcome() skips
+    // linkage silently when traceId is undefined.
+    const traceId = idx.last_trace_id !== null ? Number(idx.last_trace_id) : null;
+    const { applied, appliedIds } = outcome(ctx, ids, good, traceId !== null ? { traceId } : undefined);
+    return { applied, ids: appliedIds };
+}
+//# sourceMappingURL=outcome.js.map

package/dist/api/promote.d.ts

@@ -0,0 +1,54 @@
+import { type DatabaseSyncLike } from '../db.js';
+import type { Context } from './types.js';
+/**
+ * Copy a local memory into the global store. Mirrors `cmdPromote` in cli.ts:
+ * the `writeEntry` inside `promoteToGlobal` emits a 'remember' on the global
+ * db; we add a 'promote' audit event on the global db so the user-facing
+ * intent stays distinct from the underlying upsert.
+ *
+ * Note: `promoteToGlobal` does not currently take a tenantId override — it
+ * reads the entry from the local root via `readEntry` (no tenant filter) and
+ * preserves the entry's existing tenantId on the global side. Task 4 may
+ * tighten this once writeEntry/readEntry thread tenant context.
+ */
+export interface PromoteResult {
+    ok: true;
+    sourceId: string;
+    globalId: string;
+}
+export declare function promote(ctx: Context, id: string): PromoteResult;
+/**
+ * Replace an old memory with new content, chaining old.superseded_by = new.id.
+ * Mirrors `cmdSupersede` in cli.ts (without flag-driven layer/tag/pin overrides
+ * — A1 keeps the API minimal; the CLI handler will continue to handle those
+ * flags and pass the resolved values once Task 4 lands).
+ */
+export interface SupersedeResult {
+    ok: true;
+    oldId: string;
+    newId: string;
+}
+export declare function supersede(ctx: Context, oldId: string, newContent: string): SupersedeResult;
+/**
+ * Archive a kind='raw' memory: snapshot into raw_archive, mark archived, delete.
+ *
+ * `archiveRawMemory` audits the operation internally (op='archive_raw') using the
+ * row's own tenant_id. We DO NOT emit a second audit event here to avoid double-
+ * emitting the archive_raw op (unlike Task 1 remember/forget where the underlying
+ * helpers hardcode actor='cli'). Instead we pass `ctx.actor.subject` through as `who`,
+ * and raw-archive.ts uses that for the audit row.
+ */
+export interface ArchiveRawOpts {
+    /**
+     * Connector idempotency hook (v0.39 commit 3). Runs inside the same
+     * SAVEPOINT as the archive — throwing rolls the archive back. Used by the
+     * Slack deletion connector to mark the deletion event seen atomically.
+     */
+    afterArchive?: (db: DatabaseSyncLike, archivedMemoryId: string) => void;
+}
+export interface ArchiveRawResult {
+    ok: true;
+    archivedAt: string;
+}
+export declare function archiveRaw(ctx: Context, id: string, reason: string, opts?: ArchiveRawOpts): ArchiveRawResult;
+//# sourceMappingURL=promote.d.ts.map