@jungjaehoon/mama-core 2.4.1 → 4.1.0

package/dist/memory/api.d.ts

@@ -1,21 +1,44 @@
-import { type WikiPageIndexRecord } from '../cases/wiki-page-index.js';
+import type { DatabaseAdapter } from '../db-manager.js';
+import type { TextCompletion } from '../runtime/text-completion.js';
+import type { SearchQualityOptions } from '../knowledge/search-quality.js';
+import type { DecisionRecord } from '../db-manager.js';
+import type { DatabaseInstance } from '../db-manager.js';
 import { resolveMemoryEvolution } from './evolution-engine.js';
 import { getChannelSummary, upsertChannelSummary } from './channel-summary-store.js';
-import { type SearchHitDiagnostics } from '../search/search-quality.js';
-import type { MemoryAgentBootstrap, MemoryAuditAck, MemoryEdge, MemoryRecord, MemoryScopeRef, MemoryStatus, ProfileSnapshot, PublicIngestMemoryInput, PublicSaveMemoryInput, RecallBundle, IngestConversationInput, ExtractedMemoryUnit, IngestConversationResult, RecallMemoryOptions } from './types.js';
-import { type TrustedMemoryWriteOptions } from './provenance.js';
+import { type SearchHitDiagnostics } from '../knowledge/search-quality.js';
+import type { MemoryKind, MemoryKindFilter, MemoryAgentBootstrap, MemoryAuditAck, MemoryEdge, MemoryRecord, MemoryScopeRef, MemoryStatus, ProfileSnapshot, PublicIngestMemoryInput, PublicSaveMemoryInput, RecallBundle, IngestConversationInput, IngestConversationResult, RecallMemoryOptions } from './types.js';
+import { type JudgmentAccess } from '../knowledge/judgments.js';
+import type { ActionSessionFacts } from '../action-contracts.js';
 type SaveMemoryInput = PublicSaveMemoryInput;
 type IngestMemoryInput = PublicIngestMemoryInput;
+export interface LegacyMemoryPersistence {
+    userInvolvement?: string | null;
+    outcome?: string | null;
+    failureReason?: string | null;
+    limitation?: string | null;
+    isStatic?: number;
+    relationships?: Array<{
+        type: string;
+        targetIds: string[];
+    }>;
+}
 export interface FusedHit {
-    source_type: 'decision' | 'wiki_page';
+    source_type: 'decision';
     source_id: string;
-    record: MemoryRecord | WikiPageIndexRecord;
+    record: MemoryRecord;
     fused_rank_score: number;
-    page_type?: WikiPageIndexRecord['page_type'];
     case_id?: string | null;
     retrieval_diagnostics?: SearchHitDiagnostics;
 }
 export declare function buildDecisionId(topic: string): string;
+export interface ReadMemoryRecordsOptions {
+    kind?: MemoryKindFilter;
+    status?: MemoryStatus | readonly MemoryStatus[];
+}
+/** Read complete memory records whose stored scopes intersect the admitted scopes. */
+export declare function readMemoryRecordsInScopes(adapter: DatabaseInstance, scopes: readonly MemoryScopeRef[], options?: ReadMemoryRecordsOptions): Promise<MemoryRecord[]>;
+/** Read one complete record only when at least one stored scope is admitted. */
+export declare function readMemoryRecordById(adapter: DatabaseInstance, memoryId: string, scopes: readonly MemoryScopeRef[]): Promise<MemoryRecord | null>;
 export declare const LEXICAL_STOPWORDS: Set<string>;
 export declare function getLexicalQueryTokens(query: string): string[];
 /**
@@ -26,40 +49,64 @@ export declare function getLexicalQueryTokens(query: string): string[];
  * top-5 for 42.5% of chains - present in the candidate pool, buried by rank).
  */
 export declare function topicAffinityBoost(topic: string, tokens: string[], normalizedQuery: string): number;
-export declare function loadEdgesForIds(ids: string[]): Promise<MemoryEdge[]>;
+export declare function loadEdgesForIds(adapter: DatabaseInstance, ids: string[]): Promise<MemoryEdge[]>;
 type SaveMemoryResult = {
     success: boolean;
     id: string;
     saved_decision_id?: string;
-    timeline_event_id?: string | null;
-    timeline_event_ids?: string[];
 };
-export declare function saveMemory(input: SaveMemoryInput): Promise<SaveMemoryResult>;
-export declare function saveMemoryWithTrustedProvenance(input: SaveMemoryInput, options: TrustedMemoryWriteOptions): Promise<SaveMemoryResult>;
-export declare function promoteMemoryStatus(input: {
+export declare function saveMemory(adapter: DatabaseInstance, input: SaveMemoryInput): Promise<SaveMemoryResult>;
+/**
+ * The unified `memory.save` action path. Access IS the call authority — the
+ * command's scopes are checked against it inside `appendJudgment`, and the
+ * record's provenance is composed from it plus the session facts the host
+ * attests (never from caller input). `commandId` is the caller's operationId,
+ * so a retried call replays the original receipt.
+ */
+export declare function saveJudgmentRecord(adapter: DatabaseInstance, input: SaveMemoryInput, access: JudgmentAccess, commandId: string, session?: ActionSessionFacts): Promise<SaveMemoryResult>;
+/**
+ * The read-side scope rule for memory actions — the same bound `appendJudgment`
+ * applies to writes. An omitted request reads under the full admitted scopes;
+ * an explicit request must be a subset of them. An empty admitted set admits an
+ * empty corpus: a caller with no scopes can see no scoped record (reads never
+ * fall back to an unbounded scan — the legacy `scopes: []` = read-all behavior
+ * is exactly what this bound removes).
+ */
+export declare function boundReadScopesFor(access: JudgmentAccess, requested?: MemoryScopeRef[]): MemoryScopeRef[];
+export declare function saveLegacyMemory(adapter: DatabaseInstance, input: SaveMemoryInput, legacy: LegacyMemoryPersistence, access?: JudgmentAccess): Promise<SaveMemoryResult>;
+export declare function promoteMemoryStatus(adapter: DatabaseInstance, input: {
     memoryId: string;
     status: MemoryStatus;
     nowMs?: number;
 }): Promise<void>;
-export declare function buildProfile(scopes: MemoryScopeRef[]): Promise<ProfileSnapshot>;
-export declare function recallMemory(query: string, options?: RecallMemoryOptions): Promise<RecallBundle>;
-export declare function ingestMemory(input: IngestMemoryInput): Promise<{
-    success: boolean;
+export type MemoryRetirementStatus = Extract<MemoryStatus, 'stale' | 'superseded'>;
+/** Append an access-checked status amendment for one stored memory record. */
+export declare function retireMemoryRecord(adapter: DatabaseInstance, input: {
+    memoryId: string;
+    status: MemoryRetirementStatus;
+    reason: string;
+}, access: JudgmentAccess, commandId: string): Promise<{
+    success: true;
     id: string;
+    status: MemoryRetirementStatus;
+    reason: string;
+    receiptId: string;
 }>;
-export declare function ingestWithTrustedProvenance(input: IngestMemoryInput, options: TrustedMemoryWriteOptions): Promise<{
+export declare function buildProfile(adapter: DatabaseInstance, scopes: MemoryScopeRef[]): Promise<ProfileSnapshot>;
+export declare function recallMemory(adapter: DatabaseInstance, query: string, options?: RecallMemoryOptions): Promise<RecallBundle>;
+export declare function ingestMemory(adapter: DatabaseInstance, input: IngestMemoryInput): Promise<{
     success: boolean;
     id: string;
 }>;
 export declare function evolveMemory(input: Parameters<typeof resolveMemoryEvolution>[0]): Promise<import("./evolution-engine.js").EvolutionResult>;
-export declare function buildMemoryBootstrap(params: {
+export declare function buildMemoryBootstrap(adapter: DatabaseInstance, params: {
     scopes: MemoryScopeRef[];
     channelKey?: string;
     currentGoal?: string;
     mainAgentState?: MemoryAgentBootstrap['main_agent_state'];
 }): Promise<MemoryAgentBootstrap>;
 export declare function createAuditAck(input: MemoryAuditAck): MemoryAuditAck;
-export declare function recordMemoryAudit(input: {
+export declare function recordMemoryAudit(adapter: DatabaseInstance, input: {
     channelKey: string;
     turnId: string;
     topic: string;
@@ -75,9 +122,202 @@ export declare function recordMemoryAudit(input: {
     findingIds: string[];
     state: import("./types.js").ChannelSummaryStateRecord;
 }>;
-declare function callExtractionLLM(prompt: string, options: NonNullable<IngestConversationInput['extract']>): Promise<ExtractedMemoryUnit[]>;
-export declare function setExtractionFn(fn: typeof callExtractionLLM | null): void;
-export declare function ingestConversation(input: IngestConversationInput): Promise<IngestConversationResult>;
-export declare function ingestConversationWithTrustedProvenance(input: IngestConversationInput, options: TrustedMemoryWriteOptions): Promise<IngestConversationResult>;
+export declare function ingestConversation(adapter: DatabaseInstance, input: IngestConversationInput): Promise<IngestConversationResult>;
 export { upsertChannelSummary, getChannelSummary };
+/**
+ * Expand search results with graph context (Phase 1 - Graph-Enhanced Retrieval)
+ *
+ * For each candidate decision:
+ * 1. Add supersedes chain (evolution history)
+ * 2. Add semantic edges (refines, contradicts)
+ * 3. Deduplicate by ID
+ * 4. Re-rank by relevance (primary candidates ranked higher)
+ *
+ * @param {Array} candidates - Initial search results from vector/keyword search
+ * @returns {Promise<Array>} Graph-enhanced results with evolution context
+ */
+export interface SearchCandidate {
+    id: string;
+    topic: string;
+    decision: string;
+    reasoning?: string | null;
+    confidence?: number;
+    similarity?: number;
+    created_at?: number | string;
+    graph_source?: string;
+    graph_rank?: number;
+    related_to?: string | null;
+    edge_reason?: string | null;
+    recency_score?: number;
+    recency_age_days?: number;
+    final_score?: number;
+    outcome?: string | null;
+    failure_reason?: string | null;
+    is_static?: number;
+}
+export declare function expandWithGraphInAdapter(adapter: DatabaseAdapter, candidates: SearchCandidate[]): Promise<SearchCandidate[]>;
+/**
+ * Suggest relevant decisions based on user question
+ *
+ * DEFAULT: Returns JSON object with search results (LLM-first design)
+ * OPTIONAL: Returns Markdown string if format='markdown' (for human display)
+ *
+ * Simplified: Direct vector search without LLM intent analysis
+ * Works with short queries, long questions, Korean/English
+ *
+ * @param {string} userQuestion - User's question or intent
+ * @param {Object} options - Search options
+ * @param {string} [options.format='json'] - Output format: 'json' (default) or 'markdown'
+ * @param {number} [options.limit=5] - Max results to return
+ * @param {number} [options.threshold=0.6] - Minimum similarity (adaptive by query length)
+ * @param {boolean} [options.useReranking=false] - Use LLM re-ranking (optional, slower)
+ * @returns {Promise<Object|string|null>} Search results as JSON or Markdown, null if no results
+ *
+ * @example
+ * // LLM usage (default)
+ * const data = await mama.suggest('Why did we choose JWT?');
+ * // → { query, results: [...], meta: {...} }
+ *
+ * // Human display
+ * const markdown = await mama.suggest('mesh optimization', { format: 'markdown' });
+ * // → "💡 MAMA found 3 related topics:\n1. ..."
+ */
+export interface SuggestFunctionOptions extends SearchQualityOptions {
+    format?: 'json' | 'markdown';
+    limit?: number;
+    kind?: MemoryKind;
+    useReranking?: boolean;
+    /** Phase 3 Task 33: apply learned offline ranker rescoring. */
+    rerankWithLearned?: boolean;
+    recencyWeight?: number;
+    recencyScale?: number;
+    recencyDecay?: number;
+    scopes?: Array<{
+        kind: string;
+        id: string;
+    }>;
+    /**
+     * The model this runtime opened, when `useReranking` asks for one. This
+     * module used to open its own (a local Ollama endpoint), which decided for
+     * every host installing the library; the host states it now (§2.1).
+     */
+    runner?: TextCompletion;
+}
+export declare function suggestInAdapter(adapter: DatabaseInstance, userQuestion: string, options?: SuggestFunctionOptions): Promise<any>;
+/**
+ * List recent decisions (all topics, chronological)
+ *
+ * DEFAULT: Returns JSON array with recent decisions (LLM-first design)
+ * OPTIONAL: Returns Markdown string if format='markdown' (for human display)
+ *
+ * @param {Object} [options] - Options
+ * @param {number} [options.limit=10] - Max results
+ * @param {string} [options.format='json'] - Output format
+ * @returns {Promise<Array|string>} Recent decisions
+ */
+export interface ListDecisionsOptions {
+    limit?: number;
+    format?: 'json' | 'markdown';
+    kind?: MemoryKind;
+    scopes?: Array<{
+        kind: string;
+        id: string;
+    }>;
+    /**
+     * Exact ledger read: every decision whose topic starts with this string, superseded rows
+     * included (they are the earlier rounds of the same item). `%` and `_` are literal.
+     * This is a lookup, not a search - `suggest({topicPrefix})` treats the prefix as a soft
+     * signal and was measured returning 5 of 12 rows plus one from another item.
+     */
+    topicPrefix?: string;
+}
+export declare function listDecisionsInAdapter(adapter: DatabaseAdapter, options?: ListDecisionsOptions): Promise<DecisionRecord[] | string>;
+/**
+ * Update outcome of a decision
+ *
+ * Track whether a decision succeeded, failed, or partially worked
+ * AC: Evolutionary Decision Memory - Learn from outcomes
+ *
+ * @param {string} decisionId - Decision ID to update
+ * @param {Object} outcome - Outcome details
+ * @param {string} outcome.outcome - 'SUCCESS', 'FAILED', or 'PARTIAL'
+ * @param {string} [outcome.failure_reason] - Reason for failure (if FAILED)
+ * @param {string} [outcome.limitation] - Limitation description (if PARTIAL)
+ * @returns {Promise<void>}
+ *
+ * @example
+ * await mama.updateOutcome('decision_auth_strategy_123456_abc', {
+ *   outcome: 'FAILED',
+ *   failure_reason: 'Missing token expiration handling'
+ * });
+ */
+export interface UpdateOutcomeParams {
+    outcome: string;
+    failure_reason?: string | null;
+    limitation?: string | null;
+}
+export declare function updateOutcomeInAdapter(adapter: DatabaseInstance, decisionId: string, { outcome, failure_reason, limitation }: UpdateOutcomeParams): Promise<void>;
+/**
+ * List recent checkpoints (New Feature: Session Continuity)
+ *
+ * @param {number} limit - Max number of checkpoints to return
+ * @returns {Promise<Array>} Recent checkpoints
+ */
+/** What a stats read answers: counts over the memory a caller may see. */
+export interface MemoryStatsResult {
+    total: number;
+    thisWeek: number;
+    thisMonth: number;
+    checkpoints: number;
+    outcomes: Record<string, number>;
+    topTopics: Array<{
+        topic: string;
+        count: number;
+    }>;
+}
+/**
+ * Counts over the admitted corpus.
+ *
+ * Every count answers the same question the scope filter answers for a listing:
+ * a decision this caller may not read is not a decision it may count. An
+ * admitted-empty caller counts zero rather than counting everything — the same
+ * fail-closed reading the listing gives.
+ */
+export declare function readMemoryStatsInAdapter(adapter: DatabaseAdapter, scopes: readonly {
+    kind: string;
+    id: string;
+}[]): Promise<MemoryStatsResult>;
+/**
+ * Load latest active checkpoint (New Feature: Session Continuity)
+ *
+ * @returns {Promise<Object|null>} Latest checkpoint or null
+ */
+interface ConversationMessage {
+    role: string;
+    content: string | Array<{
+        type: string;
+        text?: string;
+        [key: string]: unknown;
+    }>;
+}
+/**
+ * Save current session checkpoint (New Feature: Session Continuity)
+ *
+ * @param {string} summary - Summary of current session state
+ * @param {Array<string>} openFiles - List of currently open files
+ * @param {string} nextSteps - Next steps to be taken
+ * @returns {Promise<number>} Checkpoint ID
+ */
+export declare function saveCheckpointInAdapter(adapter: DatabaseAdapter, summary: string, openFiles?: string[], nextSteps?: string, recentConversation?: any[]): Promise<number | bigint>;
+export interface CheckpointRow {
+    id?: number;
+    timestamp?: number;
+    summary?: string;
+    open_files?: string | string[];
+    next_steps?: string;
+    recent_conversation?: string | ConversationMessage[];
+    status?: string;
+}
+export declare function loadCheckpointInAdapter(adapter: DatabaseAdapter): Promise<CheckpointRow | null>;
+export declare function listCheckpointsInAdapter(adapter: DatabaseAdapter, limit?: number): Promise<CheckpointRow[]>;
 //# sourceMappingURL=api.d.ts.map