@jungjaehoon/mama-core 4.1.0 → 5.0.0

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,11 +70,6 @@ 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: {
@@ -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)