hippo-memory 1.60.0 → 1.61.0

package/dist/mcp/format.js

@@ -0,0 +1,135 @@
+// Text the MCP recall and context tools print, and what each printed piece costs the token budget.
+import { confidenceLabel } from '../memory.js';
+import { formatHandoffEvidenceLine } from '../handoff.js';
+import { printedTokens } from '../context-render.js';
+import { estimateTokens } from '../token-ledger.js';
+// ── Format helpers ──
+function handoffLines(h) {
+    const lines = [`- Summary: ${h.summary}`];
+    if (h.nextAction)
+        lines.push(`- Next action: ${h.nextAction}`);
+    if ((h.artifacts ?? []).length > 0)
+        lines.push(`- Artifacts: ${(h.artifacts ?? []).join(', ')}`);
+    if (h.outcome)
+        lines.push(`- Outcome: ${h.outcome}`);
+    if (h.targetRuntime)
+        lines.push(`- Target runtime: ${h.targetRuntime}`);
+    if (h.cardId)
+        lines.push(`- Card: ${h.cardId}`);
+    if ((h.constraints ?? []).length > 0)
+        lines.push(`- Constraints: ${(h.constraints ?? []).join(', ')}`);
+    if (h.evidence)
+        lines.push(`- Evidence: ${formatHandoffEvidenceLine(h.evidence)}`);
+    return lines;
+}
+function trailLines(events) {
+    return events.map((e) => {
+        const preview = e.content.length > 200 ? e.content.slice(0, 200) + '…' : e.content;
+        return `- [${e.event_type}] ${preview}`;
+    });
+}
+export function formatContinuityBlock(block) {
+    const lines = ['## Continuity'];
+    if (block.activeSnapshot) {
+        lines.push('');
+        lines.push('### Active Task Snapshot');
+        lines.push(`- Task: ${block.activeSnapshot.task}`);
+        lines.push(`- Summary: ${block.activeSnapshot.summary}`);
+        lines.push(`- Next: ${block.activeSnapshot.next_step}`);
+    }
+    if (block.sessionHandoff) {
+        lines.push('');
+        lines.push('### Session Handoff');
+        lines.push(...handoffLines(block.sessionHandoff));
+    }
+    if (block.recentSessionEvents.length > 0) {
+        lines.push('');
+        lines.push('### Recent Session Trail');
+        lines.push(...trailLines(block.recentSessionEvents));
+    }
+    if (lines.length === 1) {
+        lines.push('');
+        lines.push('(no active task snapshot, handoff, or recent events for this tenant)');
+    }
+    return lines.join('\n');
+}
+const NO_MEMORIES = 'No relevant memories found.';
+function memoriesHeading(count) {
+    return `Found ${count} memories:\n`;
+}
+function formatMemory(r) {
+    const conf = confidenceLabel(r.entry).text;
+    const tags = r.entry.tags.length > 0 ? ` tags: ${r.entry.tags.join(', ')}` : '';
+    return `[${conf}]${tags} (strength=${r.entry.strength.toFixed(2)})\n${r.entry.content}\n`;
+}
+export function formatMemories(results) {
+    if (results.length === 0)
+        return NO_MEMORIES;
+    return [memoriesHeading(results.length), ...results.map(formatMemory)].join('\n');
+}
+/** What a memory costs the budget: the text formatMemories prints for it. */
+export const memoryCost = (r) => printedTokens(formatMemory(r));
+// The widest heading or the empty-list line, whichever costs more, so either prints inside the budget.
+export function memoriesReserve(budget) {
+    return Math.max(printedTokens(memoriesHeading(budget)), estimateTokens(NO_MEMORIES));
+}
+export function snapshotPiece(s) {
+    return [
+        '## Active Task Snapshot',
+        `- Task: ${s.task}`,
+        `- Status: ${s.status}`,
+        `- Updated: ${s.updated_at}`,
+        '',
+        '### Summary',
+        s.summary,
+        '',
+        '### Next step',
+        s.next_step,
+        '',
+        '',
+    ].join('\n');
+}
+export function handoffPiece(h) {
+    return ['## Session Handoff', ...handoffLines(h), '', ''].join('\n');
+}
+export function trailPiece(events) {
+    return ['## Recent Session Trail', ...trailLines(events), '', ''].join('\n');
+}
+// Sections print ahead of the memories in hippo_context, so getContext pays for each as printed before any memory.
+export const contextCost = {
+    entry: memoryCost,
+    fixed: (budget) => memoriesReserve(budget),
+    snapshot: (s) => estimateTokens(snapshotPiece(s)),
+    handoff: (h) => estimateTokens(handoffPiece(h)),
+    trail: (events) => estimateTokens(trailPiece(events)),
+};
+// Rows the ranked list already shows drop out of this section, so pricing every row bounds what it prints.
+export function tailSection(rows) {
+    if (rows.length === 0)
+        return '';
+    const lines = ['', '## Fresh tail / substituted summaries'];
+    for (const r of rows) {
+        const tag = r.isSummary ? '[summary]' : '[tail]';
+        const head = r.content.length > 200 ? r.content.slice(0, 200) + '…' : r.content;
+        if (r.isSummary && r.substitutedFor && r.substitutedFor.length > 0) {
+            lines.push(`- ${tag} ${r.id} (covers ${r.substitutedFor.length} rows): ${head}`);
+        }
+        else {
+            lines.push(`- ${tag} ${r.id}: ${head}`);
+        }
+    }
+    return '\n' + lines.join('\n');
+}
+// J3.2: the hint depends on the query alone, so api.retrieve's copy is the one shown; JSON.stringify fences the phrase.
+export function planningSection(r) {
+    if (r.planningFallacyHint) {
+        const h = r.planningFallacyHint;
+        return `## Planning fallacy hint\nClass: ${h.classTag}\n${h.baserateSummary}\n(detected: ${JSON.stringify(h.detectedPhrase)})\n\n---\n\n`;
+    }
+    if (r.planningFallacyWatching) {
+        const w = r.planningFallacyWatching;
+        return `## Planning fallacy watch\nReason: ${w.reason}\n${w.suggestion}\n(detected: ${JSON.stringify(w.detectedPhrase)})\n\n---\n\n`;
+    }
+    return '';
+}
+//# sourceMappingURL=format.js.map

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

@@ -0,0 +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 runLearnTool({ args, ctx, hippoRoot, tenantId }: ToolCall): string;
+//# sourceMappingURL=memory-tools.d.ts.map

package/dist/mcp/memory-tools.js

@@ -0,0 +1,83 @@
+// Write-side tool handlers: hippo_remember, hippo_outcome and hippo_learn.
+import { log } from '../log.js';
+import { readEntry } from '../store/entry-reads.js';
+import { countCreatedSinceLastSleep } from '../store/index-and-stats.js';
+import { consolidate } from '../consolidate/sleep.js';
+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 }) {
+    const text = String(args.text || '');
+    if (!text)
+        return 'No text provided.';
+    const tags = [];
+    if (args.error)
+        tags.push('error');
+    if (args.tag)
+        tags.push(String(args.tag));
+    // Route through api.ts so audit_log captures the caller identity
+    // uniformly with CLI/REST: the auth-resolved ctx.actor under HTTP-MCP,
+    // 'mcp' for stdio (no ctx). api.ts.remember writes the memory + audit
+    // row in one transaction-friendly path; we re-read the entry to surface
+    // the half-life used in the MCP human-readable response.
+    const apiCtx = {
+        hippoRoot,
+        tenantId,
+        actor: mcpActor(ctx),
+    };
+    const result = apiRemember(apiCtx, {
+        content: text,
+        tags,
+    });
+    const entry = readEntry(hippoRoot, 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 (config.autoSleep.enabled &&
+        tenantId === resolveTenantId({}) &&
+        !autoSleepInFlight.has(hippoRoot) &&
+        countCreatedSinceLastSleep(hippoRoot, tenantId) >= config.autoSleep.threshold) {
+        autoSleepInFlight.add(hippoRoot);
+        // Fire-and-forget (never block the response); an unhandled rejection would kill the server, so log it.
+        consolidate(hippoRoot)
+            .catch((err) => {
+            log.error(`auto-sleep consolidate failed (tenant ${tenantId}): ${err instanceof Error ? err.message : String(err)}`);
+        })
+            .finally(() => autoSleepInFlight.delete(hippoRoot));
+    }
+    const halfLife = entry?.half_life_days ?? config.defaultHalfLifeDays;
+    const tagStr = entry?.tags.join(', ') || tags.join(', ') || 'none';
+    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 }) {
+    const good = Boolean(args.good);
+    const clientKey = resolveClientKey(ctx);
+    const ids = lastRecalledIds.get(clientKey) ?? [];
+    if (ids.length === 0)
+        return 'No recent recalls to apply outcome to.';
+    // Route through src/api.ts so audit_log captures the caller identity
+    // (auth-resolved ctx.actor under HTTP-MCP, 'mcp' for stdio) and tenant
+    // scoping is enforced uniformly (same surface as recall/remember).
+    // outcome() also handles cross-tenant id skip silently.
+    const apiCtx = {
+        hippoRoot,
+        tenantId,
+        actor: mcpActor(ctx),
+    };
+    const { applied } = apiOutcome(apiCtx, ids, good);
+    return `Applied ${good ? 'positive' : 'negative'} outcome to ${applied} memories`;
+}
+export function runLearnTool({ args, ctx, hippoRoot, tenantId }) {
+    const days = Number(args.days) || 7;
+    const result = apiLearn({ hippoRoot, tenantId, actor: mcpActor(ctx) }, { repoPath: process.cwd(), days, profile: MCP_LEARN });
+    if (result.status === 'not-a-repo')
+        return 'No git history found.';
+    if (result.status === 'no-commits')
+        return 'No fix/revert/bug commits found in the specified period.';
+    const { added, skipped, rejected, lowInfo } = result;
+    const rejectedSuffix = rejected > 0 ? `, ${rejected} rejected values skipped` : '';
+    const lowInfoSuffix = lowInfo > 0 ? `, ${lowInfo} low-information subjects dropped` : '';
+    return `Git learn: ${added} new, ${skipped} duplicates skipped${rejectedSuffix}${lowInfoSuffix} (scanned ${days} days)`;
+}
+//# sourceMappingURL=memory-tools.js.map

package/dist/mcp/protocol.d.ts

@@ -0,0 +1,83 @@
+import { loadConfig } from '../config.js';
+import type { Actor as ApiActor } from '../api.js';
+import { type ResolveProjectIdentityOpts } from '../project-identity.js';
+/** Same bounded walk as the CLI (ends at home, so HIPPO_HOME wins over ~/.hippo); cwd/opts are the test seam. */
+export declare function findHippoRoot(cwd?: string, opts?: ResolveProjectIdentityOpts): string | null;
+interface McpRequest {
+    jsonrpc: '2.0';
+    id: number | string;
+    method: string;
+    params?: Record<string, JsonValue>;
+}
+interface McpResponse {
+    jsonrpc: '2.0';
+    id: number | string | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: {
+            requestId: string;
+        };
+    };
+}
+/** JSON-RPC reply for a request that threw: typed API errors keep their text; anything else is logged and answered generically. */
+export declare function mcpErrorResponse<E>(id: McpResponse['id'], err: E, requestId?: string): McpResponse;
+export type { McpRequest, McpResponse };
+/**
+ * Optional execution context threaded from a non-stdio transport. When the
+ * HTTP transport in src/server.ts calls handleMcpRequest, it knows the
+ * server's bound hippoRoot and the auth-resolved tenantId/actor. Passing
+ * those through here lets executeTool skip the findHippoRoot() walk and
+ * the env-based resolveTenantId({}) fallback — both of which would
+ * otherwise produce the wrong store and the wrong tenant for HTTP callers.
+ *
+ * Stdio callers pass nothing; behavior stays unchanged for that path.
+ */
+export interface McpContext {
+    hippoRoot: string;
+    tenantId: string;
+    actor: string;
+    /**
+     * The caller's role from the HTTP transport's auth. Absent for stdio, which
+     * is the local operator and runs as admin. Tools must use this rather than
+     * assuming admin, or a member key over HTTP-MCP would act as admin.
+     */
+    role?: 'admin' | 'member';
+    /** EI2: scope grants for the HTTP-MCP caller's key. Absent for stdio (admin, needs none). */
+    scopes?: readonly string[];
+    viaAuthResolver?: true;
+    /** Set by the HTTP transport for the host's operator; a context without a role is in-process and implies it. */
+    hostAdmin?: true;
+    /**
+     * Per-client key for state isolation under HTTP-MCP. For stdio: 'stdio-${pid}'
+     * (one process = one client). For HTTP-SSE / HTTP MCP: hash(bearer + remoteAddr)
+     * built by src/server.ts when constructing McpContext for the request.
+     * Optional for backwards compatibility; defaults to `${tenantId}:default`.
+     */
+    clientKey?: string;
+}
+/**
+ * The api-layer actor for a tool call. Stdio (no ctx) is the local operator
+ * and runs as admin; over HTTP the transport's authenticated role is used, so
+ * a member key never acts as admin through MCP.
+ */
+export declare function mcpActor(ctx: McpContext | undefined): ApiActor;
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare function isJsonString(v: JsonValue | undefined): v is string;
+export declare function isJsonBoolean(v: JsonValue | undefined): v is boolean;
+export declare function isJsonObjectRecord(v: JsonValue | undefined): v is {
+    [key: string]: JsonValue;
+};
+/** One tool call after the store, config and tenant are resolved; every handler reads the same four. */
+export interface ToolCall {
+    args: Record<string, JsonValue>;
+    ctx?: McpContext;
+    hippoRoot: string;
+    config: ReturnType<typeof loadConfig>;
+    tenantId: string;
+}
+export type ToolHandler = (call: ToolCall) => string | Promise<string>;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/mcp/protocol.js

@@ -0,0 +1,55 @@
+// MCP wire types, the caller context, and the JSON predicates every tool handler narrows its arguments with.
+import * as fs from 'fs';
+import { randomUUID } from 'node:crypto';
+import { INTERNAL_ERROR_MESSAGE, mapApiError } from '../http-util.js';
+import { log } from '../log.js';
+import { getGlobalRoot } from '../shared.js';
+import { findHippoStoreDir } from '../project-identity.js';
+import { isSqliteBusy, STORE_BUSY_MESSAGE } from '../db.js';
+// ── Find hippo root ──
+/** Same bounded walk as the CLI (ends at home, so HIPPO_HOME wins over ~/.hippo); cwd/opts are the test seam. */
+export function findHippoRoot(cwd = process.cwd(), opts) {
+    const local = findHippoStoreDir(cwd, opts);
+    if (local !== null)
+        return local;
+    // Global fallback (respects $HIPPO_HOME / $XDG_DATA_HOME)
+    const global = getGlobalRoot();
+    return fs.existsSync(global) ? global : null;
+}
+/** JSON-RPC reply for a request that threw: typed API errors keep their text; anything else is logged and answered generically. */
+export function mcpErrorResponse(id, err, requestId = randomUUID()) {
+    if (isSqliteBusy(err))
+        return { jsonrpc: '2.0', id, error: { code: -32603, message: STORE_BUSY_MESSAGE } };
+    const { status, message } = mapApiError(err);
+    if (status !== 500)
+        return { jsonrpc: '2.0', id, error: { code: -32603, message } };
+    log.error(`mcp request failed: ${err instanceof Error ? err.message : String(err)}`, { requestId });
+    return {
+        jsonrpc: '2.0',
+        id,
+        error: { code: -32603, message: `${INTERNAL_ERROR_MESSAGE} (request id ${requestId})`, data: { requestId } },
+    };
+}
+/**
+ * The api-layer actor for a tool call. Stdio (no ctx) is the local operator
+ * and runs as admin; over HTTP the transport's authenticated role is used, so
+ * a member key never acts as admin through MCP.
+ */
+export function mcpActor(ctx) {
+    const actor = { subject: ctx?.actor ?? 'mcp', role: ctx?.role ?? 'admin', scopes: ctx?.scopes };
+    if (ctx?.viaAuthResolver)
+        actor.viaAuthResolver = true;
+    if (ctx?.role === undefined || ctx.hostAdmin)
+        actor.hostAdmin = true;
+    return actor;
+}
+export function isJsonString(v) {
+    return typeof v === 'string';
+}
+export function isJsonBoolean(v) {
+    return typeof v === 'boolean';
+}
+export function isJsonObjectRecord(v) {
+    return v !== undefined && v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+//# sourceMappingURL=protocol.js.map

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

@@ -0,0 +1,6 @@
+import { type ToolCall } from './protocol.js';
+export declare function runRecallTool(call: ToolCall): Promise<string>;
+export declare function runAssembleTool({ args, ctx, hippoRoot, tenantId }: ToolCall): string;
+export declare function runDrillTool({ args, ctx, hippoRoot, tenantId }: ToolCall): string;
+export declare function runContextTool({ args, ctx, hippoRoot, config, tenantId }: ToolCall): Promise<string>;
+//# sourceMappingURL=recall-tools.d.ts.map