@jungjaehoon/mama-core 4.1.1 → 5.1.0

package/dist/mama-api.d.ts

@@ -20,16 +20,16 @@
 import { type CheckpointRow, type ListDecisionsOptions, type SearchCandidate, type SuggestFunctionOptions, type UpdateOutcomeParams } from './memory/api.js';
 import { DecisionRecord, type DatabaseInstance } from './db-manager.js';
 import { SemanticEdges } from './decision-formatter.js';
-import { saveMemory as saveMemoryInAdapter, recallMemory as recallMemoryInAdapter, buildProfile as buildProfileInAdapter, ingestMemory as ingestMemoryInAdapter, ingestConversation as ingestConversationInAdapter, evolveMemory, buildMemoryBootstrap as buildMemoryBootstrapInAdapter, createAuditAck, recordMemoryAudit as recordMemoryAuditInAdapter, upsertChannelSummary as upsertChannelSummaryInAdapter, getChannelSummary as getChannelSummaryInAdapter } from './memory/api.js';
+import { saveMemory as saveMemoryInAdapter, recallMemory as recallMemoryInAdapter, buildProfile as buildProfileInAdapter, ingestMemory as ingestMemoryInAdapter, ingestConversation as ingestConversationInAdapter, buildMemoryBootstrap as buildMemoryBootstrapInAdapter, createAuditAck, recordMemoryAudit as recordMemoryAuditInAdapter, upsertChannelSummary as upsertChannelSummaryInAdapter, getChannelSummary as getChannelSummaryInAdapter } from './memory/api.js';
 import { createAuditFinding as createAuditFindingInAdapter, listOpenAuditFindings as listOpenAuditFindingsInAdapter } from './memory/finding-store.js';
 import { listMemoryEventsForMemory as listMemoryEventsForMemoryInAdapter, listRecentMemoryEvents as listRecentMemoryEventsInAdapter } from './memory/event-store.js';
 import { getMemoryProvenance as getMemoryProvenanceInAdapter, listMemoriesByEnvelopeHash as listMemoriesByEnvelopeHashInAdapter, listMemoriesByGatewayCallId as listMemoriesByGatewayCallIdInAdapter, listMemoriesByModelRunId as listMemoriesByModelRunIdInAdapter } from './memory/provenance-query.js';
 import { beginModelRun as beginModelRunInAdapter, commitModelRun as commitModelRunInAdapter, failModelRun as failModelRunInAdapter, getModelRun as getModelRunInAdapter, listModelRunNativeInputs as listModelRunNativeInputsInAdapter } from './runtime/model-run-store.js';
 import { appendToolTrace as appendToolTraceInAdapter, listToolTracesForRun as listToolTracesForRunInAdapter, listToolTraces as listToolTracesInAdapter, readToolTrace as readToolTraceInAdapter } from './runtime/tool-trace-store.js';
 import { type SearchHitDiagnostics } from './knowledge/search-quality.js';
-/**
- * Parameters for mama.save()
- */
+import type { RecordLink } from './memory/judgment-types.js';
+import { type DecisionLinkInput, type DecisionWithEdges } from './memory/decision-links.js';
+import type { LinkReceipt } from './knowledge/links.js';
 interface SaveParams {
     topic: string;
     decision: string;
@@ -52,6 +52,17 @@ interface SaveParams {
     }>;
     /** ISO 8601 date string for when the event actually occurred (e.g. "2023-01-15") */
     event_date?: string | null;
+    /** Decisions this one relates to, each with the relation and the reason the caller judged. */
+    links?: Array<{
+        id: string;
+        relation: RecordLink['relation'];
+        reason: string;
+    }>;
+    /** Decisions this one replaces, each with the reason. */
+    replaces?: Array<{
+        id: string;
+        reason: string;
+    }>;
 }
 /**
  * Similar decision result from search
@@ -294,6 +305,10 @@ declare function suggest(userQuestion: string, options?: SuggestFunctionOptions)
 declare function recall(topic: string, options?: RecallOptions): Promise<string | RecallGraphResult>;
 declare function expandWithGraph(candidates: SearchCandidate[]): Promise<SearchCandidate[]>;
 declare function updateOutcome(decisionId: string, outcome: UpdateOutcomeParams): Promise<void>;
+/** Link one decision to another, or correct a link, with the reason the caller judged. */
+declare function link(input: DecisionLinkInput): Promise<LinkReceipt>;
+/** One decision with every edge in and out, each with its reason and who wrote it. */
+declare function getDecision(id: string): Promise<DecisionWithEdges | null>;
 declare function listDecisions(options?: ListDecisionsOptions): Promise<DecisionRecord[] | string>;
 declare function saveCheckpoint(summary: string, openFiles?: string[], nextSteps?: string, recentConversation?: any[]): Promise<number | bigint>;
 declare function loadCheckpoint(): Promise<CheckpointRow | null>;
@@ -368,7 +383,6 @@ export declare function createMamaApi(adapter: DatabaseInstance): {
         id: string;
     }>;
     ingestConversation: (input: Parameters<typeof ingestConversationInAdapter>[1]) => Promise<import("./index.js").IngestConversationResult>;
-    evolveMemory: (input: Parameters<typeof evolveMemory>[0]) => Promise<import("./memory/evolution-engine.js").EvolutionResult>;
     buildMemoryBootstrap: (params: Parameters<typeof buildMemoryBootstrapInAdapter>[1]) => Promise<import("./memory/types.js").MemoryAgentBootstrap>;
     createAuditAck: (input: Parameters<typeof createAuditAck>[0]) => import("./memory/types.js").MemoryAuditAck;
     recordMemoryAudit: (input: Parameters<typeof recordMemoryAuditInAdapter>[1]) => Promise<{
@@ -408,6 +422,8 @@ export declare function createMamaApi(adapter: DatabaseInstance): {
 export type MamaApi = ReturnType<typeof createMamaApi>;
 declare const mama: {
     save: typeof save;
+    link: typeof link;
+    getDecision: typeof getDecision;
     suggest: typeof suggest;
     saveMemory: typeof saveMemory;
     recallMemory: typeof recallMemory;
@@ -417,7 +433,6 @@ declare const mama: {
     buildProfile: typeof buildProfile;
     ingestMemory: typeof ingestMemory;
     ingestConversation: typeof ingestConversation;
-    evolveMemory: typeof evolveMemory;
     buildMemoryBootstrap: typeof buildMemoryBootstrap;
     createAuditAck: typeof createAuditAck;
     recordMemoryAudit: typeof recordMemoryAudit;
@@ -445,6 +460,6 @@ declare const mama: {
     recall: typeof recall;
     expandWithGraph: typeof expandWithGraph;
 };
-export { save, suggest, saveMemory, recallMemory, listDecisions as list, listCheckpoints, updateOutcome, buildProfile, ingestMemory, ingestConversation, evolveMemory, buildMemoryBootstrap, createAuditAck, recordMemoryAudit, upsertChannelSummary, getChannelSummary, listOpenAuditFindings, createAuditFinding, getMemoryProvenance, listMemoriesByEnvelopeHash, listMemoriesByGatewayCallId, listMemoriesByModelRunId, listMemoryEventsForMemory, listRecentMemoryEvents, beginModelRun, commitModelRun, failModelRun, getModelRun, appendToolTrace, listToolTracesForRun, listToolTraces, readToolTrace, saveCheckpoint, loadCheckpoint, recall, expandWithGraph, };
+export { save, link, getDecision, suggest, saveMemory, recallMemory, listDecisions as list, listCheckpoints, updateOutcome, buildProfile, ingestMemory, ingestConversation, buildMemoryBootstrap, createAuditAck, recordMemoryAudit, upsertChannelSummary, getChannelSummary, listOpenAuditFindings, createAuditFinding, getMemoryProvenance, listMemoriesByEnvelopeHash, listMemoriesByGatewayCallId, listMemoriesByModelRunId, listMemoryEventsForMemory, listRecentMemoryEvents, beginModelRun, commitModelRun, failModelRun, getModelRun, appendToolTrace, listToolTracesForRun, listToolTraces, readToolTrace, saveCheckpoint, loadCheckpoint, recall, expandWithGraph, };
 export default mama;
 //# sourceMappingURL=mama-api.d.ts.map

package/dist/mama-api.js

@@ -19,9 +19,11 @@
  * @date 2025-11-26
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createAuditAck = exports.evolveMemory = void 0;
+exports.createAuditAck = void 0;
 exports.createMamaApi = createMamaApi;
 exports.save = save;
+exports.link = link;
+exports.getDecision = getDecision;
 exports.suggest = suggest;
 exports.saveMemory = saveMemory;
 exports.recallMemory = recallMemory;
@@ -63,13 +65,28 @@ const decision_formatter_js_1 = require("./decision-formatter.js");
 const progress_indicator_js_1 = require("./progress-indicator.js");
 const debug_logger_js_1 = require("./debug-logger.js");
 const api_js_2 = require("./memory/api.js");
-Object.defineProperty(exports, "evolveMemory", { enumerable: true, get: function () { return api_js_2.evolveMemory; } });
 Object.defineProperty(exports, "createAuditAck", { enumerable: true, get: function () { return api_js_2.createAuditAck; } });
 const finding_store_js_1 = require("./memory/finding-store.js");
 const event_store_js_1 = require("./memory/event-store.js");
 const provenance_query_js_1 = require("./memory/provenance-query.js");
 const model_run_store_js_1 = require("./runtime/model-run-store.js");
 const tool_trace_store_js_1 = require("./runtime/tool-trace-store.js");
+const decision_links_js_1 = require("./memory/decision-links.js");
+// ════════════════════════════════════════════════════════════════════════════
+// Type Definitions
+// ════════════════════════════════════════════════════════════════════════════
+/**
+ * Parameters for mama.save()
+ */
+/** Relations a save names; replacing is `replaces`, which also moves the replaced record's state. */
+const SAVE_LINK_RELATIONS = [
+    'builds_on',
+    'refines',
+    'contradicts',
+    'debates',
+    'synthesizes',
+    'mentions',
+];
 // Prevents spam by tracking warned topics per session
 /**
  * Save a decision or insight to MAMA's memory
@@ -98,7 +115,7 @@ const tool_trace_store_js_1 = require("./runtime/tool-trace-store.js");
  *   outcome: 'success'
  * });
  */
-async function saveInternal(adapter, { topic, decision, reasoning, confidence = 0.5, type = 'user_decision', outcome = 'pending', failure_reason = null, limitation = null, trust_context: _trust_context = null, is_static, scopes: inputScopes, item, actors, event_date, }) {
+async function saveInternal(adapter, { topic, decision, reasoning, confidence = 0.5, type = 'user_decision', outcome = 'pending', failure_reason = null, limitation = null, trust_context: _trust_context = null, is_static, scopes: inputScopes, item, actors, event_date, links, replaces, }) {
     // Validate required fields
     if (!topic || typeof topic !== 'string') {
         throw new Error('mama.save() requires topic (string)');
@@ -155,9 +172,8 @@ async function saveInternal(adapter, { topic, decision, reasoning, confidence =
         superseded: null,
     };
     const dbOutcome = outcome in outcomeMap ? outcomeMap[outcome] : outcome;
-    // Reasoning text is evidence, not authority: relationships are only written
-    // when the caller names explicit targets (saveLegacyMemory's legacy field or
-    // twin-edge links). Parsing IDs out of prose fabricated edges, so it is gone.
+    // Reasoning text is evidence, not authority: a relation is written only when the caller names
+    // its target and reason (`links`, `replaces`). Parsing ids out of prose fabricated edges.
     (0, progress_indicator_js_1.logProgress)(`Saving decision: ${topic.substring(0, 30)}...`);
     const { id: decisionId } = await (0, api_js_2.saveLegacyMemory)(adapter, {
         topic,
@@ -173,6 +189,33 @@ async function saveInternal(adapter, { topic, decision, reasoning, confidence =
         eventDate: event_date ?? undefined,
         itemId: item ?? undefined,
         actors: actors?.map((actor) => ({ personId: actor.person, role: actor.role })),
+        ...(links?.length
+            ? {
+                links: links.map((link) => {
+                    if (typeof link.reason !== 'string' || link.reason.trim() === '') {
+                        throw new Error('mama.save() each link needs a reason');
+                    }
+                    if (!SAVE_LINK_RELATIONS.includes(link.relation)) {
+                        throw new Error(`mama.save() link relation must be one of ${SAVE_LINK_RELATIONS.join(', ')}; a replaced decision goes in replaces`);
+                    }
+                    return {
+                        relation: link.relation,
+                        target: { kind: 'memory', id: link.id },
+                        attrs: { reason: link.reason.trim() },
+                    };
+                }),
+            }
+            : {}),
+        ...(replaces?.length
+            ? {
+                replaces: replaces.map((replacement) => {
+                    if (typeof replacement.reason !== 'string' || replacement.reason.trim() === '') {
+                        throw new Error('mama.save() each replaced decision needs a reason');
+                    }
+                    return { id: replacement.id, reason: replacement.reason.trim() };
+                }),
+            }
+            : {}),
     }, {
         userInvolvement: _userInvolvement,
         outcome: dbOutcome,
@@ -271,11 +314,7 @@ function _generateCollaborationHint(similarDecisions) {
     if (count === 0) {
         return null;
     }
-    return `Found ${count} related decision(s). Consider:
-- SUPERSEDE: Add "supersedes: <id>" in reasoning to replace a specific prior decision
-- BUILD-ON: Add "builds_on: <id>" in reasoning to extend
-- DEBATE: Add "debates: <id>" in reasoning for alternative view
-- SYNTHESIZE: Add "synthesizes: [id1, id2]" in reasoning to unify`;
+    return `Found ${count} related decision(s). If the new decision replaces, extends, debates or combines one of them, link it with the reason you judged: replaces [{id, reason}] or links [{id, relation, reason}] when saving, or a link afterwards. Nothing is linked for you.`;
 }
 /**
  * Get reasoning graph info for a topic
@@ -456,6 +495,16 @@ async function updateOutcome(decisionId, outcome) {
     await (0, db_manager_js_1.initDB)();
     return (0, api_js_1.updateOutcomeInAdapter)((0, db_manager_js_1.getAdapter)(), decisionId, outcome);
 }
+/** Link one decision to another, or correct a link, with the reason the caller judged. */
+async function link(input) {
+    await (0, db_manager_js_1.initDB)();
+    return (0, decision_links_js_1.appendDecisionLink)((0, db_manager_js_1.getAdapter)(), input);
+}
+/** One decision with every edge in and out, each with its reason and who wrote it. */
+async function getDecision(id) {
+    await (0, db_manager_js_1.initDB)();
+    return (0, decision_links_js_1.readDecisionWithEdges)((0, db_manager_js_1.getAdapter)(), id);
+}
 async function listDecisions(options = {}) {
     await (0, db_manager_js_1.initDB)();
     return (0, api_js_1.listDecisionsInAdapter)((0, db_manager_js_1.getAdapter)(), options);
@@ -627,7 +676,6 @@ function createMamaApi(adapter) {
         buildProfile: (scopes) => (0, api_js_2.buildProfile)(adapter, scopes),
         ingestMemory: (input) => (0, api_js_2.ingestMemory)(adapter, input),
         ingestConversation: (input) => (0, api_js_2.ingestConversation)(adapter, input),
-        evolveMemory: (input) => (0, api_js_2.evolveMemory)(input),
         buildMemoryBootstrap: (params) => (0, api_js_2.buildMemoryBootstrap)(adapter, params),
         createAuditAck: (input) => (0, api_js_2.createAuditAck)(input),
         recordMemoryAudit: (input) => (0, api_js_2.recordMemoryAudit)(adapter, input),
@@ -660,8 +708,10 @@ function createMamaApi(adapter) {
     };
 }
 const mama = {
-    // Core functions (used by 4 MCP tools)
+    // Core functions (used by the MCP tools)
     save,
+    link,
+    getDecision,
     suggest,
     saveMemory,
     recallMemory,
@@ -671,7 +721,6 @@ const mama = {
     buildProfile,
     ingestMemory,
     ingestConversation,
-    evolveMemory: api_js_2.evolveMemory,
     buildMemoryBootstrap,
     createAuditAck: api_js_2.createAuditAck,
     recordMemoryAudit,
@@ -706,7 +755,7 @@ exports.default = mama;
 // ambient `mama` facade methods at top level. Merge instead of replacing
 // module.exports: the compiled `exports.X = X` named exports (suggestInAdapter,
 // saveCheckpointInAdapter, ...) are how api/catalog.ts reaches them from dist.
-// Getter-only named exports (evolveMemory, createAuditAck) keep their getter —
+// Getter-only named exports (createAuditAck) keep their getter —
 // it already returns the same function the facade carries.
 if (typeof module !== 'undefined' && module.exports) {
     const target = module.exports;

package/dist/memory/api.d.ts

@@ -1,9 +1,9 @@
 import type { DatabaseAdapter } from '../db-manager.js';
 import type { TextCompletion } from '../runtime/text-completion.js';
+import { type DecisionCorrection } from './decision-links.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 '../knowledge/search-quality.js';
 import type { MemoryKind, MemoryKindFilter, MemoryAgentBootstrap, MemoryAuditAck, MemoryEdge, MemoryRecord, MemoryScopeRef, MemoryStatus, ProfileSnapshot, PublicIngestMemoryInput, PublicSaveMemoryInput, RecallBundle, IngestConversationInput, IngestConversationResult, RecallMemoryOptions } from './types.js';
@@ -17,10 +17,6 @@ export interface LegacyMemoryPersistence {
     failureReason?: string | null;
     limitation?: string | null;
     isStatic?: number;
-    relationships?: Array<{
-        type: string;
-        targetIds: string[];
-    }>;
 }
 export interface FusedHit {
     source_type: 'decision';
@@ -74,18 +70,13 @@ export declare function saveJudgmentRecord(adapter: DatabaseInstance, input: Sav
  */
 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 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<{
+}, access: JudgmentAccess, commandId: string, session?: ActionSessionFacts): Promise<{
     success: true;
     id: string;
     status: MemoryRetirementStatus;
@@ -98,7 +89,6 @@ export declare function ingestMemory(adapter: DatabaseInstance, input: IngestMem
     success: boolean;
     id: string;
 }>;
-export declare function evolveMemory(input: Parameters<typeof resolveMemoryEvolution>[0]): Promise<import("./evolution-engine.js").EvolutionResult>;
 export declare function buildMemoryBootstrap(adapter: DatabaseInstance, params: {
     scopes: MemoryScopeRef[];
     channelKey?: string;
@@ -148,6 +138,8 @@ export interface SearchCandidate {
     graph_rank?: number;
     related_to?: string | null;
     edge_reason?: string | null;
+    /** Later links that contradict the link this record was reached through. */
+    edge_corrected_by?: DecisionCorrection[];
     recency_score?: number;
     recency_age_days?: number;
     final_score?: number;
@@ -203,6 +195,19 @@ export interface SuggestFunctionOptions extends SearchQualityOptions {
      */
     runner?: TextCompletion;
 }
+/** One stated link from or to a search hit: a pointer the reader opens. */
+export interface SearchHitLink {
+    id: string;
+    topic: string;
+    /** The record's first line. */
+    summary: string;
+    /** Present when the record is no longer active, e.g. `superseded`. */
+    status?: string;
+    /** Seen from the hit: `builds_on` out, `built_on_by` in, and so on. */
+    relation: string;
+    reason: string | null;
+    corrected_by?: DecisionCorrection[];
+}
 export declare function suggestInAdapter(adapter: DatabaseInstance, userQuestion: string, options?: SuggestFunctionOptions): Promise<any>;
 /**
  * List recent decisions (all topics, chronological)